=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;
+ 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_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_destroy(fill);
- 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_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);
- i_fill_t *fill = i_new_fill_solid(&color, combine);
- i_fill_t *fill = i_new_fill_solidf(&fcolor, 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
+ # 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 creation
- i_img *img = i_img_16_new(width, height, channels);
+ # 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 = i_img_16_new(width, height, channels);
i_img *img = i_img_8_new(width, height, channels);
- i_img_destroy(img)
i_img *img = i_img_double_new(width, height, channels);
i_img *img = i_img_pal_new(width, height, channels, max_palette_size)
- i_img *img = i_sametype(src, width, height);
- i_img *img = i_sametype_chans(src, width, height, channels);
+ i_img_destroy(img)
# Image Implementation
+ # 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
# 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:
=item *
-channels - the number of channels in the image
+C<channels> - the number of channels in the image
=item *
-xsize, ysize - the width and height of the image in pixels
+C<xsize>, C<ysize> - the width and height of the image in pixels
=item *
-bytes - the number of bytes used to store the image data. Undefined
+C<bytes> - the number of bytes used to store the image data. Undefined
where virtual is non-zero.
=item *
-ch_mask - a mask of writable channels. eg. if this is 6 then only
+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 *
-bits - the number of bits stored per sample. Should be one of
+C<bits> - the number of bits stored per sample. Should be one of
i_8_bits, i_16_bits, i_double_bits.
=item *
-type - either i_direct_type for direct color images, or i_palette_type
+C<type> - either i_direct_type for direct color images, or i_palette_type
for paletted images.
=item *
-virtual - if zero then this image is-self contained. If non-zero then
-this image could be an interface to some other implementation.
+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 *
-idata - the image data. This should not be directly accessed. A new
+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 *
-tags - a structure storing the image's tags. This should only be
+C<tags> - a structure storing the image's tags. This should only be
accessed via the i_tags_*() functions.
=item *
-ext_data - a pointer for use internal to an image implementation.
+C<ext_data> - a pointer for use internal to an image implementation.
This should be freed by the image's destroy handler.
=item *
-im_data - data internal to Imager. This is initialized by
+C<im_data> - data internal to Imager. This is initialized by
i_img_init().
=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
=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.
=item i_arc_aa(im, x, y, rad, d1, d2, color)
-Antialias fills an arc centered at (x,y) with radius I<rad> covering
+ 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.
=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
+ 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.
=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.
=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>.
=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.
=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.
=item i_circle_aa(im, x, y, rad, color)
-Antialias fills a circle centered at (x,y) for radius I<rad> with
+ 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(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>.
+ 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 (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>.
+ 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 (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>.
+ i_flood_fill(im, 50, 50, &color);
-Returns false if (seedx, seedy) are outside the image.
+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(im, seedx, seedy, color, border)
+=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 (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
=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.
=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.
=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.
=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.
-If chans is NULL then the first chan_count channels are retrieved for
-each pixel.
+This is intended for output to image formats that don't support alpha
+channels.
+
+
+=for comment
+From: File paste.im
-Returns the number of samples read (which should be (r-l) *
-chan_count)
+=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_line(im, x1, y1, x2, y2, val, endp)
+=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.
-Draw a line to image using bresenhams linedrawing algorithm
+If C<channels> is NULL then the first C<channel_count> channels are
+retrieved for each pixel.
- 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)
+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(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
=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.
=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.
=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.
=for comment
-From: File imext.c
+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_clear_error()
+
+ i_clear_error();
+
+Clears the error stack.
+
+Called by any Imager function before doing any other processing.
+
+
+=for comment
+From: File error.c
+
+=item i_push_error(int code, char const *msg)
+
+ i_push_error(0, "Yep, it's broken");
+ i_push_error(errno, "Error writing");
+
+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 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 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
+
+
+=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 i_get_image_file_limits(&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
+
+
+=for comment
+From: File limits.c
+
+=item i_int_check_image_file_limits(width, height, channels, sample_size)
+
+
+ i_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.
+
+
+=for comment
+From: File limits.c
+
+=item i_set_image_file_limits(width, height, bytes)
+
+
+ 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.
+
+
+=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 io_new_bufchain()
+
+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).
+
+
+=for comment
+From: File iolayer.c
+
+=item io_new_buffer(data, length)
+
+Returns a new io_glue object that has the source defined as reading
+from specified buffer. Note that the buffer is not copied.
+
+ data - buffer to read from
+ length - length of buffer
+
+
+=for comment
+From: File iolayer.c
+=item io_new_cb(p, read_cb, write_cb, seek_cb, close_cb, destroy_cb)
-=back
+Create a new I/O layer object that calls your supplied callbacks.
-=head2 Error handling
+In general the callbacks should behave like the corresponding POSIX
+primitives.
=over
-=item i_clear_error()
+=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.
-Clears the error stack.
+=item *
-Called by any imager function before doing any other processing.
+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 *
-=for comment
-From: File error.c
+C<seekcb>(p, offset, whence) should seek and return the new offset.
-=item i_push_error(int code, char const *msg)
+=item *
+C<close_cb>(p) should return 0 on success, -1 on failure.
-Called by an imager function to push an error message onto the stack.
+=item *
-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.).
+C<destroy_cb>(p) should release any memory specific to your callback
+handlers.
+
+=back
=for comment
-From: File error.c
+From: File iolayer.c
-=item i_push_errorf(int code, char const *fmt, ...)
+=item io_new_fd(fd)
+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.
-A version of i_push_error() that does printf() like formating.
+ fd - file descriptor to read/write from
=for comment
-From: File error.c
+From: File iolayer.c
-=item i_push_errorvf(int code, char const *fmt, va_list ap)
+=item i_io_close(io)
+Flush any pending output and perform the close action for the stream.
-Intended for use by higher level functions, takes a varargs pointer
-and a format to produce the finally pushed error message.
+Returns 0 on success.
=for comment
-From: File error.c
+From: File iolayer.c
+=item i_io_flush(io)
-=back
+Flush any buffered output.
-=head2 Files
+Returns true on success,
-=over
-=item i_get_image_file_limits(&width, &height, &bytes)
+=for comment
+From: File iolayer.c
+=item i_io_getc(ig)
-Retrieves the file limits set by i_set_image_file_limits().
+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 limits.c
+From: File iolayer.c
-=item i_int_check_image_file_limits(width, height, channels, sample_size)
+=item i_io_gets(ig, buffer, size, end_of_line)
+ char buffer[BUFSIZ]
+ ssize_t len = i_io_gets(buffer, sizeof(buffer), '\n');
-Checks the size of a file in memory against the configured image file
-limits.
+Read up to C<size>-1 bytes from the stream C<ig> into C<buffer>.
-This also range checks the values to those permitted by Imager and
-checks for overflows in calculating the size.
+If the byte C<end_of_line> is seen then no further bytes will be read.
-Returns non-zero if the file is within limits.
+Returns the number of bytes read.
-This function is intended to be called by image file read functions.
+Always C<NUL> terminates the buffer.
=for comment
-From: File limits.c
+From: File iolayer.c
-=item i_set_image_file_limits(width, height, bytes)
+=item i_io_peekc(ig)
+Read the next character from the stream without advancing the stream.
-Set limits on the sizes of images read by Imager.
+On error or end of file, return EOF.
-Setting a limit to 0 means that limit is ignored.
+For unbuffered streams a single character buffer will be setup.
-Negative limits result in failure.
-Returns non-zero on success.
+=for comment
+From: File iolayer.c
+=item i_io_peekn(ig, buffer, size)
-=for comment
-From: File limits.c
+ 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>.
-=back
+This ignores the buffered state of the stream, and will always setup
+buffering if needed.
-=head2 Fills
+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.
-=over
+Returns -1 on error, 0 if there is no data before EOF, or the number
+of bytes read into C<buffer>.
-=item i_fill_destroy(fill)
+=for comment
+From: File iolayer.c
-Call to destroy any fill object.
+=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 fills.c
-=item i_new_fill_fount(xa, ya, xb, yb, type, repeat, combine, super_sample, ssample_param, count, segs)
+=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>.
-Creates a new general fill which fills with a fountain fill.
+Returns the number of bytes read. Returns 0 on end of file. Returns
+-1 on error.
=for comment
-From: File filters.c
+From: File iolayer.c
-=item i_new_fill_hatch(fg, bg, combine, hatch, cust_hatch, dx, dy)
+=item i_io_seek(io, offset, whence)
+Seek within the stream.
-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.
+Acts like perl's seek.
-If 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.
+=for comment
+From: File iolayer.c
-(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.
+=item i_io_set_buffered(io, buffered)
+Set the buffering mode of the stream.
-=for comment
-From: File fills.c
+If you switch buffering off on a stream with buffering on:
-=item i_new_fill_hatchf(fg, bg, combine, hatch, cust_hatch, dx, dy)
+=over
+=item *
-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.
+any buffered output will be flushed.
-If cust_hatch is non-NULL it should be a pointer to 8 bytes of the
-hash definition, with the high-bits to the left.
+=item *
-If cust_hatch is NULL then one of the standard hatches is used.
+any existing buffered input will be consumed before reads become
+unbuffered.
-(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.
+=back
+Returns true on success. This may fail if any buffered output cannot
+be flushed.
-=for comment
-From: File fills.c
-=item i_new_fill_image(im, matrix, xoff, yoff, combine)
+=for comment
+From: File iolayer.c
+=item i_io_write(io, buffer, size)
-Create an image based fill.
+ ssize_t result = i_io_write(io, buffer, size)
-matrix is an array of 9 doubles representing a transformation matrix.
+Write to the given I/O stream.
-xoff and yoff are the offset into the image to start filling from.
+Returns the number of bytes written.
=for comment
-From: File fills.c
+From: File iolayer.c
-=item i_new_fill_solid(color, combine)
+=item io_slurp(ig, c)
+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.
-Create a solid fill based on an 8-bit color.
+ ig - io_glue object
+ c - pointer to a pointer to where data should be copied to
-If combine is non-zero then alpha values will be combined.
+ 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 fills.c
+From: File iolayer.c
-=item i_new_fill_solidf(color, combine)
+=item io_glue_destroy(ig)
+ io_glue_destroy(ig);
-Create a solid fill based on a float color.
+Destroy an io_glue objects. Should clean up all related buffers.
-If combine is non-zero then alpha values will be combined.
+ ig - io_glue object to destroy.
=for comment
-From: File fills.c
+From: File iolayer.c
=back
=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.
=for comment
From: File image.c
-=item i_copyto(dest, src, x1, y1, x2, y2, tx, ty)
+=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 (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.
+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 x1 > x2 or y1 > y2 then the corresponding co-ordinates are swapped.
+If C<x1> > C<x2> or C<y1> > C<y2> then the corresponding co-ordinates
+are swapped.
=for comment
-From: File image.c
+From: File paste.im
-=item i_copyto_trans(im, src, x1, y1, x2, y2, tx, ty, trans)
+=item i_copyto_trans(C<im>, C<src>, C<x1>, C<y1>, C<x2>, C<y2>, C<tx>, C<ty>, C<trans>)
-(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.
+(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
=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.
=back
-=head2 Image creation
+=head2 Image creation/destruction
=over
=item i_img_16_new(x, y, ch)
+ 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.
=for comment
From: File img16.c
-
-=back
-
-=head2 Image creation/destruction
-
-=over
-
=item i_img_8_new(x, y, ch)
+ 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 image.c
-
-=item i_img_destroy(img)
-
+From: File img8.c
-Destroy an image object
-
-
-=for comment
-From: File image.c
+=item i_img_double_new(i_img_dim x, i_img_dim y, int ch)
-=item i_img_double_new(int x, int y, int ch)
+ i_img *img = i_img_double_new(width, height, channels);
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>)
+ i_img *img = i_img_pal_new(width, height, channels, max_palette_size)
+
Creates a new paletted image of the supplied dimensions.
-I<maxpal> is the maximum palette size and should normally be 256.
+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>)
+ 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(i_img *im, int xsize, int ysize, int channels)
+=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 i_img_destroy(C<img>)
+
+ i_img_destroy(img)
+
+Destroy an image object
+
+
=for comment
From: File image.c
=for comment
From: File image.c
-=item i_img_init(img)
+=item i_img_init(C<img>)
-Imager interal initialization of images.
+Imager internal initialization of images.
Currently this does very little, in the future it may be used to
support threads, or color profiles.
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(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.
=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
=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.
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.
=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>.
=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>.
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
=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
=for comment
From: File tags.c
-=item i_tags_setn(tags, name, idata)
+=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 I<idata>
+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
=over
-=item i_img_get_height(im)
-
-
-Returns the height in pixels of the image.
-
-
-=for comment
-From: File image.c
-
-=item i_img_get_width(im)
-
-
-Returns the width in pixels of the image.
-
-
-=for comment
-From: File image.c
-
-=item i_img_getchannels(im)
-
+=item i_utf8_advance(char **p, size_t *len)
-Get the number of channels in I<im>.
+Retrieve a C<UTF-8> character from the stream.
+Modifies *p and *len to indicate the consumed characters.
-=for comment
-From: File image.c
-
-=item i_img_getmask(im)
-
-
-Get the image channel mask for I<im>.
-
-
-=for comment
-From: File image.c
-
-=item i_img_setmask(im, ch_mask)
+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.
-Set the image channel mask for I<im> to I<ch_mask>.
+Returns ~0UL on failure.
=for comment
-From: File image.c
-
-
-
-=back
-
-
-=head1 UNDOCUMENTED
-
-The following API functions are undocumented so far, hopefully this
-will change:
-
-=over
-
-=item *
-
-B<i_color>
-
-=item *
-
-B<i_fcolor>
-
-=item *
-
-B<i_fill_t>
-
-=item *
-
-B<i_lhead>
+From: File io.c
=head1 AUTHOR
-Tony Cook <tony@imager.perl.org>
+Tony Cook <tonyc@cpan.org>
=head1 SEE ALSO
projects / imager.git / blobdiff