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