[rt #86659] PNG benign error support is more complex than a version check

[imager.git] / lib / Imager / APIRef.pod

Do not edit this file, it is generated automatically by apidocs.perl
from Imager's source files.

Each function description has a comment listing the source file where
you can find the documentation.

=head1 NAME

Imager::APIRef - Imager's C API - reference.

=head1 SYNOPSIS

  i_color color;
  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, y;
  printf("left %" i_DF "\n", i_DFc(x));
  printf("point (" i_DFp ")\n", i_DFcp(x, y));

  # 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_circle_aa(im, 50, 50, 45, &color);
  i_box(im, 0, 0, im->xsize-1, im->ysize-1, &color).
  i_box_filled(im, 0, 0, im->xsize-1, im->ysize-1, &color);
  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
  im_clear_error(aIMCTX);
  i_clear_error();
  i_push_error(0, "Yep, it's broken");
  i_push_error(errno, "Error writing");
  im_push_error(aIMCTX, 0, "Something is wrong");
  va_args args;
  va_start(args, lastarg);
  im_push_errorvf(ctx, code, format, args);
  i_push_errorf(errno, "Cannot open file %s: %d", filename, errno);
  im_push_errorf(aIMCTX, errno, "Cannot open file %s: %d", filename, errno);

  # Files
  im_set_image_file_limits(aIMCTX, 500, 500, 1000000);
  i_set_image_file_limits(500, 500, 1000000);
  im_get_image_file_limits(aIMCTX, &width, &height, &bytes)
  i_get_image_file_limits(&width, &height, &bytes)
  im_int_check_image_file_limits(aIMCTX, width, height, channels, sizeof(i_sample_t))
  i_int_check_image_file_limits(width, height, channels, sizeof(i_sample_t))

  # 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);

  # I/O Layers
  ssize_t count = i_io_peekn(ig, buffer, sizeof(buffer));
  ssize_t result = i_io_write(io, buffer, size)
  char buffer[BUFSIZ]
  ssize_t len = i_io_gets(buffer, sizeof(buffer), '\n');
  io_glue_destroy(ig);

  # Image

  # Image creation/destruction
  i_img *img = i_sametype(src, width, height);
  i_img *img = i_sametype_chans(src, width, height, channels);
  i_img *img = im_img_16_new(aIMCTX, width, height, channels);
  i_img *img = i_img_16_new(width, height, channels);
  i_img *img = im_img_8_new(aIMCTX, width, height, channels);
  i_img *img = i_img_8_new(width, height, channels);
  i_img *img = im_img_double_new(aIMCTX, width, height, channels);
  i_img *img = i_img_double_new(width, height, channels);
  i_img *img = im_img_pal_new(aIMCTX, width, height, channels, max_palette_size)
  i_img *img = i_img_pal_new(width, height, channels, max_palette_size)
  i_img_destroy(img)

  # Image Implementation
  i_img *im = im_img_alloc(aIMCTX);
  i_img *im = i_img_alloc();
  im_img_init(aIMCTX, im);
  i_img_init(im);

  # Image Information
  // only channel 0 writable 
  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

  # Mutex functions
  i_mutex_t m = i_mutex_new();
  i_mutex_destroy(m);
  i_mutex_lock(m);
  i_mutex_unlock(m);

  # Paletted images

  # Tags
  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

  i_img *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.

=item *

i_f_psamp - implements psamp() for this image.

=item *

i_f_psampf - implements psamp() for this image.

=item *

C<im_data> - image specific data internal to Imager.

=item *

C<context> - the Imager API context this image belongs to.

=back


=for comment
From: File imdatatypes.h

=item i_color

  i_color black;
  black.rgba.r = black.rgba.g = black.rgba.b = black.rgba.a = 0;

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

  i_fill_t *fill;

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

  i_img_dim x, y;

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

=item i_DF

  printf("left %" i_DF "\n", i_DFc(x));

This is a constant string that can be used with functions like
printf() to format i_img_dim values after they're been cast with i_DFc().

Does not include the leading C<%>.


=for comment
From: File imdatatypes.h

=item i_DFc

Cast an C<i_img_dim> value to a type for use with the i_DF format
string.


=for comment
From: File imdatatypes.h

=item i_DFcp

Casts two C<i_img_dim> values for use with the i_DF (or i_DFp) format.


=for comment
From: File imdatatypes.h

=item i_DFp

  printf("point (" i_DFp ")\n", i_DFcp(x, y));

Format a pair of C<i_img_dim> values.  This format string I<does>
include the leading C<%>.


=for comment
From: File imdatatypes.h


=back

=head2 Drawing

=over

=item i_arc(im, x, y, rad, d1, d2, color)


  i_arc(im, 50, 50, 20, 45, 135, &color);

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.


=for comment
From: File draw.c

=item i_arc_aa(im, x, y, rad, d1, d2, color)


  i_arc_aa(im, 50, 50, 35, 90, 135, &color);

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.


=for comment
From: File draw.c

=item i_arc_aa_cfill(im, x, y, rad, d1, d2, fill)


  i_arc_aa_cfill(im, 50, 50, 35, 90, 135, fill);

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.


=for comment
From: File draw.c

=item i_arc_cfill(im, x, y, rad, d1, d2, fill)


  i_arc_cfill(im, 50, 50, 35, 90, 135, fill);

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.


=for comment
From: File draw.c

=item i_box(im, x1, y1, x2, y2, color)


  i_box(im, 0, 0, im->xsize-1, im->ysize-1, &color).

Outlines the box from (x1,y1) to (x2,y2) inclusive with I<color>.


=for comment
From: File draw.c

=item i_box_cfill(im, x1, y1, x2, y2, fill)


  i_box_cfill(im, 0, 0, im->xsize-1, im->ysize-1, fill);

Fills the box from (x1,y1) to (x2,y2) inclusive with fill.


=for comment
From: File draw.c

=item i_box_filled(im, x1, y1, x2, y2, color)


  i_box_filled(im, 0, 0, im->xsize-1, im->ysize-1, &color);

Fills the box from (x1,y1) to (x2,y2) inclusive with color.


=for comment
From: File draw.c

=item i_circle_aa(im, x, y, rad, color)


  i_circle_aa(im, 50, 50, 45, &color);

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(C<im>, C<seedx>, C<seedy>, C<fill>)


  i_flood_cfill(im, 50, 50, fill);

Flood fills the 4-connected region starting from the point (C<seedx>,
C<seedy>) with C<fill>.

Returns false if (C<seedx>, C<seedy>) are outside the image.


=for comment
From: File draw.c

=item i_flood_cfill_border(C<im>, C<seedx>, C<seedy>, C<fill>, C<border>)


  i_flood_cfill_border(im, 50, 50, fill, 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 (C<seedx>, C<seedy>) are outside the image.


=for comment
From: File draw.c

=item i_flood_fill(C<im>, C<seedx>, C<seedy>, C<color>)


  i_flood_fill(im, 50, 50, &color);

Flood fills the 4-connected region starting from the point (C<seedx>,
C<seedy>) with I<color>.

Returns false if (C<seedx>, C<seedy>) are outside the image.


=for comment
From: File draw.c

=item i_flood_fill_border(C<im>, C<seedx>, C<seedy>, C<color>, C<border>)


  i_flood_fill_border(im, 50, 50, &color, &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 (C<seedx>, C<seedy>) are outside the image.


=for comment
From: File draw.c

=item i_glin(im, l, r, y, colors)


Retrieves (r-l) pixels starting from (l,y) into I<colors>.

Returns the number of pixels retrieved.


=for comment
From: File imext.c

=item i_glinf(im, l, r, y, colors)


Retrieves (r-l) pixels starting from (l,y) into I<colors> as floating
point colors.

Returns the number of pixels retrieved.


=for comment
From: File imext.c

=item i_gpal(im, left, right, y, indexes)


Reads palette indexes for the horizontal line (left, y) to (right-1,
y) into C<indexes>.

Returns the number of indexes read.

Always returns 0 for direct color images.


=for comment
From: File imext.c

=item i_gpix(im, C<x>, C<y>, C<color>)


Retrieves the C<color> of the pixel (x,y).

Returns 0 if the pixel was retrieved, or -1 if not.


=for comment
From: File imext.c

=item i_gpixf(im, C<x>, C<y>, C<fcolor>)


Retrieves the color of the pixel (x,y) as a floating point color into
C<fcolor>.

Returns 0 if the pixel was retrieved, or -1 if not.


=for comment
From: File imext.c

=item i_gsamp(im, left, right, y, samples, channels, channel_count)


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 channels is NULL then the first channels_count channels are retrieved for
each pixel.

Returns the number of samples read (which should be (right-left) *
channel_count)


=for comment
From: File imext.c

=item i_gsamp_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_gsamp_bits(im, left, right, y, samples, channels, channel_count, bits)

Reads integer samples scaled to C<bits> bits of precision into the
C<unsigned int> array C<samples>.

Expect this to be slow unless C<< bits == im->bits >>.

Returns the number of samples copied, or -1 on error.

Not all image types implement this method.

Pushes errors, but does not call C<i_clear_error()>.


=for comment
From: File imext.c

=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_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 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
   color - color to write to image
   endp  - endpoint flag (boolean)


=for comment
From: File draw.c

=item i_line_aa(C<im>, C<x1>, C<x2>, C<y1>, C<y2>, C<color>, C<endp>)


Anti-alias draws a line from (x1,y1) to (x2, y2) in color.

The point (x2, y2) is drawn only if C<endp> is set.


=for comment
From: File draw.c

=item i_plin(im, l, r, y, colors)


Sets (r-l) pixels starting from (l,y) using (r-l) values from
I<colors>.

Returns the number of pixels set.


=for comment
From: File imext.c

=item i_plinf(im, C<left>, C<right>, C<fcolors>)


Sets (right-left) pixels starting from (left,y) using (right-left)
floating point colors from C<fcolors>.

Returns the number of pixels set.


=for comment
From: File imext.c

=item i_ppal(im, left, right, y, indexes)


Writes palette indexes for the horizontal line (left, y) to (right-1,
y) from C<indexes>.

Returns the number of indexes written.

Always returns 0 for direct color images.


=for comment
From: File imext.c

=item i_ppix(im, x, y, color)


Sets the pixel at (x,y) to I<color>.

Returns 0 if the pixel was drawn, or -1 if not.

Does no alpha blending, just copies the channels from the supplied
color to the image.


=for comment
From: File imext.c

=item i_ppixf(im, C<x>, C<y>, C<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.

Does no alpha blending, just copies the channels from the supplied
color to the image.


=for comment
From: File imext.c

=item i_psamp(im, left, right, y, samples, channels, channel_count)

Writes sample values from C<samples> to C<im> for the horizontal line
(left, y) to (right-1, y) inclusive for the channels specified by
C<channels>, an array of C<int> with C<channel_count> elements.

If C<channels> is C<NULL> then the first C<channels_count> channels
are written to for each pixel.

Returns the number of samples written, which should be (right - left)
* channel_count.  If a channel not in the image is in channels, left
is negative, left is outside the image or y is outside the image,
returns -1 and pushes an error.


=for comment
From: File immacros.h

=item i_psamp_bits(im, left, right, y, samples, channels, channel_count, bits)

Writes integer samples scaled to C<bits> bits of precision from the
C<unsigned int> array C<samples>.

Expect this to be slow unless C<< bits == im->bits >>.

Returns the number of samples copied, or -1 on error.

Not all image types implement this method.

Pushes errors, but does not call C<i_clear_error()>.


=for comment
From: File imext.c

=item i_psampf(im, left, right, y, samples, channels, channel_count)

Writes floating point sample values from C<samples> to C<im> for the
horizontal line (left, y) to (right-1, y) inclusive for the channels
specified by C<channels>, an array of C<int> with C<channel_count>
elements.

If C<channels> is C<NULL> then the first C<channels_count> channels
are written to for each pixel.

Returns the number of samples written, which should be (right - left)
* channel_count.  If a channel not in the image is in channels, left
is negative, left is outside the image or y is outside the image,
returns -1 and pushes an error.


=for comment
From: File immacros.h


=back

=head2 Error handling

=over

=item i_push_errorf(int code, char const *fmt, ...)

  i_push_errorf(errno, "Cannot open file %s: %d", filename, errno);

A version of i_push_error() that does printf() like formatting.

Does not support perl specific format codes.


=for comment
From: File error.c

=item im_clear_error(ctx)
X<im_clear_error API>X<i_clear_error API>

  im_clear_error(aIMCTX);
  i_clear_error();

Clears the error stack.

Called by any Imager function before doing any other processing.

Also callable as C<i_clear_error()>.


=for comment
From: File error.c

=item im_push_error(ctx, code, message)
X<im_push_error API>X<i_push_error API>

  i_push_error(0, "Yep, it's broken");
  i_push_error(errno, "Error writing");
  im_push_error(aIMCTX, 0, "Something is wrong");

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
error handling is calling function that does.).


=for comment
From: File error.c

=item im_push_errorf(ctx, code, char const *fmt, ...)

  im_push_errorf(aIMCTX, errno, "Cannot open file %s: %d", filename, errno);

A version of im_push_error() that does printf() like formatting.

Does not support perl specific format codes.


=for comment
From: File error.c

=item im_push_errorvf(ctx, code, format, args)
X<im_push_error_vf API>X<i_push_errorvf API>

  va_args args;
  va_start(args, lastarg);
  im_push_errorvf(ctx, code, format, args);

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.

Also callable as C<i_push_errorvf(code, format, args)>


=for comment
From: File error.c


=back

=head2 Files

=over

=item i_get_file_background(im, &bg)


Retrieve the file write background color tag from the image.

If not present, C<bg> is set to black.

Returns 1 if the C<i_background> tag was found and valid.


=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, C<bg> is set to black.

Returns 1 if the C<i_background> tag was found and valid.


=for comment
From: File image.c

=item im_get_image_file_limits(ctx, &width, &height, &bytes)
X<im_get_image_file_limits API>X<i_get_image_file_limits>

  im_get_image_file_limits(aIMCTX, &width, &height, &bytes)
  i_get_image_file_limits(&width, &height, &bytes)

Retrieves the file limits set by i_set_image_file_limits().

=over

=item *

i_img_dim *width, *height - the maximum width and height of the image.

=item *

size_t *bytes - size in memory of the image in bytes.

=back

Also callable as C<i_get_image_file_limits(&width, &height, &bytes)>.


=for comment
From: File limits.c

=item im_int_check_image_file_limits(width, height, channels, sample_size)
X<im_int_check_image_file_limits API>X<i_int_check_image_file_limits>

  im_int_check_image_file_limits(aIMCTX, width, height, channels, sizeof(i_sample_t))
  i_int_check_image_file_limits(width, height, channels, sizeof(i_sample_t))

Checks the size of a file in memory against the configured image file
limits.

This also range checks the values to those permitted by Imager and
checks for overflows in calculating the size.

Returns non-zero if the file is within limits.

This function is intended to be called by image file read functions.

Also callable as C<i_int_check_image_file_limits(width, height, channels, sizeof(i_sample_t)>.


=for comment
From: File limits.c

=item im_set_image_file_limits(ctx, width, height, bytes)
X<im_set_image_file_limits API>X<i_set_image_file_limits API>

  im_set_image_file_limits(aIMCTX, 500, 500, 1000000);
  i_set_image_file_limits(500, 500, 1000000);

Set limits on the sizes of images read by Imager.

Setting a limit to 0 means that limit is ignored.

Negative limits result in failure.

Parameters:

=over

=item *

i_img_dim width, height - maximum width and height.

=item *

size_t bytes - maximum size in memory in bytes.  A value of zero sets
this limit to one gigabyte.

=back

Returns non-zero on success.

Also callable as C<i_set_image_file_limits(width, height, bytes)>.


=for comment
From: File limits.c


=back

=head2 Fills

=over

=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>)


  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);


Creates a new general fill which fills with a fountain fill.


=for comment
From: File filters.im

=item i_new_fill_hatch(C<fg>, C<bg>, C<combine>, C<hatch>, C<cust_hatch>, C<dx>, C<dy>)


  i_fill_t *fill = i_new_fill_hatch(&fg_color, &bg_color, combine, hatch, custom_hatch, dx, dy);

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 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 C<cust_hatch> is NULL then one of the standard hatches is used.

(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(C<fg>, C<bg>, C<combine>, C<hatch>, C<cust_hatch>, C<dx>, C<dy>)


  i_fill_t *fill = i_new_fill_hatchf(&fg_fcolor, &bg_fcolor, combine, hatch, custom_hatch, dx, dy);

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 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 C<cust_hatch> is NULL then one of the standard hatches is used.

(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(C<im>, C<matrix>, C<xoff>, C<yoff>, C<combine>)


  i_fill_t *fill = i_new_fill_image(src_img, matrix, x_offset, y_offset, combine);

Create an image based fill.

matrix is an array of 9 doubles representing a transformation matrix.

C<xoff> and C<yoff> are the offset into the image to start filling from.


=for comment
From: File fills.c

=item i_new_fill_solid(color, combine)


  i_fill_t *fill = i_new_fill_solid(&color, combine);

Create a solid fill based on an 8-bit color.

If combine is non-zero then alpha values will be combined.


=for comment
From: File fills.c

=item i_new_fill_solidf(color, combine)


  i_fill_t *fill = i_new_fill_solidf(&fcolor, combine);

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)

  i_fill_destroy(fill);

Call to destroy any fill object.


=for comment
From: File fills.c


=back

=head2 I/O Layers

=over

=item im_io_new_bufchain(ctx)
X<im_io_new_bufchain API>X<i_io_new_bufchain API>

Returns a new io_glue object that has the 'empty' source and but can
be written to and read from later (like a pseudo file).

Also callable as C<io_new_bufchain()>.


=for comment
From: File iolayer.c

=item im_io_new_buffer(ctx, data, length)
X<im_io_new_buffer API>X<io_new_buffer API>

Returns a new io_glue object that has the source defined as reading
from specified buffer.  Note that the buffer is not copied.

   ctx - an Imager context object
   data - buffer to read from
   length - length of buffer

Also callable as C<io_new_buffer(data, length>.


=for comment
From: File iolayer.c

=item im_io_new_cb(ctx, p, read_cb, write_cb, seek_cb, close_cb, destroy_cb)
X<im_io_new_cb API>X<io_new_cb API>

Create a new I/O layer object that calls your supplied callbacks.

In general the callbacks should behave like the corresponding POSIX
primitives.

=over

=item *

C<read_cb>(p, buffer, length) should read up to C<length> bytes into
C<buffer> and return the number of bytes read.  At end of file, return
0.  On error, return -1.

=item *

C<write_cb>(p, buffer, length) should write up to C<length> bytes from
C<buffer> and return the number of bytes written.  A return value <= 0
will be treated as an error.

=item *

C<seekcb>(p, offset, whence) should seek and return the new offset.

=item *

C<close_cb>(p) should return 0 on success, -1 on failure.

=item *

C<destroy_cb>(p) should release any memory specific to your callback
handlers.

=back

Also callable as C<io_new_cb(p, readcb, writecb, seekcb, closecb,
destroycb)>.


=for comment
From: File iolayer.c

=item im_io_new_fd(ctx, file)
X<io_new_fd API>X<im_io_new_fd API>

Returns a new io_glue object that has the source defined as reading
from specified file descriptor.  Note that the the interface to receiving
data from the io_glue callbacks hasn't been done yet.

  ctx - and Imager context object
  file - file descriptor to read/write from

Also callable as C<io_new_fd(file)>.


=for comment
From: File iolayer.c

=item i_io_close(io)

Flush any pending output and perform the close action for the stream.

Returns 0 on success.


=for comment
From: File iolayer.c

=item i_io_flush(io)

Flush any buffered output.

Returns true on success,


=for comment
From: File iolayer.c

=item i_io_getc(ig)

A macro to read a single byte from a buffered I/O glue object.

Returns EOF on failure, or a byte.


=for comment
From: File iolayer.c

=item i_io_gets(ig, buffer, size, end_of_line)

  char buffer[BUFSIZ]
  ssize_t len = i_io_gets(buffer, sizeof(buffer), '\n');

Read up to C<size>-1 bytes from the stream C<ig> into C<buffer>.

If the byte C<end_of_line> is seen then no further bytes will be read.

Returns the number of bytes read.

Always C<NUL> terminates the buffer.


=for comment
From: File iolayer.c

=item i_io_peekc(ig)

Read the next character from the stream without advancing the stream.

On error or end of file, return EOF.

For unbuffered streams a single character buffer will be setup.


=for comment
From: File iolayer.c

=item i_io_peekn(ig, buffer, size)

  ssize_t count = i_io_peekn(ig, buffer, sizeof(buffer));

Buffer at least C<size> (at most C<< ig->buf_size >> bytes of data
from the stream and return C<size> bytes of it to the caller in
C<buffer>.

This ignores the buffered state of the stream, and will always setup
buffering if needed.

If no C<type> parameter is provided to Imager::read() or
Imager::read_multi(), Imager will call C<i_io_peekn()> when probing
for the file format.

Returns -1 on error, 0 if there is no data before EOF, or the number
of bytes read into C<buffer>.


=for comment
From: File iolayer.c

=item i_io_putc(ig, c)

Write a single character to the stream.

On success return c, on error returns EOF


=for comment
From: File iolayer.c

=item i_io_read(io, buffer, size)

Read up to C<size> bytes from the stream C<io> into C<buffer>.

Returns the number of bytes read.  Returns 0 on end of file.  Returns
-1 on error.


=for comment
From: File iolayer.c

=item i_io_seek(io, offset, whence)

Seek within the stream.

Acts like perl's seek.


=for comment
From: File iolayer.c

=item i_io_set_buffered(io, buffered)

Set the buffering mode of the stream.

If you switch buffering off on a stream with buffering on:

=over

=item *

any buffered output will be flushed.

=item *

any existing buffered input will be consumed before reads become
unbuffered.

=back

Returns true on success.  This may fail if any buffered output cannot
be flushed.


=for comment
From: File iolayer.c

=item i_io_write(io, buffer, size)

  ssize_t result = i_io_write(io, buffer, size)

Write to the given I/O stream.

Returns the number of bytes written.


=for comment
From: File iolayer.c

=item io_slurp(ig, c)
X<io_slurp API>

Takes the source that the io_glue is bound to and allocates space for
a return buffer and returns the entire content in a single buffer.
Note: This only works for io_glue objects created by
io_new_bufchain().  It is useful for saving to scalars and such.

   ig - io_glue object
   c  - pointer to a pointer to where data should be copied to

  char *data;
  size_t size = io_slurp(ig, &data);
  ... do something with the data ...
  myfree(data);

io_slurp() will abort the program if the supplied I/O layer is not
from io_new_bufchain().


=for comment
From: File iolayer.c

=item io_glue_destroy(ig)
X<io_glue_destroy API>

  io_glue_destroy(ig);

Destroy an io_glue objects.  Should clean up all related buffers.

   ig - io_glue object to destroy.


=for comment
From: File iolayer.c


=back

=head2 Image

=over

=item i_copy(source)


Creates a new image that is a copy of the image C<source>.

Tags are not copied, only the image data.

Returns: i_img *


=for comment
From: File image.c

=item i_copyto(C<dest>, C<src>, C<x1>, C<y1>, C<x2>, C<y2>, C<tx>, C<ty>)


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.

If C<x1> > C<x2> or C<y1> > C<y2> then the corresponding co-ordinates
are swapped.


=for comment
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>)


(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
From: File image.c

=item i_img_info(im, info)


Return image information

   im - Image pointer
   info - pointer to array to return data

info is an array of 4 integers with the following values:

 info[0] - width
 info[1] - height
 info[2] - channels
 info[3] - channel mask


=for comment
From: File image.c

=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 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 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 rubthru.im


=back

=head2 Image creation/destruction

=over

=item i_sametype(C<im>, C<xsize>, C<ysize>)


  i_img *img = i_sametype(src, width, height);

Returns an image of the same type (sample size, channels, paletted/direct).

For paletted images the palette is copied from the source.


=for comment
From: File image.c

=item i_sametype_chans(C<im>, C<xsize>, C<ysize>, C<channels>)


  i_img *img = i_sametype_chans(src, width, height, channels);

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 im_img_16_new(ctx, x, y, ch)
X<im_img_16_new API>X<i_img_16_new API>

  i_img *img = im_img_16_new(aIMCTX, width, height, channels);
  i_img *img = i_img_16_new(width, height, channels);

Create a new 16-bit/sample image.

Returns the image on success, or NULL on failure.

Also callable as C<i_img_16_new(x, y, ch)>


=for comment
From: File img16.c

=item im_img_8_new(ctx, x, y, ch)
X<im_img_8_new API>X<i_img_8_new API>

  i_img *img = im_img_8_new(aIMCTX, width, height, channels);
  i_img *img = i_img_8_new(width, height, channels);

Creates a new image object I<x> pixels wide, and I<y> pixels high with
I<ch> channels.


=for comment
From: File img8.c

=item im_img_double_new(ctx, x, y, ch)
X<im_img_double_new API>X<i_img_double_new API>

  i_img *img = im_img_double_new(aIMCTX, width, height, channels);
  i_img *img = i_img_double_new(width, height, channels);

Creates a new double per sample image.

Also callable as C<i_img_double_new(width, height, channels)>.


=for comment
From: File imgdouble.c

=item im_img_pal_new(ctx, C<x>, C<y>, C<channels>, C<maxpal>)
X<im_img_pal_new API>X<i_img_pal_new API>

  i_img *img = im_img_pal_new(aIMCTX, width, height, channels, max_palette_size)
  i_img *img = i_img_pal_new(width, height, channels, max_palette_size)

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.

Also callable as C<i_img_pal_new(width, height, channels, max_palette_size)>.


=for comment
From: File palimg.c

=item i_img_destroy(C<img>)

  i_img_destroy(img)

Destroy an image object


=for comment
From: File image.c


=back

=head2 Image Implementation

=over

=item im_img_alloc(aIMCTX)
X<im_img_alloc API>X<i_img_alloc API>

  i_img *im = im_img_alloc(aIMCTX);
  i_img *im = 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 im_img_init(aIMCTX, image)
X<im_img_init API>X<i_img_init API>

  im_img_init(aIMCTX, im);
  i_img_init(im);

Imager internal initialization of images.

See L</im_img_alloc(aIMCTX)> for more information.


=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>)

  i_img_dim height = i_img_get_height(im);

Returns the height in pixels of the image.


=for comment
From: File image.c

=item i_img_get_width(C<im>)

  i_img_dim width = i_img_get_width(im);

Returns the width in pixels of the image.


=for comment
From: File image.c

=item i_img_getchannels(C<im>)

  int channels = i_img_getchannels(img);

Get the number of channels in C<im>.


=for comment
From: File image.c

=item i_img_getmask(C<im>)

  int mask = i_img_getmask(img);

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>)

  // only channel 0 writable 
  i_img_setmask(img, 0x01);

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


=back

=head2 Image quantization

=over

=item i_quant_makemap(C<quant>, C<imgs>, C<count>)


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(C<quant>, C<img>)


Quantize the image given the palette in C<quant>.

On success returns a pointer to a memory block of C<< img->xsize *
img->ysize >> C<i_palidx> entries.

On failure returns NULL.

You should call myfree() on the returned block when you're done with
it.

This function will fail if the supplied palette contains no colors.


=for comment
From: File quant.c

=item i_quant_transparent(C<quant>, C<data>, C<img>, C<trans_index>)


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 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


=back

=head2 Mutex functions

=over

=item i_mutex_new()

  i_mutex_t m = i_mutex_new();

Create a mutex.

If a critical section cannot be created for whatever reason, Imager
will abort.


=for comment
From: File mutexwin.c

=item i_mutex_destroy(m)

  i_mutex_destroy(m);

Destroy a mutex.


=for comment
From: File mutexwin.c

=item i_mutex_lock(m)

  i_mutex_lock(m);

Lock the mutex, waiting if another thread has the mutex locked.


=for comment
From: File mutexwin.c

=item i_mutex_unlock(m)

  i_mutex_unlock(m);

Release the mutex.

The behavior of releasing a mutex you don't hold is unspecified.


=for comment
From: File mutexwin.c


=back

=head2 Paletted images

=over

=item i_addcolors(im, colors, count)


Adds colors to the image's palette.

On success returns the index of the lowest color added.

On failure returns -1.

Always fails for direct color images.


=for comment
From: File imext.c

=item i_colorcount(im)


Returns the number of colors in the image's palette.

Returns -1 for direct images.


=for comment
From: File imext.c

=item i_findcolor(im, color, &entry)


Searches the images palette for the given color.

On success sets *I<entry> to the index of the color, and returns true.

On failure returns false.

Always fails on direct color images.


=for comment
From: File imext.c

=item i_getcolors(im, index, colors, count)


Retrieves I<count> colors starting from I<index> in the image's
palette.

On success stores the colors into I<colors> and returns true.

On failure returns false.

Always fails for direct color images.

Fails if there are less than I<index>+I<count> colors in the image's
palette.


=for comment
From: File imext.c

=item i_maxcolors(im)


Returns the maximum number of colors the palette can hold for the
image.

Returns -1 for direct color images.


=for comment
From: File imext.c

=item i_setcolors(im, index, colors, count)


Sets I<count> colors starting from I<index> in the image's palette.

On success returns true.

On failure returns false.

The image must have at least I<index>+I<count> colors in it's palette
for this to succeed.

Always fails on direct color images.


=for comment
From: File imext.c


=back

=head2 Tags

=over

=item i_tags_delbycode(tags, code)


Delete any tags with the given code.

Returns the number of tags deleted.


=for comment
From: File tags.c

=item i_tags_delbyname(tags, name)


Delete any tags with the given name.

Returns the number of tags deleted.


=for comment
From: File tags.c

=item i_tags_delete(tags, index)


Delete a tag by index.

Returns true on success.


=for comment
From: File tags.c

=item i_tags_destroy(tags)


Destroys the given tags structure.  Called by i_img_destroy().


=for comment
From: File tags.c

=item i_tags_find(tags, name, start, &entry)


Searches for a tag of the given I<name> starting from index I<start>.

On success returns true and sets *I<entry>.

On failure returns false.


=for comment
From: File tags.c

=item i_tags_findn(tags, code, start, &entry)


Searches for a tag of the given I<code> starting from index I<start>.

On success returns true and sets *I<entry>.

On failure returns false.


=for comment
From: File tags.c

=item i_tags_get_color(tags, name, code, &value)


Retrieve a tag specified by name or code as color.

On success sets the i_color *I<value> to the color and returns true.

On failure returns false.


=for comment
From: File tags.c

=item i_tags_get_float(tags, name, code, value)


Retrieves a tag as a floating point value.  

If the tag has a string value then that is parsed as a floating point
number, otherwise the integer value of the tag is used.

On success sets *I<value> and returns true.

On failure returns false.


=for comment
From: File tags.c

=item i_tags_get_int(tags, name, code, &value)


Retrieve a tag specified by name or code as an integer.

On success sets the int *I<value> to the integer and returns true.

On failure returns false.


=for comment
From: File tags.c

=item i_tags_get_string(tags, name, code, value, value_size)


Retrieves a tag by name or code as a string.

On success copies the string to value for a max of value_size and
returns true.

On failure returns false.

value_size must be at least large enough for a string representation
of an integer.

The copied value is always C<NUL> terminated.


=for comment
From: File tags.c

=item i_tags_new(i_img_tags *tags)


Initialize a tags structure.  Should not be used if the tags structure
has been previously used.

This should be called tags member of an i_img object on creation (in
i_img_*_new() functions).

To destroy the contents use i_tags_destroy()


=for comment
From: File tags.c

=item i_tags_set(tags, name, data, size)

  i_tags_set(&img->tags, "i_comment", -1);

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

=item i_tags_set_color(tags, name, code, &value)


Stores the given color as a tag with the given name and code.


=for comment
From: File tags.c

=item i_tags_set_float(tags, name, code, value)


Equivalent to i_tags_set_float2(tags, name, code, value, 30).


=for comment
From: File tags.c

=item i_tags_set_float2(tags, name, code, value, places)


Sets the tag with the given name and code to the given floating point
value.

Since tags are strings or ints, we convert the value to a string before
storage at the precision specified by C<places>.


=for comment
From: File tags.c

=item i_tags_setn(C<tags>, C<name>, C<idata>)

  i_tags_setn(&img->tags, "i_xres", 204);
  i_tags_setn(&img->tags, "i_yres", 196);

Sets the given tag to the integer C<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.  Since this is typically used to implement text
output by font drivers, the strings supplied shouldn't have such out
of range characters.

This doesn't check that the C<UTF-8> character is using the shortest
possible representation.

Returns ~0UL on failure.


=for comment
From: File io.c

=item im_context_refdec(ctx, where)
X<im_context_refdec API>
=section Context objects

  im_context_refdec(aIMCTX, "a description");

Remove a reference to the context, releasing it if all references have
been removed.


=for comment
From: File context.c

=item im_context_refinc(ctx, where)
X<im_context_refinc API>
=section Context objects

  im_context_refinc(aIMCTX, "a description");

Add a new reference to the context.


=for comment
From: File context.c

=item im_context_slot_get(ctx, slot)

Retrieve the value previously stored in the given slot of the context
object.


=for comment
From: File context.c

=item im_context_slot_new(destructor)

Allocate a new context-local-storage slot.

C<desctructor> will be called when the context is destroyed if the
corresponding slot is non-NULL.


=for comment
From: File context.c

=item im_context_slot_set(slot, value)

Set the value of a slot.

Returns true on success.

Aborts if the slot supplied is invalid.

If reallocation of slot storage fails, returns false.


=for comment
From: File context.c

=item im_errors(ctx)

  i_errmsg *errors = im_errors(aIMCTX);
  i_errmsg *errors = i_errors();

Returns a pointer to the first element of an array of error messages,
terminated by a NULL pointer.  The highest level message is first.

Also callable as C<i_errors()>.


=for comment
From: File error.c

=item im_get_context()

Retrieve the context object for the current thread.

Inside Imager itself this is just a function pointer, which the
F<Imager.xs> BOOT handler initializes for use within perl.  If you're
taking the Imager code and embedding it elsewhere you need to
initialize the C<im_get_context> pointer at some point.


=for comment
From: File imext.c



=back


=head1 UNDOCUMENTED

The following API functions are undocumented so far, hopefully this
will change:

=over

=item *

B<im_lhead>

=item *

B<im_loog>

=item *

B<mm_log>



=back


=head1 AUTHOR

Tony Cook <tonyc@cpan.org>

=head1 SEE ALSO

Imager, Imager::API, Imager::ExtUtils, Imager::Inline

=cut