/ 
Imager-1.024_002
River stage three • 112 direct dependents • 130 total dependents
/ Imager::interface.pod

NAME

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

SYNOPSIS

DESCRIPTION

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 gamma image types:

  • 8-bit/sample direct images

  • 16-bit/sample direct images

  • float/sample direct images.

  • double/sample direct images

  • 8-bit/sample 8-bit/index paletted images

and the following linear sample image types:

  • 16-bit/sample direct images

  • float/sample direct images.

  • double/sample direct images

There will not be a 8-bit/linear sample image, since 8-bits won't represent low levels precisely enough.

Currently there is only one virtual image type:

  • masked images, where a mask image can control write access to an underlying image.

Other possible concrete images include:

  • "bitmaps", 1 bit/sample images (perhaps limited to a single channel)

  • 16-bit/index paletted images

Some other possible virtual images:

  • image alpha combining, where the combining function can be specified (see the layer modes in graphical editors like the GIMP or Photoshop.

THE INTERFACE

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:

  • vtbl - pointer to an i_img_vtable struct which contains the callbacks listed below.

  • channels - the number of color related samples kept for each pixel in the image. For paletted images the samples are kept for each entry in the palette.

  • extrachannels - the number of extra samples kept for each pixel in the image. Imager's paletted image doesn't allow extra samples.

  • xsize, ysize - the dimensions of the image in pixels.

  • bytes - the number of bytes of data kept for the image. Zero for virtual images. Does not include the space required for the palette for paletted images.

  • ch_mask - controls which samples will be written to for direct images.

  • bits - the number of bits kept for each sample. There are enum values i_8_bits, i_16_bits and i_double_bits (64).

  • type - the type of image, either i_direct_type or i_palette_type. Direct images keep the samples for every pixel image, while i_palette_type images keep an index into a color table for each pixel.

  • islinear - whether the image's native samples are linear or gamma scaled.

  • isvirtual - whether the image keeps any pixel data. If this is non-zero then idata points to image data, otherwise it points to implementation defined data, though ext_data is more likely to be used for that.

  • idata - image data. If the image is 8-bit direct, non-virtual, then this consists of each sample of the image stored one after another, otherwise it is implementation defined.

  • tags - will be used to store meta-data for an image, eg. tags from a TIFF file, or animation information from a GIF file. This should be initialized with a call to i_tags_new() in your image constructor if creating a new image type.

  • ref_count - the number of references to this image.

  • ext_data - for internal use of image types. This is not released by the standard i_img_exorcise() function. If you create a new image type and want to store a pointer to allocated memory here you should point i_f_destroy at a function that will release the data.

  • context - the Imager API context this image was created in.

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.

i_f_gsamp(im,l,r,y,samples,chans,chan_count)
i_f_gsampf(im,l,r,y,fsamples,chans,chan_count)

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.

i_f_psamp(im,l,r,y,samples,chans,chan_count)
i_f_psampf(im,l,r,y,fsamples,chans,chan_count)

Writes samples to 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 samples set (not the number of channels). If a channel in chans is not present in the image or l < 0, returns -1. If r > im->xsize, then the samples from (l,y) ... (im->xsize-1, y) are returned.

i_f_data(im, layout, bits, flags, &data, *size, &extra)

Retrieves image data for the whole image. If the requested layout matches the image layout this will return the image's internal representation, otherwise if idf_synthesize is set in flags it will allocate a buffer and fill it with the requested layout (with some limitations). An implementor can check for the image's layout, and fallback to "i_img_data_fallback()" in Imager::APIRef.

The return value is used to release the returned data, it can hold a reference count on the image, or a callback to release the data returned in data.

i_f_imageop(im, name, parameters)

Perform a specified (generally) whole-image operation. Future use. Values of opname starting with i_ are reserved for definition by Imager itself.

i_f_gsamp_bits(im,l,r,y,usamples,chans,chan_count,bits)

Like i_f_gsamp except the samples buffer is unsigned rather than i_sample_t, and the samples are scaled by 1<<(bits-1). An implementor can fallback to i_gsamp_bits_fb.

i_f_psamp_bits(im,l,r,y,usamples,chans,chan_count,bits)

Like i_f_psamp except the samples buffer is unsigned rather than i_sample_t, and the samples are scaled by 1<<(bits-1). An implementor can fallback to i_psamp_bits_fb.

i_f_gslin(im,l,r,y,samples,chans,chan_count)
i_f_gslinf(im,l,r,y,fsamples,chans,chan_count)

Like gsamp()/gsampf() except linear samples are returned. An implementation can set this to i_gslin_fallback or i_gslinf_fallback to save effort at the cost of a little performance.

i_f_pslin(im,l,r,y,samples,chans,chan_count)
i_f_pslinf(im,l,r,y,fsamples,chans,chan_count)

Like psamp()/psampf() except linear samples are returned. An implementation can set this to i_pslin_fallback or i_pslinf_fallback to save effort at the cost of a little performance.

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

i_f_gpal(im,l,r,y,vals)

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

i_f_ppal(im,l,r,y,vals)

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

i_f_addcolors(im,colors,count)

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.

i_f_getcolors(im,index,colors,count)

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

i_f_colorcount(im)

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

i_f_maxcolors(im)

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

i_f_findcolor(im,color,entry)

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.

i_f_setcolors_t(im,index,colors,count)

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.

TOOLS

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

These tools are available by including imagei.h.

Fallback functions

These functions implement most of the interface, allowing an image implementer to only implement the i_gsamp() and i_gsampf() interfaces.

These are:

i_gsampf_fp
i_psampf_fp
i_gsamp_bits_fb
i_psamp_bits_fb
i_gslin_fallback
i_gslinf_fallback
i_pslin_fallback
i_pslinf_fallback
i_img_data_fallback

See "im_img_alloc()" in Imager::APIRef for some details.

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

i_addcolors_forward
i_getcolors_forward
i_colorcount_forward
i_maxcolors_forward
i_findcolor_forward
i_setcolors_forward

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

SampleFTo16(sample)
Sample16ToF(sample)
SampleFTo8(sample)
Sample8ToF(sample)
Sample16To8(num)
Sample8To16(num)

AUTHOR

Tony Cook <tonyc@cpan.org>, Arnar M. Hrafnkelsson