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