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