Imager::APIRef - Imager's C API - reference.
i_color color; color.rgba.r = 255; color.rgba.g = 0; color.rgba.b = 255; # Blit tools # Data Types i_img *img; i_color black; black.rgba.r = black.rgba.g = black.rgba.b = black.rgba.a = 0; i_fill_t *fill; i_img_dim x, y; printf("left %" i_DF "\n", i_DFc(x)); printf("point (" i_DFp ")\n", i_DFcp(x, y)); # Drawing i_arc(im, 50, 50, 20, 45, 135, &color); i_arc_cfill(im, 50, 50, 35, 90, 135, fill); i_arc_aa(im, 50, 50, 35, 90, 135, &color); i_arc_aa_cfill(im, 50, 50, 35, 90, 135, fill); i_circle_aa(im, 50, 50, 45, &color); i_box(im, 0, 0, im->xsize-1, im->ysize-1, &color). i_box_filled(im, 0, 0, im->xsize-1, im->ysize-1, &color); i_box_cfill(im, 0, 0, im->xsize-1, im->ysize-1, fill); i_flood_fill(im, 50, 50, &color); i_flood_cfill(im, 50, 50, fill); i_flood_fill_border(im, 50, 50, &color, &border); i_flood_cfill_border(im, 50, 50, fill, border); # Error handling i_clear_error(); i_push_error(0, "Yep, it's broken"); i_push_error(errno, "Error writing"); i_push_errorf(errno, "Cannot open file %s: %d", filename, errno); # Files i_set_image_file_limits(500, 500, 1000000); i_get_image_file_limits(&width, &height, &bytes) i_i_int_check_image_file_limits(width, height, channels, sizeof(i_sample_t)) # Fills i_fill_t *fill = i_new_fill_solidf(&fcolor, combine); i_fill_t *fill = i_new_fill_solid(&color, combine); i_fill_t *fill = i_new_fill_hatch(&fg_color, &bg_color, combine, hatch, custom_hatch, dx, dy); i_fill_t *fill = i_new_fill_hatchf(&fg_fcolor, &bg_fcolor, combine, hatch, custom_hatch, dx, dy); i_fill_t *fill = i_new_fill_image(src_img, matrix, x_offset, y_offset, combine); fill = i_new_fill_fount(0, 0, 100, 100, i_ft_linear, i_ft_linear, i_fr_triangle, 0, i_fts_grid, 9, 1, segs); i_fill_destroy(fill); # I/O Layers ssize_t count = i_io_peekn(ig, buffer, sizeof(buffer)); ssize_t result = i_io_write(io, buffer, size) char buffer[BUFSIZ] ssize_t len = i_io_gets(buffer, sizeof(buffer), '\n'); io_glue_destroy(ig); # Image # Image creation/destruction i_img *img = i_sametype(src, width, height); i_img *img = i_sametype_chans(src, width, height, channels); i_img *img = i_img_16_new(width, height, channels); i_img *img = i_img_8_new(width, height, channels); i_img *img = i_img_double_new(width, height, channels); i_img *img = i_img_pal_new(width, height, channels, max_palette_size) i_img_destroy(img) # Image Implementation # Image Information // only channel 0 writable i_img_setmask(img, 0x01); int mask = i_img_getmask(img); int channels = i_img_getchannels(img); i_img_dim width = i_img_get_width(im); i_img_dim height = i_img_get_height(im); # Image quantization # Logging # Paletted images # Tags i_tags_set(&img->tags, "i_comment", -1); i_tags_setn(&img->tags, "i_xres", 204); i_tags_setn(&img->tags, "i_yres", 196);
Render the given color with the coverage specified by source[0] to source[width-1].
source[0]
source[width-1]
Renders in normal combine mode.
Release an i_render object.
i_render
Render the given fill with the coverage in source[0] through source[width-1].
Allocate a new i_render object and initialize it.
i_img *img;
This is Imager's image type.
It contains the following members:
channels - the number of channels in the image
channels
xsize, ysize - the width and height of the image in pixels
xsize
ysize
bytes - the number of bytes used to store the image data. Undefined where virtual is non-zero.
bytes
ch_mask - a mask of writable channels. eg. if this is 6 then only channels 1 and 2 are writable. There may be bits set for which there are no channels in the image.
ch_mask
bits - the number of bits stored per sample. Should be one of i_8_bits, i_16_bits, i_double_bits.
bits
type - either i_direct_type for direct color images, or i_palette_type for paletted images.
type
virtual - if zero then this image is-self contained. If non-zero then this image could be an interface to some other implementation.
virtual
idata - the image data. This should not be directly accessed. A new image implementation can use this to store its image data. i_img_destroy() will myfree() this pointer if it's non-null.
idata
tags - a structure storing the image's tags. This should only be accessed via the i_tags_*() functions.
tags
ext_data - a pointer for use internal to an image implementation. This should be freed by the image's destroy handler.
ext_data
im_data - data internal to Imager. This is initialized by i_img_init().
im_data
i_f_ppix, i_f_ppixf, i_f_plin, i_f_plinf, i_f_gpix, i_f_gpixf, i_f_glin, i_f_glinf, i_f_gsamp, i_f_gampf - implementations for each of the required image functions. An image implementation should initialize these between calling i_img_alloc() and i_img_init().
i_f_gpal, i_f_ppal, i_f_addcolors, i_f_getcolors, i_f_colorcount, i_f_maxcolors, i_f_findcolor, i_f_setcolors - implementations for each paletted image function.
i_f_destroy - custom image destruction function. This should be used to release memory if necessary.
i_f_gsamp_bits - implements i_gsamp_bits() for this image.
i_f_psamp_bits - implements i_psamp_bits() for this image.
i_color black; black.rgba.r = black.rgba.g = black.rgba.b = black.rgba.a = 0;
Type for 8-bit/sample color.
Samples as per;
i_color c;
i_color is a union of:
gray - contains a single element gray_color, eg. c.gray.gray_color
c.gray.gray_color
rgb - contains three elements r, g, b, eg. c.rgb.r
rgb
r
g
b
c.rgb.r
rgba - contains four elements r, g, b, a, eg. c.rgba.a
rgba
a
c.rgba.a
cmyk - contains four elements c, m, y, k, eg. c.cmyk.y. Note that Imager never uses CMYK colors except when reading/writing files.
cmyk
c
m
y
k
c.cmyk.y
channels - an array of four channels, eg c.channels[2].
c.channels[2]
This is the double/sample color type.
Its layout exactly corresponds to i_color.
i_fill_t *fill;
This is the "abstract" base type for Imager's fill types.
Unless you're implementing a new fill type you'll typically treat this as an opaque type.
i_img_dim x, y;
A signed integer type that represents an image dimension or ordinate.
May be larger than int on some platforms.
printf("left %" i_DF "\n", i_DFc(x));
This is a constant string that can be used with functions like printf() to format i_img_dim values after they're been cast with i_DFc().
Does not include the leading %.
%
Cast an i_img_dim value to a type for use with the i_DF format string.
i_img_dim
Casts two i_img_dim values for use with the i_DF (or i_DFp) format.
printf("point (" i_DFp ")\n", i_DFcp(x, y));
Format a pair of i_img_dim values. This format string does include the leading %.
i_arc(im, 50, 50, 20, 45, 135, &color);
Fills an arc centered at (x,y) with radius rad covering the range of angles in degrees from d1 to d2, with the color.
i_arc_aa(im, 50, 50, 35, 90, 135, &color);
Anti-alias fills an arc centered at (x,y) with radius rad covering the range of angles in degrees from d1 to d2, with the color.
i_arc_aa_cfill(im, 50, 50, 35, 90, 135, fill);
Anti-alias fills an arc centered at (x,y) with radius rad covering the range of angles in degrees from d1 to d2, with the fill object.
i_arc_cfill(im, 50, 50, 35, 90, 135, fill);
Fills an arc centered at (x,y) with radius rad covering the range of angles in degrees from d1 to d2, with the fill object.
i_box(im, 0, 0, im->xsize-1, im->ysize-1, &color).
Outlines the box from (x1,y1) to (x2,y2) inclusive with color.
i_box_cfill(im, 0, 0, im->xsize-1, im->ysize-1, fill);
Fills the box from (x1,y1) to (x2,y2) inclusive with fill.
i_box_filled(im, 0, 0, im->xsize-1, im->ysize-1, &color);
Fills the box from (x1,y1) to (x2,y2) inclusive with color.
i_circle_aa(im, 50, 50, 45, &color);
Anti-alias fills a circle centered at (x,y) for radius rad with color.
im
seedx
seedy
fill
i_flood_cfill(im, 50, 50, fill);
Flood fills the 4-connected region starting from the point (seedx, seedy) with fill.
Returns false if (seedx, seedy) are outside the image.
border
i_flood_cfill_border(im, 50, 50, fill, border);
Flood fills the 4-connected region starting from the point (seedx, seedy) with fill, the fill stops when it reaches pixels of color border.
color
i_flood_fill(im, 50, 50, &color);
Flood fills the 4-connected region starting from the point (seedx, seedy) with color.
i_flood_fill_border(im, 50, 50, &color, &border);
Flood fills the 4-connected region starting from the point (seedx, seedy) with color, fill stops when the fill reaches a pixels with color border.
Retrieves (r-l) pixels starting from (l,y) into colors.
Returns the number of pixels retrieved.
Retrieves (r-l) pixels starting from (l,y) into colors as floating point colors.
Reads palette indexes for the horizontal line (left, y) to (right-1, y) into indexes.
indexes
Returns the number of indexes read.
Always returns 0 for direct color images.
x
Retrieves the color of the pixel (x,y).
Returns 0 if the pixel was retrieved, or -1 if not.
fcolor
Retrieves the color of the pixel (x,y) as a floating point color into fcolor.
Reads sample values from im for the horizontal line (left, y) to (right-1,y) for the channels specified by channels, an array of int with channel_count elements.
channel_count
If channels is NULL then the first channels_count channels are retrieved for each pixel.
Returns the number of samples read (which should be (right-left) * channel_count)
Like i_gsampf() but applies the source image color over a supplied background color.
i_gsampf()
This is intended for output to image formats that don't support alpha channels.
Reads floating point sample values from im for the horizontal line (left, y) to (right-1,y) for the channels specified by channels, an array of int with channel_count elements.
If channels is NULL then the first channel_count channels are retrieved for each pixel.
right
left
x1
y1
x2
y2
endp
Draw a line to image using Bresenham's line drawing algorithm
im - image to draw to x1 - starting x coordinate y1 - starting x coordinate x2 - starting x coordinate y2 - starting x coordinate color - color to write to image endp - endpoint flag (boolean)
Anti-alias draws a line from (x1,y1) to (x2, y2) in color.
The point (x2, y2) is drawn only if endp is set.
Sets (r-l) pixels starting from (l,y) using (r-l) values from colors.
Returns the number of pixels set.
fcolors
Sets (right-left) pixels starting from (left,y) using (right-left) floating point colors from fcolors.
Writes palette indexes for the horizontal line (left, y) to (right-1, y) from indexes.
Returns the number of indexes written.
Sets the pixel at (x,y) to color.
Returns 0 if the pixel was drawn, or -1 if not.
Does no alpha blending, just copies the channels from the supplied color to the image.
Sets the pixel at (x,y) to the floating point color fcolor.
i_clear_error();
Clears the error stack.
Called by any Imager function before doing any other processing.
i_push_error(0, "Yep, it's broken"); i_push_error(errno, "Error writing");
Called by an Imager function to push an error message onto the stack.
No message is pushed if the stack is full (since this means someone forgot to call i_clear_error(), or that a function that doesn't do error handling is calling function that does.).
i_push_errorf(errno, "Cannot open file %s: %d", filename, errno);
A version of i_push_error() that does printf() like formatting.
Does not support perl specific format codes.
code
fmt
ap
Intended for use by higher level functions, takes a varargs pointer and a format to produce the finally pushed error message.
Retrieve the file write background color tag from the image.
If not present, returns black.
Retrieve the file write background color tag from the image as a floating point color.
Implemented in terms of i_get_file_background().
i_get_image_file_limits(&width, &height, &bytes)
Retrieves the file limits set by i_set_image_file_limits().
i_img_dim *width, *height - the maximum width and height of the image.
size_t *bytes - size in memory of the image in bytes.
i_i_int_check_image_file_limits(width, height, channels, sizeof(i_sample_t))
Checks the size of a file in memory against the configured image file limits.
This also range checks the values to those permitted by Imager and checks for overflows in calculating the size.
Returns non-zero if the file is within limits.
This function is intended to be called by image file read functions.
i_set_image_file_limits(500, 500, 1000000);
Set limits on the sizes of images read by Imager.
Setting a limit to 0 means that limit is ignored.
Negative limits result in failure.
Parameters:
i_img_dim width, height - maximum width and height.
size_t bytes - maximum size in memory in bytes
Returns non-zero on success.
xa
ya
xb
yb
repeat
combine
super_sample
ssample_param
count
segs
fill = i_new_fill_fount(0, 0, 100, 100, i_ft_linear, i_ft_linear, i_fr_triangle, 0, i_fts_grid, 9, 1, segs);
Creates a new general fill which fills with a fountain fill.
fg
bg
hatch
cust_hatch
dx
dy
i_fill_t *fill = i_new_fill_hatch(&fg_color, &bg_color, combine, hatch, custom_hatch, dx, dy);
Creates a new hatched fill with the fg color used for the 1 bits in the hatch and bg for the 0 bits. If combine is non-zero alpha values will be combined.
If cust_hatch is non-NULL it should be a pointer to 8 bytes of the hash definition, with the high-bits to the left.
If cust_hatch is NULL then one of the standard hatches is used.
(dx, dy) are an offset into the hatch which can be used to hatch adjoining areas out of alignment, or to align the origin of a hatch with the the side of a filled area.
i_fill_t *fill = i_new_fill_hatchf(&fg_fcolor, &bg_fcolor, combine, hatch, custom_hatch, dx, dy);
matrix
xoff
yoff
i_fill_t *fill = i_new_fill_image(src_img, matrix, x_offset, y_offset, combine);
Create an image based fill.
matrix is an array of 9 doubles representing a transformation matrix.
xoff and yoff are the offset into the image to start filling from.
i_fill_t *fill = i_new_fill_solid(&color, combine);
Create a solid fill based on an 8-bit color.
If combine is non-zero then alpha values will be combined.
i_fill_t *fill = i_new_fill_solidf(&fcolor, combine);
Create a solid fill based on a float color.
i_fill_destroy(fill);
Call to destroy any fill object.
returns a new io_glue object that has the 'empty' source and but can be written to and read from later (like a pseudo file).
Returns a new io_glue object that has the source defined as reading from specified buffer. Note that the buffer is not copied.
data - buffer to read from length - length of buffer
Create a new I/O layer object that calls your supplied callbacks.
In general the callbacks should behave like the corresponding POSIX primitives.
read_cb(p, buffer, length) should read up to length bytes into buffer and return the number of bytes read. At end of file, return 0. On error, return -1.
read_cb
length
buffer
write_cb(p, buffer, length) should write up to length bytes from buffer and return the number of bytes written. A return value <= 0 will be treated as an error.
write_cb
seekcb(p, offset, whence) should seek and return the new offset.
seekcb
close_cb(p) should return 0 on success, -1 on failure.
close_cb
destroy_cb(p) should release any memory specific to your callback handlers.
destroy_cb
returns a new io_glue object that has the source defined as reading from specified file descriptor. Note that the the interface to receiving data from the io_glue callbacks hasn't been done yet.
fd - file descriptor to read/write from
Flush any pending output and perform the close action for the stream.
Returns 0 on success.
Flush any buffered output.
Returns true on success,
A macro to read a single byte from a buffered I/O glue object.
Returns EOF on failure, or a byte.
char buffer[BUFSIZ] ssize_t len = i_io_gets(buffer, sizeof(buffer), '\n');
Read up to size-1 bytes from the stream ig into buffer.
size
ig
If the byte end_of_line is seen then no further bytes will be read.
end_of_line
Returns the number of bytes read.
Always NUL terminates the buffer.
NUL
Read the next character from the stream without advancing the stream.
On error or end of file, return EOF.
For unbuffered streams a single character buffer will be setup.
ssize_t count = i_io_peekn(ig, buffer, sizeof(buffer));
Buffer at least size (at most ig->buf_size bytes of data from the stream and return size bytes of it to the caller in buffer.
ig->buf_size
This ignores the buffered state of the stream, and will always setup buffering if needed.
If no type parameter is provided to Imager::read() or Imager::read_multi(), Imager will call i_io_peekn() when probing for the file format.
i_io_peekn()
Returns -1 on error, 0 if there is no data before EOF, or the number of bytes read into buffer.
Write a single character to the stream.
On success return c, on error returns EOF
Read up to size bytes from the stream io into buffer.
io
Returns the number of bytes read. Returns 0 on end of file. Returns -1 on error.
Seek within the stream.
Acts like perl's seek.
Set the buffering mode of the stream.
If you switch buffering off on a stream with buffering on:
any buffered output will be flushed.
any existing buffered input will be consumed before reads become unbuffered.
Returns true on success. This may fail if any buffered output cannot be flushed.
ssize_t result = i_io_write(io, buffer, size)
Write to the given I/O stream.
Returns the number of bytes written.
Takes the source that the io_glue is bound to and allocates space for a return buffer and returns the entire content in a single buffer. Note: This only works for io_glue objects created by io_new_bufchain(). It is useful for saving to scalars and such.
ig - io_glue object c - pointer to a pointer to where data should be copied to char *data; size_t size = io_slurp(ig, &data); ... do something with the data ... myfree(data);
io_slurp() will abort the program if the supplied I/O layer is not from io_new_bufchain().
io_glue_destroy(ig);
Destroy an io_glue objects. Should clean up all related buffers.
ig - io_glue object to destroy.
Creates a new image that is a copy of the image source.
source
Tags are not copied, only the image data.
Returns: i_img *
dest
src
tx
ty
Copies image data from the area (x1,y1)-[x2,y2] in the source image to a rectangle the same size with it's top-left corner at (tx,ty) in the destination image.
If x1 > x2 or y1 > y2 then the corresponding co-ordinates are swapped.
trans
(x1,y1) (x2,y2) specifies the region to copy (in the source coordinates) (tx,ty) specifies the upper left corner for the target image. pass NULL in trans for non transparent i_colors.
Return image information
im - Image pointer info - pointer to array to return data
info is an array of 4 integers with the following values:
info[0] - width info[1] - height info[2] - channels info[3] - channel mask
src_minx
src_miny
src_maxx
src_maxy
Takes the sub image src[src_minx, src_maxx)[src_miny, src_maxy)> and overlays it at (tx,ty) on the image object.
The alpha channel of each pixel in src is used to control how much the existing color in im is replaced, if it is 255 then the color is completely replaced, if it is 0 then the original color is left unmodified.
i_img *img = i_img_16_new(width, height, channels);
Create a new 16-bit/sample image.
Returns the image on success, or NULL on failure.
i_img *img = i_img_8_new(width, height, channels);
Creates a new image object x pixels wide, and y pixels high with ch channels.
i_img *img = i_img_double_new(width, height, channels);
Creates a new double per sample image.
maxpal
i_img *img = i_img_pal_new(width, height, channels, max_palette_size)
Creates a new paletted image of the supplied dimensions.
maxpal is the maximum palette size and should normally be 256.
Returns a new image or NULL on failure.
i_img *img = i_sametype(src, width, height);
Returns an image of the same type (sample size, channels, paletted/direct).
For paletted images the palette is copied from the source.
i_img *img = i_sametype_chans(src, width, height, channels);
Returns an image of the same type (sample size).
For paletted images the equivalent direct type is returned.
img
i_img_destroy(img)
Destroy an image object
Allocates a new i_img structure.
When implementing a new image type perform the following steps in your image object creation function:
allocate the image with i_img_alloc().
initialize any function pointers or other data as needed, you can overwrite the whole block if you need to.
initialize Imager's internal data by calling i_img_init() on the image object.
Imager internal initialization of images.
Currently this does very little, in the future it may be used to support threads, or color profiles.
The number of channels holding color information.
i_img_dim height = i_img_get_height(im);
Returns the height in pixels of the image.
i_img_dim width = i_img_get_width(im);
Returns the width in pixels of the image.
int channels = i_img_getchannels(img);
Get the number of channels in im.
int mask = i_img_getmask(img);
Get the image channel mask for im.
Return true if the image has an alpha channel.
Tests an image to check it meets our monochrome tests.
The idea is that a file writer can use this to test where it should write the image in whatever bi-level format it uses, eg. pbm for pnm.
pbm
pnm
For performance of encoders we require monochrome images:
be paletted
have a palette of two colors, containing only (0,0,0) and (255,255,255) in either order.
(0,0,0)
(255,255,255)
zero_is_white is set to non-zero if the first palette entry is white.
zero_is_white
// only channel 0 writable i_img_setmask(img, 0x01);
Set the image channel mask for im to ch_mask.
The image channel mask gives some control over which channels can be written to in the image.
quant
imgs
Analyzes the count images in imgs according to the rules in quant to build a color map (optimal or not depending on quant->make_colors).
quant->make_colors
Quantize the image given the palette in quant.
On success returns a pointer to a memory block of img->xsize * img->ysize i_palidx entries.
img->xsize * img->ysize
i_palidx
On failure returns NULL.
You should call myfree() on the returned block when you're done with it.
This function will fail if the supplied palette contains no colors.
data
trans_index
Dither the alpha channel on img into the palette indexes in data. Pixels to be transparent are replaced with trans_pixel.
trans_pixel
The method used depends on the tr_* members of quant.
This is an internal function called by the mm_log() macro.
This is the main entry point to logging. Note that the extra set of parentheses are required due to limitations in C89 macros.
This will format a string with the current file and line number to the log file if logging is enabled.
Adds colors to the image's palette.
On success returns the index of the lowest color added.
On failure returns -1.
Always fails for direct color images.
Returns the number of colors in the image's palette.
Returns -1 for direct images.
Searches the images palette for the given color.
On success sets *entry to the index of the color, and returns true.
On failure returns false.
Always fails on direct color images.
Retrieves count colors starting from index in the image's palette.
On success stores the colors into colors and returns true.
Fails if there are less than index+count colors in the image's palette.
Returns the maximum number of colors the palette can hold for the image.
Returns -1 for direct color images.
Sets count colors starting from index in the image's palette.
On success returns true.
The image must have at least index+count colors in it's palette for this to succeed.
Delete any tags with the given code.
Returns the number of tags deleted.
Delete any tags with the given name.
Delete a tag by index.
Returns true on success.
Destroys the given tags structure. Called by i_img_destroy().
Searches for a tag of the given name starting from index start.
On success returns true and sets *entry.
Searches for a tag of the given code starting from index start.
Retrieve a tag specified by name or code as color.
On success sets the i_color *value to the color and returns true.
Retrieves a tag as a floating point value.
If the tag has a string value then that is parsed as a floating point number, otherwise the integer value of the tag is used.
On success sets *value and returns true.
Retrieve a tag specified by name or code as an integer.
On success sets the int *value to the integer and returns true.
Retrieves a tag by name or code as a string.
On success copies the string to value for a max of value_size and returns true.
value_size must be at least large enough for a string representation of an integer.
The copied value is always NUL terminated.
Initialize a tags structure. Should not be used if the tags structure has been previously used.
This should be called tags member of an i_img object on creation (in i_img_*_new() functions).
To destroy the contents use i_tags_destroy()
i_tags_set(&img->tags, "i_comment", -1);
Sets the given tag to the string data
If size is -1 then the strlen(data) bytes are stored.
Even on failure, if an existing tag name exists, it will be removed.
Stores the given color as a tag with the given name and code.
Equivalent to i_tags_set_float2(tags, name, code, value, 30).
Sets the tag with the given name and code to the given floating point value.
Since tags are strings or ints, we convert the value to a string before storage at the precision specified by places.
places
name
i_tags_setn(&img->tags, "i_xres", 204); i_tags_setn(&img->tags, "i_yres", 196);
Sets the given tag to the integer idata
Retrieve a UTF-8 character from the stream.
UTF-8
Modifies *p and *len to indicate the consumed characters.
This doesn't support the extended UTF-8 encoding used by later versions of Perl. Since this is typically used to implement text output by font drivers, the strings supplied shouldn't have such out of range characters.
This doesn't check that the UTF-8 character is using the shortest possible representation.
Returns ~0UL on failure.
Tony Cook <tonyc@cpan.org>
Imager, Imager::ExtUtils, Imager::Inline
To install Imager, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Imager
CPAN shell
perl -MCPAN -e shell install Imager
For more information on module installation, please visit the detailed CPAN module installation guide.