Imager::APIRef - Imager's C API - reference. |
Imager::APIRef - Imager's C API - reference.
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);
source[0]
to
source[width-1]
.
Renders in normal combine mode.
i_render_delete(r)
i_render
object.
source[0]
through
source[width-1]
.
source[0]
through
source[width-1]
.
source[0]
through
source[width-1]
.
i_render
object and initialize it.
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 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:
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]
.
Its layout exactly corresponds to i_color.
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_pfm_evenodd
- simple even-odd fills.
i_pfm_nonzero
- non-zero winding rule fills.
x
, y
- arrays of x and y locations of vertices.
count
- the number of entries in the x
and y
arrays.
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_img_dim_u limit;
An unsigned variant of i_img_dim.
An enumerated type with the following possible values:
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.
icm_gray
- gray scale with no alpha channel.
icm_gray_alpha
- gray scale with an alpha channel.
icm_rgb
- RGB
icm_rgb_alpha
- RGB with an alpha channel.
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_img_dim
value to a type for use with the i_DF format
string.
i_img_dim
values for use with the i_DF (or i_DFp) format.
printf("point (" i_DFp ")\n", i_DFcp(x, y));
Format a pair of i_img_dim
values. This format string does
include the leading %
.
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, 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, 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, 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, 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, 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, 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, 50, 50, 45, &color);
Anti-alias fills a circle centered at (x,y) for radius rad with color.
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.
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.
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.
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.
Returns the number of pixels retrieved.
Returns the number of pixels retrieved.
indexes
.
Returns the number of indexes read.
Always returns 0 for direct color images.
x
, y
, color
)color
of the pixel (x,y).
Returns 0 if the pixel was retrieved, or -1 if not.
x
, y
, fcolor
)fcolor
.
Returns 0 if the pixel was retrieved, or -1 if not.
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_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.
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()
.
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()
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.
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)
im
, x1
, x2
, y1
, y2
, color
, endp
)The point (x2, y2) is drawn only if endp
is set.
Returns the number of pixels set.
left
, right
, fcolors
)fcolors
.
Returns the number of pixels set.
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 fill
.
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 color
.
i_poly_poly_aa(im, 1, &poly, mode, color);
Fill the count
polygons defined by polys
the color specified by
color
.
At least one polygon must be supplied.
All polygons must have at least 3 points.
i_poly_poly_aa_cfill(im, 1, &poly, mode, fill);
Fill the count
polygons defined by polys
the fill specified by
fill
.
At least one polygon must be supplied.
All polygons must have at least 3 points.
indexes
.
Returns the number of indexes written.
Always returns 0 for direct color images.
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.
x
, y
, fcolor
)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.
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.
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()
.
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_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()
.
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(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.
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)
If not present, bg
is set to black.
Returns 1 if the i_background
tag was found and valid.
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(aIMCTX, &width, &height, &bytes) i_get_image_file_limits(&width, &height, &bytes)
Retrieves the file limits set by i_set_image_file_limits().
Also callable as 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))
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(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:
Returns non-zero on success.
Also callable as i_set_image_file_limits(width, height, bytes)
.
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.
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 side of a filled area.
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 side of a filled area.
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_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_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.
im_io_new_bufchain(ctx)
Also callable as io_new_bufchain()
.
ctx - an Imager context object data - buffer to read from length - length of buffer
Also callable as io_new_buffer(data, length
.
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)
.
ctx - and Imager context object file - file descriptor to read/write from
Also callable as io_new_fd(file)
.
i_io_close(io)
Returns 0 on success.
i_io_flush(io)
Returns true on success,
i_io_getc(ig)
Returns EOF on failure, or a byte.
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)
On error or end of file, return EOF.
For unbuffered streams a single character buffer will be setup.
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
.
On success return c, on error returns EOF
size
bytes from the stream io
into buffer
.
Returns the number of bytes read. Returns 0 on end of file. Returns -1 on error.
Acts like perl's seek.
If you switch buffering off on a stream with buffering on:
Returns true on success. This may fail if any buffered output cannot be flushed.
ssize_t result = i_io_write(io, buffer, size)
Write to the given I/O stream.
Returns the number of bytes written.
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.
i_copy(source)
source
.
Tags are not copied, only the image data.
Returns: i_img *
dest
, src
, x1
, y1
, x2
, y2
, tx
, ty
)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.
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.
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
im
, src
, tx
, ty
, src_minx
, src_miny
, src_maxx
, src_maxy
)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.
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.
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.
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)
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.
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)
.
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)
.
img
)i_img_destroy(img)
Destroy an image object
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:
i_img_init()
on the image
object.
im_img_init(aIMCTX, im); i_img_init(im);
Imager internal initialization of images.
See im_img_alloc(aIMCTX) for more information.
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 *channel
to the alpha
channel index and returns non-zero.
If the image has no alpha channel, returns zero and *channel
is not
modified.
channel
may be NULL
.
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.
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.
im
)i_img_dim height = i_img_get_height(im);
Returns the height in pixels of the image.
im
)i_img_dim width = i_img_get_width(im);
Returns the width in pixels of the image.
im
)int channels = i_img_getchannels(img);
Get the number of channels in im
.
im
)int mask = i_img_getmask(img);
Get the image channel mask for im
.
im
)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:
(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.
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.
quant
, imgs
, count
)count
images in imgs
according to the rules in
quant
to build a color map (optimal or not depending on
quant->make_colors
).
quant
, img
)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.
quant
, data
, img
, trans_index
)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
.
mm_log()
macro.
mm_log()
macro.
i_mutex_t mutex;
Opaque type for Imager's mutex API.
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.
On success returns the index of the lowest color added.
On failure returns -1.
Always fails for direct color images.
i_colorcount(im)
Returns -1 for direct images.
On success sets *entry to the index of the color, and returns true.
On failure returns false.
Always fails on direct color images.
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 -1 for direct color images.
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.
Returns the number of tags deleted.
Returns the number of tags deleted.
Returns true on success.
i_tags_destroy(tags)
On success returns true and sets *entry.
On failure returns false.
On success returns true and sets *entry.
On failure returns false.
On success sets the i_color *value to the color and returns true.
On failure returns false.
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.
On success sets the int *value to the integer and returns true.
On failure returns false.
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.
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(&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.
Since tags are strings or ints, we convert the value to a string before
storage at the precision specified by places
.
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.
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(aIMCTX, "a description");
Remove a reference to the context, releasing it if all references have been removed.
im_context_refinc(aIMCTX, "a description");
Add a new reference to the context.
im_context_slot_new(destructor)
desctructor
will be called when the context is destroyed if the
corresponding slot is non-NULL.
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()
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.
The following API functions are undocumented so far, hopefully this will change:
Tony Cook <tonyc@cpan.org>
Imager, Imager::API, Imager::ExtUtils, Imager::Inline
Imager::APIRef - Imager's C API - reference. |