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