=head1 NAME

Imager::interface.pod - decribes the 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 *

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.  Currently unused.

=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