e92e4c49db8afd8a93003675003721f827e80a94
[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   i_fill_t *fill = i_new_fill_...(...);
16
17
18   # Drawing
19   i_arc(im, 50, 50, 20, 45, 135, &color);
20   i_arc_aa(im, 50, 50, 35, 90, 135, &color);
21   i_arc_aa_cfill(im, 50, 50, 35, 90, 135, fill);
22   i_arc_cfill(im, 50, 50, 35, 90, 135, fill);
23   i_box(im, 0, 0, im->xsize-1, im->ysize-1, &color).
24   i_box_cfill(im, 0, 0, im->xsize-1, im->ysize-1, fill);
25   i_box_filled(im, 0, 0, im->xsize-1, im->ysize-1, &color);
26   i_circle_aa(im, 50, 50, 45, &color);
27   i_flood_cfill(im, 50, 50, fill);
28   i_flood_cfill_border(im, 50, 50, fill, border);
29   i_flood_fill(im, 50, 50, &color);
30   i_flood_fill_border(im, 50, 50, &color, &border);
31
32   # Error handling
33
34   # Files
35   i_get_image_file_limits(&width, &height, &bytes)
36   i_i_int_check_image_file_limits(width, height, channels, sizeof(i_sample_t))
37   i_set_image_file_limits(500, 500, 1000000);
38
39   # Fills
40   fill = i_new_fill_fount(0, 0, 100, 100, i_ft_linear, i_ft_linear, 
41                           i_fr_triangle, 0, i_fts_grid, 9, 1, segs);
42
43   # Image
44
45   # Image creation
46
47   # Image quantization
48
49   # Paletted images
50
51   # Tags
52
53    i_fill_destroy(fill);
54
55 =head1 DESCRIPTION
56
57 =head2 Drawing
58
59 =over
60
61 =item i_arc(im, x, y, rad, d1, d2, color)
62
63
64 Fills an arc centered at (x,y) with radius I<rad> covering the range
65 of angles in degrees from d1 to d2, with the color.
66
67
68 =for comment
69 From: File draw.c
70
71 =item i_arc_aa(im, x, y, rad, d1, d2, color)
72
73
74 Antialias fills an arc centered at (x,y) with radius I<rad> covering
75 the range of angles in degrees from d1 to d2, with the color.
76
77
78 =for comment
79 From: File draw.c
80
81 =item i_arc_aa_cfill(im, x, y, rad, d1, d2, fill)
82
83
84 Antialias fills an arc centered at (x,y) with radius I<rad> covering
85 the range of angles in degrees from d1 to d2, with the fill object.
86
87
88 =for comment
89 From: File draw.c
90
91 =item i_arc_cfill(im, x, y, rad, d1, d2, fill)
92
93
94 Fills an arc centered at (x,y) with radius I<rad> covering the range
95 of angles in degrees from d1 to d2, with the fill object.
96
97
98 =for comment
99 From: File draw.c
100
101 =item i_box(im, x1, y1, x2, y2, color)
102
103
104 Outlines the box from (x1,y1) to (x2,y2) inclusive with I<color>.
105
106
107 =for comment
108 From: File draw.c
109
110 =item i_box_cfill(im, x1, y1, x2, y2, fill)
111
112
113 Fills the box from (x1,y1) to (x2,y2) inclusive with fill.
114
115
116 =for comment
117 From: File draw.c
118
119 =item i_box_filled(im, x1, y1, x2, y2, color)
120
121
122 Fills the box from (x1,y1) to (x2,y2) inclusive with color.
123
124
125 =for comment
126 From: File draw.c
127
128 =item i_circle_aa(im, x, y, rad, color)
129
130
131 Antialias fills a circle centered at (x,y) for radius I<rad> with
132 color.
133
134
135 =for comment
136 From: File draw.c
137
138 =item i_flood_cfill(im, seedx, seedy, fill)
139
140
141 Flood fills the 4-connected region starting from the point (seedx,
142 seedy) with I<fill>.
143
144 Returns false if (seedx, seedy) are outside the image.
145
146
147 =for comment
148 From: File draw.c
149
150 =item i_flood_cfill_border(im, seedx, seedy, fill, border)
151
152
153 Flood fills the 4-connected region starting from the point (seedx,
154 seedy) with I<fill>, the fill stops when it reaches pixels of color
155 I<border>.
156
157 Returns false if (seedx, seedy) are outside the image.
158
159
160 =for comment
161 From: File draw.c
162
163 =item i_flood_fill(im, seedx, seedy, color)
164
165
166 Flood fills the 4-connected region starting from the point (seedx,
167 seedy) with I<color>.
168
169 Returns false if (seedx, seedy) are outside the image.
170
171
172 =for comment
173 From: File draw.c
174
175 =item i_flood_fill_border(im, seedx, seedy, color, border)
176
177
178 Flood fills the 4-connected region starting from the point (seedx,
179 seedy) with I<color>, fill stops when the fill reaches a pixels with
180 color I<border>.
181
182 Returns false if (seedx, seedy) are outside the image.
183
184
185 =for comment
186 From: File draw.c
187
188 =item i_glin(im, l, r, y, colors)
189
190
191 Retrieves (r-l) pixels starting from (l,y) into I<colors>.
192
193 Returns the number of pixels retrieved.
194
195
196 =for comment
197 From: File imext.c
198
199 =item i_glinf(im, l, r, y, colors)
200
201
202 Retrieves (r-l) pixels starting from (l,y) into I<colors> as floating
203 point colors.
204
205 Returns the number of pixels retrieved.
206
207
208 =for comment
209 From: File imext.c
210
211 =item i_gpal(im, x, r, y, indexes)
212
213
214 Reads palette indexes for the horizontal line (x, y) to (r-1, y) into
215 indexes.
216
217 Returns the number of indexes read.
218
219 Always returns 0 for direct color images.
220
221
222 =for comment
223 From: File imext.c
224
225 =item i_gpix(im, x, y, color)
226
227
228 Retrieves the I<color> of the pixel (x,y).
229
230 Returns 0 if the pixel was retrieved, or -1 if not.
231
232
233 =for comment
234 From: File imext.c
235
236 =item i_gpixf(im, x, y, fcolor)
237
238
239 Retrieves the color of the pixel (x,y) as a floating point color into
240 I<fcolor>.
241
242 Returns 0 if the pixel was retrieved, or -1 if not.
243
244
245 =for comment
246 From: File imext.c
247
248 =item i_gsamp(im, l, r, y, samp, chans, chan_count)
249
250
251 Reads sample values from im for the horizontal line (l, y) to (r-1,y)
252 for the channels specified by chans, an array of int with chan_count
253 elements.
254
255 If chans is NULL then the first chan_count channels are retrieved for
256 each pixel.
257
258 Returns the number of samples read (which should be (r-l) *
259 chan_count)
260
261
262 =for comment
263 From: File imext.c
264
265 =item i_gsampf(im, l, r, y, samp, chans, chan_count)
266
267
268 Reads floating point sample values from im for the horizontal line (l,
269 y) to (r-1,y) for the channels specified by chans, an array of int
270 with chan_count elements.
271
272 If chans is NULL then the first chan_count channels are retrieved for
273 each pixel.
274
275 Returns the number of samples read (which should be (r-l) *
276 chan_count)
277
278
279 =for comment
280 From: File imext.c
281
282 =item i_line(im, x1, y1, x2, y2, val, endp)
283
284
285 Draw a line to image using bresenhams linedrawing algorithm
286
287    im   - image to draw to
288    x1   - starting x coordinate
289    y1   - starting x coordinate
290    x2   - starting x coordinate
291    y2   - starting x coordinate
292    val  - color to write to image
293    endp - endpoint flag (boolean)
294
295
296 =for comment
297 From: File draw.c
298
299 =item i_line_aa(im, x1, x2, y1, y2, color, endp)
300
301
302 Antialias draws a line from (x1,y1) to (x2, y2) in color.
303
304 The point (x2, y2) is drawn only if endp is set.
305
306
307 =for comment
308 From: File draw.c
309
310 =item i_plin(im, l, r, y, colors)
311
312
313 Sets (r-l) pixels starting from (l,y) using (r-l) values from
314 I<colors>.
315
316 Returns the number of pixels set.
317
318
319 =for comment
320 From: File imext.c
321
322 =item i_plinf(im, l, r, fcolors)
323
324
325 Sets (r-l) pixels starting from (l,y) using (r-l) floating point
326 colors from I<colors>.
327
328 Returns the number of pixels set.
329
330
331 =for comment
332 From: File imext.c
333
334 =item i_ppal(im, x, r, y, indexes)
335
336
337 Writes palette indexes for the horizontal line (x, y) to (r-1, y) from
338 indexes.
339
340 Returns the number of indexes written.
341
342 Always returns 0 for direct color images.
343
344
345 =for comment
346 From: File imext.c
347
348 =item i_ppix(im, x, y, color)
349
350
351 Sets the pixel at (x,y) to I<color>.
352
353 Returns 0 if the pixel was drawn, or -1 if not.
354
355 Does no alpha blending, just copies the channels from the supplied
356 color to the image.
357
358
359 =for comment
360 From: File imext.c
361
362 =item i_ppixf(im, x, y, fcolor)
363
364
365 Sets the pixel at (x,y) to the floating point color I<fcolor>.
366
367 Returns 0 if the pixel was drawn, or -1 if not.
368
369 Does no alpha blending, just copies the channels from the supplied
370 color to the image.
371
372
373 =for comment
374 From: File imext.c
375
376
377 =back
378
379 =head2 Error handling
380
381 =over
382
383 =item i_clear_error()
384
385
386 Clears the error stack.
387
388 Called by any imager function before doing any other processing.
389
390
391 =for comment
392 From: File error.c
393
394 =item i_push_error(int code, char const *msg)
395
396
397 Called by an imager function to push an error message onto the stack.
398
399 No message is pushed if the stack is full (since this means someone
400 forgot to call i_clear_error(), or that a function that doesn't do
401 error handling is calling function that does.).
402
403
404 =for comment
405 From: File error.c
406
407 =item i_push_errorf(int code, char const *fmt, ...)
408
409
410 A version of i_push_error() that does printf() like formating.
411
412
413 =for comment
414 From: File error.c
415
416 =item i_push_errorvf(int code, char const *fmt, va_list ap)
417
418
419 Intended for use by higher level functions, takes a varargs pointer
420 and a format to produce the finally pushed error message.
421
422
423 =for comment
424 From: File error.c
425
426
427 =back
428
429 =head2 Files
430
431 =over
432
433 =item i_get_image_file_limits(&width, &height, &bytes)
434
435
436 Retrieves the file limits set by i_set_image_file_limits().
437
438
439 =for comment
440 From: File limits.c
441
442 =item i_int_check_image_file_limits(width, height, channels, sample_size)
443
444
445 Checks the size of a file in memory against the configured image file
446 limits.
447
448 This also range checks the values to those permitted by Imager and
449 checks for overflows in calculating the size.
450
451 Returns non-zero if the file is within limits.
452
453 This function is intended to be called by image file read functions.
454
455
456 =for comment
457 From: File limits.c
458
459 =item i_set_image_file_limits(width, height, bytes)
460
461
462 Set limits on the sizes of images read by Imager.
463
464 Setting a limit to 0 means that limit is ignored.
465
466 Negative limits result in failure.
467
468 Returns non-zero on success.
469
470
471 =for comment
472 From: File limits.c
473
474
475 =back
476
477 =head2 Fills
478
479 =over
480
481 =item i_fill_destroy(fill)
482
483
484 Call to destroy any fill object.
485
486
487 =for comment
488 From: File fills.c
489
490 =item i_new_fill_fount(xa, ya, xb, yb, type, repeat, combine, super_sample, ssample_param, count, segs)
491
492
493
494 Creates a new general fill which fills with a fountain fill.
495
496
497 =for comment
498 From: File filters.c
499
500 =item i_new_fill_hatch(fg, bg, combine, hatch, cust_hatch, dx, dy)
501
502
503 Creates a new hatched fill with the fg color used for the 1 bits in
504 the hatch and bg for the 0 bits.  If combine is non-zero alpha values
505 will be combined.
506
507 If cust_hatch is non-NULL it should be a pointer to 8 bytes of the
508 hash definition, with the high-bits to the left.
509
510 If cust_hatch is NULL then one of the standard hatches is used.
511
512 (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.
513
514
515 =for comment
516 From: File fills.c
517
518 =item i_new_fill_hatchf(fg, bg, combine, hatch, cust_hatch, dx, dy)
519
520
521 Creates a new hatched fill with the fg color used for the 1 bits in
522 the hatch and bg for the 0 bits.  If combine is non-zero alpha values
523 will be combined.
524
525 If cust_hatch is non-NULL it should be a pointer to 8 bytes of the
526 hash definition, with the high-bits to the left.
527
528 If cust_hatch is NULL then one of the standard hatches is used.
529
530 (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.
531
532
533 =for comment
534 From: File fills.c
535
536 =item i_new_fill_image(im, matrix, xoff, yoff, combine)
537
538
539 Create an image based fill.
540
541 matrix is an array of 9 doubles representing a transformation matrix.
542
543 xoff and yoff are the offset into the image to start filling from.
544
545
546 =for comment
547 From: File fills.c
548
549 =item i_new_fill_solid(color, combine)
550
551
552 Create a solid fill based on an 8-bit color.
553
554 If combine is non-zero then alpha values will be combined.
555
556
557 =for comment
558 From: File fills.c
559
560 =item i_new_fill_solidf(color, combine)
561
562
563 Create a solid fill based on a float color.
564
565 If combine is non-zero then alpha values will be combined.
566
567
568 =for comment
569 From: File fills.c
570
571
572 =back
573
574 =head2 Image
575
576 =over
577
578 =item i_copy(src)
579
580
581 Creates a new image that is a copy of src.
582
583 Tags are not copied, only the image data.
584
585 Returns: i_img *
586
587
588 =for comment
589 From: File image.c
590
591 =item i_copyto(dest, src, x1, y1, x2, y2, tx, ty)
592
593
594 Copies image data from the area (x1,y1)-[x2,y2] in the source image to
595 a rectangle the same size with it's top-left corner at (tx,ty) in the
596 destination image.
597
598 If x1 > x2 or y1 > y2 then the corresponding co-ordinates are swapped.
599
600
601 =for comment
602 From: File image.c
603
604 =item i_copyto_trans(im, src, x1, y1, x2, y2, tx, ty, trans)
605
606
607 (x1,y1) (x2,y2) specifies the region to copy (in the source coordinates)
608 (tx,ty) specifies the upper left corner for the target image.
609 pass NULL in trans for non transparent i_colors.
610
611
612 =for comment
613 From: File image.c
614
615 =item i_img_destroy(im)
616
617
618 Destroy image and free data via exorcise.
619
620    im - Image pointer
621
622
623 =for comment
624 From: File image.c
625
626 =item i_img_info(im, info)
627
628
629 Return image information
630
631    im - Image pointer
632    info - pointer to array to return data
633
634 info is an array of 4 integers with the following values:
635
636  info[0] - width
637  info[1] - height
638  info[2] - channels
639  info[3] - channel mask
640
641
642 =for comment
643 From: File image.c
644
645 =item i_rubthru(im, src, tx, ty, src_minx, src_miny, src_maxx, src_maxy )
646
647
648 Takes the sub image I<src[src_minx, src_maxx)[src_miny, src_maxy)> and
649 overlays it at (I<tx>,I<ty>) on the image object.
650
651 The alpha channel of each pixel in I<src> is used to control how much
652 the existing colour in I<im> is replaced, if it is 255 then the colour
653 is completely replaced, if it is 0 then the original colour is left 
654 unmodified.
655
656
657 =for comment
658 From: File image.c
659
660
661 =back
662
663 =head2 Image creation
664
665 =over
666
667 =item i_img_16_new(x, y, ch)
668
669
670 Create a new 16-bit/sample image.
671
672 Returns the image on success, or NULL on failure.
673
674
675 =for comment
676 From: File img16.c
677
678 =item i_img_8_new(x, y, ch)
679
680
681 Creates a new image object I<x> pixels wide, and I<y> pixels high with
682 I<ch> channels.
683
684
685 =for comment
686 From: File image.c
687
688 =item i_img_double_new(int x, int y, int ch)
689
690
691 Creates a new double per sample image.
692
693
694 =for comment
695 From: File imgdouble.c
696
697 =item i_img_pal_new(x, y, channels, maxpal)
698
699
700 Creates a new paletted image of the supplied dimensions.
701
702 Returns a new image or NULL on failure.
703
704
705 =for comment
706 From: File palimg.c
707
708 =item i_sametype(i_img *im, int xsize, int ysize)
709
710
711 Returns an image of the same type (sample size, channels, paletted/direct).
712
713 For paletted images the palette is copied from the source.
714
715
716 =for comment
717 From: File image.c
718
719 =item i_sametype_chans(i_img *im, int xsize, int ysize, int channels)
720
721
722 Returns an image of the same type (sample size).
723
724 For paletted images the equivalent direct type is returned.
725
726
727 =for comment
728 From: File image.c
729
730
731 =back
732
733 =head2 Image quantization
734
735 =over
736
737 =item i_quant_makemap(quant, imgs, count)
738
739
740 Analyzes the I<count> images in I<imgs> according to the rules in
741 I<quant> to build a color map (optimal or not depending on
742 quant->make_colors).
743
744
745 =for comment
746 From: File quant.c
747
748 =item i_quant_translate(quant, img)
749
750
751 Quantize the image given the palette in quant.
752
753 On success returns a pointer to a memory block of img->xsize *
754 img->ysize i_palidx entries.
755
756 On failure returns NULL.
757
758 You should call myfree() on the returned block when you're done with
759 it.
760
761 This function will fail if the supplied palette contains no colors.
762
763
764 =for comment
765 From: File quant.c
766
767 =item i_quant_transparent(quant, data, img, trans_index)
768
769
770 Dither the alpha channel on I<img> into the palette indexes in
771 I<data>.  Pixels to be transparent are replaced with I<trans_pixel>.
772
773 The method used depends on the tr_* members of quant.
774
775
776 =for comment
777 From: File quant.c
778
779
780 =back
781
782 =head2 Paletted images
783
784 =over
785
786 =item i_addcolors(im, colors, count)
787
788
789 Adds colors to the image's palette.
790
791 On success returns the index of the lowest color added.
792
793 On failure returns -1.
794
795 Always fails for direct color images.
796
797
798 =for comment
799 From: File imext.c
800
801 =item i_colorcount(im)
802
803
804 Returns the number of colors in the image's palette.
805
806 Returns -1 for direct images.
807
808
809 =for comment
810 From: File imext.c
811
812 =item i_findcolor(im, color, &entry)
813
814
815 Searches the images palette for the given color.
816
817 On success sets *I<entry> to the index of the color, and returns true.
818
819 On failure returns false.
820
821 Always fails on direct color images.
822
823
824 =for comment
825 From: File imext.c
826
827 =item i_getcolors(im, index, colors, count)
828
829
830 Retrieves I<count> colors starting from I<index> in the image's
831 palette.
832
833 On success stores the colors into I<colors> and returns true.
834
835 On failure returns false.
836
837 Always fails for direct color images.
838
839 Fails if there are less than I<index>+I<count> colors in the image's
840 palette.
841
842
843 =for comment
844 From: File imext.c
845
846 =item i_maxcolors(im)
847
848
849 Returns the maximum number of colors the palette can hold for the
850 image.
851
852 Returns -1 for direct color images.
853
854
855 =for comment
856 From: File imext.c
857
858 =item i_setcolors(im, index, colors, count)
859
860
861 Sets I<count> colors starting from I<index> in the image's palette.
862
863 On sucess returns true.
864
865 On failure returns false.
866
867 The image must have at least I<index>+I<count> colors in it's palette
868 for this to succeed.
869
870 Always fails on direct color images.
871
872
873 =for comment
874 From: File imext.c
875
876
877 =back
878
879 =head2 Tags
880
881 =over
882
883 =item i_tags_delbycode(tags, code)
884
885
886 Delete any tags with the given code.
887
888 Returns the number of tags deleted.
889
890
891 =for comment
892 From: File tags.c
893
894 =item i_tags_delbyname(tags, name)
895
896
897 Delete any tags with the given name.
898
899 Returns the number of tags deleted.
900
901
902 =for comment
903 From: File tags.c
904
905 =item i_tags_delete(tags, index)
906
907
908 Delete a tag by index.
909
910 Returns true on success.
911
912
913 =for comment
914 From: File tags.c
915
916 =item i_tags_destroy(tags)
917
918
919 Destroys the given tags structure.  Called by i_img_destroy().
920
921
922 =for comment
923 From: File tags.c
924
925 =item i_tags_find(tags, name, start, &entry)
926
927
928 Searchs for a tag of the given I<name> starting from index I<start>.
929
930 On success returns true and sets *I<entry>.
931
932 On failure returns false.
933
934
935 =for comment
936 From: File tags.c
937
938 =item i_tags_findn(tags, code, start, &entry)
939
940
941 Searchs for a tag of the given I<code> starting from index I<start>.
942
943 On success returns true and sets *I<entry>.
944
945 On failure returns false.
946
947
948 =for comment
949 From: File tags.c
950
951 =item i_tags_get_color(tags, name, code, &value)
952
953
954 Retrieve a tag specified by name or code as color.
955
956 On success sets the i_color *I<value> to the color and returns true.
957
958 On failure returns false.
959
960
961 =for comment
962 From: File tags.c
963
964 =item i_tags_get_float(tags, name, code, value)
965
966
967 Retrieves a tag as a floating point value.  
968
969 If the tag has a string value then that is parsed as a floating point
970 number, otherwise the integer value of the tag is used.
971
972 On success sets *I<value> and returns true.
973
974 On failure returns false.
975
976
977 =for comment
978 From: File tags.c
979
980 =item i_tags_get_int(tags, name, code, &value)
981
982
983 Retrieve a tag specified by name or code as an integer.
984
985 On success sets the int *I<value> to the integer and returns true.
986
987 On failure returns false.
988
989
990 =for comment
991 From: File tags.c
992
993 =item i_tags_get_string(tags, name, code, value, value_size)
994
995
996 Retrieves a tag by name or code as a string.
997
998 On success copies the string to value for a max of value_size and
999 returns true.
1000
1001 On failure returns false.
1002
1003 value_size must be at least large enough for a string representation
1004 of an integer.
1005
1006 The copied value is always NUL terminated.
1007
1008
1009 =for comment
1010 From: File tags.c
1011
1012 =item i_tags_new(i_img_tags *tags)
1013
1014
1015 Initialize a tags structure.  Should not be used if the tags structure
1016 has been previously used.
1017
1018 This should be called tags member of an i_img object on creation (in
1019 i_img_*_new() functions).
1020
1021 To destroy the contents use i_tags_destroy()
1022
1023
1024 =for comment
1025 From: File tags.c
1026
1027 =item i_tags_set(tags, name, data, size)
1028
1029
1030 Sets the given tag to the string I<data>
1031
1032
1033 =for comment
1034 From: File tags.c
1035
1036 =item i_tags_set_color(tags, name, code, &value)
1037
1038
1039 Stores the given color as a tag with the given name and code.
1040
1041
1042 =for comment
1043 From: File tags.c
1044
1045 =item i_tags_set_float(tags, name, code, value)
1046
1047
1048 Equivalent to i_tags_set_float2(tags, name, code, value, 30).
1049
1050
1051 =for comment
1052 From: File tags.c
1053
1054 =item i_tags_set_float2(tags, name, code, value, places)
1055
1056
1057 Sets the tag with the given name and code to the given floating point
1058 value.
1059
1060 Since tags are strings or ints, we convert the value to a string before
1061 storage at the precision specified by C<places>.
1062
1063
1064 =for comment
1065 From: File tags.c
1066
1067 =item i_tags_setn(tags, name, idata)
1068
1069
1070 Sets the given tag to the integer I<idata>
1071
1072
1073 =for comment
1074 From: File tags.c
1075
1076
1077 =back
1078
1079
1080 =head1 AUTHOR
1081
1082 Tony Cook <tony@imager.perl.org>
1083
1084 =head1 SEE ALSO
1085
1086 Imager, Imager::ExtUtils, Imager::Inline
1087
1088 =cut