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