=head1 NAME
|
|
|
|
Imager::interface.pod - decribes the C level virtual image interface
|
|
|
|
=head1 SYNOPSIS
|
|
|
|
|
|
=head1 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.
|
|
|
|
=head2 Existing Images
|
|
|
|
As of this writing we have the following concrete image types:
|
|
|
|
=over
|
|
|
|
=item *
|
|
|
|
8-bit/sample direct images
|
|
|
|
=item *
|
|
|
|
16-bit/sample direct images
|
|
|
|
=item *
|
|
|
|
double/sample direct images
|
|
|
|
=item *
|
|
|
|
8-bit/sample 8-bit/index paletted images
|
|
|
|
=back
|
|
|
|
Currently there is only one virtual image type:
|
|
|
|
=over
|
|
|
|
=item *
|
|
|
|
masked images, where a mask image can control write access to an
|
|
underlying image.
|
|
|
|
=back
|
|
|
|
Other possible concrete images include:
|
|
|
|
=over
|
|
|
|
=item *
|
|
|
|
"bitmaps", 1 bit/sample images (perhaps limited to a single channel)
|
|
|
|
=item *
|
|
|
|
16-bit/index paletted images
|
|
|
|
=back
|
|
|
|
Some other possible virtual images:
|
|
|
|
=over
|
|
|
|
=item *
|
|
|
|
image alpha combining, where the combining function can be specified
|
|
(see the layer modes in graphical editors like the GIMP or photoshop.
|
|
|
|
=back
|
|
|
|
=head1 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:
|
|
|
|
=over
|
|
|
|
=item 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.
|
|
|
|
=item xsize, ysize
|
|
|
|
the dimensions of the image in pixels.
|
|
|
|
=item 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.
|
|
|
|
=item ch_mask
|
|
|
|
controls which samples will be written to for direct images.
|
|
|
|
=item bits
|
|
|
|
the number of bits kept for each sample. There are enum values
|
|
i_8_bits, i_16_bits and i_double_bits (64).
|
|
|
|
=item 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.
|
|
|
|
=item 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.
|
|
|
|
=item 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.
|
|
|
|
=item 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.
|
|
|
|
=item 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.
|
|
|
|
=back
|
|
|
|
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.
|
|
|
|
=over
|
|
|
|
=item i_f_ppix(im, x, y, color)
|
|
|
|
=item i_f_ppixf(im, x, y, fcolor)
|
|
|
|
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.
|
|
|
|
=item i_f_plin(im, l, r, y, colors)
|
|
|
|
=item i_f_plinf(im, l, r, y, fcolors)
|
|
|
|
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.
|
|
|
|
=item i_f_gpix(im, x, y, color)
|
|
|
|
=item i_f_gpixf(im, x, y, fcolor)
|
|
|
|
retrieves a single pixel from position (x,y). This returns the
|
|
samples rather than the index for paletted images.
|
|
|
|
=item i_f_glin(im, l, r, y, colors)
|
|
|
|
=item i_f_glinf(im, l, r, y, fcolors)
|
|
|
|
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.
|
|
|
|
=item i_f_gsamp(im, l, r, y, samples, chans, chan_count)
|
|
|
|
=item 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.
|
|
|
|
=back
|
|
|
|
The following are for images where type == i_palette_type only.
|
|
|
|
=over
|
|
|
|
=item 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.
|
|
|
|
=item 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 indices are
|
|
outside the range of the images palette, then you may have problems
|
|
reading those pixels with i_gpix() or i_glin().
|
|
|
|
=item 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.
|
|
|
|
=item 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.
|
|
|
|
=item i_f_colorcount(im)
|
|
|
|
Returns the number of colors in the image's palette. Returns -1 if
|
|
this is not a paletted image.
|
|
|
|
=item 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.
|
|
|
|
=item 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.
|
|
|
|
=item 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.
|
|
|
|
=back
|
|
|
|
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.
|
|
|
|
=head1 TOOLS
|
|
|
|
Several functions have been written to simplify creating new image types.
|
|
|
|
These tools are available by including imagei.h.
|
|
|
|
=head2 Floating point wrappers
|
|
|
|
These functions implement the floating point sample versions of each
|
|
interface function in terms of the integer sample version.
|
|
|
|
These are:
|
|
|
|
=over
|
|
|
|
=item i_ppixf_fp
|
|
|
|
=item i_gpixf_fp
|
|
|
|
=item i_plinf_fp
|
|
|
|
=item i_glinf_fp
|
|
|
|
=item i_gsampf_fp
|
|
|
|
=back
|
|
|
|
|
|
=head2 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 :)
|
|
|
|
=over
|
|
|
|
=item i_addcolors_forward
|
|
|
|
=item i_getcolors_forward
|
|
|
|
=item i_colorcount_forward
|
|
|
|
=item i_maxcolors_forward
|
|
|
|
=item i_findcolor_forward
|
|
|
|
=item i_setcolors_forward
|
|
|
|
=back
|
|
|
|
=head2 Sample macros
|
|
|
|
Imagei.h defines several macros for converting samples between
|
|
different sizes.
|
|
|
|
Each macro is of the form SampleI<size>ToI<size> where I<size> is one
|
|
of 8, 16, or F (for floating-point samples).
|
|
|
|
=over
|
|
|
|
=item SampleFTo16(sample)
|
|
|
|
=item Sample16ToF(sample)
|
|
|
|
=item SampleFTo8(sample)
|
|
|
|
=item Sample8ToF(sample)
|
|
|
|
=item Sample16To8(num)
|
|
|
|
=item Sample8To16(num)
|
|
|
|
=back
|
|
|
|
=cut
|