1Imager::APIRef(3) User Contributed Perl Documentation Imager::APIRef(3)
2
6 Imager::APIRef - Imager's C API.
7
9 i_color color;
10 color.rgba.red = 255; color.rgba.green = 0; color.rgba.blue = 255;
11 # Data Types
13 i_img *img;
14 # Drawing
16 i_arc(im, 50, 50, 20, 45, 135, &color);
17 i_arc_aa(im, 50, 50, 35, 90, 135, &color);
18 i_arc_aa_cfill(im, 50, 50, 35, 90, 135, fill);
19 i_arc_cfill(im, 50, 50, 35, 90, 135, fill);
20 i_box(im, 0, 0, im->xsize-1, im->ysize-1, &color).
21 i_box_cfill(im, 0, 0, im->xsize-1, im->ysize-1, fill);
22 i_box_filled(im, 0, 0, im->xsize-1, im->ysize-1, &color);
23 i_circle_aa(im, 50, 50, 45, &color);
24 i_flood_cfill(im, 50, 50, fill);
25 i_flood_cfill_border(im, 50, 50, fill, border);
26 i_flood_fill(im, 50, 50, &color);
27 i_flood_fill_border(im, 50, 50, &color, &border);
28 # Error handling
30 # Files
32 i_get_image_file_limits(&width, &height, &bytes)
33 i_i_int_check_image_file_limits(width, height, channels, sizeof(i_sample_t))
34 i_set_image_file_limits(500, 500, 1000000);
35 # Fills
37 i_fill_destroy(fill);
38 fill = i_new_fill_fount(0, 0, 100, 100, i_ft_linear, i_ft_linear,
39 i_fr_triangle, 0, i_fts_grid, 9, 1, segs);
40 i_fill_t *fill = i_new_fill_hatch(&fg_color, &bg_color, combine, hatch, custom_hatch, dx, dy);
41 i_fill_t *fill = i_new_fill_hatchf(&fg_fcolor, &bg_fcolor, combine, hatch, custom_hatch, dx, dy);
42 i_fill_t *fill = i_new_fill_image(src_img, matrix, x_offset, y_offset, combine);
43 i_fill_t *fill = i_new_fill_solid(&color, combine);
44 i_fill_t *fill = i_new_fill_solidf(&fcolor, combine);
45 # Image
47 # Image creation
49 i_img *img = i_img_16_new(width, height, channels);
50 # Image creation/destruction
52 i_img *img = i_img_8_new(width, height, channels);
53 i_img_destroy(img)
54 i_img *img = i_img_double_new(width, height, channels);
55 i_img *img = i_img_pal_new(width, height, channels, max_palette_size)
56 i_img *img = i_sametype(src, width, height);
57 i_img *img = i_sametype_chans(src, width, height, channels);
58 # Image Implementation
60 # Image Information
62 # Image quantization
64 # Logging
66 # Paletted images
68 # Tags
70
72 Data Types
73 i_img
75 This is Imager's image type.
76 It contains the following members:
78 * channels - the number of channels in the image
80 * xsize, ysize - the width and height of the image in pixels
82 * bytes - the number of bytes used to store the image data.
84 Undefined where virtual is non-zero.
85 * ch_mask - a mask of writable channels. eg. if this is 6 then
87 only channels 1 and 2 are writable. There may be bits set for
88 which there are no channels in the image.
89 * bits - the number of bits stored per sample. Should be one of
91 i_8_bits, i_16_bits, i_double_bits.
92 * type - either i_direct_type for direct color images, or i_pal‐
94 ette_type for paletted images.
95 * virtual - if zero then this image is-self contained. If non-
97 zero then this image could be an interface to some other imple‐
98 mentation.
99 * idata - the image data. This should not be directly accessed.
101 A new image implementation can use this to store its image
102 data. i_img_destroy() will myfree() this pointer if it's
103 non-null.
104 * tags - a structure storing the image's tags. This should only
106 be accessed via the i_tags_*() functions.
107 * ext_data - a pointer for use internal to an image implementa‐
109 tion. This should be freed by the image's destroy handler.
110 * im_data - data internal to Imager. This is initialized by
112 i_img_init().
113 * i_f_ppix, i_f_ppixf, i_f_plin, i_f_plinf, i_f_gpix, i_f_gpixf,
115 i_f_glin, i_f_glinf, i_f_gsamp, i_f_gampf - implementations for
116 each of the required image functions. An image implementation
117 should initialize these between calling i_img_alloc() and
118 i_img_init().
119 * i_f_gpal, i_f_ppal, i_f_addcolors, i_f_getcolors, i_f_color‐
121 count, i_f_maxcolors, i_f_findcolor, i_f_setcolors - implemen‐
122 tations for each paletted image function.
123 * i_f_destroy - custom image destruction function. This should
125 be used to release memory if necessary.
126 * i_f_gsamp_bits - implements i_gsamp_bits() for this image.
128 * i_f_psamp_bits - implements i_psamp_bits() for this image.
130 Drawing
132 i_arc(im, x, y, rad, d1, d2, color)
134 Fills an arc centered at (x,y) with radius rad covering the range
135 of angles in degrees from d1 to d2, with the color.
136 i_arc_aa(im, x, y, rad, d1, d2, color)
138 Antialias fills an arc centered at (x,y) with radius rad covering
139 the range of angles in degrees from d1 to d2, with the color.
140 i_arc_aa_cfill(im, x, y, rad, d1, d2, fill)
142 Antialias fills an arc centered at (x,y) with radius rad covering
143 the range of angles in degrees from d1 to d2, with the fill object.
144 i_arc_cfill(im, x, y, rad, d1, d2, fill)
146 Fills an arc centered at (x,y) with radius rad covering the range
147 of angles in degrees from d1 to d2, with the fill object.
148 i_box(im, x1, y1, x2, y2, color)
150 Outlines the box from (x1,y1) to (x2,y2) inclusive with color.
151 i_box_cfill(im, x1, y1, x2, y2, fill)
153 Fills the box from (x1,y1) to (x2,y2) inclusive with fill.
154 i_box_filled(im, x1, y1, x2, y2, color)
156 Fills the box from (x1,y1) to (x2,y2) inclusive with color.
157 i_circle_aa(im, x, y, rad, color)
159 Antialias fills a circle centered at (x,y) for radius rad with
160 color.
161 i_flood_cfill(im, seedx, seedy, fill)
163 Flood fills the 4-connected region starting from the point (seedx,
164 seedy) with fill.
165 Returns false if (seedx, seedy) are outside the image.
167 i_flood_cfill_border(im, seedx, seedy, fill, border)
169 Flood fills the 4-connected region starting from the point (seedx,
170 seedy) with fill, the fill stops when it reaches pixels of color
171 border.
172 Returns false if (seedx, seedy) are outside the image.
174 i_flood_fill(im, seedx, seedy, color)
176 Flood fills the 4-connected region starting from the point (seedx,
177 seedy) with color.
178 Returns false if (seedx, seedy) are outside the image.
180 i_flood_fill_border(im, seedx, seedy, color, border)
182 Flood fills the 4-connected region starting from the point (seedx,
183 seedy) with color, fill stops when the fill reaches a pixels with
184 color border.
185 Returns false if (seedx, seedy) are outside the image.
187 i_glin(im, l, r, y, colors)
189 Retrieves (r-l) pixels starting from (l,y) into colors.
190 Returns the number of pixels retrieved.
192 i_glinf(im, l, r, y, colors)
194 Retrieves (r-l) pixels starting from (l,y) into colors as floating
195 point colors.
196 Returns the number of pixels retrieved.
198 i_gpal(im, x, r, y, indexes)
200 Reads palette indexes for the horizontal line (x, y) to (r-1, y)
201 into indexes.
202 Returns the number of indexes read.
204 Always returns 0 for direct color images.
206 i_gpix(im, x, y, color)
208 Retrieves the color of the pixel (x,y).
209 Returns 0 if the pixel was retrieved, or -1 if not.
211 i_gpixf(im, x, y, fcolor)
213 Retrieves the color of the pixel (x,y) as a floating point color
214 into fcolor.
215 Returns 0 if the pixel was retrieved, or -1 if not.
217 i_gsamp(im, l, r, y, samp, chans, chan_count)
219 Reads sample values from im for the horizontal line (l, y) to
220 (r-1,y) for the channels specified by chans, an array of int with
221 chan_count elements.
222 If chans is NULL then the first chan_count channels are retrieved
224 for each pixel.
225 Returns the number of samples read (which should be (r-l) *
227 chan_count)
228 i_gsampf(im, l, r, y, samp, chans, chan_count)
230 Reads floating point sample values from im for the horizontal line
231 (l, y) to (r-1,y) for the channels specified by chans, an array of
232 int with chan_count elements.
233 If chans is NULL then the first chan_count channels are retrieved
235 for each pixel.
236 Returns the number of samples read (which should be (r-l) *
238 chan_count)
239 i_line(im, x1, y1, x2, y2, val, endp)
241 Draw a line to image using bresenhams linedrawing algorithm
242 im - image to draw to
244 x1 - starting x coordinate
245 y1 - starting x coordinate
246 x2 - starting x coordinate
247 y2 - starting x coordinate
248 val - color to write to image
249 endp - endpoint flag (boolean)
250 i_line_aa(im, x1, x2, y1, y2, color, endp)
252 Antialias draws a line from (x1,y1) to (x2, y2) in color.
253 The point (x2, y2) is drawn only if endp is set.
255 i_plin(im, l, r, y, colors)
257 Sets (r-l) pixels starting from (l,y) using (r-l) values from col‐
258 ors.
259 Returns the number of pixels set.
261 i_plinf(im, l, r, fcolors)
263 Sets (r-l) pixels starting from (l,y) using (r-l) floating point
264 colors from colors.
265 Returns the number of pixels set.
267 i_ppal(im, x, r, y, indexes)
269 Writes palette indexes for the horizontal line (x, y) to (r-1, y)
270 from indexes.
271 Returns the number of indexes written.
273 Always returns 0 for direct color images.
275 i_ppix(im, x, y, color)
277 Sets the pixel at (x,y) to color.
278 Returns 0 if the pixel was drawn, or -1 if not.
280 Does no alpha blending, just copies the channels from the supplied
282 color to the image.
283 i_ppixf(im, x, y, fcolor)
285 Sets the pixel at (x,y) to the floating point color fcolor.
286 Returns 0 if the pixel was drawn, or -1 if not.
288 Does no alpha blending, just copies the channels from the supplied
290 color to the image.
291 Error handling
293 i_clear_error()
295 Clears the error stack.
296 Called by any imager function before doing any other processing.
298 i_push_error(int code, char const *msg)
300 Called by an imager function to push an error message onto the
301 stack.
302 No message is pushed if the stack is full (since this means someone
304 forgot to call i_clear_error(), or that a function that doesn't do
305 error handling is calling function that does.).
306 i_push_errorf(int code, char const *fmt, ...)
308 A version of i_push_error() that does printf() like formating.
309 i_push_errorvf(int code, char const *fmt, va_list ap)
311 Intended for use by higher level functions, takes a varargs pointer
312 and a format to produce the finally pushed error message.
313 Files
315 i_get_image_file_limits(&width, &height, &bytes)
317 Retrieves the file limits set by i_set_image_file_limits().
318 i_int_check_image_file_limits(width, height, channels, sample_size)
320 Checks the size of a file in memory against the configured image
321 file limits.
322 This also range checks the values to those permitted by Imager and
324 checks for overflows in calculating the size.
325 Returns non-zero if the file is within limits.
327 This function is intended to be called by image file read func‐
329 tions.
330 i_set_image_file_limits(width, height, bytes)
332 Set limits on the sizes of images read by Imager.
333 Setting a limit to 0 means that limit is ignored.
335 Negative limits result in failure.
337 Returns non-zero on success.
339 Fills
341 i_fill_destroy(fill)
343 Call to destroy any fill object.
344 i_new_fill_fount(xa, ya, xb, yb, type, repeat, combine, super_sample,
346 ssample_param, count, segs)
347 Creates a new general fill which fills with a fountain fill.
348 i_new_fill_hatch(fg, bg, combine, hatch, cust_hatch, dx, dy)
350 Creates a new hatched fill with the fg color used for the 1 bits in
351 the hatch and bg for the 0 bits. If combine is non-zero alpha val‐
352 ues will be combined.
353 If cust_hatch is non-NULL it should be a pointer to 8 bytes of the
355 hash definition, with the high-bits to the left.
356 If cust_hatch is NULL then one of the standard hatches is used.
358 (dx, dy) are an offset into the hatch which can be used to unalign
360 adjoining areas, or to align the origin of a hatch with the the
361 side of a filled area.
362 i_new_fill_hatchf(fg, bg, combine, hatch, cust_hatch, dx, dy)
364 Creates a new hatched fill with the fg color used for the 1 bits in
365 the hatch and bg for the 0 bits. If combine is non-zero alpha val‐
366 ues will be combined.
367 If cust_hatch is non-NULL it should be a pointer to 8 bytes of the
369 hash definition, with the high-bits to the left.
370 If cust_hatch is NULL then one of the standard hatches is used.
372 (dx, dy) are an offset into the hatch which can be used to unalign
374 adjoining areas, or to align the origin of a hatch with the the
375 side of a filled area.
376 i_new_fill_image(im, matrix, xoff, yoff, combine)
378 Create an image based fill.
379 matrix is an array of 9 doubles representing a transformation
381 matrix.
382 xoff and yoff are the offset into the image to start filling from.
384 i_new_fill_solid(color, combine)
386 Create a solid fill based on an 8-bit color.
387 If combine is non-zero then alpha values will be combined.
389 i_new_fill_solidf(color, combine)
391 Create a solid fill based on a float color.
392 If combine is non-zero then alpha values will be combined.
394 Image
396 i_copy(src)
398 Creates a new image that is a copy of src.
399 Tags are not copied, only the image data.
401 Returns: i_img *
403 i_copyto(dest, src, x1, y1, x2, y2, tx, ty)
405 Copies image data from the area (x1,y1)-[x2,y2] in the source image
406 to a rectangle the same size with it's top-left corner at (tx,ty)
407 in the destination image.
408 If x1 > x2 or y1 > y2 then the corresponding co-ordinates are
410 swapped.
411 i_copyto_trans(im, src, x1, y1, x2, y2, tx, ty, trans)
413 (x1,y1) (x2,y2) specifies the region to copy (in the source coordi‐
414 nates) (tx,ty) specifies the upper left corner for the target
415 image. pass NULL in trans for non transparent i_colors.
416 i_img_info(im, info)
418 Return image information
419 im - Image pointer
421 info - pointer to array to return data
422 info is an array of 4 integers with the following values:
424 info[0] - width
426 info[1] - height
427 info[2] - channels
428 info[3] - channel mask
429 i_rubthru(im, src, tx, ty, src_minx, src_miny, src_maxx, src_maxy )
431 Takes the sub image src[src_minx, src_maxx)[src_miny, src_maxy) and
432 overlays it at (tx,ty) on the image object.
433 The alpha channel of each pixel in src is used to control how much
435 the existing colour in im is replaced, if it is 255 then the colour
436 is completely replaced, if it is 0 then the original colour is left
437 unmodified.
438 Image creation
440 i_img_16_new(x, y, ch)
442 Create a new 16-bit/sample image.
443 Returns the image on success, or NULL on failure.
445 Image creation/destruction
447 i_img_8_new(x, y, ch)
449 Creates a new image object x pixels wide, and y pixels high with ch
450 channels.
451 i_img_destroy(img)
453 Destroy an image object
454 i_img_double_new(int x, int y, int ch)
456 Creates a new double per sample image.
457 i_img_pal_new(x, y, channels, maxpal)
459 Creates a new paletted image of the supplied dimensions.
460 maxpal is the maximum palette size and should normally be 256.
462 Returns a new image or NULL on failure.
464 i_sametype(i_img *im, int xsize, int ysize)
466 Returns an image of the same type (sample size, channels, palet‐
467 ted/direct).
468 For paletted images the palette is copied from the source.
470 i_sametype_chans(i_img *im, int xsize, int ysize, int channels)
472 Returns an image of the same type (sample size).
473 For paletted images the equivalent direct type is returned.
475 Image Implementation
477 i_img_alloc()
479 Allocates a new i_img structure.
480 When implementing a new image type perform the following steps in
482 your image object creation function:
483 1. allocate the image with i_img_alloc().
485 2. initialize any function pointers or other data as needed, you
487 can overwrite the whole block if you need to.
488 3. initialize Imager's internal data by calling i_img_init() on
490 the image object.
491 i_img_init(img)
493 Imager interal initialization of images.
494 Currently this does very little, in the future it may be used to
496 support threads, or color profiles.
497 Image Information
499 i_img_color_channels(im)
501 The number of channels holding color information.
502 i_img_has_alpha(im)
504 Return true if the image has an alpha channel.
505 Image quantization
507 i_quant_makemap(quant, imgs, count)
509 Analyzes the count images in imgs according to the rules in quant
510 to build a color map (optimal or not depending on quant->make_col‐
511 ors).
512 i_quant_translate(quant, img)
514 Quantize the image given the palette in quant.
515 On success returns a pointer to a memory block of img->xsize *
517 img->ysize i_palidx entries.
518 On failure returns NULL.
520 You should call myfree() on the returned block when you're done
522 with it.
523 This function will fail if the supplied palette contains no colors.
525 i_quant_transparent(quant, data, img, trans_index)
527 Dither the alpha channel on img into the palette indexes in data.
528 Pixels to be transparent are replaced with trans_pixel.
529 The method used depends on the tr_* members of quant.
531 Logging
533 i_loog(level, format, ...)
535 This is an internal function called by the mm_log() macro.
536 mm_log((level, format, ...))
538 This is the main entry point to logging. Note that the extra set of
539 parentheses are required due to limitations in C89 macros.
540 This will format a string with the current file and line number to
542 the log file if logging is enabled.
543 Paletted images
545 i_addcolors(im, colors, count)
547 Adds colors to the image's palette.
548 On success returns the index of the lowest color added.
550 On failure returns -1.
552 Always fails for direct color images.
554 i_colorcount(im)
556 Returns the number of colors in the image's palette.
557 Returns -1 for direct images.
559 i_findcolor(im, color, &entry)
561 Searches the images palette for the given color.
562 On success sets *entry to the index of the color, and returns true.
564 On failure returns false.
566 Always fails on direct color images.
568 i_getcolors(im, index, colors, count)
570 Retrieves count colors starting from index in the image's palette.
571 On success stores the colors into colors and returns true.
573 On failure returns false.
575 Always fails for direct color images.
577 Fails if there are less than index+count colors in the image's pal‐
579 ette.
580 i_maxcolors(im)
582 Returns the maximum number of colors the palette can hold for the
583 image.
584 Returns -1 for direct color images.
586 i_setcolors(im, index, colors, count)
588 Sets count colors starting from index in the image's palette.
589 On sucess returns true.
591 On failure returns false.
593 The image must have at least index+count colors in it's palette for
595 this to succeed.
596 Always fails on direct color images.
598 Tags
600 i_tags_delbycode(tags, code)
602 Delete any tags with the given code.
603 Returns the number of tags deleted.
605 i_tags_delbyname(tags, name)
607 Delete any tags with the given name.
608 Returns the number of tags deleted.
610 i_tags_delete(tags, index)
612 Delete a tag by index.
613 Returns true on success.
615 i_tags_destroy(tags)
617 Destroys the given tags structure. Called by i_img_destroy().
618 i_tags_find(tags, name, start, &entry)
620 Searchs for a tag of the given name starting from index start.
621 On success returns true and sets *entry.
623 On failure returns false.
625 i_tags_findn(tags, code, start, &entry)
627 Searchs for a tag of the given code starting from index start.
628 On success returns true and sets *entry.
630 On failure returns false.
632 i_tags_get_color(tags, name, code, &value)
634 Retrieve a tag specified by name or code as color.
635 On success sets the i_color *value to the color and returns true.
637 On failure returns false.
639 i_tags_get_float(tags, name, code, value)
641 Retrieves a tag as a floating point value.
642 If the tag has a string value then that is parsed as a floating
644 point number, otherwise the integer value of the tag is used.
645 On success sets *value and returns true.
647 On failure returns false.
649 i_tags_get_int(tags, name, code, &value)
651 Retrieve a tag specified by name or code as an integer.
652 On success sets the int *value to the integer and returns true.
654 On failure returns false.
656 i_tags_get_string(tags, name, code, value, value_size)
658 Retrieves a tag by name or code as a string.
659 On success copies the string to value for a max of value_size and
661 returns true.
662 On failure returns false.
664 value_size must be at least large enough for a string representa‐
666 tion of an integer.
667 The copied value is always NUL terminated.
669 i_tags_new(i_img_tags *tags)
671 Initialize a tags structure. Should not be used if the tags struc‐
672 ture has been previously used.
673 This should be called tags member of an i_img object on creation
675 (in i_img_*_new() functions).
676 To destroy the contents use i_tags_destroy()
678 i_tags_set(tags, name, data, size)
680 Sets the given tag to the string data
681 i_tags_set_color(tags, name, code, &value)
683 Stores the given color as a tag with the given name and code.
684 i_tags_set_float(tags, name, code, value)
686 Equivalent to i_tags_set_float2(tags, name, code, value, 30).
687 i_tags_set_float2(tags, name, code, value, places)
689 Sets the tag with the given name and code to the given floating
690 point value.
691 Since tags are strings or ints, we convert the value to a string
693 before storage at the precision specified by "places".
694 i_tags_setn(tags, name, idata)
696 Sets the given tag to the integer idata
697 Uncategorized functions
699 i_img_get_height(im)
701 Returns the height in pixels of the image.
702 i_img_get_width(im)
704 Returns the width in pixels of the image.
705 i_img_getchannels(im)
707 Get the number of channels in im.
708 i_img_getmask(im)
710 Get the image channel mask for im.
711 i_img_setmask(im, ch_mask)
713 Set the image channel mask for im to ch_mask.
714
716 The following API functions are undocumented so far, hopefully this
717 will change:
718 · i_color
720 · i_fcolor
722 · i_fill_t
724 · i_lhead
726
728 Tony Cook <tony@imager.perl.org>
729
731 Imager, Imager::ExtUtils, Imager::Inline
732perl v5.8.8 2008-03-28 Imager::APIRef(3)