320f0648593a09eacb5cb0a1cd14ce2f47b48bc5
[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   # Data Types
18   i_img *img;
19   i_color black;
20   black.rgba.r = black.rgba.g = black.rgba.b = black.rgba.a = 0;
21   i_fill_t *fill;
22   i_img_dim x;
23
24   # 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
38   # 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
44   # 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
49   # 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
59   # Image
60
61   # 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
70   # Image Implementation
71
72   # 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
80   # Image quantization
81
82   # Logging
83
84   # Paletted images
85
86   # 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
91 =head1 DESCRIPTION
92
93 =head2 Data Types
94
95 =over
96
97 =item i_img
98
99 This is Imager's image type.
100
101 It contains the following members:
102
103 =over
104
105 =item *
106
107 channels - the number of channels in the image
108
109 =item *
110
111 xsize, ysize - the width and height of the image in pixels
112
113 =item *
114
115 bytes - the number of bytes used to store the image data.  Undefined
116 where virtual is non-zero.
117
118 =item *
119
120 ch_mask - a mask of writable channels.  eg. if this is 6 then only
121 channels 1 and 2 are writable.  There may be bits set for which there
122 are no channels in the image.
123
124 =item *
125
126 bits - the number of bits stored per sample.  Should be one of
127 i_8_bits, i_16_bits, i_double_bits.
128
129 =item *
130
131 type - either i_direct_type for direct color images, or i_palette_type
132 for paletted images.
133
134 =item *
135
136 virtual - if zero then this image is-self contained.  If non-zero then
137 this image could be an interface to some other implementation.
138
139 =item *
140
141 idata - the image data.  This should not be directly accessed.  A new
142 image implementation can use this to store its image data.
143 i_img_destroy() will myfree() this pointer if it's non-null.
144
145 =item *
146
147 tags - a structure storing the image's tags.  This should only be
148 accessed via the i_tags_*() functions.
149
150 =item *
151
152 ext_data - a pointer for use internal to an image implementation.
153 This should be freed by the image's destroy handler.
154
155 =item *
156
157 im_data - data internal to Imager.  This is initialized by
158 i_img_init().
159
160 =item *
161
162 i_f_ppix, i_f_ppixf, i_f_plin, i_f_plinf, i_f_gpix, i_f_gpixf,
163 i_f_glin, i_f_glinf, i_f_gsamp, i_f_gampf - implementations for each
164 of the required image functions.  An image implementation should
165 initialize these between calling i_img_alloc() and i_img_init().
166
167 =item *
168
169 i_f_gpal, i_f_ppal, i_f_addcolors, i_f_getcolors, i_f_colorcount,
170 i_f_maxcolors, i_f_findcolor, i_f_setcolors - implementations for each
171 paletted image function.
172
173 =item *
174
175 i_f_destroy - custom image destruction function.  This should be used
176 to release memory if necessary.
177
178 =item *
179
180 i_f_gsamp_bits - implements i_gsamp_bits() for this image.
181
182 =item *
183
184 i_f_psamp_bits - implements i_psamp_bits() for this image.
185
186 =back
187
188
189 =for comment
190 From: File imdatatypes.h
191
192 =item i_color
193
194 Type for 8-bit/sample color.
195
196 Samples as per;
197
198   i_color c;
199
200 i_color is a union of:
201
202 =over
203
204 =item *
205
206 gray - contains a single element gray_color, eg. c.gray.gray_color
207
208 =item *
209
210 rgb - contains three elements r, g, b, eg. c.rgb.r
211
212 =item *
213
214 rgba - contains four elements r, g, b, a, eg. c.rgba.a
215
216 =item *
217
218 cmyk - contains four elements c, m, y, k, eg. C<c.cmyk.y>.  Note that
219 Imager never uses CMYK colors except when reading/writing files.
220
221 =item *
222
223 channels - an array of four channels, eg C<c.channels[2]>.
224
225 =back
226
227
228 =for comment
229 From: File imdatatypes.h
230
231 =item i_fcolor
232
233 This is the double/sample color type.
234
235 Its layout exactly corresponds to i_color.
236
237
238 =for comment
239 From: File imdatatypes.h
240
241 =item i_fill_t
242
243 This is the "abstract" base type for Imager's fill types.
244
245 Unless you're implementing a new fill type you'll typically treat this
246 as an opaque type.
247
248
249 =for comment
250 From: File imdatatypes.h
251
252 =item i_img_dim
253
254 A signed integer type that represents an image dimension or ordinate.
255
256 May be larger than int on some platforms.
257
258
259 =for comment
260 From: File imdatatypes.h
261
262
263 =back
264
265 =head2 Drawing
266
267 =over
268
269 =item i_arc(im, x, y, rad, d1, d2, color)
270
271
272 Fills an arc centered at (x,y) with radius I<rad> covering the range
273 of angles in degrees from d1 to d2, with the color.
274
275
276 =for comment
277 From: File draw.c
278
279 =item i_arc_aa(im, x, y, rad, d1, d2, color)
280
281
282 Antialias fills an arc centered at (x,y) with radius I<rad> covering
283 the range of angles in degrees from d1 to d2, with the color.
284
285
286 =for comment
287 From: File draw.c
288
289 =item i_arc_aa_cfill(im, x, y, rad, d1, d2, fill)
290
291
292 Antialias fills an arc centered at (x,y) with radius I<rad> covering
293 the range of angles in degrees from d1 to d2, with the fill object.
294
295
296 =for comment
297 From: File draw.c
298
299 =item i_arc_cfill(im, x, y, rad, d1, d2, fill)
300
301
302 Fills an arc centered at (x,y) with radius I<rad> covering the range
303 of angles in degrees from d1 to d2, with the fill object.
304
305
306 =for comment
307 From: File draw.c
308
309 =item i_box(im, x1, y1, x2, y2, color)
310
311
312 Outlines the box from (x1,y1) to (x2,y2) inclusive with I<color>.
313
314
315 =for comment
316 From: File draw.c
317
318 =item i_box_cfill(im, x1, y1, x2, y2, fill)
319
320
321 Fills the box from (x1,y1) to (x2,y2) inclusive with fill.
322
323
324 =for comment
325 From: File draw.c
326
327 =item i_box_filled(im, x1, y1, x2, y2, color)
328
329
330 Fills the box from (x1,y1) to (x2,y2) inclusive with color.
331
332
333 =for comment
334 From: File draw.c
335
336 =item i_circle_aa(im, x, y, rad, color)
337
338
339 Antialias fills a circle centered at (x,y) for radius I<rad> with
340 color.
341
342
343 =for comment
344 From: File draw.c
345
346 =item i_flood_cfill(im, seedx, seedy, fill)
347
348
349 Flood fills the 4-connected region starting from the point (seedx,
350 seedy) with I<fill>.
351
352 Returns false if (seedx, seedy) are outside the image.
353
354
355 =for comment
356 From: File draw.c
357
358 =item i_flood_cfill_border(im, seedx, seedy, fill, border)
359
360
361 Flood fills the 4-connected region starting from the point (seedx,
362 seedy) with I<fill>, the fill stops when it reaches pixels of color
363 I<border>.
364
365 Returns false if (seedx, seedy) are outside the image.
366
367
368 =for comment
369 From: File draw.c
370
371 =item i_flood_fill(im, seedx, seedy, color)
372
373
374 Flood fills the 4-connected region starting from the point (seedx,
375 seedy) with I<color>.
376
377 Returns false if (seedx, seedy) are outside the image.
378
379
380 =for comment
381 From: File draw.c
382
383 =item i_flood_fill_border(im, seedx, seedy, color, border)
384
385
386 Flood fills the 4-connected region starting from the point (seedx,
387 seedy) with I<color>, fill stops when the fill reaches a pixels with
388 color I<border>.
389
390 Returns false if (seedx, seedy) are outside the image.
391
392
393 =for comment
394 From: File draw.c
395
396 =item i_glin(im, l, r, y, colors)
397
398
399 Retrieves (r-l) pixels starting from (l,y) into I<colors>.
400
401 Returns the number of pixels retrieved.
402
403
404 =for comment
405 From: File imext.c
406
407 =item i_glinf(im, l, r, y, colors)
408
409
410 Retrieves (r-l) pixels starting from (l,y) into I<colors> as floating
411 point colors.
412
413 Returns the number of pixels retrieved.
414
415
416 =for comment
417 From: File imext.c
418
419 =item i_gpal(im, x, r, y, indexes)
420
421
422 Reads palette indexes for the horizontal line (x, y) to (r-1, y) into
423 indexes.
424
425 Returns the number of indexes read.
426
427 Always returns 0 for direct color images.
428
429
430 =for comment
431 From: File imext.c
432
433 =item i_gpix(im, x, y, color)
434
435
436 Retrieves the I<color> of the pixel (x,y).
437
438 Returns 0 if the pixel was retrieved, or -1 if not.
439
440
441 =for comment
442 From: File imext.c
443
444 =item i_gpixf(im, x, y, fcolor)
445
446
447 Retrieves the color of the pixel (x,y) as a floating point color into
448 I<fcolor>.
449
450 Returns 0 if the pixel was retrieved, or -1 if not.
451
452
453 =for comment
454 From: File imext.c
455
456 =item i_gsamp(im, l, r, y, samp, chans, chan_count)
457
458
459 Reads sample values from im for the horizontal line (l, y) to (r-1,y)
460 for the channels specified by chans, an array of int with chan_count
461 elements.
462
463 If chans is NULL then the first chan_count channels are retrieved for
464 each pixel.
465
466 Returns the number of samples read (which should be (r-l) *
467 chan_count)
468
469
470 =for comment
471 From: File imext.c
472
473 =item i_gsampf(im, l, r, y, samp, chans, chan_count)
474
475
476 Reads floating point sample values from im for the horizontal line (l,
477 y) to (r-1,y) for the channels specified by chans, an array of int
478 with chan_count elements.
479
480 If chans is NULL then the first chan_count channels are retrieved for
481 each pixel.
482
483 Returns the number of samples read (which should be (r-l) *
484 chan_count)
485
486
487 =for comment
488 From: File imext.c
489
490 =item i_line(im, x1, y1, x2, y2, val, endp)
491
492
493 Draw a line to image using bresenhams linedrawing algorithm
494
495    im   - image to draw to
496    x1   - starting x coordinate
497    y1   - starting x coordinate
498    x2   - starting x coordinate
499    y2   - starting x coordinate
500    val  - color to write to image
501    endp - endpoint flag (boolean)
502
503
504 =for comment
505 From: File draw.c
506
507 =item i_line_aa(im, x1, x2, y1, y2, color, endp)
508
509
510 Antialias draws a line from (x1,y1) to (x2, y2) in color.
511
512 The point (x2, y2) is drawn only if endp is set.
513
514
515 =for comment
516 From: File draw.c
517
518 =item i_plin(im, l, r, y, colors)
519
520
521 Sets (r-l) pixels starting from (l,y) using (r-l) values from
522 I<colors>.
523
524 Returns the number of pixels set.
525
526
527 =for comment
528 From: File imext.c
529
530 =item i_plinf(im, l, r, fcolors)
531
532
533 Sets (r-l) pixels starting from (l,y) using (r-l) floating point
534 colors from I<colors>.
535
536 Returns the number of pixels set.
537
538
539 =for comment
540 From: File imext.c
541
542 =item i_ppal(im, x, r, y, indexes)
543
544
545 Writes palette indexes for the horizontal line (x, y) to (r-1, y) from
546 indexes.
547
548 Returns the number of indexes written.
549
550 Always returns 0 for direct color images.
551
552
553 =for comment
554 From: File imext.c
555
556 =item i_ppix(im, x, y, color)
557
558
559 Sets the pixel at (x,y) to I<color>.
560
561 Returns 0 if the pixel was drawn, or -1 if not.
562
563 Does no alpha blending, just copies the channels from the supplied
564 color to the image.
565
566
567 =for comment
568 From: File imext.c
569
570 =item i_ppixf(im, x, y, fcolor)
571
572
573 Sets the pixel at (x,y) to the floating point color I<fcolor>.
574
575 Returns 0 if the pixel was drawn, or -1 if not.
576
577 Does no alpha blending, just copies the channels from the supplied
578 color to the image.
579
580
581 =for comment
582 From: File imext.c
583
584
585 =back
586
587 =head2 Error handling
588
589 =over
590
591 =item i_clear_error()
592
593 Clears the error stack.
594
595 Called by any imager function before doing any other processing.
596
597
598 =for comment
599 From: File error.c
600
601 =item i_push_error(int code, char const *msg)
602
603 Called by an Imager function to push an error message onto the stack.
604
605 No message is pushed if the stack is full (since this means someone
606 forgot to call i_clear_error(), or that a function that doesn't do
607 error handling is calling function that does.).
608
609
610 =for comment
611 From: File error.c
612
613 =item i_push_errorf(int code, char const *fmt, ...)
614
615 A version of i_push_error() that does printf() like formating.
616
617 Does not support perl specific format codes.
618
619
620 =for comment
621 From: File error.c
622
623 =item i_push_errorvf(int code, char const *fmt, va_list ap)
624
625
626 Intended for use by higher level functions, takes a varargs pointer
627 and a format to produce the finally pushed error message.
628
629 Does not support perl specific format codes.
630
631
632 =for comment
633 From: File error.c
634
635
636 =back
637
638 =head2 Files
639
640 =over
641
642 =item i_get_image_file_limits(&width, &height, &bytes)
643
644
645 Retrieves the file limits set by i_set_image_file_limits().
646
647
648 =for comment
649 From: File limits.c
650
651 =item i_int_check_image_file_limits(width, height, channels, sample_size)
652
653
654 Checks the size of a file in memory against the configured image file
655 limits.
656
657 This also range checks the values to those permitted by Imager and
658 checks for overflows in calculating the size.
659
660 Returns non-zero if the file is within limits.
661
662 This function is intended to be called by image file read functions.
663
664
665 =for comment
666 From: File limits.c
667
668 =item i_set_image_file_limits(width, height, bytes)
669
670
671 Set limits on the sizes of images read by Imager.
672
673 Setting a limit to 0 means that limit is ignored.
674
675 Negative limits result in failure.
676
677 Returns non-zero on success.
678
679
680 =for comment
681 From: File limits.c
682
683
684 =back
685
686 =head2 Fills
687
688 =over
689
690 =item i_new_fill_fount(xa, ya, xb, yb, type, repeat, combine, super_sample, ssample_param, count, segs)
691
692
693
694 Creates a new general fill which fills with a fountain fill.
695
696
697 =for comment
698 From: File filters.im
699
700 =item i_new_fill_hatch(fg, bg, combine, hatch, cust_hatch, dx, dy)
701
702
703 Creates a new hatched fill with the fg color used for the 1 bits in
704 the hatch and bg for the 0 bits.  If combine is non-zero alpha values
705 will be combined.
706
707 If cust_hatch is non-NULL it should be a pointer to 8 bytes of the
708 hash definition, with the high-bits to the left.
709
710 If cust_hatch is NULL then one of the standard hatches is used.
711
712 (dx, dy) are an offset into the hatch which can be used to unalign adjoining areas, or to align the origin of a hatch with the the side of a filled area.
713
714
715 =for comment
716 From: File fills.c
717
718 =item i_new_fill_hatchf(fg, bg, combine, hatch, cust_hatch, dx, dy)
719
720
721 Creates a new hatched fill with the fg color used for the 1 bits in
722 the hatch and bg for the 0 bits.  If combine is non-zero alpha values
723 will be combined.
724
725 If cust_hatch is non-NULL it should be a pointer to 8 bytes of the
726 hash definition, with the high-bits to the left.
727
728 If cust_hatch is NULL then one of the standard hatches is used.
729
730 (dx, dy) are an offset into the hatch which can be used to unalign adjoining areas, or to align the origin of a hatch with the the side of a filled area.
731
732
733 =for comment
734 From: File fills.c
735
736 =item i_new_fill_image(im, matrix, xoff, yoff, combine)
737
738
739 Create an image based fill.
740
741 matrix is an array of 9 doubles representing a transformation matrix.
742
743 xoff and yoff are the offset into the image to start filling from.
744
745
746 =for comment
747 From: File fills.c
748
749 =item i_new_fill_solid(color, combine)
750
751
752 Create a solid fill based on an 8-bit color.
753
754 If combine is non-zero then alpha values will be combined.
755
756
757 =for comment
758 From: File fills.c
759
760 =item i_new_fill_solidf(color, combine)
761
762
763 Create a solid fill based on a float color.
764
765 If combine is non-zero then alpha values will be combined.
766
767
768 =for comment
769 From: File fills.c
770
771 =item i_fill_destroy(fill)
772
773 Call to destroy any fill object.
774
775
776 =for comment
777 From: File fills.c
778
779
780 =back
781
782 =head2 Image
783
784 =over
785
786 =item i_copy(src)
787
788
789 Creates a new image that is a copy of src.
790
791 Tags are not copied, only the image data.
792
793 Returns: i_img *
794
795
796 =for comment
797 From: File image.c
798
799 =item i_copyto(dest, src, x1, y1, x2, y2, tx, ty)
800
801
802 Copies image data from the area (x1,y1)-[x2,y2] in the source image to
803 a rectangle the same size with it's top-left corner at (tx,ty) in the
804 destination image.
805
806 If x1 > x2 or y1 > y2 then the corresponding co-ordinates are swapped.
807
808
809 =for comment
810 From: File paste.im
811
812 =item i_copyto_trans(im, src, x1, y1, x2, y2, tx, ty, trans)
813
814
815 (x1,y1) (x2,y2) specifies the region to copy (in the source coordinates)
816 (tx,ty) specifies the upper left corner for the target image.
817 pass NULL in trans for non transparent i_colors.
818
819
820 =for comment
821 From: File image.c
822
823 =item i_img_info(im, info)
824
825
826 Return image information
827
828    im - Image pointer
829    info - pointer to array to return data
830
831 info is an array of 4 integers with the following values:
832
833  info[0] - width
834  info[1] - height
835  info[2] - channels
836  info[3] - channel mask
837
838
839 =for comment
840 From: File image.c
841
842 =item i_rubthru(im, src, tx, ty, src_minx, src_miny, src_maxx, src_maxy )
843
844
845 Takes the sub image I<src[src_minx, src_maxx)[src_miny, src_maxy)> and
846 overlays it at (I<tx>,I<ty>) on the image object.
847
848 The alpha channel of each pixel in I<src> is used to control how much
849 the existing colour in I<im> is replaced, if it is 255 then the colour
850 is completely replaced, if it is 0 then the original colour is left 
851 unmodified.
852
853
854 =for comment
855 From: File rubthru.im
856
857
858 =back
859
860 =head2 Image creation/destruction
861
862 =over
863
864 =item i_img_16_new(x, y, ch)
865
866
867 Create a new 16-bit/sample image.
868
869 Returns the image on success, or NULL on failure.
870
871
872 =for comment
873 From: File img16.c
874
875 =item i_img_8_new(x, y, ch)
876
877
878
879 Creates a new image object I<x> pixels wide, and I<y> pixels high with
880 I<ch> channels.
881
882
883 =for comment
884 From: File image.c
885
886 =item i_img_double_new(int x, int y, int ch)
887
888 Creates a new double per sample image.
889
890
891 =for comment
892 From: File imgdouble.c
893
894 =item i_img_pal_new(x, y, channels, maxpal)
895
896
897 Creates a new paletted image of the supplied dimensions.
898
899 I<maxpal> is the maximum palette size and should normally be 256.
900
901 Returns a new image or NULL on failure.
902
903
904 =for comment
905 From: File palimg.c
906
907 =item i_sametype(i_img *im, int xsize, int ysize)
908
909
910 Returns an image of the same type (sample size, channels, paletted/direct).
911
912 For paletted images the palette is copied from the source.
913
914
915 =for comment
916 From: File image.c
917
918 =item i_sametype_chans(i_img *im, int xsize, int ysize, int channels)
919
920
921 Returns an image of the same type (sample size).
922
923 For paletted images the equivalent direct type is returned.
924
925
926 =for comment
927 From: File image.c
928
929 =item i_img_destroy(img)
930
931 Destroy an image object
932
933
934 =for comment
935 From: File image.c
936
937
938 =back
939
940 =head2 Image Implementation
941
942 =over
943
944 =item i_img_alloc()
945
946 Allocates a new i_img structure.
947
948 When implementing a new image type perform the following steps in your
949 image object creation function:
950
951 =over
952
953 =item 1.
954
955 allocate the image with i_img_alloc().
956
957 =item 2.
958
959 initialize any function pointers or other data as needed, you can
960 overwrite the whole block if you need to.
961
962 =item 3.
963
964 initialize Imager's internal data by calling i_img_init() on the image
965 object.
966
967 =back
968
969
970 =for comment
971 From: File image.c
972
973 =item i_img_init(img)
974
975 Imager interal initialization of images.
976
977 Currently this does very little, in the future it may be used to
978 support threads, or color profiles.
979
980
981 =for comment
982 From: File image.c
983
984
985 =back
986
987 =head2 Image Information
988
989 =over
990
991 =item i_img_color_channels(im)
992
993
994 The number of channels holding color information.
995
996
997 =for comment
998 From: File immacros.h
999
1000 =item i_img_get_height(im)
1001
1002 Returns the height in pixels of the image.
1003
1004
1005 =for comment
1006 From: File image.c
1007
1008 =item i_img_get_width(im)
1009
1010 Returns the width in pixels of the image.
1011
1012
1013 =for comment
1014 From: File image.c
1015
1016 =item i_img_getchannels(im)
1017
1018 Get the number of channels in I<im>.
1019
1020
1021 =for comment
1022 From: File image.c
1023
1024 =item i_img_getmask(im)
1025
1026 Get the image channel mask for I<im>.
1027
1028
1029 =for comment
1030 From: File image.c
1031
1032 =item i_img_has_alpha(im)
1033
1034
1035 Return true if the image has an alpha channel.
1036
1037
1038 =for comment
1039 From: File immacros.h
1040
1041 =item i_img_setmask(im, ch_mask)
1042
1043 Set the image channel mask for I<im> to I<ch_mask>.
1044
1045 The image channel mask gives some control over which channels can be
1046 written to in the image.
1047
1048
1049 =for comment
1050 From: File image.c
1051
1052
1053 =back
1054
1055 =head2 Image quantization
1056
1057 =over
1058
1059 =item i_quant_makemap(quant, imgs, count)
1060
1061
1062 Analyzes the I<count> images in I<imgs> according to the rules in
1063 I<quant> to build a color map (optimal or not depending on
1064 quant->make_colors).
1065
1066
1067 =for comment
1068 From: File quant.c
1069
1070 =item i_quant_translate(quant, img)
1071
1072
1073 Quantize the image given the palette in quant.
1074
1075 On success returns a pointer to a memory block of img->xsize *
1076 img->ysize i_palidx entries.
1077
1078 On failure returns NULL.
1079
1080 You should call myfree() on the returned block when you're done with
1081 it.
1082
1083 This function will fail if the supplied palette contains no colors.
1084
1085
1086 =for comment
1087 From: File quant.c
1088
1089 =item i_quant_transparent(quant, data, img, trans_index)
1090
1091
1092 Dither the alpha channel on I<img> into the palette indexes in
1093 I<data>.  Pixels to be transparent are replaced with I<trans_pixel>.
1094
1095 The method used depends on the tr_* members of quant.
1096
1097
1098 =for comment
1099 From: File quant.c
1100
1101
1102 =back
1103
1104 =head2 Logging
1105
1106 =over
1107
1108 =item i_lhead(file, line)
1109
1110 This is an internal function called by the mm_log() macro.
1111
1112
1113 =for comment
1114 From: File log.c
1115
1116 =item i_loog(level, format, ...)
1117
1118 This is an internal function called by the mm_log() macro.
1119
1120
1121 =for comment
1122 From: File log.c
1123
1124 =item mm_log((level, format, ...))
1125
1126 This is the main entry point to logging. Note that the extra set of
1127 parentheses are required due to limitations in C89 macros.
1128
1129 This will format a string with the current file and line number to the
1130 log file if logging is enabled.
1131
1132
1133 =for comment
1134 From: File log.h
1135
1136
1137 =back
1138
1139 =head2 Paletted images
1140
1141 =over
1142
1143 =item i_addcolors(im, colors, count)
1144
1145
1146 Adds colors to the image's palette.
1147
1148 On success returns the index of the lowest color added.
1149
1150 On failure returns -1.
1151
1152 Always fails for direct color images.
1153
1154
1155 =for comment
1156 From: File imext.c
1157
1158 =item i_colorcount(im)
1159
1160
1161 Returns the number of colors in the image's palette.
1162
1163 Returns -1 for direct images.
1164
1165
1166 =for comment
1167 From: File imext.c
1168
1169 =item i_findcolor(im, color, &entry)
1170
1171
1172 Searches the images palette for the given color.
1173
1174 On success sets *I<entry> to the index of the color, and returns true.
1175
1176 On failure returns false.
1177
1178 Always fails on direct color images.
1179
1180
1181 =for comment
1182 From: File imext.c
1183
1184 =item i_getcolors(im, index, colors, count)
1185
1186
1187 Retrieves I<count> colors starting from I<index> in the image's
1188 palette.
1189
1190 On success stores the colors into I<colors> and returns true.
1191
1192 On failure returns false.
1193
1194 Always fails for direct color images.
1195
1196 Fails if there are less than I<index>+I<count> colors in the image's
1197 palette.
1198
1199
1200 =for comment
1201 From: File imext.c
1202
1203 =item i_maxcolors(im)
1204
1205
1206 Returns the maximum number of colors the palette can hold for the
1207 image.
1208
1209 Returns -1 for direct color images.
1210
1211
1212 =for comment
1213 From: File imext.c
1214
1215 =item i_setcolors(im, index, colors, count)
1216
1217
1218 Sets I<count> colors starting from I<index> in the image's palette.
1219
1220 On sucess returns true.
1221
1222 On failure returns false.
1223
1224 The image must have at least I<index>+I<count> colors in it's palette
1225 for this to succeed.
1226
1227 Always fails on direct color images.
1228
1229
1230 =for comment
1231 From: File imext.c
1232
1233
1234 =back
1235
1236 =head2 Tags
1237
1238 =over
1239
1240 =item i_tags_delbycode(tags, code)
1241
1242
1243 Delete any tags with the given code.
1244
1245 Returns the number of tags deleted.
1246
1247
1248 =for comment
1249 From: File tags.c
1250
1251 =item i_tags_delbyname(tags, name)
1252
1253
1254 Delete any tags with the given name.
1255
1256 Returns the number of tags deleted.
1257
1258
1259 =for comment
1260 From: File tags.c
1261
1262 =item i_tags_delete(tags, index)
1263
1264
1265 Delete a tag by index.
1266
1267 Returns true on success.
1268
1269
1270 =for comment
1271 From: File tags.c
1272
1273 =item i_tags_destroy(tags)
1274
1275
1276 Destroys the given tags structure.  Called by i_img_destroy().
1277
1278
1279 =for comment
1280 From: File tags.c
1281
1282 =item i_tags_find(tags, name, start, &entry)
1283
1284
1285 Searchs for a tag of the given I<name> starting from index I<start>.
1286
1287 On success returns true and sets *I<entry>.
1288
1289 On failure returns false.
1290
1291
1292 =for comment
1293 From: File tags.c
1294
1295 =item i_tags_findn(tags, code, start, &entry)
1296
1297
1298 Searchs for a tag of the given I<code> starting from index I<start>.
1299
1300 On success returns true and sets *I<entry>.
1301
1302 On failure returns false.
1303
1304
1305 =for comment
1306 From: File tags.c
1307
1308 =item i_tags_get_color(tags, name, code, &value)
1309
1310
1311 Retrieve a tag specified by name or code as color.
1312
1313 On success sets the i_color *I<value> to the color and returns true.
1314
1315 On failure returns false.
1316
1317
1318 =for comment
1319 From: File tags.c
1320
1321 =item i_tags_get_float(tags, name, code, value)
1322
1323
1324 Retrieves a tag as a floating point value.  
1325
1326 If the tag has a string value then that is parsed as a floating point
1327 number, otherwise the integer value of the tag is used.
1328
1329 On success sets *I<value> and returns true.
1330
1331 On failure returns false.
1332
1333
1334 =for comment
1335 From: File tags.c
1336
1337 =item i_tags_get_int(tags, name, code, &value)
1338
1339
1340 Retrieve a tag specified by name or code as an integer.
1341
1342 On success sets the int *I<value> to the integer and returns true.
1343
1344 On failure returns false.
1345
1346
1347 =for comment
1348 From: File tags.c
1349
1350 =item i_tags_get_string(tags, name, code, value, value_size)
1351
1352
1353 Retrieves a tag by name or code as a string.
1354
1355 On success copies the string to value for a max of value_size and
1356 returns true.
1357
1358 On failure returns false.
1359
1360 value_size must be at least large enough for a string representation
1361 of an integer.
1362
1363 The copied value is always NUL terminated.
1364
1365
1366 =for comment
1367 From: File tags.c
1368
1369 =item i_tags_new(i_img_tags *tags)
1370
1371
1372 Initialize a tags structure.  Should not be used if the tags structure
1373 has been previously used.
1374
1375 This should be called tags member of an i_img object on creation (in
1376 i_img_*_new() functions).
1377
1378 To destroy the contents use i_tags_destroy()
1379
1380
1381 =for comment
1382 From: File tags.c
1383
1384 =item i_tags_set(tags, name, data, size)
1385
1386 Sets the given tag to the string I<data>
1387
1388 If size is -1 then the strlen(I<data>) bytes are stored.
1389
1390 Even on failure, if an existing tag I<name> exists, it will be
1391 removed.
1392
1393
1394 =for comment
1395 From: File tags.c
1396
1397 =item i_tags_set_color(tags, name, code, &value)
1398
1399
1400 Stores the given color as a tag with the given name and code.
1401
1402
1403 =for comment
1404 From: File tags.c
1405
1406 =item i_tags_set_float(tags, name, code, value)
1407
1408
1409 Equivalent to i_tags_set_float2(tags, name, code, value, 30).
1410
1411
1412 =for comment
1413 From: File tags.c
1414
1415 =item i_tags_set_float2(tags, name, code, value, places)
1416
1417
1418 Sets the tag with the given name and code to the given floating point
1419 value.
1420
1421 Since tags are strings or ints, we convert the value to a string before
1422 storage at the precision specified by C<places>.
1423
1424
1425 =for comment
1426 From: File tags.c
1427
1428 =item i_tags_setn(tags, name, idata)
1429
1430 Sets the given tag to the integer I<idata>
1431
1432 Even on failure, if an existing tag I<name> exists, it will be
1433 removed.
1434
1435
1436 =for comment
1437 From: File tags.c
1438
1439
1440 =back
1441
1442
1443 =head1 AUTHOR
1444
1445 Tony Cook <tony@imager.perl.org>
1446
1447 =head1 SEE ALSO
1448
1449 Imager, Imager::ExtUtils, Imager::Inline
1450
1451 =cut