.\" Automatically generated by Pod::Man 4.11 (Pod::Simple 3.35)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "Imager::interface 3"
.TH Imager::interface 3 "2014-01-10" "perl v5.26.3" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Imager::interface.pod \- describes the C level virtual image interface
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.SH "DESCRIPTION"
.IX Header "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.
.PP
This is a C level interface rather than Perl.
.SS "Existing Images"
.IX Subsection "Existing Images"
As of this writing we have the following concrete image types:
.IP "\(bu" 4
8\-bit/sample direct images
.IP "\(bu" 4
16\-bit/sample direct images
.IP "\(bu" 4
double/sample direct images
.IP "\(bu" 4
8\-bit/sample 8\-bit/index paletted images
.PP
Currently there is only one virtual image type:
.IP "\(bu" 4
masked images, where a mask image can control write access to an
underlying image.
.PP
Other possible concrete images include:
.IP "\(bu" 4
\&\*(L"bitmaps\*(R", 1 bit/sample images (perhaps limited to a single channel)
.IP "\(bu" 4
16\-bit/index paletted images
.PP
Some other possible virtual images:
.IP "\(bu" 4
image alpha combining, where the combining function can be specified
(see the layer modes in graphical editors like the \s-1GIMP\s0 or Photoshop.
.SH "THE INTERFACE"
.IX Header "THE INTERFACE"
Each image type needs to define a number of functions which implement
the image operations.
.PP
The image structure includes information describes the image, which
can be used to determine the structure of the image:
.IP "\(bu" 4
\&\f(CW\*(C`channels\*(C'\fR \- the number of samples kept for each pixel in the image.
For paletted images the samples are kept for each entry in the
palette.
.IP "\(bu" 4
\&\f(CW\*(C`xsize\*(C'\fR, \f(CW\*(C`ysize\*(C'\fR \- the dimensions of the image in pixels.
.IP "\(bu" 4
\&\f(CW\*(C`bytes\*(C'\fR \- 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.
.IP "\(bu" 4
\&\f(CW\*(C`ch_mask\*(C'\fR \- controls which samples will be written to for direct
images.
.IP "\(bu" 4
\&\f(CW\*(C`bits\*(C'\fR \- the number of bits kept for each sample.  There are enum
values i_8_bits, i_16_bits and i_double_bits (64).
.IP "\(bu" 4
\&\f(CW\*(C`type\*(C'\fR \- 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.
.IP "\(bu" 4
\&\f(CW\*(C`virtual\*(C'\fR \- whether the image keeps any pixel data.  If this is
non-zero then \f(CW\*(C`idata\*(C'\fR points to image data, otherwise it points to
implementation defined data, though \f(CW\*(C`ext_data\*(C'\fR is more likely to be
used for that.
.IP "\(bu" 4
\&\f(CW\*(C`idata\*(C'\fR \- 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.
.IP "\(bu" 4
\&\f(CW\*(C`tags\*(C'\fR \- will be used to store meta-data for an image, eg. tags from
a \s-1TIFF\s0 file, or animation information from a \s-1GIF\s0 file.  This should be
initialized with a call to \fBi_tags_new()\fR in your image constructor if
creating a new image type.
.IP "\(bu" 4
\&\f(CW\*(C`ext_data\*(C'\fR \- for internal use of image types.  This is not released
by the standard \fBi_img_exorcise()\fR 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.
.PP
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.
.PP
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.
.IP "i_f_ppix(im,x,y,color)" 4
.IX Item "i_f_ppix(im,x,y,color)"
.PD 0
.IP "i_f_ppixf(im,x,y,fcolor)" 4
.IX Item "i_f_ppixf(im,x,y,fcolor)"
.PD
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 \f(CW\*(C`color\*(C'\fR or \f(CW\*(C`fcolor\*(C'\fR always contains the actual samples to be
written, rather than a palette index.
.IP "i_f_plin(im,l,r,y,colors)" 4
.IX Item "i_f_plin(im,l,r,y,colors)"
.PD 0
.IP "i_f_plinf(im,l,r,y,fcolors)" 4
.IX Item "i_f_plinf(im,l,r,y,fcolors)"
.PD
stores (r\-l) pixels at positions (l,y) ... (r\-1, y) from the array
specified by \f(CW\*(C`colors\*(C'\fR (or \f(CW\*(C`fcolors\*(C'\fR).  Returns the number of pixels
written to.  If l is negative it will return 0.  If \f(CW\*(C`r > im\->xsize\*(C'\fR then only \f(CW\*(C`(im\->xsize \- l)\*(C'\fR will be written.
.IP "i_f_gpix(im,x,y,color)" 4
.IX Item "i_f_gpix(im,x,y,color)"
.PD 0
.IP "i_f_gpixf(im,x,y,fcolor)" 4
.IX Item "i_f_gpixf(im,x,y,fcolor)"
.PD
retrieves a single pixel from position (x,y).  This returns the
samples rather than the index for paletted images.
.IP "i_f_glin(im,l,r,y,colors)" 4
.IX Item "i_f_glin(im,l,r,y,colors)"
.PD 0
.IP "i_f_glinf(im,l,r,y,fcolors)" 4
.IX Item "i_f_glinf(im,l,r,y,fcolors)"
.PD
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 \f(CW\*(C`r > im\->xsize\*(C'\fR then pixels
\&\f(CW\*(C`(l, y)\*(C'\fR ... \f(CW\*(C`(im\->xsize\-1, y)\*(C'\fR are retrieved.  Retrieves
the samples rather than the color indexes for paletted images.
.IP "i_f_gsamp(im,l,r,y,samples,chans,chan_count)" 4
.IX Item "i_f_gsamp(im,l,r,y,samples,chans,chan_count)"
.PD 0
.IP "i_f_gsampf(im,l,r,y,fsamples,chans,chan_count)" 4
.IX Item "i_f_gsampf(im,l,r,y,fsamples,chans,chan_count)"
.PD
Retrieves samples from channels specified by \f(CW\*(C`chans\*(C'\fR (for length
\&\f(CW\*(C`chan_count\*(C'\fR) from pixels at positions (l,y) ... (r\-1, y).  If
\&\f(CW\*(C`chans\*(C'\fR is \s-1NULL\s0 then samples from channels 0 ... \f(CW\*(C`chan_count\-1\*(C'\fR will
be retrieved.  Returns the number of sample retrieved (\fInot\fR the
number of channels).  If a channel in \f(CW\*(C`chans\*(C'\fR is not present in the
image or l < 0, returns 0.  If \f(CW\*(C`r > im\->xsize\*(C'\fR, then the samples
from \f(CW\*(C`(l,y)\*(C'\fR ... \f(CW\*(C`(im\->xsize\-1, y)\*(C'\fR are returned.
.PP
The following are for images where type == i_palette_type only.
.IP "i_f_gpal(im,l,r,y,vals)" 4
.IX Item "i_f_gpal(im,l,r,y,vals)"
Retrieves color indexes from the image for pixels (l, y) ... (r\-1, y)
into \f(CW\*(C`vals\*(C'\fR.  Returns the number of indexes retrieved.
.IP "i_f_ppal(im,l,r,y,vals)" 4
.IX Item "i_f_ppal(im,l,r,y,vals)"
Stores color indexes into the image for pixels (l, y) ... (r\-1, y)
from \f(CW\*(C`vals\*(C'\fR.  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 \fBi_gpix()\fR or \fBi_glin()\fR.
.IP "i_f_addcolors(im,colors,count)" 4
.IX 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.
.IP "i_f_getcolors(im,index,colors,count)" 4
.IX 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.
.IP "i_f_colorcount(im)" 4
.IX Item "i_f_colorcount(im)"
Returns the number of colors in the image's palette.  Returns \-1 if
this is not a paletted image.
.IP "i_f_maxcolors(im)" 4
.IX 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.
.IP "i_f_findcolor(im,color,entry)" 4
.IX 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.
.IP "i_f_setcolors_t(im,index,colors,count)" 4
.IX 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.
.PP
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.
.PP
When writing to a paletted image with \fBi_ppix()\fR or \fBi_plin()\fR 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.
.SH "TOOLS"
.IX Header "TOOLS"
Several functions have been written to simplify creating new image types.
.PP
These tools are available by including \fIimagei.h\fR.
.SS "Floating point wrappers"
.IX Subsection "Floating point wrappers"
These functions implement the floating point sample versions of each
interface function in terms of the integer sample version.
.PP
These are:
.IP "i_ppixf_fp" 4
.IX Item "i_ppixf_fp"
.PD 0
.IP "i_gpixf_fp" 4
.IX Item "i_gpixf_fp"
.IP "i_plinf_fp" 4
.IX Item "i_plinf_fp"
.IP "i_glinf_fp" 4
.IX Item "i_glinf_fp"
.IP "i_gsampf_fp" 4
.IX Item "i_gsampf_fp"
.PD
.SS "Forwarding functions"
.IX Subsection "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.
.PP
If this is not the case then these functions will just crash :)
.IP "i_addcolors_forward" 4
.IX Item "i_addcolors_forward"
.PD 0
.IP "i_getcolors_forward" 4
.IX Item "i_getcolors_forward"
.IP "i_colorcount_forward" 4
.IX Item "i_colorcount_forward"
.IP "i_maxcolors_forward" 4
.IX Item "i_maxcolors_forward"
.IP "i_findcolor_forward" 4
.IX Item "i_findcolor_forward"
.IP "i_setcolors_forward" 4
.IX Item "i_setcolors_forward"
.PD
.SS "Sample macros"
.IX Subsection "Sample macros"
\&\f(CW\*(C`imagei.h\*(C'\fR defines several macros for converting samples between
different sizes.
.PP
Each macro is of the form \f(CW\*(C`Sample\*(C'\fR\fIsize\fR\f(CW\*(C`To\*(C'\fR\fIsize\fR where \fIsize\fR is one
of 8, 16, or F (for floating-point samples).
.IP "SampleFTo16(sample)" 4
.IX Item "SampleFTo16(sample)"
.PD 0
.IP "Sample16ToF(sample)" 4
.IX Item "Sample16ToF(sample)"
.IP "SampleFTo8(sample)" 4
.IX Item "SampleFTo8(sample)"
.IP "Sample8ToF(sample)" 4
.IX Item "Sample8ToF(sample)"
.IP "Sample16To8(num)" 4
.IX Item "Sample16To8(num)"
.IP "Sample8To16(num)" 4
.IX Item "Sample8To16(num)"
.PD
.SH "AUTHOR"
.IX Header "AUTHOR"
Tony Cook <tonyc@cpan.org>, Arnar M. Hrafnkelsson