X-Git-Url: http://git.imager.perl.org/imager.git/blobdiff_plain/5ca7e2abea05462da0438ea64592fae1dcf86666..7477ff14dc863339428b6f9f4b863adcd9fa1103:/lib/Imager/APIRef.pod

diff --git a/lib/Imager/APIRef.pod b/lib/Imager/APIRef.pod
index e92e4c49..c9e5b480 100644
--- a/lib/Imager/APIRef.pod
+++ b/lib/Imager/APIRef.pod
@@ -6,54 +6,326 @@ you can find the documentation.
 
 =head1 NAME
 
-Imager::APIRef - Imager's C API.
+Imager::APIRef - Imager's C API - reference.
 
 =head1 SYNOPSIS
 
   i_color color;
-  color.rgba.red = 255; color.rgba.green = 0; color.rgba.blue = 255;
-  i_fill_t *fill = i_new_fill_...(...);
+  color.rgba.r = 255; color.rgba.g = 0; color.rgba.b = 255;
 
 
+  # Blit tools
+
+  # Data Types
+  i_img *img;
+  i_color black;
+  black.rgba.r = black.rgba.g = black.rgba.b = black.rgba.a = 0;
+  i_fill_t *fill;
+  i_img_dim x;
+
   # Drawing
   i_arc(im, 50, 50, 20, 45, 135, &color);
+  i_arc_cfill(im, 50, 50, 35, 90, 135, fill);
   i_arc_aa(im, 50, 50, 35, 90, 135, &color);
   i_arc_aa_cfill(im, 50, 50, 35, 90, 135, fill);
-  i_arc_cfill(im, 50, 50, 35, 90, 135, fill);
+  i_circle_aa(im, 50, 50, 45, &color);
   i_box(im, 0, 0, im->xsize-1, im->ysize-1, &color).
-  i_box_cfill(im, 0, 0, im->xsize-1, im->ysize-1, fill);
   i_box_filled(im, 0, 0, im->xsize-1, im->ysize-1, &color);
-  i_circle_aa(im, 50, 50, 45, &color);
-  i_flood_cfill(im, 50, 50, fill);
-  i_flood_cfill_border(im, 50, 50, fill, border);
+  i_box_cfill(im, 0, 0, im->xsize-1, im->ysize-1, fill);
   i_flood_fill(im, 50, 50, &color);
+  i_flood_cfill(im, 50, 50, fill);
   i_flood_fill_border(im, 50, 50, &color, &border);
+  i_flood_cfill_border(im, 50, 50, fill, border);
 
   # Error handling
+  i_clear_error();
+  i_push_error(0, "Yep, it's broken");
+  i_push_error(errno, "Error writing");
+  i_push_errorf(errno, "Cannot open file %s: %d", filename, errno);
 
   # Files
+  i_set_image_file_limits(500, 500, 1000000);
   i_get_image_file_limits(&width, &height, &bytes)
   i_i_int_check_image_file_limits(width, height, channels, sizeof(i_sample_t))
-  i_set_image_file_limits(500, 500, 1000000);
 
   # Fills
+  i_fill_t *fill = i_new_fill_solidf(&fcolor, combine);
+  i_fill_t *fill = i_new_fill_solid(&color, combine);
+  i_fill_t *fill = i_new_fill_hatch(&fg_color, &bg_color, combine, hatch, custom_hatch, dx, dy);
+  i_fill_t *fill = i_new_fill_hatchf(&fg_fcolor, &bg_fcolor, combine, hatch, custom_hatch, dx, dy);
+  i_fill_t *fill = i_new_fill_image(src_img, matrix, x_offset, y_offset, combine);
   fill = i_new_fill_fount(0, 0, 100, 100, i_ft_linear, i_ft_linear, 
                           i_fr_triangle, 0, i_fts_grid, 9, 1, segs);
+  i_fill_destroy(fill);
 
   # Image
 
-  # Image creation
+  # Image creation/destruction
+  i_img *img = i_img_8_new(width, height, channels);
+  i_img *img = i_sametype(src, width, height);
+  i_img *img = i_sametype_chans(src, width, height, channels);
+  i_img *img = i_img_pal_new(width, height, channels, max_palette_size)
+  i_img *img = i_img_double_new(width, height, channels);
+  i_img *img = i_img_16_new(width, height, channels);
+  i_img_destroy(img)
+
+  # Image Implementation
+
+  # Image Information
+  // only channel 0 writeable 
+  i_img_setmask(img, 0x01);
+  int mask = i_img_getmask(img);
+  int channels = i_img_getchannels(img);
+  i_img_dim width = i_img_get_width(im);
+  i_img_dim height = i_img_get_height(im);
 
   # Image quantization
 
+  # Logging
+
   # Paletted images
 
   # Tags
-
-   i_fill_destroy(fill);
+  i_tags_set(&img->tags, "i_comment", -1);
+  i_tags_setn(&img->tags, "i_xres", 204);
+  i_tags_setn(&img->tags, "i_yres", 196);
 
 =head1 DESCRIPTION
 
+=head2 Blit tools
+
+=over
+
+=item i_render_color(r, x, y, width, source, color)
+
+Render the given color with the coverage specified by C<source[0]> to
+C<source[width-1]>.
+
+Renders in normal combine mode.
+
+
+=for comment
+From: File render.im
+
+=item i_render_delete(r)
+
+Release an C<i_render> object.
+
+
+=for comment
+From: File render.im
+
+=item i_render_fill(r, x, y, width, source, fill)
+
+Render the given fill with the coverage in C<source[0]> through
+C<source[width-1]>.
+
+
+=for comment
+From: File render.im
+
+=item i_render_line(r, x, y, width, source, fill)
+
+Render the given fill with the coverage in C<source[0]> through
+C<source[width-1]>.
+
+
+=for comment
+From: File render.im
+
+=item i_render_linef(r, x, y, width, source, fill)
+
+Render the given fill with the coverage in C<source[0]> through
+C<source[width-1]>.
+
+
+=for comment
+From: File render.im
+
+=item i_render_new(im, width)
+
+Allocate a new C<i_render> object and initialize it.
+
+
+=for comment
+From: File render.im
+
+
+=back
+
+=head2 Data Types
+
+=over
+
+=item i_img
+
+This is Imager's image type.
+
+It contains the following members:
+
+=over
+
+=item *
+
+C<channels> - the number of channels in the image
+
+=item *
+
+C<xsize>, C<ysize> - the width and height of the image in pixels
+
+=item *
+
+C<bytes> - the number of bytes used to store the image data.  Undefined
+where virtual is non-zero.
+
+=item *
+
+C<ch_mask> - a mask of writable channels.  eg. if this is 6 then only
+channels 1 and 2 are writable.  There may be bits set for which there
+are no channels in the image.
+
+=item *
+
+C<bits> - the number of bits stored per sample.  Should be one of
+i_8_bits, i_16_bits, i_double_bits.
+
+=item *
+
+C<type> - either i_direct_type for direct color images, or i_palette_type
+for paletted images.
+
+=item *
+
+C<virtual> - if zero then this image is-self contained.  If non-zero
+then this image could be an interface to some other implementation.
+
+=item *
+
+C<idata> - the image data.  This should not be directly accessed.  A new
+image implementation can use this to store its image data.
+i_img_destroy() will myfree() this pointer if it's non-null.
+
+=item *
+
+C<tags> - a structure storing the image's tags.  This should only be
+accessed via the i_tags_*() functions.
+
+=item *
+
+C<ext_data> - a pointer for use internal to an image implementation.
+This should be freed by the image's destroy handler.
+
+=item *
+
+C<im_data> - data internal to Imager.  This is initialized by
+i_img_init().
+
+=item *
+
+i_f_ppix, i_f_ppixf, i_f_plin, i_f_plinf, i_f_gpix, i_f_gpixf,
+i_f_glin, i_f_glinf, i_f_gsamp, i_f_gampf - implementations for each
+of the required image functions.  An image implementation should
+initialize these between calling i_img_alloc() and i_img_init().
+
+=item *
+
+i_f_gpal, i_f_ppal, i_f_addcolors, i_f_getcolors, i_f_colorcount,
+i_f_maxcolors, i_f_findcolor, i_f_setcolors - implementations for each
+paletted image function.
+
+=item *
+
+i_f_destroy - custom image destruction function.  This should be used
+to release memory if necessary.
+
+=item *
+
+i_f_gsamp_bits - implements i_gsamp_bits() for this image.
+
+=item *
+
+i_f_psamp_bits - implements i_psamp_bits() for this image.
+
+=back
+
+
+=for comment
+From: File imdatatypes.h
+
+=item i_color
+
+Type for 8-bit/sample color.
+
+Samples as per;
+
+  i_color c;
+
+i_color is a union of:
+
+=over
+
+=item *
+
+gray - contains a single element gray_color, eg. C<c.gray.gray_color>
+
+=item *
+
+C<rgb> - contains three elements C<r>, C<g>, C<b>, eg. C<c.rgb.r>
+
+=item *
+
+C<rgba> - contains four elements C<r>, C<g>, C<b>, C<a>, eg. C<c.rgba.a>
+
+=item *
+
+C<cmyk> - contains four elements C<c>, C<m>, C<y>, C<k>,
+eg. C<c.cmyk.y>.  Note that Imager never uses CMYK colors except when
+reading/writing files.
+
+=item *
+
+channels - an array of four channels, eg C<c.channels[2]>.
+
+=back
+
+
+=for comment
+From: File imdatatypes.h
+
+=item i_fcolor
+
+This is the double/sample color type.
+
+Its layout exactly corresponds to i_color.
+
+
+=for comment
+From: File imdatatypes.h
+
+=item i_fill_t
+
+This is the "abstract" base type for Imager's fill types.
+
+Unless you're implementing a new fill type you'll typically treat this
+as an opaque type.
+
+
+=for comment
+From: File imdatatypes.h
+
+=item i_img_dim
+
+A signed integer type that represents an image dimension or ordinate.
+
+May be larger than int on some platforms.
+
+
+=for comment
+From: File imdatatypes.h
+
+
+=back
+
 =head2 Drawing
 
 =over
@@ -71,7 +343,7 @@ From: File draw.c
 =item i_arc_aa(im, x, y, rad, d1, d2, color)
 
 
-Antialias fills an arc centered at (x,y) with radius I<rad> covering
+Anti-alias fills an arc centered at (x,y) with radius I<rad> covering
 the range of angles in degrees from d1 to d2, with the color.
 
 
@@ -81,7 +353,7 @@ From: File draw.c
 =item i_arc_aa_cfill(im, x, y, rad, d1, d2, fill)
 
 
-Antialias fills an arc centered at (x,y) with radius I<rad> covering
+Anti-alias fills an arc centered at (x,y) with radius I<rad> covering
 the range of angles in degrees from d1 to d2, with the fill object.
 
 
@@ -128,58 +400,58 @@ From: File draw.c
 =item i_circle_aa(im, x, y, rad, color)
 
 
-Antialias fills a circle centered at (x,y) for radius I<rad> with
+Anti-alias fills a circle centered at (x,y) for radius I<rad> with
 color.
 
 
 =for comment
 From: File draw.c
 
-=item i_flood_cfill(im, seedx, seedy, fill)
+=item i_flood_cfill(C<im>, C<seedx>, C<seedy>, C<fill>)
 
 
-Flood fills the 4-connected region starting from the point (seedx,
-seedy) with I<fill>.
+Flood fills the 4-connected region starting from the point (C<seedx>,
+C<seedy>) with C<fill>.
 
-Returns false if (seedx, seedy) are outside the image.
+Returns false if (C<seedx>, C<seedy>) are outside the image.
 
 
 =for comment
 From: File draw.c
 
-=item i_flood_cfill_border(im, seedx, seedy, fill, border)
+=item i_flood_cfill_border(C<im>, C<seedx>, C<seedy>, C<fill>, C<border>)
 
 
-Flood fills the 4-connected region starting from the point (seedx,
-seedy) with I<fill>, the fill stops when it reaches pixels of color
-I<border>.
+Flood fills the 4-connected region starting from the point (C<seedx>,
+C<seedy>) with C<fill>, the fill stops when it reaches pixels of color
+C<border>.
 
-Returns false if (seedx, seedy) are outside the image.
+Returns false if (C<seedx>, C<seedy>) are outside the image.
 
 
 =for comment
 From: File draw.c
 
-=item i_flood_fill(im, seedx, seedy, color)
+=item i_flood_fill(C<im>, C<seedx>, C<seedy>, C<color>)
 
 
-Flood fills the 4-connected region starting from the point (seedx,
-seedy) with I<color>.
+Flood fills the 4-connected region starting from the point (C<seedx>,
+C<seedy>) with I<color>.
 
-Returns false if (seedx, seedy) are outside the image.
+Returns false if (C<seedx>, C<seedy>) are outside the image.
 
 
 =for comment
 From: File draw.c
 
-=item i_flood_fill_border(im, seedx, seedy, color, border)
+=item i_flood_fill_border(C<im>, C<seedx>, C<seedy>, C<color>, C<border>)
 
 
-Flood fills the 4-connected region starting from the point (seedx,
-seedy) with I<color>, fill stops when the fill reaches a pixels with
-color I<border>.
+Flood fills the 4-connected region starting from the point (C<seedx>,
+C<seedy>) with C<color>, fill stops when the fill reaches a pixels
+with color C<border>.
 
-Returns false if (seedx, seedy) are outside the image.
+Returns false if (C<seedx>, C<seedy>) are outside the image.
 
 
 =for comment
@@ -208,11 +480,11 @@ Returns the number of pixels retrieved.
 =for comment
 From: File imext.c
 
-=item i_gpal(im, x, r, y, indexes)
+=item i_gpal(im, left, right, y, indexes)
 
 
-Reads palette indexes for the horizontal line (x, y) to (r-1, y) into
-indexes.
+Reads palette indexes for the horizontal line (left, y) to (right-1,
+y) into C<indexes>.
 
 Returns the number of indexes read.
 
@@ -222,10 +494,10 @@ Always returns 0 for direct color images.
 =for comment
 From: File imext.c
 
-=item i_gpix(im, x, y, color)
+=item i_gpix(im, C<x>, C<y>, C<color>)
 
 
-Retrieves the I<color> of the pixel (x,y).
+Retrieves the C<color> of the pixel (x,y).
 
 Returns 0 if the pixel was retrieved, or -1 if not.
 
@@ -233,11 +505,11 @@ Returns 0 if the pixel was retrieved, or -1 if not.
 =for comment
 From: File imext.c
 
-=item i_gpixf(im, x, y, fcolor)
+=item i_gpixf(im, C<x>, C<y>, C<fcolor>)
 
 
 Retrieves the color of the pixel (x,y) as a floating point color into
-I<fcolor>.
+C<fcolor>.
 
 Returns 0 if the pixel was retrieved, or -1 if not.
 
@@ -245,63 +517,91 @@ Returns 0 if the pixel was retrieved, or -1 if not.
 =for comment
 From: File imext.c
 
-=item i_gsamp(im, l, r, y, samp, chans, chan_count)
+=item i_gsamp(im, left, right, y, samples, channels, channel_count)
 
 
-Reads sample values from im for the horizontal line (l, y) to (r-1,y)
-for the channels specified by chans, an array of int with chan_count
-elements.
+Reads sample values from C<im> for the horizontal line (left, y) to
+(right-1,y) for the channels specified by C<channels>, an array of int
+with C<channel_count> elements.
 
-If chans is NULL then the first chan_count channels are retrieved for
+If channels is NULL then the first channels_count channels are retrieved for
 each pixel.
 
-Returns the number of samples read (which should be (r-l) *
-chan_count)
+Returns the number of samples read (which should be (right-left) *
+channel_count)
 
 
 =for comment
 From: File imext.c
 
-=item i_gsampf(im, l, r, y, samp, chans, chan_count)
+=item i_gsamp_bg(im, l, r, y, samples, out_channels, background)
 
 
-Reads floating point sample values from im for the horizontal line (l,
-y) to (r-1,y) for the channels specified by chans, an array of int
-with chan_count elements.
+Like C<i_gsampf()> but applies the source image color over a supplied
+background color.
+
+This is intended for output to image formats that don't support alpha
+channels.
 
-If chans is NULL then the first chan_count channels are retrieved for
-each pixel.
 
-Returns the number of samples read (which should be (r-l) *
-chan_count)
+=for comment
+From: File paste.im
+
+=item i_gsampf(im, left, right, y, samples, channels, channel_count)
+
+
+Reads floating point sample values from C<im> for the horizontal line
+(left, y) to (right-1,y) for the channels specified by C<channels>, an
+array of int with channel_count elements.
+
+If C<channels> is NULL then the first C<channel_count> channels are
+retrieved for each pixel.
+
+Returns the number of samples read (which should be (C<right>-C<left>)
+* C<channel_count>)
 
 
 =for comment
 From: File imext.c
 
-=item i_line(im, x1, y1, x2, y2, val, endp)
+=item i_gsampf_bg(im, l, r, y, samples, out_channels, background)
+
+
+Like C<i_gsampf()> but applies the source image color over a supplied
+background color.
+
+This is intended for output to image formats that don't support alpha
+channels.
+
+
+=for comment
+From: File paste.im
+
+=item i_line(C<im>, C<x1>, C<y1>, C<x2>, C<y2>, C<color>, C<endp>)
+
 
+=for stopwords Bresenham's
 
-Draw a line to image using bresenhams linedrawing algorithm
+Draw a line to image using Bresenham's line drawing algorithm
 
-   im   - image to draw to
-   x1   - starting x coordinate
-   y1   - starting x coordinate
-   x2   - starting x coordinate
-   y2   - starting x coordinate
-   val  - color to write to image
-   endp - endpoint flag (boolean)
+   im    - image to draw to
+   x1    - starting x coordinate
+   y1    - starting x coordinate
+   x2    - starting x coordinate
+   y2    - starting x coordinate
+   color - color to write to image
+   endp  - endpoint flag (boolean)
 
 
 =for comment
 From: File draw.c
 
-=item i_line_aa(im, x1, x2, y1, y2, color, endp)
+=item i_line_aa(C<im>, C<x1>, C<x2>, C<y1>, C<y2>, C<color>, C<endp>)
 
 
-Antialias draws a line from (x1,y1) to (x2, y2) in color.
+Anti-alias draws a line from (x1,y1) to (x2, y2) in color.
 
-The point (x2, y2) is drawn only if endp is set.
+The point (x2, y2) is drawn only if C<endp> is set.
 
 
 =for comment
@@ -319,11 +619,11 @@ Returns the number of pixels set.
 =for comment
 From: File imext.c
 
-=item i_plinf(im, l, r, fcolors)
+=item i_plinf(im, C<left>, C<right>, C<fcolors>)
 
 
-Sets (r-l) pixels starting from (l,y) using (r-l) floating point
-colors from I<colors>.
+Sets (right-left) pixels starting from (left,y) using (right-left)
+floating point colors from C<fcolors>.
 
 Returns the number of pixels set.
 
@@ -331,11 +631,11 @@ Returns the number of pixels set.
 =for comment
 From: File imext.c
 
-=item i_ppal(im, x, r, y, indexes)
+=item i_ppal(im, left, right, y, indexes)
 
 
-Writes palette indexes for the horizontal line (x, y) to (r-1, y) from
-indexes.
+Writes palette indexes for the horizontal line (left, y) to (right-1,
+y) from C<indexes>.
 
 Returns the number of indexes written.
 
@@ -359,10 +659,10 @@ color to the image.
 =for comment
 From: File imext.c
 
-=item i_ppixf(im, x, y, fcolor)
+=item i_ppixf(im, C<x>, C<y>, C<fcolor>)
 
 
-Sets the pixel at (x,y) to the floating point color I<fcolor>.
+Sets the pixel at (C<x>,C<y>) to the floating point color C<fcolor>.
 
 Returns 0 if the pixel was drawn, or -1 if not.
 
@@ -382,10 +682,9 @@ From: File imext.c
 
 =item i_clear_error()
 
-
 Clears the error stack.
 
-Called by any imager function before doing any other processing.
+Called by any Imager function before doing any other processing.
 
 
 =for comment
@@ -393,8 +692,7 @@ From: File error.c
 
 =item i_push_error(int code, char const *msg)
 
-
-Called by an imager function to push an error message onto the stack.
+Called by an Imager function to push an error message onto the stack.
 
 No message is pushed if the stack is full (since this means someone
 forgot to call i_clear_error(), or that a function that doesn't do
@@ -406,19 +704,22 @@ From: File error.c
 
 =item i_push_errorf(int code, char const *fmt, ...)
 
+A version of i_push_error() that does printf() like formatting.
 
-A version of i_push_error() that does printf() like formating.
+Does not support perl specific format codes.
 
 
 =for comment
 From: File error.c
 
-=item i_push_errorvf(int code, char const *fmt, va_list ap)
+=item i_push_errorvf(int C<code>, char const *C<fmt>, va_list C<ap>)
 
 
 Intended for use by higher level functions, takes a varargs pointer
 and a format to produce the finally pushed error message.
 
+Does not support perl specific format codes.
+
 
 =for comment
 From: File error.c
@@ -430,6 +731,31 @@ From: File error.c
 
 =over
 
+=item i_get_file_background(im, &bg)
+
+
+Retrieve the file write background color tag from the image.
+
+If not present, returns black.
+
+
+=for comment
+From: File image.c
+
+=item i_get_file_backgroundf(im, &bg)
+
+
+Retrieve the file write background color tag from the image as a
+floating point color.
+
+Implemented in terms of i_get_file_background().
+
+If not present, returns black.
+
+
+=for comment
+From: File image.c
+
 =item i_get_image_file_limits(&width, &height, &bytes)
 
 
@@ -478,16 +804,7 @@ From: File limits.c
 
 =over
 
-=item i_fill_destroy(fill)
-
-
-Call to destroy any fill object.
-
-
-=for comment
-From: File fills.c
-
-=item i_new_fill_fount(xa, ya, xb, yb, type, repeat, combine, super_sample, ssample_param, count, segs)
+=item i_new_fill_fount(C<xa>, C<ya>, C<xb>, C<yb>, C<type>, C<repeat>, C<combine>, C<super_sample>, C<ssample_param>, C<count>, C<segs>)
 
 
 
@@ -495,52 +812,56 @@ Creates a new general fill which fills with a fountain fill.
 
 
 =for comment
-From: File filters.c
+From: File filters.im
 
-=item i_new_fill_hatch(fg, bg, combine, hatch, cust_hatch, dx, dy)
+=item i_new_fill_hatch(C<fg>, C<bg>, C<combine>, C<hatch>, C<cust_hatch>, C<dx>, C<dy>)
 
 
-Creates a new hatched fill with the fg color used for the 1 bits in
-the hatch and bg for the 0 bits.  If combine is non-zero alpha values
-will be combined.
+Creates a new hatched fill with the C<fg> color used for the 1 bits in
+the hatch and C<bg> for the 0 bits.  If C<combine> is non-zero alpha
+values will be combined.
 
-If cust_hatch is non-NULL it should be a pointer to 8 bytes of the
+If C<cust_hatch> is non-NULL it should be a pointer to 8 bytes of the
 hash definition, with the high-bits to the left.
 
-If cust_hatch is NULL then one of the standard hatches is used.
+If C<cust_hatch> is NULL then one of the standard hatches is used.
 
-(dx, dy) are an offset into the hatch which can be used to unalign adjoining areas, or to align the origin of a hatch with the the side of a filled area.
+(C<dx>, C<dy>) are an offset into the hatch which can be used to hatch
+adjoining areas out of alignment, or to align the origin of a hatch
+with the the side of a filled area.
 
 
 =for comment
 From: File fills.c
 
-=item i_new_fill_hatchf(fg, bg, combine, hatch, cust_hatch, dx, dy)
+=item i_new_fill_hatchf(C<fg>, C<bg>, C<combine>, C<hatch>, C<cust_hatch>, C<dx>, C<dy>)
 
 
-Creates a new hatched fill with the fg color used for the 1 bits in
-the hatch and bg for the 0 bits.  If combine is non-zero alpha values
-will be combined.
+Creates a new hatched fill with the C<fg> color used for the 1 bits in
+the hatch and C<bg> for the 0 bits.  If C<combine> is non-zero alpha
+values will be combined.
 
-If cust_hatch is non-NULL it should be a pointer to 8 bytes of the
+If C<cust_hatch> is non-NULL it should be a pointer to 8 bytes of the
 hash definition, with the high-bits to the left.
 
-If cust_hatch is NULL then one of the standard hatches is used.
+If C<cust_hatch> is NULL then one of the standard hatches is used.
 
-(dx, dy) are an offset into the hatch which can be used to unalign adjoining areas, or to align the origin of a hatch with the the side of a filled area.
+(C<dx>, C<dy>) are an offset into the hatch which can be used to hatch
+adjoining areas out of alignment, or to align the origin of a hatch
+with the the side of a filled area.
 
 
 =for comment
 From: File fills.c
 
-=item i_new_fill_image(im, matrix, xoff, yoff, combine)
+=item i_new_fill_image(C<im>, C<matrix>, C<xoff>, C<yoff>, C<combine>)
 
 
 Create an image based fill.
 
 matrix is an array of 9 doubles representing a transformation matrix.
 
-xoff and yoff are the offset into the image to start filling from.
+C<xoff> and C<yoff> are the offset into the image to start filling from.
 
 
 =for comment
@@ -565,6 +886,14 @@ Create a solid fill based on a float color.
 If combine is non-zero then alpha values will be combined.
 
 
+=for comment
+From: File fills.c
+
+=item i_fill_destroy(fill)
+
+Call to destroy any fill object.
+
+
 =for comment
 From: File fills.c
 
@@ -575,10 +904,10 @@ From: File fills.c
 
 =over
 
-=item i_copy(src)
+=item i_copy(source)
 
 
-Creates a new image that is a copy of src.
+Creates a new image that is a copy of the image C<source>.
 
 Tags are not copied, only the image data.
 
@@ -588,36 +917,26 @@ Returns: i_img *
 =for comment
 From: File image.c
 
-=item i_copyto(dest, src, x1, y1, x2, y2, tx, ty)
-
-
-Copies image data from the area (x1,y1)-[x2,y2] in the source image to
-a rectangle the same size with it's top-left corner at (tx,ty) in the
-destination image.
-
-If x1 > x2 or y1 > y2 then the corresponding co-ordinates are swapped.
-
+=item i_copyto(C<dest>, C<src>, C<x1>, C<y1>, C<x2>, C<y2>, C<tx>, C<ty>)
 
-=for comment
-From: File image.c
-
-=item i_copyto_trans(im, src, x1, y1, x2, y2, tx, ty, trans)
 
+Copies image data from the area (C<x1>,C<y1>)-[C<x2>,C<y2>] in the
+source image to a rectangle the same size with it's top-left corner at
+(C<tx>,C<ty>) in the destination image.
 
-(x1,y1) (x2,y2) specifies the region to copy (in the source coordinates)
-(tx,ty) specifies the upper left corner for the target image.
-pass NULL in trans for non transparent i_colors.
+If C<x1> > C<x2> or C<y1> > C<y2> then the corresponding co-ordinates
+are swapped.
 
 
 =for comment
-From: File image.c
-
-=item i_img_destroy(im)
+From: File paste.im
 
+=item i_copyto_trans(C<im>, C<src>, C<x1>, C<y1>, C<x2>, C<y2>, C<tx>, C<ty>, C<trans>)
 
-Destroy image and free data via exorcise.
 
-   im - Image pointer
+(C<x1>,C<y1>) (C<x2>,C<y2>) specifies the region to copy (in the
+source coordinates) (C<tx>,C<ty>) specifies the upper left corner for
+the target image.  pass NULL in C<trans> for non transparent i_colors.
 
 
 =for comment
@@ -642,25 +961,25 @@ info is an array of 4 integers with the following values:
 =for comment
 From: File image.c
 
-=item i_rubthru(im, src, tx, ty, src_minx, src_miny, src_maxx, src_maxy )
+=item i_rubthru(C<im>, C<src>, C<tx>, C<ty>, C<src_minx>, C<src_miny>, C<src_maxx>, C<src_maxy>)
 
 
-Takes the sub image I<src[src_minx, src_maxx)[src_miny, src_maxy)> and
-overlays it at (I<tx>,I<ty>) on the image object.
+Takes the sub image C<src>[C<src_minx>, C<src_maxx>)[C<src_miny>, C<src_maxy>)> and
+overlays it at (C<tx>,C<ty>) on the image object.
 
-The alpha channel of each pixel in I<src> is used to control how much
-the existing colour in I<im> is replaced, if it is 255 then the colour
-is completely replaced, if it is 0 then the original colour is left 
+The alpha channel of each pixel in C<src> is used to control how much
+the existing color in C<im> is replaced, if it is 255 then the color
+is completely replaced, if it is 0 then the original color is left
 unmodified.
 
 
 =for comment
-From: File image.c
+From: File rubthru.im
 
 
 =back
 
-=head2 Image creation
+=head2 Image creation/destruction
 
 =over
 
@@ -678,6 +997,7 @@ From: File img16.c
 =item i_img_8_new(x, y, ch)
 
 
+
 Creates a new image object I<x> pixels wide, and I<y> pixels high with
 I<ch> channels.
 
@@ -687,25 +1007,26 @@ From: File image.c
 
 =item i_img_double_new(int x, int y, int ch)
 
-
 Creates a new double per sample image.
 
 
 =for comment
 From: File imgdouble.c
 
-=item i_img_pal_new(x, y, channels, maxpal)
+=item i_img_pal_new(C<x>, C<y>, C<channels>, C<maxpal>)
 
 
 Creates a new paletted image of the supplied dimensions.
 
+C<maxpal> is the maximum palette size and should normally be 256.
+
 Returns a new image or NULL on failure.
 
 
 =for comment
 From: File palimg.c
 
-=item i_sametype(i_img *im, int xsize, int ysize)
+=item i_sametype(C<im>, C<xsize>, C<ysize>)
 
 
 Returns an image of the same type (sample size, channels, paletted/direct).
@@ -716,7 +1037,7 @@ For paletted images the palette is copied from the source.
 =for comment
 From: File image.c
 
-=item i_sametype_chans(i_img *im, int xsize, int ysize, int channels)
+=item i_sametype_chans(C<im>, C<xsize>, C<ysize>, C<channels>)
 
 
 Returns an image of the same type (sample size).
@@ -724,6 +1045,159 @@ Returns an image of the same type (sample size).
 For paletted images the equivalent direct type is returned.
 
 
+=for comment
+From: File image.c
+
+=item i_img_destroy(C<img>)
+
+Destroy an image object
+
+
+=for comment
+From: File image.c
+
+
+=back
+
+=head2 Image Implementation
+
+=over
+
+=item i_img_alloc()
+
+Allocates a new i_img structure.
+
+When implementing a new image type perform the following steps in your
+image object creation function:
+
+=over
+
+=item 1.
+
+allocate the image with i_img_alloc().
+
+=item 2.
+
+initialize any function pointers or other data as needed, you can
+overwrite the whole block if you need to.
+
+=item 3.
+
+initialize Imager's internal data by calling i_img_init() on the image
+object.
+
+=back
+
+
+=for comment
+From: File image.c
+
+=item i_img_init(C<img>)
+
+Imager internal initialization of images.
+
+Currently this does very little, in the future it may be used to
+support threads, or color profiles.
+
+
+=for comment
+From: File image.c
+
+
+=back
+
+=head2 Image Information
+
+=over
+
+=item i_img_color_channels(C<im>)
+
+
+The number of channels holding color information.
+
+
+=for comment
+From: File immacros.h
+
+=item i_img_get_height(C<im>)
+
+Returns the height in pixels of the image.
+
+
+=for comment
+From: File image.c
+
+=item i_img_get_width(C<im>)
+
+Returns the width in pixels of the image.
+
+
+=for comment
+From: File image.c
+
+=item i_img_getchannels(C<im>)
+
+Get the number of channels in C<im>.
+
+
+=for comment
+From: File image.c
+
+=item i_img_getmask(C<im>)
+
+Get the image channel mask for C<im>.
+
+
+=for comment
+From: File image.c
+
+=item i_img_has_alpha(C<im>)
+
+
+Return true if the image has an alpha channel.
+
+
+=for comment
+From: File immacros.h
+
+=item i_img_is_monochrome(img, &zero_is_white)
+
+
+Tests an image to check it meets our monochrome tests.
+
+The idea is that a file writer can use this to test where it should
+write the image in whatever bi-level format it uses, eg. C<pbm> for
+C<pnm>.
+
+For performance of encoders we require monochrome images:
+
+=over
+
+=item *
+
+be paletted
+
+=item *
+
+have a palette of two colors, containing only C<(0,0,0)> and
+C<(255,255,255)> in either order.
+
+=back
+
+C<zero_is_white> is set to non-zero if the first palette entry is white.
+
+
+=for comment
+From: File image.c
+
+=item i_img_setmask(C<im>, C<ch_mask>)
+
+Set the image channel mask for C<im> to C<ch_mask>.
+
+The image channel mask gives some control over which channels can be
+written to in the image.
+
+
 =for comment
 From: File image.c
 
@@ -734,24 +1208,24 @@ From: File image.c
 
 =over
 
-=item i_quant_makemap(quant, imgs, count)
+=item i_quant_makemap(C<quant>, C<imgs>, C<count>)
 
 
-Analyzes the I<count> images in I<imgs> according to the rules in
-I<quant> to build a color map (optimal or not depending on
-quant->make_colors).
+Analyzes the C<count> images in C<imgs> according to the rules in
+C<quant> to build a color map (optimal or not depending on
+C<< quant->make_colors >>).
 
 
 =for comment
 From: File quant.c
 
-=item i_quant_translate(quant, img)
+=item i_quant_translate(C<quant>, C<img>)
 
 
-Quantize the image given the palette in quant.
+Quantize the image given the palette in C<quant>.
 
-On success returns a pointer to a memory block of img->xsize *
-img->ysize i_palidx entries.
+On success returns a pointer to a memory block of C<< img->xsize *
+img->ysize >> C<i_palidx> entries.
 
 On failure returns NULL.
 
@@ -764,19 +1238,54 @@ This function will fail if the supplied palette contains no colors.
 =for comment
 From: File quant.c
 
-=item i_quant_transparent(quant, data, img, trans_index)
+=item i_quant_transparent(C<quant>, C<data>, C<img>, C<trans_index>)
 
 
-Dither the alpha channel on I<img> into the palette indexes in
-I<data>.  Pixels to be transparent are replaced with I<trans_pixel>.
+Dither the alpha channel on C<img> into the palette indexes in
+C<data>.  Pixels to be transparent are replaced with C<trans_pixel>.
 
-The method used depends on the tr_* members of quant.
+The method used depends on the tr_* members of C<quant>.
 
 
 =for comment
 From: File quant.c
 
 
+=back
+
+=head2 Logging
+
+=over
+
+=item i_lhead(file, line)
+
+This is an internal function called by the mm_log() macro.
+
+
+=for comment
+From: File log.c
+
+=item i_loog(level, format, ...)
+
+This is an internal function called by the mm_log() macro.
+
+
+=for comment
+From: File log.c
+
+=item mm_log((level, format, ...))
+
+This is the main entry point to logging. Note that the extra set of
+parentheses are required due to limitations in C89 macros.
+
+This will format a string with the current file and line number to the
+log file if logging is enabled.
+
+
+=for comment
+From: File log.h
+
+
 =back
 
 =head2 Paletted images
@@ -860,7 +1369,7 @@ From: File imext.c
 
 Sets I<count> colors starting from I<index> in the image's palette.
 
-On sucess returns true.
+On success returns true.
 
 On failure returns false.
 
@@ -925,7 +1434,7 @@ From: File tags.c
 =item i_tags_find(tags, name, start, &entry)
 
 
-Searchs for a tag of the given I<name> starting from index I<start>.
+Searches for a tag of the given I<name> starting from index I<start>.
 
 On success returns true and sets *I<entry>.
 
@@ -938,7 +1447,7 @@ From: File tags.c
 =item i_tags_findn(tags, code, start, &entry)
 
 
-Searchs for a tag of the given I<code> starting from index I<start>.
+Searches for a tag of the given I<code> starting from index I<start>.
 
 On success returns true and sets *I<entry>.
 
@@ -1003,7 +1512,7 @@ On failure returns false.
 value_size must be at least large enough for a string representation
 of an integer.
 
-The copied value is always NUL terminated.
+The copied value is always C<NUL> terminated.
 
 
 =for comment
@@ -1026,9 +1535,13 @@ From: File tags.c
 
 =item i_tags_set(tags, name, data, size)
 
-
 Sets the given tag to the string I<data>
 
+If size is -1 then the strlen(I<data>) bytes are stored.
+
+Even on failure, if an existing tag I<name> exists, it will be
+removed.
+
 
 =for comment
 From: File tags.c
@@ -1064,16 +1577,42 @@ storage at the precision specified by C<places>.
 =for comment
 From: File tags.c
 
-=item i_tags_setn(tags, name, idata)
+=item i_tags_setn(C<tags>, C<name>, C<idata>)
 
+Sets the given tag to the integer C<idata>
 
-Sets the given tag to the integer I<idata>
+Even on failure, if an existing tag C<name> exists, it will be
+removed.
 
 
 =for comment
 From: File tags.c
 
 
+=back
+
+=head2 Uncategorized functions
+
+=over
+
+=item i_utf8_advance(char **p, size_t *len)
+
+Retrieve a C<UTF-8> character from the stream.
+
+Modifies *p and *len to indicate the consumed characters.
+
+This doesn't support the extended C<UTF-8> encoding used by later
+versions of Perl.
+
+This doesn't check that the C<UTF-8> character is using the shortest
+possible representation.
+
+
+=for comment
+From: File io.c
+
+
+
 =back