Imager::APIRef(3) User Contributed Perl Documentation Imager::APIRef(3)NAMEImager::APIRef - Imager's C API - reference.
SYNOPSIS
i_color color;
color.rgba.r = 255; color.rgba.g = 0; color.rgba.b = 255;
# Blit tools
# Data Types
i_img *img;
i_color black;
black.rgba.r = black.rgba.g = black.rgba.b = black.rgba.a = 0;
i_fill_t *fill;
i_img_dim x, y;
printf("left %" i_DF "\n", i_DFc(x));
printf("point (" i_DFp ")\n", i_DFcp(x, y));
# Drawing
i_arc(im, 50, 50, 20, 45, 135, &color);
i_arc_cfill(im, 50, 50, 35, 90, 135, fill);
i_arc_aa(im, 50, 50, 35, 90, 135, &color);
i_arc_aa_cfill(im, 50, 50, 35, 90, 135, fill);
i_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
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);
# Image quantization
# Logging
# 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);
DESCRIPTION
Blit tools
i_render_color(r, x, y, width, source, color)
Render the given color with the coverage specified by "source[0]"
to "source[width-1]".
Renders in normal combine mode.
i_render_delete(r)
Release an "i_render" object.
i_render_fill(r, x, y, width, source, fill)
Render the given fill with the coverage in "source[0]" through
"source[width-1]".
i_render_line(r, x, y, width, source, fill)
Render the given fill with the coverage in "source[0]" through
"source[width-1]".
i_render_linef(r, x, y, width, source, fill)
Render the given fill with the coverage in "source[0]" through
"source[width-1]".
i_render_new(im, width)
Allocate a new "i_render" object and initialize it.
Data Types
i_img
i_img *img;
This is Imager's image type.
It contains the following members:
· "channels" - the number of channels in the image
· "xsize", "ysize" - the width and height of the image in pixels
· "bytes" - the number of bytes used to store the image data.
Undefined where virtual is non-zero.
· "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.
· "bits" - the number of bits stored per sample. Should be one
of i_8_bits, i_16_bits, i_double_bits.
· "type" - either i_direct_type for direct color images, or
i_palette_type for paletted images.
· "virtual" - if zero then this image is-self contained. If non-
zero then this image could be an interface to some other
implementation.
· "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.
· "tags" - a structure storing the image's tags. This should
only be accessed via the i_tags_*() functions.
· "ext_data" - a pointer for use internal to an image
implementation. This should be freed by the image's destroy
handler.
· "im_data" - data internal to Imager. This is initialized by
i_img_init().
· 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().
· 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.
· i_f_destroy - custom image destruction function. This should
be used to release memory if necessary.
· i_f_gsamp_bits - implements i_gsamp_bits() for this image.
· i_f_psamp_bits - implements i_psamp_bits() for this image.
· i_f_psamp - implements psamp() for this image.
· i_f_psampf - implements psamp() for this image.
· "im_data" - image specific data internal to Imager.
· "context" - the Imager API context this image belongs to.
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:
· gray - contains a single element gray_color, eg.
"c.gray.gray_color"
· "rgb" - contains three elements "r", "g", "b", eg. "c.rgb.r"
· "rgba" - contains four elements "r", "g", "b", "a", eg.
"c.rgba.a"
· "cmyk" - contains four elements "c", "m", "y", "k", eg.
"c.cmyk.y". Note that Imager never uses CMYK colors except
when reading/writing files.
· channels - an array of four channels, eg "c.channels[2]".
i_fcolor
This is the double/sample color type.
Its layout exactly corresponds to i_color.
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.
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.
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 "%".
i_DFc
Cast an "i_img_dim" value to a type for use with the i_DF format
string.
i_DFcp
Casts two "i_img_dim" values for use with the i_DF (or i_DFp)
format.
i_DFp
printf("point (" i_DFp ")\n", i_DFcp(x, y));
Format a pair of "i_img_dim" values. This format string does
include the leading "%".
Drawing
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 rad covering the range
of angles in degrees from d1 to d2, with the color.
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 rad covering
the range of angles in degrees from d1 to d2, with the color.
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 rad covering
the range of angles in degrees from d1 to d2, with the fill object.
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 rad covering the range
of angles in degrees from d1 to d2, with the fill object.
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 color.
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.
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.
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 rad with
color.
i_flood_cfill("im", "seedx", "seedy", "fill")
i_flood_cfill(im, 50, 50, fill);
Flood fills the 4-connected region starting from the point
("seedx", "seedy") with "fill".
Returns false if ("seedx", "seedy") are outside the image.
i_flood_cfill_border("im", "seedx", "seedy", "fill", "border")
i_flood_cfill_border(im, 50, 50, fill, border);
Flood fills the 4-connected region starting from the point
("seedx", "seedy") with "fill", the fill stops when it reaches
pixels of color "border".
Returns false if ("seedx", "seedy") are outside the image.
i_flood_fill("im", "seedx", "seedy", "color")
i_flood_fill(im, 50, 50, &color);
Flood fills the 4-connected region starting from the point
("seedx", "seedy") with color.
Returns false if ("seedx", "seedy") are outside the image.
i_flood_fill_border("im", "seedx", "seedy", "color", "border")
i_flood_fill_border(im, 50, 50, &color, &border);
Flood fills the 4-connected region starting from the point
("seedx", "seedy") with "color", fill stops when the fill reaches a
pixels with color "border".
Returns false if ("seedx", "seedy") are outside the image.
i_glin(im, l, r, y, colors)
Retrieves (r-l) pixels starting from (l,y) into colors.
Returns the number of pixels retrieved.
i_glinf(im, l, r, y, colors)
Retrieves (r-l) pixels starting from (l,y) into colors as floating
point colors.
Returns the number of pixels retrieved.
i_gpal(im, left, right, y, indexes)
Reads palette indexes for the horizontal line (left, y) to
(right-1, y) into "indexes".
Returns the number of indexes read.
Always returns 0 for direct color images.
i_gpix(im, "x", "y", "color")
Retrieves the "color" of the pixel (x,y).
Returns 0 if the pixel was retrieved, or -1 if not.
i_gpixf(im, "x", "y", "fcolor")
Retrieves the color of the pixel (x,y) as a floating point color
into "fcolor".
Returns 0 if the pixel was retrieved, or -1 if not.
i_gsamp(im, left, right, y, samples, channels, channel_count)
Reads sample values from "im" for the horizontal line (left, y) to
(right-1,y) for the channels specified by "channels", an array of
int with "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)
i_gsamp_bg(im, l, r, y, samples, out_channels, background)
Like "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.
i_gsamp_bits(im, left, right, y, samples, channels, channel_count,
bits)
Reads integer samples scaled to "bits" bits of precision into the
"unsigned int" array "samples".
Expect this to be slow unless "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 "i_clear_error()".
i_gsampf(im, left, right, y, samples, channels, channel_count)
Reads floating point sample values from "im" for the horizontal
line (left, y) to (right-1,y) for the channels specified by
"channels", an array of int with channel_count elements.
If "channels" is NULL then the first "channel_count" channels are
retrieved for each pixel.
Returns the number of samples read (which should be
("right"-"left") * "channel_count")
i_gsampf_bg(im, l, r, y, samples, out_channels, background)
Like "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.
i_line("im", "x1", "y1", "x2", "y2", "color", "endp")
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)
i_line_aa("im", "x1", "x2", "y1", "y2", "color", "endp")
Anti-alias draws a line from (x1,y1) to (x2, y2) in color.
The point (x2, y2) is drawn only if "endp" is set.
i_plin(im, l, r, y, colors)
Sets (r-l) pixels starting from (l,y) using (r-l) values from
colors.
Returns the number of pixels set.
i_plinf(im, "left", "right", "fcolors")
Sets (right-left) pixels starting from (left,y) using (right-left)
floating point colors from "fcolors".
Returns the number of pixels set.
i_ppal(im, left, right, y, indexes)
Writes palette indexes for the horizontal line (left, y) to
(right-1, y) from "indexes".
Returns the number of indexes written.
Always returns 0 for direct color images.
i_ppix(im, x, y, color)
Sets the pixel at (x,y) to 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.
i_ppixf(im, "x", "y", "fcolor")
Sets the pixel at ("x","y") to the floating point color "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.
i_psamp(im, left, right, y, samples, channels, channel_count)
Writes sample values from "samples" to "im" for the horizontal line
(left, y) to (right-1, y) inclusive for the channels specified by
"channels", an array of "int" with "channel_count" elements.
If "channels" is "NULL" then the first "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.
i_psamp_bits(im, left, right, y, samples, channels, channel_count,
bits)
Writes integer samples scaled to "bits" bits of precision from the
"unsigned int" array "samples".
Expect this to be slow unless "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 "i_clear_error()".
i_psampf(im, left, right, y, samples, channels, channel_count)
Writes floating point sample values from "samples" to "im" for the
horizontal line (left, y) to (right-1, y) inclusive for the
channels specified by "channels", an array of "int" with
"channel_count" elements.
If "channels" is "NULL" then the first "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.
Error handling
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.
im_clear_error(ctx)im_clear_error(aIMCTX);
i_clear_error();
Clears the error stack.
Called by any Imager function before doing any other processing.
Also callable as "i_clear_error()".
im_push_error(ctx, code, message)
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.).
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.
im_push_errorvf(ctx, code, format, args)
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 "i_push_errorvf(code, format, args)"
Files
i_get_file_background(im, &bg)
Retrieve the file write background color tag from the image.
If not present, "bg" is set to black.
Returns 1 if the "i_background" tag was found and valid.
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, "bg" is set to black.
Returns 1 if the "i_background" tag was found and valid.
im_get_image_file_limits(ctx, &width, &height, &bytes)
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().
· i_img_dim *width, *height - the maximum width and height of the
image.
· size_t *bytes - size in memory of the image in bytes.
Also callable as "i_get_image_file_limits(&width, &height,
&bytes)".
im_int_check_image_file_limits(width, height, channels, sample_size)
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 "i_int_check_image_file_limits(width, height,
channels, sizeof(i_sample_t)".
im_set_image_file_limits(ctx, width, height, bytes)
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:
· i_img_dim width, height - maximum width and height.
· size_t bytes - maximum size in memory in bytes. A value of
zero sets this limit to one gigabyte.
Returns non-zero on success.
Also callable as "i_set_image_file_limits(width, height, bytes)".
Fills
i_new_fill_fount("xa", "ya", "xb", "yb", "type", "repeat", "combine",
"super_sample", "ssample_param", "count", "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.
i_new_fill_hatch("fg", "bg", "combine", "hatch", "cust_hatch", "dx",
"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 "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
hatch adjoining areas out of alignment, or to align the origin of a
hatch with the the side of a filled area.
i_new_fill_hatchf("fg", "bg", "combine", "hatch", "cust_hatch", "dx",
"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 "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
hatch adjoining areas out of alignment, or to align the origin of a
hatch with the the side of a filled area.
i_new_fill_image("im", "matrix", "xoff", "yoff", "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.
"xoff" and "yoff" are the offset into the image to start filling
from.
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.
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.
i_fill_destroy(fill)i_fill_destroy(fill);
Call to destroy any fill object.
I/O Layers
im_io_new_bufchain(ctx)
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 "io_new_bufchain()".
im_io_new_buffer(ctx, data, length)
Returns a new io_glue object that has the source defined as reading
from specified buffer. Note that the buffer is not copied.
ctx - an Imager context object
data - buffer to read from
length - length of buffer
Also callable as "io_new_buffer(data, length".
im_io_new_cb(ctx, p, read_cb, write_cb, seek_cb, close_cb, destroy_cb)
Create a new I/O layer object that calls your supplied callbacks.
In general the callbacks should behave like the corresponding POSIX
primitives.
· "read_cb"(p, buffer, length) should read up to "length" bytes
into "buffer" and return the number of bytes read. At end of
file, return 0. On error, return -1.
· "write_cb"(p, buffer, length) should write up to "length" bytes
from "buffer" and return the number of bytes written. A return
value <= 0 will be treated as an error.
· "seekcb"(p, offset, whence) should seek and return the new
offset.
· "close_cb"(p) should return 0 on success, -1 on failure.
· "destroy_cb"(p) should release any memory specific to your
callback handlers.
Also callable as "io_new_cb(p, readcb, writecb, seekcb, closecb,
destroycb)".
im_io_new_fd(ctx, file)
Returns a new io_glue object that has the source defined as reading
from specified file descriptor. Note that the the interface to
receiving data from the io_glue callbacks hasn't been done yet.
ctx - and Imager context object
file - file descriptor to read/write from
Also callable as "io_new_fd(file)".
i_io_close(io)
Flush any pending output and perform the close action for the
stream.
Returns 0 on success.
i_io_flush(io)
Flush any buffered output.
Returns true on success,
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.
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 "size"-1 bytes from the stream "ig" into "buffer".
If the byte "end_of_line" is seen then no further bytes will be
read.
Returns the number of bytes read.
Always "NUL" terminates the buffer.
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.
i_io_peekn(ig, buffer, size)
ssize_t count = i_io_peekn(ig, buffer, sizeof(buffer));
Buffer at least "size" (at most "ig->buf_size" bytes of data from
the stream and return "size" bytes of it to the caller in "buffer".
This ignores the buffered state of the stream, and will always
setup buffering if needed.
If no "type" parameter is provided to Imager::read() or
Imager::read_multi(), Imager will call "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 "buffer".
i_io_putc(ig, c)
Write a single character to the stream.
On success return c, on error returns EOF
i_io_read(io, buffer, size)
Read up to "size" bytes from the stream "io" into "buffer".
Returns the number of bytes read. Returns 0 on end of file.
Returns -1 on error.
i_io_seek(io, offset, whence)
Seek within the stream.
Acts like perl's seek.
i_io_set_buffered(io, buffered)
Set the buffering mode of the stream.
If you switch buffering off on a stream with buffering on:
· any buffered output will be flushed.
· any existing buffered input will be consumed before reads
become unbuffered.
Returns true on success. This may fail if any buffered output
cannot be flushed.
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.
io_slurp(ig, c)
Takes the source that the io_glue is bound to and allocates space
for a return buffer and returns the entire content in a single
buffer. Note: This only works for io_glue objects created by
io_new_bufchain(). It is useful for saving to scalars and such.
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().
io_glue_destroy(ig)io_glue_destroy(ig);
Destroy an io_glue objects. Should clean up all related buffers.
ig - io_glue object to destroy.
Image
i_copy(source)
Creates a new image that is a copy of the image "source".
Tags are not copied, only the image data.
Returns: i_img *
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.
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.
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
i_rubthru("im", "src", "tx", "ty", "src_minx", "src_miny", "src_maxx",
"src_maxy")
Takes the sub image "src"["src_minx", "src_maxx")["src_miny",
"src_maxy")> and overlays it at ("tx","ty") on the image object.
The alpha channel of each pixel in "src" is used to control how
much the existing color in "im" is replaced, if it is 255 then the
color is completely replaced, if it is 0 then the original color is
left unmodified.
Image creation/destruction
i_sametype("im", "xsize", "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.
i_sametype_chans("im", "xsize", "ysize", "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.
im_img_16_new(ctx, x, y, ch)
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 "i_img_16_new(x, y, ch)"
im_img_8_new(ctx, x, y, ch)
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 x pixels wide, and y pixels high with ch
channels.
im_img_double_new(ctx, x, y, ch)
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 "i_img_double_new(width, height, channels)".
im_img_pal_new(ctx, "x", "y", "channels", "maxpal")
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.
"maxpal" is the maximum palette size and should normally be 256.
Returns a new image or NULL on failure.
Also callable as "i_img_pal_new(width, height, channels,
max_palette_size)".
i_img_destroy("img")
i_img_destroy(img)
Destroy an image object
Image Implementation
im_img_alloc(aIMCTX)
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:
1. allocate the image with i_img_alloc().
2. initialize any function pointers or other data as needed, you
can overwrite the whole block if you need to.
3. initialize Imager's internal data by calling i_img_init() on
the image object.
im_img_init(aIMCTX, image)
im_img_init(aIMCTX, im);
i_img_init(im);
Imager internal initialization of images.
See "im_img_alloc(aIMCTX)" for more information.
Image Information
i_img_color_channels("im")
The number of channels holding color information.
i_img_get_height("im")
i_img_dim height = i_img_get_height(im);
Returns the height in pixels of the image.
i_img_get_width("im")
i_img_dim width = i_img_get_width(im);
Returns the width in pixels of the image.
i_img_getchannels("im")
int channels = i_img_getchannels(img);
Get the number of channels in "im".
i_img_getmask("im")
int mask = i_img_getmask(img);
Get the image channel mask for "im".
i_img_has_alpha("im")
Return true if the image has an alpha channel.
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. "pbm" for
"pnm".
For performance of encoders we require monochrome images:
· be paletted
· have a palette of two colors, containing only "(0,0,0)" and
"(255,255,255)" in either order.
"zero_is_white" is set to non-zero if the first palette entry is
white.
i_img_setmask("im", "ch_mask")
// only channel 0 writable
i_img_setmask(img, 0x01);
Set the image channel mask for "im" to "ch_mask".
The image channel mask gives some control over which channels can
be written to in the image.
Image quantization
i_quant_makemap("quant", "imgs", "count")
Analyzes the "count" images in "imgs" according to the rules in
"quant" to build a color map (optimal or not depending on
"quant->make_colors").
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.
i_quant_transparent("quant", "data", "img", "trans_index")
Dither the alpha channel on "img" into the palette indexes in
"data". Pixels to be transparent are replaced with "trans_pixel".
The method used depends on the tr_* members of "quant".
Logging
i_lhead(file, line)
This is an internal function called by the mm_log() macro.
i_loog(level, format, ...)
This is an internal function called by the mm_log() macro.
Mutex functions
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.
i_mutex_destroy(m)i_mutex_destroy(m);
Destroy a mutex.
i_mutex_lock(m)i_mutex_lock(m);
Lock the mutex, waiting if another thread has the mutex locked.
i_mutex_unlock(m)i_mutex_unlock(m);
Release the mutex.
The behavior of releasing a mutex you don't hold is unspecified.
Paletted images
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.
i_colorcount(im)
Returns the number of colors in the image's palette.
Returns -1 for direct images.
i_findcolor(im, color, &entry)
Searches the images palette for the given color.
On success sets *entry to the index of the color, and returns true.
On failure returns false.
Always fails on direct color images.
i_getcolors(im, index, colors, count)
Retrieves count colors starting from index in the image's palette.
On success stores the colors into colors and returns true.
On failure returns false.
Always fails for direct color images.
Fails if there are less than index+count colors in the image's
palette.
i_maxcolors(im)
Returns the maximum number of colors the palette can hold for the
image.
Returns -1 for direct color images.
i_setcolors(im, index, colors, count)
Sets count colors starting from index in the image's palette.
On success returns true.
On failure returns false.
The image must have at least index+count colors in it's palette for
this to succeed.
Always fails on direct color images.
Tags
i_tags_delbycode(tags, code)
Delete any tags with the given code.
Returns the number of tags deleted.
i_tags_delbyname(tags, name)
Delete any tags with the given name.
Returns the number of tags deleted.
i_tags_delete(tags, index)
Delete a tag by index.
Returns true on success.
i_tags_destroy(tags)
Destroys the given tags structure. Called by i_img_destroy().
i_tags_find(tags, name, start, &entry)
Searches for a tag of the given name starting from index start.
On success returns true and sets *entry.
On failure returns false.
i_tags_findn(tags, code, start, &entry)
Searches for a tag of the given code starting from index start.
On success returns true and sets *entry.
On failure returns false.
i_tags_get_color(tags, name, code, &value)
Retrieve a tag specified by name or code as color.
On success sets the i_color *value to the color and returns true.
On failure returns false.
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 *value and returns true.
On failure returns false.
i_tags_get_int(tags, name, code, &value)
Retrieve a tag specified by name or code as an integer.
On success sets the int *value to the integer and returns true.
On failure returns false.
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.
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()
i_tags_set(tags, name, data, size)
i_tags_set(&img->tags, "i_comment", -1);
Sets the given tag to the string data
If size is -1 then the strlen(data) bytes are stored.
Even on failure, if an existing tag name exists, it will be
removed.
i_tags_set_color(tags, name, code, &value)
Stores the given color as a tag with the given name and code.
i_tags_set_float(tags, name, code, value)
Equivalent to i_tags_set_float2(tags, name, code, value, 30).
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 "places".
i_tags_setn("tags", "name", "idata")
i_tags_setn(&img->tags, "i_xres", 204);
i_tags_setn(&img->tags, "i_yres", 196);
Sets the given tag to the integer "idata"
Even on failure, if an existing tag "name" exists, it will be
removed.
Uncategorized functions
i_utf8_advance(char **p, size_t *len)
Retrieve a "UTF-8" character from the stream.
Modifies *p and *len to indicate the consumed characters.
This doesn't support the extended "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 "UTF-8" character is using the shortest
possible representation.
Returns ~0UL on failure.
im_context_refdec(ctx, where) =section Context objects
im_context_refdec(aIMCTX, "a description");
Remove a reference to the context, releasing it if all references
have been removed.
im_context_refinc(ctx, where) =section Context objects
im_context_refinc(aIMCTX, "a description");
Add a new reference to the context.
im_context_slot_get(ctx, slot)
Retrieve the value previously stored in the given slot of the
context object.
im_context_slot_new(destructor)
Allocate a new context-local-storage slot.
"desctructor" will be called when the context is destroyed if the
corresponding slot is non-NULL.
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.
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 "i_errors()".
im_get_context()
Retrieve the context object for the current thread.
Inside Imager itself this is just a function pointer, which the
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 "im_get_context" pointer at some point.
UNDOCUMENTED
The following API functions are undocumented so far, hopefully this
will change:
· im_lhead
· im_loog
· mm_log
AUTHOR
Tony Cook <tonyc@cpan.org>
SEE ALSO
Imager, Imager::API, Imager::ExtUtils, Imager::Inline
perl v5.14.3 2012-12-22 Imager::APIRef(3)
