Imager::interface.pod - describes the C level virtual image interface |
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.
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:
channels
- the number of samples kept for each pixel in the image.
For paletted images the samples are kept for each entry in the
palette.
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.
virtual
- 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.
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.
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_ppix(im,x,y,color)
i_f_ppixf(im,x,y,fcolor)
color
or fcolor
always contains the actual samples to be
written, rather than a palette index.
i_f_plin(im,l,r,y,colors)
i_f_plinf(im,l,r,y,fcolors)
colors
(or fcolors
). Returns the number of pixels
written to. If l is negative it will return 0. If r > im->xsize
>> then only C<< (im->xsize - l) >>
will be written.
i_f_gpix(im,x,y,color)
i_f_gpixf(im,x,y,fcolor)
i_f_glin(im,l,r,y,colors)
i_f_glinf(im,l,r,y,fcolors)
r > im->xsize
then pixels
(l, y)
... (im->xsize-1, y)
are retrieved. Retrieves
the samples rather than the color indexes for paletted images.
i_f_gsamp(im,l,r,y,samples,chans,chan_count)
i_f_gsampf(im,l,r,y,fsamples,chans,chan_count)
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.
i_f_gpal(im,l,r,y,vals)
vals
. Returns the number of indexes retrieved.
i_f_ppal(im,l,r,y,vals)
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)
i_f_getcolors(im,index,colors,count)
i_f_colorcount(im)
i_f_maxcolors(im)
i_f_findcolor(im,color,entry)
i_f_setcolors_t(im,index,colors,count)
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.
These functions implement the floating point sample versions of each interface function in terms of the integer sample version.
These are:
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 :)
imagei.h
defines several macros for converting samples between
different sizes.
Each macro is of the form Sample
sizeTo
size 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)
Tony Cook <tonyc@cpan.org>, Arnar M. Hrafnkelsson
Imager::interface.pod - describes the C level virtual image interface |