1Imager::APIRef(3)     User Contributed Perl Documentation    Imager::APIRef(3)
2
3
4

NAME

6       Imager::APIRef - Imager's C API - reference.
7

SYNOPSIS

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
18
19         # Blit tools
20
21         # 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
31         # 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
49         # 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
61         # 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
69         # 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
79         # 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
86         # Image
87
88         # 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
101         # 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
107         # 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
119         # Image quantization
120
121         # Logging
122
123         # mutex
124         i_mutex_t mutex;
125
126         # 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
132         # Paletted images
133
134         # 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

DESCRIPTION

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
145           Renders in normal combine mode.
146
147       i_render_delete(r)
148           Release an "i_render" object.
149
150       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
154       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
158       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
162       i_render_new(im, width)
163           Allocate a new "i_render" object and initialize it.
164
165   Data Types
166       i_img
167             i_img *img;
168
169           This is Imager's image type.
170
171           It contains the following members:
172
173           •   "channels" - the number of channels in the image
174
175           •   "xsize", "ysize" - the width and height of the image in pixels
176
177           •   "bytes" - the number of bytes used to store the image data.
178               Undefined where virtual is non-zero.
179
180           •   "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
184           •   "bits" - the number of bits stored per sample.  Should be one
185               of i_8_bits, i_16_bits, i_double_bits.
186
187           •   "type" - either i_direct_type for direct color images, or
188               i_palette_type for paletted images.
189
190           •   "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
194           •   "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
199           •   "tags" - a structure storing the image's tags.  This should
200               only be accessed via the i_tags_*() functions.
201
202           •   "ext_data" - a pointer for use internal to an image
203               implementation.  This should be freed by the image's destroy
204               handler.
205
206           •   "im_data" - data internal to Imager.  This is initialized by
207               i_img_init().
208
209           •   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
215           •   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
219           •   i_f_destroy - custom image destruction function.  This should
220               be used to release memory if necessary.
221
222           •   i_f_gsamp_bits - implements i_gsamp_bits() for this image.
223
224           •   i_f_psamp_bits - implements i_psamp_bits() for this image.
225
226           •   i_f_psamp - implements psamp() for this image.
227
228           •   i_f_psampf - implements psamp() for this image.
229
230           •   "im_data" - image specific data internal to Imager.
231
232           •   "context" - the Imager API context this image belongs to.
233
234       i_color
235             i_color black;
236             black.rgba.r = black.rgba.g = black.rgba.b = black.rgba.a = 0;
237
238           Type for 8-bit/sample color.
239
240           Samples as per;
241
242             i_color c;
243
244           i_color is a union of:
245
246           •   gray - contains a single element gray_color, eg.
247               "c.gray.gray_color"
248
249           •   "rgb" - contains three elements "r", "g", "b", eg. "c.rgb.r"
250
251           •   "rgba" - contains four elements "r", "g", "b", "a", eg.
252               "c.rgba.a"
253
254           •   "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
258           •   channels - an array of four channels, eg "c.channels[2]".
259
260       i_fcolor
261           This is the double/sample color type.
262
263           Its layout exactly corresponds to i_color.
264
265       i_fill_t
266             i_fill_t *fill;
267
268           This is the "abstract" base type for Imager's fill types.
269
270           Unless you're implementing a new fill type you'll typically treat
271           this as an opaque type.
272
273       i_poly_fill_mode_t
274           Control how polygons are filled.  Has the following values:
275
276           •   "i_pfm_evenodd" - simple even-odd fills.
277
278           •   "i_pfm_nonzero" - non-zero winding rule fills.
279
280       i_polygon_t
281           Represents a polygon.  Has the following members:
282
283           •   "x", "y" - arrays of x and y locations of vertices.
284
285           •   "count" - the number of entries in the "x" and "y" arrays.
286
287       im_context_t
288           Imager's per-thread context.
289
290       im_slot_t
291           Represents a slot in the context object.
292
293       i_img_dim
294             i_img_dim x, y;
295
296           A signed integer type that represents an image dimension or
297           ordinate.
298
299           May be larger than int on some platforms.
300
301       i_img_dim_u
302             i_img_dim_u limit;
303
304           An unsigned variant of "i_img_dim".
305
306       i_color_model_t
307           Returned by "i_img_color_model(im)" to indicate the color model of
308           the image.
309
310           An enumerated type with the following possible values:
311
312           •   "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
317           •   "icm_gray" - gray scale with no alpha channel.
318
319           •   "icm_gray_alpha" - gray scale with an alpha channel.
320
321           •   "icm_rgb" - RGB
322
323           •   "icm_rgb_alpha" - RGB with an alpha channel.
324
325       i_DF
326             printf("left %" i_DF "\n", i_DFc(x));
327
328           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
332           Does not include the leading "%".
333
334       i_DFc
335           Cast an "i_img_dim" value to a type for use with the i_DF format
336           string.
337
338       i_DFcp
339           Casts two "i_img_dim" values for use with the i_DF (or i_DFp)
340           format.
341
342       i_DFp
343             printf("point (" i_DFp ")\n", i_DFcp(x, y));
344
345           Format a pair of "i_img_dim" values.  This format string does
346           include the leading "%".
347
348   Drawing
349       i_arc(im, x, y, rad, d1, d2, color)
350             i_arc(im, 50, 50, 20, 45, 135, &color);
351
352           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
355       i_arc_aa(im, x, y, rad, d1, d2, color)
356             i_arc_aa(im, 50, 50, 35, 90, 135, &color);
357
358           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
361       i_arc_aa_cfill(im, x, y, rad, d1, d2, fill)
362             i_arc_aa_cfill(im, 50, 50, 35, 90, 135, fill);
363
364           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
367       i_arc_cfill(im, x, y, rad, d1, d2, fill)
368             i_arc_cfill(im, 50, 50, 35, 90, 135, fill);
369
370           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
373       i_box(im, x1, y1, x2, y2, color)
374             i_box(im, 0, 0, im->xsize-1, im->ysize-1, &color).
375
376           Outlines the box from (x1,y1) to (x2,y2) inclusive with color.
377
378       i_box_cfill(im, x1, y1, x2, y2, fill)
379             i_box_cfill(im, 0, 0, im->xsize-1, im->ysize-1, fill);
380
381           Fills the box from (x1,y1) to (x2,y2) inclusive with fill.
382
383       i_box_filled(im, x1, y1, x2, y2, color)
384             i_box_filled(im, 0, 0, im->xsize-1, im->ysize-1, &color);
385
386           Fills the box from (x1,y1) to (x2,y2) inclusive with color.
387
388       i_circle_aa(im, x, y, rad, color)
389             i_circle_aa(im, 50, 50, 45, &color);
390
391           Anti-alias fills a circle centered at (x,y) for radius rad with
392           color.
393
394       i_flood_cfill("im", "seedx", "seedy", "fill")
395             i_flood_cfill(im, 50, 50, fill);
396
397           Flood fills the 4-connected region starting from the point
398           ("seedx", "seedy") with "fill".
399
400           Returns false if ("seedx", "seedy") are outside the image.
401
402       i_flood_cfill_border("im", "seedx", "seedy", "fill", "border")
403             i_flood_cfill_border(im, 50, 50, fill, border);
404
405           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
409           Returns false if ("seedx", "seedy") are outside the image.
410
411       i_flood_fill("im", "seedx", "seedy", "color")
412             i_flood_fill(im, 50, 50, &color);
413
414           Flood fills the 4-connected region starting from the point
415           ("seedx", "seedy") with color.
416
417           Returns false if ("seedx", "seedy") are outside the image.
418
419       i_flood_fill_border("im", "seedx", "seedy", "color", "border")
420             i_flood_fill_border(im, 50, 50, &color, &border);
421
422           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
426           Returns false if ("seedx", "seedy") are outside the image.
427
428       i_glin(im, l, r, y, colors)
429           Retrieves (r-l) pixels starting from (l,y) into colors.
430
431           Returns the number of pixels retrieved.
432
433       i_glinf(im, l, r, y, colors)
434           Retrieves (r-l) pixels starting from (l,y) into colors as floating
435           point colors.
436
437           Returns the number of pixels retrieved.
438
439       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
443           Returns the number of indexes read.
444
445           Always returns 0 for direct color images.
446
447       i_gpix(im, "x", "y", "color")
448           Retrieves the "color" of the pixel (x,y).
449
450           Returns 0 if the pixel was retrieved, or -1 if not.
451
452       i_gpixf(im, "x", "y", "fcolor")
453           Retrieves the color of the pixel (x,y) as a floating point color
454           into "fcolor".
455
456           Returns 0 if the pixel was retrieved, or -1 if not.
457
458       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
463           If channels is NULL then the first channels_count channels are
464           retrieved for each pixel.
465
466           Returns the number of samples read (which should be (right-left) *
467           channel_count)
468
469       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
473           This is intended for output to image formats that don't support
474           alpha channels.
475
476       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
481           Expect this to be slow unless "bits == im->bits".
482
483           Returns the number of samples copied, or -1 on error.
484
485           Not all image types implement this method.
486
487           Pushes errors, but does not call "i_clear_error()".
488
489       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
494           If "channels" is NULL then the first "channel_count" channels are
495           retrieved for each pixel.
496
497           Returns the number of samples read (which should be
498           ("right"-"left") * "channel_count")
499
500       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
504           This is intended for output to image formats that don't support
505           alpha channels.
506
507       i_line("im", "x1", "y1", "x2", "y2", "color", "endp")
508           Draw a line to image using Bresenham's line drawing algorithm
509
510              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
518       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
521           The point (x2, y2) is drawn only if "endp" is set.
522
523       i_plin(im, l, r, y, colors)
524           Sets (r-l) pixels starting from (l,y) using (r-l) values from
525           colors.
526
527           Returns the number of pixels set.
528
529       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
533           Returns the number of pixels set.
534
535       i_poly_aa_cfill_m(im, count, x, y, mode, fill)
536             i_poly_aa_cfill(im, count, x, y, mode, fill);
537
538           Fill a polygon defined by the points specified by the x and y
539           arrays with the fill specified by "fill".
540
541       i_poly_aa_m(im, count, x, y, mode, color)
542             i_poly_aa_m(im, count, x, y, mode, color);
543
544           Fill a polygon defined by the points specified by the x and y
545           arrays with the color specified by "color".
546
547       i_poly_poly_aa(im, count, polys, mode, color)
548             i_poly_poly_aa(im, 1, &poly, mode, color);
549
550           Fill the "count" polygons defined by "polys" the color specified by
551           "color".
552
553           At least one polygon must be supplied.
554
555           All polygons must have at least 3 points.
556
557       i_poly_poly_aa_cfill(im, count, polys, mode, fill)
558             i_poly_poly_aa_cfill(im, 1, &poly, mode, fill);
559
560           Fill the "count" polygons defined by "polys" the fill specified by
561           "fill".
562
563           At least one polygon must be supplied.
564
565           All polygons must have at least 3 points.
566
567       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
571           Returns the number of indexes written.
572
573           Always returns 0 for direct color images.
574
575       i_ppix(im, x, y, color)
576           Sets the pixel at (x,y) to color.
577
578           Returns 0 if the pixel was drawn, or -1 if not.
579
580           Does no alpha blending, just copies the channels from the supplied
581           color to the image.
582
583       i_ppixf(im, "x", "y", "fcolor")
584           Sets the pixel at ("x","y") to the floating point color "fcolor".
585
586           Returns 0 if the pixel was drawn, or -1 if not.
587
588           Does no alpha blending, just copies the channels from the supplied
589           color to the image.
590
591       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
596           If "channels" is "NULL" then the first "channels_count" channels
597           are written to for each pixel.
598
599           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
604       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
609           Expect this to be slow unless "bits == im->bits".
610
611           Returns the number of samples copied, or -1 on error.
612
613           Not all image types implement this method.
614
615           Pushes errors, but does not call "i_clear_error()".
616
617       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
623           If "channels" is "NULL" then the first "channels_count" channels
624           are written to for each pixel.
625
626           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
631   Error handling
632       i_push_errorf(int code, char const *fmt, ...)
633             i_push_errorf(errno, "Cannot open file %s: %d", filename, errno);
634
635           A version of i_push_error() that does printf() like formatting.
636
637           Does not support perl specific format codes.
638
639       im_clear_error(ctx)
640             im_clear_error(aIMCTX);
641             i_clear_error();
642
643           Clears the error stack.
644
645           Called by any Imager function before doing any other processing.
646
647           Also callable as "i_clear_error()".
648
649       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
654           Called by an Imager function to push an error message onto the
655           stack.
656
657           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
661       im_push_errorf(ctx, code, char const *fmt, ...)
662             im_push_errorf(aIMCTX, errno, "Cannot open file %s: %d", filename, errno);
663
664           A version of im_push_error() that does printf() like formatting.
665
666           Does not support perl specific format codes.
667
668       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
673           Intended for use by higher level functions, takes a varargs pointer
674           and a format to produce the finally pushed error message.
675
676           Does not support perl specific format codes.
677
678           Also callable as "i_push_errorvf(code, format, args)"
679
680   Files
681       i_get_file_background(im, &bg)
682           Retrieve the file write background color tag from the image.
683
684           If not present, "bg" is set to black.
685
686           Returns 1 if the "i_background" tag was found and valid.
687
688       i_get_file_backgroundf(im, &bg)
689           Retrieve the file write background color tag from the image as a
690           floating point color.
691
692           Implemented in terms of i_get_file_background().
693
694           If not present, "bg" is set to black.
695
696           Returns 1 if the "i_background" tag was found and valid.
697
698       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
702           Retrieves the file limits set by i_set_image_file_limits().
703
704           •   i_img_dim *width, *height - the maximum width and height of the
705               image.
706
707           •   size_t *bytes - size in memory of the image in bytes.
708
709           Also callable as "i_get_image_file_limits(&width, &height,
710           &bytes)".
711
712       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
716           Checks the size of a file in memory against the configured image
717           file limits.
718
719           This also range checks the values to those permitted by Imager and
720           checks for overflows in calculating the size.
721
722           Returns non-zero if the file is within limits.
723
724           This function is intended to be called by image file read
725           functions.
726
727           Also callable as "i_int_check_image_file_limits(width, height,
728           channels, sizeof(i_sample_t)".
729
730       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
734           Set limits on the sizes of images read by Imager.
735
736           Setting a limit to 0 means that limit is ignored.
737
738           Negative limits result in failure.
739
740           Parameters:
741
742           •   i_img_dim width, height - maximum width and height.
743
744           •   size_t bytes - maximum size in memory in bytes.  A value of
745               zero sets this limit to one gigabyte.
746
747           Returns non-zero on success.
748
749           Also callable as "i_set_image_file_limits(width, height, bytes)".
750
751   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
757           Creates a new general fill which fills with a fountain fill.
758
759       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
763           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
767           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
770           If "cust_hatch" is NULL then one of the standard hatches is used.
771
772           ("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
776       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
780           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
784           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
787           If "cust_hatch" is NULL then one of the standard hatches is used.
788
789           ("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
793       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
796           Create an image based fill.
797
798           matrix is an array of 9 doubles representing a transformation
799           matrix.
800
801           "xoff" and "yoff" are the offset into the image to start filling
802           from.
803
804       i_new_fill_solid(color, combine)
805             i_fill_t *fill = i_new_fill_solid(&color, combine);
806
807           Create a solid fill based on an 8-bit color.
808
809           If combine is non-zero then alpha values will be combined.
810
811       i_new_fill_solidf(color, combine)
812             i_fill_t *fill = i_new_fill_solidf(&fcolor, combine);
813
814           Create a solid fill based on a float color.
815
816           If combine is non-zero then alpha values will be combined.
817
818       i_fill_destroy(fill)
819             i_fill_destroy(fill);
820
821           Call to destroy any fill object.
822
823   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
828           Also callable as "io_new_bufchain()".
829
830       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
834              ctx - an Imager context object
835              data - buffer to read from
836              length - length of buffer
837
838           Also callable as "io_new_buffer(data, length".
839
840       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
843           In general the callbacks should behave like the corresponding POSIX
844           primitives.
845
846           •   "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
850           •   "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
854           •   "seekcb"(p, offset, whence) should seek and return the new
855               offset.
856
857           •   "close_cb"(p) should return 0 on success, -1 on failure.
858
859           •   "destroy_cb"(p) should release any memory specific to your
860               callback handlers.
861
862           Also callable as "io_new_cb(p, readcb, writecb, seekcb, closecb,
863           destroycb)".
864
865       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
870             ctx - and Imager context object
871             file - file descriptor to read/write from
872
873           Also callable as "io_new_fd(file)".
874
875       i_io_close(io)
876           Flush any pending output and perform the close action for the
877           stream.
878
879           Returns 0 on success.
880
881       i_io_flush(io)
882           Flush any buffered output.
883
884           Returns true on success,
885
886       i_io_getc(ig)
887           A macro to read a single byte from a buffered I/O glue object.
888
889           Returns EOF on failure, or a byte.
890
891       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
895           Read up to "size"-1 bytes from the stream "ig" into "buffer".
896
897           If the byte "end_of_line" is seen then no further bytes will be
898           read.
899
900           Returns the number of bytes read.
901
902           Always "NUL" terminates the buffer.
903
904       i_io_peekc(ig)
905           Read the next character from the stream without advancing the
906           stream.
907
908           On error or end of file, return EOF.
909
910           For unbuffered streams a single character buffer will be setup.
911
912       i_io_peekn(ig, buffer, size)
913             ssize_t count = i_io_peekn(ig, buffer, sizeof(buffer));
914
915           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
918           This ignores the buffered state of the stream, and will always
919           setup buffering if needed.
920
921           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
925           Returns -1 on error, 0 if there is no data before EOF, or the
926           number of bytes read into "buffer".
927
928       i_io_putc(ig, c)
929           Write a single character to the stream.
930
931           On success return c, on error returns EOF
932
933       i_io_read(io, buffer, size)
934           Read up to "size" bytes from the stream "io" into "buffer".
935
936           Returns the number of bytes read.  Returns 0 on end of file.
937           Returns -1 on error.
938
939       i_io_seek(io, offset, whence)
940           Seek within the stream.
941
942           Acts like perl's seek.
943
944       i_io_set_buffered(io, buffered)
945           Set the buffering mode of the stream.
946
947           If you switch buffering off on a stream with buffering on:
948
949           •   any buffered output will be flushed.
950
951           •   any existing buffered input will be consumed before reads
952               become unbuffered.
953
954           Returns true on success.  This may fail if any buffered output
955           cannot be flushed.
956
957       i_io_write(io, buffer, size)
958             ssize_t result = i_io_write(io, buffer, size)
959
960           Write to the given I/O stream.
961
962           Returns the number of bytes written.
963
964       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
970              ig - io_glue object
971              c  - pointer to a pointer to where data should be copied to
972
973             char *data;
974             size_t size = io_slurp(ig, &data);
975             ... do something with the data ...
976             myfree(data);
977
978           io_slurp() will abort the program if the supplied I/O layer is not
979           from io_new_bufchain().
980
981       io_glue_destroy(ig)
982             io_glue_destroy(ig);
983
984           Destroy an io_glue objects.  Should clean up all related buffers.
985
986              ig - io_glue object to destroy.
987
988   Image
989       i_copy(source)
990           Creates a new image that is a copy of the image "source".
991
992           Tags are not copied, only the image data.
993
994           Returns: i_img *
995
996       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
1001           If "x1" > "x2" or "y1" > "y2" then the corresponding co-ordinates
1002           are swapped.
1003
1004       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
1010       i_img_info(im, info)
1011           Return image information
1012
1013              im - Image pointer
1014              info - pointer to array to return data
1015
1016           info is an array of 4 integers with the following values:
1017
1018            info[0] - width
1019            info[1] - height
1020            info[2] - channels
1021            info[3] - channel mask
1022
1023       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
1028           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
1033   Image creation/destruction
1034       i_sametype("im", "xsize", "ysize")
1035             i_img *img = i_sametype(src, width, height);
1036
1037           Returns an image of the same type (sample size, channels,
1038           paletted/direct).
1039
1040           For paletted images the palette is copied from the source.
1041
1042       i_sametype_chans("im", "xsize", "ysize", "channels")
1043             i_img *img = i_sametype_chans(src, width, height, channels);
1044
1045           Returns an image of the same type (sample size).
1046
1047           For paletted images the equivalent direct type is returned.
1048
1049       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
1053           Create a new 16-bit/sample image.
1054
1055           Returns the image on success, or NULL on failure.
1056
1057           Also callable as "i_img_16_new(x, y, ch)"
1058
1059       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
1063           Creates a new image object x pixels wide, and y pixels high with ch
1064           channels.
1065
1066       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
1070           Creates a new double per sample image.
1071
1072           Also callable as "i_img_double_new(width, height, channels)".
1073
1074       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
1078           Creates a new paletted image of the supplied dimensions.
1079
1080           "maxpal" is the maximum palette size and should normally be 256.
1081
1082           Returns a new image or NULL on failure.
1083
1084           Also callable as "i_img_pal_new(width, height, channels,
1085           max_palette_size)".
1086
1087       i_img_destroy("img")
1088             i_img_destroy(img)
1089
1090           Destroy an image object
1091
1092   Image Implementation
1093       im_img_alloc(aIMCTX)
1094             i_img *im = im_img_alloc(aIMCTX);
1095             i_img *im = i_img_alloc();
1096
1097           Allocates a new i_img structure.
1098
1099           When implementing a new image type perform the following steps in
1100           your image object creation function:
1101
1102           1.  allocate the image with i_img_alloc().
1103
1104           2.  initialize any function pointers or other data as needed, you
1105               can overwrite the whole block if you need to.
1106
1107           3.  initialize Imager's internal data by calling i_img_init() on
1108               the image object.
1109
1110       im_img_init(aIMCTX, image)
1111             im_img_init(aIMCTX, im);
1112             i_img_init(im);
1113
1114           Imager internal initialization of images.
1115
1116           See "im_img_alloc(aIMCTX)" for more information.
1117
1118   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
1123           Work out the alpha channel for an image.
1124
1125           If the image has an alpha channel, sets *channel to the alpha
1126           channel index and returns non-zero.
1127
1128           If the image has no alpha channel, returns zero and *channel is not
1129           modified.
1130
1131           "channel" may be "NULL".
1132
1133       i_img_color_channels(im)
1134             int color_channels = i_img_color_channels(im);
1135
1136           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
1140       i_img_color_model(im)
1141             i_color_model_t cm = i_img_color_model(im);
1142
1143           Returns the color model for the image.
1144
1145           A future version of Imager will allow for images with extra
1146           channels beyond gray/rgb and alpha.
1147
1148       i_img_get_height("im")
1149             i_img_dim height = i_img_get_height(im);
1150
1151           Returns the height in pixels of the image.
1152
1153       i_img_get_width("im")
1154             i_img_dim width = i_img_get_width(im);
1155
1156           Returns the width in pixels of the image.
1157
1158       i_img_getchannels("im")
1159             int channels = i_img_getchannels(img);
1160
1161           Get the number of channels in "im".
1162
1163       i_img_getmask("im")
1164             int mask = i_img_getmask(img);
1165
1166           Get the image channel mask for "im".
1167
1168       i_img_has_alpha("im")
1169           Return true if the image has an alpha channel.
1170
1171       i_img_is_monochrome(img, &zero_is_white)
1172           Tests an image to check it meets our monochrome tests.
1173
1174           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
1178           For performance of encoders we require monochrome images:
1179
1180           •   be paletted
1181
1182           •   have a palette of two colors, containing only "(0,0,0)" and
1183               "(255,255,255)" in either order.
1184
1185           "zero_is_white" is set to non-zero if the first palette entry is
1186           white.
1187
1188       i_img_setmask("im", "ch_mask")
1189             // only channel 0 writable
1190             i_img_setmask(img, 0x01);
1191
1192           Set the image channel mask for "im" to "ch_mask".
1193
1194           The image channel mask gives some control over which channels can
1195           be written to in the image.
1196
1197   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
1203       i_quant_translate("quant", "img")
1204           Quantize the image given the palette in "quant".
1205
1206           On success returns a pointer to a memory block of "img->xsize *
1207           img->ysize" "i_palidx" entries.
1208
1209           On failure returns NULL.
1210
1211           You should call myfree() on the returned block when you're done
1212           with it.
1213
1214           This function will fail if the supplied palette contains no colors.
1215
1216       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
1220           The method used depends on the tr_* members of "quant".
1221
1222   Logging
1223       i_lhead(file, line)
1224           This is an internal function called by the mm_log() macro.
1225
1226       i_loog(level, format, ...)
1227           This is an internal function called by the mm_log() macro.
1228
1229   mutex
1230       i_mutex_t
1231             i_mutex_t mutex;
1232
1233           Opaque type for Imager's mutex API.
1234
1235   Mutex functions
1236       i_mutex_new()
1237             i_mutex_t m = i_mutex_new();
1238
1239           Create a mutex.
1240
1241           If a critical section cannot be created for whatever reason, Imager
1242           will abort.
1243
1244       i_mutex_destroy(m)
1245             i_mutex_destroy(m);
1246
1247           Destroy a mutex.
1248
1249       i_mutex_lock(m)
1250             i_mutex_lock(m);
1251
1252           Lock the mutex, waiting if another thread has the mutex locked.
1253
1254       i_mutex_unlock(m)
1255             i_mutex_unlock(m);
1256
1257           Release the mutex.
1258
1259           The behavior of releasing a mutex you don't hold is unspecified.
1260
1261   Paletted images
1262       i_addcolors(im, colors, count)
1263           Adds colors to the image's palette.
1264
1265           On success returns the index of the lowest color added.
1266
1267           On failure returns -1.
1268
1269           Always fails for direct color images.
1270
1271       i_colorcount(im)
1272           Returns the number of colors in the image's palette.
1273
1274           Returns -1 for direct images.
1275
1276       i_findcolor(im, color, &entry)
1277           Searches the images palette for the given color.
1278
1279           On success sets *entry to the index of the color, and returns true.
1280
1281           On failure returns false.
1282
1283           Always fails on direct color images.
1284
1285       i_getcolors(im, index, colors, count)
1286           Retrieves count colors starting from index in the image's palette.
1287
1288           On success stores the colors into colors and returns true.
1289
1290           On failure returns false.
1291
1292           Always fails for direct color images.
1293
1294           Fails if there are less than index+count colors in the image's
1295           palette.
1296
1297       i_maxcolors(im)
1298           Returns the maximum number of colors the palette can hold for the
1299           image.
1300
1301           Returns -1 for direct color images.
1302
1303       i_setcolors(im, index, colors, count)
1304           Sets count colors starting from index in the image's palette.
1305
1306           On success returns true.
1307
1308           On failure returns false.
1309
1310           The image must have at least index+count colors in it's palette for
1311           this to succeed.
1312
1313           Always fails on direct color images.
1314
1315   Tags
1316       i_tags_delbycode(tags, code)
1317           Delete any tags with the given code.
1318
1319           Returns the number of tags deleted.
1320
1321       i_tags_delbyname(tags, name)
1322           Delete any tags with the given name.
1323
1324           Returns the number of tags deleted.
1325
1326       i_tags_delete(tags, index)
1327           Delete a tag by index.
1328
1329           Returns true on success.
1330
1331       i_tags_destroy(tags)
1332           Destroys the given tags structure.  Called by i_img_destroy().
1333
1334       i_tags_find(tags, name, start, &entry)
1335           Searches for a tag of the given name starting from index start.
1336
1337           On success returns true and sets *entry.
1338
1339           On failure returns false.
1340
1341       i_tags_findn(tags, code, start, &entry)
1342           Searches for a tag of the given code starting from index start.
1343
1344           On success returns true and sets *entry.
1345
1346           On failure returns false.
1347
1348       i_tags_get_color(tags, name, code, &value)
1349           Retrieve a tag specified by name or code as color.
1350
1351           On success sets the i_color *value to the color and returns true.
1352
1353           On failure returns false.
1354
1355       i_tags_get_float(tags, name, code, value)
1356           Retrieves a tag as a floating point value.
1357
1358           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
1361           On success sets *value and returns true.
1362
1363           On failure returns false.
1364
1365       i_tags_get_int(tags, name, code, &value)
1366           Retrieve a tag specified by name or code as an integer.
1367
1368           On success sets the int *value to the integer and returns true.
1369
1370           On failure returns false.
1371
1372       i_tags_get_string(tags, name, code, value, value_size)
1373           Retrieves a tag by name or code as a string.
1374
1375           On success copies the string to value for a max of value_size and
1376           returns true.
1377
1378           On failure returns false.
1379
1380           value_size must be at least large enough for a string
1381           representation of an integer.
1382
1383           The copied value is always "NUL" terminated.
1384
1385       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
1389           This should be called tags member of an i_img object on creation
1390           (in i_img_*_new() functions).
1391
1392           To destroy the contents use i_tags_destroy()
1393
1394       i_tags_set(tags, name, data, size)
1395             i_tags_set(&img->tags, "i_comment", -1);
1396
1397           Sets the given tag to the string data
1398
1399           If size is -1 then the strlen(data) bytes are stored.
1400
1401           Even on failure, if an existing tag name exists, it will be
1402           removed.
1403
1404       i_tags_set_color(tags, name, code, &value)
1405           Stores the given color as a tag with the given name and code.
1406
1407       i_tags_set_float(tags, name, code, value)
1408           Equivalent to i_tags_set_float2(tags, name, code, value, 30).
1409
1410       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
1414           Since tags are strings or ints, we convert the value to a string
1415           before storage at the precision specified by "places".
1416
1417       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
1421           Sets the given tag to the integer "idata"
1422
1423           Even on failure, if an existing tag "name" exists, it will be
1424           removed.
1425
1426   Uncategorized functions
1427       i_utf8_advance(char **p, size_t *len)
1428           Retrieve a "UTF-8" character from the stream.
1429
1430           Modifies *p and *len to indicate the consumed characters.
1431
1432           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
1437           This doesn't check that the "UTF-8" character is using the shortest
1438           possible representation.
1439
1440           Returns ~0UL on failure.
1441
1442       im_context_refdec(ctx, where) =section Context objects
1443             im_context_refdec(aIMCTX, "a description");
1444
1445           Remove a reference to the context, releasing it if all references
1446           have been removed.
1447
1448       im_context_refinc(ctx, where) =section Context objects
1449             im_context_refinc(aIMCTX, "a description");
1450
1451           Add a new reference to the context.
1452
1453       im_context_slot_get(ctx, slot)
1454           Retrieve the value previously stored in the given slot of the
1455           context object.
1456
1457       im_context_slot_new(destructor)
1458           Allocate a new context-local-storage slot.
1459
1460           "desctructor" will be called when the context is destroyed if the
1461           corresponding slot is non-NULL.
1462
1463       im_context_slot_set(slot, value)
1464           Set the value of a slot.
1465
1466           Returns true on success.
1467
1468           Aborts if the slot supplied is invalid.
1469
1470           If reallocation of slot storage fails, returns false.
1471
1472       im_decode_exif
1473           im_decode_exif(im, data_base, data_size);
1474
1475           The data from "data_base" for "data_size" bytes will be scanned for
1476           EXIF data.
1477
1478           Any data found will be used to set tags in the supplied image.
1479
1480           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
1484           Returns true if an EXIF header was seen.
1485
1486       im_errors(ctx)
1487             i_errmsg *errors = im_errors(aIMCTX);
1488             i_errmsg *errors = i_errors();
1489
1490           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
1494           Also callable as "i_errors()".
1495
1496       im_get_context()
1497           Retrieve the context object for the current thread.
1498
1499           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

UNDOCUMENTED

1505       The following API functions are undocumented so far, hopefully this
1506       will change:
1507
1508im_lhead
1509
1510im_loog
1511
1512mm_log
1513

AUTHOR

1515       Tony Cook <tonyc@cpan.org>
1516

SEE ALSO

1518       Imager, Imager::API, Imager::ExtUtils, Imager::Inline
1519
1520
1521
1522perl v5.34.0                      2022-01-21                 Imager::APIRef(3)
Impressum