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