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 # Blit tools
14 # Data Types
16 i_img *img;
17 i_color black;
18 black.rgba.r = black.rgba.g = black.rgba.b = black.rgba.a = 0;
19 i_fill_t *fill;
20 i_img_dim x, y;
21 printf("left %" i_DF "\n", i_DFc(x));
22 printf("point (" i_DFp ")\n", i_DFcp(x, y));
23 # Drawing
25 i_arc(im, 50, 50, 20, 45, 135, &color);
26 i_arc_cfill(im, 50, 50, 35, 90, 135, fill);
27 i_arc_aa(im, 50, 50, 35, 90, 135, &color);
28 i_arc_aa_cfill(im, 50, 50, 35, 90, 135, fill);
29 i_circle_aa(im, 50, 50, 45, &color);
30 i_box(im, 0, 0, im->xsize-1, im->ysize-1, &color).
31 i_box_filled(im, 0, 0, im->xsize-1, im->ysize-1, &color);
32 i_box_cfill(im, 0, 0, im->xsize-1, im->ysize-1, fill);
33 i_flood_fill(im, 50, 50, &color);
34 i_flood_cfill(im, 50, 50, fill);
35 i_flood_fill_border(im, 50, 50, &color, &border);
36 i_flood_cfill_border(im, 50, 50, fill, border);
37 # Error handling
39 i_clear_error();
40 i_push_error(0, "Yep, it's broken");
41 i_push_error(errno, "Error writing");
42 i_push_errorf(errno, "Cannot open file %s: %d", filename, errno);
43 # Files
45 i_set_image_file_limits(500, 500, 1000000);
46 i_get_image_file_limits(&width, &height, &bytes)
47 i_i_int_check_image_file_limits(width, height, channels, sizeof(i_sample_t))
48 # Fills
50 i_fill_t *fill = i_new_fill_solidf(&fcolor, combine);
51 i_fill_t *fill = i_new_fill_solid(&color, combine);
52 i_fill_t *fill = i_new_fill_hatch(&fg_color, &bg_color, combine, hatch, custom_hatch, dx, dy);
53 i_fill_t *fill = i_new_fill_hatchf(&fg_fcolor, &bg_fcolor, combine, hatch, custom_hatch, dx, dy);
54 i_fill_t *fill = i_new_fill_image(src_img, matrix, x_offset, y_offset, combine);
55 fill = i_new_fill_fount(0, 0, 100, 100, i_ft_linear, i_ft_linear,
56 i_fr_triangle, 0, i_fts_grid, 9, 1, segs);
57 i_fill_destroy(fill);
58 # Image
60 # Image creation/destruction
62 i_img *img = i_img_8_new(width, height, channels);
63 i_img *img = i_sametype(src, width, height);
64 i_img *img = i_sametype_chans(src, width, height, channels);
65 i_img *img = i_img_pal_new(width, height, channels, max_palette_size)
66 i_img *img = i_img_double_new(width, height, channels);
67 i_img *img = i_img_16_new(width, height, channels);
68 i_img_destroy(img)
69 # Image Implementation
71 # Image Information
73 // only channel 0 writeable
74 i_img_setmask(img, 0x01);
75 int mask = i_img_getmask(img);
76 int channels = i_img_getchannels(img);
77 i_img_dim width = i_img_get_width(im);
78 i_img_dim height = i_img_get_height(im);
79 # Image quantization
81 # Logging
83 # Paletted images
85 # Tags
87 i_tags_set(&img->tags, "i_comment", -1);
88 i_tags_setn(&img->tags, "i_xres", 204);
89 i_tags_setn(&img->tags, "i_yres", 196);
90
92 Blit tools
93 i_render_color(r, x, y, width, source, color)
94 Render the given color with the coverage specified by "source[0]"
95 to "source[width-1]".
96 Renders in normal combine mode.
98 i_render_delete(r)
100 Release an "i_render" object.
101 i_render_fill(r, x, y, width, source, fill)
103 Render the given fill with the coverage in "source[0]" through
104 "source[width-1]".
105 i_render_line(r, x, y, width, source, fill)
107 Render the given fill with the coverage in "source[0]" through
108 "source[width-1]".
109 i_render_linef(r, x, y, width, source, fill)
111 Render the given fill with the coverage in "source[0]" through
112 "source[width-1]".
113 i_render_new(im, width)
115 Allocate a new "i_render" object and initialize it.
116 Data Types
118 i_img
119 i_img *img;
120 This is Imager's image type.
122 It contains the following members:
124 · "channels" - the number of channels in the image
126 · "xsize", "ysize" - the width and height of the image in pixels
128 · "bytes" - the number of bytes used to store the image data.
130 Undefined where virtual is non-zero.
131 · "ch_mask" - a mask of writable channels. eg. if this is 6 then
133 only channels 1 and 2 are writable. There may be bits set for
134 which there are no channels in the image.
135 · "bits" - the number of bits stored per sample. Should be one
137 of i_8_bits, i_16_bits, i_double_bits.
138 · "type" - either i_direct_type for direct color images, or
140 i_palette_type for paletted images.
141 · "virtual" - if zero then this image is-self contained. If non-
143 zero then this image could be an interface to some other
144 implementation.
145 · "idata" - the image data. This should not be directly
147 accessed. A new image implementation can use this to store its
148 image data. i_img_destroy() will myfree() this pointer if it's
149 non-null.
150 · "tags" - a structure storing the image's tags. This should
152 only be accessed via the i_tags_*() functions.
153 · "ext_data" - a pointer for use internal to an image
155 implementation. This should be freed by the image's destroy
156 handler.
157 · "im_data" - data internal to Imager. This is initialized by
159 i_img_init().
160 · i_f_ppix, i_f_ppixf, i_f_plin, i_f_plinf, i_f_gpix, i_f_gpixf,
162 i_f_glin, i_f_glinf, i_f_gsamp, i_f_gampf - implementations for
163 each of the required image functions. An image implementation
164 should initialize these between calling i_img_alloc() and
165 i_img_init().
166 · i_f_gpal, i_f_ppal, i_f_addcolors, i_f_getcolors,
168 i_f_colorcount, i_f_maxcolors, i_f_findcolor, i_f_setcolors -
169 implementations for each paletted image function.
170 · i_f_destroy - custom image destruction function. This should
172 be used to release memory if necessary.
173 · i_f_gsamp_bits - implements i_gsamp_bits() for this image.
175 · i_f_psamp_bits - implements i_psamp_bits() for this image.
177 i_color
179 i_color black;
180 black.rgba.r = black.rgba.g = black.rgba.b = black.rgba.a = 0;
181 Type for 8-bit/sample color.
183 Samples as per;
185 i_color c;
187 i_color is a union of:
189 · gray - contains a single element gray_color, eg.
191 "c.gray.gray_color"
192 · "rgb" - contains three elements "r", "g", "b", eg. "c.rgb.r"
194 · "rgba" - contains four elements "r", "g", "b", "a", eg.
196 "c.rgba.a"
197 · "cmyk" - contains four elements "c", "m", "y", "k", eg.
199 "c.cmyk.y". Note that Imager never uses CMYK colors except
200 when reading/writing files.
201 · channels - an array of four channels, eg "c.channels[2]".
203 i_fcolor
205 This is the double/sample color type.
206 Its layout exactly corresponds to i_color.
208 i_fill_t
210 i_fill_t *fill;
211 This is the "abstract" base type for Imager's fill types.
213 Unless you're implementing a new fill type you'll typically treat
215 this as an opaque type.
216 i_img_dim
218 i_img_dim x, y;
219 A signed integer type that represents an image dimension or
221 ordinate.
222 May be larger than int on some platforms.
224 i_DF
226 printf("left %" i_DF "\n", i_DFc(x));
227 This is a constant string that can be used with functions like
229 printf() to format i_img_dim values after they're been cast with
230 i_DFc().
231 Does not include the leading "%".
233 i_DFc
235 Cast an "i_img_dim" value to a type for use with the i_DF format
236 string.
237 i_DFcp
239 Casts two "i_img_dim" values for use with the i_DF (or i_DFp)
240 format.
241 i_DFp
243 printf("point (" i_DFp ")\n", i_DFcp(x, y));
244 Format a pair of "i_img_dim" values. This format string does
246 include the leading "%".
247 Drawing
249 i_arc(im, x, y, rad, d1, d2, color)
250 i_arc(im, 50, 50, 20, 45, 135, &color);
251 Fills an arc centered at (x,y) with radius rad covering the range
253 of angles in degrees from d1 to d2, with the color.
254 i_arc_aa(im, x, y, rad, d1, d2, color)
256 i_arc_aa(im, 50, 50, 35, 90, 135, &color);
257 Anti-alias fills an arc centered at (x,y) with radius rad covering
259 the range of angles in degrees from d1 to d2, with the color.
260 i_arc_aa_cfill(im, x, y, rad, d1, d2, fill)
262 i_arc_aa_cfill(im, 50, 50, 35, 90, 135, fill);
263 Anti-alias fills an arc centered at (x,y) with radius rad covering
265 the range of angles in degrees from d1 to d2, with the fill object.
266 i_arc_cfill(im, x, y, rad, d1, d2, fill)
268 i_arc_cfill(im, 50, 50, 35, 90, 135, fill);
269 Fills an arc centered at (x,y) with radius rad covering the range
271 of angles in degrees from d1 to d2, with the fill object.
272 i_box(im, x1, y1, x2, y2, color)
274 i_box(im, 0, 0, im->xsize-1, im->ysize-1, &color).
275 Outlines the box from (x1,y1) to (x2,y2) inclusive with color.
277 i_box_cfill(im, x1, y1, x2, y2, fill)
279 i_box_cfill(im, 0, 0, im->xsize-1, im->ysize-1, fill);
280 Fills the box from (x1,y1) to (x2,y2) inclusive with fill.
282 i_box_filled(im, x1, y1, x2, y2, color)
284 i_box_filled(im, 0, 0, im->xsize-1, im->ysize-1, &color);
285 Fills the box from (x1,y1) to (x2,y2) inclusive with color.
287 i_circle_aa(im, x, y, rad, color)
289 i_circle_aa(im, 50, 50, 45, &color);
290 Anti-alias fills a circle centered at (x,y) for radius rad with
292 color.
293 i_flood_cfill("im", "seedx", "seedy", "fill")
295 i_flood_cfill(im, 50, 50, fill);
296 Flood fills the 4-connected region starting from the point
298 ("seedx", "seedy") with "fill".
299 Returns false if ("seedx", "seedy") are outside the image.
301 i_flood_cfill_border("im", "seedx", "seedy", "fill", "border")
303 i_flood_cfill_border(im, 50, 50, fill, border);
304 Flood fills the 4-connected region starting from the point
306 ("seedx", "seedy") with "fill", the fill stops when it reaches
307 pixels of color "border".
308 Returns false if ("seedx", "seedy") are outside the image.
310 i_flood_fill("im", "seedx", "seedy", "color")
312 i_flood_fill(im, 50, 50, &color);
313 Flood fills the 4-connected region starting from the point
315 ("seedx", "seedy") with color.
316 Returns false if ("seedx", "seedy") are outside the image.
318 i_flood_fill_border("im", "seedx", "seedy", "color", "border")
320 i_flood_fill_border(im, 50, 50, &color, &border);
321 Flood fills the 4-connected region starting from the point
323 ("seedx", "seedy") with "color", fill stops when the fill reaches a
324 pixels with color "border".
325 Returns false if ("seedx", "seedy") are outside the image.
327 i_glin(im, l, r, y, colors)
329 Retrieves (r-l) pixels starting from (l,y) into colors.
330 Returns the number of pixels retrieved.
332 i_glinf(im, l, r, y, colors)
334 Retrieves (r-l) pixels starting from (l,y) into colors as floating
335 point colors.
336 Returns the number of pixels retrieved.
338 i_gpal(im, left, right, y, indexes)
340 Reads palette indexes for the horizontal line (left, y) to
341 (right-1, y) into "indexes".
342 Returns the number of indexes read.
344 Always returns 0 for direct color images.
346 i_gpix(im, "x", "y", "color")
348 Retrieves the "color" of the pixel (x,y).
349 Returns 0 if the pixel was retrieved, or -1 if not.
351 i_gpixf(im, "x", "y", "fcolor")
353 Retrieves the color of the pixel (x,y) as a floating point color
354 into "fcolor".
355 Returns 0 if the pixel was retrieved, or -1 if not.
357 i_gsamp(im, left, right, y, samples, channels, channel_count)
359 Reads sample values from "im" for the horizontal line (left, y) to
360 (right-1,y) for the channels specified by "channels", an array of
361 int with "channel_count" elements.
362 If channels is NULL then the first channels_count channels are
364 retrieved for each pixel.
365 Returns the number of samples read (which should be (right-left) *
367 channel_count)
368 i_gsamp_bg(im, l, r, y, samples, out_channels, background)
370 Like "i_gsampf()" but applies the source image color over a
371 supplied background color.
372 This is intended for output to image formats that don't support
374 alpha channels.
375 i_gsampf(im, left, right, y, samples, channels, channel_count)
377 Reads floating point sample values from "im" for the horizontal
378 line (left, y) to (right-1,y) for the channels specified by
379 "channels", an array of int with channel_count elements.
380 If "channels" is NULL then the first "channel_count" channels are
382 retrieved for each pixel.
383 Returns the number of samples read (which should be
385 ("right"-"left") * "channel_count")
386 i_gsampf_bg(im, l, r, y, samples, out_channels, background)
388 Like "i_gsampf()" but applies the source image color over a
389 supplied background color.
390 This is intended for output to image formats that don't support
392 alpha channels.
393 i_line("im", "x1", "y1", "x2", "y2", "color", "endp")
395 Draw a line to image using Bresenham's line drawing algorithm
396 im - image to draw to
398 x1 - starting x coordinate
399 y1 - starting x coordinate
400 x2 - starting x coordinate
401 y2 - starting x coordinate
402 color - color to write to image
403 endp - endpoint flag (boolean)
404 i_line_aa("im", "x1", "x2", "y1", "y2", "color", "endp")
406 Anti-alias draws a line from (x1,y1) to (x2, y2) in color.
407 The point (x2, y2) is drawn only if "endp" is set.
409 i_plin(im, l, r, y, colors)
411 Sets (r-l) pixels starting from (l,y) using (r-l) values from
412 colors.
413 Returns the number of pixels set.
415 i_plinf(im, "left", "right", "fcolors")
417 Sets (right-left) pixels starting from (left,y) using (right-left)
418 floating point colors from "fcolors".
419 Returns the number of pixels set.
421 i_ppal(im, left, right, y, indexes)
423 Writes palette indexes for the horizontal line (left, y) to
424 (right-1, y) from "indexes".
425 Returns the number of indexes written.
427 Always returns 0 for direct color images.
429 i_ppix(im, x, y, color)
431 Sets the pixel at (x,y) to color.
432 Returns 0 if the pixel was drawn, or -1 if not.
434 Does no alpha blending, just copies the channels from the supplied
436 color to the image.
437 i_ppixf(im, "x", "y", "fcolor")
439 Sets the pixel at ("x","y") to the floating point color "fcolor".
440 Returns 0 if the pixel was drawn, or -1 if not.
442 Does no alpha blending, just copies the channels from the supplied
444 color to the image.
445 Error handling
447 i_clear_error()
448 i_clear_error();
449 Clears the error stack.
451 Called by any Imager function before doing any other processing.
453 i_push_error(int code, char const *msg)
455 i_push_error(0, "Yep, it's broken");
456 i_push_error(errno, "Error writing");
457 Called by an Imager function to push an error message onto the
459 stack.
460 No message is pushed if the stack is full (since this means someone
462 forgot to call i_clear_error(), or that a function that doesn't do
463 error handling is calling function that does.).
464 i_push_errorf(int code, char const *fmt, ...)
466 i_push_errorf(errno, "Cannot open file %s: %d", filename, errno);
467 A version of i_push_error() that does printf() like formatting.
469 Does not support perl specific format codes.
471 i_push_errorvf(int "code", char const *"fmt", va_list "ap")
473 Intended for use by higher level functions, takes a varargs pointer
474 and a format to produce the finally pushed error message.
475 Does not support perl specific format codes.
477 Files
479 i_get_file_background(im, &bg)
480 Retrieve the file write background color tag from the image.
481 If not present, returns black.
483 i_get_file_backgroundf(im, &bg)
485 Retrieve the file write background color tag from the image as a
486 floating point color.
487 Implemented in terms of i_get_file_background().
489 If not present, returns black.
491 i_get_image_file_limits(&width, &height, &bytes)
493 i_get_image_file_limits(&width, &height, &bytes)
494 Retrieves the file limits set by i_set_image_file_limits().
496 · i_img_dim *width, *height - the maximum width and height of the
498 image.
499 · size_t *bytes - size in memory of the image in bytes.
501 i_int_check_image_file_limits(width, height, channels, sample_size)
503 i_i_int_check_image_file_limits(width, height, channels, sizeof(i_sample_t))
504 Checks the size of a file in memory against the configured image
506 file limits.
507 This also range checks the values to those permitted by Imager and
509 checks for overflows in calculating the size.
510 Returns non-zero if the file is within limits.
512 This function is intended to be called by image file read
514 functions.
515 i_set_image_file_limits(width, height, bytes)
517 i_set_image_file_limits(500, 500, 1000000);
518 Set limits on the sizes of images read by Imager.
520 Setting a limit to 0 means that limit is ignored.
522 Negative limits result in failure.
524 Parameters:
526 · i_img_dim width, height - maximum width and height.
528 · size_t bytes - maximum size in memory in bytes
530 Returns non-zero on success.
532 Fills
534 i_new_fill_fount("xa", "ya", "xb", "yb", "type", "repeat", "combine",
535 "super_sample", "ssample_param", "count", "segs")
536 fill = i_new_fill_fount(0, 0, 100, 100, i_ft_linear, i_ft_linear,
537 i_fr_triangle, 0, i_fts_grid, 9, 1, segs);
538 Creates a new general fill which fills with a fountain fill.
540 i_new_fill_hatch("fg", "bg", "combine", "hatch", "cust_hatch", "dx",
542 "dy")
543 i_fill_t *fill = i_new_fill_hatch(&fg_color, &bg_color, combine, hatch, custom_hatch, dx, dy);
544 Creates a new hatched fill with the "fg" color used for the 1 bits
546 in the hatch and "bg" for the 0 bits. If "combine" is non-zero
547 alpha values will be combined.
548 If "cust_hatch" is non-NULL it should be a pointer to 8 bytes of
550 the hash definition, with the high-bits to the left.
551 If "cust_hatch" is NULL then one of the standard hatches is used.
553 ("dx", "dy") are an offset into the hatch which can be used to
555 hatch adjoining areas out of alignment, or to align the origin of a
556 hatch with the the side of a filled area.
557 i_new_fill_hatchf("fg", "bg", "combine", "hatch", "cust_hatch", "dx",
559 "dy")
560 i_fill_t *fill = i_new_fill_hatchf(&fg_fcolor, &bg_fcolor, combine, hatch, custom_hatch, dx, dy);
561 Creates a new hatched fill with the "fg" color used for the 1 bits
563 in the hatch and "bg" for the 0 bits. If "combine" is non-zero
564 alpha values will be combined.
565 If "cust_hatch" is non-NULL it should be a pointer to 8 bytes of
567 the hash definition, with the high-bits to the left.
568 If "cust_hatch" is NULL then one of the standard hatches is used.
570 ("dx", "dy") are an offset into the hatch which can be used to
572 hatch adjoining areas out of alignment, or to align the origin of a
573 hatch with the the side of a filled area.
574 i_new_fill_image("im", "matrix", "xoff", "yoff", "combine")
576 i_fill_t *fill = i_new_fill_image(src_img, matrix, x_offset, y_offset, combine);
577 Create an image based fill.
579 matrix is an array of 9 doubles representing a transformation
581 matrix.
582 "xoff" and "yoff" are the offset into the image to start filling
584 from.
585 i_new_fill_solid(color, combine)
587 i_fill_t *fill = i_new_fill_solid(&color, combine);
588 Create a solid fill based on an 8-bit color.
590 If combine is non-zero then alpha values will be combined.
592 i_new_fill_solidf(color, combine)
594 i_fill_t *fill = i_new_fill_solidf(&fcolor, combine);
595 Create a solid fill based on a float color.
597 If combine is non-zero then alpha values will be combined.
599 i_fill_destroy(fill)
601 i_fill_destroy(fill);
602 Call to destroy any fill object.
604 Image
606 i_copy(source)
607 Creates a new image that is a copy of the image "source".
608 Tags are not copied, only the image data.
610 Returns: i_img *
612 i_copyto("dest", "src", "x1", "y1", "x2", "y2", "tx", "ty")
614 Copies image data from the area ("x1","y1")-["x2","y2"] in the
615 source image to a rectangle the same size with it's top-left corner
616 at ("tx","ty") in the destination image.
617 If "x1" > "x2" or "y1" > "y2" then the corresponding co-ordinates
619 are swapped.
620 i_copyto_trans("im", "src", "x1", "y1", "x2", "y2", "tx", "ty",
622 "trans")
623 ("x1","y1") ("x2","y2") specifies the region to copy (in the source
624 coordinates) ("tx","ty") specifies the upper left corner for the
625 target image. pass NULL in "trans" for non transparent i_colors.
626 i_img_info(im, info)
628 Return image information
629 im - Image pointer
631 info - pointer to array to return data
632 info is an array of 4 integers with the following values:
634 info[0] - width
636 info[1] - height
637 info[2] - channels
638 info[3] - channel mask
639 i_rubthru("im", "src", "tx", "ty", "src_minx", "src_miny", "src_maxx",
641 "src_maxy")
642 Takes the sub image "src"["src_minx", "src_maxx")["src_miny",
643 "src_maxy")> and overlays it at ("tx","ty") on the image object.
644 The alpha channel of each pixel in "src" is used to control how
646 much the existing color in "im" is replaced, if it is 255 then the
647 color is completely replaced, if it is 0 then the original color is
648 left unmodified.
649 Image creation/destruction
651 i_img_16_new(x, y, ch)
652 i_img *img = i_img_16_new(width, height, channels);
653 Create a new 16-bit/sample image.
655 Returns the image on success, or NULL on failure.
657 i_img_8_new(x, y, ch)
659 i_img *img = i_img_8_new(width, height, channels);
660 Creates a new image object x pixels wide, and y pixels high with ch
662 channels.
663 i_img_double_new(i_img_dim x, i_img_dim y, int ch)
665 i_img *img = i_img_double_new(width, height, channels);
666 Creates a new double per sample image.
668 i_img_pal_new("x", "y", "channels", "maxpal")
670 i_img *img = i_img_pal_new(width, height, channels, max_palette_size)
671 Creates a new paletted image of the supplied dimensions.
673 "maxpal" is the maximum palette size and should normally be 256.
675 Returns a new image or NULL on failure.
677 i_sametype("im", "xsize", "ysize")
679 i_img *img = i_sametype(src, width, height);
680 Returns an image of the same type (sample size, channels,
682 paletted/direct).
683 For paletted images the palette is copied from the source.
685 i_sametype_chans("im", "xsize", "ysize", "channels")
687 i_img *img = i_sametype_chans(src, width, height, channels);
688 Returns an image of the same type (sample size).
690 For paletted images the equivalent direct type is returned.
692 i_img_destroy("img")
694 i_img_destroy(img)
695 Destroy an image object
697 Image Implementation
699 i_img_alloc()
700 Allocates a new i_img structure.
701 When implementing a new image type perform the following steps in
703 your image object creation function:
704 1. allocate the image with i_img_alloc().
706 2. initialize any function pointers or other data as needed, you
708 can overwrite the whole block if you need to.
709 3. initialize Imager's internal data by calling i_img_init() on
711 the image object.
712 i_img_init("img")
714 Imager internal initialization of images.
715 Currently this does very little, in the future it may be used to
717 support threads, or color profiles.
718 Image Information
720 i_img_color_channels("im")
721 The number of channels holding color information.
722 i_img_get_height("im")
724 i_img_dim height = i_img_get_height(im);
725 Returns the height in pixels of the image.
727 i_img_get_width("im")
729 i_img_dim width = i_img_get_width(im);
730 Returns the width in pixels of the image.
732 i_img_getchannels("im")
734 int channels = i_img_getchannels(img);
735 Get the number of channels in "im".
737 i_img_getmask("im")
739 int mask = i_img_getmask(img);
740 Get the image channel mask for "im".
742 i_img_has_alpha("im")
744 Return true if the image has an alpha channel.
745 i_img_is_monochrome(img, &zero_is_white)
747 Tests an image to check it meets our monochrome tests.
748 The idea is that a file writer can use this to test where it should
750 write the image in whatever bi-level format it uses, eg. "pbm" for
751 "pnm".
752 For performance of encoders we require monochrome images:
754 · be paletted
756 · have a palette of two colors, containing only "(0,0,0)" and
758 "(255,255,255)" in either order.
759 "zero_is_white" is set to non-zero if the first palette entry is
761 white.
762 i_img_setmask("im", "ch_mask")
764 // only channel 0 writeable
765 i_img_setmask(img, 0x01);
766 Set the image channel mask for "im" to "ch_mask".
768 The image channel mask gives some control over which channels can
770 be written to in the image.
771 Image quantization
773 i_quant_makemap("quant", "imgs", "count")
774 Analyzes the "count" images in "imgs" according to the rules in
775 "quant" to build a color map (optimal or not depending on
776 "quant->make_colors").
777 i_quant_translate("quant", "img")
779 Quantize the image given the palette in "quant".
780 On success returns a pointer to a memory block of "img->xsize *
782 img->ysize" "i_palidx" entries.
783 On failure returns NULL.
785 You should call myfree() on the returned block when you're done
787 with it.
788 This function will fail if the supplied palette contains no colors.
790 i_quant_transparent("quant", "data", "img", "trans_index")
792 Dither the alpha channel on "img" into the palette indexes in
793 "data". Pixels to be transparent are replaced with "trans_pixel".
794 The method used depends on the tr_* members of "quant".
796 Logging
798 i_lhead(file, line)
799 This is an internal function called by the mm_log() macro.
800 i_loog(level, format, ...)
802 This is an internal function called by the mm_log() macro.
803 mm_log((level, format, ...))
805 This is the main entry point to logging. Note that the extra set of
806 parentheses are required due to limitations in C89 macros.
807 This will format a string with the current file and line number to
809 the log file if logging is enabled.
810 Paletted images
812 i_addcolors(im, colors, count)
813 Adds colors to the image's palette.
814 On success returns the index of the lowest color added.
816 On failure returns -1.
818 Always fails for direct color images.
820 i_colorcount(im)
822 Returns the number of colors in the image's palette.
823 Returns -1 for direct images.
825 i_findcolor(im, color, &entry)
827 Searches the images palette for the given color.
828 On success sets *entry to the index of the color, and returns true.
830 On failure returns false.
832 Always fails on direct color images.
834 i_getcolors(im, index, colors, count)
836 Retrieves count colors starting from index in the image's palette.
837 On success stores the colors into colors and returns true.
839 On failure returns false.
841 Always fails for direct color images.
843 Fails if there are less than index+count colors in the image's
845 palette.
846 i_maxcolors(im)
848 Returns the maximum number of colors the palette can hold for the
849 image.
850 Returns -1 for direct color images.
852 i_setcolors(im, index, colors, count)
854 Sets count colors starting from index in the image's palette.
855 On success returns true.
857 On failure returns false.
859 The image must have at least index+count colors in it's palette for
861 this to succeed.
862 Always fails on direct color images.
864 Tags
866 i_tags_delbycode(tags, code)
867 Delete any tags with the given code.
868 Returns the number of tags deleted.
870 i_tags_delbyname(tags, name)
872 Delete any tags with the given name.
873 Returns the number of tags deleted.
875 i_tags_delete(tags, index)
877 Delete a tag by index.
878 Returns true on success.
880 i_tags_destroy(tags)
882 Destroys the given tags structure. Called by i_img_destroy().
883 i_tags_find(tags, name, start, &entry)
885 Searches for a tag of the given name starting from index start.
886 On success returns true and sets *entry.
888 On failure returns false.
890 i_tags_findn(tags, code, start, &entry)
892 Searches for a tag of the given code starting from index start.
893 On success returns true and sets *entry.
895 On failure returns false.
897 i_tags_get_color(tags, name, code, &value)
899 Retrieve a tag specified by name or code as color.
900 On success sets the i_color *value to the color and returns true.
902 On failure returns false.
904 i_tags_get_float(tags, name, code, value)
906 Retrieves a tag as a floating point value.
907 If the tag has a string value then that is parsed as a floating
909 point number, otherwise the integer value of the tag is used.
910 On success sets *value and returns true.
912 On failure returns false.
914 i_tags_get_int(tags, name, code, &value)
916 Retrieve a tag specified by name or code as an integer.
917 On success sets the int *value to the integer and returns true.
919 On failure returns false.
921 i_tags_get_string(tags, name, code, value, value_size)
923 Retrieves a tag by name or code as a string.
924 On success copies the string to value for a max of value_size and
926 returns true.
927 On failure returns false.
929 value_size must be at least large enough for a string
931 representation of an integer.
932 The copied value is always "NUL" terminated.
934 i_tags_new(i_img_tags *tags)
936 Initialize a tags structure. Should not be used if the tags
937 structure has been previously used.
938 This should be called tags member of an i_img object on creation
940 (in i_img_*_new() functions).
941 To destroy the contents use i_tags_destroy()
943 i_tags_set(tags, name, data, size)
945 i_tags_set(&img->tags, "i_comment", -1);
946 Sets the given tag to the string data
948 If size is -1 then the strlen(data) bytes are stored.
950 Even on failure, if an existing tag name exists, it will be
952 removed.
953 i_tags_set_color(tags, name, code, &value)
955 Stores the given color as a tag with the given name and code.
956 i_tags_set_float(tags, name, code, value)
958 Equivalent to i_tags_set_float2(tags, name, code, value, 30).
959 i_tags_set_float2(tags, name, code, value, places)
961 Sets the tag with the given name and code to the given floating
962 point value.
963 Since tags are strings or ints, we convert the value to a string
965 before storage at the precision specified by "places".
966 i_tags_setn("tags", "name", "idata")
968 i_tags_setn(&img->tags, "i_xres", 204);
969 i_tags_setn(&img->tags, "i_yres", 196);
970 Sets the given tag to the integer "idata"
972 Even on failure, if an existing tag "name" exists, it will be
974 removed.
975 Uncategorized functions
977 i_utf8_advance(char **p, size_t *len)
978 Retrieve a "UTF-8" character from the stream.
979 Modifies *p and *len to indicate the consumed characters.
981 This doesn't support the extended "UTF-8" encoding used by later
983 versions of Perl. Since this is typically used to implement text
984 output by font drivers, the strings supplied shouldn't have such
985 out of range characters.
986 This doesn't check that the "UTF-8" character is using the shortest
988 possible representation.
989 Returns ~0UL on failure.
991
993 Tony Cook <tonyc@cpan.org>
994
996 Imager, Imager::ExtUtils, Imager::Inline
997perl v5.12.3 2011-09-06 Imager::APIRef(3)