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