2641 lines
52 KiB
Plaintext
2641 lines
52 KiB
Plaintext
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;
|
|
double x[] = { ... };
|
|
double y[] = { ... };
|
|
i_polygon_t poly;
|
|
poly.count = sizeof(x) / sizeof(*x);
|
|
poly.x = x;
|
|
poly.y = y;
|
|
|
|
|
|
# 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;
|
|
i_img_dim_u limit;
|
|
printf("left %" i_DF "\n", i_DFc(x));
|
|
printf("point (" i_DFp ")\n", i_DFcp(x, y));
|
|
|
|
# Drawing
|
|
i_arc(im, 50, 50, 20, 45, 135, &color);
|
|
i_arc_cfill(im, 50, 50, 35, 90, 135, fill);
|
|
i_arc_aa(im, 50, 50, 35, 90, 135, &color);
|
|
i_arc_aa_cfill(im, 50, 50, 35, 90, 135, fill);
|
|
i_circle_aa(im, 50, 50, 45, &color);
|
|
i_box(im, 0, 0, im->xsize-1, im->ysize-1, &color).
|
|
i_box_filled(im, 0, 0, im->xsize-1, im->ysize-1, &color);
|
|
i_box_cfill(im, 0, 0, im->xsize-1, im->ysize-1, fill);
|
|
i_flood_fill(im, 50, 50, &color);
|
|
i_flood_cfill(im, 50, 50, fill);
|
|
i_flood_fill_border(im, 50, 50, &color, &border);
|
|
i_flood_cfill_border(im, 50, 50, fill, border);
|
|
i_poly_poly_aa(im, 1, &poly, mode, color);
|
|
i_poly_aa_m(im, count, x, y, mode, color);
|
|
i_poly_poly_aa_cfill(im, 1, &poly, mode, fill);
|
|
i_poly_aa_cfill(im, count, x, y, mode, fill);
|
|
|
|
# Error handling
|
|
im_clear_error(aIMCTX);
|
|
i_clear_error();
|
|
i_push_error(0, "Yep, it's broken");
|
|
i_push_error(errno, "Error writing");
|
|
im_push_error(aIMCTX, 0, "Something is wrong");
|
|
va_args args;
|
|
va_start(args, lastarg);
|
|
im_push_errorvf(ctx, code, format, args);
|
|
i_push_errorf(errno, "Cannot open file %s: %d", filename, errno);
|
|
im_push_errorf(aIMCTX, errno, "Cannot open file %s: %d", filename, errno);
|
|
|
|
# Files
|
|
im_set_image_file_limits(aIMCTX, 500, 500, 1000000);
|
|
i_set_image_file_limits(500, 500, 1000000);
|
|
im_get_image_file_limits(aIMCTX, &width, &height, &bytes)
|
|
i_get_image_file_limits(&width, &height, &bytes)
|
|
im_int_check_image_file_limits(aIMCTX, width, height, channels, sizeof(i_sample_t))
|
|
i_int_check_image_file_limits(width, height, channels, sizeof(i_sample_t))
|
|
|
|
# Fills
|
|
i_fill_t *fill = i_new_fill_solidf(&fcolor, combine);
|
|
i_fill_t *fill = i_new_fill_solid(&color, combine);
|
|
i_fill_t *fill = i_new_fill_hatch(&fg_color, &bg_color, combine, hatch, custom_hatch, dx, dy);
|
|
i_fill_t *fill = i_new_fill_hatchf(&fg_fcolor, &bg_fcolor, combine, hatch, custom_hatch, dx, dy);
|
|
i_fill_t *fill = i_new_fill_image(src_img, matrix, x_offset, y_offset, combine);
|
|
fill = i_new_fill_fount(0, 0, 100, 100, i_ft_linear, i_ft_linear,
|
|
i_fr_triangle, 0, i_fts_grid, 9, 1, segs);
|
|
i_fill_destroy(fill);
|
|
|
|
# I/O Layers
|
|
ssize_t count = i_io_peekn(ig, buffer, sizeof(buffer));
|
|
ssize_t result = i_io_write(io, buffer, size)
|
|
char buffer[BUFSIZ]
|
|
ssize_t len = i_io_gets(buffer, sizeof(buffer), '\n');
|
|
io_glue_destroy(ig);
|
|
|
|
# Image
|
|
|
|
# Image creation/destruction
|
|
i_img *img = i_sametype(src, width, height);
|
|
i_img *img = i_sametype_chans(src, width, height, channels);
|
|
i_img *img = im_img_16_new(aIMCTX, width, height, channels);
|
|
i_img *img = i_img_16_new(width, height, channels);
|
|
i_img *img = im_img_8_new(aIMCTX, width, height, channels);
|
|
i_img *img = i_img_8_new(width, height, channels);
|
|
i_img *img = im_img_double_new(aIMCTX, width, height, channels);
|
|
i_img *img = i_img_double_new(width, height, channels);
|
|
i_img *img = im_img_pal_new(aIMCTX, width, height, channels, max_palette_size)
|
|
i_img *img = i_img_pal_new(width, height, channels, max_palette_size)
|
|
i_img_destroy(img)
|
|
|
|
# Image Implementation
|
|
i_img *im = im_img_alloc(aIMCTX);
|
|
i_img *im = i_img_alloc();
|
|
im_img_init(aIMCTX, im);
|
|
i_img_init(im);
|
|
|
|
# Image Information
|
|
// only channel 0 writable
|
|
i_img_setmask(img, 0x01);
|
|
int mask = i_img_getmask(img);
|
|
int channels = i_img_getchannels(img);
|
|
i_img_dim width = i_img_get_width(im);
|
|
i_img_dim height = i_img_get_height(im);
|
|
i_color_model_t cm = i_img_color_model(im);
|
|
int alpha_channel;
|
|
int has_alpha = i_img_alpha_channel(im, &alpha_channel);
|
|
int color_channels = i_img_color_channels(im);
|
|
|
|
# Image quantization
|
|
|
|
# Logging
|
|
|
|
# mutex
|
|
i_mutex_t mutex;
|
|
|
|
# Mutex functions
|
|
i_mutex_t m = i_mutex_new();
|
|
i_mutex_destroy(m);
|
|
i_mutex_lock(m);
|
|
i_mutex_unlock(m);
|
|
|
|
# Paletted images
|
|
|
|
# Tags
|
|
i_tags_set(&img->tags, "i_comment", -1);
|
|
i_tags_setn(&img->tags, "i_xres", 204);
|
|
i_tags_setn(&img->tags, "i_yres", 196);
|
|
|
|
=head1 DESCRIPTION
|
|
|
|
=head2 Blit tools
|
|
|
|
=over
|
|
|
|
=item i_render_color(r, x, y, width, source, color)
|
|
|
|
Render the given color with the coverage specified by C<source[0]> to
|
|
C<source[width-1]>.
|
|
|
|
Renders in normal combine mode.
|
|
|
|
|
|
=for comment
|
|
From: File render.im
|
|
|
|
=item i_render_delete(r)
|
|
|
|
Release an C<i_render> object.
|
|
|
|
|
|
=for comment
|
|
From: File render.im
|
|
|
|
=item i_render_fill(r, x, y, width, source, fill)
|
|
|
|
Render the given fill with the coverage in C<source[0]> through
|
|
C<source[width-1]>.
|
|
|
|
|
|
=for comment
|
|
From: File render.im
|
|
|
|
=item i_render_line(r, x, y, width, source, fill)
|
|
|
|
Render the given fill with the coverage in C<source[0]> through
|
|
C<source[width-1]>.
|
|
|
|
|
|
=for comment
|
|
From: File render.im
|
|
|
|
=item i_render_linef(r, x, y, width, source, fill)
|
|
|
|
Render the given fill with the coverage in C<source[0]> through
|
|
C<source[width-1]>.
|
|
|
|
|
|
=for comment
|
|
From: File render.im
|
|
|
|
=item i_render_new(im, width)
|
|
|
|
Allocate a new C<i_render> object and initialize it.
|
|
|
|
|
|
=for comment
|
|
From: File render.im
|
|
|
|
|
|
=back
|
|
|
|
=head2 Data Types
|
|
|
|
=over
|
|
|
|
=item i_img
|
|
|
|
i_img *img;
|
|
|
|
This is Imager's image type.
|
|
|
|
It contains the following members:
|
|
|
|
=over
|
|
|
|
=item *
|
|
|
|
C<channels> - the number of channels in the image
|
|
|
|
=item *
|
|
|
|
C<xsize>, C<ysize> - the width and height of the image in pixels
|
|
|
|
=item *
|
|
|
|
C<bytes> - the number of bytes used to store the image data. Undefined
|
|
where virtual is non-zero.
|
|
|
|
=item *
|
|
|
|
C<ch_mask> - a mask of writable channels. eg. if this is 6 then only
|
|
channels 1 and 2 are writable. There may be bits set for which there
|
|
are no channels in the image.
|
|
|
|
=item *
|
|
|
|
C<bits> - the number of bits stored per sample. Should be one of
|
|
i_8_bits, i_16_bits, i_double_bits.
|
|
|
|
=item *
|
|
|
|
C<type> - either i_direct_type for direct color images, or i_palette_type
|
|
for paletted images.
|
|
|
|
=item *
|
|
|
|
C<virtual> - if zero then this image is-self contained. If non-zero
|
|
then this image could be an interface to some other implementation.
|
|
|
|
=item *
|
|
|
|
C<idata> - the image data. This should not be directly accessed. A new
|
|
image implementation can use this to store its image data.
|
|
i_img_destroy() will myfree() this pointer if it's non-null.
|
|
|
|
=item *
|
|
|
|
C<tags> - a structure storing the image's tags. This should only be
|
|
accessed via the i_tags_*() functions.
|
|
|
|
=item *
|
|
|
|
C<ext_data> - a pointer for use internal to an image implementation.
|
|
This should be freed by the image's destroy handler.
|
|
|
|
=item *
|
|
|
|
C<im_data> - data internal to Imager. This is initialized by
|
|
i_img_init().
|
|
|
|
=item *
|
|
|
|
i_f_ppix, i_f_ppixf, i_f_plin, i_f_plinf, i_f_gpix, i_f_gpixf,
|
|
i_f_glin, i_f_glinf, i_f_gsamp, i_f_gampf - implementations for each
|
|
of the required image functions. An image implementation should
|
|
initialize these between calling i_img_alloc() and i_img_init().
|
|
|
|
=item *
|
|
|
|
i_f_gpal, i_f_ppal, i_f_addcolors, i_f_getcolors, i_f_colorcount,
|
|
i_f_maxcolors, i_f_findcolor, i_f_setcolors - implementations for each
|
|
paletted image function.
|
|
|
|
=item *
|
|
|
|
i_f_destroy - custom image destruction function. This should be used
|
|
to release memory if necessary.
|
|
|
|
=item *
|
|
|
|
i_f_gsamp_bits - implements i_gsamp_bits() for this image.
|
|
|
|
=item *
|
|
|
|
i_f_psamp_bits - implements i_psamp_bits() for this image.
|
|
|
|
=item *
|
|
|
|
i_f_psamp - implements psamp() for this image.
|
|
|
|
=item *
|
|
|
|
i_f_psampf - implements psamp() for this image.
|
|
|
|
=item *
|
|
|
|
C<im_data> - image specific data internal to Imager.
|
|
|
|
=item *
|
|
|
|
C<context> - the Imager API context this image belongs to.
|
|
|
|
=back
|
|
|
|
|
|
=for comment
|
|
From: File imdatatypes.h
|
|
|
|
=item i_color
|
|
|
|
i_color black;
|
|
black.rgba.r = black.rgba.g = black.rgba.b = black.rgba.a = 0;
|
|
|
|
Type for 8-bit/sample color.
|
|
|
|
Samples as per;
|
|
|
|
i_color c;
|
|
|
|
i_color is a union of:
|
|
|
|
=over
|
|
|
|
=item *
|
|
|
|
gray - contains a single element gray_color, eg. C<c.gray.gray_color>
|
|
|
|
=item *
|
|
|
|
C<rgb> - contains three elements C<r>, C<g>, C<b>, eg. C<c.rgb.r>
|
|
|
|
=item *
|
|
|
|
C<rgba> - contains four elements C<r>, C<g>, C<b>, C<a>, eg. C<c.rgba.a>
|
|
|
|
=item *
|
|
|
|
C<cmyk> - contains four elements C<c>, C<m>, C<y>, C<k>,
|
|
eg. C<c.cmyk.y>. Note that Imager never uses CMYK colors except when
|
|
reading/writing files.
|
|
|
|
=item *
|
|
|
|
channels - an array of four channels, eg C<c.channels[2]>.
|
|
|
|
=back
|
|
|
|
|
|
=for comment
|
|
From: File imdatatypes.h
|
|
|
|
=item i_fcolor
|
|
|
|
This is the double/sample color type.
|
|
|
|
Its layout exactly corresponds to i_color.
|
|
|
|
|
|
=for comment
|
|
From: File imdatatypes.h
|
|
|
|
=item i_fill_t
|
|
|
|
i_fill_t *fill;
|
|
|
|
This is the "abstract" base type for Imager's fill types.
|
|
|
|
Unless you're implementing a new fill type you'll typically treat this
|
|
as an opaque type.
|
|
|
|
|
|
=for comment
|
|
From: File imdatatypes.h
|
|
|
|
=item i_poly_fill_mode_t
|
|
|
|
Control how polygons are filled. Has the following values:
|
|
|
|
=over
|
|
|
|
=item *
|
|
|
|
C<i_pfm_evenodd> - simple even-odd fills.
|
|
|
|
=item *
|
|
|
|
C<i_pfm_nonzero> - non-zero winding rule fills.
|
|
|
|
=back
|
|
|
|
|
|
=for comment
|
|
From: File imdatatypes.h
|
|
|
|
=item i_polygon_t
|
|
|
|
Represents a polygon. Has the following members:
|
|
|
|
=over
|
|
|
|
=item *
|
|
|
|
C<x>, C<y> - arrays of x and y locations of vertices.
|
|
|
|
=item *
|
|
|
|
C<count> - the number of entries in the C<x> and C<y> arrays.
|
|
|
|
=back
|
|
|
|
|
|
=for comment
|
|
From: File imdatatypes.h
|
|
|
|
=item im_context_t
|
|
|
|
Imager's per-thread context.
|
|
|
|
|
|
=for comment
|
|
From: File imdatatypes.h
|
|
|
|
=item im_slot_t
|
|
|
|
Represents a slot in the context object.
|
|
|
|
|
|
=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_img_dim_u
|
|
|
|
i_img_dim_u limit;
|
|
|
|
An unsigned variant of L</i_img_dim>.
|
|
|
|
|
|
=for comment
|
|
From: File imdatatypes.h
|
|
|
|
=item i_color_model_t
|
|
|
|
Returned by L</i_img_color_model(im)> to indicate the color model of
|
|
the image.
|
|
|
|
An enumerated type with the following possible values:
|
|
|
|
=over
|
|
|
|
=item *
|
|
|
|
C<icm_unknown> - the image has no usable color data. In future
|
|
versions of Imager this will be returned in a few limited cases,
|
|
eg. when the source image is CMYK and the user has requested no color
|
|
translation is done.
|
|
|
|
=item *
|
|
|
|
C<icm_gray> - gray scale with no alpha channel.
|
|
|
|
=item *
|
|
|
|
C<icm_gray_alpha> - gray scale with an alpha channel.
|
|
|
|
=item *
|
|
|
|
C<icm_rgb> - RGB
|
|
|
|
=item *
|
|
|
|
C<icm_rgb_alpha> - RGB with an alpha channel.
|
|
|
|
=back
|
|
|
|
|
|
=for comment
|
|
From: File imdatatypes.h
|
|
|
|
=item i_DF
|
|
|
|
printf("left %" i_DF "\n", i_DFc(x));
|
|
|
|
This is a constant string that can be used with functions like
|
|
printf() to format i_img_dim values after they're been cast with i_DFc().
|
|
|
|
Does not include the leading C<%>.
|
|
|
|
|
|
=for comment
|
|
From: File imdatatypes.h
|
|
|
|
=item i_DFc
|
|
|
|
Cast an C<i_img_dim> value to a type for use with the i_DF format
|
|
string.
|
|
|
|
|
|
=for comment
|
|
From: File imdatatypes.h
|
|
|
|
=item i_DFcp
|
|
|
|
Casts two C<i_img_dim> values for use with the i_DF (or i_DFp) format.
|
|
|
|
|
|
=for comment
|
|
From: File imdatatypes.h
|
|
|
|
=item i_DFp
|
|
|
|
printf("point (" i_DFp ")\n", i_DFcp(x, y));
|
|
|
|
Format a pair of C<i_img_dim> values. This format string I<does>
|
|
include the leading C<%>.
|
|
|
|
|
|
=for comment
|
|
From: File imdatatypes.h
|
|
|
|
|
|
=back
|
|
|
|
=head2 Drawing
|
|
|
|
=over
|
|
|
|
=item i_arc(im, x, y, rad, d1, d2, color)
|
|
|
|
|
|
i_arc(im, 50, 50, 20, 45, 135, &color);
|
|
|
|
Fills an arc centered at (x,y) with radius I<rad> covering the range
|
|
of angles in degrees from d1 to d2, with the color.
|
|
|
|
|
|
=for comment
|
|
From: File draw.c
|
|
|
|
=item i_arc_aa(im, x, y, rad, d1, d2, color)
|
|
|
|
|
|
i_arc_aa(im, 50, 50, 35, 90, 135, &color);
|
|
|
|
Anti-alias fills an arc centered at (x,y) with radius I<rad> covering
|
|
the range of angles in degrees from d1 to d2, with the color.
|
|
|
|
|
|
=for comment
|
|
From: File draw.c
|
|
|
|
=item i_arc_aa_cfill(im, x, y, rad, d1, d2, fill)
|
|
|
|
|
|
i_arc_aa_cfill(im, 50, 50, 35, 90, 135, fill);
|
|
|
|
Anti-alias fills an arc centered at (x,y) with radius I<rad> covering
|
|
the range of angles in degrees from d1 to d2, with the fill object.
|
|
|
|
|
|
=for comment
|
|
From: File draw.c
|
|
|
|
=item i_arc_cfill(im, x, y, rad, d1, d2, fill)
|
|
|
|
|
|
i_arc_cfill(im, 50, 50, 35, 90, 135, fill);
|
|
|
|
Fills an arc centered at (x,y) with radius I<rad> covering the range
|
|
of angles in degrees from d1 to d2, with the fill object.
|
|
|
|
|
|
=for comment
|
|
From: File draw.c
|
|
|
|
=item i_box(im, x1, y1, x2, y2, color)
|
|
|
|
|
|
i_box(im, 0, 0, im->xsize-1, im->ysize-1, &color).
|
|
|
|
Outlines the box from (x1,y1) to (x2,y2) inclusive with I<color>.
|
|
|
|
|
|
=for comment
|
|
From: File draw.c
|
|
|
|
=item i_box_cfill(im, x1, y1, x2, y2, fill)
|
|
|
|
|
|
i_box_cfill(im, 0, 0, im->xsize-1, im->ysize-1, fill);
|
|
|
|
Fills the box from (x1,y1) to (x2,y2) inclusive with fill.
|
|
|
|
|
|
=for comment
|
|
From: File draw.c
|
|
|
|
=item i_box_filled(im, x1, y1, x2, y2, color)
|
|
|
|
|
|
i_box_filled(im, 0, 0, im->xsize-1, im->ysize-1, &color);
|
|
|
|
Fills the box from (x1,y1) to (x2,y2) inclusive with color.
|
|
|
|
|
|
=for comment
|
|
From: File draw.c
|
|
|
|
=item i_circle_aa(im, x, y, rad, color)
|
|
|
|
|
|
i_circle_aa(im, 50, 50, 45, &color);
|
|
|
|
Anti-alias fills a circle centered at (x,y) for radius I<rad> with
|
|
color.
|
|
|
|
|
|
=for comment
|
|
From: File draw.c
|
|
|
|
=item i_flood_cfill(C<im>, C<seedx>, C<seedy>, C<fill>)
|
|
|
|
|
|
i_flood_cfill(im, 50, 50, fill);
|
|
|
|
Flood fills the 4-connected region starting from the point (C<seedx>,
|
|
C<seedy>) with C<fill>.
|
|
|
|
Returns false if (C<seedx>, C<seedy>) are outside the image.
|
|
|
|
|
|
=for comment
|
|
From: File draw.c
|
|
|
|
=item i_flood_cfill_border(C<im>, C<seedx>, C<seedy>, C<fill>, C<border>)
|
|
|
|
|
|
i_flood_cfill_border(im, 50, 50, fill, border);
|
|
|
|
Flood fills the 4-connected region starting from the point (C<seedx>,
|
|
C<seedy>) with C<fill>, the fill stops when it reaches pixels of color
|
|
C<border>.
|
|
|
|
Returns false if (C<seedx>, C<seedy>) are outside the image.
|
|
|
|
|
|
=for comment
|
|
From: File draw.c
|
|
|
|
=item i_flood_fill(C<im>, C<seedx>, C<seedy>, C<color>)
|
|
|
|
|
|
i_flood_fill(im, 50, 50, &color);
|
|
|
|
Flood fills the 4-connected region starting from the point (C<seedx>,
|
|
C<seedy>) with I<color>.
|
|
|
|
Returns false if (C<seedx>, C<seedy>) are outside the image.
|
|
|
|
|
|
=for comment
|
|
From: File draw.c
|
|
|
|
=item i_flood_fill_border(C<im>, C<seedx>, C<seedy>, C<color>, C<border>)
|
|
|
|
|
|
i_flood_fill_border(im, 50, 50, &color, &border);
|
|
|
|
Flood fills the 4-connected region starting from the point (C<seedx>,
|
|
C<seedy>) with C<color>, fill stops when the fill reaches a pixels
|
|
with color C<border>.
|
|
|
|
Returns false if (C<seedx>, C<seedy>) are outside the image.
|
|
|
|
|
|
=for comment
|
|
From: File draw.c
|
|
|
|
=item i_glin(im, l, r, y, colors)
|
|
|
|
|
|
Retrieves (r-l) pixels starting from (l,y) into I<colors>.
|
|
|
|
Returns the number of pixels retrieved.
|
|
|
|
|
|
=for comment
|
|
From: File imext.c
|
|
|
|
=item i_glinf(im, l, r, y, colors)
|
|
|
|
|
|
Retrieves (r-l) pixels starting from (l,y) into I<colors> as floating
|
|
point colors.
|
|
|
|
Returns the number of pixels retrieved.
|
|
|
|
|
|
=for comment
|
|
From: File imext.c
|
|
|
|
=item i_gpal(im, left, right, y, indexes)
|
|
|
|
|
|
Reads palette indexes for the horizontal line (left, y) to (right-1,
|
|
y) into C<indexes>.
|
|
|
|
Returns the number of indexes read.
|
|
|
|
Always returns 0 for direct color images.
|
|
|
|
|
|
=for comment
|
|
From: File imext.c
|
|
|
|
=item i_gpix(im, C<x>, C<y>, C<color>)
|
|
|
|
|
|
Retrieves the C<color> of the pixel (x,y).
|
|
|
|
Returns 0 if the pixel was retrieved, or -1 if not.
|
|
|
|
|
|
=for comment
|
|
From: File imext.c
|
|
|
|
=item i_gpixf(im, C<x>, C<y>, C<fcolor>)
|
|
|
|
|
|
Retrieves the color of the pixel (x,y) as a floating point color into
|
|
C<fcolor>.
|
|
|
|
Returns 0 if the pixel was retrieved, or -1 if not.
|
|
|
|
|
|
=for comment
|
|
From: File imext.c
|
|
|
|
=item i_gsamp(im, left, right, y, samples, channels, channel_count)
|
|
|
|
|
|
Reads sample values from C<im> for the horizontal line (left, y) to
|
|
(right-1,y) for the channels specified by C<channels>, an array of int
|
|
with C<channel_count> elements.
|
|
|
|
If channels is NULL then the first channels_count channels are retrieved for
|
|
each pixel.
|
|
|
|
Returns the number of samples read (which should be (right-left) *
|
|
channel_count)
|
|
|
|
|
|
=for comment
|
|
From: File imext.c
|
|
|
|
=item i_gsamp_bg(im, l, r, y, samples, out_channels, background)
|
|
|
|
|
|
Like C<i_gsampf()> but applies the source image color over a supplied
|
|
background color.
|
|
|
|
This is intended for output to image formats that don't support alpha
|
|
channels.
|
|
|
|
|
|
=for comment
|
|
From: File paste.im
|
|
|
|
=item i_gsamp_bits(im, left, right, y, samples, channels, channel_count, bits)
|
|
|
|
Reads integer samples scaled to C<bits> bits of precision into the
|
|
C<unsigned int> array C<samples>.
|
|
|
|
Expect this to be slow unless C<< bits == im->bits >>.
|
|
|
|
Returns the number of samples copied, or -1 on error.
|
|
|
|
Not all image types implement this method.
|
|
|
|
Pushes errors, but does not call C<i_clear_error()>.
|
|
|
|
|
|
=for comment
|
|
From: File imext.c
|
|
|
|
=item i_gsampf(im, left, right, y, samples, channels, channel_count)
|
|
|
|
|
|
Reads floating point sample values from C<im> for the horizontal line
|
|
(left, y) to (right-1,y) for the channels specified by C<channels>, an
|
|
array of int with channel_count elements.
|
|
|
|
If C<channels> is NULL then the first C<channel_count> channels are
|
|
retrieved for each pixel.
|
|
|
|
Returns the number of samples read (which should be (C<right>-C<left>)
|
|
* C<channel_count>)
|
|
|
|
|
|
=for comment
|
|
From: File imext.c
|
|
|
|
=item i_gsampf_bg(im, l, r, y, samples, out_channels, background)
|
|
|
|
|
|
Like C<i_gsampf()> but applies the source image color over a supplied
|
|
background color.
|
|
|
|
This is intended for output to image formats that don't support alpha
|
|
channels.
|
|
|
|
|
|
=for comment
|
|
From: File paste.im
|
|
|
|
=item i_line(C<im>, C<x1>, C<y1>, C<x2>, C<y2>, C<color>, C<endp>)
|
|
|
|
|
|
=for stopwords Bresenham's
|
|
|
|
Draw a line to image using Bresenham's line drawing algorithm
|
|
|
|
im - image to draw to
|
|
x1 - starting x coordinate
|
|
y1 - starting x coordinate
|
|
x2 - starting x coordinate
|
|
y2 - starting x coordinate
|
|
color - color to write to image
|
|
endp - endpoint flag (boolean)
|
|
|
|
|
|
=for comment
|
|
From: File draw.c
|
|
|
|
=item i_line_aa(C<im>, C<x1>, C<x2>, C<y1>, C<y2>, C<color>, C<endp>)
|
|
|
|
|
|
Anti-alias draws a line from (x1,y1) to (x2, y2) in color.
|
|
|
|
The point (x2, y2) is drawn only if C<endp> is set.
|
|
|
|
|
|
=for comment
|
|
From: File draw.c
|
|
|
|
=item i_plin(im, l, r, y, colors)
|
|
|
|
|
|
Sets (r-l) pixels starting from (l,y) using (r-l) values from
|
|
I<colors>.
|
|
|
|
Returns the number of pixels set.
|
|
|
|
|
|
=for comment
|
|
From: File imext.c
|
|
|
|
=item i_plinf(im, C<left>, C<right>, C<fcolors>)
|
|
|
|
|
|
Sets (right-left) pixels starting from (left,y) using (right-left)
|
|
floating point colors from C<fcolors>.
|
|
|
|
Returns the number of pixels set.
|
|
|
|
|
|
=for comment
|
|
From: File imext.c
|
|
|
|
=item i_poly_aa_cfill_m(im, count, x, y, mode, fill)
|
|
|
|
i_poly_aa_cfill(im, count, x, y, mode, fill);
|
|
|
|
Fill a polygon defined by the points specified by the x and y arrays with
|
|
the fill specified by C<fill>.
|
|
|
|
|
|
=for comment
|
|
From: File polygon.c
|
|
|
|
=item i_poly_aa_m(im, count, x, y, mode, color)
|
|
|
|
i_poly_aa_m(im, count, x, y, mode, color);
|
|
|
|
Fill a polygon defined by the points specified by the x and y arrays with
|
|
the color specified by C<color>.
|
|
|
|
|
|
=for comment
|
|
From: File polygon.c
|
|
|
|
=item i_poly_poly_aa(im, count, polys, mode, color)
|
|
|
|
i_poly_poly_aa(im, 1, &poly, mode, color);
|
|
|
|
Fill the C<count> polygons defined by C<polys> the color specified by
|
|
C<color>.
|
|
|
|
At least one polygon must be supplied.
|
|
|
|
All polygons must have at least 3 points.
|
|
|
|
|
|
=for comment
|
|
From: File polygon.c
|
|
|
|
=item i_poly_poly_aa_cfill(im, count, polys, mode, fill)
|
|
|
|
i_poly_poly_aa_cfill(im, 1, &poly, mode, fill);
|
|
|
|
Fill the C<count> polygons defined by C<polys> the fill specified by
|
|
C<fill>.
|
|
|
|
At least one polygon must be supplied.
|
|
|
|
All polygons must have at least 3 points.
|
|
|
|
|
|
=for comment
|
|
From: File polygon.c
|
|
|
|
=item i_ppal(im, left, right, y, indexes)
|
|
|
|
|
|
Writes palette indexes for the horizontal line (left, y) to (right-1,
|
|
y) from C<indexes>.
|
|
|
|
Returns the number of indexes written.
|
|
|
|
Always returns 0 for direct color images.
|
|
|
|
|
|
=for comment
|
|
From: File imext.c
|
|
|
|
=item i_ppix(im, x, y, color)
|
|
|
|
|
|
Sets the pixel at (x,y) to I<color>.
|
|
|
|
Returns 0 if the pixel was drawn, or -1 if not.
|
|
|
|
Does no alpha blending, just copies the channels from the supplied
|
|
color to the image.
|
|
|
|
|
|
=for comment
|
|
From: File imext.c
|
|
|
|
=item i_ppixf(im, C<x>, C<y>, C<fcolor>)
|
|
|
|
|
|
Sets the pixel at (C<x>,C<y>) to the floating point color C<fcolor>.
|
|
|
|
Returns 0 if the pixel was drawn, or -1 if not.
|
|
|
|
Does no alpha blending, just copies the channels from the supplied
|
|
color to the image.
|
|
|
|
|
|
=for comment
|
|
From: File imext.c
|
|
|
|
=item i_psamp(im, left, right, y, samples, channels, channel_count)
|
|
|
|
Writes sample values from C<samples> to C<im> for the horizontal line
|
|
(left, y) to (right-1, y) inclusive for the channels specified by
|
|
C<channels>, an array of C<int> with C<channel_count> elements.
|
|
|
|
If C<channels> is C<NULL> then the first C<channels_count> channels
|
|
are written to for each pixel.
|
|
|
|
Returns the number of samples written, which should be (right - left)
|
|
* channel_count. If a channel not in the image is in channels, left
|
|
is negative, left is outside the image or y is outside the image,
|
|
returns -1 and pushes an error.
|
|
|
|
|
|
=for comment
|
|
From: File immacros.h
|
|
|
|
=item i_psamp_bits(im, left, right, y, samples, channels, channel_count, bits)
|
|
|
|
Writes integer samples scaled to C<bits> bits of precision from the
|
|
C<unsigned int> array C<samples>.
|
|
|
|
Expect this to be slow unless C<< bits == im->bits >>.
|
|
|
|
Returns the number of samples copied, or -1 on error.
|
|
|
|
Not all image types implement this method.
|
|
|
|
Pushes errors, but does not call C<i_clear_error()>.
|
|
|
|
|
|
=for comment
|
|
From: File imext.c
|
|
|
|
=item i_psampf(im, left, right, y, samples, channels, channel_count)
|
|
|
|
Writes floating point sample values from C<samples> to C<im> for the
|
|
horizontal line (left, y) to (right-1, y) inclusive for the channels
|
|
specified by C<channels>, an array of C<int> with C<channel_count>
|
|
elements.
|
|
|
|
If C<channels> is C<NULL> then the first C<channels_count> channels
|
|
are written to for each pixel.
|
|
|
|
Returns the number of samples written, which should be (right - left)
|
|
* channel_count. If a channel not in the image is in channels, left
|
|
is negative, left is outside the image or y is outside the image,
|
|
returns -1 and pushes an error.
|
|
|
|
|
|
=for comment
|
|
From: File immacros.h
|
|
|
|
|
|
=back
|
|
|
|
=head2 Error handling
|
|
|
|
=over
|
|
|
|
=item i_push_errorf(int code, char const *fmt, ...)
|
|
|
|
i_push_errorf(errno, "Cannot open file %s: %d", filename, errno);
|
|
|
|
A version of i_push_error() that does printf() like formatting.
|
|
|
|
Does not support perl specific format codes.
|
|
|
|
|
|
=for comment
|
|
From: File error.c
|
|
|
|
=item im_clear_error(ctx)
|
|
X<im_clear_error API>X<i_clear_error API>
|
|
|
|
im_clear_error(aIMCTX);
|
|
i_clear_error();
|
|
|
|
Clears the error stack.
|
|
|
|
Called by any Imager function before doing any other processing.
|
|
|
|
Also callable as C<i_clear_error()>.
|
|
|
|
|
|
=for comment
|
|
From: File error.c
|
|
|
|
=item im_push_error(ctx, code, message)
|
|
X<im_push_error API>X<i_push_error API>
|
|
|
|
i_push_error(0, "Yep, it's broken");
|
|
i_push_error(errno, "Error writing");
|
|
im_push_error(aIMCTX, 0, "Something is wrong");
|
|
|
|
Called by an Imager function to push an error message onto the stack.
|
|
|
|
No message is pushed if the stack is full (since this means someone
|
|
forgot to call i_clear_error(), or that a function that doesn't do
|
|
error handling is calling function that does.).
|
|
|
|
|
|
=for comment
|
|
From: File error.c
|
|
|
|
=item im_push_errorf(ctx, code, char const *fmt, ...)
|
|
|
|
im_push_errorf(aIMCTX, errno, "Cannot open file %s: %d", filename, errno);
|
|
|
|
A version of im_push_error() that does printf() like formatting.
|
|
|
|
Does not support perl specific format codes.
|
|
|
|
|
|
=for comment
|
|
From: File error.c
|
|
|
|
=item im_push_errorvf(ctx, code, format, args)
|
|
X<im_push_error_vf API>X<i_push_errorvf API>
|
|
|
|
va_args args;
|
|
va_start(args, lastarg);
|
|
im_push_errorvf(ctx, code, format, args);
|
|
|
|
Intended for use by higher level functions, takes a varargs pointer
|
|
and a format to produce the finally pushed error message.
|
|
|
|
Does not support perl specific format codes.
|
|
|
|
Also callable as C<i_push_errorvf(code, format, args)>
|
|
|
|
|
|
=for comment
|
|
From: File error.c
|
|
|
|
|
|
=back
|
|
|
|
=head2 Files
|
|
|
|
=over
|
|
|
|
=item i_get_file_background(im, &bg)
|
|
|
|
|
|
Retrieve the file write background color tag from the image.
|
|
|
|
If not present, C<bg> is set to black.
|
|
|
|
Returns 1 if the C<i_background> tag was found and valid.
|
|
|
|
|
|
=for comment
|
|
From: File image.c
|
|
|
|
=item i_get_file_backgroundf(im, &bg)
|
|
|
|
|
|
Retrieve the file write background color tag from the image as a
|
|
floating point color.
|
|
|
|
Implemented in terms of i_get_file_background().
|
|
|
|
If not present, C<bg> is set to black.
|
|
|
|
Returns 1 if the C<i_background> tag was found and valid.
|
|
|
|
|
|
=for comment
|
|
From: File image.c
|
|
|
|
=item im_get_image_file_limits(ctx, &width, &height, &bytes)
|
|
X<im_get_image_file_limits API>X<i_get_image_file_limits>
|
|
|
|
im_get_image_file_limits(aIMCTX, &width, &height, &bytes)
|
|
i_get_image_file_limits(&width, &height, &bytes)
|
|
|
|
Retrieves the file limits set by i_set_image_file_limits().
|
|
|
|
=over
|
|
|
|
=item *
|
|
|
|
i_img_dim *width, *height - the maximum width and height of the image.
|
|
|
|
=item *
|
|
|
|
size_t *bytes - size in memory of the image in bytes.
|
|
|
|
=back
|
|
|
|
Also callable as C<i_get_image_file_limits(&width, &height, &bytes)>.
|
|
|
|
|
|
=for comment
|
|
From: File limits.c
|
|
|
|
=item im_int_check_image_file_limits(width, height, channels, sample_size)
|
|
X<im_int_check_image_file_limits API>X<i_int_check_image_file_limits>
|
|
|
|
im_int_check_image_file_limits(aIMCTX, width, height, channels, sizeof(i_sample_t))
|
|
i_int_check_image_file_limits(width, height, channels, sizeof(i_sample_t))
|
|
|
|
Checks the size of a file in memory against the configured image file
|
|
limits.
|
|
|
|
This also range checks the values to those permitted by Imager and
|
|
checks for overflows in calculating the size.
|
|
|
|
Returns non-zero if the file is within limits.
|
|
|
|
This function is intended to be called by image file read functions.
|
|
|
|
Also callable as C<i_int_check_image_file_limits(width, height, channels, sizeof(i_sample_t)>.
|
|
|
|
|
|
=for comment
|
|
From: File limits.c
|
|
|
|
=item im_set_image_file_limits(ctx, width, height, bytes)
|
|
X<im_set_image_file_limits API>X<i_set_image_file_limits API>
|
|
|
|
im_set_image_file_limits(aIMCTX, 500, 500, 1000000);
|
|
i_set_image_file_limits(500, 500, 1000000);
|
|
|
|
Set limits on the sizes of images read by Imager.
|
|
|
|
Setting a limit to 0 means that limit is ignored.
|
|
|
|
Negative limits result in failure.
|
|
|
|
Parameters:
|
|
|
|
=over
|
|
|
|
=item *
|
|
|
|
i_img_dim width, height - maximum width and height.
|
|
|
|
=item *
|
|
|
|
size_t bytes - maximum size in memory in bytes. A value of zero sets
|
|
this limit to one gigabyte.
|
|
|
|
=back
|
|
|
|
Returns non-zero on success.
|
|
|
|
Also callable as C<i_set_image_file_limits(width, height, bytes)>.
|
|
|
|
|
|
=for comment
|
|
From: File limits.c
|
|
|
|
|
|
=back
|
|
|
|
=head2 Fills
|
|
|
|
=over
|
|
|
|
=item i_new_fill_fount(C<xa>, C<ya>, C<xb>, C<yb>, C<type>, C<repeat>, C<combine>, C<super_sample>, C<ssample_param>, C<count>, C<segs>)
|
|
|
|
|
|
fill = i_new_fill_fount(0, 0, 100, 100, i_ft_linear, i_ft_linear,
|
|
i_fr_triangle, 0, i_fts_grid, 9, 1, segs);
|
|
|
|
|
|
Creates a new general fill which fills with a fountain fill.
|
|
|
|
|
|
=for comment
|
|
From: File filters.im
|
|
|
|
=item i_new_fill_hatch(C<fg>, C<bg>, C<combine>, C<hatch>, C<cust_hatch>, C<dx>, C<dy>)
|
|
|
|
|
|
i_fill_t *fill = i_new_fill_hatch(&fg_color, &bg_color, combine, hatch, custom_hatch, dx, dy);
|
|
|
|
Creates a new hatched fill with the C<fg> color used for the 1 bits in
|
|
the hatch and C<bg> for the 0 bits. If C<combine> is non-zero alpha
|
|
values will be combined.
|
|
|
|
If C<cust_hatch> is non-NULL it should be a pointer to 8 bytes of the
|
|
hash definition, with the high-bits to the left.
|
|
|
|
If C<cust_hatch> is NULL then one of the standard hatches is used.
|
|
|
|
(C<dx>, C<dy>) are an offset into the hatch which can be used to hatch
|
|
adjoining areas out of alignment, or to align the origin of a hatch
|
|
with the 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 side of a filled area.
|
|
|
|
|
|
=for comment
|
|
From: File fills.c
|
|
|
|
=item i_new_fill_image(C<im>, C<matrix>, C<xoff>, C<yoff>, C<combine>)
|
|
|
|
|
|
i_fill_t *fill = i_new_fill_image(src_img, matrix, x_offset, y_offset, combine);
|
|
|
|
Create an image based fill.
|
|
|
|
matrix is an array of 9 doubles representing a transformation matrix.
|
|
|
|
C<xoff> and C<yoff> are the offset into the image to start filling from.
|
|
|
|
|
|
=for comment
|
|
From: File fills.c
|
|
|
|
=item i_new_fill_solid(color, combine)
|
|
|
|
|
|
i_fill_t *fill = i_new_fill_solid(&color, combine);
|
|
|
|
Create a solid fill based on an 8-bit color.
|
|
|
|
If combine is non-zero then alpha values will be combined.
|
|
|
|
|
|
=for comment
|
|
From: File fills.c
|
|
|
|
=item i_new_fill_solidf(color, combine)
|
|
|
|
|
|
i_fill_t *fill = i_new_fill_solidf(&fcolor, combine);
|
|
|
|
Create a solid fill based on a float color.
|
|
|
|
If combine is non-zero then alpha values will be combined.
|
|
|
|
|
|
=for comment
|
|
From: File fills.c
|
|
|
|
=item i_fill_destroy(fill)
|
|
|
|
i_fill_destroy(fill);
|
|
|
|
Call to destroy any fill object.
|
|
|
|
|
|
=for comment
|
|
From: File fills.c
|
|
|
|
|
|
=back
|
|
|
|
=head2 I/O Layers
|
|
|
|
=over
|
|
|
|
=item im_io_new_bufchain(ctx)
|
|
X<im_io_new_bufchain API>X<i_io_new_bufchain API>
|
|
|
|
Returns a new io_glue object that has the 'empty' source and but can
|
|
be written to and read from later (like a pseudo file).
|
|
|
|
Also callable as C<io_new_bufchain()>.
|
|
|
|
|
|
=for comment
|
|
From: File iolayer.c
|
|
|
|
=item im_io_new_buffer(ctx, data, length)
|
|
X<im_io_new_buffer API>X<io_new_buffer API>
|
|
|
|
Returns a new io_glue object that has the source defined as reading
|
|
from specified buffer. Note that the buffer is not copied.
|
|
|
|
ctx - an Imager context object
|
|
data - buffer to read from
|
|
length - length of buffer
|
|
|
|
Also callable as C<io_new_buffer(data, length>.
|
|
|
|
|
|
=for comment
|
|
From: File iolayer.c
|
|
|
|
=item im_io_new_cb(ctx, p, read_cb, write_cb, seek_cb, close_cb, destroy_cb)
|
|
X<im_io_new_cb API>X<io_new_cb API>
|
|
|
|
Create a new I/O layer object that calls your supplied callbacks.
|
|
|
|
In general the callbacks should behave like the corresponding POSIX
|
|
primitives.
|
|
|
|
=over
|
|
|
|
=item *
|
|
|
|
C<read_cb>(p, buffer, length) should read up to C<length> bytes into
|
|
C<buffer> and return the number of bytes read. At end of file, return
|
|
0. On error, return -1.
|
|
|
|
=item *
|
|
|
|
C<write_cb>(p, buffer, length) should write up to C<length> bytes from
|
|
C<buffer> and return the number of bytes written. A return value <= 0
|
|
will be treated as an error.
|
|
|
|
=item *
|
|
|
|
C<seekcb>(p, offset, whence) should seek and return the new offset.
|
|
|
|
=item *
|
|
|
|
C<close_cb>(p) should return 0 on success, -1 on failure.
|
|
|
|
=item *
|
|
|
|
C<destroy_cb>(p) should release any memory specific to your callback
|
|
handlers.
|
|
|
|
=back
|
|
|
|
Also callable as C<io_new_cb(p, readcb, writecb, seekcb, closecb,
|
|
destroycb)>.
|
|
|
|
|
|
=for comment
|
|
From: File iolayer.c
|
|
|
|
=item im_io_new_fd(ctx, file)
|
|
X<io_new_fd API>X<im_io_new_fd API>
|
|
|
|
Returns a new io_glue object that has the source defined as reading
|
|
from specified file descriptor. Note that the interface to receiving
|
|
data from the io_glue callbacks hasn't been done yet.
|
|
|
|
ctx - and Imager context object
|
|
file - file descriptor to read/write from
|
|
|
|
Also callable as C<io_new_fd(file)>.
|
|
|
|
|
|
=for comment
|
|
From: File iolayer.c
|
|
|
|
=item i_io_close(io)
|
|
|
|
Flush any pending output and perform the close action for the stream.
|
|
|
|
Returns 0 on success.
|
|
|
|
|
|
=for comment
|
|
From: File iolayer.c
|
|
|
|
=item i_io_flush(io)
|
|
|
|
Flush any buffered output.
|
|
|
|
Returns true on success,
|
|
|
|
|
|
=for comment
|
|
From: File iolayer.c
|
|
|
|
=item i_io_getc(ig)
|
|
|
|
A macro to read a single byte from a buffered I/O glue object.
|
|
|
|
Returns EOF on failure, or a byte.
|
|
|
|
|
|
=for comment
|
|
From: File iolayer.c
|
|
|
|
=item i_io_gets(ig, buffer, size, end_of_line)
|
|
|
|
char buffer[BUFSIZ]
|
|
ssize_t len = i_io_gets(buffer, sizeof(buffer), '\n');
|
|
|
|
Read up to C<size>-1 bytes from the stream C<ig> into C<buffer>.
|
|
|
|
If the byte C<end_of_line> is seen then no further bytes will be read.
|
|
|
|
Returns the number of bytes read.
|
|
|
|
Always C<NUL> terminates the buffer.
|
|
|
|
|
|
=for comment
|
|
From: File iolayer.c
|
|
|
|
=item i_io_peekc(ig)
|
|
|
|
Read the next character from the stream without advancing the stream.
|
|
|
|
On error or end of file, return EOF.
|
|
|
|
For unbuffered streams a single character buffer will be setup.
|
|
|
|
|
|
=for comment
|
|
From: File iolayer.c
|
|
|
|
=item i_io_peekn(ig, buffer, size)
|
|
|
|
ssize_t count = i_io_peekn(ig, buffer, sizeof(buffer));
|
|
|
|
Buffer at least C<size> (at most C<< ig->buf_size >> bytes of data
|
|
from the stream and return C<size> bytes of it to the caller in
|
|
C<buffer>.
|
|
|
|
This ignores the buffered state of the stream, and will always setup
|
|
buffering if needed.
|
|
|
|
If no C<type> parameter is provided to Imager::read() or
|
|
Imager::read_multi(), Imager will call C<i_io_peekn()> when probing
|
|
for the file format.
|
|
|
|
Returns -1 on error, 0 if there is no data before EOF, or the number
|
|
of bytes read into C<buffer>.
|
|
|
|
|
|
=for comment
|
|
From: File iolayer.c
|
|
|
|
=item i_io_putc(ig, c)
|
|
|
|
Write a single character to the stream.
|
|
|
|
On success return c, on error returns EOF
|
|
|
|
|
|
=for comment
|
|
From: File iolayer.c
|
|
|
|
=item i_io_read(io, buffer, size)
|
|
|
|
Read up to C<size> bytes from the stream C<io> into C<buffer>.
|
|
|
|
Returns the number of bytes read. Returns 0 on end of file. Returns
|
|
-1 on error.
|
|
|
|
|
|
=for comment
|
|
From: File iolayer.c
|
|
|
|
=item i_io_seek(io, offset, whence)
|
|
|
|
Seek within the stream.
|
|
|
|
Acts like perl's seek.
|
|
|
|
|
|
=for comment
|
|
From: File iolayer.c
|
|
|
|
=item i_io_set_buffered(io, buffered)
|
|
|
|
Set the buffering mode of the stream.
|
|
|
|
If you switch buffering off on a stream with buffering on:
|
|
|
|
=over
|
|
|
|
=item *
|
|
|
|
any buffered output will be flushed.
|
|
|
|
=item *
|
|
|
|
any existing buffered input will be consumed before reads become
|
|
unbuffered.
|
|
|
|
=back
|
|
|
|
Returns true on success. This may fail if any buffered output cannot
|
|
be flushed.
|
|
|
|
|
|
=for comment
|
|
From: File iolayer.c
|
|
|
|
=item i_io_write(io, buffer, size)
|
|
|
|
ssize_t result = i_io_write(io, buffer, size)
|
|
|
|
Write to the given I/O stream.
|
|
|
|
Returns the number of bytes written.
|
|
|
|
|
|
=for comment
|
|
From: File iolayer.c
|
|
|
|
=item io_slurp(ig, c)
|
|
X<io_slurp API>
|
|
|
|
Takes the source that the io_glue is bound to and allocates space for
|
|
a return buffer and returns the entire content in a single buffer.
|
|
Note: This only works for io_glue objects created by
|
|
io_new_bufchain(). It is useful for saving to scalars and such.
|
|
|
|
ig - io_glue object
|
|
c - pointer to a pointer to where data should be copied to
|
|
|
|
char *data;
|
|
size_t size = io_slurp(ig, &data);
|
|
... do something with the data ...
|
|
myfree(data);
|
|
|
|
io_slurp() will abort the program if the supplied I/O layer is not
|
|
from io_new_bufchain().
|
|
|
|
|
|
=for comment
|
|
From: File iolayer.c
|
|
|
|
=item io_glue_destroy(ig)
|
|
X<io_glue_destroy API>
|
|
|
|
io_glue_destroy(ig);
|
|
|
|
Destroy an io_glue objects. Should clean up all related buffers.
|
|
|
|
ig - io_glue object to destroy.
|
|
|
|
|
|
=for comment
|
|
From: File iolayer.c
|
|
|
|
|
|
=back
|
|
|
|
=head2 Image
|
|
|
|
=over
|
|
|
|
=item i_copy(source)
|
|
|
|
|
|
Creates a new image that is a copy of the image C<source>.
|
|
|
|
Tags are not copied, only the image data.
|
|
|
|
Returns: i_img *
|
|
|
|
|
|
=for comment
|
|
From: File image.c
|
|
|
|
=item i_copyto(C<dest>, C<src>, C<x1>, C<y1>, C<x2>, C<y2>, C<tx>, C<ty>)
|
|
|
|
|
|
Copies image data from the area (C<x1>,C<y1>)-[C<x2>,C<y2>] in the
|
|
source image to a rectangle the same size with it's top-left corner at
|
|
(C<tx>,C<ty>) in the destination image.
|
|
|
|
If C<x1> > C<x2> or C<y1> > C<y2> then the corresponding co-ordinates
|
|
are swapped.
|
|
|
|
|
|
=for comment
|
|
From: File paste.im
|
|
|
|
=item i_copyto_trans(C<im>, C<src>, C<x1>, C<y1>, C<x2>, C<y2>, C<tx>, C<ty>, C<trans>)
|
|
|
|
|
|
(C<x1>,C<y1>) (C<x2>,C<y2>) specifies the region to copy (in the
|
|
source coordinates) (C<tx>,C<ty>) specifies the upper left corner for
|
|
the target image. pass NULL in C<trans> for non transparent i_colors.
|
|
|
|
|
|
=for comment
|
|
From: File image.c
|
|
|
|
=item i_img_info(im, info)
|
|
|
|
|
|
Return image information
|
|
|
|
im - Image pointer
|
|
info - pointer to array to return data
|
|
|
|
info is an array of 4 integers with the following values:
|
|
|
|
info[0] - width
|
|
info[1] - height
|
|
info[2] - channels
|
|
info[3] - channel mask
|
|
|
|
|
|
=for comment
|
|
From: File image.c
|
|
|
|
=item i_rubthru(C<im>, C<src>, C<tx>, C<ty>, C<src_minx>, C<src_miny>, C<src_maxx>, C<src_maxy>)
|
|
|
|
|
|
Takes the sub image C<src>[C<src_minx>, C<src_maxx>)[C<src_miny>, C<src_maxy>)> and
|
|
overlays it at (C<tx>,C<ty>) on the image object.
|
|
|
|
The alpha channel of each pixel in C<src> is used to control how much
|
|
the existing color in C<im> is replaced, if it is 255 then the color
|
|
is completely replaced, if it is 0 then the original color is left
|
|
unmodified.
|
|
|
|
|
|
=for comment
|
|
From: File rubthru.im
|
|
|
|
|
|
=back
|
|
|
|
=head2 Image creation/destruction
|
|
|
|
=over
|
|
|
|
=item i_sametype(C<im>, C<xsize>, C<ysize>)
|
|
|
|
|
|
i_img *img = i_sametype(src, width, height);
|
|
|
|
Returns an image of the same type (sample size, channels, paletted/direct).
|
|
|
|
For paletted images the palette is copied from the source.
|
|
|
|
|
|
=for comment
|
|
From: File image.c
|
|
|
|
=item i_sametype_chans(C<im>, C<xsize>, C<ysize>, C<channels>)
|
|
|
|
|
|
i_img *img = i_sametype_chans(src, width, height, channels);
|
|
|
|
Returns an image of the same type (sample size).
|
|
|
|
For paletted images the equivalent direct type is returned.
|
|
|
|
|
|
=for comment
|
|
From: File image.c
|
|
|
|
=item im_img_16_new(ctx, x, y, ch)
|
|
X<im_img_16_new API>X<i_img_16_new API>
|
|
|
|
i_img *img = im_img_16_new(aIMCTX, width, height, channels);
|
|
i_img *img = i_img_16_new(width, height, channels);
|
|
|
|
Create a new 16-bit/sample image.
|
|
|
|
Returns the image on success, or NULL on failure.
|
|
|
|
Also callable as C<i_img_16_new(x, y, ch)>
|
|
|
|
|
|
=for comment
|
|
From: File img16.c
|
|
|
|
=item im_img_8_new(ctx, x, y, ch)
|
|
X<im_img_8_new API>X<i_img_8_new API>
|
|
|
|
i_img *img = im_img_8_new(aIMCTX, width, height, channels);
|
|
i_img *img = i_img_8_new(width, height, channels);
|
|
|
|
Creates a new image object I<x> pixels wide, and I<y> pixels high with
|
|
I<ch> channels.
|
|
|
|
|
|
=for comment
|
|
From: File img8.c
|
|
|
|
=item im_img_double_new(ctx, x, y, ch)
|
|
X<im_img_double_new API>X<i_img_double_new API>
|
|
|
|
i_img *img = im_img_double_new(aIMCTX, width, height, channels);
|
|
i_img *img = i_img_double_new(width, height, channels);
|
|
|
|
Creates a new double per sample image.
|
|
|
|
Also callable as C<i_img_double_new(width, height, channels)>.
|
|
|
|
|
|
=for comment
|
|
From: File imgdouble.c
|
|
|
|
=item im_img_pal_new(ctx, C<x>, C<y>, C<channels>, C<maxpal>)
|
|
X<im_img_pal_new API>X<i_img_pal_new API>
|
|
|
|
i_img *img = im_img_pal_new(aIMCTX, width, height, channels, max_palette_size)
|
|
i_img *img = i_img_pal_new(width, height, channels, max_palette_size)
|
|
|
|
Creates a new paletted image of the supplied dimensions.
|
|
|
|
C<maxpal> is the maximum palette size and should normally be 256.
|
|
|
|
Returns a new image or NULL on failure.
|
|
|
|
Also callable as C<i_img_pal_new(width, height, channels, max_palette_size)>.
|
|
|
|
|
|
=for comment
|
|
From: File palimg.c
|
|
|
|
=item i_img_destroy(C<img>)
|
|
|
|
i_img_destroy(img)
|
|
|
|
Destroy an image object
|
|
|
|
|
|
=for comment
|
|
From: File image.c
|
|
|
|
|
|
=back
|
|
|
|
=head2 Image Implementation
|
|
|
|
=over
|
|
|
|
=item im_img_alloc(aIMCTX)
|
|
X<im_img_alloc API>X<i_img_alloc API>
|
|
|
|
i_img *im = im_img_alloc(aIMCTX);
|
|
i_img *im = i_img_alloc();
|
|
|
|
Allocates a new i_img structure.
|
|
|
|
When implementing a new image type perform the following steps in your
|
|
image object creation function:
|
|
|
|
=over
|
|
|
|
=item 1.
|
|
|
|
allocate the image with i_img_alloc().
|
|
|
|
=item 2.
|
|
|
|
initialize any function pointers or other data as needed, you can
|
|
overwrite the whole block if you need to.
|
|
|
|
=item 3.
|
|
|
|
initialize Imager's internal data by calling i_img_init() on the image
|
|
object.
|
|
|
|
=back
|
|
|
|
|
|
=for comment
|
|
From: File image.c
|
|
|
|
=item im_img_init(aIMCTX, image)
|
|
X<im_img_init API>X<i_img_init API>
|
|
|
|
im_img_init(aIMCTX, im);
|
|
i_img_init(im);
|
|
|
|
Imager internal initialization of images.
|
|
|
|
See L</im_img_alloc(aIMCTX)> for more information.
|
|
|
|
|
|
=for comment
|
|
From: File image.c
|
|
|
|
|
|
=back
|
|
|
|
=head2 Image Information
|
|
|
|
=over
|
|
|
|
=item i_img_alpha_channel(im, &channel)
|
|
|
|
int alpha_channel;
|
|
int has_alpha = i_img_alpha_channel(im, &alpha_channel);
|
|
|
|
Work out the alpha channel for an image.
|
|
|
|
If the image has an alpha channel, sets C<*channel> to the alpha
|
|
channel index and returns non-zero.
|
|
|
|
If the image has no alpha channel, returns zero and C<*channel> is not
|
|
modified.
|
|
|
|
C<channel> may be C<NULL>.
|
|
|
|
|
|
=for comment
|
|
From: File image.c
|
|
|
|
=item i_img_color_channels(im)
|
|
|
|
int color_channels = i_img_color_channels(im);
|
|
|
|
Returns the number of color channels in the image. For now this is
|
|
always 1 (for grayscale) or 3 (for RGB) but may be 0 in some special
|
|
cases in a future release of Imager.
|
|
|
|
|
|
=for comment
|
|
From: File image.c
|
|
|
|
=item i_img_color_model(im)
|
|
|
|
i_color_model_t cm = i_img_color_model(im);
|
|
|
|
Returns the color model for the image.
|
|
|
|
A future version of Imager will allow for images with extra channels
|
|
beyond gray/rgb and alpha.
|
|
|
|
|
|
=for comment
|
|
From: File image.c
|
|
|
|
=item i_img_get_height(C<im>)
|
|
|
|
i_img_dim height = i_img_get_height(im);
|
|
|
|
Returns the height in pixels of the image.
|
|
|
|
|
|
=for comment
|
|
From: File image.c
|
|
|
|
=item i_img_get_width(C<im>)
|
|
|
|
i_img_dim width = i_img_get_width(im);
|
|
|
|
Returns the width in pixels of the image.
|
|
|
|
|
|
=for comment
|
|
From: File image.c
|
|
|
|
=item i_img_getchannels(C<im>)
|
|
|
|
int channels = i_img_getchannels(img);
|
|
|
|
Get the number of channels in C<im>.
|
|
|
|
|
|
=for comment
|
|
From: File image.c
|
|
|
|
=item i_img_getmask(C<im>)
|
|
|
|
int mask = i_img_getmask(img);
|
|
|
|
Get the image channel mask for C<im>.
|
|
|
|
|
|
=for comment
|
|
From: File image.c
|
|
|
|
=item i_img_has_alpha(C<im>)
|
|
|
|
|
|
Return true if the image has an alpha channel.
|
|
|
|
|
|
=for comment
|
|
From: File immacros.h
|
|
|
|
=item i_img_is_monochrome(img, &zero_is_white)
|
|
|
|
|
|
Tests an image to check it meets our monochrome tests.
|
|
|
|
The idea is that a file writer can use this to test where it should
|
|
write the image in whatever bi-level format it uses, eg. C<pbm> for
|
|
C<pnm>.
|
|
|
|
For performance of encoders we require monochrome images:
|
|
|
|
=over
|
|
|
|
=item *
|
|
|
|
be paletted
|
|
|
|
=item *
|
|
|
|
have a palette of two colors, containing only C<(0,0,0)> and
|
|
C<(255,255,255)> in either order.
|
|
|
|
=back
|
|
|
|
C<zero_is_white> is set to non-zero if the first palette entry is white.
|
|
|
|
|
|
=for comment
|
|
From: File image.c
|
|
|
|
=item i_img_setmask(C<im>, C<ch_mask>)
|
|
|
|
// only channel 0 writable
|
|
i_img_setmask(img, 0x01);
|
|
|
|
Set the image channel mask for C<im> to C<ch_mask>.
|
|
|
|
The image channel mask gives some control over which channels can be
|
|
written to in the image.
|
|
|
|
|
|
=for comment
|
|
From: File image.c
|
|
|
|
|
|
=back
|
|
|
|
=head2 Image quantization
|
|
|
|
=over
|
|
|
|
=item i_quant_makemap(C<quant>, C<imgs>, C<count>)
|
|
|
|
|
|
Analyzes the C<count> images in C<imgs> according to the rules in
|
|
C<quant> to build a color map (optimal or not depending on
|
|
C<< quant->make_colors >>).
|
|
|
|
|
|
=for comment
|
|
From: File quant.c
|
|
|
|
=item i_quant_translate(C<quant>, C<img>)
|
|
|
|
|
|
Quantize the image given the palette in C<quant>.
|
|
|
|
On success returns a pointer to a memory block of C<< img->xsize *
|
|
img->ysize >> C<i_palidx> entries.
|
|
|
|
On failure returns NULL.
|
|
|
|
You should call myfree() on the returned block when you're done with
|
|
it.
|
|
|
|
This function will fail if the supplied palette contains no colors.
|
|
|
|
|
|
=for comment
|
|
From: File quant.c
|
|
|
|
=item i_quant_transparent(C<quant>, C<data>, C<img>, C<trans_index>)
|
|
|
|
|
|
Dither the alpha channel on C<img> into the palette indexes in
|
|
C<data>. Pixels to be transparent are replaced with C<trans_pixel>.
|
|
|
|
The method used depends on the tr_* members of C<quant>.
|
|
|
|
|
|
=for comment
|
|
From: File quant.c
|
|
|
|
|
|
=back
|
|
|
|
=head2 Logging
|
|
|
|
=over
|
|
|
|
=item i_lhead(file, line)
|
|
|
|
This is an internal function called by the mm_log() macro.
|
|
|
|
|
|
=for comment
|
|
From: File log.c
|
|
|
|
=item i_loog(level, format, ...)
|
|
|
|
This is an internal function called by the mm_log() macro.
|
|
|
|
|
|
=for comment
|
|
From: File log.c
|
|
|
|
|
|
=back
|
|
|
|
=head2 mutex
|
|
|
|
=over
|
|
|
|
=item i_mutex_t
|
|
X<i_mutex>
|
|
|
|
i_mutex_t mutex;
|
|
|
|
Opaque type for Imager's mutex API.
|
|
|
|
|
|
=for comment
|
|
From: File imdatatypes.h
|
|
|
|
|
|
=back
|
|
|
|
=head2 Mutex functions
|
|
|
|
=over
|
|
|
|
=item i_mutex_new()
|
|
|
|
i_mutex_t m = i_mutex_new();
|
|
|
|
Create a mutex.
|
|
|
|
If a critical section cannot be created for whatever reason, Imager
|
|
will abort.
|
|
|
|
|
|
=for comment
|
|
From: File mutexwin.c
|
|
|
|
=item i_mutex_destroy(m)
|
|
|
|
i_mutex_destroy(m);
|
|
|
|
Destroy a mutex.
|
|
|
|
|
|
=for comment
|
|
From: File mutexwin.c
|
|
|
|
=item i_mutex_lock(m)
|
|
|
|
i_mutex_lock(m);
|
|
|
|
Lock the mutex, waiting if another thread has the mutex locked.
|
|
|
|
|
|
=for comment
|
|
From: File mutexwin.c
|
|
|
|
=item i_mutex_unlock(m)
|
|
|
|
i_mutex_unlock(m);
|
|
|
|
Release the mutex.
|
|
|
|
The behavior of releasing a mutex you don't hold is unspecified.
|
|
|
|
|
|
=for comment
|
|
From: File mutexwin.c
|
|
|
|
|
|
=back
|
|
|
|
=head2 Paletted images
|
|
|
|
=over
|
|
|
|
=item i_addcolors(im, colors, count)
|
|
|
|
|
|
Adds colors to the image's palette.
|
|
|
|
On success returns the index of the lowest color added.
|
|
|
|
On failure returns -1.
|
|
|
|
Always fails for direct color images.
|
|
|
|
|
|
=for comment
|
|
From: File imext.c
|
|
|
|
=item i_colorcount(im)
|
|
|
|
|
|
Returns the number of colors in the image's palette.
|
|
|
|
Returns -1 for direct images.
|
|
|
|
|
|
=for comment
|
|
From: File imext.c
|
|
|
|
=item i_findcolor(im, color, &entry)
|
|
|
|
|
|
Searches the images palette for the given color.
|
|
|
|
On success sets *I<entry> to the index of the color, and returns true.
|
|
|
|
On failure returns false.
|
|
|
|
Always fails on direct color images.
|
|
|
|
|
|
=for comment
|
|
From: File imext.c
|
|
|
|
=item i_getcolors(im, index, colors, count)
|
|
|
|
|
|
Retrieves I<count> colors starting from I<index> in the image's
|
|
palette.
|
|
|
|
On success stores the colors into I<colors> and returns true.
|
|
|
|
On failure returns false.
|
|
|
|
Always fails for direct color images.
|
|
|
|
Fails if there are less than I<index>+I<count> colors in the image's
|
|
palette.
|
|
|
|
|
|
=for comment
|
|
From: File imext.c
|
|
|
|
=item i_maxcolors(im)
|
|
|
|
|
|
Returns the maximum number of colors the palette can hold for the
|
|
image.
|
|
|
|
Returns -1 for direct color images.
|
|
|
|
|
|
=for comment
|
|
From: File imext.c
|
|
|
|
=item i_setcolors(im, index, colors, count)
|
|
|
|
|
|
Sets I<count> colors starting from I<index> in the image's palette.
|
|
|
|
On success returns true.
|
|
|
|
On failure returns false.
|
|
|
|
The image must have at least I<index>+I<count> colors in it's palette
|
|
for this to succeed.
|
|
|
|
Always fails on direct color images.
|
|
|
|
|
|
=for comment
|
|
From: File imext.c
|
|
|
|
|
|
=back
|
|
|
|
=head2 Tags
|
|
|
|
=over
|
|
|
|
=item i_tags_delbycode(tags, code)
|
|
|
|
|
|
Delete any tags with the given code.
|
|
|
|
Returns the number of tags deleted.
|
|
|
|
|
|
=for comment
|
|
From: File tags.c
|
|
|
|
=item i_tags_delbyname(tags, name)
|
|
|
|
|
|
Delete any tags with the given name.
|
|
|
|
Returns the number of tags deleted.
|
|
|
|
|
|
=for comment
|
|
From: File tags.c
|
|
|
|
=item i_tags_delete(tags, index)
|
|
|
|
|
|
Delete a tag by index.
|
|
|
|
Returns true on success.
|
|
|
|
|
|
=for comment
|
|
From: File tags.c
|
|
|
|
=item i_tags_destroy(tags)
|
|
|
|
|
|
Destroys the given tags structure. Called by i_img_destroy().
|
|
|
|
|
|
=for comment
|
|
From: File tags.c
|
|
|
|
=item i_tags_find(tags, name, start, &entry)
|
|
|
|
|
|
Searches for a tag of the given I<name> starting from index I<start>.
|
|
|
|
On success returns true and sets *I<entry>.
|
|
|
|
On failure returns false.
|
|
|
|
|
|
=for comment
|
|
From: File tags.c
|
|
|
|
=item i_tags_findn(tags, code, start, &entry)
|
|
|
|
|
|
Searches for a tag of the given I<code> starting from index I<start>.
|
|
|
|
On success returns true and sets *I<entry>.
|
|
|
|
On failure returns false.
|
|
|
|
|
|
=for comment
|
|
From: File tags.c
|
|
|
|
=item i_tags_get_color(tags, name, code, &value)
|
|
|
|
|
|
Retrieve a tag specified by name or code as color.
|
|
|
|
On success sets the i_color *I<value> to the color and returns true.
|
|
|
|
On failure returns false.
|
|
|
|
|
|
=for comment
|
|
From: File tags.c
|
|
|
|
=item i_tags_get_float(tags, name, code, value)
|
|
|
|
|
|
Retrieves a tag as a floating point value.
|
|
|
|
If the tag has a string value then that is parsed as a floating point
|
|
number, otherwise the integer value of the tag is used.
|
|
|
|
On success sets *I<value> and returns true.
|
|
|
|
On failure returns false.
|
|
|
|
|
|
=for comment
|
|
From: File tags.c
|
|
|
|
=item i_tags_get_int(tags, name, code, &value)
|
|
|
|
|
|
Retrieve a tag specified by name or code as an integer.
|
|
|
|
On success sets the int *I<value> to the integer and returns true.
|
|
|
|
On failure returns false.
|
|
|
|
|
|
=for comment
|
|
From: File tags.c
|
|
|
|
=item i_tags_get_string(tags, name, code, value, value_size)
|
|
|
|
|
|
Retrieves a tag by name or code as a string.
|
|
|
|
On success copies the string to value for a max of value_size and
|
|
returns true.
|
|
|
|
On failure returns false.
|
|
|
|
value_size must be at least large enough for a string representation
|
|
of an integer.
|
|
|
|
The copied value is always C<NUL> terminated.
|
|
|
|
|
|
=for comment
|
|
From: File tags.c
|
|
|
|
=item i_tags_new(i_img_tags *tags)
|
|
|
|
|
|
Initialize a tags structure. Should not be used if the tags structure
|
|
has been previously used.
|
|
|
|
This should be called tags member of an i_img object on creation (in
|
|
i_img_*_new() functions).
|
|
|
|
To destroy the contents use i_tags_destroy()
|
|
|
|
|
|
=for comment
|
|
From: File tags.c
|
|
|
|
=item i_tags_set(tags, name, data, size)
|
|
|
|
i_tags_set(&img->tags, "i_comment", -1);
|
|
|
|
Sets the given tag to the string I<data>
|
|
|
|
If size is -1 then the strlen(I<data>) bytes are stored.
|
|
|
|
Even on failure, if an existing tag I<name> exists, it will be
|
|
removed.
|
|
|
|
|
|
=for comment
|
|
From: File tags.c
|
|
|
|
=item i_tags_set_color(tags, name, code, &value)
|
|
|
|
|
|
Stores the given color as a tag with the given name and code.
|
|
|
|
|
|
=for comment
|
|
From: File tags.c
|
|
|
|
=item i_tags_set_float(tags, name, code, value)
|
|
|
|
|
|
Equivalent to i_tags_set_float2(tags, name, code, value, 30).
|
|
|
|
|
|
=for comment
|
|
From: File tags.c
|
|
|
|
=item i_tags_set_float2(tags, name, code, value, places)
|
|
|
|
|
|
Sets the tag with the given name and code to the given floating point
|
|
value.
|
|
|
|
Since tags are strings or ints, we convert the value to a string before
|
|
storage at the precision specified by C<places>.
|
|
|
|
|
|
=for comment
|
|
From: File tags.c
|
|
|
|
=item i_tags_setn(C<tags>, C<name>, C<idata>)
|
|
|
|
i_tags_setn(&img->tags, "i_xres", 204);
|
|
i_tags_setn(&img->tags, "i_yres", 196);
|
|
|
|
Sets the given tag to the integer C<idata>
|
|
|
|
Even on failure, if an existing tag C<name> exists, it will be
|
|
removed.
|
|
|
|
|
|
=for comment
|
|
From: File tags.c
|
|
|
|
|
|
=back
|
|
|
|
=head2 Uncategorized functions
|
|
|
|
=over
|
|
|
|
=item i_utf8_advance(char **p, size_t *len)
|
|
|
|
Retrieve a C<UTF-8> character from the stream.
|
|
|
|
Modifies *p and *len to indicate the consumed characters.
|
|
|
|
This doesn't support the extended C<UTF-8> encoding used by later
|
|
versions of Perl. Since this is typically used to implement text
|
|
output by font drivers, the strings supplied shouldn't have such out
|
|
of range characters.
|
|
|
|
This doesn't check that the C<UTF-8> character is using the shortest
|
|
possible representation.
|
|
|
|
Returns ~0UL on failure.
|
|
|
|
|
|
=for comment
|
|
From: File io.c
|
|
|
|
=item im_context_refdec(ctx, where)
|
|
X<im_context_refdec API>
|
|
=section Context objects
|
|
|
|
im_context_refdec(aIMCTX, "a description");
|
|
|
|
Remove a reference to the context, releasing it if all references have
|
|
been removed.
|
|
|
|
|
|
=for comment
|
|
From: File context.c
|
|
|
|
=item im_context_refinc(ctx, where)
|
|
X<im_context_refinc API>
|
|
=section Context objects
|
|
|
|
im_context_refinc(aIMCTX, "a description");
|
|
|
|
Add a new reference to the context.
|
|
|
|
|
|
=for comment
|
|
From: File context.c
|
|
|
|
=item im_context_slot_get(ctx, slot)
|
|
|
|
Retrieve the value previously stored in the given slot of the context
|
|
object.
|
|
|
|
|
|
=for comment
|
|
From: File context.c
|
|
|
|
=item im_context_slot_new(destructor)
|
|
|
|
Allocate a new context-local-storage slot.
|
|
|
|
C<desctructor> will be called when the context is destroyed if the
|
|
corresponding slot is non-NULL.
|
|
|
|
|
|
=for comment
|
|
From: File context.c
|
|
|
|
=item im_context_slot_set(slot, value)
|
|
|
|
Set the value of a slot.
|
|
|
|
Returns true on success.
|
|
|
|
Aborts if the slot supplied is invalid.
|
|
|
|
If reallocation of slot storage fails, returns false.
|
|
|
|
|
|
=for comment
|
|
From: File context.c
|
|
|
|
=item im_decode_exif
|
|
|
|
im_decode_exif(im, data_base, data_size);
|
|
|
|
The data from C<data_base> for C<data_size> bytes will be scanned for
|
|
EXIF data.
|
|
|
|
Any data found will be used to set tags in the supplied image.
|
|
|
|
The intent is that invalid EXIF data will simply fail to set tags, and
|
|
write to the log. In no case should this code exit when supplied
|
|
invalid data.
|
|
|
|
Returns true if an EXIF header was seen.
|
|
|
|
|
|
=for comment
|
|
From: File imexif.c
|
|
|
|
=item im_errors(ctx)
|
|
|
|
i_errmsg *errors = im_errors(aIMCTX);
|
|
i_errmsg *errors = i_errors();
|
|
|
|
Returns a pointer to the first element of an array of error messages,
|
|
terminated by a NULL pointer. The highest level message is first.
|
|
|
|
Also callable as C<i_errors()>.
|
|
|
|
|
|
=for comment
|
|
From: File error.c
|
|
|
|
=item im_get_context()
|
|
|
|
Retrieve the context object for the current thread.
|
|
|
|
Inside Imager itself this is just a function pointer, which the
|
|
F<Imager.xs> BOOT handler initializes for use within perl. If you're
|
|
taking the Imager code and embedding it elsewhere you need to
|
|
initialize the C<im_get_context> pointer at some point.
|
|
|
|
|
|
=for comment
|
|
From: File imext.c
|
|
|
|
|
|
|
|
=back
|
|
|
|
|
|
=head1 UNDOCUMENTED
|
|
|
|
The following API functions are undocumented so far, hopefully this
|
|
will change:
|
|
|
|
=over
|
|
|
|
=item *
|
|
|
|
B<im_lhead>
|
|
|
|
=item *
|
|
|
|
B<im_loog>
|
|
|
|
=item *
|
|
|
|
B<mm_log>
|
|
|
|
|
|
|
|
=back
|
|
|
|
|
|
=head1 AUTHOR
|
|
|
|
Tony Cook <tonyc@cpan.org>
|
|
|
|
=head1 SEE ALSO
|
|
|
|
Imager, Imager::API, Imager::ExtUtils, Imager::Inline
|
|
|
|
=cut
|