Imager::interface.pod - describes the C level virtual image interface



The Imager virtual interface aims to allow image types to be created for special purposes, both to allow consistent access to images with different sample sizes, and organizations, but also to allow creation of synthesized or virtual images.

This is a C level interface rather than Perl.

Existing Images

As of this writing we have the following concrete image types:

Currently there is only one virtual image type:

Other possible concrete images include:

Some other possible virtual images:


Each image type needs to define a number of functions which implement the image operations.

The image structure includes information describes the image, which can be used to determine the structure of the image:

If a caller has no knowledge of the internal format of an image, the caller must call the appropriate image function pointer. Imager provides macros that wrap these functions, so it isn't necessary to call them directly.

Many functions have a similar function with an 'f' suffix, these take or return samples specified with floating point values rather than 8-bit integers (unsigned char). Floating point samples are returned in the range 0 to 1 inclusive.


stores the specified color at pixel (x,y) in the image. If the pixel can be stored return 0, otherwise -1. An image type may choose to return 0 under some circumstances, eg. writing to a masked area of an image. The color or fcolor always contains the actual samples to be written, rather than a palette index.


stores (r-l) pixels at positions (l,y) ... (r-1, y) from the array specified by colors (or fcolors). Returns the number of pixels written to. If l is negative it will return 0. If r > im->xsize then only (im->xsize - l) will be written.


retrieves a single pixel from position (x,y). This returns the samples rather than the index for paletted images.


retrieves (r-l) pixels from positions (l, y) through (r-1, y) into the array specified by colors. Returns the number of pixels retrieved. If l < 0 no pixels are retrieved. If r > im->xsize then pixels (l, y) ... (im->xsize-1, y) are retrieved. Retrieves the samples rather than the color indexes for paletted images.


Retrieves samples from channels specified by chans (for length chan_count) from pixels at positions (l,y) ... (r-1, y). If chans is NULL then samples from channels 0 ... chan_count-1 will be retrieved. Returns the number of sample retrieved (not the number of channels). If a channel in chans is not present in the image or l < 0, returns 0. If r > im->xsize, then the samples from (l,y) ... (im->xsize-1, y) are returned.

The following are for images where type == i_palette_type only.


Retrieves color indexes from the image for pixels (l, y) ... (r-1, y) into vals. Returns the number of indexes retrieved.


Stores color indexes into the image for pixels (l, y) ... (r-1, y) from vals. Returns the number of indexes retrieved. If indexes are outside the range of the images palette, then you may have problems reading those pixels with i_gpix() or i_glin().


Adds the count colors to the image's palette. Returns the index of the first color added, or -1 if there is not enough space for count colors.


Retrieves count colors from the image's palette starting from entry index in the palette. Returns non-zero on success.


Returns the number of colors in the image's palette. Returns -1 if this is not a paletted image.


Returns the maximum number of colors that can fit in the image's palette. Returns -1 if this is not a paletted image.


Searches the image's palette for the specified color, setting *entry to the index and returning non-zero. Returns zero if the color is not found.


Sets count colors starting from index in the image from the array colors. The colors to be set must already have entries in the image's palette. Returns non-zero on success.

Finally, the i_f_destroy function pointer can be set which is called when the image is destroyed. This can be used to release memory pointed to by ext_data or release any other resources.

When writing to a paletted image with i_ppix() or i_plin() and the color you are writing doesn't exist in the image, then it's possible that the image will be internally converted to a direct image with the same number of channels.


Several functions have been written to simplify creating new image types.

These tools are available by including imagei.h.

Floating point wrappers

These functions implement the floating point sample versions of each interface function in terms of the integer sample version.

These are:


Forwarding functions

These functions are used in virtual images where the call should simply be forwarded to the underlying image. The underlying image is assumed to be the first pointer in a structure pointed at by ext_data.

If this is not the case then these functions will just crash :)


Sample macros

Imagei.h defines several macros for converting samples between different sizes.

Each macro is of the form SamplesizeTosize where size is one of 8, 16, or F (for floating-point samples).