NAME

Imager::APIRef - Imager's C API - reference.

SYNOPSIS

i_color color;
color.rgba.r = 255; color.rgba.g = 0; color.rgba.b = 255;


# 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;

# 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);

# Image

# Image creation/destruction
i_img *img = i_img_8_new(width, height, channels);
i_img *img = i_sametype(src, width, height);
i_img *img = i_sametype_chans(src, width, height, channels);
i_img *img = i_img_pal_new(width, height, channels, max_palette_size)
i_img *img = i_img_double_new(width, height, channels);
i_img *img = i_img_16_new(width, height, channels);
i_img_destroy(img)

# Image Implementation

# Image Information
// only channel 0 writeable 
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);

DESCRIPTION

Data Types

i_img

This is Imager's image type.

It contains the following members:

channels - the number of channels in the image
xsize, ysize - the width and height of the image in pixels
bytes - the number of bytes used to store the image data. Undefined where virtual is non-zero.
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.
bits - the number of bits stored per sample. Should be one of i_8_bits, i_16_bits, i_double_bits.
type - either i_direct_type for direct color images, or i_palette_type for paletted images.
virtual - if zero then this image is-self contained. If non-zero then this image could be an interface to some other implementation.
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.
tags - a structure storing the image's tags. This should only be accessed via the i_tags_*() functions.
ext_data - a pointer for use internal to an image implementation. This should be freed by the image's destroy handler.
im_data - data internal to Imager. This is initialized by i_img_init().
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

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
rgb - contains three elements r, g, b, eg. c.rgb.r
rgba - contains four elements r, g, b, a, eg. 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.
channels - an array of four channels, eg c.channels[2].

i_fcolor

This is the double/sample color type.

Its layout exactly corresponds to i_color.

i_fill_t

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

A signed integer type that represents an image dimension or ordinate.

May be larger than int on some platforms.

Drawing

i_arc(im, x, y, rad, d1, d2, 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, x, y, rad, d1, d2, 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, x, y, rad, d1, d2, 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, x, y, rad, d1, d2, 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, x1, y1, x2, y2, color)

Outlines the box from (x1,y1) to (x2,y2) inclusive with color.

i_box_cfill(im, x1, y1, x2, y2, fill)

Fills the box from (x1,y1) to (x2,y2) inclusive with fill.

i_box_filled(im, x1, y1, x2, y2, color)

Fills the box from (x1,y1) to (x2,y2) inclusive with color.

i_circle_aa(im, x, y, rad, color)

Anti-alias fills a circle centered at (x,y) for radius rad with color.

i_flood_cfill(im, seedx, seedy, fill)

Flood fills the 4-connected region starting from the point (seedx, seedy) with fill.

Returns false if (seedx, seedy) are outside the image.

i_flood_cfill_border(im, seedx, seedy, 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.

Returns false if (seedx, seedy) are outside the image.

i_flood_fill(im, seedx, seedy, color)

Flood fills the 4-connected region starting from the point (seedx, seedy) with color.

Returns false if (seedx, seedy) are outside the image.

i_flood_fill_border(im, seedx, seedy, 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.

Returns false if (seedx, seedy) are outside the image.

i_glin(im, l, r, y, colors)

Retrieves (r-l) pixels starting from (l,y) into colors.

Returns the number of pixels retrieved.

i_glinf(im, l, r, y, colors)

Retrieves (r-l) pixels starting from (l,y) into colors as floating point colors.

Returns the number of pixels retrieved.

i_gpal(im, left, right, y, indexes)

Reads palette indexes for the horizontal line (left, y) to (right-1, y) into indexes.

Returns the number of indexes read.

Always returns 0 for direct color images.

i_gpix(im, x, y, color)

Retrieves the color of the pixel (x,y).

Returns 0 if the pixel was retrieved, or -1 if not.

i_gpixf(im, x, y, fcolor)

Retrieves the color of the pixel (x,y) as a floating point color into fcolor.

Returns 0 if the pixel was retrieved, or -1 if not.

i_gsamp(im, left, right, y, samples, channels, channel_count)

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.

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)

i_gsampf(im, left, right, y, samples, channels, channel_count)

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.

Returns the number of samples read (which should be (right-left) * channel_count)

i_line(im, x1, y1, x2, y2, color, 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)

i_line_aa(im, x1, x2, y1, y2, color, endp)

Anti-alias draws a line from (x1,y1) to (x2, y2) in color.

The point (x2, y2) is drawn only if endp is set.

i_plin(im, l, r, y, colors)

Sets (r-l) pixels starting from (l,y) using (r-l) values from colors.

Returns the number of pixels set.

i_plinf(im, left, right, fcolors)

Sets (right-left) pixels starting from (left,y) using (right-left) floating point colors from fcolors.

Returns the number of pixels set.

i_ppal(im, left, right, y, indexes)

Writes palette indexes for the horizontal line (left, y) to (right-1, y) from indexes.

Returns the number of indexes written.

Always returns 0 for direct color images.

i_ppix(im, x, y, color)

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.

i_ppixf(im, x, y, fcolor)

Sets the pixel at (x,y) to the floating point color fcolor.

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.

Error handling

i_clear_error()

Clears the error stack.

Called by any Imager function before doing any other processing.

i_push_error(int code, char const *msg)

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(int code, char const *fmt, ...)

A version of i_push_error() that does printf() like formatting.

Does not support perl specific format codes.

i_push_errorvf(int code, char const *fmt, va_list ap)

Intended for use by higher level functions, takes a varargs pointer and a format to produce the finally pushed error message.

Does not support perl specific format codes.

Files

i_get_image_file_limits(&width, &height, &bytes)

Retrieves the file limits set by i_set_image_file_limits().

i_int_check_image_file_limits(width, height, channels, sample_size)

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(width, height, bytes)

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.

Returns non-zero on success.

Fills

i_new_fill_fount(xa, ya, xb, yb, type, repeat, combine, super_sample, ssample_param, count, segs)

Creates a new general fill which fills with a fountain fill.

i_new_fill_hatch(fg, bg, combine, hatch, cust_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_new_fill_hatchf(fg, bg, combine, hatch, cust_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_new_fill_image(im, matrix, xoff, yoff, 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_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_new_fill_solidf(color, combine)

Create a solid fill based on a float color.

If combine is non-zero then alpha values will be combined.

i_fill_destroy(fill)

Call to destroy any fill object.

Image

i_copy(source)

Creates a new image that is a copy of the image source.

Tags are not copied, only the image data.

Returns: i_img *

i_copyto(dest, src, x1, y1, x2, y2, 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.

i_copyto_trans(im, src, x1, y1, x2, y2, tx, ty, 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.

i_img_info(im, info)

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

i_rubthru(im, src, tx, ty, 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.

Image creation/destruction

i_img_16_new(x, y, ch)

Create a new 16-bit/sample image.

Returns the image on success, or NULL on failure.

i_img_8_new(x, y, ch)

Creates a new image object x pixels wide, and y pixels high with ch channels.

i_img_double_new(int x, int y, int ch)

Creates a new double per sample image.

i_img_pal_new(x, y, channels, maxpal)

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_sametype(im, xsize, ysize)

Returns an image of the same type (sample size, channels, paletted/direct).

For paletted images the palette is copied from the source.

i_sametype_chans(im, xsize, ysize, channels)

Returns an image of the same type (sample size).

For paletted images the equivalent direct type is returned.

i_img_destroy(img)

Destroy an image object

Image Implementation

i_img_alloc()

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.

i_img_init(img)

Imager internal initialization of images.

Currently this does very little, in the future it may be used to support threads, or color profiles.

Image Information

i_img_color_channels(im)

The number of channels holding color information.

i_img_get_height(im)

Returns the height in pixels of the image.

i_img_get_width(im)

Returns the width in pixels of the image.

i_img_getchannels(im)

Get the number of channels in im.

i_img_getmask(im)

Get the image channel mask for im.

i_img_has_alpha(im)

Return true if the image has an alpha channel.

i_img_setmask(im, ch_mask)

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.

Image quantization

i_quant_makemap(quant, imgs, count)

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).

i_quant_translate(quant, img)

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.

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.

i_quant_transparent(quant, data, img, trans_index)

Dither the alpha channel on img into the palette indexes in data. Pixels to be transparent are replaced with trans_pixel.

The method used depends on the tr_* members of quant.

Logging

i_lhead(file, line)

This is an internal function called by the mm_log() macro.

i_loog(level, format, ...)

This is an internal function called by the mm_log() macro.

mm_log((level, format, ...))

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.

Paletted images

i_addcolors(im, colors, count)

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.

i_colorcount(im)

Returns the number of colors in the image's palette.

Returns -1 for direct images.

i_findcolor(im, color, &entry)

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.

i_getcolors(im, index, colors, count)

Retrieves count colors starting from index in the image's palette.

On success stores the colors into colors and returns true.

On failure returns false.

Always fails for direct color images.

Fails if there are less than index+count colors in the image's palette.

i_maxcolors(im)

Returns the maximum number of colors the palette can hold for the image.

Returns -1 for direct color images.

i_setcolors(im, index, colors, count)

Sets count colors starting from index in the image's palette.

On success returns true.

On failure returns false.

The image must have at least index+count colors in it's palette for this to succeed.

Always fails on direct color images.

AUTHOR

Tony Cook <tony@imager.perl.org>

	Global
`s`	Focus search bar
`?`	Bring up this help dialog

	GitHub
`g` `p`	Go to pull requests
`g` `i`	go to github issues (only if github is preferred repository)

	POD
`g` `a`	Go to author
`g` `c`	Go to changes
`g` `i`	Go to issues
`g` `d`	Go to dist
`g` `r`	Go to repository/SCM
`g` `s`	Go to source
`g` `b`	Go to file browse

	Search terms
module: (e.g. module:Plugin)
distribution: (e.g. distribution:Dancer auth)
author: (e.g. author:SONGMU Redis)
version: (e.g. version:1.00)

NAME

SYNOPSIS

DESCRIPTION

Data Types

Drawing

Error handling

Files

Fills

Image

Image creation/destruction

Image Implementation

Image Information

Image quantization

Logging

Paletted images

Tags

AUTHOR

SEE ALSO

Module Install Instructions