diff options
Diffstat (limited to 'Master/tlpkg/tlperl/lib/Imager/APIRef.pod')
| -rwxr-xr-x | Master/tlpkg/tlperl/lib/Imager/APIRef.pod | 1451 |
1 files changed, 1451 insertions, 0 deletions
diff --git a/Master/tlpkg/tlperl/lib/Imager/APIRef.pod b/Master/tlpkg/tlperl/lib/Imager/APIRef.pod new file mode 100755 index 00000000000..320f0648593 --- /dev/null +++ b/Master/tlpkg/tlperl/lib/Imager/APIRef.pod @@ -0,0 +1,1451 @@ +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 * + +channels - the number of channels in the image + +=item * + +xsize, ysize - the width and height of the image in pixels + +=item * + +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 +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 +i_8_bits, i_16_bits, i_double_bits. + +=item * + +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. + +=item * + +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 +accessed via the i_tags_*() functions. + +=item * + +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 +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.gray.gray_color + +=item * + +rgb - contains three elements r, g, b, eg. c.rgb.r + +=item * + +rgba - contains four elements r, g, b, a, eg. c.rgba.a + +=item * + +cmyk - contains four elements c, m, y, 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) + + +Antialias 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) + + +Antialias 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) + + +Antialias 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) + + +Flood fills the 4-connected region starting from the point (seedx, +seedy) with I<fill>. + +Returns false if (seedx, seedy) are outside the image. + + +=for comment +From: File draw.c + +=item i_flood_cfill_border(im, seedx, seedy, fill, 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>. + +Returns false if (seedx, seedy) are outside the image. + + +=for comment +From: File draw.c + +=item i_flood_fill(im, seedx, seedy, color) + + +Flood fills the 4-connected region starting from the point (seedx, +seedy) with I<color>. + +Returns false if (seedx, seedy) are outside the image. + + +=for comment +From: File draw.c + +=item i_flood_fill_border(im, seedx, seedy, 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>. + +Returns false if (seedx, 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, x, r, y, indexes) + + +Reads palette indexes for the horizontal line (x, y) to (r-1, y) into +indexes. + +Returns the number of indexes read. + +Always returns 0 for direct color images. + + +=for comment +From: File imext.c + +=item i_gpix(im, x, y, color) + + +Retrieves the I<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) + + +Retrieves the color of the pixel (x,y) as a floating point color into +I<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) + + +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. + +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 imext.c + +=item i_gsampf(im, l, r, y, samp, chans, chan_count) + + +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. + +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 imext.c + +=item i_line(im, x1, y1, x2, y2, val, endp) + + +Draw a line to image using bresenhams linedrawing 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) + + +=for comment +From: File draw.c + +=item i_line_aa(im, x1, x2, y1, y2, color, endp) + + +Antialias draws a line from (x1,y1) to (x2, y2) in color. + +The point (x2, y2) is drawn only if 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, l, r, fcolors) + + +Sets (r-l) pixels starting from (l,y) using (r-l) floating point +colors from I<colors>. + +Returns the number of pixels set. + + +=for comment +From: File imext.c + +=item i_ppal(im, x, r, y, indexes) + + +Writes palette indexes for the horizontal line (x, y) to (r-1, y) from +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, x, y, fcolor) + + +Sets the pixel at (x,y) to the floating point color I<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 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) + + +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(xa, ya, xb, yb, type, repeat, combine, super_sample, ssample_param, count, segs) + + + +Creates a new general fill which fills with a fountain fill. + + +=for comment +From: File filters.im + +=item i_new_fill_hatch(fg, bg, combine, hatch, cust_hatch, dx, 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. + +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. + +(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. + + +=for comment +From: File fills.c + +=item i_new_fill_hatchf(fg, bg, combine, hatch, cust_hatch, dx, 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. + +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. + +(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. + + +=for comment +From: File fills.c + +=item i_new_fill_image(im, matrix, xoff, yoff, 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. + + +=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(src) + + +Creates a new image that is a copy of src. + +Tags are not copied, only the image data. + +Returns: i_img * + + +=for comment +From: File image.c + +=item i_copyto(dest, src, x1, y1, x2, y2, tx, ty) + + +Copies image data from the area (x1,y1)-[x2,y2] in the source image to +a rectangle the same size with it's top-left corner at (tx,ty) in the +destination image. + +If x1 > x2 or y1 > y2 then the corresponding co-ordinates are swapped. + + +=for comment +From: File paste.im + +=item i_copyto_trans(im, src, x1, y1, x2, y2, tx, ty, 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. + + +=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(im, src, tx, ty, src_minx, src_miny, src_maxx, 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. + +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 +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(x, y, channels, maxpal) + + +Creates a new paletted image of the supplied dimensions. + +I<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) + + +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) + + +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(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(img) + +Imager interal 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(im) + + +The number of channels holding color information. + + +=for comment +From: File immacros.h + +=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) + +Get the number of channels in I<im>. + + +=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_has_alpha(im) + + +Return true if the image has an alpha channel. + + +=for comment +From: File immacros.h + +=item i_img_setmask(im, ch_mask) + +Set the image channel mask for I<im> to I<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) + + +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). + + +=for comment +From: File quant.c + +=item i_quant_translate(quant, img) + + +Quantize the image given the palette in quant. + +On success returns a pointer to a memory block of img->xsize * +img->ysize 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(quant, data, img, 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>. + +The method used depends on the tr_* members of 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 sucess 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) + + +Searchs 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) + + +Searchs 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 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(tags, name, idata) + +Sets the given tag to the integer I<idata> + +Even on failure, if an existing tag I<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 |