use $Config{path_sep} instead of working it out on our own

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


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

  # 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/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_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 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(im, x, y, rad, d1, d2, 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)


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)


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)


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)


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)


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)


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)


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


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


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


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


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


=back

=head2 Error handling

=over

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

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

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_image_file_limits(&width, &height, &bytes)


Retrieves the file limits set by i_set_image_file_limits().


=for comment
From: File limits.c

=item i_int_check_image_file_limits(width, height, channels, sample_size)


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)


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.

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



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


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


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


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)


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)


Create a solid fill based on a float color.

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


=for comment
From: File fills.c

=item i_fill_destroy(fill)

Call to destroy any fill object.


=for comment
From: File fills.c


=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_img_16_new(x, y, ch)


Create a new 16-bit/sample image.

Returns the image on success, or NULL on failure.


=for comment
From: File img16.c

=item i_img_8_new(x, y, ch)



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


=for comment
From: File image.c

=item i_img_double_new(int x, int y, int ch)

Creates a new double per sample image.


=for comment
From: File imgdouble.c

=item i_img_pal_new(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(C<im>, C<xsize>, C<ysize>)


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


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


=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

=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

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

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

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


=head1 AUTHOR

Tony Cook <tony@imager.perl.org>

=head1 SEE ALSO

Imager, Imager::ExtUtils, Imager::Inline

=cut