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