move JPEG into it's 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   # 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_gsampf_bg(im, l, r, y, samples, out_channels, background)
492
493
494 Like C<i_gsampf()> but applies the source image color over a supplied
495 background color.
496
497 This is intended for output to image formats that don't support alpha
498 channels.
499
500
501 =for comment
502 From: File paste.im
503
504 =item i_line(C<im>, C<x1>, C<y1>, C<x2>, C<y2>, C<color>, C<endp>)
505
506
507 =for stopwords Bresenham's
508
509 Draw a line to image using Bresenham's line drawing algorithm
510
511    im    - image to draw to
512    x1    - starting x coordinate
513    y1    - starting x coordinate
514    x2    - starting x coordinate
515    y2    - starting x coordinate
516    color - color to write to image
517    endp  - endpoint flag (boolean)
518
519
520 =for comment
521 From: File draw.c
522
523 =item i_line_aa(C<im>, C<x1>, C<x2>, C<y1>, C<y2>, C<color>, C<endp>)
524
525
526 Anti-alias draws a line from (x1,y1) to (x2, y2) in color.
527
528 The point (x2, y2) is drawn only if C<endp> is set.
529
530
531 =for comment
532 From: File draw.c
533
534 =item i_plin(im, l, r, y, colors)
535
536
537 Sets (r-l) pixels starting from (l,y) using (r-l) values from
538 I<colors>.
539
540 Returns the number of pixels set.
541
542
543 =for comment
544 From: File imext.c
545
546 =item i_plinf(im, C<left>, C<right>, C<fcolors>)
547
548
549 Sets (right-left) pixels starting from (left,y) using (right-left)
550 floating point colors from C<fcolors>.
551
552 Returns the number of pixels set.
553
554
555 =for comment
556 From: File imext.c
557
558 =item i_ppal(im, left, right, y, indexes)
559
560
561 Writes palette indexes for the horizontal line (left, y) to (right-1,
562 y) from C<indexes>.
563
564 Returns the number of indexes written.
565
566 Always returns 0 for direct color images.
567
568
569 =for comment
570 From: File imext.c
571
572 =item i_ppix(im, x, y, color)
573
574
575 Sets the pixel at (x,y) to I<color>.
576
577 Returns 0 if the pixel was drawn, or -1 if not.
578
579 Does no alpha blending, just copies the channels from the supplied
580 color to the image.
581
582
583 =for comment
584 From: File imext.c
585
586 =item i_ppixf(im, C<x>, C<y>, C<fcolor>)
587
588
589 Sets the pixel at (C<x>,C<y>) to the floating point color C<fcolor>.
590
591 Returns 0 if the pixel was drawn, or -1 if not.
592
593 Does no alpha blending, just copies the channels from the supplied
594 color to the image.
595
596
597 =for comment
598 From: File imext.c
599
600
601 =back
602
603 =head2 Error handling
604
605 =over
606
607 =item i_clear_error()
608
609 Clears the error stack.
610
611 Called by any Imager function before doing any other processing.
612
613
614 =for comment
615 From: File error.c
616
617 =item i_push_error(int code, char const *msg)
618
619 Called by an Imager function to push an error message onto the stack.
620
621 No message is pushed if the stack is full (since this means someone
622 forgot to call i_clear_error(), or that a function that doesn't do
623 error handling is calling function that does.).
624
625
626 =for comment
627 From: File error.c
628
629 =item i_push_errorf(int code, char const *fmt, ...)
630
631 A version of i_push_error() that does printf() like formatting.
632
633 Does not support perl specific format codes.
634
635
636 =for comment
637 From: File error.c
638
639 =item i_push_errorvf(int C<code>, char const *C<fmt>, va_list C<ap>)
640
641
642 Intended for use by higher level functions, takes a varargs pointer
643 and a format to produce the finally pushed error message.
644
645 Does not support perl specific format codes.
646
647
648 =for comment
649 From: File error.c
650
651
652 =back
653
654 =head2 Files
655
656 =over
657
658 =item i_get_file_background(im, &bg)
659
660
661 Retrieve the file write background color tag from the image.
662
663 If not present, returns black.
664
665
666 =for comment
667 From: File image.c
668
669 =item i_get_file_backgroundf(im, &bg)
670
671
672 Retrieve the file write background color tag from the image as a
673 floating point color.
674
675 Implemented in terms of i_get_file_background().
676
677 If not present, returns black.
678
679
680 =for comment
681 From: File image.c
682
683 =item i_get_image_file_limits(&width, &height, &bytes)
684
685
686 Retrieves the file limits set by i_set_image_file_limits().
687
688
689 =for comment
690 From: File limits.c
691
692 =item i_int_check_image_file_limits(width, height, channels, sample_size)
693
694
695 Checks the size of a file in memory against the configured image file
696 limits.
697
698 This also range checks the values to those permitted by Imager and
699 checks for overflows in calculating the size.
700
701 Returns non-zero if the file is within limits.
702
703 This function is intended to be called by image file read functions.
704
705
706 =for comment
707 From: File limits.c
708
709 =item i_set_image_file_limits(width, height, bytes)
710
711
712 Set limits on the sizes of images read by Imager.
713
714 Setting a limit to 0 means that limit is ignored.
715
716 Negative limits result in failure.
717
718 Returns non-zero on success.
719
720
721 =for comment
722 From: File limits.c
723
724
725 =back
726
727 =head2 Fills
728
729 =over
730
731 =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>)
732
733
734
735 Creates a new general fill which fills with a fountain fill.
736
737
738 =for comment
739 From: File filters.im
740
741 =item i_new_fill_hatch(C<fg>, C<bg>, C<combine>, C<hatch>, C<cust_hatch>, C<dx>, C<dy>)
742
743
744 Creates a new hatched fill with the C<fg> color used for the 1 bits in
745 the hatch and C<bg> for the 0 bits.  If C<combine> is non-zero alpha
746 values will be combined.
747
748 If C<cust_hatch> is non-NULL it should be a pointer to 8 bytes of the
749 hash definition, with the high-bits to the left.
750
751 If C<cust_hatch> is NULL then one of the standard hatches is used.
752
753 (C<dx>, C<dy>) are an offset into the hatch which can be used to hatch
754 adjoining areas out of alignment, or to align the origin of a hatch
755 with the the side of a filled area.
756
757
758 =for comment
759 From: File fills.c
760
761 =item i_new_fill_hatchf(C<fg>, C<bg>, C<combine>, C<hatch>, C<cust_hatch>, C<dx>, C<dy>)
762
763
764 Creates a new hatched fill with the C<fg> color used for the 1 bits in
765 the hatch and C<bg> for the 0 bits.  If C<combine> is non-zero alpha
766 values will be combined.
767
768 If C<cust_hatch> is non-NULL it should be a pointer to 8 bytes of the
769 hash definition, with the high-bits to the left.
770
771 If C<cust_hatch> is NULL then one of the standard hatches is used.
772
773 (C<dx>, C<dy>) are an offset into the hatch which can be used to hatch
774 adjoining areas out of alignment, or to align the origin of a hatch
775 with the the side of a filled area.
776
777
778 =for comment
779 From: File fills.c
780
781 =item i_new_fill_image(C<im>, C<matrix>, C<xoff>, C<yoff>, C<combine>)
782
783
784 Create an image based fill.
785
786 matrix is an array of 9 doubles representing a transformation matrix.
787
788 C<xoff> and C<yoff> are the offset into the image to start filling from.
789
790
791 =for comment
792 From: File fills.c
793
794 =item i_new_fill_solid(color, combine)
795
796
797 Create a solid fill based on an 8-bit color.
798
799 If combine is non-zero then alpha values will be combined.
800
801
802 =for comment
803 From: File fills.c
804
805 =item i_new_fill_solidf(color, combine)
806
807
808 Create a solid fill based on a float color.
809
810 If combine is non-zero then alpha values will be combined.
811
812
813 =for comment
814 From: File fills.c
815
816 =item i_fill_destroy(fill)
817
818 Call to destroy any fill object.
819
820
821 =for comment
822 From: File fills.c
823
824
825 =back
826
827 =head2 Image
828
829 =over
830
831 =item i_copy(source)
832
833
834 Creates a new image that is a copy of the image C<source>.
835
836 Tags are not copied, only the image data.
837
838 Returns: i_img *
839
840
841 =for comment
842 From: File image.c
843
844 =item i_copyto(C<dest>, C<src>, C<x1>, C<y1>, C<x2>, C<y2>, C<tx>, C<ty>)
845
846
847 Copies image data from the area (C<x1>,C<y1>)-[C<x2>,C<y2>] in the
848 source image to a rectangle the same size with it's top-left corner at
849 (C<tx>,C<ty>) in the destination image.
850
851 If C<x1> > C<x2> or C<y1> > C<y2> then the corresponding co-ordinates
852 are swapped.
853
854
855 =for comment
856 From: File paste.im
857
858 =item i_copyto_trans(C<im>, C<src>, C<x1>, C<y1>, C<x2>, C<y2>, C<tx>, C<ty>, C<trans>)
859
860
861 (C<x1>,C<y1>) (C<x2>,C<y2>) specifies the region to copy (in the
862 source coordinates) (C<tx>,C<ty>) specifies the upper left corner for
863 the target image.  pass NULL in C<trans> for non transparent i_colors.
864
865
866 =for comment
867 From: File image.c
868
869 =item i_img_info(im, info)
870
871
872 Return image information
873
874    im - Image pointer
875    info - pointer to array to return data
876
877 info is an array of 4 integers with the following values:
878
879  info[0] - width
880  info[1] - height
881  info[2] - channels
882  info[3] - channel mask
883
884
885 =for comment
886 From: File image.c
887
888 =item i_rubthru(C<im>, C<src>, C<tx>, C<ty>, C<src_minx>, C<src_miny>, C<src_maxx>, C<src_maxy>)
889
890
891 Takes the sub image C<src>[C<src_minx>, C<src_maxx>)[C<src_miny>, C<src_maxy>)> and
892 overlays it at (C<tx>,C<ty>) on the image object.
893
894 The alpha channel of each pixel in C<src> is used to control how much
895 the existing color in C<im> is replaced, if it is 255 then the color
896 is completely replaced, if it is 0 then the original color is left
897 unmodified.
898
899
900 =for comment
901 From: File rubthru.im
902
903
904 =back
905
906 =head2 Image creation/destruction
907
908 =over
909
910 =item i_img_16_new(x, y, ch)
911
912
913 Create a new 16-bit/sample image.
914
915 Returns the image on success, or NULL on failure.
916
917
918 =for comment
919 From: File img16.c
920
921 =item i_img_8_new(x, y, ch)
922
923
924
925 Creates a new image object I<x> pixels wide, and I<y> pixels high with
926 I<ch> channels.
927
928
929 =for comment
930 From: File image.c
931
932 =item i_img_double_new(int x, int y, int ch)
933
934 Creates a new double per sample image.
935
936
937 =for comment
938 From: File imgdouble.c
939
940 =item i_img_pal_new(C<x>, C<y>, C<channels>, C<maxpal>)
941
942
943 Creates a new paletted image of the supplied dimensions.
944
945 C<maxpal> is the maximum palette size and should normally be 256.
946
947 Returns a new image or NULL on failure.
948
949
950 =for comment
951 From: File palimg.c
952
953 =item i_sametype(C<im>, C<xsize>, C<ysize>)
954
955
956 Returns an image of the same type (sample size, channels, paletted/direct).
957
958 For paletted images the palette is copied from the source.
959
960
961 =for comment
962 From: File image.c
963
964 =item i_sametype_chans(C<im>, C<xsize>, C<ysize>, C<channels>)
965
966
967 Returns an image of the same type (sample size).
968
969 For paletted images the equivalent direct type is returned.
970
971
972 =for comment
973 From: File image.c
974
975 =item i_img_destroy(C<img>)
976
977 Destroy an image object
978
979
980 =for comment
981 From: File image.c
982
983
984 =back
985
986 =head2 Image Implementation
987
988 =over
989
990 =item i_img_alloc()
991
992 Allocates a new i_img structure.
993
994 When implementing a new image type perform the following steps in your
995 image object creation function:
996
997 =over
998
999 =item 1.
1000
1001 allocate the image with i_img_alloc().
1002
1003 =item 2.
1004
1005 initialize any function pointers or other data as needed, you can
1006 overwrite the whole block if you need to.
1007
1008 =item 3.
1009
1010 initialize Imager's internal data by calling i_img_init() on the image
1011 object.
1012
1013 =back
1014
1015
1016 =for comment
1017 From: File image.c
1018
1019 =item i_img_init(C<img>)
1020
1021 Imager internal initialization of images.
1022
1023 Currently this does very little, in the future it may be used to
1024 support threads, or color profiles.
1025
1026
1027 =for comment
1028 From: File image.c
1029
1030
1031 =back
1032
1033 =head2 Image Information
1034
1035 =over
1036
1037 =item i_img_color_channels(C<im>)
1038
1039
1040 The number of channels holding color information.
1041
1042
1043 =for comment
1044 From: File immacros.h
1045
1046 =item i_img_get_height(C<im>)
1047
1048 Returns the height in pixels of the image.
1049
1050
1051 =for comment
1052 From: File image.c
1053
1054 =item i_img_get_width(C<im>)
1055
1056 Returns the width in pixels of the image.
1057
1058
1059 =for comment
1060 From: File image.c
1061
1062 =item i_img_getchannels(C<im>)
1063
1064 Get the number of channels in C<im>.
1065
1066
1067 =for comment
1068 From: File image.c
1069
1070 =item i_img_getmask(C<im>)
1071
1072 Get the image channel mask for C<im>.
1073
1074
1075 =for comment
1076 From: File image.c
1077
1078 =item i_img_has_alpha(C<im>)
1079
1080
1081 Return true if the image has an alpha channel.
1082
1083
1084 =for comment
1085 From: File immacros.h
1086
1087 =item i_img_is_monochrome(img, &zero_is_white)
1088
1089
1090 Tests an image to check it meets our monochrome tests.
1091
1092 The idea is that a file writer can use this to test where it should
1093 write the image in whatever bi-level format it uses, eg. C<pbm> for
1094 C<pnm>.
1095
1096 For performance of encoders we require monochrome images:
1097
1098 =over
1099
1100 =item *
1101
1102 be paletted
1103
1104 =item *
1105
1106 have a palette of two colors, containing only C<(0,0,0)> and
1107 C<(255,255,255)> in either order.
1108
1109 =back
1110
1111 C<zero_is_white> is set to non-zero if the first palette entry is white.
1112
1113
1114 =for comment
1115 From: File image.c
1116
1117 =item i_img_setmask(C<im>, C<ch_mask>)
1118
1119 Set the image channel mask for C<im> to C<ch_mask>.
1120
1121 The image channel mask gives some control over which channels can be
1122 written to in the image.
1123
1124
1125 =for comment
1126 From: File image.c
1127
1128
1129 =back
1130
1131 =head2 Image quantization
1132
1133 =over
1134
1135 =item i_quant_makemap(C<quant>, C<imgs>, C<count>)
1136
1137
1138 Analyzes the C<count> images in C<imgs> according to the rules in
1139 C<quant> to build a color map (optimal or not depending on
1140 C<< quant->make_colors >>).
1141
1142
1143 =for comment
1144 From: File quant.c
1145
1146 =item i_quant_translate(C<quant>, C<img>)
1147
1148
1149 Quantize the image given the palette in C<quant>.
1150
1151 On success returns a pointer to a memory block of C<< img->xsize *
1152 img->ysize >> C<i_palidx> entries.
1153
1154 On failure returns NULL.
1155
1156 You should call myfree() on the returned block when you're done with
1157 it.
1158
1159 This function will fail if the supplied palette contains no colors.
1160
1161
1162 =for comment
1163 From: File quant.c
1164
1165 =item i_quant_transparent(C<quant>, C<data>, C<img>, C<trans_index>)
1166
1167
1168 Dither the alpha channel on C<img> into the palette indexes in
1169 C<data>.  Pixels to be transparent are replaced with C<trans_pixel>.
1170
1171 The method used depends on the tr_* members of C<quant>.
1172
1173
1174 =for comment
1175 From: File quant.c
1176
1177
1178 =back
1179
1180 =head2 Logging
1181
1182 =over
1183
1184 =item i_lhead(file, line)
1185
1186 This is an internal function called by the mm_log() macro.
1187
1188
1189 =for comment
1190 From: File log.c
1191
1192 =item i_loog(level, format, ...)
1193
1194 This is an internal function called by the mm_log() macro.
1195
1196
1197 =for comment
1198 From: File log.c
1199
1200 =item mm_log((level, format, ...))
1201
1202 This is the main entry point to logging. Note that the extra set of
1203 parentheses are required due to limitations in C89 macros.
1204
1205 This will format a string with the current file and line number to the
1206 log file if logging is enabled.
1207
1208
1209 =for comment
1210 From: File log.h
1211
1212
1213 =back
1214
1215 =head2 Paletted images
1216
1217 =over
1218
1219 =item i_addcolors(im, colors, count)
1220
1221
1222 Adds colors to the image's palette.
1223
1224 On success returns the index of the lowest color added.
1225
1226 On failure returns -1.
1227
1228 Always fails for direct color images.
1229
1230
1231 =for comment
1232 From: File imext.c
1233
1234 =item i_colorcount(im)
1235
1236
1237 Returns the number of colors in the image's palette.
1238
1239 Returns -1 for direct images.
1240
1241
1242 =for comment
1243 From: File imext.c
1244
1245 =item i_findcolor(im, color, &entry)
1246
1247
1248 Searches the images palette for the given color.
1249
1250 On success sets *I<entry> to the index of the color, and returns true.
1251
1252 On failure returns false.
1253
1254 Always fails on direct color images.
1255
1256
1257 =for comment
1258 From: File imext.c
1259
1260 =item i_getcolors(im, index, colors, count)
1261
1262
1263 Retrieves I<count> colors starting from I<index> in the image's
1264 palette.
1265
1266 On success stores the colors into I<colors> and returns true.
1267
1268 On failure returns false.
1269
1270 Always fails for direct color images.
1271
1272 Fails if there are less than I<index>+I<count> colors in the image's
1273 palette.
1274
1275
1276 =for comment
1277 From: File imext.c
1278
1279 =item i_maxcolors(im)
1280
1281
1282 Returns the maximum number of colors the palette can hold for the
1283 image.
1284
1285 Returns -1 for direct color images.
1286
1287
1288 =for comment
1289 From: File imext.c
1290
1291 =item i_setcolors(im, index, colors, count)
1292
1293
1294 Sets I<count> colors starting from I<index> in the image's palette.
1295
1296 On success returns true.
1297
1298 On failure returns false.
1299
1300 The image must have at least I<index>+I<count> colors in it's palette
1301 for this to succeed.
1302
1303 Always fails on direct color images.
1304
1305
1306 =for comment
1307 From: File imext.c
1308
1309
1310 =back
1311
1312 =head2 Tags
1313
1314 =over
1315
1316 =item i_tags_delbycode(tags, code)
1317
1318
1319 Delete any tags with the given code.
1320
1321 Returns the number of tags deleted.
1322
1323
1324 =for comment
1325 From: File tags.c
1326
1327 =item i_tags_delbyname(tags, name)
1328
1329
1330 Delete any tags with the given name.
1331
1332 Returns the number of tags deleted.
1333
1334
1335 =for comment
1336 From: File tags.c
1337
1338 =item i_tags_delete(tags, index)
1339
1340
1341 Delete a tag by index.
1342
1343 Returns true on success.
1344
1345
1346 =for comment
1347 From: File tags.c
1348
1349 =item i_tags_destroy(tags)
1350
1351
1352 Destroys the given tags structure.  Called by i_img_destroy().
1353
1354
1355 =for comment
1356 From: File tags.c
1357
1358 =item i_tags_find(tags, name, start, &entry)
1359
1360
1361 Searches for a tag of the given I<name> starting from index I<start>.
1362
1363 On success returns true and sets *I<entry>.
1364
1365 On failure returns false.
1366
1367
1368 =for comment
1369 From: File tags.c
1370
1371 =item i_tags_findn(tags, code, start, &entry)
1372
1373
1374 Searches for a tag of the given I<code> starting from index I<start>.
1375
1376 On success returns true and sets *I<entry>.
1377
1378 On failure returns false.
1379
1380
1381 =for comment
1382 From: File tags.c
1383
1384 =item i_tags_get_color(tags, name, code, &value)
1385
1386
1387 Retrieve a tag specified by name or code as color.
1388
1389 On success sets the i_color *I<value> to the color and returns true.
1390
1391 On failure returns false.
1392
1393
1394 =for comment
1395 From: File tags.c
1396
1397 =item i_tags_get_float(tags, name, code, value)
1398
1399
1400 Retrieves a tag as a floating point value.  
1401
1402 If the tag has a string value then that is parsed as a floating point
1403 number, otherwise the integer value of the tag is used.
1404
1405 On success sets *I<value> and returns true.
1406
1407 On failure returns false.
1408
1409
1410 =for comment
1411 From: File tags.c
1412
1413 =item i_tags_get_int(tags, name, code, &value)
1414
1415
1416 Retrieve a tag specified by name or code as an integer.
1417
1418 On success sets the int *I<value> to the integer and returns true.
1419
1420 On failure returns false.
1421
1422
1423 =for comment
1424 From: File tags.c
1425
1426 =item i_tags_get_string(tags, name, code, value, value_size)
1427
1428
1429 Retrieves a tag by name or code as a string.
1430
1431 On success copies the string to value for a max of value_size and
1432 returns true.
1433
1434 On failure returns false.
1435
1436 value_size must be at least large enough for a string representation
1437 of an integer.
1438
1439 The copied value is always C<NUL> terminated.
1440
1441
1442 =for comment
1443 From: File tags.c
1444
1445 =item i_tags_new(i_img_tags *tags)
1446
1447
1448 Initialize a tags structure.  Should not be used if the tags structure
1449 has been previously used.
1450
1451 This should be called tags member of an i_img object on creation (in
1452 i_img_*_new() functions).
1453
1454 To destroy the contents use i_tags_destroy()
1455
1456
1457 =for comment
1458 From: File tags.c
1459
1460 =item i_tags_set(tags, name, data, size)
1461
1462 Sets the given tag to the string I<data>
1463
1464 If size is -1 then the strlen(I<data>) bytes are stored.
1465
1466 Even on failure, if an existing tag I<name> exists, it will be
1467 removed.
1468
1469
1470 =for comment
1471 From: File tags.c
1472
1473 =item i_tags_set_color(tags, name, code, &value)
1474
1475
1476 Stores the given color as a tag with the given name and code.
1477
1478
1479 =for comment
1480 From: File tags.c
1481
1482 =item i_tags_set_float(tags, name, code, value)
1483
1484
1485 Equivalent to i_tags_set_float2(tags, name, code, value, 30).
1486
1487
1488 =for comment
1489 From: File tags.c
1490
1491 =item i_tags_set_float2(tags, name, code, value, places)
1492
1493
1494 Sets the tag with the given name and code to the given floating point
1495 value.
1496
1497 Since tags are strings or ints, we convert the value to a string before
1498 storage at the precision specified by C<places>.
1499
1500
1501 =for comment
1502 From: File tags.c
1503
1504 =item i_tags_setn(C<tags>, C<name>, C<idata>)
1505
1506 Sets the given tag to the integer C<idata>
1507
1508 Even on failure, if an existing tag C<name> exists, it will be
1509 removed.
1510
1511
1512 =for comment
1513 From: File tags.c
1514
1515
1516 =back
1517
1518
1519 =head1 UNDOCUMENTED
1520
1521 The following API functions are undocumented so far, hopefully this
1522 will change:
1523
1524 =over
1525
1526 =item *
1527
1528 B<i_gsamp_bg>
1529
1530
1531
1532 =back
1533
1534
1535 =head1 AUTHOR
1536
1537 Tony Cook <tony@imager.perl.org>
1538
1539 =head1 SEE ALSO
1540
1541 Imager, Imager::ExtUtils, Imager::Inline
1542
1543 =cut