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