1Imager::APIRef(3) User Contributed Perl Documentation Imager::APIRef(3)
2
6 Imager::APIRef - Imager's C API - reference.
7
9 i_color color;
10 color.rgba.r = 255; color.rgba.g = 0; color.rgba.b = 255;
11 double x[] = { ... };
12 double y[] = { ... };
13 i_polygon_t poly;
14 poly.count = sizeof(x) / sizeof(*x);
15 poly.x = x;
16 poly.y = y;
17 # Blit tools
20 # Data Types
22 i_img *img;
23 i_color black;
24 black.rgba.r = black.rgba.g = black.rgba.b = black.rgba.a = 0;
25 i_fill_t *fill;
26 i_img_dim x, y;
27 i_img_dim_u limit;
28 printf("left %" i_DF "\n", i_DFc(x));
29 printf("point (" i_DFp ")\n", i_DFcp(x, y));
30 # Drawing
32 i_arc(im, 50, 50, 20, 45, 135, &color);
33 i_arc_cfill(im, 50, 50, 35, 90, 135, fill);
34 i_arc_aa(im, 50, 50, 35, 90, 135, &color);
35 i_arc_aa_cfill(im, 50, 50, 35, 90, 135, fill);
36 i_circle_aa(im, 50, 50, 45, &color);
37 i_box(im, 0, 0, im->xsize-1, im->ysize-1, &color).
38 i_box_filled(im, 0, 0, im->xsize-1, im->ysize-1, &color);
39 i_box_cfill(im, 0, 0, im->xsize-1, im->ysize-1, fill);
40 i_flood_fill(im, 50, 50, &color);
41 i_flood_cfill(im, 50, 50, fill);
42 i_flood_fill_border(im, 50, 50, &color, &border);
43 i_flood_cfill_border(im, 50, 50, fill, border);
44 i_poly_poly_aa(im, 1, &poly, mode, color);
45 i_poly_aa_m(im, count, x, y, mode, color);
46 i_poly_poly_aa_cfill(im, 1, &poly, mode, fill);
47 i_poly_aa_cfill(im, count, x, y, mode, fill);
48 # Error handling
50 im_clear_error(aIMCTX);
51 i_clear_error();
52 i_push_error(0, "Yep, it's broken");
53 i_push_error(errno, "Error writing");
54 im_push_error(aIMCTX, 0, "Something is wrong");
55 va_args args;
56 va_start(args, lastarg);
57 im_push_errorvf(ctx, code, format, args);
58 i_push_errorf(errno, "Cannot open file %s: %d", filename, errno);
59 im_push_errorf(aIMCTX, errno, "Cannot open file %s: %d", filename, errno);
60 # Files
62 im_set_image_file_limits(aIMCTX, 500, 500, 1000000);
63 i_set_image_file_limits(500, 500, 1000000);
64 im_get_image_file_limits(aIMCTX, &width, &height, &bytes)
65 i_get_image_file_limits(&width, &height, &bytes)
66 im_int_check_image_file_limits(aIMCTX, width, height, channels, sizeof(i_sample_t))
67 i_int_check_image_file_limits(width, height, channels, sizeof(i_sample_t))
68 # Fills
70 i_fill_t *fill = i_new_fill_solidf(&fcolor, combine);
71 i_fill_t *fill = i_new_fill_solid(&color, combine);
72 i_fill_t *fill = i_new_fill_hatch(&fg_color, &bg_color, combine, hatch, custom_hatch, dx, dy);
73 i_fill_t *fill = i_new_fill_hatchf(&fg_fcolor, &bg_fcolor, combine, hatch, custom_hatch, dx, dy);
74 i_fill_t *fill = i_new_fill_image(src_img, matrix, x_offset, y_offset, combine);
75 fill = i_new_fill_fount(0, 0, 100, 100, i_ft_linear, i_ft_linear,
76 i_fr_triangle, 0, i_fts_grid, 9, 1, segs);
77 i_fill_destroy(fill);
78 # I/O Layers
80 ssize_t count = i_io_peekn(ig, buffer, sizeof(buffer));
81 ssize_t result = i_io_write(io, buffer, size)
82 char buffer[BUFSIZ]
83 ssize_t len = i_io_gets(buffer, sizeof(buffer), '\n');
84 io_glue_destroy(ig);
85 # Image
87 # Image creation/destruction
89 i_img *img = i_sametype(src, width, height);
90 i_img *img = i_sametype_chans(src, width, height, channels);
91 i_img *img = im_img_16_new(aIMCTX, width, height, channels);
92 i_img *img = i_img_16_new(width, height, channels);
93 i_img *img = im_img_8_new(aIMCTX, width, height, channels);
94 i_img *img = i_img_8_new(width, height, channels);
95 i_img *img = im_img_double_new(aIMCTX, width, height, channels);
96 i_img *img = i_img_double_new(width, height, channels);
97 i_img *img = im_img_pal_new(aIMCTX, width, height, channels, max_palette_size)
98 i_img *img = i_img_pal_new(width, height, channels, max_palette_size)
99 i_img_destroy(img)
100 # Image Implementation
102 i_img *im = im_img_alloc(aIMCTX);
103 i_img *im = i_img_alloc();
104 im_img_init(aIMCTX, im);
105 i_img_init(im);
106 # Image Information
108 // only channel 0 writable
109 i_img_setmask(img, 0x01);
110 int mask = i_img_getmask(img);
111 int channels = i_img_getchannels(img);
112 i_img_dim width = i_img_get_width(im);
113 i_img_dim height = i_img_get_height(im);
114 i_color_model_t cm = i_img_color_model(im);
115 int alpha_channel;
116 int has_alpha = i_img_alpha_channel(im, &alpha_channel);
117 int color_channels = i_img_color_channels(im);
118 # Image quantization
120 # Logging
122 # mutex
124 i_mutex_t mutex;
125 # Mutex functions
127 i_mutex_t m = i_mutex_new();
128 i_mutex_destroy(m);
129 i_mutex_lock(m);
130 i_mutex_unlock(m);
131 # Paletted images
133 # Tags
135 i_tags_set(&img->tags, "i_comment", -1);
136 i_tags_setn(&img->tags, "i_xres", 204);
137 i_tags_setn(&img->tags, "i_yres", 196);
138
140 Blit tools
141 i_render_color(r, x, y, width, source, color)
142 Render the given color with the coverage specified by "source[0]"
143 to "source[width-1]".
144 Renders in normal combine mode.
146 i_render_delete(r)
148 Release an "i_render" object.
149 i_render_fill(r, x, y, width, source, fill)
151 Render the given fill with the coverage in "source[0]" through
152 "source[width-1]".
153 i_render_line(r, x, y, width, source, fill)
155 Render the given fill with the coverage in "source[0]" through
156 "source[width-1]".
157 i_render_linef(r, x, y, width, source, fill)
159 Render the given fill with the coverage in "source[0]" through
160 "source[width-1]".
161 i_render_new(im, width)
163 Allocate a new "i_render" object and initialize it.
164 Data Types
166 i_img
167 i_img *img;
168 This is Imager's image type.
170 It contains the following members:
172 • "channels" - the number of channels in the image
174 • "xsize", "ysize" - the width and height of the image in pixels
176 • "bytes" - the number of bytes used to store the image data.
178 Undefined where virtual is non-zero.
179 • "ch_mask" - a mask of writable channels. eg. if this is 6 then
181 only channels 1 and 2 are writable. There may be bits set for
182 which there are no channels in the image.
183 • "bits" - the number of bits stored per sample. Should be one
185 of i_8_bits, i_16_bits, i_double_bits.
186 • "type" - either i_direct_type for direct color images, or
188 i_palette_type for paletted images.
189 • "virtual" - if zero then this image is-self contained. If non-
191 zero then this image could be an interface to some other
192 implementation.
193 • "idata" - the image data. This should not be directly
195 accessed. A new image implementation can use this to store its
196 image data. i_img_destroy() will myfree() this pointer if it's
197 non-null.
198 • "tags" - a structure storing the image's tags. This should
200 only be accessed via the i_tags_*() functions.
201 • "ext_data" - a pointer for use internal to an image
203 implementation. This should be freed by the image's destroy
204 handler.
205 • "im_data" - data internal to Imager. This is initialized by
207 i_img_init().
208 • i_f_ppix, i_f_ppixf, i_f_plin, i_f_plinf, i_f_gpix, i_f_gpixf,
210 i_f_glin, i_f_glinf, i_f_gsamp, i_f_gampf - implementations for
211 each of the required image functions. An image implementation
212 should initialize these between calling i_img_alloc() and
213 i_img_init().
214 • i_f_gpal, i_f_ppal, i_f_addcolors, i_f_getcolors,
216 i_f_colorcount, i_f_maxcolors, i_f_findcolor, i_f_setcolors -
217 implementations for each paletted image function.
218 • i_f_destroy - custom image destruction function. This should
220 be used to release memory if necessary.
221 • i_f_gsamp_bits - implements i_gsamp_bits() for this image.
223 • i_f_psamp_bits - implements i_psamp_bits() for this image.
225 • i_f_psamp - implements psamp() for this image.
227 • i_f_psampf - implements psamp() for this image.
229 • "im_data" - image specific data internal to Imager.
231 • "context" - the Imager API context this image belongs to.
233 i_color
235 i_color black;
236 black.rgba.r = black.rgba.g = black.rgba.b = black.rgba.a = 0;
237 Type for 8-bit/sample color.
239 Samples as per;
241 i_color c;
243 i_color is a union of:
245 • gray - contains a single element gray_color, eg.
247 "c.gray.gray_color"
248 • "rgb" - contains three elements "r", "g", "b", eg. "c.rgb.r"
250 • "rgba" - contains four elements "r", "g", "b", "a", eg.
252 "c.rgba.a"
253 • "cmyk" - contains four elements "c", "m", "y", "k", eg.
255 "c.cmyk.y". Note that Imager never uses CMYK colors except
256 when reading/writing files.
257 • channels - an array of four channels, eg "c.channels[2]".
259 i_fcolor
261 This is the double/sample color type.
262 Its layout exactly corresponds to i_color.
264 i_fill_t
266 i_fill_t *fill;
267 This is the "abstract" base type for Imager's fill types.
269 Unless you're implementing a new fill type you'll typically treat
271 this as an opaque type.
272 i_poly_fill_mode_t
274 Control how polygons are filled. Has the following values:
275 • "i_pfm_evenodd" - simple even-odd fills.
277 • "i_pfm_nonzero" - non-zero winding rule fills.
279 i_polygon_t
281 Represents a polygon. Has the following members:
282 • "x", "y" - arrays of x and y locations of vertices.
284 • "count" - the number of entries in the "x" and "y" arrays.
286 im_context_t
288 Imager's per-thread context.
289 im_slot_t
291 Represents a slot in the context object.
292 i_img_dim
294 i_img_dim x, y;
295 A signed integer type that represents an image dimension or
297 ordinate.
298 May be larger than int on some platforms.
300 i_img_dim_u
302 i_img_dim_u limit;
303 An unsigned variant of "i_img_dim".
305 i_color_model_t
307 Returned by "i_img_color_model(im)" to indicate the color model of
308 the image.
309 An enumerated type with the following possible values:
311 • "icm_unknown" - the image has no usable color data. In future
313 versions of Imager this will be returned in a few limited
314 cases, eg. when the source image is CMYK and the user has
315 requested no color translation is done.
316 • "icm_gray" - gray scale with no alpha channel.
318 • "icm_gray_alpha" - gray scale with an alpha channel.
320 • "icm_rgb" - RGB
322 • "icm_rgb_alpha" - RGB with an alpha channel.
324 i_DF
326 printf("left %" i_DF "\n", i_DFc(x));
327 This is a constant string that can be used with functions like
329 printf() to format i_img_dim values after they're been cast with
330 i_DFc().
331 Does not include the leading "%".
333 i_DFc
335 Cast an "i_img_dim" value to a type for use with the i_DF format
336 string.
337 i_DFcp
339 Casts two "i_img_dim" values for use with the i_DF (or i_DFp)
340 format.
341 i_DFp
343 printf("point (" i_DFp ")\n", i_DFcp(x, y));
344 Format a pair of "i_img_dim" values. This format string does
346 include the leading "%".
347 Drawing
349 i_arc(im, x, y, rad, d1, d2, color)
350 i_arc(im, 50, 50, 20, 45, 135, &color);
351 Fills an arc centered at (x,y) with radius rad covering the range
353 of angles in degrees from d1 to d2, with the color.
354 i_arc_aa(im, x, y, rad, d1, d2, color)
356 i_arc_aa(im, 50, 50, 35, 90, 135, &color);
357 Anti-alias fills an arc centered at (x,y) with radius rad covering
359 the range of angles in degrees from d1 to d2, with the color.
360 i_arc_aa_cfill(im, x, y, rad, d1, d2, fill)
362 i_arc_aa_cfill(im, 50, 50, 35, 90, 135, fill);
363 Anti-alias fills an arc centered at (x,y) with radius rad covering
365 the range of angles in degrees from d1 to d2, with the fill object.
366 i_arc_cfill(im, x, y, rad, d1, d2, fill)
368 i_arc_cfill(im, 50, 50, 35, 90, 135, fill);
369 Fills an arc centered at (x,y) with radius rad covering the range
371 of angles in degrees from d1 to d2, with the fill object.
372 i_box(im, x1, y1, x2, y2, color)
374 i_box(im, 0, 0, im->xsize-1, im->ysize-1, &color).
375 Outlines the box from (x1,y1) to (x2,y2) inclusive with color.
377 i_box_cfill(im, x1, y1, x2, y2, fill)
379 i_box_cfill(im, 0, 0, im->xsize-1, im->ysize-1, fill);
380 Fills the box from (x1,y1) to (x2,y2) inclusive with fill.
382 i_box_filled(im, x1, y1, x2, y2, color)
384 i_box_filled(im, 0, 0, im->xsize-1, im->ysize-1, &color);
385 Fills the box from (x1,y1) to (x2,y2) inclusive with color.
387 i_circle_aa(im, x, y, rad, color)
389 i_circle_aa(im, 50, 50, 45, &color);
390 Anti-alias fills a circle centered at (x,y) for radius rad with
392 color.
393 i_flood_cfill("im", "seedx", "seedy", "fill")
395 i_flood_cfill(im, 50, 50, fill);
396 Flood fills the 4-connected region starting from the point
398 ("seedx", "seedy") with "fill".
399 Returns false if ("seedx", "seedy") are outside the image.
401 i_flood_cfill_border("im", "seedx", "seedy", "fill", "border")
403 i_flood_cfill_border(im, 50, 50, fill, border);
404 Flood fills the 4-connected region starting from the point
406 ("seedx", "seedy") with "fill", the fill stops when it reaches
407 pixels of color "border".
408 Returns false if ("seedx", "seedy") are outside the image.
410 i_flood_fill("im", "seedx", "seedy", "color")
412 i_flood_fill(im, 50, 50, &color);
413 Flood fills the 4-connected region starting from the point
415 ("seedx", "seedy") with color.
416 Returns false if ("seedx", "seedy") are outside the image.
418 i_flood_fill_border("im", "seedx", "seedy", "color", "border")
420 i_flood_fill_border(im, 50, 50, &color, &border);
421 Flood fills the 4-connected region starting from the point
423 ("seedx", "seedy") with "color", fill stops when the fill reaches a
424 pixels with color "border".
425 Returns false if ("seedx", "seedy") are outside the image.
427 i_glin(im, l, r, y, colors)
429 Retrieves (r-l) pixels starting from (l,y) into colors.
430 Returns the number of pixels retrieved.
432 i_glinf(im, l, r, y, colors)
434 Retrieves (r-l) pixels starting from (l,y) into colors as floating
435 point colors.
436 Returns the number of pixels retrieved.
438 i_gpal(im, left, right, y, indexes)
440 Reads palette indexes for the horizontal line (left, y) to
441 (right-1, y) into "indexes".
442 Returns the number of indexes read.
444 Always returns 0 for direct color images.
446 i_gpix(im, "x", "y", "color")
448 Retrieves the "color" of the pixel (x,y).
449 Returns 0 if the pixel was retrieved, or -1 if not.
451 i_gpixf(im, "x", "y", "fcolor")
453 Retrieves the color of the pixel (x,y) as a floating point color
454 into "fcolor".
455 Returns 0 if the pixel was retrieved, or -1 if not.
457 i_gsamp(im, left, right, y, samples, channels, channel_count)
459 Reads sample values from "im" for the horizontal line (left, y) to
460 (right-1,y) for the channels specified by "channels", an array of
461 int with "channel_count" elements.
462 If channels is NULL then the first channels_count channels are
464 retrieved for each pixel.
465 Returns the number of samples read (which should be (right-left) *
467 channel_count)
468 i_gsamp_bg(im, l, r, y, samples, out_channels, background)
470 Like "i_gsampf()" but applies the source image color over a
471 supplied background color.
472 This is intended for output to image formats that don't support
474 alpha channels.
475 i_gsamp_bits(im, left, right, y, samples, channels, channel_count,
477 bits)
478 Reads integer samples scaled to "bits" bits of precision into the
479 "unsigned int" array "samples".
480 Expect this to be slow unless "bits == im->bits".
482 Returns the number of samples copied, or -1 on error.
484 Not all image types implement this method.
486 Pushes errors, but does not call "i_clear_error()".
488 i_gsampf(im, left, right, y, samples, channels, channel_count)
490 Reads floating point sample values from "im" for the horizontal
491 line (left, y) to (right-1,y) for the channels specified by
492 "channels", an array of int with channel_count elements.
493 If "channels" is NULL then the first "channel_count" channels are
495 retrieved for each pixel.
496 Returns the number of samples read (which should be
498 ("right"-"left") * "channel_count")
499 i_gsampf_bg(im, l, r, y, samples, out_channels, background)
501 Like "i_gsampf()" but applies the source image color over a
502 supplied background color.
503 This is intended for output to image formats that don't support
505 alpha channels.
506 i_line("im", "x1", "y1", "x2", "y2", "color", "endp")
508 Draw a line to image using Bresenham's line drawing algorithm
509 im - image to draw to
511 x1 - starting x coordinate
512 y1 - starting x coordinate
513 x2 - starting x coordinate
514 y2 - starting x coordinate
515 color - color to write to image
516 endp - endpoint flag (boolean)
517 i_line_aa("im", "x1", "x2", "y1", "y2", "color", "endp")
519 Anti-alias draws a line from (x1,y1) to (x2, y2) in color.
520 The point (x2, y2) is drawn only if "endp" is set.
522 i_plin(im, l, r, y, colors)
524 Sets (r-l) pixels starting from (l,y) using (r-l) values from
525 colors.
526 Returns the number of pixels set.
528 i_plinf(im, "left", "right", "fcolors")
530 Sets (right-left) pixels starting from (left,y) using (right-left)
531 floating point colors from "fcolors".
532 Returns the number of pixels set.
534 i_poly_aa_cfill_m(im, count, x, y, mode, fill)
536 i_poly_aa_cfill(im, count, x, y, mode, fill);
537 Fill a polygon defined by the points specified by the x and y
539 arrays with the fill specified by "fill".
540 i_poly_aa_m(im, count, x, y, mode, color)
542 i_poly_aa_m(im, count, x, y, mode, color);
543 Fill a polygon defined by the points specified by the x and y
545 arrays with the color specified by "color".
546 i_poly_poly_aa(im, count, polys, mode, color)
548 i_poly_poly_aa(im, 1, &poly, mode, color);
549 Fill the "count" polygons defined by "polys" the color specified by
551 "color".
552 At least one polygon must be supplied.
554 All polygons must have at least 3 points.
556 i_poly_poly_aa_cfill(im, count, polys, mode, fill)
558 i_poly_poly_aa_cfill(im, 1, &poly, mode, fill);
559 Fill the "count" polygons defined by "polys" the fill specified by
561 "fill".
562 At least one polygon must be supplied.
564 All polygons must have at least 3 points.
566 i_ppal(im, left, right, y, indexes)
568 Writes palette indexes for the horizontal line (left, y) to
569 (right-1, y) from "indexes".
570 Returns the number of indexes written.
572 Always returns 0 for direct color images.
574 i_ppix(im, x, y, color)
576 Sets the pixel at (x,y) to color.
577 Returns 0 if the pixel was drawn, or -1 if not.
579 Does no alpha blending, just copies the channels from the supplied
581 color to the image.
582 i_ppixf(im, "x", "y", "fcolor")
584 Sets the pixel at ("x","y") to the floating point color "fcolor".
585 Returns 0 if the pixel was drawn, or -1 if not.
587 Does no alpha blending, just copies the channels from the supplied
589 color to the image.
590 i_psamp(im, left, right, y, samples, channels, channel_count)
592 Writes sample values from "samples" to "im" for the horizontal line
593 (left, y) to (right-1, y) inclusive for the channels specified by
594 "channels", an array of "int" with "channel_count" elements.
595 If "channels" is "NULL" then the first "channels_count" channels
597 are written to for each pixel.
598 Returns the number of samples written, which should be (right -
600 left) * channel_count. If a channel not in the image is in
601 channels, left is negative, left is outside the image or y is
602 outside the image, returns -1 and pushes an error.
603 i_psamp_bits(im, left, right, y, samples, channels, channel_count,
605 bits)
606 Writes integer samples scaled to "bits" bits of precision from the
607 "unsigned int" array "samples".
608 Expect this to be slow unless "bits == im->bits".
610 Returns the number of samples copied, or -1 on error.
612 Not all image types implement this method.
614 Pushes errors, but does not call "i_clear_error()".
616 i_psampf(im, left, right, y, samples, channels, channel_count)
618 Writes floating point sample values from "samples" to "im" for the
619 horizontal line (left, y) to (right-1, y) inclusive for the
620 channels specified by "channels", an array of "int" with
621 "channel_count" elements.
622 If "channels" is "NULL" then the first "channels_count" channels
624 are written to for each pixel.
625 Returns the number of samples written, which should be (right -
627 left) * channel_count. If a channel not in the image is in
628 channels, left is negative, left is outside the image or y is
629 outside the image, returns -1 and pushes an error.
630 Error handling
632 i_push_errorf(int code, char const *fmt, ...)
633 i_push_errorf(errno, "Cannot open file %s: %d", filename, errno);
634 A version of i_push_error() that does printf() like formatting.
636 Does not support perl specific format codes.
638 im_clear_error(ctx)
640 im_clear_error(aIMCTX);
641 i_clear_error();
642 Clears the error stack.
644 Called by any Imager function before doing any other processing.
646 Also callable as "i_clear_error()".
648 im_push_error(ctx, code, message)
650 i_push_error(0, "Yep, it's broken");
651 i_push_error(errno, "Error writing");
652 im_push_error(aIMCTX, 0, "Something is wrong");
653 Called by an Imager function to push an error message onto the
655 stack.
656 No message is pushed if the stack is full (since this means someone
658 forgot to call i_clear_error(), or that a function that doesn't do
659 error handling is calling function that does.).
660 im_push_errorf(ctx, code, char const *fmt, ...)
662 im_push_errorf(aIMCTX, errno, "Cannot open file %s: %d", filename, errno);
663 A version of im_push_error() that does printf() like formatting.
665 Does not support perl specific format codes.
667 im_push_errorvf(ctx, code, format, args)
669 va_args args;
670 va_start(args, lastarg);
671 im_push_errorvf(ctx, code, format, args);
672 Intended for use by higher level functions, takes a varargs pointer
674 and a format to produce the finally pushed error message.
675 Does not support perl specific format codes.
677 Also callable as "i_push_errorvf(code, format, args)"
679 Files
681 i_get_file_background(im, &bg)
682 Retrieve the file write background color tag from the image.
683 If not present, "bg" is set to black.
685 Returns 1 if the "i_background" tag was found and valid.
687 i_get_file_backgroundf(im, &bg)
689 Retrieve the file write background color tag from the image as a
690 floating point color.
691 Implemented in terms of i_get_file_background().
693 If not present, "bg" is set to black.
695 Returns 1 if the "i_background" tag was found and valid.
697 im_get_image_file_limits(ctx, &width, &height, &bytes)
699 im_get_image_file_limits(aIMCTX, &width, &height, &bytes)
700 i_get_image_file_limits(&width, &height, &bytes)
701 Retrieves the file limits set by i_set_image_file_limits().
703 • i_img_dim *width, *height - the maximum width and height of the
705 image.
706 • size_t *bytes - size in memory of the image in bytes.
708 Also callable as "i_get_image_file_limits(&width, &height,
710 &bytes)".
711 im_int_check_image_file_limits(width, height, channels, sample_size)
713 im_int_check_image_file_limits(aIMCTX, width, height, channels, sizeof(i_sample_t))
714 i_int_check_image_file_limits(width, height, channels, sizeof(i_sample_t))
715 Checks the size of a file in memory against the configured image
717 file limits.
718 This also range checks the values to those permitted by Imager and
720 checks for overflows in calculating the size.
721 Returns non-zero if the file is within limits.
723 This function is intended to be called by image file read
725 functions.
726 Also callable as "i_int_check_image_file_limits(width, height,
728 channels, sizeof(i_sample_t)".
729 im_set_image_file_limits(ctx, width, height, bytes)
731 im_set_image_file_limits(aIMCTX, 500, 500, 1000000);
732 i_set_image_file_limits(500, 500, 1000000);
733 Set limits on the sizes of images read by Imager.
735 Setting a limit to 0 means that limit is ignored.
737 Negative limits result in failure.
739 Parameters:
741 • i_img_dim width, height - maximum width and height.
743 • size_t bytes - maximum size in memory in bytes. A value of
745 zero sets this limit to one gigabyte.
746 Returns non-zero on success.
748 Also callable as "i_set_image_file_limits(width, height, bytes)".
750 Fills
752 i_new_fill_fount("xa", "ya", "xb", "yb", "type", "repeat", "combine",
753 "super_sample", "ssample_param", "count", "segs")
754 fill = i_new_fill_fount(0, 0, 100, 100, i_ft_linear, i_ft_linear,
755 i_fr_triangle, 0, i_fts_grid, 9, 1, segs);
756 Creates a new general fill which fills with a fountain fill.
758 i_new_fill_hatch("fg", "bg", "combine", "hatch", "cust_hatch", "dx",
760 "dy")
761 i_fill_t *fill = i_new_fill_hatch(&fg_color, &bg_color, combine, hatch, custom_hatch, dx, dy);
762 Creates a new hatched fill with the "fg" color used for the 1 bits
764 in the hatch and "bg" for the 0 bits. If "combine" is non-zero
765 alpha values will be combined.
766 If "cust_hatch" is non-NULL it should be a pointer to 8 bytes of
768 the hash definition, with the high-bits to the left.
769 If "cust_hatch" is NULL then one of the standard hatches is used.
771 ("dx", "dy") are an offset into the hatch which can be used to
773 hatch adjoining areas out of alignment, or to align the origin of a
774 hatch with the side of a filled area.
775 i_new_fill_hatchf("fg", "bg", "combine", "hatch", "cust_hatch", "dx",
777 "dy")
778 i_fill_t *fill = i_new_fill_hatchf(&fg_fcolor, &bg_fcolor, combine, hatch, custom_hatch, dx, dy);
779 Creates a new hatched fill with the "fg" color used for the 1 bits
781 in the hatch and "bg" for the 0 bits. If "combine" is non-zero
782 alpha values will be combined.
783 If "cust_hatch" is non-NULL it should be a pointer to 8 bytes of
785 the hash definition, with the high-bits to the left.
786 If "cust_hatch" is NULL then one of the standard hatches is used.
788 ("dx", "dy") are an offset into the hatch which can be used to
790 hatch adjoining areas out of alignment, or to align the origin of a
791 hatch with the side of a filled area.
792 i_new_fill_image("im", "matrix", "xoff", "yoff", "combine")
794 i_fill_t *fill = i_new_fill_image(src_img, matrix, x_offset, y_offset, combine);
795 Create an image based fill.
797 matrix is an array of 9 doubles representing a transformation
799 matrix.
800 "xoff" and "yoff" are the offset into the image to start filling
802 from.
803 i_new_fill_solid(color, combine)
805 i_fill_t *fill = i_new_fill_solid(&color, combine);
806 Create a solid fill based on an 8-bit color.
808 If combine is non-zero then alpha values will be combined.
810 i_new_fill_solidf(color, combine)
812 i_fill_t *fill = i_new_fill_solidf(&fcolor, combine);
813 Create a solid fill based on a float color.
815 If combine is non-zero then alpha values will be combined.
817 i_fill_destroy(fill)
819 i_fill_destroy(fill);
820 Call to destroy any fill object.
822 I/O Layers
824 im_io_new_bufchain(ctx)
825 Returns a new io_glue object that has the 'empty' source and but
826 can be written to and read from later (like a pseudo file).
827 Also callable as "io_new_bufchain()".
829 im_io_new_buffer(ctx, data, length)
831 Returns a new io_glue object that has the source defined as reading
832 from specified buffer. Note that the buffer is not copied.
833 ctx - an Imager context object
835 data - buffer to read from
836 length - length of buffer
837 Also callable as "io_new_buffer(data, length".
839 im_io_new_cb(ctx, p, read_cb, write_cb, seek_cb, close_cb, destroy_cb)
841 Create a new I/O layer object that calls your supplied callbacks.
842 In general the callbacks should behave like the corresponding POSIX
844 primitives.
845 • "read_cb"(p, buffer, length) should read up to "length" bytes
847 into "buffer" and return the number of bytes read. At end of
848 file, return 0. On error, return -1.
849 • "write_cb"(p, buffer, length) should write up to "length" bytes
851 from "buffer" and return the number of bytes written. A return
852 value <= 0 will be treated as an error.
853 • "seekcb"(p, offset, whence) should seek and return the new
855 offset.
856 • "close_cb"(p) should return 0 on success, -1 on failure.
858 • "destroy_cb"(p) should release any memory specific to your
860 callback handlers.
861 Also callable as "io_new_cb(p, readcb, writecb, seekcb, closecb,
863 destroycb)".
864 im_io_new_fd(ctx, file)
866 Returns a new io_glue object that has the source defined as reading
867 from specified file descriptor. Note that the interface to
868 receiving data from the io_glue callbacks hasn't been done yet.
869 ctx - and Imager context object
871 file - file descriptor to read/write from
872 Also callable as "io_new_fd(file)".
874 i_io_close(io)
876 Flush any pending output and perform the close action for the
877 stream.
878 Returns 0 on success.
880 i_io_flush(io)
882 Flush any buffered output.
883 Returns true on success,
885 i_io_getc(ig)
887 A macro to read a single byte from a buffered I/O glue object.
888 Returns EOF on failure, or a byte.
890 i_io_gets(ig, buffer, size, end_of_line)
892 char buffer[BUFSIZ]
893 ssize_t len = i_io_gets(buffer, sizeof(buffer), '\n');
894 Read up to "size"-1 bytes from the stream "ig" into "buffer".
896 If the byte "end_of_line" is seen then no further bytes will be
898 read.
899 Returns the number of bytes read.
901 Always "NUL" terminates the buffer.
903 i_io_peekc(ig)
905 Read the next character from the stream without advancing the
906 stream.
907 On error or end of file, return EOF.
909 For unbuffered streams a single character buffer will be setup.
911 i_io_peekn(ig, buffer, size)
913 ssize_t count = i_io_peekn(ig, buffer, sizeof(buffer));
914 Buffer at least "size" (at most "ig->buf_size" bytes of data from
916 the stream and return "size" bytes of it to the caller in "buffer".
917 This ignores the buffered state of the stream, and will always
919 setup buffering if needed.
920 If no "type" parameter is provided to Imager::read() or
922 Imager::read_multi(), Imager will call "i_io_peekn()" when probing
923 for the file format.
924 Returns -1 on error, 0 if there is no data before EOF, or the
926 number of bytes read into "buffer".
927 i_io_putc(ig, c)
929 Write a single character to the stream.
930 On success return c, on error returns EOF
932 i_io_read(io, buffer, size)
934 Read up to "size" bytes from the stream "io" into "buffer".
935 Returns the number of bytes read. Returns 0 on end of file.
937 Returns -1 on error.
938 i_io_seek(io, offset, whence)
940 Seek within the stream.
941 Acts like perl's seek.
943 i_io_set_buffered(io, buffered)
945 Set the buffering mode of the stream.
946 If you switch buffering off on a stream with buffering on:
948 • any buffered output will be flushed.
950 • any existing buffered input will be consumed before reads
952 become unbuffered.
953 Returns true on success. This may fail if any buffered output
955 cannot be flushed.
956 i_io_write(io, buffer, size)
958 ssize_t result = i_io_write(io, buffer, size)
959 Write to the given I/O stream.
961 Returns the number of bytes written.
963 io_slurp(ig, c)
965 Takes the source that the io_glue is bound to and allocates space
966 for a return buffer and returns the entire content in a single
967 buffer. Note: This only works for io_glue objects created by
968 io_new_bufchain(). It is useful for saving to scalars and such.
969 ig - io_glue object
971 c - pointer to a pointer to where data should be copied to
972 char *data;
974 size_t size = io_slurp(ig, &data);
975 ... do something with the data ...
976 myfree(data);
977 io_slurp() will abort the program if the supplied I/O layer is not
979 from io_new_bufchain().
980 io_glue_destroy(ig)
982 io_glue_destroy(ig);
983 Destroy an io_glue objects. Should clean up all related buffers.
985 ig - io_glue object to destroy.
987 Image
989 i_copy(source)
990 Creates a new image that is a copy of the image "source".
991 Tags are not copied, only the image data.
993 Returns: i_img *
995 i_copyto("dest", "src", "x1", "y1", "x2", "y2", "tx", "ty")
997 Copies image data from the area ("x1","y1")-["x2","y2"] in the
998 source image to a rectangle the same size with it's top-left corner
999 at ("tx","ty") in the destination image.
1000 If "x1" > "x2" or "y1" > "y2" then the corresponding co-ordinates
1002 are swapped.
1003 i_copyto_trans("im", "src", "x1", "y1", "x2", "y2", "tx", "ty",
1005 "trans")
1006 ("x1","y1") ("x2","y2") specifies the region to copy (in the source
1007 coordinates) ("tx","ty") specifies the upper left corner for the
1008 target image. pass NULL in "trans" for non transparent i_colors.
1009 i_img_info(im, info)
1011 Return image information
1012 im - Image pointer
1014 info - pointer to array to return data
1015 info is an array of 4 integers with the following values:
1017 info[0] - width
1019 info[1] - height
1020 info[2] - channels
1021 info[3] - channel mask
1022 i_rubthru("im", "src", "tx", "ty", "src_minx", "src_miny", "src_maxx",
1024 "src_maxy")
1025 Takes the sub image "src"["src_minx", "src_maxx")["src_miny",
1026 "src_maxy")> and overlays it at ("tx","ty") on the image object.
1027 The alpha channel of each pixel in "src" is used to control how
1029 much the existing color in "im" is replaced, if it is 255 then the
1030 color is completely replaced, if it is 0 then the original color is
1031 left unmodified.
1032 Image creation/destruction
1034 i_sametype("im", "xsize", "ysize")
1035 i_img *img = i_sametype(src, width, height);
1036 Returns an image of the same type (sample size, channels,
1038 paletted/direct).
1039 For paletted images the palette is copied from the source.
1041 i_sametype_chans("im", "xsize", "ysize", "channels")
1043 i_img *img = i_sametype_chans(src, width, height, channels);
1044 Returns an image of the same type (sample size).
1046 For paletted images the equivalent direct type is returned.
1048 im_img_16_new(ctx, x, y, ch)
1050 i_img *img = im_img_16_new(aIMCTX, width, height, channels);
1051 i_img *img = i_img_16_new(width, height, channels);
1052 Create a new 16-bit/sample image.
1054 Returns the image on success, or NULL on failure.
1056 Also callable as "i_img_16_new(x, y, ch)"
1058 im_img_8_new(ctx, x, y, ch)
1060 i_img *img = im_img_8_new(aIMCTX, width, height, channels);
1061 i_img *img = i_img_8_new(width, height, channels);
1062 Creates a new image object x pixels wide, and y pixels high with ch
1064 channels.
1065 im_img_double_new(ctx, x, y, ch)
1067 i_img *img = im_img_double_new(aIMCTX, width, height, channels);
1068 i_img *img = i_img_double_new(width, height, channels);
1069 Creates a new double per sample image.
1071 Also callable as "i_img_double_new(width, height, channels)".
1073 im_img_pal_new(ctx, "x", "y", "channels", "maxpal")
1075 i_img *img = im_img_pal_new(aIMCTX, width, height, channels, max_palette_size)
1076 i_img *img = i_img_pal_new(width, height, channels, max_palette_size)
1077 Creates a new paletted image of the supplied dimensions.
1079 "maxpal" is the maximum palette size and should normally be 256.
1081 Returns a new image or NULL on failure.
1083 Also callable as "i_img_pal_new(width, height, channels,
1085 max_palette_size)".
1086 i_img_destroy("img")
1088 i_img_destroy(img)
1089 Destroy an image object
1091 Image Implementation
1093 im_img_alloc(aIMCTX)
1094 i_img *im = im_img_alloc(aIMCTX);
1095 i_img *im = i_img_alloc();
1096 Allocates a new i_img structure.
1098 When implementing a new image type perform the following steps in
1100 your image object creation function:
1101 1. allocate the image with i_img_alloc().
1103 2. initialize any function pointers or other data as needed, you
1105 can overwrite the whole block if you need to.
1106 3. initialize Imager's internal data by calling i_img_init() on
1108 the image object.
1109 im_img_init(aIMCTX, image)
1111 im_img_init(aIMCTX, im);
1112 i_img_init(im);
1113 Imager internal initialization of images.
1115 See "im_img_alloc(aIMCTX)" for more information.
1117 Image Information
1119 i_img_alpha_channel(im, &channel)
1120 int alpha_channel;
1121 int has_alpha = i_img_alpha_channel(im, &alpha_channel);
1122 Work out the alpha channel for an image.
1124 If the image has an alpha channel, sets *channel to the alpha
1126 channel index and returns non-zero.
1127 If the image has no alpha channel, returns zero and *channel is not
1129 modified.
1130 "channel" may be "NULL".
1132 i_img_color_channels(im)
1134 int color_channels = i_img_color_channels(im);
1135 Returns the number of color channels in the image. For now this is
1137 always 1 (for grayscale) or 3 (for RGB) but may be 0 in some
1138 special cases in a future release of Imager.
1139 i_img_color_model(im)
1141 i_color_model_t cm = i_img_color_model(im);
1142 Returns the color model for the image.
1144 A future version of Imager will allow for images with extra
1146 channels beyond gray/rgb and alpha.
1147 i_img_get_height("im")
1149 i_img_dim height = i_img_get_height(im);
1150 Returns the height in pixels of the image.
1152 i_img_get_width("im")
1154 i_img_dim width = i_img_get_width(im);
1155 Returns the width in pixels of the image.
1157 i_img_getchannels("im")
1159 int channels = i_img_getchannels(img);
1160 Get the number of channels in "im".
1162 i_img_getmask("im")
1164 int mask = i_img_getmask(img);
1165 Get the image channel mask for "im".
1167 i_img_has_alpha("im")
1169 Return true if the image has an alpha channel.
1170 i_img_is_monochrome(img, &zero_is_white)
1172 Tests an image to check it meets our monochrome tests.
1173 The idea is that a file writer can use this to test where it should
1175 write the image in whatever bi-level format it uses, eg. "pbm" for
1176 "pnm".
1177 For performance of encoders we require monochrome images:
1179 • be paletted
1181 • have a palette of two colors, containing only "(0,0,0)" and
1183 "(255,255,255)" in either order.
1184 "zero_is_white" is set to non-zero if the first palette entry is
1186 white.
1187 i_img_setmask("im", "ch_mask")
1189 // only channel 0 writable
1190 i_img_setmask(img, 0x01);
1191 Set the image channel mask for "im" to "ch_mask".
1193 The image channel mask gives some control over which channels can
1195 be written to in the image.
1196 Image quantization
1198 i_quant_makemap("quant", "imgs", "count")
1199 Analyzes the "count" images in "imgs" according to the rules in
1200 "quant" to build a color map (optimal or not depending on
1201 "quant->make_colors").
1202 i_quant_translate("quant", "img")
1204 Quantize the image given the palette in "quant".
1205 On success returns a pointer to a memory block of "img->xsize *
1207 img->ysize" "i_palidx" entries.
1208 On failure returns NULL.
1210 You should call myfree() on the returned block when you're done
1212 with it.
1213 This function will fail if the supplied palette contains no colors.
1215 i_quant_transparent("quant", "data", "img", "trans_index")
1217 Dither the alpha channel on "img" into the palette indexes in
1218 "data". Pixels to be transparent are replaced with "trans_pixel".
1219 The method used depends on the tr_* members of "quant".
1221 Logging
1223 i_lhead(file, line)
1224 This is an internal function called by the mm_log() macro.
1225 i_loog(level, format, ...)
1227 This is an internal function called by the mm_log() macro.
1228 mutex
1230 i_mutex_t
1231 i_mutex_t mutex;
1232 Opaque type for Imager's mutex API.
1234 Mutex functions
1236 i_mutex_new()
1237 i_mutex_t m = i_mutex_new();
1238 Create a mutex.
1240 If a critical section cannot be created for whatever reason, Imager
1242 will abort.
1243 i_mutex_destroy(m)
1245 i_mutex_destroy(m);
1246 Destroy a mutex.
1248 i_mutex_lock(m)
1250 i_mutex_lock(m);
1251 Lock the mutex, waiting if another thread has the mutex locked.
1253 i_mutex_unlock(m)
1255 i_mutex_unlock(m);
1256 Release the mutex.
1258 The behavior of releasing a mutex you don't hold is unspecified.
1260 Paletted images
1262 i_addcolors(im, colors, count)
1263 Adds colors to the image's palette.
1264 On success returns the index of the lowest color added.
1266 On failure returns -1.
1268 Always fails for direct color images.
1270 i_colorcount(im)
1272 Returns the number of colors in the image's palette.
1273 Returns -1 for direct images.
1275 i_findcolor(im, color, &entry)
1277 Searches the images palette for the given color.
1278 On success sets *entry to the index of the color, and returns true.
1280 On failure returns false.
1282 Always fails on direct color images.
1284 i_getcolors(im, index, colors, count)
1286 Retrieves count colors starting from index in the image's palette.
1287 On success stores the colors into colors and returns true.
1289 On failure returns false.
1291 Always fails for direct color images.
1293 Fails if there are less than index+count colors in the image's
1295 palette.
1296 i_maxcolors(im)
1298 Returns the maximum number of colors the palette can hold for the
1299 image.
1300 Returns -1 for direct color images.
1302 i_setcolors(im, index, colors, count)
1304 Sets count colors starting from index in the image's palette.
1305 On success returns true.
1307 On failure returns false.
1309 The image must have at least index+count colors in it's palette for
1311 this to succeed.
1312 Always fails on direct color images.
1314 Tags
1316 i_tags_delbycode(tags, code)
1317 Delete any tags with the given code.
1318 Returns the number of tags deleted.
1320 i_tags_delbyname(tags, name)
1322 Delete any tags with the given name.
1323 Returns the number of tags deleted.
1325 i_tags_delete(tags, index)
1327 Delete a tag by index.
1328 Returns true on success.
1330 i_tags_destroy(tags)
1332 Destroys the given tags structure. Called by i_img_destroy().
1333 i_tags_find(tags, name, start, &entry)
1335 Searches for a tag of the given name starting from index start.
1336 On success returns true and sets *entry.
1338 On failure returns false.
1340 i_tags_findn(tags, code, start, &entry)
1342 Searches for a tag of the given code starting from index start.
1343 On success returns true and sets *entry.
1345 On failure returns false.
1347 i_tags_get_color(tags, name, code, &value)
1349 Retrieve a tag specified by name or code as color.
1350 On success sets the i_color *value to the color and returns true.
1352 On failure returns false.
1354 i_tags_get_float(tags, name, code, value)
1356 Retrieves a tag as a floating point value.
1357 If the tag has a string value then that is parsed as a floating
1359 point number, otherwise the integer value of the tag is used.
1360 On success sets *value and returns true.
1362 On failure returns false.
1364 i_tags_get_int(tags, name, code, &value)
1366 Retrieve a tag specified by name or code as an integer.
1367 On success sets the int *value to the integer and returns true.
1369 On failure returns false.
1371 i_tags_get_string(tags, name, code, value, value_size)
1373 Retrieves a tag by name or code as a string.
1374 On success copies the string to value for a max of value_size and
1376 returns true.
1377 On failure returns false.
1379 value_size must be at least large enough for a string
1381 representation of an integer.
1382 The copied value is always "NUL" terminated.
1384 i_tags_new(i_img_tags *tags)
1386 Initialize a tags structure. Should not be used if the tags
1387 structure has been previously used.
1388 This should be called tags member of an i_img object on creation
1390 (in i_img_*_new() functions).
1391 To destroy the contents use i_tags_destroy()
1393 i_tags_set(tags, name, data, size)
1395 i_tags_set(&img->tags, "i_comment", -1);
1396 Sets the given tag to the string data
1398 If size is -1 then the strlen(data) bytes are stored.
1400 Even on failure, if an existing tag name exists, it will be
1402 removed.
1403 i_tags_set_color(tags, name, code, &value)
1405 Stores the given color as a tag with the given name and code.
1406 i_tags_set_float(tags, name, code, value)
1408 Equivalent to i_tags_set_float2(tags, name, code, value, 30).
1409 i_tags_set_float2(tags, name, code, value, places)
1411 Sets the tag with the given name and code to the given floating
1412 point value.
1413 Since tags are strings or ints, we convert the value to a string
1415 before storage at the precision specified by "places".
1416 i_tags_setn("tags", "name", "idata")
1418 i_tags_setn(&img->tags, "i_xres", 204);
1419 i_tags_setn(&img->tags, "i_yres", 196);
1420 Sets the given tag to the integer "idata"
1422 Even on failure, if an existing tag "name" exists, it will be
1424 removed.
1425 Uncategorized functions
1427 i_utf8_advance(char **p, size_t *len)
1428 Retrieve a "UTF-8" character from the stream.
1429 Modifies *p and *len to indicate the consumed characters.
1431 This doesn't support the extended "UTF-8" encoding used by later
1433 versions of Perl. Since this is typically used to implement text
1434 output by font drivers, the strings supplied shouldn't have such
1435 out of range characters.
1436 This doesn't check that the "UTF-8" character is using the shortest
1438 possible representation.
1439 Returns ~0UL on failure.
1441 im_context_refdec(ctx, where) =section Context objects
1443 im_context_refdec(aIMCTX, "a description");
1444 Remove a reference to the context, releasing it if all references
1446 have been removed.
1447 im_context_refinc(ctx, where) =section Context objects
1449 im_context_refinc(aIMCTX, "a description");
1450 Add a new reference to the context.
1452 im_context_slot_get(ctx, slot)
1454 Retrieve the value previously stored in the given slot of the
1455 context object.
1456 im_context_slot_new(destructor)
1458 Allocate a new context-local-storage slot.
1459 "desctructor" will be called when the context is destroyed if the
1461 corresponding slot is non-NULL.
1462 im_context_slot_set(slot, value)
1464 Set the value of a slot.
1465 Returns true on success.
1467 Aborts if the slot supplied is invalid.
1469 If reallocation of slot storage fails, returns false.
1471 im_decode_exif
1473 im_decode_exif(im, data_base, data_size);
1474 The data from "data_base" for "data_size" bytes will be scanned for
1476 EXIF data.
1477 Any data found will be used to set tags in the supplied image.
1479 The intent is that invalid EXIF data will simply fail to set tags,
1481 and write to the log. In no case should this code exit when
1482 supplied invalid data.
1483 Returns true if an EXIF header was seen.
1485 im_errors(ctx)
1487 i_errmsg *errors = im_errors(aIMCTX);
1488 i_errmsg *errors = i_errors();
1489 Returns a pointer to the first element of an array of error
1491 messages, terminated by a NULL pointer. The highest level message
1492 is first.
1493 Also callable as "i_errors()".
1495 im_get_context()
1497 Retrieve the context object for the current thread.
1498 Inside Imager itself this is just a function pointer, which the
1500 Imager.xs BOOT handler initializes for use within perl. If you're
1501 taking the Imager code and embedding it elsewhere you need to
1502 initialize the "im_get_context" pointer at some point.
1503
1505 The following API functions are undocumented so far, hopefully this
1506 will change:
1507 • im_lhead
1509 • im_loog
1511 • mm_log
1513
1515 Tony Cook <tonyc@cpan.org>
1516
1518 Imager, Imager::API, Imager::ExtUtils, Imager::Inline
1519perl v5.34.0 2022-01-21 Imager::APIRef(3)