1 files changed, 343 insertions, 0 deletions
diff --git a/Master/tlpkg/tlperl0/lib/Imager/interface.pod b/Master/tlpkg/tlperl0/lib/Imager/interface.pod
new file mode 100755
index 00000000000..580e6e5fc8a
--- /dev/null
+++ b/Master/tlpkg/tlperl0/lib/Imager/interface.pod
@@ -0,0 +1,343 @@
+=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