fill out documentation
[imager.git] / lib / Imager / APIRef.pod
1 Do not edit this file, it is generated automatically by apidocs.perl
2 from Imager's source files.
3
4 Each function description has a comment listing the source file where
5 you can find the documentation.
6
7 =head1 NAME
8
9 Imager::APIRef - Imager's C API - reference.
10
11 =head1 SYNOPSIS
12
13   i_color color;
14   color.rgba.r = 255; color.rgba.g = 0; color.rgba.b = 255;
15
16
17   # Blit tools
18
19   # Data Types
20   i_img *img;
21   i_color black;
22   black.rgba.r = black.rgba.g = black.rgba.b = black.rgba.a = 0;
23   i_fill_t *fill;
24   i_img_dim x, y;
25   printf("left %" i_DF "\n", i_DFc(x));
26   printf("point (" i_DFp ")\n", i_DFcp(x, y));
27
28   # Drawing
29   i_arc(im, 50, 50, 20, 45, 135, &color);
30   i_arc_cfill(im, 50, 50, 35, 90, 135, fill);
31   i_arc_aa(im, 50, 50, 35, 90, 135, &color);
32   i_arc_aa_cfill(im, 50, 50, 35, 90, 135, fill);
33   i_circle_aa(im, 50, 50, 45, &color);
34   i_box(im, 0, 0, im->xsize-1, im->ysize-1, &color).
35   i_box_filled(im, 0, 0, im->xsize-1, im->ysize-1, &color);
36   i_box_cfill(im, 0, 0, im->xsize-1, im->ysize-1, fill);
37   i_flood_fill(im, 50, 50, &color);
38   i_flood_cfill(im, 50, 50, fill);
39   i_flood_fill_border(im, 50, 50, &color, &border);
40   i_flood_cfill_border(im, 50, 50, fill, border);
41
42   # Error handling
43   im_clear_error(aIMCTX);
44   i_clear_error();
45   i_push_error(0, "Yep, it's broken");
46   i_push_error(errno, "Error writing");
47   im_push_error(aIMCTX, 0, "Something is wrong");
48   va_args args;
49   va_start(args, lastarg);
50   im_push_errorvf(ctx, code, format, args);
51   i_push_errorf(errno, "Cannot open file %s: %d", filename, errno);
52   im_push_errorf(aIMCTX, errno, "Cannot open file %s: %d", filename, errno);
53
54   # Files
55   im_set_image_file_limits(aIMCTX, 500, 500, 1000000);
56   i_set_image_file_limits(500, 500, 1000000);
57   im_get_image_file_limits(aIMCTX, &width, &height, &bytes)
58   i_get_image_file_limits(&width, &height, &bytes)
59   im_int_check_image_file_limits(aIMCTX, width, height, channels, sizeof(i_sample_t))
60   i_int_check_image_file_limits(width, height, channels, sizeof(i_sample_t))
61
62   # Fills
63   i_fill_t *fill = i_new_fill_solidf(&fcolor, combine);
64   i_fill_t *fill = i_new_fill_solid(&color, combine);
65   i_fill_t *fill = i_new_fill_hatch(&fg_color, &bg_color, combine, hatch, custom_hatch, dx, dy);
66   i_fill_t *fill = i_new_fill_hatchf(&fg_fcolor, &bg_fcolor, combine, hatch, custom_hatch, dx, dy);
67   i_fill_t *fill = i_new_fill_image(src_img, matrix, x_offset, y_offset, combine);
68   fill = i_new_fill_fount(0, 0, 100, 100, i_ft_linear, i_ft_linear, 
69                           i_fr_triangle, 0, i_fts_grid, 9, 1, segs);
70   i_fill_destroy(fill);
71
72   # I/O Layers
73   ssize_t count = i_io_peekn(ig, buffer, sizeof(buffer));
74   ssize_t result = i_io_write(io, buffer, size)
75   char buffer[BUFSIZ]
76   ssize_t len = i_io_gets(buffer, sizeof(buffer), '\n');
77   io_glue_destroy(ig);
78
79   # Image
80
81   # Image creation/destruction
82   i_img *img = i_sametype(src, width, height);
83   i_img *img = i_sametype_chans(src, width, height, channels);
84   i_img *img = im_img_16_new(aIMCTX, width, height, channels);
85   i_img *img = i_img_16_new(width, height, channels);
86   i_img *img = im_img_8_new(aIMCTX, width, height, channels);
87   i_img *img = i_img_8_new(width, height, channels);
88   i_img *img = im_img_double_new(aIMCTX, width, height, channels);
89   i_img *img = i_img_double_new(width, height, channels);
90   i_img *img = im_img_pal_new(aIMCTX, width, height, channels, max_palette_size)
91   i_img *img = i_img_pal_new(width, height, channels, max_palette_size)
92   i_img_destroy(img)
93
94   # Image Implementation
95   i_img *im = im_img_alloc(aIMCTX);
96   i_img *im = i_img_alloc();
97   im_img_init(aIMCTX, im);
98   i_img_init(im);
99
100   # Image Information
101   // only channel 0 writable 
102   i_img_setmask(img, 0x01);
103   int mask = i_img_getmask(img);
104   int channels = i_img_getchannels(img);
105   i_img_dim width = i_img_get_width(im);
106   i_img_dim height = i_img_get_height(im);
107
108   # Image quantization
109
110   # Logging
111
112   # Paletted images
113
114   # Tags
115   i_tags_set(&img->tags, "i_comment", -1);
116   i_tags_setn(&img->tags, "i_xres", 204);
117   i_tags_setn(&img->tags, "i_yres", 196);
118
119 =head1 DESCRIPTION
120
121 =head2 Blit tools
122
123 =over
124
125 =item i_render_color(r, x, y, width, source, color)
126
127 Render the given color with the coverage specified by C<source[0]> to
128 C<source[width-1]>.
129
130 Renders in normal combine mode.
131
132
133 =for comment
134 From: File render.im
135
136 =item i_render_delete(r)
137
138 Release an C<i_render> object.
139
140
141 =for comment
142 From: File render.im
143
144 =item i_render_fill(r, x, y, width, source, fill)
145
146 Render the given fill with the coverage in C<source[0]> through
147 C<source[width-1]>.
148
149
150 =for comment
151 From: File render.im
152
153 =item i_render_line(r, x, y, width, source, fill)
154
155 Render the given fill with the coverage in C<source[0]> through
156 C<source[width-1]>.
157
158
159 =for comment
160 From: File render.im
161
162 =item i_render_linef(r, x, y, width, source, fill)
163
164 Render the given fill with the coverage in C<source[0]> through
165 C<source[width-1]>.
166
167
168 =for comment
169 From: File render.im
170
171 =item i_render_new(im, width)
172
173 Allocate a new C<i_render> object and initialize it.
174
175
176 =for comment
177 From: File render.im
178
179
180 =back
181
182 =head2 Data Types
183
184 =over
185
186 =item i_img
187
188   i_img *img;
189
190 This is Imager's image type.
191
192 It contains the following members:
193
194 =over
195
196 =item *
197
198 C<channels> - the number of channels in the image
199
200 =item *
201
202 C<xsize>, C<ysize> - the width and height of the image in pixels
203
204 =item *
205
206 C<bytes> - the number of bytes used to store the image data.  Undefined
207 where virtual is non-zero.
208
209 =item *
210
211 C<ch_mask> - a mask of writable channels.  eg. if this is 6 then only
212 channels 1 and 2 are writable.  There may be bits set for which there
213 are no channels in the image.
214
215 =item *
216
217 C<bits> - the number of bits stored per sample.  Should be one of
218 i_8_bits, i_16_bits, i_double_bits.
219
220 =item *
221
222 C<type> - either i_direct_type for direct color images, or i_palette_type
223 for paletted images.
224
225 =item *
226
227 C<virtual> - if zero then this image is-self contained.  If non-zero
228 then this image could be an interface to some other implementation.
229
230 =item *
231
232 C<idata> - the image data.  This should not be directly accessed.  A new
233 image implementation can use this to store its image data.
234 i_img_destroy() will myfree() this pointer if it's non-null.
235
236 =item *
237
238 C<tags> - a structure storing the image's tags.  This should only be
239 accessed via the i_tags_*() functions.
240
241 =item *
242
243 C<ext_data> - a pointer for use internal to an image implementation.
244 This should be freed by the image's destroy handler.
245
246 =item *
247
248 C<im_data> - data internal to Imager.  This is initialized by
249 i_img_init().
250
251 =item *
252
253 i_f_ppix, i_f_ppixf, i_f_plin, i_f_plinf, i_f_gpix, i_f_gpixf,
254 i_f_glin, i_f_glinf, i_f_gsamp, i_f_gampf - implementations for each
255 of the required image functions.  An image implementation should
256 initialize these between calling i_img_alloc() and i_img_init().
257
258 =item *
259
260 i_f_gpal, i_f_ppal, i_f_addcolors, i_f_getcolors, i_f_colorcount,
261 i_f_maxcolors, i_f_findcolor, i_f_setcolors - implementations for each
262 paletted image function.
263
264 =item *
265
266 i_f_destroy - custom image destruction function.  This should be used
267 to release memory if necessary.
268
269 =item *
270
271 i_f_gsamp_bits - implements i_gsamp_bits() for this image.
272
273 =item *
274
275 i_f_psamp_bits - implements i_psamp_bits() for this image.
276
277 =item *
278
279 i_f_psamp - implements psamp() for this image.
280
281 =item *
282
283 i_f_psampf - implements psamp() for this image.
284
285 =item *
286
287 C<im_data> - image specific data internal to Imager.
288
289 =item *
290
291 C<context> - the Imager API context this image belongs to.
292
293 =back
294
295
296 =for comment
297 From: File imdatatypes.h
298
299 =item i_color
300
301   i_color black;
302   black.rgba.r = black.rgba.g = black.rgba.b = black.rgba.a = 0;
303
304 Type for 8-bit/sample color.
305
306 Samples as per;
307
308   i_color c;
309
310 i_color is a union of:
311
312 =over
313
314 =item *
315
316 gray - contains a single element gray_color, eg. C<c.gray.gray_color>
317
318 =item *
319
320 C<rgb> - contains three elements C<r>, C<g>, C<b>, eg. C<c.rgb.r>
321
322 =item *
323
324 C<rgba> - contains four elements C<r>, C<g>, C<b>, C<a>, eg. C<c.rgba.a>
325
326 =item *
327
328 C<cmyk> - contains four elements C<c>, C<m>, C<y>, C<k>,
329 eg. C<c.cmyk.y>.  Note that Imager never uses CMYK colors except when
330 reading/writing files.
331
332 =item *
333
334 channels - an array of four channels, eg C<c.channels[2]>.
335
336 =back
337
338
339 =for comment
340 From: File imdatatypes.h
341
342 =item i_fcolor
343
344 This is the double/sample color type.
345
346 Its layout exactly corresponds to i_color.
347
348
349 =for comment
350 From: File imdatatypes.h
351
352 =item i_fill_t
353
354   i_fill_t *fill;
355
356 This is the "abstract" base type for Imager's fill types.
357
358 Unless you're implementing a new fill type you'll typically treat this
359 as an opaque type.
360
361
362 =for comment
363 From: File imdatatypes.h
364
365 =item i_img_dim
366
367   i_img_dim x, y;
368
369 A signed integer type that represents an image dimension or ordinate.
370
371 May be larger than int on some platforms.
372
373
374 =for comment
375 From: File imdatatypes.h
376
377 =item i_DF
378
379   printf("left %" i_DF "\n", i_DFc(x));
380
381 This is a constant string that can be used with functions like
382 printf() to format i_img_dim values after they're been cast with i_DFc().
383
384 Does not include the leading C<%>.
385
386
387 =for comment
388 From: File imdatatypes.h
389
390 =item i_DFc
391
392 Cast an C<i_img_dim> value to a type for use with the i_DF format
393 string.
394
395
396 =for comment
397 From: File imdatatypes.h
398
399 =item i_DFcp
400
401 Casts two C<i_img_dim> values for use with the i_DF (or i_DFp) format.
402
403
404 =for comment
405 From: File imdatatypes.h
406
407 =item i_DFp
408
409   printf("point (" i_DFp ")\n", i_DFcp(x, y));
410
411 Format a pair of C<i_img_dim> values.  This format string I<does>
412 include the leading C<%>.
413
414
415 =for comment
416 From: File imdatatypes.h
417
418
419 =back
420
421 =head2 Drawing
422
423 =over
424
425 =item i_arc(im, x, y, rad, d1, d2, color)
426
427
428   i_arc(im, 50, 50, 20, 45, 135, &color);
429
430 Fills an arc centered at (x,y) with radius I<rad> covering the range
431 of angles in degrees from d1 to d2, with the color.
432
433
434 =for comment
435 From: File draw.c
436
437 =item i_arc_aa(im, x, y, rad, d1, d2, color)
438
439
440   i_arc_aa(im, 50, 50, 35, 90, 135, &color);
441
442 Anti-alias fills an arc centered at (x,y) with radius I<rad> covering
443 the range of angles in degrees from d1 to d2, with the color.
444
445
446 =for comment
447 From: File draw.c
448
449 =item i_arc_aa_cfill(im, x, y, rad, d1, d2, fill)
450
451
452   i_arc_aa_cfill(im, 50, 50, 35, 90, 135, fill);
453
454 Anti-alias fills an arc centered at (x,y) with radius I<rad> covering
455 the range of angles in degrees from d1 to d2, with the fill object.
456
457
458 =for comment
459 From: File draw.c
460
461 =item i_arc_cfill(im, x, y, rad, d1, d2, fill)
462
463
464   i_arc_cfill(im, 50, 50, 35, 90, 135, fill);
465
466 Fills an arc centered at (x,y) with radius I<rad> covering the range
467 of angles in degrees from d1 to d2, with the fill object.
468
469
470 =for comment
471 From: File draw.c
472
473 =item i_box(im, x1, y1, x2, y2, color)
474
475
476   i_box(im, 0, 0, im->xsize-1, im->ysize-1, &color).
477
478 Outlines the box from (x1,y1) to (x2,y2) inclusive with I<color>.
479
480
481 =for comment
482 From: File draw.c
483
484 =item i_box_cfill(im, x1, y1, x2, y2, fill)
485
486
487   i_box_cfill(im, 0, 0, im->xsize-1, im->ysize-1, fill);
488
489 Fills the box from (x1,y1) to (x2,y2) inclusive with fill.
490
491
492 =for comment
493 From: File draw.c
494
495 =item i_box_filled(im, x1, y1, x2, y2, color)
496
497
498   i_box_filled(im, 0, 0, im->xsize-1, im->ysize-1, &color);
499
500 Fills the box from (x1,y1) to (x2,y2) inclusive with color.
501
502
503 =for comment
504 From: File draw.c
505
506 =item i_circle_aa(im, x, y, rad, color)
507
508
509   i_circle_aa(im, 50, 50, 45, &color);
510
511 Anti-alias fills a circle centered at (x,y) for radius I<rad> with
512 color.
513
514
515 =for comment
516 From: File draw.c
517
518 =item i_flood_cfill(C<im>, C<seedx>, C<seedy>, C<fill>)
519
520
521   i_flood_cfill(im, 50, 50, fill);
522
523 Flood fills the 4-connected region starting from the point (C<seedx>,
524 C<seedy>) with C<fill>.
525
526 Returns false if (C<seedx>, C<seedy>) are outside the image.
527
528
529 =for comment
530 From: File draw.c
531
532 =item i_flood_cfill_border(C<im>, C<seedx>, C<seedy>, C<fill>, C<border>)
533
534
535   i_flood_cfill_border(im, 50, 50, fill, border);
536
537 Flood fills the 4-connected region starting from the point (C<seedx>,
538 C<seedy>) with C<fill>, the fill stops when it reaches pixels of color
539 C<border>.
540
541 Returns false if (C<seedx>, C<seedy>) are outside the image.
542
543
544 =for comment
545 From: File draw.c
546
547 =item i_flood_fill(C<im>, C<seedx>, C<seedy>, C<color>)
548
549
550   i_flood_fill(im, 50, 50, &color);
551
552 Flood fills the 4-connected region starting from the point (C<seedx>,
553 C<seedy>) with I<color>.
554
555 Returns false if (C<seedx>, C<seedy>) are outside the image.
556
557
558 =for comment
559 From: File draw.c
560
561 =item i_flood_fill_border(C<im>, C<seedx>, C<seedy>, C<color>, C<border>)
562
563
564   i_flood_fill_border(im, 50, 50, &color, &border);
565
566 Flood fills the 4-connected region starting from the point (C<seedx>,
567 C<seedy>) with C<color>, fill stops when the fill reaches a pixels
568 with color C<border>.
569
570 Returns false if (C<seedx>, C<seedy>) are outside the image.
571
572
573 =for comment
574 From: File draw.c
575
576 =item i_glin(im, l, r, y, colors)
577
578
579 Retrieves (r-l) pixels starting from (l,y) into I<colors>.
580
581 Returns the number of pixels retrieved.
582
583
584 =for comment
585 From: File imext.c
586
587 =item i_glinf(im, l, r, y, colors)
588
589
590 Retrieves (r-l) pixels starting from (l,y) into I<colors> as floating
591 point colors.
592
593 Returns the number of pixels retrieved.
594
595
596 =for comment
597 From: File imext.c
598
599 =item i_gpal(im, left, right, y, indexes)
600
601
602 Reads palette indexes for the horizontal line (left, y) to (right-1,
603 y) into C<indexes>.
604
605 Returns the number of indexes read.
606
607 Always returns 0 for direct color images.
608
609
610 =for comment
611 From: File imext.c
612
613 =item i_gpix(im, C<x>, C<y>, C<color>)
614
615
616 Retrieves the C<color> of the pixel (x,y).
617
618 Returns 0 if the pixel was retrieved, or -1 if not.
619
620
621 =for comment
622 From: File imext.c
623
624 =item i_gpixf(im, C<x>, C<y>, C<fcolor>)
625
626
627 Retrieves the color of the pixel (x,y) as a floating point color into
628 C<fcolor>.
629
630 Returns 0 if the pixel was retrieved, or -1 if not.
631
632
633 =for comment
634 From: File imext.c
635
636 =item i_gsamp(im, left, right, y, samples, channels, channel_count)
637
638
639 Reads sample values from C<im> for the horizontal line (left, y) to
640 (right-1,y) for the channels specified by C<channels>, an array of int
641 with C<channel_count> elements.
642
643 If channels is NULL then the first channels_count channels are retrieved for
644 each pixel.
645
646 Returns the number of samples read (which should be (right-left) *
647 channel_count)
648
649
650 =for comment
651 From: File imext.c
652
653 =item i_gsamp_bg(im, l, r, y, samples, out_channels, background)
654
655
656 Like C<i_gsampf()> but applies the source image color over a supplied
657 background color.
658
659 This is intended for output to image formats that don't support alpha
660 channels.
661
662
663 =for comment
664 From: File paste.im
665
666 =item i_gsamp_bits(im, left, right, y, samples, channels, channel_count, bits)
667
668 Reads integer samples scaled to C<bits> bits of precision into the
669 C<unsigned int> array C<samples>.
670
671 Expect this to be slow unless C<< bits == im->bits >>.
672
673 Returns the number of samples copied, or -1 on error.
674
675 Not all image types implement this method.
676
677 Pushes errors, but does not call C<i_clear_error()>.
678
679
680 =for comment
681 From: File imext.c
682
683 =item i_gsampf(im, left, right, y, samples, channels, channel_count)
684
685
686 Reads floating point sample values from C<im> for the horizontal line
687 (left, y) to (right-1,y) for the channels specified by C<channels>, an
688 array of int with channel_count elements.
689
690 If C<channels> is NULL then the first C<channel_count> channels are
691 retrieved for each pixel.
692
693 Returns the number of samples read (which should be (C<right>-C<left>)
694 * C<channel_count>)
695
696
697 =for comment
698 From: File imext.c
699
700 =item i_gsampf_bg(im, l, r, y, samples, out_channels, background)
701
702
703 Like C<i_gsampf()> but applies the source image color over a supplied
704 background color.
705
706 This is intended for output to image formats that don't support alpha
707 channels.
708
709
710 =for comment
711 From: File paste.im
712
713 =item i_line(C<im>, C<x1>, C<y1>, C<x2>, C<y2>, C<color>, C<endp>)
714
715
716 =for stopwords Bresenham's
717
718 Draw a line to image using Bresenham's line drawing algorithm
719
720    im    - image to draw to
721    x1    - starting x coordinate
722    y1    - starting x coordinate
723    x2    - starting x coordinate
724    y2    - starting x coordinate
725    color - color to write to image
726    endp  - endpoint flag (boolean)
727
728
729 =for comment
730 From: File draw.c
731
732 =item i_line_aa(C<im>, C<x1>, C<x2>, C<y1>, C<y2>, C<color>, C<endp>)
733
734
735 Anti-alias draws a line from (x1,y1) to (x2, y2) in color.
736
737 The point (x2, y2) is drawn only if C<endp> is set.
738
739
740 =for comment
741 From: File draw.c
742
743 =item i_plin(im, l, r, y, colors)
744
745
746 Sets (r-l) pixels starting from (l,y) using (r-l) values from
747 I<colors>.
748
749 Returns the number of pixels set.
750
751
752 =for comment
753 From: File imext.c
754
755 =item i_plinf(im, C<left>, C<right>, C<fcolors>)
756
757
758 Sets (right-left) pixels starting from (left,y) using (right-left)
759 floating point colors from C<fcolors>.
760
761 Returns the number of pixels set.
762
763
764 =for comment
765 From: File imext.c
766
767 =item i_ppal(im, left, right, y, indexes)
768
769
770 Writes palette indexes for the horizontal line (left, y) to (right-1,
771 y) from C<indexes>.
772
773 Returns the number of indexes written.
774
775 Always returns 0 for direct color images.
776
777
778 =for comment
779 From: File imext.c
780
781 =item i_ppix(im, x, y, color)
782
783
784 Sets the pixel at (x,y) to I<color>.
785
786 Returns 0 if the pixel was drawn, or -1 if not.
787
788 Does no alpha blending, just copies the channels from the supplied
789 color to the image.
790
791
792 =for comment
793 From: File imext.c
794
795 =item i_ppixf(im, C<x>, C<y>, C<fcolor>)
796
797
798 Sets the pixel at (C<x>,C<y>) to the floating point color C<fcolor>.
799
800 Returns 0 if the pixel was drawn, or -1 if not.
801
802 Does no alpha blending, just copies the channels from the supplied
803 color to the image.
804
805
806 =for comment
807 From: File imext.c
808
809 =item i_psamp(im, left, right, y, samples, channels, channel_count)
810
811 Writes sample values from C<samples> to C<im> for the horizontal line
812 (left, y) to (right-1, y) inclusive for the channels specified by
813 C<channels>, an array of C<int> with C<channel_count> elements.
814
815 If C<channels> is C<NULL> then the first C<channels_count> channels
816 are written to for each pixel.
817
818 Returns the number of samples written, which should be (right - left)
819 * channel_count.  If a channel not in the image is in channels, left
820 is negative, left is outside the image or y is outside the image,
821 returns -1 and pushes an error.
822
823
824 =for comment
825 From: File immacros.h
826
827 =item i_psamp_bits(im, left, right, y, samples, channels, channel_count, bits)
828
829 Writes integer samples scaled to C<bits> bits of precision from the
830 C<unsigned int> array C<samples>.
831
832 Expect this to be slow unless C<< bits == im->bits >>.
833
834 Returns the number of samples copied, or -1 on error.
835
836 Not all image types implement this method.
837
838 Pushes errors, but does not call C<i_clear_error()>.
839
840
841 =for comment
842 From: File imext.c
843
844 =item i_psampf(im, left, right, y, samples, channels, channel_count)
845
846 Writes floating point sample values from C<samples> to C<im> for the
847 horizontal line (left, y) to (right-1, y) inclusive for the channels
848 specified by C<channels>, an array of C<int> with C<channel_count>
849 elements.
850
851 If C<channels> is C<NULL> then the first C<channels_count> channels
852 are written to for each pixel.
853
854 Returns the number of samples written, which should be (right - left)
855 * channel_count.  If a channel not in the image is in channels, left
856 is negative, left is outside the image or y is outside the image,
857 returns -1 and pushes an error.
858
859
860 =for comment
861 From: File immacros.h
862
863
864 =back
865
866 =head2 Error handling
867
868 =over
869
870 =item i_push_errorf(int code, char const *fmt, ...)
871
872   i_push_errorf(errno, "Cannot open file %s: %d", filename, errno);
873
874 A version of i_push_error() that does printf() like formatting.
875
876 Does not support perl specific format codes.
877
878
879 =for comment
880 From: File error.c
881
882 =item im_clear_error(ctx)
883 X<im_clear_error API>X<i_clear_error API>
884
885   im_clear_error(aIMCTX);
886   i_clear_error();
887
888 Clears the error stack.
889
890 Called by any Imager function before doing any other processing.
891
892 Also callable as C<i_clear_error()>.
893
894
895 =for comment
896 From: File error.c
897
898 =item im_push_error(ctx, code, message)
899 X<im_push_error API>X<i_push_error API>
900
901   i_push_error(0, "Yep, it's broken");
902   i_push_error(errno, "Error writing");
903   im_push_error(aIMCTX, 0, "Something is wrong");
904
905 Called by an Imager function to push an error message onto the stack.
906
907 No message is pushed if the stack is full (since this means someone
908 forgot to call i_clear_error(), or that a function that doesn't do
909 error handling is calling function that does.).
910
911
912 =for comment
913 From: File error.c
914
915 =item im_push_errorf(ctx, code, char const *fmt, ...)
916
917   im_push_errorf(aIMCTX, errno, "Cannot open file %s: %d", filename, errno);
918
919 A version of im_push_error() that does printf() like formatting.
920
921 Does not support perl specific format codes.
922
923
924 =for comment
925 From: File error.c
926
927 =item im_push_errorvf(ctx, code, format, args)
928 X<im_push_error_vf API>X<i_push_errorvf API>
929
930   va_args args;
931   va_start(args, lastarg);
932   im_push_errorvf(ctx, code, format, args);
933
934 Intended for use by higher level functions, takes a varargs pointer
935 and a format to produce the finally pushed error message.
936
937 Does not support perl specific format codes.
938
939 Also callable as C<i_push_errorvf(code, format, args)>
940
941
942 =for comment
943 From: File error.c
944
945
946 =back
947
948 =head2 Files
949
950 =over
951
952 =item i_get_file_background(im, &bg)
953
954
955 Retrieve the file write background color tag from the image.
956
957 If not present, C<bg> is set to black.
958
959 Returns 1 if the C<i_background> tag was found and valid.
960
961
962 =for comment
963 From: File image.c
964
965 =item i_get_file_backgroundf(im, &bg)
966
967
968 Retrieve the file write background color tag from the image as a
969 floating point color.
970
971 Implemented in terms of i_get_file_background().
972
973 If not present, C<bg> is set to black.
974
975 Returns 1 if the C<i_background> tag was found and valid.
976
977
978 =for comment
979 From: File image.c
980
981 =item im_get_image_file_limits(ctx, &width, &height, &bytes)
982 X<im_get_image_file_limits API>X<i_get_image_file_limits>
983
984   im_get_image_file_limits(aIMCTX, &width, &height, &bytes)
985   i_get_image_file_limits(&width, &height, &bytes)
986
987 Retrieves the file limits set by i_set_image_file_limits().
988
989 =over
990
991 =item *
992
993 i_img_dim *width, *height - the maximum width and height of the image.
994
995 =item *
996
997 size_t *bytes - size in memory of the image in bytes.
998
999 =back
1000
1001 Also callable as C<i_get_image_file_limits(&width, &height, &bytes)>.
1002
1003
1004 =for comment
1005 From: File limits.c
1006
1007 =item im_int_check_image_file_limits(width, height, channels, sample_size)
1008 X<im_int_check_image_file_limits API>X<i_int_check_image_file_limits>
1009
1010   im_int_check_image_file_limits(aIMCTX, width, height, channels, sizeof(i_sample_t))
1011   i_int_check_image_file_limits(width, height, channels, sizeof(i_sample_t))
1012
1013 Checks the size of a file in memory against the configured image file
1014 limits.
1015
1016 This also range checks the values to those permitted by Imager and
1017 checks for overflows in calculating the size.
1018
1019 Returns non-zero if the file is within limits.
1020
1021 This function is intended to be called by image file read functions.
1022
1023 Also callable as C<i_int_check_image_file_limits(width, height, channels, sizeof(i_sample_t)>.
1024
1025
1026 =for comment
1027 From: File limits.c
1028
1029 =item im_set_image_file_limits(ctx, width, height, bytes)
1030 X<im_set_image_file_limits API>X<i_set_image_file_limits API>
1031
1032   im_set_image_file_limits(aIMCTX, 500, 500, 1000000);
1033   i_set_image_file_limits(500, 500, 1000000);
1034
1035 Set limits on the sizes of images read by Imager.
1036
1037 Setting a limit to 0 means that limit is ignored.
1038
1039 Negative limits result in failure.
1040
1041 Parameters:
1042
1043 =over
1044
1045 =item *
1046
1047 i_img_dim width, height - maximum width and height.
1048
1049 =item *
1050
1051 size_t bytes - maximum size in memory in bytes.  A value of zero sets
1052 this limit to one gigabyte.
1053
1054 =back
1055
1056 Returns non-zero on success.
1057
1058 Also callable as C<i_set_image_file_limits(width, height, bytes)>.
1059
1060
1061 =for comment
1062 From: File limits.c
1063
1064
1065 =back
1066
1067 =head2 Fills
1068
1069 =over
1070
1071 =item i_new_fill_fount(C<xa>, C<ya>, C<xb>, C<yb>, C<type>, C<repeat>, C<combine>, C<super_sample>, C<ssample_param>, C<count>, C<segs>)
1072
1073
1074   fill = i_new_fill_fount(0, 0, 100, 100, i_ft_linear, i_ft_linear, 
1075                           i_fr_triangle, 0, i_fts_grid, 9, 1, segs);
1076
1077
1078 Creates a new general fill which fills with a fountain fill.
1079
1080
1081 =for comment
1082 From: File filters.im
1083
1084 =item i_new_fill_hatch(C<fg>, C<bg>, C<combine>, C<hatch>, C<cust_hatch>, C<dx>, C<dy>)
1085
1086
1087   i_fill_t *fill = i_new_fill_hatch(&fg_color, &bg_color, combine, hatch, custom_hatch, dx, dy);
1088
1089 Creates a new hatched fill with the C<fg> color used for the 1 bits in
1090 the hatch and C<bg> for the 0 bits.  If C<combine> is non-zero alpha
1091 values will be combined.
1092
1093 If C<cust_hatch> is non-NULL it should be a pointer to 8 bytes of the
1094 hash definition, with the high-bits to the left.
1095
1096 If C<cust_hatch> is NULL then one of the standard hatches is used.
1097
1098 (C<dx>, C<dy>) are an offset into the hatch which can be used to hatch
1099 adjoining areas out of alignment, or to align the origin of a hatch
1100 with the the side of a filled area.
1101
1102
1103 =for comment
1104 From: File fills.c
1105
1106 =item i_new_fill_hatchf(C<fg>, C<bg>, C<combine>, C<hatch>, C<cust_hatch>, C<dx>, C<dy>)
1107
1108
1109   i_fill_t *fill = i_new_fill_hatchf(&fg_fcolor, &bg_fcolor, combine, hatch, custom_hatch, dx, dy);
1110
1111 Creates a new hatched fill with the C<fg> color used for the 1 bits in
1112 the hatch and C<bg> for the 0 bits.  If C<combine> is non-zero alpha
1113 values will be combined.
1114
1115 If C<cust_hatch> is non-NULL it should be a pointer to 8 bytes of the
1116 hash definition, with the high-bits to the left.
1117
1118 If C<cust_hatch> is NULL then one of the standard hatches is used.
1119
1120 (C<dx>, C<dy>) are an offset into the hatch which can be used to hatch
1121 adjoining areas out of alignment, or to align the origin of a hatch
1122 with the the side of a filled area.
1123
1124
1125 =for comment
1126 From: File fills.c
1127
1128 =item i_new_fill_image(C<im>, C<matrix>, C<xoff>, C<yoff>, C<combine>)
1129
1130
1131   i_fill_t *fill = i_new_fill_image(src_img, matrix, x_offset, y_offset, combine);
1132
1133 Create an image based fill.
1134
1135 matrix is an array of 9 doubles representing a transformation matrix.
1136
1137 C<xoff> and C<yoff> are the offset into the image to start filling from.
1138
1139
1140 =for comment
1141 From: File fills.c
1142
1143 =item i_new_fill_solid(color, combine)
1144
1145
1146   i_fill_t *fill = i_new_fill_solid(&color, combine);
1147
1148 Create a solid fill based on an 8-bit color.
1149
1150 If combine is non-zero then alpha values will be combined.
1151
1152
1153 =for comment
1154 From: File fills.c
1155
1156 =item i_new_fill_solidf(color, combine)
1157
1158
1159   i_fill_t *fill = i_new_fill_solidf(&fcolor, combine);
1160
1161 Create a solid fill based on a float color.
1162
1163 If combine is non-zero then alpha values will be combined.
1164
1165
1166 =for comment
1167 From: File fills.c
1168
1169 =item i_fill_destroy(fill)
1170
1171   i_fill_destroy(fill);
1172
1173 Call to destroy any fill object.
1174
1175
1176 =for comment
1177 From: File fills.c
1178
1179
1180 =back
1181
1182 =head2 I/O Layers
1183
1184 =over
1185
1186 =item im_io_new_bufchain(ctx)
1187 X<im_io_new_bufchain API>X<i_io_new_bufchain API>
1188
1189 Returns a new io_glue object that has the 'empty' source and but can
1190 be written to and read from later (like a pseudo file).
1191
1192 Also callable as C<io_new_bufchain()>.
1193
1194
1195 =for comment
1196 From: File iolayer.c
1197
1198 =item im_io_new_buffer(ctx, data, length)
1199 X<im_io_new_buffer API>X<io_new_buffer API>
1200
1201 Returns a new io_glue object that has the source defined as reading
1202 from specified buffer.  Note that the buffer is not copied.
1203
1204    ctx - an Imager context object
1205    data - buffer to read from
1206    length - length of buffer
1207
1208 Also callable as C<io_new_buffer(data, length>.
1209
1210
1211 =for comment
1212 From: File iolayer.c
1213
1214 =item im_io_new_cb(ctx, p, read_cb, write_cb, seek_cb, close_cb, destroy_cb)
1215 X<im_io_new_cb API>X<io_new_cb API>
1216
1217 Create a new I/O layer object that calls your supplied callbacks.
1218
1219 In general the callbacks should behave like the corresponding POSIX
1220 primitives.
1221
1222 =over
1223
1224 =item *
1225
1226 C<read_cb>(p, buffer, length) should read up to C<length> bytes into
1227 C<buffer> and return the number of bytes read.  At end of file, return
1228 0.  On error, return -1.
1229
1230 =item *
1231
1232 C<write_cb>(p, buffer, length) should write up to C<length> bytes from
1233 C<buffer> and return the number of bytes written.  A return value <= 0
1234 will be treated as an error.
1235
1236 =item *
1237
1238 C<seekcb>(p, offset, whence) should seek and return the new offset.
1239
1240 =item *
1241
1242 C<close_cb>(p) should return 0 on success, -1 on failure.
1243
1244 =item *
1245
1246 C<destroy_cb>(p) should release any memory specific to your callback
1247 handlers.
1248
1249 =back
1250
1251 Also callable as C<io_new_cb(p, readcb, writecb, seekcb, closecb,
1252 destroycb)>.
1253
1254
1255 =for comment
1256 From: File iolayer.c
1257
1258 =item im_io_new_fd(ctx, file)
1259 X<io_new_fd API>X<im_io_new_fd API>
1260
1261 Returns a new io_glue object that has the source defined as reading
1262 from specified file descriptor.  Note that the the interface to receiving
1263 data from the io_glue callbacks hasn't been done yet.
1264
1265   ctx - and Imager context object
1266   file - file descriptor to read/write from
1267
1268 Also callable as C<io_new_fd(file)>.
1269
1270
1271 =for comment
1272 From: File iolayer.c
1273
1274 =item i_io_close(io)
1275
1276 Flush any pending output and perform the close action for the stream.
1277
1278 Returns 0 on success.
1279
1280
1281 =for comment
1282 From: File iolayer.c
1283
1284 =item i_io_flush(io)
1285
1286 Flush any buffered output.
1287
1288 Returns true on success,
1289
1290
1291 =for comment
1292 From: File iolayer.c
1293
1294 =item i_io_getc(ig)
1295
1296 A macro to read a single byte from a buffered I/O glue object.
1297
1298 Returns EOF on failure, or a byte.
1299
1300
1301 =for comment
1302 From: File iolayer.c
1303
1304 =item i_io_gets(ig, buffer, size, end_of_line)
1305
1306   char buffer[BUFSIZ]
1307   ssize_t len = i_io_gets(buffer, sizeof(buffer), '\n');
1308
1309 Read up to C<size>-1 bytes from the stream C<ig> into C<buffer>.
1310
1311 If the byte C<end_of_line> is seen then no further bytes will be read.
1312
1313 Returns the number of bytes read.
1314
1315 Always C<NUL> terminates the buffer.
1316
1317
1318 =for comment
1319 From: File iolayer.c
1320
1321 =item i_io_peekc(ig)
1322
1323 Read the next character from the stream without advancing the stream.
1324
1325 On error or end of file, return EOF.
1326
1327 For unbuffered streams a single character buffer will be setup.
1328
1329
1330 =for comment
1331 From: File iolayer.c
1332
1333 =item i_io_peekn(ig, buffer, size)
1334
1335   ssize_t count = i_io_peekn(ig, buffer, sizeof(buffer));
1336
1337 Buffer at least C<size> (at most C<< ig->buf_size >> bytes of data
1338 from the stream and return C<size> bytes of it to the caller in
1339 C<buffer>.
1340
1341 This ignores the buffered state of the stream, and will always setup
1342 buffering if needed.
1343
1344 If no C<type> parameter is provided to Imager::read() or
1345 Imager::read_multi(), Imager will call C<i_io_peekn()> when probing
1346 for the file format.
1347
1348 Returns -1 on error, 0 if there is no data before EOF, or the number
1349 of bytes read into C<buffer>.
1350
1351
1352 =for comment
1353 From: File iolayer.c
1354
1355 =item i_io_putc(ig, c)
1356
1357 Write a single character to the stream.
1358
1359 On success return c, on error returns EOF
1360
1361
1362 =for comment
1363 From: File iolayer.c
1364
1365 =item i_io_read(io, buffer, size)
1366
1367 Read up to C<size> bytes from the stream C<io> into C<buffer>.
1368
1369 Returns the number of bytes read.  Returns 0 on end of file.  Returns
1370 -1 on error.
1371
1372
1373 =for comment
1374 From: File iolayer.c
1375
1376 =item i_io_seek(io, offset, whence)
1377
1378 Seek within the stream.
1379
1380 Acts like perl's seek.
1381
1382
1383 =for comment
1384 From: File iolayer.c
1385
1386 =item i_io_set_buffered(io, buffered)
1387
1388 Set the buffering mode of the stream.
1389
1390 If you switch buffering off on a stream with buffering on:
1391
1392 =over
1393
1394 =item *
1395
1396 any buffered output will be flushed.
1397
1398 =item *
1399
1400 any existing buffered input will be consumed before reads become
1401 unbuffered.
1402
1403 =back
1404
1405 Returns true on success.  This may fail if any buffered output cannot
1406 be flushed.
1407
1408
1409 =for comment
1410 From: File iolayer.c
1411
1412 =item i_io_write(io, buffer, size)
1413
1414   ssize_t result = i_io_write(io, buffer, size)
1415
1416 Write to the given I/O stream.
1417
1418 Returns the number of bytes written.
1419
1420
1421 =for comment
1422 From: File iolayer.c
1423
1424 =item io_slurp(ig, c)
1425 X<io_slurp API>
1426
1427 Takes the source that the io_glue is bound to and allocates space for
1428 a return buffer and returns the entire content in a single buffer.
1429 Note: This only works for io_glue objects created by
1430 io_new_bufchain().  It is useful for saving to scalars and such.
1431
1432    ig - io_glue object
1433    c  - pointer to a pointer to where data should be copied to
1434
1435   char *data;
1436   size_t size = io_slurp(ig, &data);
1437   ... do something with the data ...
1438   myfree(data);
1439
1440 io_slurp() will abort the program if the supplied I/O layer is not
1441 from io_new_bufchain().
1442
1443
1444 =for comment
1445 From: File iolayer.c
1446
1447 =item io_glue_destroy(ig)
1448 X<io_glue_destroy API>
1449
1450   io_glue_destroy(ig);
1451
1452 Destroy an io_glue objects.  Should clean up all related buffers.
1453
1454    ig - io_glue object to destroy.
1455
1456
1457 =for comment
1458 From: File iolayer.c
1459
1460
1461 =back
1462
1463 =head2 Image
1464
1465 =over
1466
1467 =item i_copy(source)
1468
1469
1470 Creates a new image that is a copy of the image C<source>.
1471
1472 Tags are not copied, only the image data.
1473
1474 Returns: i_img *
1475
1476
1477 =for comment
1478 From: File image.c
1479
1480 =item i_copyto(C<dest>, C<src>, C<x1>, C<y1>, C<x2>, C<y2>, C<tx>, C<ty>)
1481
1482
1483 Copies image data from the area (C<x1>,C<y1>)-[C<x2>,C<y2>] in the
1484 source image to a rectangle the same size with it's top-left corner at
1485 (C<tx>,C<ty>) in the destination image.
1486
1487 If C<x1> > C<x2> or C<y1> > C<y2> then the corresponding co-ordinates
1488 are swapped.
1489
1490
1491 =for comment
1492 From: File paste.im
1493
1494 =item i_copyto_trans(C<im>, C<src>, C<x1>, C<y1>, C<x2>, C<y2>, C<tx>, C<ty>, C<trans>)
1495
1496
1497 (C<x1>,C<y1>) (C<x2>,C<y2>) specifies the region to copy (in the
1498 source coordinates) (C<tx>,C<ty>) specifies the upper left corner for
1499 the target image.  pass NULL in C<trans> for non transparent i_colors.
1500
1501
1502 =for comment
1503 From: File image.c
1504
1505 =item i_img_info(im, info)
1506
1507
1508 Return image information
1509
1510    im - Image pointer
1511    info - pointer to array to return data
1512
1513 info is an array of 4 integers with the following values:
1514
1515  info[0] - width
1516  info[1] - height
1517  info[2] - channels
1518  info[3] - channel mask
1519
1520
1521 =for comment
1522 From: File image.c
1523
1524 =item i_rubthru(C<im>, C<src>, C<tx>, C<ty>, C<src_minx>, C<src_miny>, C<src_maxx>, C<src_maxy>)
1525
1526
1527 Takes the sub image C<src>[C<src_minx>, C<src_maxx>)[C<src_miny>, C<src_maxy>)> and
1528 overlays it at (C<tx>,C<ty>) on the image object.
1529
1530 The alpha channel of each pixel in C<src> is used to control how much
1531 the existing color in C<im> is replaced, if it is 255 then the color
1532 is completely replaced, if it is 0 then the original color is left
1533 unmodified.
1534
1535
1536 =for comment
1537 From: File rubthru.im
1538
1539
1540 =back
1541
1542 =head2 Image creation/destruction
1543
1544 =over
1545
1546 =item i_sametype(C<im>, C<xsize>, C<ysize>)
1547
1548
1549   i_img *img = i_sametype(src, width, height);
1550
1551 Returns an image of the same type (sample size, channels, paletted/direct).
1552
1553 For paletted images the palette is copied from the source.
1554
1555
1556 =for comment
1557 From: File image.c
1558
1559 =item i_sametype_chans(C<im>, C<xsize>, C<ysize>, C<channels>)
1560
1561
1562   i_img *img = i_sametype_chans(src, width, height, channels);
1563
1564 Returns an image of the same type (sample size).
1565
1566 For paletted images the equivalent direct type is returned.
1567
1568
1569 =for comment
1570 From: File image.c
1571
1572 =item im_img_16_new(ctx, x, y, ch)
1573 X<im_img_16_new API>X<i_img_16_new API>
1574
1575   i_img *img = im_img_16_new(aIMCTX, width, height, channels);
1576   i_img *img = i_img_16_new(width, height, channels);
1577
1578 Create a new 16-bit/sample image.
1579
1580 Returns the image on success, or NULL on failure.
1581
1582 Also callable as C<i_img_16_new(x, y, ch)>
1583
1584
1585 =for comment
1586 From: File img16.c
1587
1588 =item im_img_8_new(ctx, x, y, ch)
1589 X<im_img_8_new API>X<i_img_8_new API>
1590
1591   i_img *img = im_img_8_new(aIMCTX, width, height, channels);
1592   i_img *img = i_img_8_new(width, height, channels);
1593
1594 Creates a new image object I<x> pixels wide, and I<y> pixels high with
1595 I<ch> channels.
1596
1597
1598 =for comment
1599 From: File img8.c
1600
1601 =item im_img_double_new(ctx, x, y, ch)
1602 X<im_img_double_new API>X<i_img_double_new API>
1603
1604   i_img *img = im_img_double_new(aIMCTX, width, height, channels);
1605   i_img *img = i_img_double_new(width, height, channels);
1606
1607 Creates a new double per sample image.
1608
1609 Also callable as C<i_img_double_new(width, height, channels)>.
1610
1611
1612 =for comment
1613 From: File imgdouble.c
1614
1615 =item im_img_pal_new(ctx, C<x>, C<y>, C<channels>, C<maxpal>)
1616 X<im_img_pal_new API>X<i_img_pal_new API>
1617
1618   i_img *img = im_img_pal_new(aIMCTX, width, height, channels, max_palette_size)
1619   i_img *img = i_img_pal_new(width, height, channels, max_palette_size)
1620
1621 Creates a new paletted image of the supplied dimensions.
1622
1623 C<maxpal> is the maximum palette size and should normally be 256.
1624
1625 Returns a new image or NULL on failure.
1626
1627 Also callable as C<i_img_pal_new(width, height, channels, max_palette_size)>.
1628
1629
1630 =for comment
1631 From: File palimg.c
1632
1633 =item i_img_destroy(C<img>)
1634
1635   i_img_destroy(img)
1636
1637 Destroy an image object
1638
1639
1640 =for comment
1641 From: File image.c
1642
1643
1644 =back
1645
1646 =head2 Image Implementation
1647
1648 =over
1649
1650 =item im_img_alloc(aIMCTX)
1651 X<im_img_alloc API>X<i_img_alloc API>
1652
1653   i_img *im = im_img_alloc(aIMCTX);
1654   i_img *im = i_img_alloc();
1655
1656 Allocates a new i_img structure.
1657
1658 When implementing a new image type perform the following steps in your
1659 image object creation function:
1660
1661 =over
1662
1663 =item 1.
1664
1665 allocate the image with i_img_alloc().
1666
1667 =item 2.
1668
1669 initialize any function pointers or other data as needed, you can
1670 overwrite the whole block if you need to.
1671
1672 =item 3.
1673
1674 initialize Imager's internal data by calling i_img_init() on the image
1675 object.
1676
1677 =back
1678
1679
1680 =for comment
1681 From: File image.c
1682
1683 =item im_img_init(aIMCTX, image)
1684 X<im_img_init API>X<i_img_init API>
1685
1686   im_img_init(aIMCTX, im);
1687   i_img_init(im);
1688
1689 Imager internal initialization of images.
1690
1691 See L</im_img_alloc(aIMCTX)> for more information.
1692
1693
1694 =for comment
1695 From: File image.c
1696
1697
1698 =back
1699
1700 =head2 Image Information
1701
1702 =over
1703
1704 =item i_img_color_channels(C<im>)
1705
1706
1707 The number of channels holding color information.
1708
1709
1710 =for comment
1711 From: File immacros.h
1712
1713 =item i_img_get_height(C<im>)
1714
1715   i_img_dim height = i_img_get_height(im);
1716
1717 Returns the height in pixels of the image.
1718
1719
1720 =for comment
1721 From: File image.c
1722
1723 =item i_img_get_width(C<im>)
1724
1725   i_img_dim width = i_img_get_width(im);
1726
1727 Returns the width in pixels of the image.
1728
1729
1730 =for comment
1731 From: File image.c
1732
1733 =item i_img_getchannels(C<im>)
1734
1735   int channels = i_img_getchannels(img);
1736
1737 Get the number of channels in C<im>.
1738
1739
1740 =for comment
1741 From: File image.c
1742
1743 =item i_img_getmask(C<im>)
1744
1745   int mask = i_img_getmask(img);
1746
1747 Get the image channel mask for C<im>.
1748
1749
1750 =for comment
1751 From: File image.c
1752
1753 =item i_img_has_alpha(C<im>)
1754
1755
1756 Return true if the image has an alpha channel.
1757
1758
1759 =for comment
1760 From: File immacros.h
1761
1762 =item i_img_is_monochrome(img, &zero_is_white)
1763
1764
1765 Tests an image to check it meets our monochrome tests.
1766
1767 The idea is that a file writer can use this to test where it should
1768 write the image in whatever bi-level format it uses, eg. C<pbm> for
1769 C<pnm>.
1770
1771 For performance of encoders we require monochrome images:
1772
1773 =over
1774
1775 =item *
1776
1777 be paletted
1778
1779 =item *
1780
1781 have a palette of two colors, containing only C<(0,0,0)> and
1782 C<(255,255,255)> in either order.
1783
1784 =back
1785
1786 C<zero_is_white> is set to non-zero if the first palette entry is white.
1787
1788
1789 =for comment
1790 From: File image.c
1791
1792 =item i_img_setmask(C<im>, C<ch_mask>)
1793
1794   // only channel 0 writable 
1795   i_img_setmask(img, 0x01);
1796
1797 Set the image channel mask for C<im> to C<ch_mask>.
1798
1799 The image channel mask gives some control over which channels can be
1800 written to in the image.
1801
1802
1803 =for comment
1804 From: File image.c
1805
1806
1807 =back
1808
1809 =head2 Image quantization
1810
1811 =over
1812
1813 =item i_quant_makemap(C<quant>, C<imgs>, C<count>)
1814
1815
1816 Analyzes the C<count> images in C<imgs> according to the rules in
1817 C<quant> to build a color map (optimal or not depending on
1818 C<< quant->make_colors >>).
1819
1820
1821 =for comment
1822 From: File quant.c
1823
1824 =item i_quant_translate(C<quant>, C<img>)
1825
1826
1827 Quantize the image given the palette in C<quant>.
1828
1829 On success returns a pointer to a memory block of C<< img->xsize *
1830 img->ysize >> C<i_palidx> entries.
1831
1832 On failure returns NULL.
1833
1834 You should call myfree() on the returned block when you're done with
1835 it.
1836
1837 This function will fail if the supplied palette contains no colors.
1838
1839
1840 =for comment
1841 From: File quant.c
1842
1843 =item i_quant_transparent(C<quant>, C<data>, C<img>, C<trans_index>)
1844
1845
1846 Dither the alpha channel on C<img> into the palette indexes in
1847 C<data>.  Pixels to be transparent are replaced with C<trans_pixel>.
1848
1849 The method used depends on the tr_* members of C<quant>.
1850
1851
1852 =for comment
1853 From: File quant.c
1854
1855
1856 =back
1857
1858 =head2 Logging
1859
1860 =over
1861
1862 =item i_lhead(file, line)
1863
1864 This is an internal function called by the mm_log() macro.
1865
1866
1867 =for comment
1868 From: File log.c
1869
1870 =item i_loog(level, format, ...)
1871
1872 This is an internal function called by the mm_log() macro.
1873
1874
1875 =for comment
1876 From: File log.c
1877
1878
1879 =back
1880
1881 =head2 Paletted images
1882
1883 =over
1884
1885 =item i_addcolors(im, colors, count)
1886
1887
1888 Adds colors to the image's palette.
1889
1890 On success returns the index of the lowest color added.
1891
1892 On failure returns -1.
1893
1894 Always fails for direct color images.
1895
1896
1897 =for comment
1898 From: File imext.c
1899
1900 =item i_colorcount(im)
1901
1902
1903 Returns the number of colors in the image's palette.
1904
1905 Returns -1 for direct images.
1906
1907
1908 =for comment
1909 From: File imext.c
1910
1911 =item i_findcolor(im, color, &entry)
1912
1913
1914 Searches the images palette for the given color.
1915
1916 On success sets *I<entry> to the index of the color, and returns true.
1917
1918 On failure returns false.
1919
1920 Always fails on direct color images.
1921
1922
1923 =for comment
1924 From: File imext.c
1925
1926 =item i_getcolors(im, index, colors, count)
1927
1928
1929 Retrieves I<count> colors starting from I<index> in the image's
1930 palette.
1931
1932 On success stores the colors into I<colors> and returns true.
1933
1934 On failure returns false.
1935
1936 Always fails for direct color images.
1937
1938 Fails if there are less than I<index>+I<count> colors in the image's
1939 palette.
1940
1941
1942 =for comment
1943 From: File imext.c
1944
1945 =item i_maxcolors(im)
1946
1947
1948 Returns the maximum number of colors the palette can hold for the
1949 image.
1950
1951 Returns -1 for direct color images.
1952
1953
1954 =for comment
1955 From: File imext.c
1956
1957 =item i_setcolors(im, index, colors, count)
1958
1959
1960 Sets I<count> colors starting from I<index> in the image's palette.
1961
1962 On success returns true.
1963
1964 On failure returns false.
1965
1966 The image must have at least I<index>+I<count> colors in it's palette
1967 for this to succeed.
1968
1969 Always fails on direct color images.
1970
1971
1972 =for comment
1973 From: File imext.c
1974
1975
1976 =back
1977
1978 =head2 Tags
1979
1980 =over
1981
1982 =item i_tags_delbycode(tags, code)
1983
1984
1985 Delete any tags with the given code.
1986
1987 Returns the number of tags deleted.
1988
1989
1990 =for comment
1991 From: File tags.c
1992
1993 =item i_tags_delbyname(tags, name)
1994
1995
1996 Delete any tags with the given name.
1997
1998 Returns the number of tags deleted.
1999
2000
2001 =for comment
2002 From: File tags.c
2003
2004 =item i_tags_delete(tags, index)
2005
2006
2007 Delete a tag by index.
2008
2009 Returns true on success.
2010
2011
2012 =for comment
2013 From: File tags.c
2014
2015 =item i_tags_destroy(tags)
2016
2017
2018 Destroys the given tags structure.  Called by i_img_destroy().
2019
2020
2021 =for comment
2022 From: File tags.c
2023
2024 =item i_tags_find(tags, name, start, &entry)
2025
2026
2027 Searches for a tag of the given I<name> starting from index I<start>.
2028
2029 On success returns true and sets *I<entry>.
2030
2031 On failure returns false.
2032
2033
2034 =for comment
2035 From: File tags.c
2036
2037 =item i_tags_findn(tags, code, start, &entry)
2038
2039
2040 Searches for a tag of the given I<code> starting from index I<start>.
2041
2042 On success returns true and sets *I<entry>.
2043
2044 On failure returns false.
2045
2046
2047 =for comment
2048 From: File tags.c
2049
2050 =item i_tags_get_color(tags, name, code, &value)
2051
2052
2053 Retrieve a tag specified by name or code as color.
2054
2055 On success sets the i_color *I<value> to the color and returns true.
2056
2057 On failure returns false.
2058
2059
2060 =for comment
2061 From: File tags.c
2062
2063 =item i_tags_get_float(tags, name, code, value)
2064
2065
2066 Retrieves a tag as a floating point value.  
2067
2068 If the tag has a string value then that is parsed as a floating point
2069 number, otherwise the integer value of the tag is used.
2070
2071 On success sets *I<value> and returns true.
2072
2073 On failure returns false.
2074
2075
2076 =for comment
2077 From: File tags.c
2078
2079 =item i_tags_get_int(tags, name, code, &value)
2080
2081
2082 Retrieve a tag specified by name or code as an integer.
2083
2084 On success sets the int *I<value> to the integer and returns true.
2085
2086 On failure returns false.
2087
2088
2089 =for comment
2090 From: File tags.c
2091
2092 =item i_tags_get_string(tags, name, code, value, value_size)
2093
2094
2095 Retrieves a tag by name or code as a string.
2096
2097 On success copies the string to value for a max of value_size and
2098 returns true.
2099
2100 On failure returns false.
2101
2102 value_size must be at least large enough for a string representation
2103 of an integer.
2104
2105 The copied value is always C<NUL> terminated.
2106
2107
2108 =for comment
2109 From: File tags.c
2110
2111 =item i_tags_new(i_img_tags *tags)
2112
2113
2114 Initialize a tags structure.  Should not be used if the tags structure
2115 has been previously used.
2116
2117 This should be called tags member of an i_img object on creation (in
2118 i_img_*_new() functions).
2119
2120 To destroy the contents use i_tags_destroy()
2121
2122
2123 =for comment
2124 From: File tags.c
2125
2126 =item i_tags_set(tags, name, data, size)
2127
2128   i_tags_set(&img->tags, "i_comment", -1);
2129
2130 Sets the given tag to the string I<data>
2131
2132 If size is -1 then the strlen(I<data>) bytes are stored.
2133
2134 Even on failure, if an existing tag I<name> exists, it will be
2135 removed.
2136
2137
2138 =for comment
2139 From: File tags.c
2140
2141 =item i_tags_set_color(tags, name, code, &value)
2142
2143
2144 Stores the given color as a tag with the given name and code.
2145
2146
2147 =for comment
2148 From: File tags.c
2149
2150 =item i_tags_set_float(tags, name, code, value)
2151
2152
2153 Equivalent to i_tags_set_float2(tags, name, code, value, 30).
2154
2155
2156 =for comment
2157 From: File tags.c
2158
2159 =item i_tags_set_float2(tags, name, code, value, places)
2160
2161
2162 Sets the tag with the given name and code to the given floating point
2163 value.
2164
2165 Since tags are strings or ints, we convert the value to a string before
2166 storage at the precision specified by C<places>.
2167
2168
2169 =for comment
2170 From: File tags.c
2171
2172 =item i_tags_setn(C<tags>, C<name>, C<idata>)
2173
2174   i_tags_setn(&img->tags, "i_xres", 204);
2175   i_tags_setn(&img->tags, "i_yres", 196);
2176
2177 Sets the given tag to the integer C<idata>
2178
2179 Even on failure, if an existing tag C<name> exists, it will be
2180 removed.
2181
2182
2183 =for comment
2184 From: File tags.c
2185
2186
2187 =back
2188
2189 =head2 Uncategorized functions
2190
2191 =over
2192
2193 =item i_utf8_advance(char **p, size_t *len)
2194
2195 Retrieve a C<UTF-8> character from the stream.
2196
2197 Modifies *p and *len to indicate the consumed characters.
2198
2199 This doesn't support the extended C<UTF-8> encoding used by later
2200 versions of Perl.  Since this is typically used to implement text
2201 output by font drivers, the strings supplied shouldn't have such out
2202 of range characters.
2203
2204 This doesn't check that the C<UTF-8> character is using the shortest
2205 possible representation.
2206
2207 Returns ~0UL on failure.
2208
2209
2210 =for comment
2211 From: File io.c
2212
2213 =item im_errors(ctx)
2214
2215   i_errmsg *errors = im_errors(aIMCTX);
2216   i_errmsg *errors = i_errors();
2217
2218 Returns a pointer to the first element of an array of error messages,
2219 terminated by a NULL pointer.  The highest level message is first.
2220
2221 Also callable as C<i_errors()>.
2222
2223
2224 =for comment
2225 From: File error.c
2226
2227 =item im_get_context()
2228
2229 Retrieve the context object for the current thread.
2230
2231 Inside Imager itself this is just a function pointer, which the
2232 F<Imager.xs> BOOT handler initializes for use within perl.  If you're
2233 taking the Imager code and embedding it elsewhere you need to
2234 initialize the C<im_get_context> pointer at some point.
2235
2236
2237 =for comment
2238 From: File imext.c
2239
2240
2241
2242 =back
2243
2244
2245 =head1 UNDOCUMENTED
2246
2247 The following API functions are undocumented so far, hopefully this
2248 will change:
2249
2250 =over
2251
2252 =item *
2253
2254 B<im_context_refdec>
2255
2256 =item *
2257
2258 B<im_context_refinc>
2259
2260 =item *
2261
2262 B<im_lhead>
2263
2264 =item *
2265
2266 B<im_loog>
2267
2268 =item *
2269
2270 B<mm_log>
2271
2272
2273
2274 =back
2275
2276
2277 =head1 AUTHOR
2278
2279 Tony Cook <tonyc@cpan.org>
2280
2281 =head1 SEE ALSO
2282
2283 Imager, Imager::API, Imager::ExtUtils, Imager::Inline
2284
2285 =cut