huge spelling update and spell checking patch
[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_setmask(C<im>, C<ch_mask>)
1050
1051 Set the image channel mask for C<im> to C<ch_mask>.
1052
1053 The image channel mask gives some control over which channels can be
1054 written to in the image.
1055
1056
1057 =for comment
1058 From: File image.c
1059
1060
1061 =back
1062
1063 =head2 Image quantization
1064
1065 =over
1066
1067 =item i_quant_makemap(C<quant>, C<imgs>, C<count>)
1068
1069
1070 Analyzes the C<count> images in C<imgs> according to the rules in
1071 C<quant> to build a color map (optimal or not depending on
1072 C<< quant->make_colors >>).
1073
1074
1075 =for comment
1076 From: File quant.c
1077
1078 =item i_quant_translate(C<quant>, C<img>)
1079
1080
1081 Quantize the image given the palette in C<quant>.
1082
1083 On success returns a pointer to a memory block of C<< img->xsize *
1084 img->ysize >> C<i_palidx> entries.
1085
1086 On failure returns NULL.
1087
1088 You should call myfree() on the returned block when you're done with
1089 it.
1090
1091 This function will fail if the supplied palette contains no colors.
1092
1093
1094 =for comment
1095 From: File quant.c
1096
1097 =item i_quant_transparent(C<quant>, C<data>, C<img>, C<trans_index>)
1098
1099
1100 Dither the alpha channel on C<img> into the palette indexes in
1101 C<data>.  Pixels to be transparent are replaced with C<trans_pixel>.
1102
1103 The method used depends on the tr_* members of C<quant>.
1104
1105
1106 =for comment
1107 From: File quant.c
1108
1109
1110 =back
1111
1112 =head2 Logging
1113
1114 =over
1115
1116 =item i_lhead(file, line)
1117
1118 This is an internal function called by the mm_log() macro.
1119
1120
1121 =for comment
1122 From: File log.c
1123
1124 =item i_loog(level, format, ...)
1125
1126 This is an internal function called by the mm_log() macro.
1127
1128
1129 =for comment
1130 From: File log.c
1131
1132 =item mm_log((level, format, ...))
1133
1134 This is the main entry point to logging. Note that the extra set of
1135 parentheses are required due to limitations in C89 macros.
1136
1137 This will format a string with the current file and line number to the
1138 log file if logging is enabled.
1139
1140
1141 =for comment
1142 From: File log.h
1143
1144
1145 =back
1146
1147 =head2 Paletted images
1148
1149 =over
1150
1151 =item i_addcolors(im, colors, count)
1152
1153
1154 Adds colors to the image's palette.
1155
1156 On success returns the index of the lowest color added.
1157
1158 On failure returns -1.
1159
1160 Always fails for direct color images.
1161
1162
1163 =for comment
1164 From: File imext.c
1165
1166 =item i_colorcount(im)
1167
1168
1169 Returns the number of colors in the image's palette.
1170
1171 Returns -1 for direct images.
1172
1173
1174 =for comment
1175 From: File imext.c
1176
1177 =item i_findcolor(im, color, &entry)
1178
1179
1180 Searches the images palette for the given color.
1181
1182 On success sets *I<entry> to the index of the color, and returns true.
1183
1184 On failure returns false.
1185
1186 Always fails on direct color images.
1187
1188
1189 =for comment
1190 From: File imext.c
1191
1192 =item i_getcolors(im, index, colors, count)
1193
1194
1195 Retrieves I<count> colors starting from I<index> in the image's
1196 palette.
1197
1198 On success stores the colors into I<colors> and returns true.
1199
1200 On failure returns false.
1201
1202 Always fails for direct color images.
1203
1204 Fails if there are less than I<index>+I<count> colors in the image's
1205 palette.
1206
1207
1208 =for comment
1209 From: File imext.c
1210
1211 =item i_maxcolors(im)
1212
1213
1214 Returns the maximum number of colors the palette can hold for the
1215 image.
1216
1217 Returns -1 for direct color images.
1218
1219
1220 =for comment
1221 From: File imext.c
1222
1223 =item i_setcolors(im, index, colors, count)
1224
1225
1226 Sets I<count> colors starting from I<index> in the image's palette.
1227
1228 On success returns true.
1229
1230 On failure returns false.
1231
1232 The image must have at least I<index>+I<count> colors in it's palette
1233 for this to succeed.
1234
1235 Always fails on direct color images.
1236
1237
1238 =for comment
1239 From: File imext.c
1240
1241
1242 =back
1243
1244 =head2 Tags
1245
1246 =over
1247
1248 =item i_tags_delbycode(tags, code)
1249
1250
1251 Delete any tags with the given code.
1252
1253 Returns the number of tags deleted.
1254
1255
1256 =for comment
1257 From: File tags.c
1258
1259 =item i_tags_delbyname(tags, name)
1260
1261
1262 Delete any tags with the given name.
1263
1264 Returns the number of tags deleted.
1265
1266
1267 =for comment
1268 From: File tags.c
1269
1270 =item i_tags_delete(tags, index)
1271
1272
1273 Delete a tag by index.
1274
1275 Returns true on success.
1276
1277
1278 =for comment
1279 From: File tags.c
1280
1281 =item i_tags_destroy(tags)
1282
1283
1284 Destroys the given tags structure.  Called by i_img_destroy().
1285
1286
1287 =for comment
1288 From: File tags.c
1289
1290 =item i_tags_find(tags, name, start, &entry)
1291
1292
1293 Searches for a tag of the given I<name> starting from index I<start>.
1294
1295 On success returns true and sets *I<entry>.
1296
1297 On failure returns false.
1298
1299
1300 =for comment
1301 From: File tags.c
1302
1303 =item i_tags_findn(tags, code, start, &entry)
1304
1305
1306 Searches for a tag of the given I<code> starting from index I<start>.
1307
1308 On success returns true and sets *I<entry>.
1309
1310 On failure returns false.
1311
1312
1313 =for comment
1314 From: File tags.c
1315
1316 =item i_tags_get_color(tags, name, code, &value)
1317
1318
1319 Retrieve a tag specified by name or code as color.
1320
1321 On success sets the i_color *I<value> to the color and returns true.
1322
1323 On failure returns false.
1324
1325
1326 =for comment
1327 From: File tags.c
1328
1329 =item i_tags_get_float(tags, name, code, value)
1330
1331
1332 Retrieves a tag as a floating point value.  
1333
1334 If the tag has a string value then that is parsed as a floating point
1335 number, otherwise the integer value of the tag is used.
1336
1337 On success sets *I<value> and returns true.
1338
1339 On failure returns false.
1340
1341
1342 =for comment
1343 From: File tags.c
1344
1345 =item i_tags_get_int(tags, name, code, &value)
1346
1347
1348 Retrieve a tag specified by name or code as an integer.
1349
1350 On success sets the int *I<value> to the integer and returns true.
1351
1352 On failure returns false.
1353
1354
1355 =for comment
1356 From: File tags.c
1357
1358 =item i_tags_get_string(tags, name, code, value, value_size)
1359
1360
1361 Retrieves a tag by name or code as a string.
1362
1363 On success copies the string to value for a max of value_size and
1364 returns true.
1365
1366 On failure returns false.
1367
1368 value_size must be at least large enough for a string representation
1369 of an integer.
1370
1371 The copied value is always C<NUL> terminated.
1372
1373
1374 =for comment
1375 From: File tags.c
1376
1377 =item i_tags_new(i_img_tags *tags)
1378
1379
1380 Initialize a tags structure.  Should not be used if the tags structure
1381 has been previously used.
1382
1383 This should be called tags member of an i_img object on creation (in
1384 i_img_*_new() functions).
1385
1386 To destroy the contents use i_tags_destroy()
1387
1388
1389 =for comment
1390 From: File tags.c
1391
1392 =item i_tags_set(tags, name, data, size)
1393
1394 Sets the given tag to the string I<data>
1395
1396 If size is -1 then the strlen(I<data>) bytes are stored.
1397
1398 Even on failure, if an existing tag I<name> exists, it will be
1399 removed.
1400
1401
1402 =for comment
1403 From: File tags.c
1404
1405 =item i_tags_set_color(tags, name, code, &value)
1406
1407
1408 Stores the given color as a tag with the given name and code.
1409
1410
1411 =for comment
1412 From: File tags.c
1413
1414 =item i_tags_set_float(tags, name, code, value)
1415
1416
1417 Equivalent to i_tags_set_float2(tags, name, code, value, 30).
1418
1419
1420 =for comment
1421 From: File tags.c
1422
1423 =item i_tags_set_float2(tags, name, code, value, places)
1424
1425
1426 Sets the tag with the given name and code to the given floating point
1427 value.
1428
1429 Since tags are strings or ints, we convert the value to a string before
1430 storage at the precision specified by C<places>.
1431
1432
1433 =for comment
1434 From: File tags.c
1435
1436 =item i_tags_setn(C<tags>, C<name>, C<idata>)
1437
1438 Sets the given tag to the integer C<idata>
1439
1440 Even on failure, if an existing tag C<name> exists, it will be
1441 removed.
1442
1443
1444 =for comment
1445 From: File tags.c
1446
1447
1448 =back
1449
1450
1451 =head1 AUTHOR
1452
1453 Tony Cook <tony@imager.perl.org>
1454
1455 =head1 SEE ALSO
1456
1457 Imager, Imager::ExtUtils, Imager::Inline
1458
1459 =cut