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