9827ff731aa0ea1ca1e8b8cbf0a81f48ea478e20
[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 - reference.
10
11 =head1 SYNOPSIS
12
13   i_color color;
14   color.rgba.r = 255; color.rgba.g = 0; color.rgba.b = 255;
15
16
17   # Blit tools
18
19   # Data Types
20   i_img *img;
21   i_color black;
22   black.rgba.r = black.rgba.g = black.rgba.b = black.rgba.a = 0;
23   i_fill_t *fill;
24   i_img_dim x, y;
25   printf("left %" i_DF "\n", i_DFc(x));
26   printf("point (" i_DFp ")\n", i_DFcp(x, y));
27
28   # Drawing
29   i_arc(im, 50, 50, 20, 45, 135, &color);
30   i_arc_cfill(im, 50, 50, 35, 90, 135, fill);
31   i_arc_aa(im, 50, 50, 35, 90, 135, &color);
32   i_arc_aa_cfill(im, 50, 50, 35, 90, 135, fill);
33   i_circle_aa(im, 50, 50, 45, &color);
34   i_box(im, 0, 0, im->xsize-1, im->ysize-1, &color).
35   i_box_filled(im, 0, 0, im->xsize-1, im->ysize-1, &color);
36   i_box_cfill(im, 0, 0, im->xsize-1, im->ysize-1, fill);
37   i_flood_fill(im, 50, 50, &color);
38   i_flood_cfill(im, 50, 50, fill);
39   i_flood_fill_border(im, 50, 50, &color, &border);
40   i_flood_cfill_border(im, 50, 50, fill, border);
41
42   # Error handling
43   i_clear_error();
44   i_push_error(0, "Yep, it's broken");
45   i_push_error(errno, "Error writing");
46   i_push_errorf(errno, "Cannot open file %s: %d", filename, errno);
47
48   # Files
49   i_set_image_file_limits(500, 500, 1000000);
50   i_get_image_file_limits(&width, &height, &bytes)
51   i_i_int_check_image_file_limits(width, height, channels, sizeof(i_sample_t))
52
53   # Fills
54   i_fill_t *fill = i_new_fill_solidf(&fcolor, combine);
55   i_fill_t *fill = i_new_fill_solid(&color, combine);
56   i_fill_t *fill = i_new_fill_hatch(&fg_color, &bg_color, combine, hatch, custom_hatch, dx, dy);
57   i_fill_t *fill = i_new_fill_hatchf(&fg_fcolor, &bg_fcolor, combine, hatch, custom_hatch, dx, dy);
58   i_fill_t *fill = i_new_fill_image(src_img, matrix, x_offset, y_offset, combine);
59   fill = i_new_fill_fount(0, 0, 100, 100, i_ft_linear, i_ft_linear, 
60                           i_fr_triangle, 0, i_fts_grid, 9, 1, segs);
61   i_fill_destroy(fill);
62
63   # I/O Layers
64   ssize_t count = i_io_peekn(ig, buffer, sizeof(buffer));
65   ssize_t result = i_io_write(io, buffer, size)
66   char buffer[BUFSIZ]
67   ssize_t len = i_io_gets(buffer, sizeof(buffer), '\n');
68   io_glue_destroy(ig);
69
70   # Image
71
72   # Image creation/destruction
73   i_img *img = i_sametype(src, width, height);
74   i_img *img = i_sametype_chans(src, width, height, channels);
75   i_img *img = i_img_16_new(width, height, channels);
76   i_img *img = i_img_8_new(width, height, channels);
77   i_img *img = i_img_double_new(width, height, channels);
78   i_img *img = i_img_pal_new(width, height, channels, max_palette_size)
79   i_img_destroy(img)
80
81   # Image Implementation
82
83   # Image Information
84   // only channel 0 writable 
85   i_img_setmask(img, 0x01);
86   int mask = i_img_getmask(img);
87   int channels = i_img_getchannels(img);
88   i_img_dim width = i_img_get_width(im);
89   i_img_dim height = i_img_get_height(im);
90
91   # Image quantization
92
93   # Logging
94
95   # Paletted images
96
97   # Tags
98   i_tags_set(&img->tags, "i_comment", -1);
99   i_tags_setn(&img->tags, "i_xres", 204);
100   i_tags_setn(&img->tags, "i_yres", 196);
101
102 =head1 DESCRIPTION
103
104 =head2 Blit tools
105
106 =over
107
108 =item i_render_color(r, x, y, width, source, color)
109
110 Render the given color with the coverage specified by C<source[0]> to
111 C<source[width-1]>.
112
113 Renders in normal combine mode.
114
115
116 =for comment
117 From: File render.im
118
119 =item i_render_delete(r)
120
121 Release an C<i_render> object.
122
123
124 =for comment
125 From: File render.im
126
127 =item i_render_fill(r, x, y, width, source, fill)
128
129 Render the given fill with the coverage in C<source[0]> through
130 C<source[width-1]>.
131
132
133 =for comment
134 From: File render.im
135
136 =item i_render_line(r, x, y, width, source, fill)
137
138 Render the given fill with the coverage in C<source[0]> through
139 C<source[width-1]>.
140
141
142 =for comment
143 From: File render.im
144
145 =item i_render_linef(r, x, y, width, source, fill)
146
147 Render the given fill with the coverage in C<source[0]> through
148 C<source[width-1]>.
149
150
151 =for comment
152 From: File render.im
153
154 =item i_render_new(im, width)
155
156 Allocate a new C<i_render> object and initialize it.
157
158
159 =for comment
160 From: File render.im
161
162
163 =back
164
165 =head2 Data Types
166
167 =over
168
169 =item i_img
170
171   i_img *img;
172
173 This is Imager's image type.
174
175 It contains the following members:
176
177 =over
178
179 =item *
180
181 C<channels> - the number of channels in the image
182
183 =item *
184
185 C<xsize>, C<ysize> - the width and height of the image in pixels
186
187 =item *
188
189 C<bytes> - the number of bytes used to store the image data.  Undefined
190 where virtual is non-zero.
191
192 =item *
193
194 C<ch_mask> - a mask of writable channels.  eg. if this is 6 then only
195 channels 1 and 2 are writable.  There may be bits set for which there
196 are no channels in the image.
197
198 =item *
199
200 C<bits> - the number of bits stored per sample.  Should be one of
201 i_8_bits, i_16_bits, i_double_bits.
202
203 =item *
204
205 C<type> - either i_direct_type for direct color images, or i_palette_type
206 for paletted images.
207
208 =item *
209
210 C<virtual> - if zero then this image is-self contained.  If non-zero
211 then this image could be an interface to some other implementation.
212
213 =item *
214
215 C<idata> - the image data.  This should not be directly accessed.  A new
216 image implementation can use this to store its image data.
217 i_img_destroy() will myfree() this pointer if it's non-null.
218
219 =item *
220
221 C<tags> - a structure storing the image's tags.  This should only be
222 accessed via the i_tags_*() functions.
223
224 =item *
225
226 C<ext_data> - a pointer for use internal to an image implementation.
227 This should be freed by the image's destroy handler.
228
229 =item *
230
231 C<im_data> - data internal to Imager.  This is initialized by
232 i_img_init().
233
234 =item *
235
236 i_f_ppix, i_f_ppixf, i_f_plin, i_f_plinf, i_f_gpix, i_f_gpixf,
237 i_f_glin, i_f_glinf, i_f_gsamp, i_f_gampf - implementations for each
238 of the required image functions.  An image implementation should
239 initialize these between calling i_img_alloc() and i_img_init().
240
241 =item *
242
243 i_f_gpal, i_f_ppal, i_f_addcolors, i_f_getcolors, i_f_colorcount,
244 i_f_maxcolors, i_f_findcolor, i_f_setcolors - implementations for each
245 paletted image function.
246
247 =item *
248
249 i_f_destroy - custom image destruction function.  This should be used
250 to release memory if necessary.
251
252 =item *
253
254 i_f_gsamp_bits - implements i_gsamp_bits() for this image.
255
256 =item *
257
258 i_f_psamp_bits - implements i_psamp_bits() for this image.
259
260 =item *
261
262 i_f_psamp - implements psamp() for this image.
263
264 =item *
265
266 i_f_psampf - implements psamp() for this image.
267
268 =back
269
270
271 =for comment
272 From: File imdatatypes.h
273
274 =item i_color
275
276   i_color black;
277   black.rgba.r = black.rgba.g = black.rgba.b = black.rgba.a = 0;
278
279 Type for 8-bit/sample color.
280
281 Samples as per;
282
283   i_color c;
284
285 i_color is a union of:
286
287 =over
288
289 =item *
290
291 gray - contains a single element gray_color, eg. C<c.gray.gray_color>
292
293 =item *
294
295 C<rgb> - contains three elements C<r>, C<g>, C<b>, eg. C<c.rgb.r>
296
297 =item *
298
299 C<rgba> - contains four elements C<r>, C<g>, C<b>, C<a>, eg. C<c.rgba.a>
300
301 =item *
302
303 C<cmyk> - contains four elements C<c>, C<m>, C<y>, C<k>,
304 eg. C<c.cmyk.y>.  Note that Imager never uses CMYK colors except when
305 reading/writing files.
306
307 =item *
308
309 channels - an array of four channels, eg C<c.channels[2]>.
310
311 =back
312
313
314 =for comment
315 From: File imdatatypes.h
316
317 =item i_fcolor
318
319 This is the double/sample color type.
320
321 Its layout exactly corresponds to i_color.
322
323
324 =for comment
325 From: File imdatatypes.h
326
327 =item i_fill_t
328
329   i_fill_t *fill;
330
331 This is the "abstract" base type for Imager's fill types.
332
333 Unless you're implementing a new fill type you'll typically treat this
334 as an opaque type.
335
336
337 =for comment
338 From: File imdatatypes.h
339
340 =item i_img_dim
341
342   i_img_dim x, y;
343
344 A signed integer type that represents an image dimension or ordinate.
345
346 May be larger than int on some platforms.
347
348
349 =for comment
350 From: File imdatatypes.h
351
352 =item i_DF
353
354   printf("left %" i_DF "\n", i_DFc(x));
355
356 This is a constant string that can be used with functions like
357 printf() to format i_img_dim values after they're been cast with i_DFc().
358
359 Does not include the leading C<%>.
360
361
362 =for comment
363 From: File imdatatypes.h
364
365 =item i_DFc
366
367 Cast an C<i_img_dim> value to a type for use with the i_DF format
368 string.
369
370
371 =for comment
372 From: File imdatatypes.h
373
374 =item i_DFcp
375
376 Casts two C<i_img_dim> values for use with the i_DF (or i_DFp) format.
377
378
379 =for comment
380 From: File imdatatypes.h
381
382 =item i_DFp
383
384   printf("point (" i_DFp ")\n", i_DFcp(x, y));
385
386 Format a pair of C<i_img_dim> values.  This format string I<does>
387 include the leading C<%>.
388
389
390 =for comment
391 From: File imdatatypes.h
392
393
394 =back
395
396 =head2 Drawing
397
398 =over
399
400 =item i_arc(im, x, y, rad, d1, d2, color)
401
402
403   i_arc(im, 50, 50, 20, 45, 135, &color);
404
405 Fills an arc centered at (x,y) with radius I<rad> covering the range
406 of angles in degrees from d1 to d2, with the color.
407
408
409 =for comment
410 From: File draw.c
411
412 =item i_arc_aa(im, x, y, rad, d1, d2, color)
413
414
415   i_arc_aa(im, 50, 50, 35, 90, 135, &color);
416
417 Anti-alias fills an arc centered at (x,y) with radius I<rad> covering
418 the range of angles in degrees from d1 to d2, with the color.
419
420
421 =for comment
422 From: File draw.c
423
424 =item i_arc_aa_cfill(im, x, y, rad, d1, d2, fill)
425
426
427   i_arc_aa_cfill(im, 50, 50, 35, 90, 135, fill);
428
429 Anti-alias fills an arc centered at (x,y) with radius I<rad> covering
430 the range of angles in degrees from d1 to d2, with the fill object.
431
432
433 =for comment
434 From: File draw.c
435
436 =item i_arc_cfill(im, x, y, rad, d1, d2, fill)
437
438
439   i_arc_cfill(im, 50, 50, 35, 90, 135, fill);
440
441 Fills an arc centered at (x,y) with radius I<rad> covering the range
442 of angles in degrees from d1 to d2, with the fill object.
443
444
445 =for comment
446 From: File draw.c
447
448 =item i_box(im, x1, y1, x2, y2, color)
449
450
451   i_box(im, 0, 0, im->xsize-1, im->ysize-1, &color).
452
453 Outlines the box from (x1,y1) to (x2,y2) inclusive with I<color>.
454
455
456 =for comment
457 From: File draw.c
458
459 =item i_box_cfill(im, x1, y1, x2, y2, fill)
460
461
462   i_box_cfill(im, 0, 0, im->xsize-1, im->ysize-1, fill);
463
464 Fills the box from (x1,y1) to (x2,y2) inclusive with fill.
465
466
467 =for comment
468 From: File draw.c
469
470 =item i_box_filled(im, x1, y1, x2, y2, color)
471
472
473   i_box_filled(im, 0, 0, im->xsize-1, im->ysize-1, &color);
474
475 Fills the box from (x1,y1) to (x2,y2) inclusive with color.
476
477
478 =for comment
479 From: File draw.c
480
481 =item i_circle_aa(im, x, y, rad, color)
482
483
484   i_circle_aa(im, 50, 50, 45, &color);
485
486 Anti-alias fills a circle centered at (x,y) for radius I<rad> with
487 color.
488
489
490 =for comment
491 From: File draw.c
492
493 =item i_flood_cfill(C<im>, C<seedx>, C<seedy>, C<fill>)
494
495
496   i_flood_cfill(im, 50, 50, fill);
497
498 Flood fills the 4-connected region starting from the point (C<seedx>,
499 C<seedy>) with C<fill>.
500
501 Returns false if (C<seedx>, C<seedy>) are outside the image.
502
503
504 =for comment
505 From: File draw.c
506
507 =item i_flood_cfill_border(C<im>, C<seedx>, C<seedy>, C<fill>, C<border>)
508
509
510   i_flood_cfill_border(im, 50, 50, fill, border);
511
512 Flood fills the 4-connected region starting from the point (C<seedx>,
513 C<seedy>) with C<fill>, the fill stops when it reaches pixels of color
514 C<border>.
515
516 Returns false if (C<seedx>, C<seedy>) are outside the image.
517
518
519 =for comment
520 From: File draw.c
521
522 =item i_flood_fill(C<im>, C<seedx>, C<seedy>, C<color>)
523
524
525   i_flood_fill(im, 50, 50, &color);
526
527 Flood fills the 4-connected region starting from the point (C<seedx>,
528 C<seedy>) with I<color>.
529
530 Returns false if (C<seedx>, C<seedy>) are outside the image.
531
532
533 =for comment
534 From: File draw.c
535
536 =item i_flood_fill_border(C<im>, C<seedx>, C<seedy>, C<color>, C<border>)
537
538
539   i_flood_fill_border(im, 50, 50, &color, &border);
540
541 Flood fills the 4-connected region starting from the point (C<seedx>,
542 C<seedy>) with C<color>, fill stops when the fill reaches a pixels
543 with color C<border>.
544
545 Returns false if (C<seedx>, C<seedy>) are outside the image.
546
547
548 =for comment
549 From: File draw.c
550
551 =item i_glin(im, l, r, y, colors)
552
553
554 Retrieves (r-l) pixels starting from (l,y) into I<colors>.
555
556 Returns the number of pixels retrieved.
557
558
559 =for comment
560 From: File imext.c
561
562 =item i_glinf(im, l, r, y, colors)
563
564
565 Retrieves (r-l) pixels starting from (l,y) into I<colors> as floating
566 point colors.
567
568 Returns the number of pixels retrieved.
569
570
571 =for comment
572 From: File imext.c
573
574 =item i_gpal(im, left, right, y, indexes)
575
576
577 Reads palette indexes for the horizontal line (left, y) to (right-1,
578 y) into C<indexes>.
579
580 Returns the number of indexes read.
581
582 Always returns 0 for direct color images.
583
584
585 =for comment
586 From: File imext.c
587
588 =item i_gpix(im, C<x>, C<y>, C<color>)
589
590
591 Retrieves the C<color> of the pixel (x,y).
592
593 Returns 0 if the pixel was retrieved, or -1 if not.
594
595
596 =for comment
597 From: File imext.c
598
599 =item i_gpixf(im, C<x>, C<y>, C<fcolor>)
600
601
602 Retrieves the color of the pixel (x,y) as a floating point color into
603 C<fcolor>.
604
605 Returns 0 if the pixel was retrieved, or -1 if not.
606
607
608 =for comment
609 From: File imext.c
610
611 =item i_gsamp(im, left, right, y, samples, channels, channel_count)
612
613
614 Reads sample values from C<im> for the horizontal line (left, y) to
615 (right-1,y) for the channels specified by C<channels>, an array of int
616 with C<channel_count> elements.
617
618 If channels is NULL then the first channels_count channels are retrieved for
619 each pixel.
620
621 Returns the number of samples read (which should be (right-left) *
622 channel_count)
623
624
625 =for comment
626 From: File imext.c
627
628 =item i_gsamp_bg(im, l, r, y, samples, out_channels, background)
629
630
631 Like C<i_gsampf()> but applies the source image color over a supplied
632 background color.
633
634 This is intended for output to image formats that don't support alpha
635 channels.
636
637
638 =for comment
639 From: File paste.im
640
641 =item i_gsamp_bits(im, left, right, y, samples, channels, channel_count, bits)
642
643 Reads integer samples scaled to C<bits> bits of precision into the
644 C<unsigned int> array C<samples>.
645
646 Expect this to be slow unless C<< bits == im->bits >>.
647
648 Returns the number of samples copied, or -1 on error.
649
650 Not all image types implement this method.
651
652 Pushes errors, but does not call C<i_clear_error()>.
653
654
655 =for comment
656 From: File imext.c
657
658 =item i_gsampf(im, left, right, y, samples, channels, channel_count)
659
660
661 Reads floating point sample values from C<im> for the horizontal line
662 (left, y) to (right-1,y) for the channels specified by C<channels>, an
663 array of int with channel_count elements.
664
665 If C<channels> is NULL then the first C<channel_count> channels are
666 retrieved for each pixel.
667
668 Returns the number of samples read (which should be (C<right>-C<left>)
669 * C<channel_count>)
670
671
672 =for comment
673 From: File imext.c
674
675 =item i_gsampf_bg(im, l, r, y, samples, out_channels, background)
676
677
678 Like C<i_gsampf()> but applies the source image color over a supplied
679 background color.
680
681 This is intended for output to image formats that don't support alpha
682 channels.
683
684
685 =for comment
686 From: File paste.im
687
688 =item i_line(C<im>, C<x1>, C<y1>, C<x2>, C<y2>, C<color>, C<endp>)
689
690
691 =for stopwords Bresenham's
692
693 Draw a line to image using Bresenham's line drawing algorithm
694
695    im    - image to draw to
696    x1    - starting x coordinate
697    y1    - starting x coordinate
698    x2    - starting x coordinate
699    y2    - starting x coordinate
700    color - color to write to image
701    endp  - endpoint flag (boolean)
702
703
704 =for comment
705 From: File draw.c
706
707 =item i_line_aa(C<im>, C<x1>, C<x2>, C<y1>, C<y2>, C<color>, C<endp>)
708
709
710 Anti-alias draws a line from (x1,y1) to (x2, y2) in color.
711
712 The point (x2, y2) is drawn only if C<endp> is set.
713
714
715 =for comment
716 From: File draw.c
717
718 =item i_plin(im, l, r, y, colors)
719
720
721 Sets (r-l) pixels starting from (l,y) using (r-l) values from
722 I<colors>.
723
724 Returns the number of pixels set.
725
726
727 =for comment
728 From: File imext.c
729
730 =item i_plinf(im, C<left>, C<right>, C<fcolors>)
731
732
733 Sets (right-left) pixels starting from (left,y) using (right-left)
734 floating point colors from C<fcolors>.
735
736 Returns the number of pixels set.
737
738
739 =for comment
740 From: File imext.c
741
742 =item i_ppal(im, left, right, y, indexes)
743
744
745 Writes palette indexes for the horizontal line (left, y) to (right-1,
746 y) from C<indexes>.
747
748 Returns the number of indexes written.
749
750 Always returns 0 for direct color images.
751
752
753 =for comment
754 From: File imext.c
755
756 =item i_ppix(im, x, y, color)
757
758
759 Sets the pixel at (x,y) to I<color>.
760
761 Returns 0 if the pixel was drawn, or -1 if not.
762
763 Does no alpha blending, just copies the channels from the supplied
764 color to the image.
765
766
767 =for comment
768 From: File imext.c
769
770 =item i_ppixf(im, C<x>, C<y>, C<fcolor>)
771
772
773 Sets the pixel at (C<x>,C<y>) to the floating point color C<fcolor>.
774
775 Returns 0 if the pixel was drawn, or -1 if not.
776
777 Does no alpha blending, just copies the channels from the supplied
778 color to the image.
779
780
781 =for comment
782 From: File imext.c
783
784 =item i_psamp(im, left, right, y, samples, channels, channel_count)
785
786 Writes sample values from C<samples> to C<im> for the horizontal line
787 (left, y) to (right-1, y) inclusive for the channels specified by
788 C<channels>, an array of C<int> with C<channel_count> elements.
789
790 If C<channels> is C<NULL> then the first C<channels_count> channels
791 are written to for each pixel.
792
793 Returns the number of samples written, which should be (right - left)
794 * channel_count.  If a channel not in the image is in channels, left
795 is negative, left is outside the image or y is outside the image,
796 returns -1 and pushes an error.
797
798
799 =for comment
800 From: File immacros.h
801
802 =item i_psamp_bits(im, left, right, y, samples, channels, channel_count, bits)
803
804 Writes integer samples scaled to C<bits> bits of precision from the
805 C<unsigned int> array C<samples>.
806
807 Expect this to be slow unless C<< bits == im->bits >>.
808
809 Returns the number of samples copied, or -1 on error.
810
811 Not all image types implement this method.
812
813 Pushes errors, but does not call C<i_clear_error()>.
814
815
816 =for comment
817 From: File imext.c
818
819 =item i_psampf(im, left, right, y, samples, channels, channel_count)
820
821 Writes floating point sample values from C<samples> to C<im> for the
822 horizontal line (left, y) to (right-1, y) inclusive for the channels
823 specified by C<channels>, an array of C<int> with C<channel_count>
824 elements.
825
826 If C<channels> is C<NULL> then the first C<channels_count> channels
827 are written to for each pixel.
828
829 Returns the number of samples written, which should be (right - left)
830 * channel_count.  If a channel not in the image is in channels, left
831 is negative, left is outside the image or y is outside the image,
832 returns -1 and pushes an error.
833
834
835 =for comment
836 From: File immacros.h
837
838
839 =back
840
841 =head2 Error handling
842
843 =over
844
845 =item i_clear_error()
846
847   i_clear_error();
848
849 Clears the error stack.
850
851 Called by any Imager function before doing any other processing.
852
853
854 =for comment
855 From: File error.c
856
857 =item i_push_error(int code, char const *msg)
858
859   i_push_error(0, "Yep, it's broken");
860   i_push_error(errno, "Error writing");
861
862 Called by an Imager function to push an error message onto the stack.
863
864 No message is pushed if the stack is full (since this means someone
865 forgot to call i_clear_error(), or that a function that doesn't do
866 error handling is calling function that does.).
867
868
869 =for comment
870 From: File error.c
871
872 =item i_push_errorf(int code, char const *fmt, ...)
873
874   i_push_errorf(errno, "Cannot open file %s: %d", filename, errno);
875
876 A version of i_push_error() that does printf() like formatting.
877
878 Does not support perl specific format codes.
879
880
881 =for comment
882 From: File error.c
883
884 =item i_push_errorvf(int C<code>, char const *C<fmt>, va_list C<ap>)
885
886
887 Intended for use by higher level functions, takes a varargs pointer
888 and a format to produce the finally pushed error message.
889
890 Does not support perl specific format codes.
891
892
893 =for comment
894 From: File error.c
895
896
897 =back
898
899 =head2 Files
900
901 =over
902
903 =item i_get_file_background(im, &bg)
904
905
906 Retrieve the file write background color tag from the image.
907
908 If not present, C<bg> is set to black.
909
910 Returns 1 if the C<i_background> tag was found and valid.
911
912
913 =for comment
914 From: File image.c
915
916 =item i_get_file_backgroundf(im, &bg)
917
918
919 Retrieve the file write background color tag from the image as a
920 floating point color.
921
922 Implemented in terms of i_get_file_background().
923
924 If not present, C<bg> is set to black.
925
926 Returns 1 if the C<i_background> tag was found and valid.
927
928
929 =for comment
930 From: File image.c
931
932 =item i_get_image_file_limits(&width, &height, &bytes)
933
934
935   i_get_image_file_limits(&width, &height, &bytes)
936
937 Retrieves the file limits set by i_set_image_file_limits().
938
939 =over
940
941 =item *
942
943 i_img_dim *width, *height - the maximum width and height of the image.
944
945 =item *
946
947 size_t *bytes - size in memory of the image in bytes.
948
949 =back
950
951
952 =for comment
953 From: File limits.c
954
955 =item i_int_check_image_file_limits(width, height, channels, sample_size)
956
957
958   i_i_int_check_image_file_limits(width, height, channels, sizeof(i_sample_t))
959
960 Checks the size of a file in memory against the configured image file
961 limits.
962
963 This also range checks the values to those permitted by Imager and
964 checks for overflows in calculating the size.
965
966 Returns non-zero if the file is within limits.
967
968 This function is intended to be called by image file read functions.
969
970
971 =for comment
972 From: File limits.c
973
974 =item i_set_image_file_limits(width, height, bytes)
975
976
977   i_set_image_file_limits(500, 500, 1000000);
978
979 Set limits on the sizes of images read by Imager.
980
981 Setting a limit to 0 means that limit is ignored.
982
983 Negative limits result in failure.
984
985 Parameters:
986
987 =over
988
989 =item *
990
991 i_img_dim width, height - maximum width and height.
992
993 =item *
994
995 size_t bytes - maximum size in memory in bytes.  A value of zero sets
996 this limit to one gigabyte.
997
998 =back
999
1000 Returns non-zero on success.
1001
1002
1003 =for comment
1004 From: File limits.c
1005
1006
1007 =back
1008
1009 =head2 Fills
1010
1011 =over
1012
1013 =item i_new_fill_fount(C<xa>, C<ya>, C<xb>, C<yb>, C<type>, C<repeat>, C<combine>, C<super_sample>, C<ssample_param>, C<count>, C<segs>)
1014
1015
1016   fill = i_new_fill_fount(0, 0, 100, 100, i_ft_linear, i_ft_linear, 
1017                           i_fr_triangle, 0, i_fts_grid, 9, 1, segs);
1018
1019
1020 Creates a new general fill which fills with a fountain fill.
1021
1022
1023 =for comment
1024 From: File filters.im
1025
1026 =item i_new_fill_hatch(C<fg>, C<bg>, C<combine>, C<hatch>, C<cust_hatch>, C<dx>, C<dy>)
1027
1028
1029   i_fill_t *fill = i_new_fill_hatch(&fg_color, &bg_color, combine, hatch, custom_hatch, dx, dy);
1030
1031 Creates a new hatched fill with the C<fg> color used for the 1 bits in
1032 the hatch and C<bg> for the 0 bits.  If C<combine> is non-zero alpha
1033 values will be combined.
1034
1035 If C<cust_hatch> is non-NULL it should be a pointer to 8 bytes of the
1036 hash definition, with the high-bits to the left.
1037
1038 If C<cust_hatch> is NULL then one of the standard hatches is used.
1039
1040 (C<dx>, C<dy>) are an offset into the hatch which can be used to hatch
1041 adjoining areas out of alignment, or to align the origin of a hatch
1042 with the the side of a filled area.
1043
1044
1045 =for comment
1046 From: File fills.c
1047
1048 =item i_new_fill_hatchf(C<fg>, C<bg>, C<combine>, C<hatch>, C<cust_hatch>, C<dx>, C<dy>)
1049
1050
1051   i_fill_t *fill = i_new_fill_hatchf(&fg_fcolor, &bg_fcolor, combine, hatch, custom_hatch, dx, dy);
1052
1053 Creates a new hatched fill with the C<fg> color used for the 1 bits in
1054 the hatch and C<bg> for the 0 bits.  If C<combine> is non-zero alpha
1055 values will be combined.
1056
1057 If C<cust_hatch> is non-NULL it should be a pointer to 8 bytes of the
1058 hash definition, with the high-bits to the left.
1059
1060 If C<cust_hatch> is NULL then one of the standard hatches is used.
1061
1062 (C<dx>, C<dy>) are an offset into the hatch which can be used to hatch
1063 adjoining areas out of alignment, or to align the origin of a hatch
1064 with the the side of a filled area.
1065
1066
1067 =for comment
1068 From: File fills.c
1069
1070 =item i_new_fill_image(C<im>, C<matrix>, C<xoff>, C<yoff>, C<combine>)
1071
1072
1073   i_fill_t *fill = i_new_fill_image(src_img, matrix, x_offset, y_offset, combine);
1074
1075 Create an image based fill.
1076
1077 matrix is an array of 9 doubles representing a transformation matrix.
1078
1079 C<xoff> and C<yoff> are the offset into the image to start filling from.
1080
1081
1082 =for comment
1083 From: File fills.c
1084
1085 =item i_new_fill_solid(color, combine)
1086
1087
1088   i_fill_t *fill = i_new_fill_solid(&color, combine);
1089
1090 Create a solid fill based on an 8-bit color.
1091
1092 If combine is non-zero then alpha values will be combined.
1093
1094
1095 =for comment
1096 From: File fills.c
1097
1098 =item i_new_fill_solidf(color, combine)
1099
1100
1101   i_fill_t *fill = i_new_fill_solidf(&fcolor, combine);
1102
1103 Create a solid fill based on a float color.
1104
1105 If combine is non-zero then alpha values will be combined.
1106
1107
1108 =for comment
1109 From: File fills.c
1110
1111 =item i_fill_destroy(fill)
1112
1113   i_fill_destroy(fill);
1114
1115 Call to destroy any fill object.
1116
1117
1118 =for comment
1119 From: File fills.c
1120
1121
1122 =back
1123
1124 =head2 I/O Layers
1125
1126 =over
1127
1128 =item io_new_bufchain()
1129
1130 returns a new io_glue object that has the 'empty' source and but can
1131 be written to and read from later (like a pseudo file).
1132
1133
1134 =for comment
1135 From: File iolayer.c
1136
1137 =item io_new_buffer(data, length)
1138
1139 Returns a new io_glue object that has the source defined as reading
1140 from specified buffer.  Note that the buffer is not copied.
1141
1142    data - buffer to read from
1143    length - length of buffer
1144
1145
1146 =for comment
1147 From: File iolayer.c
1148
1149 =item io_new_cb(p, read_cb, write_cb, seek_cb, close_cb, destroy_cb)
1150
1151 Create a new I/O layer object that calls your supplied callbacks.
1152
1153 In general the callbacks should behave like the corresponding POSIX
1154 primitives.
1155
1156 =over
1157
1158 =item *
1159
1160 C<read_cb>(p, buffer, length) should read up to C<length> bytes into
1161 C<buffer> and return the number of bytes read.  At end of file, return
1162 0.  On error, return -1.
1163
1164 =item *
1165
1166 C<write_cb>(p, buffer, length) should write up to C<length> bytes from
1167 C<buffer> and return the number of bytes written.  A return value <= 0
1168 will be treated as an error.
1169
1170 =item *
1171
1172 C<seekcb>(p, offset, whence) should seek and return the new offset.
1173
1174 =item *
1175
1176 C<close_cb>(p) should return 0 on success, -1 on failure.
1177
1178 =item *
1179
1180 C<destroy_cb>(p) should release any memory specific to your callback
1181 handlers.
1182
1183 =back
1184
1185
1186 =for comment
1187 From: File iolayer.c
1188
1189 =item io_new_fd(fd)
1190
1191 returns a new io_glue object that has the source defined as reading
1192 from specified file descriptor.  Note that the the interface to receiving
1193 data from the io_glue callbacks hasn't been done yet.
1194
1195    fd - file descriptor to read/write from
1196
1197
1198 =for comment
1199 From: File iolayer.c
1200
1201 =item i_io_close(io)
1202
1203 Flush any pending output and perform the close action for the stream.
1204
1205 Returns 0 on success.
1206
1207
1208 =for comment
1209 From: File iolayer.c
1210
1211 =item i_io_flush(io)
1212
1213 Flush any buffered output.
1214
1215 Returns true on success,
1216
1217
1218 =for comment
1219 From: File iolayer.c
1220
1221 =item i_io_getc(ig)
1222
1223 A macro to read a single byte from a buffered I/O glue object.
1224
1225 Returns EOF on failure, or a byte.
1226
1227
1228 =for comment
1229 From: File iolayer.c
1230
1231 =item i_io_gets(ig, buffer, size, end_of_line)
1232
1233   char buffer[BUFSIZ]
1234   ssize_t len = i_io_gets(buffer, sizeof(buffer), '\n');
1235
1236 Read up to C<size>-1 bytes from the stream C<ig> into C<buffer>.
1237
1238 If the byte C<end_of_line> is seen then no further bytes will be read.
1239
1240 Returns the number of bytes read.
1241
1242 Always C<NUL> terminates the buffer.
1243
1244
1245 =for comment
1246 From: File iolayer.c
1247
1248 =item i_io_peekc(ig)
1249
1250 Read the next character from the stream without advancing the stream.
1251
1252 On error or end of file, return EOF.
1253
1254 For unbuffered streams a single character buffer will be setup.
1255
1256
1257 =for comment
1258 From: File iolayer.c
1259
1260 =item i_io_peekn(ig, buffer, size)
1261
1262   ssize_t count = i_io_peekn(ig, buffer, sizeof(buffer));
1263
1264 Buffer at least C<size> (at most C<< ig->buf_size >> bytes of data
1265 from the stream and return C<size> bytes of it to the caller in
1266 C<buffer>.
1267
1268 This ignores the buffered state of the stream, and will always setup
1269 buffering if needed.
1270
1271 If no C<type> parameter is provided to Imager::read() or
1272 Imager::read_multi(), Imager will call C<i_io_peekn()> when probing
1273 for the file format.
1274
1275 Returns -1 on error, 0 if there is no data before EOF, or the number
1276 of bytes read into C<buffer>.
1277
1278
1279 =for comment
1280 From: File iolayer.c
1281
1282 =item i_io_putc(ig, c)
1283
1284 Write a single character to the stream.
1285
1286 On success return c, on error returns EOF
1287
1288
1289 =for comment
1290 From: File iolayer.c
1291
1292 =item i_io_read(io, buffer, size)
1293
1294 Read up to C<size> bytes from the stream C<io> into C<buffer>.
1295
1296 Returns the number of bytes read.  Returns 0 on end of file.  Returns
1297 -1 on error.
1298
1299
1300 =for comment
1301 From: File iolayer.c
1302
1303 =item i_io_seek(io, offset, whence)
1304
1305 Seek within the stream.
1306
1307 Acts like perl's seek.
1308
1309
1310 =for comment
1311 From: File iolayer.c
1312
1313 =item i_io_set_buffered(io, buffered)
1314
1315 Set the buffering mode of the stream.
1316
1317 If you switch buffering off on a stream with buffering on:
1318
1319 =over
1320
1321 =item *
1322
1323 any buffered output will be flushed.
1324
1325 =item *
1326
1327 any existing buffered input will be consumed before reads become
1328 unbuffered.
1329
1330 =back
1331
1332 Returns true on success.  This may fail if any buffered output cannot
1333 be flushed.
1334
1335
1336 =for comment
1337 From: File iolayer.c
1338
1339 =item i_io_write(io, buffer, size)
1340
1341   ssize_t result = i_io_write(io, buffer, size)
1342
1343 Write to the given I/O stream.
1344
1345 Returns the number of bytes written.
1346
1347
1348 =for comment
1349 From: File iolayer.c
1350
1351 =item io_slurp(ig, c)
1352
1353 Takes the source that the io_glue is bound to and allocates space for
1354 a return buffer and returns the entire content in a single buffer.
1355 Note: This only works for io_glue objects created by
1356 io_new_bufchain().  It is useful for saving to scalars and such.
1357
1358    ig - io_glue object
1359    c  - pointer to a pointer to where data should be copied to
1360
1361   char *data;
1362   size_t size = io_slurp(ig, &data);
1363   ... do something with the data ...
1364   myfree(data);
1365
1366 io_slurp() will abort the program if the supplied I/O layer is not
1367 from io_new_bufchain().
1368
1369
1370 =for comment
1371 From: File iolayer.c
1372
1373 =item io_glue_destroy(ig)
1374
1375   io_glue_destroy(ig);
1376
1377 Destroy an io_glue objects.  Should clean up all related buffers.
1378
1379    ig - io_glue object to destroy.
1380
1381
1382 =for comment
1383 From: File iolayer.c
1384
1385
1386 =back
1387
1388 =head2 Image
1389
1390 =over
1391
1392 =item i_copy(source)
1393
1394
1395 Creates a new image that is a copy of the image C<source>.
1396
1397 Tags are not copied, only the image data.
1398
1399 Returns: i_img *
1400
1401
1402 =for comment
1403 From: File image.c
1404
1405 =item i_copyto(C<dest>, C<src>, C<x1>, C<y1>, C<x2>, C<y2>, C<tx>, C<ty>)
1406
1407
1408 Copies image data from the area (C<x1>,C<y1>)-[C<x2>,C<y2>] in the
1409 source image to a rectangle the same size with it's top-left corner at
1410 (C<tx>,C<ty>) in the destination image.
1411
1412 If C<x1> > C<x2> or C<y1> > C<y2> then the corresponding co-ordinates
1413 are swapped.
1414
1415
1416 =for comment
1417 From: File paste.im
1418
1419 =item i_copyto_trans(C<im>, C<src>, C<x1>, C<y1>, C<x2>, C<y2>, C<tx>, C<ty>, C<trans>)
1420
1421
1422 (C<x1>,C<y1>) (C<x2>,C<y2>) specifies the region to copy (in the
1423 source coordinates) (C<tx>,C<ty>) specifies the upper left corner for
1424 the target image.  pass NULL in C<trans> for non transparent i_colors.
1425
1426
1427 =for comment
1428 From: File image.c
1429
1430 =item i_img_info(im, info)
1431
1432
1433 Return image information
1434
1435    im - Image pointer
1436    info - pointer to array to return data
1437
1438 info is an array of 4 integers with the following values:
1439
1440  info[0] - width
1441  info[1] - height
1442  info[2] - channels
1443  info[3] - channel mask
1444
1445
1446 =for comment
1447 From: File image.c
1448
1449 =item i_rubthru(C<im>, C<src>, C<tx>, C<ty>, C<src_minx>, C<src_miny>, C<src_maxx>, C<src_maxy>)
1450
1451
1452 Takes the sub image C<src>[C<src_minx>, C<src_maxx>)[C<src_miny>, C<src_maxy>)> and
1453 overlays it at (C<tx>,C<ty>) on the image object.
1454
1455 The alpha channel of each pixel in C<src> is used to control how much
1456 the existing color in C<im> is replaced, if it is 255 then the color
1457 is completely replaced, if it is 0 then the original color is left
1458 unmodified.
1459
1460
1461 =for comment
1462 From: File rubthru.im
1463
1464
1465 =back
1466
1467 =head2 Image creation/destruction
1468
1469 =over
1470
1471 =item i_img_16_new(x, y, ch)
1472
1473
1474   i_img *img = i_img_16_new(width, height, channels);
1475
1476 Create a new 16-bit/sample image.
1477
1478 Returns the image on success, or NULL on failure.
1479
1480
1481 =for comment
1482 From: File img16.c
1483
1484 =item i_img_8_new(x, y, ch)
1485
1486
1487
1488   i_img *img = i_img_8_new(width, height, channels);
1489
1490 Creates a new image object I<x> pixels wide, and I<y> pixels high with
1491 I<ch> channels.
1492
1493
1494 =for comment
1495 From: File img8.c
1496
1497 =item i_img_double_new(i_img_dim x, i_img_dim y, int ch)
1498
1499   i_img *img = i_img_double_new(width, height, channels);
1500
1501 Creates a new double per sample image.
1502
1503
1504 =for comment
1505 From: File imgdouble.c
1506
1507 =item i_img_pal_new(C<x>, C<y>, C<channels>, C<maxpal>)
1508
1509
1510   i_img *img = i_img_pal_new(width, height, channels, max_palette_size)
1511
1512 Creates a new paletted image of the supplied dimensions.
1513
1514 C<maxpal> is the maximum palette size and should normally be 256.
1515
1516 Returns a new image or NULL on failure.
1517
1518
1519 =for comment
1520 From: File palimg.c
1521
1522 =item i_sametype(C<im>, C<xsize>, C<ysize>)
1523
1524
1525   i_img *img = i_sametype(src, width, height);
1526
1527 Returns an image of the same type (sample size, channels, paletted/direct).
1528
1529 For paletted images the palette is copied from the source.
1530
1531
1532 =for comment
1533 From: File image.c
1534
1535 =item i_sametype_chans(C<im>, C<xsize>, C<ysize>, C<channels>)
1536
1537
1538   i_img *img = i_sametype_chans(src, width, height, channels);
1539
1540 Returns an image of the same type (sample size).
1541
1542 For paletted images the equivalent direct type is returned.
1543
1544
1545 =for comment
1546 From: File image.c
1547
1548 =item i_img_destroy(C<img>)
1549
1550   i_img_destroy(img)
1551
1552 Destroy an image object
1553
1554
1555 =for comment
1556 From: File image.c
1557
1558
1559 =back
1560
1561 =head2 Image Implementation
1562
1563 =over
1564
1565 =item i_img_alloc()
1566
1567 Allocates a new i_img structure.
1568
1569 When implementing a new image type perform the following steps in your
1570 image object creation function:
1571
1572 =over
1573
1574 =item 1.
1575
1576 allocate the image with i_img_alloc().
1577
1578 =item 2.
1579
1580 initialize any function pointers or other data as needed, you can
1581 overwrite the whole block if you need to.
1582
1583 =item 3.
1584
1585 initialize Imager's internal data by calling i_img_init() on the image
1586 object.
1587
1588 =back
1589
1590
1591 =for comment
1592 From: File image.c
1593
1594 =item i_img_init(C<img>)
1595
1596 Imager internal initialization of images.
1597
1598 Currently this does very little, in the future it may be used to
1599 support threads, or color profiles.
1600
1601
1602 =for comment
1603 From: File image.c
1604
1605
1606 =back
1607
1608 =head2 Image Information
1609
1610 =over
1611
1612 =item i_img_color_channels(C<im>)
1613
1614
1615 The number of channels holding color information.
1616
1617
1618 =for comment
1619 From: File immacros.h
1620
1621 =item i_img_get_height(C<im>)
1622
1623   i_img_dim height = i_img_get_height(im);
1624
1625 Returns the height in pixels of the image.
1626
1627
1628 =for comment
1629 From: File image.c
1630
1631 =item i_img_get_width(C<im>)
1632
1633   i_img_dim width = i_img_get_width(im);
1634
1635 Returns the width in pixels of the image.
1636
1637
1638 =for comment
1639 From: File image.c
1640
1641 =item i_img_getchannels(C<im>)
1642
1643   int channels = i_img_getchannels(img);
1644
1645 Get the number of channels in C<im>.
1646
1647
1648 =for comment
1649 From: File image.c
1650
1651 =item i_img_getmask(C<im>)
1652
1653   int mask = i_img_getmask(img);
1654
1655 Get the image channel mask for C<im>.
1656
1657
1658 =for comment
1659 From: File image.c
1660
1661 =item i_img_has_alpha(C<im>)
1662
1663
1664 Return true if the image has an alpha channel.
1665
1666
1667 =for comment
1668 From: File immacros.h
1669
1670 =item i_img_is_monochrome(img, &zero_is_white)
1671
1672
1673 Tests an image to check it meets our monochrome tests.
1674
1675 The idea is that a file writer can use this to test where it should
1676 write the image in whatever bi-level format it uses, eg. C<pbm> for
1677 C<pnm>.
1678
1679 For performance of encoders we require monochrome images:
1680
1681 =over
1682
1683 =item *
1684
1685 be paletted
1686
1687 =item *
1688
1689 have a palette of two colors, containing only C<(0,0,0)> and
1690 C<(255,255,255)> in either order.
1691
1692 =back
1693
1694 C<zero_is_white> is set to non-zero if the first palette entry is white.
1695
1696
1697 =for comment
1698 From: File image.c
1699
1700 =item i_img_setmask(C<im>, C<ch_mask>)
1701
1702   // only channel 0 writable 
1703   i_img_setmask(img, 0x01);
1704
1705 Set the image channel mask for C<im> to C<ch_mask>.
1706
1707 The image channel mask gives some control over which channels can be
1708 written to in the image.
1709
1710
1711 =for comment
1712 From: File image.c
1713
1714
1715 =back
1716
1717 =head2 Image quantization
1718
1719 =over
1720
1721 =item i_quant_makemap(C<quant>, C<imgs>, C<count>)
1722
1723
1724 Analyzes the C<count> images in C<imgs> according to the rules in
1725 C<quant> to build a color map (optimal or not depending on
1726 C<< quant->make_colors >>).
1727
1728
1729 =for comment
1730 From: File quant.c
1731
1732 =item i_quant_translate(C<quant>, C<img>)
1733
1734
1735 Quantize the image given the palette in C<quant>.
1736
1737 On success returns a pointer to a memory block of C<< img->xsize *
1738 img->ysize >> C<i_palidx> entries.
1739
1740 On failure returns NULL.
1741
1742 You should call myfree() on the returned block when you're done with
1743 it.
1744
1745 This function will fail if the supplied palette contains no colors.
1746
1747
1748 =for comment
1749 From: File quant.c
1750
1751 =item i_quant_transparent(C<quant>, C<data>, C<img>, C<trans_index>)
1752
1753
1754 Dither the alpha channel on C<img> into the palette indexes in
1755 C<data>.  Pixels to be transparent are replaced with C<trans_pixel>.
1756
1757 The method used depends on the tr_* members of C<quant>.
1758
1759
1760 =for comment
1761 From: File quant.c
1762
1763
1764 =back
1765
1766 =head2 Logging
1767
1768 =over
1769
1770 =item i_lhead(file, line)
1771
1772 This is an internal function called by the mm_log() macro.
1773
1774
1775 =for comment
1776 From: File log.c
1777
1778 =item i_loog(level, format, ...)
1779
1780 This is an internal function called by the mm_log() macro.
1781
1782
1783 =for comment
1784 From: File log.c
1785
1786 =item mm_log((level, format, ...))
1787
1788 This is the main entry point to logging. Note that the extra set of
1789 parentheses are required due to limitations in C89 macros.
1790
1791 This will format a string with the current file and line number to the
1792 log file if logging is enabled.
1793
1794
1795 =for comment
1796 From: File log.h
1797
1798
1799 =back
1800
1801 =head2 Paletted images
1802
1803 =over
1804
1805 =item i_addcolors(im, colors, count)
1806
1807
1808 Adds colors to the image's palette.
1809
1810 On success returns the index of the lowest color added.
1811
1812 On failure returns -1.
1813
1814 Always fails for direct color images.
1815
1816
1817 =for comment
1818 From: File imext.c
1819
1820 =item i_colorcount(im)
1821
1822
1823 Returns the number of colors in the image's palette.
1824
1825 Returns -1 for direct images.
1826
1827
1828 =for comment
1829 From: File imext.c
1830
1831 =item i_findcolor(im, color, &entry)
1832
1833
1834 Searches the images palette for the given color.
1835
1836 On success sets *I<entry> to the index of the color, and returns true.
1837
1838 On failure returns false.
1839
1840 Always fails on direct color images.
1841
1842
1843 =for comment
1844 From: File imext.c
1845
1846 =item i_getcolors(im, index, colors, count)
1847
1848
1849 Retrieves I<count> colors starting from I<index> in the image's
1850 palette.
1851
1852 On success stores the colors into I<colors> and returns true.
1853
1854 On failure returns false.
1855
1856 Always fails for direct color images.
1857
1858 Fails if there are less than I<index>+I<count> colors in the image's
1859 palette.
1860
1861
1862 =for comment
1863 From: File imext.c
1864
1865 =item i_maxcolors(im)
1866
1867
1868 Returns the maximum number of colors the palette can hold for the
1869 image.
1870
1871 Returns -1 for direct color images.
1872
1873
1874 =for comment
1875 From: File imext.c
1876
1877 =item i_setcolors(im, index, colors, count)
1878
1879
1880 Sets I<count> colors starting from I<index> in the image's palette.
1881
1882 On success returns true.
1883
1884 On failure returns false.
1885
1886 The image must have at least I<index>+I<count> colors in it's palette
1887 for this to succeed.
1888
1889 Always fails on direct color images.
1890
1891
1892 =for comment
1893 From: File imext.c
1894
1895
1896 =back
1897
1898 =head2 Tags
1899
1900 =over
1901
1902 =item i_tags_delbycode(tags, code)
1903
1904
1905 Delete any tags with the given code.
1906
1907 Returns the number of tags deleted.
1908
1909
1910 =for comment
1911 From: File tags.c
1912
1913 =item i_tags_delbyname(tags, name)
1914
1915
1916 Delete any tags with the given name.
1917
1918 Returns the number of tags deleted.
1919
1920
1921 =for comment
1922 From: File tags.c
1923
1924 =item i_tags_delete(tags, index)
1925
1926
1927 Delete a tag by index.
1928
1929 Returns true on success.
1930
1931
1932 =for comment
1933 From: File tags.c
1934
1935 =item i_tags_destroy(tags)
1936
1937
1938 Destroys the given tags structure.  Called by i_img_destroy().
1939
1940
1941 =for comment
1942 From: File tags.c
1943
1944 =item i_tags_find(tags, name, start, &entry)
1945
1946
1947 Searches for a tag of the given I<name> starting from index I<start>.
1948
1949 On success returns true and sets *I<entry>.
1950
1951 On failure returns false.
1952
1953
1954 =for comment
1955 From: File tags.c
1956
1957 =item i_tags_findn(tags, code, start, &entry)
1958
1959
1960 Searches for a tag of the given I<code> starting from index I<start>.
1961
1962 On success returns true and sets *I<entry>.
1963
1964 On failure returns false.
1965
1966
1967 =for comment
1968 From: File tags.c
1969
1970 =item i_tags_get_color(tags, name, code, &value)
1971
1972
1973 Retrieve a tag specified by name or code as color.
1974
1975 On success sets the i_color *I<value> to the color and returns true.
1976
1977 On failure returns false.
1978
1979
1980 =for comment
1981 From: File tags.c
1982
1983 =item i_tags_get_float(tags, name, code, value)
1984
1985
1986 Retrieves a tag as a floating point value.  
1987
1988 If the tag has a string value then that is parsed as a floating point
1989 number, otherwise the integer value of the tag is used.
1990
1991 On success sets *I<value> and returns true.
1992
1993 On failure returns false.
1994
1995
1996 =for comment
1997 From: File tags.c
1998
1999 =item i_tags_get_int(tags, name, code, &value)
2000
2001
2002 Retrieve a tag specified by name or code as an integer.
2003
2004 On success sets the int *I<value> to the integer and returns true.
2005
2006 On failure returns false.
2007
2008
2009 =for comment
2010 From: File tags.c
2011
2012 =item i_tags_get_string(tags, name, code, value, value_size)
2013
2014
2015 Retrieves a tag by name or code as a string.
2016
2017 On success copies the string to value for a max of value_size and
2018 returns true.
2019
2020 On failure returns false.
2021
2022 value_size must be at least large enough for a string representation
2023 of an integer.
2024
2025 The copied value is always C<NUL> terminated.
2026
2027
2028 =for comment
2029 From: File tags.c
2030
2031 =item i_tags_new(i_img_tags *tags)
2032
2033
2034 Initialize a tags structure.  Should not be used if the tags structure
2035 has been previously used.
2036
2037 This should be called tags member of an i_img object on creation (in
2038 i_img_*_new() functions).
2039
2040 To destroy the contents use i_tags_destroy()
2041
2042
2043 =for comment
2044 From: File tags.c
2045
2046 =item i_tags_set(tags, name, data, size)
2047
2048   i_tags_set(&img->tags, "i_comment", -1);
2049
2050 Sets the given tag to the string I<data>
2051
2052 If size is -1 then the strlen(I<data>) bytes are stored.
2053
2054 Even on failure, if an existing tag I<name> exists, it will be
2055 removed.
2056
2057
2058 =for comment
2059 From: File tags.c
2060
2061 =item i_tags_set_color(tags, name, code, &value)
2062
2063
2064 Stores the given color as a tag with the given name and code.
2065
2066
2067 =for comment
2068 From: File tags.c
2069
2070 =item i_tags_set_float(tags, name, code, value)
2071
2072
2073 Equivalent to i_tags_set_float2(tags, name, code, value, 30).
2074
2075
2076 =for comment
2077 From: File tags.c
2078
2079 =item i_tags_set_float2(tags, name, code, value, places)
2080
2081
2082 Sets the tag with the given name and code to the given floating point
2083 value.
2084
2085 Since tags are strings or ints, we convert the value to a string before
2086 storage at the precision specified by C<places>.
2087
2088
2089 =for comment
2090 From: File tags.c
2091
2092 =item i_tags_setn(C<tags>, C<name>, C<idata>)
2093
2094   i_tags_setn(&img->tags, "i_xres", 204);
2095   i_tags_setn(&img->tags, "i_yres", 196);
2096
2097 Sets the given tag to the integer C<idata>
2098
2099 Even on failure, if an existing tag C<name> exists, it will be
2100 removed.
2101
2102
2103 =for comment
2104 From: File tags.c
2105
2106
2107 =back
2108
2109 =head2 Uncategorized functions
2110
2111 =over
2112
2113 =item i_utf8_advance(char **p, size_t *len)
2114
2115 Retrieve a C<UTF-8> character from the stream.
2116
2117 Modifies *p and *len to indicate the consumed characters.
2118
2119 This doesn't support the extended C<UTF-8> encoding used by later
2120 versions of Perl.  Since this is typically used to implement text
2121 output by font drivers, the strings supplied shouldn't have such out
2122 of range characters.
2123
2124 This doesn't check that the C<UTF-8> character is using the shortest
2125 possible representation.
2126
2127 Returns ~0UL on failure.
2128
2129
2130 =for comment
2131 From: File io.c
2132
2133
2134
2135 =back
2136
2137
2138 =head1 AUTHOR
2139
2140 Tony Cook <tonyc@cpan.org>
2141
2142 =head1 SEE ALSO
2143
2144 Imager, Imager::ExtUtils, Imager::Inline
2145
2146 =cut