add the context slot APIs
[imager.git] / lib / Imager / APIRef.pod
1 Do not edit this file, it is generated automatically by apidocs.perl
2 from Imager's source files.
3
4 Each function description has a comment listing the source file where
5 you can find the documentation.
6
7 =head1 NAME
8
9 Imager::APIRef - Imager's C API - reference.
10
11 =head1 SYNOPSIS
12
13   i_color color;
14   color.rgba.r = 255; color.rgba.g = 0; color.rgba.b = 255;
15
16
17   # Blit tools
18
19   # Data Types
20   i_img *img;
21   i_color black;
22   black.rgba.r = black.rgba.g = black.rgba.b = black.rgba.a = 0;
23   i_fill_t *fill;
24   i_img_dim x, y;
25   printf("left %" i_DF "\n", i_DFc(x));
26   printf("point (" i_DFp ")\n", i_DFcp(x, y));
27
28   # Drawing
29   i_arc(im, 50, 50, 20, 45, 135, &color);
30   i_arc_cfill(im, 50, 50, 35, 90, 135, fill);
31   i_arc_aa(im, 50, 50, 35, 90, 135, &color);
32   i_arc_aa_cfill(im, 50, 50, 35, 90, 135, fill);
33   i_circle_aa(im, 50, 50, 45, &color);
34   i_box(im, 0, 0, im->xsize-1, im->ysize-1, &color).
35   i_box_filled(im, 0, 0, im->xsize-1, im->ysize-1, &color);
36   i_box_cfill(im, 0, 0, im->xsize-1, im->ysize-1, fill);
37   i_flood_fill(im, 50, 50, &color);
38   i_flood_cfill(im, 50, 50, fill);
39   i_flood_fill_border(im, 50, 50, &color, &border);
40   i_flood_cfill_border(im, 50, 50, fill, border);
41
42   # Error handling
43   im_clear_error(aIMCTX);
44   i_clear_error();
45   i_push_error(0, "Yep, it's broken");
46   i_push_error(errno, "Error writing");
47   im_push_error(aIMCTX, 0, "Something is wrong");
48   va_args args;
49   va_start(args, lastarg);
50   im_push_errorvf(ctx, code, format, args);
51   i_push_errorf(errno, "Cannot open file %s: %d", filename, errno);
52   im_push_errorf(aIMCTX, errno, "Cannot open file %s: %d", filename, errno);
53
54   # Files
55   im_set_image_file_limits(aIMCTX, 500, 500, 1000000);
56   i_set_image_file_limits(500, 500, 1000000);
57   im_get_image_file_limits(aIMCTX, &width, &height, &bytes)
58   i_get_image_file_limits(&width, &height, &bytes)
59   im_int_check_image_file_limits(aIMCTX, width, height, channels, sizeof(i_sample_t))
60   i_int_check_image_file_limits(width, height, channels, sizeof(i_sample_t))
61
62   # Fills
63   i_fill_t *fill = i_new_fill_solidf(&fcolor, combine);
64   i_fill_t *fill = i_new_fill_solid(&color, combine);
65   i_fill_t *fill = i_new_fill_hatch(&fg_color, &bg_color, combine, hatch, custom_hatch, dx, dy);
66   i_fill_t *fill = i_new_fill_hatchf(&fg_fcolor, &bg_fcolor, combine, hatch, custom_hatch, dx, dy);
67   i_fill_t *fill = i_new_fill_image(src_img, matrix, x_offset, y_offset, combine);
68   fill = i_new_fill_fount(0, 0, 100, 100, i_ft_linear, i_ft_linear, 
69                           i_fr_triangle, 0, i_fts_grid, 9, 1, segs);
70   i_fill_destroy(fill);
71
72   # I/O Layers
73   ssize_t count = i_io_peekn(ig, buffer, sizeof(buffer));
74   ssize_t result = i_io_write(io, buffer, size)
75   char buffer[BUFSIZ]
76   ssize_t len = i_io_gets(buffer, sizeof(buffer), '\n');
77   io_glue_destroy(ig);
78
79   # Image
80
81   # Image creation/destruction
82   i_img *img = i_sametype(src, width, height);
83   i_img *img = i_sametype_chans(src, width, height, channels);
84   i_img *img = im_img_16_new(aIMCTX, width, height, channels);
85   i_img *img = i_img_16_new(width, height, channels);
86   i_img *img = im_img_8_new(aIMCTX, width, height, channels);
87   i_img *img = i_img_8_new(width, height, channels);
88   i_img *img = im_img_double_new(aIMCTX, width, height, channels);
89   i_img *img = i_img_double_new(width, height, channels);
90   i_img *img = im_img_pal_new(aIMCTX, width, height, channels, max_palette_size)
91   i_img *img = i_img_pal_new(width, height, channels, max_palette_size)
92   i_img_destroy(img)
93
94   # Image Implementation
95   i_img *im = im_img_alloc(aIMCTX);
96   i_img *im = i_img_alloc();
97   im_img_init(aIMCTX, im);
98   i_img_init(im);
99
100   # Image Information
101   // only channel 0 writable 
102   i_img_setmask(img, 0x01);
103   int mask = i_img_getmask(img);
104   int channels = i_img_getchannels(img);
105   i_img_dim width = i_img_get_width(im);
106   i_img_dim height = i_img_get_height(im);
107
108   # Image quantization
109
110   # Logging
111
112   # Mutex functions
113   i_mutex_t m = i_mutex_new();
114   i_mutex_destroy(m);
115   i_mutex_lock(m);
116   i_mutex_unlock(m);
117
118   # Paletted images
119
120   # Tags
121   i_tags_set(&img->tags, "i_comment", -1);
122   i_tags_setn(&img->tags, "i_xres", 204);
123   i_tags_setn(&img->tags, "i_yres", 196);
124
125 =head1 DESCRIPTION
126
127 =head2 Blit tools
128
129 =over
130
131 =item i_render_color(r, x, y, width, source, color)
132
133 Render the given color with the coverage specified by C<source[0]> to
134 C<source[width-1]>.
135
136 Renders in normal combine mode.
137
138
139 =for comment
140 From: File render.im
141
142 =item i_render_delete(r)
143
144 Release an C<i_render> object.
145
146
147 =for comment
148 From: File render.im
149
150 =item i_render_fill(r, x, y, width, source, fill)
151
152 Render the given fill with the coverage in C<source[0]> through
153 C<source[width-1]>.
154
155
156 =for comment
157 From: File render.im
158
159 =item i_render_line(r, x, y, width, source, fill)
160
161 Render the given fill with the coverage in C<source[0]> through
162 C<source[width-1]>.
163
164
165 =for comment
166 From: File render.im
167
168 =item i_render_linef(r, x, y, width, source, fill)
169
170 Render the given fill with the coverage in C<source[0]> through
171 C<source[width-1]>.
172
173
174 =for comment
175 From: File render.im
176
177 =item i_render_new(im, width)
178
179 Allocate a new C<i_render> object and initialize it.
180
181
182 =for comment
183 From: File render.im
184
185
186 =back
187
188 =head2 Data Types
189
190 =over
191
192 =item i_img
193
194   i_img *img;
195
196 This is Imager's image type.
197
198 It contains the following members:
199
200 =over
201
202 =item *
203
204 C<channels> - the number of channels in the image
205
206 =item *
207
208 C<xsize>, C<ysize> - the width and height of the image in pixels
209
210 =item *
211
212 C<bytes> - the number of bytes used to store the image data.  Undefined
213 where virtual is non-zero.
214
215 =item *
216
217 C<ch_mask> - a mask of writable channels.  eg. if this is 6 then only
218 channels 1 and 2 are writable.  There may be bits set for which there
219 are no channels in the image.
220
221 =item *
222
223 C<bits> - the number of bits stored per sample.  Should be one of
224 i_8_bits, i_16_bits, i_double_bits.
225
226 =item *
227
228 C<type> - either i_direct_type for direct color images, or i_palette_type
229 for paletted images.
230
231 =item *
232
233 C<virtual> - if zero then this image is-self contained.  If non-zero
234 then this image could be an interface to some other implementation.
235
236 =item *
237
238 C<idata> - the image data.  This should not be directly accessed.  A new
239 image implementation can use this to store its image data.
240 i_img_destroy() will myfree() this pointer if it's non-null.
241
242 =item *
243
244 C<tags> - a structure storing the image's tags.  This should only be
245 accessed via the i_tags_*() functions.
246
247 =item *
248
249 C<ext_data> - a pointer for use internal to an image implementation.
250 This should be freed by the image's destroy handler.
251
252 =item *
253
254 C<im_data> - data internal to Imager.  This is initialized by
255 i_img_init().
256
257 =item *
258
259 i_f_ppix, i_f_ppixf, i_f_plin, i_f_plinf, i_f_gpix, i_f_gpixf,
260 i_f_glin, i_f_glinf, i_f_gsamp, i_f_gampf - implementations for each
261 of the required image functions.  An image implementation should
262 initialize these between calling i_img_alloc() and i_img_init().
263
264 =item *
265
266 i_f_gpal, i_f_ppal, i_f_addcolors, i_f_getcolors, i_f_colorcount,
267 i_f_maxcolors, i_f_findcolor, i_f_setcolors - implementations for each
268 paletted image function.
269
270 =item *
271
272 i_f_destroy - custom image destruction function.  This should be used
273 to release memory if necessary.
274
275 =item *
276
277 i_f_gsamp_bits - implements i_gsamp_bits() for this image.
278
279 =item *
280
281 i_f_psamp_bits - implements i_psamp_bits() for this image.
282
283 =item *
284
285 i_f_psamp - implements psamp() for this image.
286
287 =item *
288
289 i_f_psampf - implements psamp() for this image.
290
291 =item *
292
293 C<im_data> - image specific data internal to Imager.
294
295 =item *
296
297 C<context> - the Imager API context this image belongs to.
298
299 =back
300
301
302 =for comment
303 From: File imdatatypes.h
304
305 =item i_color
306
307   i_color black;
308   black.rgba.r = black.rgba.g = black.rgba.b = black.rgba.a = 0;
309
310 Type for 8-bit/sample color.
311
312 Samples as per;
313
314   i_color c;
315
316 i_color is a union of:
317
318 =over
319
320 =item *
321
322 gray - contains a single element gray_color, eg. C<c.gray.gray_color>
323
324 =item *
325
326 C<rgb> - contains three elements C<r>, C<g>, C<b>, eg. C<c.rgb.r>
327
328 =item *
329
330 C<rgba> - contains four elements C<r>, C<g>, C<b>, C<a>, eg. C<c.rgba.a>
331
332 =item *
333
334 C<cmyk> - contains four elements C<c>, C<m>, C<y>, C<k>,
335 eg. C<c.cmyk.y>.  Note that Imager never uses CMYK colors except when
336 reading/writing files.
337
338 =item *
339
340 channels - an array of four channels, eg C<c.channels[2]>.
341
342 =back
343
344
345 =for comment
346 From: File imdatatypes.h
347
348 =item i_fcolor
349
350 This is the double/sample color type.
351
352 Its layout exactly corresponds to i_color.
353
354
355 =for comment
356 From: File imdatatypes.h
357
358 =item i_fill_t
359
360   i_fill_t *fill;
361
362 This is the "abstract" base type for Imager's fill types.
363
364 Unless you're implementing a new fill type you'll typically treat this
365 as an opaque type.
366
367
368 =for comment
369 From: File imdatatypes.h
370
371 =item i_img_dim
372
373   i_img_dim x, y;
374
375 A signed integer type that represents an image dimension or ordinate.
376
377 May be larger than int on some platforms.
378
379
380 =for comment
381 From: File imdatatypes.h
382
383 =item i_DF
384
385   printf("left %" i_DF "\n", i_DFc(x));
386
387 This is a constant string that can be used with functions like
388 printf() to format i_img_dim values after they're been cast with i_DFc().
389
390 Does not include the leading C<%>.
391
392
393 =for comment
394 From: File imdatatypes.h
395
396 =item i_DFc
397
398 Cast an C<i_img_dim> value to a type for use with the i_DF format
399 string.
400
401
402 =for comment
403 From: File imdatatypes.h
404
405 =item i_DFcp
406
407 Casts two C<i_img_dim> values for use with the i_DF (or i_DFp) format.
408
409
410 =for comment
411 From: File imdatatypes.h
412
413 =item i_DFp
414
415   printf("point (" i_DFp ")\n", i_DFcp(x, y));
416
417 Format a pair of C<i_img_dim> values.  This format string I<does>
418 include the leading C<%>.
419
420
421 =for comment
422 From: File imdatatypes.h
423
424
425 =back
426
427 =head2 Drawing
428
429 =over
430
431 =item i_arc(im, x, y, rad, d1, d2, color)
432
433
434   i_arc(im, 50, 50, 20, 45, 135, &color);
435
436 Fills an arc centered at (x,y) with radius I<rad> covering the range
437 of angles in degrees from d1 to d2, with the color.
438
439
440 =for comment
441 From: File draw.c
442
443 =item i_arc_aa(im, x, y, rad, d1, d2, color)
444
445
446   i_arc_aa(im, 50, 50, 35, 90, 135, &color);
447
448 Anti-alias fills an arc centered at (x,y) with radius I<rad> covering
449 the range of angles in degrees from d1 to d2, with the color.
450
451
452 =for comment
453 From: File draw.c
454
455 =item i_arc_aa_cfill(im, x, y, rad, d1, d2, fill)
456
457
458   i_arc_aa_cfill(im, 50, 50, 35, 90, 135, fill);
459
460 Anti-alias fills an arc centered at (x,y) with radius I<rad> covering
461 the range of angles in degrees from d1 to d2, with the fill object.
462
463
464 =for comment
465 From: File draw.c
466
467 =item i_arc_cfill(im, x, y, rad, d1, d2, fill)
468
469
470   i_arc_cfill(im, 50, 50, 35, 90, 135, fill);
471
472 Fills an arc centered at (x,y) with radius I<rad> covering the range
473 of angles in degrees from d1 to d2, with the fill object.
474
475
476 =for comment
477 From: File draw.c
478
479 =item i_box(im, x1, y1, x2, y2, color)
480
481
482   i_box(im, 0, 0, im->xsize-1, im->ysize-1, &color).
483
484 Outlines the box from (x1,y1) to (x2,y2) inclusive with I<color>.
485
486
487 =for comment
488 From: File draw.c
489
490 =item i_box_cfill(im, x1, y1, x2, y2, fill)
491
492
493   i_box_cfill(im, 0, 0, im->xsize-1, im->ysize-1, fill);
494
495 Fills the box from (x1,y1) to (x2,y2) inclusive with fill.
496
497
498 =for comment
499 From: File draw.c
500
501 =item i_box_filled(im, x1, y1, x2, y2, color)
502
503
504   i_box_filled(im, 0, 0, im->xsize-1, im->ysize-1, &color);
505
506 Fills the box from (x1,y1) to (x2,y2) inclusive with color.
507
508
509 =for comment
510 From: File draw.c
511
512 =item i_circle_aa(im, x, y, rad, color)
513
514
515   i_circle_aa(im, 50, 50, 45, &color);
516
517 Anti-alias fills a circle centered at (x,y) for radius I<rad> with
518 color.
519
520
521 =for comment
522 From: File draw.c
523
524 =item i_flood_cfill(C<im>, C<seedx>, C<seedy>, C<fill>)
525
526
527   i_flood_cfill(im, 50, 50, fill);
528
529 Flood fills the 4-connected region starting from the point (C<seedx>,
530 C<seedy>) with C<fill>.
531
532 Returns false if (C<seedx>, C<seedy>) are outside the image.
533
534
535 =for comment
536 From: File draw.c
537
538 =item i_flood_cfill_border(C<im>, C<seedx>, C<seedy>, C<fill>, C<border>)
539
540
541   i_flood_cfill_border(im, 50, 50, fill, border);
542
543 Flood fills the 4-connected region starting from the point (C<seedx>,
544 C<seedy>) with C<fill>, the fill stops when it reaches pixels of color
545 C<border>.
546
547 Returns false if (C<seedx>, C<seedy>) are outside the image.
548
549
550 =for comment
551 From: File draw.c
552
553 =item i_flood_fill(C<im>, C<seedx>, C<seedy>, C<color>)
554
555
556   i_flood_fill(im, 50, 50, &color);
557
558 Flood fills the 4-connected region starting from the point (C<seedx>,
559 C<seedy>) with I<color>.
560
561 Returns false if (C<seedx>, C<seedy>) are outside the image.
562
563
564 =for comment
565 From: File draw.c
566
567 =item i_flood_fill_border(C<im>, C<seedx>, C<seedy>, C<color>, C<border>)
568
569
570   i_flood_fill_border(im, 50, 50, &color, &border);
571
572 Flood fills the 4-connected region starting from the point (C<seedx>,
573 C<seedy>) with C<color>, fill stops when the fill reaches a pixels
574 with color C<border>.
575
576 Returns false if (C<seedx>, C<seedy>) are outside the image.
577
578
579 =for comment
580 From: File draw.c
581
582 =item i_glin(im, l, r, y, colors)
583
584
585 Retrieves (r-l) pixels starting from (l,y) into I<colors>.
586
587 Returns the number of pixels retrieved.
588
589
590 =for comment
591 From: File imext.c
592
593 =item i_glinf(im, l, r, y, colors)
594
595
596 Retrieves (r-l) pixels starting from (l,y) into I<colors> as floating
597 point colors.
598
599 Returns the number of pixels retrieved.
600
601
602 =for comment
603 From: File imext.c
604
605 =item i_gpal(im, left, right, y, indexes)
606
607
608 Reads palette indexes for the horizontal line (left, y) to (right-1,
609 y) into C<indexes>.
610
611 Returns the number of indexes read.
612
613 Always returns 0 for direct color images.
614
615
616 =for comment
617 From: File imext.c
618
619 =item i_gpix(im, C<x>, C<y>, C<color>)
620
621
622 Retrieves the C<color> of the pixel (x,y).
623
624 Returns 0 if the pixel was retrieved, or -1 if not.
625
626
627 =for comment
628 From: File imext.c
629
630 =item i_gpixf(im, C<x>, C<y>, C<fcolor>)
631
632
633 Retrieves the color of the pixel (x,y) as a floating point color into
634 C<fcolor>.
635
636 Returns 0 if the pixel was retrieved, or -1 if not.
637
638
639 =for comment
640 From: File imext.c
641
642 =item i_gsamp(im, left, right, y, samples, channels, channel_count)
643
644
645 Reads sample values from C<im> for the horizontal line (left, y) to
646 (right-1,y) for the channels specified by C<channels>, an array of int
647 with C<channel_count> elements.
648
649 If channels is NULL then the first channels_count channels are retrieved for
650 each pixel.
651
652 Returns the number of samples read (which should be (right-left) *
653 channel_count)
654
655
656 =for comment
657 From: File imext.c
658
659 =item i_gsamp_bg(im, l, r, y, samples, out_channels, background)
660
661
662 Like C<i_gsampf()> but applies the source image color over a supplied
663 background color.
664
665 This is intended for output to image formats that don't support alpha
666 channels.
667
668
669 =for comment
670 From: File paste.im
671
672 =item i_gsamp_bits(im, left, right, y, samples, channels, channel_count, bits)
673
674 Reads integer samples scaled to C<bits> bits of precision into the
675 C<unsigned int> array C<samples>.
676
677 Expect this to be slow unless C<< bits == im->bits >>.
678
679 Returns the number of samples copied, or -1 on error.
680
681 Not all image types implement this method.
682
683 Pushes errors, but does not call C<i_clear_error()>.
684
685
686 =for comment
687 From: File imext.c
688
689 =item i_gsampf(im, left, right, y, samples, channels, channel_count)
690
691
692 Reads floating point sample values from C<im> for the horizontal line
693 (left, y) to (right-1,y) for the channels specified by C<channels>, an
694 array of int with channel_count elements.
695
696 If C<channels> is NULL then the first C<channel_count> channels are
697 retrieved for each pixel.
698
699 Returns the number of samples read (which should be (C<right>-C<left>)
700 * C<channel_count>)
701
702
703 =for comment
704 From: File imext.c
705
706 =item i_gsampf_bg(im, l, r, y, samples, out_channels, background)
707
708
709 Like C<i_gsampf()> but applies the source image color over a supplied
710 background color.
711
712 This is intended for output to image formats that don't support alpha
713 channels.
714
715
716 =for comment
717 From: File paste.im
718
719 =item i_line(C<im>, C<x1>, C<y1>, C<x2>, C<y2>, C<color>, C<endp>)
720
721
722 =for stopwords Bresenham's
723
724 Draw a line to image using Bresenham's line drawing algorithm
725
726    im    - image to draw to
727    x1    - starting x coordinate
728    y1    - starting x coordinate
729    x2    - starting x coordinate
730    y2    - starting x coordinate
731    color - color to write to image
732    endp  - endpoint flag (boolean)
733
734
735 =for comment
736 From: File draw.c
737
738 =item i_line_aa(C<im>, C<x1>, C<x2>, C<y1>, C<y2>, C<color>, C<endp>)
739
740
741 Anti-alias draws a line from (x1,y1) to (x2, y2) in color.
742
743 The point (x2, y2) is drawn only if C<endp> is set.
744
745
746 =for comment
747 From: File draw.c
748
749 =item i_plin(im, l, r, y, colors)
750
751
752 Sets (r-l) pixels starting from (l,y) using (r-l) values from
753 I<colors>.
754
755 Returns the number of pixels set.
756
757
758 =for comment
759 From: File imext.c
760
761 =item i_plinf(im, C<left>, C<right>, C<fcolors>)
762
763
764 Sets (right-left) pixels starting from (left,y) using (right-left)
765 floating point colors from C<fcolors>.
766
767 Returns the number of pixels set.
768
769
770 =for comment
771 From: File imext.c
772
773 =item i_ppal(im, left, right, y, indexes)
774
775
776 Writes palette indexes for the horizontal line (left, y) to (right-1,
777 y) from C<indexes>.
778
779 Returns the number of indexes written.
780
781 Always returns 0 for direct color images.
782
783
784 =for comment
785 From: File imext.c
786
787 =item i_ppix(im, x, y, color)
788
789
790 Sets the pixel at (x,y) to I<color>.
791
792 Returns 0 if the pixel was drawn, or -1 if not.
793
794 Does no alpha blending, just copies the channels from the supplied
795 color to the image.
796
797
798 =for comment
799 From: File imext.c
800
801 =item i_ppixf(im, C<x>, C<y>, C<fcolor>)
802
803
804 Sets the pixel at (C<x>,C<y>) to the floating point color C<fcolor>.
805
806 Returns 0 if the pixel was drawn, or -1 if not.
807
808 Does no alpha blending, just copies the channels from the supplied
809 color to the image.
810
811
812 =for comment
813 From: File imext.c
814
815 =item i_psamp(im, left, right, y, samples, channels, channel_count)
816
817 Writes sample values from C<samples> to C<im> for the horizontal line
818 (left, y) to (right-1, y) inclusive for the channels specified by
819 C<channels>, an array of C<int> with C<channel_count> elements.
820
821 If C<channels> is C<NULL> then the first C<channels_count> channels
822 are written to for each pixel.
823
824 Returns the number of samples written, which should be (right - left)
825 * channel_count.  If a channel not in the image is in channels, left
826 is negative, left is outside the image or y is outside the image,
827 returns -1 and pushes an error.
828
829
830 =for comment
831 From: File immacros.h
832
833 =item i_psamp_bits(im, left, right, y, samples, channels, channel_count, bits)
834
835 Writes integer samples scaled to C<bits> bits of precision from the
836 C<unsigned int> array C<samples>.
837
838 Expect this to be slow unless C<< bits == im->bits >>.
839
840 Returns the number of samples copied, or -1 on error.
841
842 Not all image types implement this method.
843
844 Pushes errors, but does not call C<i_clear_error()>.
845
846
847 =for comment
848 From: File imext.c
849
850 =item i_psampf(im, left, right, y, samples, channels, channel_count)
851
852 Writes floating point sample values from C<samples> to C<im> for the
853 horizontal line (left, y) to (right-1, y) inclusive for the channels
854 specified by C<channels>, an array of C<int> with C<channel_count>
855 elements.
856
857 If C<channels> is C<NULL> then the first C<channels_count> channels
858 are written to for each pixel.
859
860 Returns the number of samples written, which should be (right - left)
861 * channel_count.  If a channel not in the image is in channels, left
862 is negative, left is outside the image or y is outside the image,
863 returns -1 and pushes an error.
864
865
866 =for comment
867 From: File immacros.h
868
869
870 =back
871
872 =head2 Error handling
873
874 =over
875
876 =item i_push_errorf(int code, char const *fmt, ...)
877
878   i_push_errorf(errno, "Cannot open file %s: %d", filename, errno);
879
880 A version of i_push_error() that does printf() like formatting.
881
882 Does not support perl specific format codes.
883
884
885 =for comment
886 From: File error.c
887
888 =item im_clear_error(ctx)
889 X<im_clear_error API>X<i_clear_error API>
890
891   im_clear_error(aIMCTX);
892   i_clear_error();
893
894 Clears the error stack.
895
896 Called by any Imager function before doing any other processing.
897
898 Also callable as C<i_clear_error()>.
899
900
901 =for comment
902 From: File error.c
903
904 =item im_push_error(ctx, code, message)
905 X<im_push_error API>X<i_push_error API>
906
907   i_push_error(0, "Yep, it's broken");
908   i_push_error(errno, "Error writing");
909   im_push_error(aIMCTX, 0, "Something is wrong");
910
911 Called by an Imager function to push an error message onto the stack.
912
913 No message is pushed if the stack is full (since this means someone
914 forgot to call i_clear_error(), or that a function that doesn't do
915 error handling is calling function that does.).
916
917
918 =for comment
919 From: File error.c
920
921 =item im_push_errorf(ctx, code, char const *fmt, ...)
922
923   im_push_errorf(aIMCTX, errno, "Cannot open file %s: %d", filename, errno);
924
925 A version of im_push_error() that does printf() like formatting.
926
927 Does not support perl specific format codes.
928
929
930 =for comment
931 From: File error.c
932
933 =item im_push_errorvf(ctx, code, format, args)
934 X<im_push_error_vf API>X<i_push_errorvf API>
935
936   va_args args;
937   va_start(args, lastarg);
938   im_push_errorvf(ctx, code, format, args);
939
940 Intended for use by higher level functions, takes a varargs pointer
941 and a format to produce the finally pushed error message.
942
943 Does not support perl specific format codes.
944
945 Also callable as C<i_push_errorvf(code, format, args)>
946
947
948 =for comment
949 From: File error.c
950
951
952 =back
953
954 =head2 Files
955
956 =over
957
958 =item i_get_file_background(im, &bg)
959
960
961 Retrieve the file write background color tag from the image.
962
963 If not present, C<bg> is set to black.
964
965 Returns 1 if the C<i_background> tag was found and valid.
966
967
968 =for comment
969 From: File image.c
970
971 =item i_get_file_backgroundf(im, &bg)
972
973
974 Retrieve the file write background color tag from the image as a
975 floating point color.
976
977 Implemented in terms of i_get_file_background().
978
979 If not present, C<bg> is set to black.
980
981 Returns 1 if the C<i_background> tag was found and valid.
982
983
984 =for comment
985 From: File image.c
986
987 =item im_get_image_file_limits(ctx, &width, &height, &bytes)
988 X<im_get_image_file_limits API>X<i_get_image_file_limits>
989
990   im_get_image_file_limits(aIMCTX, &width, &height, &bytes)
991   i_get_image_file_limits(&width, &height, &bytes)
992
993 Retrieves the file limits set by i_set_image_file_limits().
994
995 =over
996
997 =item *
998
999 i_img_dim *width, *height - the maximum width and height of the image.
1000
1001 =item *
1002
1003 size_t *bytes - size in memory of the image in bytes.
1004
1005 =back
1006
1007 Also callable as C<i_get_image_file_limits(&width, &height, &bytes)>.
1008
1009
1010 =for comment
1011 From: File limits.c
1012
1013 =item im_int_check_image_file_limits(width, height, channels, sample_size)
1014 X<im_int_check_image_file_limits API>X<i_int_check_image_file_limits>
1015
1016   im_int_check_image_file_limits(aIMCTX, width, height, channels, sizeof(i_sample_t))
1017   i_int_check_image_file_limits(width, height, channels, sizeof(i_sample_t))
1018
1019 Checks the size of a file in memory against the configured image file
1020 limits.
1021
1022 This also range checks the values to those permitted by Imager and
1023 checks for overflows in calculating the size.
1024
1025 Returns non-zero if the file is within limits.
1026
1027 This function is intended to be called by image file read functions.
1028
1029 Also callable as C<i_int_check_image_file_limits(width, height, channels, sizeof(i_sample_t)>.
1030
1031
1032 =for comment
1033 From: File limits.c
1034
1035 =item im_set_image_file_limits(ctx, width, height, bytes)
1036 X<im_set_image_file_limits API>X<i_set_image_file_limits API>
1037
1038   im_set_image_file_limits(aIMCTX, 500, 500, 1000000);
1039   i_set_image_file_limits(500, 500, 1000000);
1040
1041 Set limits on the sizes of images read by Imager.
1042
1043 Setting a limit to 0 means that limit is ignored.
1044
1045 Negative limits result in failure.
1046
1047 Parameters:
1048
1049 =over
1050
1051 =item *
1052
1053 i_img_dim width, height - maximum width and height.
1054
1055 =item *
1056
1057 size_t bytes - maximum size in memory in bytes.  A value of zero sets
1058 this limit to one gigabyte.
1059
1060 =back
1061
1062 Returns non-zero on success.
1063
1064 Also callable as C<i_set_image_file_limits(width, height, bytes)>.
1065
1066
1067 =for comment
1068 From: File limits.c
1069
1070
1071 =back
1072
1073 =head2 Fills
1074
1075 =over
1076
1077 =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>)
1078
1079
1080   fill = i_new_fill_fount(0, 0, 100, 100, i_ft_linear, i_ft_linear, 
1081                           i_fr_triangle, 0, i_fts_grid, 9, 1, segs);
1082
1083
1084 Creates a new general fill which fills with a fountain fill.
1085
1086
1087 =for comment
1088 From: File filters.im
1089
1090 =item i_new_fill_hatch(C<fg>, C<bg>, C<combine>, C<hatch>, C<cust_hatch>, C<dx>, C<dy>)
1091
1092
1093   i_fill_t *fill = i_new_fill_hatch(&fg_color, &bg_color, combine, hatch, custom_hatch, dx, dy);
1094
1095 Creates a new hatched fill with the C<fg> color used for the 1 bits in
1096 the hatch and C<bg> for the 0 bits.  If C<combine> is non-zero alpha
1097 values will be combined.
1098
1099 If C<cust_hatch> is non-NULL it should be a pointer to 8 bytes of the
1100 hash definition, with the high-bits to the left.
1101
1102 If C<cust_hatch> is NULL then one of the standard hatches is used.
1103
1104 (C<dx>, C<dy>) are an offset into the hatch which can be used to hatch
1105 adjoining areas out of alignment, or to align the origin of a hatch
1106 with the the side of a filled area.
1107
1108
1109 =for comment
1110 From: File fills.c
1111
1112 =item i_new_fill_hatchf(C<fg>, C<bg>, C<combine>, C<hatch>, C<cust_hatch>, C<dx>, C<dy>)
1113
1114
1115   i_fill_t *fill = i_new_fill_hatchf(&fg_fcolor, &bg_fcolor, combine, hatch, custom_hatch, dx, dy);
1116
1117 Creates a new hatched fill with the C<fg> color used for the 1 bits in
1118 the hatch and C<bg> for the 0 bits.  If C<combine> is non-zero alpha
1119 values will be combined.
1120
1121 If C<cust_hatch> is non-NULL it should be a pointer to 8 bytes of the
1122 hash definition, with the high-bits to the left.
1123
1124 If C<cust_hatch> is NULL then one of the standard hatches is used.
1125
1126 (C<dx>, C<dy>) are an offset into the hatch which can be used to hatch
1127 adjoining areas out of alignment, or to align the origin of a hatch
1128 with the the side of a filled area.
1129
1130
1131 =for comment
1132 From: File fills.c
1133
1134 =item i_new_fill_image(C<im>, C<matrix>, C<xoff>, C<yoff>, C<combine>)
1135
1136
1137   i_fill_t *fill = i_new_fill_image(src_img, matrix, x_offset, y_offset, combine);
1138
1139 Create an image based fill.
1140
1141 matrix is an array of 9 doubles representing a transformation matrix.
1142
1143 C<xoff> and C<yoff> are the offset into the image to start filling from.
1144
1145
1146 =for comment
1147 From: File fills.c
1148
1149 =item i_new_fill_solid(color, combine)
1150
1151
1152   i_fill_t *fill = i_new_fill_solid(&color, combine);
1153
1154 Create a solid fill based on an 8-bit color.
1155
1156 If combine is non-zero then alpha values will be combined.
1157
1158
1159 =for comment
1160 From: File fills.c
1161
1162 =item i_new_fill_solidf(color, combine)
1163
1164
1165   i_fill_t *fill = i_new_fill_solidf(&fcolor, combine);
1166
1167 Create a solid fill based on a float color.
1168
1169 If combine is non-zero then alpha values will be combined.
1170
1171
1172 =for comment
1173 From: File fills.c
1174
1175 =item i_fill_destroy(fill)
1176
1177   i_fill_destroy(fill);
1178
1179 Call to destroy any fill object.
1180
1181
1182 =for comment
1183 From: File fills.c
1184
1185
1186 =back
1187
1188 =head2 I/O Layers
1189
1190 =over
1191
1192 =item im_io_new_bufchain(ctx)
1193 X<im_io_new_bufchain API>X<i_io_new_bufchain API>
1194
1195 Returns a new io_glue object that has the 'empty' source and but can
1196 be written to and read from later (like a pseudo file).
1197
1198 Also callable as C<io_new_bufchain()>.
1199
1200
1201 =for comment
1202 From: File iolayer.c
1203
1204 =item im_io_new_buffer(ctx, data, length)
1205 X<im_io_new_buffer API>X<io_new_buffer API>
1206
1207 Returns a new io_glue object that has the source defined as reading
1208 from specified buffer.  Note that the buffer is not copied.
1209
1210    ctx - an Imager context object
1211    data - buffer to read from
1212    length - length of buffer
1213
1214 Also callable as C<io_new_buffer(data, length>.
1215
1216
1217 =for comment
1218 From: File iolayer.c
1219
1220 =item im_io_new_cb(ctx, p, read_cb, write_cb, seek_cb, close_cb, destroy_cb)
1221 X<im_io_new_cb API>X<io_new_cb API>
1222
1223 Create a new I/O layer object that calls your supplied callbacks.
1224
1225 In general the callbacks should behave like the corresponding POSIX
1226 primitives.
1227
1228 =over
1229
1230 =item *
1231
1232 C<read_cb>(p, buffer, length) should read up to C<length> bytes into
1233 C<buffer> and return the number of bytes read.  At end of file, return
1234 0.  On error, return -1.
1235
1236 =item *
1237
1238 C<write_cb>(p, buffer, length) should write up to C<length> bytes from
1239 C<buffer> and return the number of bytes written.  A return value <= 0
1240 will be treated as an error.
1241
1242 =item *
1243
1244 C<seekcb>(p, offset, whence) should seek and return the new offset.
1245
1246 =item *
1247
1248 C<close_cb>(p) should return 0 on success, -1 on failure.
1249
1250 =item *
1251
1252 C<destroy_cb>(p) should release any memory specific to your callback
1253 handlers.
1254
1255 =back
1256
1257 Also callable as C<io_new_cb(p, readcb, writecb, seekcb, closecb,
1258 destroycb)>.
1259
1260
1261 =for comment
1262 From: File iolayer.c
1263
1264 =item im_io_new_fd(ctx, file)
1265 X<io_new_fd API>X<im_io_new_fd API>
1266
1267 Returns a new io_glue object that has the source defined as reading
1268 from specified file descriptor.  Note that the the interface to receiving
1269 data from the io_glue callbacks hasn't been done yet.
1270
1271   ctx - and Imager context object
1272   file - file descriptor to read/write from
1273
1274 Also callable as C<io_new_fd(file)>.
1275
1276
1277 =for comment
1278 From: File iolayer.c
1279
1280 =item i_io_close(io)
1281
1282 Flush any pending output and perform the close action for the stream.
1283
1284 Returns 0 on success.
1285
1286
1287 =for comment
1288 From: File iolayer.c
1289
1290 =item i_io_flush(io)
1291
1292 Flush any buffered output.
1293
1294 Returns true on success,
1295
1296
1297 =for comment
1298 From: File iolayer.c
1299
1300 =item i_io_getc(ig)
1301
1302 A macro to read a single byte from a buffered I/O glue object.
1303
1304 Returns EOF on failure, or a byte.
1305
1306
1307 =for comment
1308 From: File iolayer.c
1309
1310 =item i_io_gets(ig, buffer, size, end_of_line)
1311
1312   char buffer[BUFSIZ]
1313   ssize_t len = i_io_gets(buffer, sizeof(buffer), '\n');
1314
1315 Read up to C<size>-1 bytes from the stream C<ig> into C<buffer>.
1316
1317 If the byte C<end_of_line> is seen then no further bytes will be read.
1318
1319 Returns the number of bytes read.
1320
1321 Always C<NUL> terminates the buffer.
1322
1323
1324 =for comment
1325 From: File iolayer.c
1326
1327 =item i_io_peekc(ig)
1328
1329 Read the next character from the stream without advancing the stream.
1330
1331 On error or end of file, return EOF.
1332
1333 For unbuffered streams a single character buffer will be setup.
1334
1335
1336 =for comment
1337 From: File iolayer.c
1338
1339 =item i_io_peekn(ig, buffer, size)
1340
1341   ssize_t count = i_io_peekn(ig, buffer, sizeof(buffer));
1342
1343 Buffer at least C<size> (at most C<< ig->buf_size >> bytes of data
1344 from the stream and return C<size> bytes of it to the caller in
1345 C<buffer>.
1346
1347 This ignores the buffered state of the stream, and will always setup
1348 buffering if needed.
1349
1350 If no C<type> parameter is provided to Imager::read() or
1351 Imager::read_multi(), Imager will call C<i_io_peekn()> when probing
1352 for the file format.
1353
1354 Returns -1 on error, 0 if there is no data before EOF, or the number
1355 of bytes read into C<buffer>.
1356
1357
1358 =for comment
1359 From: File iolayer.c
1360
1361 =item i_io_putc(ig, c)
1362
1363 Write a single character to the stream.
1364
1365 On success return c, on error returns EOF
1366
1367
1368 =for comment
1369 From: File iolayer.c
1370
1371 =item i_io_read(io, buffer, size)
1372
1373 Read up to C<size> bytes from the stream C<io> into C<buffer>.
1374
1375 Returns the number of bytes read.  Returns 0 on end of file.  Returns
1376 -1 on error.
1377
1378
1379 =for comment
1380 From: File iolayer.c
1381
1382 =item i_io_seek(io, offset, whence)
1383
1384 Seek within the stream.
1385
1386 Acts like perl's seek.
1387
1388
1389 =for comment
1390 From: File iolayer.c
1391
1392 =item i_io_set_buffered(io, buffered)
1393
1394 Set the buffering mode of the stream.
1395
1396 If you switch buffering off on a stream with buffering on:
1397
1398 =over
1399
1400 =item *
1401
1402 any buffered output will be flushed.
1403
1404 =item *
1405
1406 any existing buffered input will be consumed before reads become
1407 unbuffered.
1408
1409 =back
1410
1411 Returns true on success.  This may fail if any buffered output cannot
1412 be flushed.
1413
1414
1415 =for comment
1416 From: File iolayer.c
1417
1418 =item i_io_write(io, buffer, size)
1419
1420   ssize_t result = i_io_write(io, buffer, size)
1421
1422 Write to the given I/O stream.
1423
1424 Returns the number of bytes written.
1425
1426
1427 =for comment
1428 From: File iolayer.c
1429
1430 =item io_slurp(ig, c)
1431 X<io_slurp API>
1432
1433 Takes the source that the io_glue is bound to and allocates space for
1434 a return buffer and returns the entire content in a single buffer.
1435 Note: This only works for io_glue objects created by
1436 io_new_bufchain().  It is useful for saving to scalars and such.
1437
1438    ig - io_glue object
1439    c  - pointer to a pointer to where data should be copied to
1440
1441   char *data;
1442   size_t size = io_slurp(ig, &data);
1443   ... do something with the data ...
1444   myfree(data);
1445
1446 io_slurp() will abort the program if the supplied I/O layer is not
1447 from io_new_bufchain().
1448
1449
1450 =for comment
1451 From: File iolayer.c
1452
1453 =item io_glue_destroy(ig)
1454 X<io_glue_destroy API>
1455
1456   io_glue_destroy(ig);
1457
1458 Destroy an io_glue objects.  Should clean up all related buffers.
1459
1460    ig - io_glue object to destroy.
1461
1462
1463 =for comment
1464 From: File iolayer.c
1465
1466
1467 =back
1468
1469 =head2 Image
1470
1471 =over
1472
1473 =item i_copy(source)
1474
1475
1476 Creates a new image that is a copy of the image C<source>.
1477
1478 Tags are not copied, only the image data.
1479
1480 Returns: i_img *
1481
1482
1483 =for comment
1484 From: File image.c
1485
1486 =item i_copyto(C<dest>, C<src>, C<x1>, C<y1>, C<x2>, C<y2>, C<tx>, C<ty>)
1487
1488
1489 Copies image data from the area (C<x1>,C<y1>)-[C<x2>,C<y2>] in the
1490 source image to a rectangle the same size with it's top-left corner at
1491 (C<tx>,C<ty>) in the destination image.
1492
1493 If C<x1> > C<x2> or C<y1> > C<y2> then the corresponding co-ordinates
1494 are swapped.
1495
1496
1497 =for comment
1498 From: File paste.im
1499
1500 =item i_copyto_trans(C<im>, C<src>, C<x1>, C<y1>, C<x2>, C<y2>, C<tx>, C<ty>, C<trans>)
1501
1502
1503 (C<x1>,C<y1>) (C<x2>,C<y2>) specifies the region to copy (in the
1504 source coordinates) (C<tx>,C<ty>) specifies the upper left corner for
1505 the target image.  pass NULL in C<trans> for non transparent i_colors.
1506
1507
1508 =for comment
1509 From: File image.c
1510
1511 =item i_img_info(im, info)
1512
1513
1514 Return image information
1515
1516    im - Image pointer
1517    info - pointer to array to return data
1518
1519 info is an array of 4 integers with the following values:
1520
1521  info[0] - width
1522  info[1] - height
1523  info[2] - channels
1524  info[3] - channel mask
1525
1526
1527 =for comment
1528 From: File image.c
1529
1530 =item i_rubthru(C<im>, C<src>, C<tx>, C<ty>, C<src_minx>, C<src_miny>, C<src_maxx>, C<src_maxy>)
1531
1532
1533 Takes the sub image C<src>[C<src_minx>, C<src_maxx>)[C<src_miny>, C<src_maxy>)> and
1534 overlays it at (C<tx>,C<ty>) on the image object.
1535
1536 The alpha channel of each pixel in C<src> is used to control how much
1537 the existing color in C<im> is replaced, if it is 255 then the color
1538 is completely replaced, if it is 0 then the original color is left
1539 unmodified.
1540
1541
1542 =for comment
1543 From: File rubthru.im
1544
1545
1546 =back
1547
1548 =head2 Image creation/destruction
1549
1550 =over
1551
1552 =item i_sametype(C<im>, C<xsize>, C<ysize>)
1553
1554
1555   i_img *img = i_sametype(src, width, height);
1556
1557 Returns an image of the same type (sample size, channels, paletted/direct).
1558
1559 For paletted images the palette is copied from the source.
1560
1561
1562 =for comment
1563 From: File image.c
1564
1565 =item i_sametype_chans(C<im>, C<xsize>, C<ysize>, C<channels>)
1566
1567
1568   i_img *img = i_sametype_chans(src, width, height, channels);
1569
1570 Returns an image of the same type (sample size).
1571
1572 For paletted images the equivalent direct type is returned.
1573
1574
1575 =for comment
1576 From: File image.c
1577
1578 =item im_img_16_new(ctx, x, y, ch)
1579 X<im_img_16_new API>X<i_img_16_new API>
1580
1581   i_img *img = im_img_16_new(aIMCTX, width, height, channels);
1582   i_img *img = i_img_16_new(width, height, channels);
1583
1584 Create a new 16-bit/sample image.
1585
1586 Returns the image on success, or NULL on failure.
1587
1588 Also callable as C<i_img_16_new(x, y, ch)>
1589
1590
1591 =for comment
1592 From: File img16.c
1593
1594 =item im_img_8_new(ctx, x, y, ch)
1595 X<im_img_8_new API>X<i_img_8_new API>
1596
1597   i_img *img = im_img_8_new(aIMCTX, width, height, channels);
1598   i_img *img = i_img_8_new(width, height, channels);
1599
1600 Creates a new image object I<x> pixels wide, and I<y> pixels high with
1601 I<ch> channels.
1602
1603
1604 =for comment
1605 From: File img8.c
1606
1607 =item im_img_double_new(ctx, x, y, ch)
1608 X<im_img_double_new API>X<i_img_double_new API>
1609
1610   i_img *img = im_img_double_new(aIMCTX, width, height, channels);
1611   i_img *img = i_img_double_new(width, height, channels);
1612
1613 Creates a new double per sample image.
1614
1615 Also callable as C<i_img_double_new(width, height, channels)>.
1616
1617
1618 =for comment
1619 From: File imgdouble.c
1620
1621 =item im_img_pal_new(ctx, C<x>, C<y>, C<channels>, C<maxpal>)
1622 X<im_img_pal_new API>X<i_img_pal_new API>
1623
1624   i_img *img = im_img_pal_new(aIMCTX, width, height, channels, max_palette_size)
1625   i_img *img = i_img_pal_new(width, height, channels, max_palette_size)
1626
1627 Creates a new paletted image of the supplied dimensions.
1628
1629 C<maxpal> is the maximum palette size and should normally be 256.
1630
1631 Returns a new image or NULL on failure.
1632
1633 Also callable as C<i_img_pal_new(width, height, channels, max_palette_size)>.
1634
1635
1636 =for comment
1637 From: File palimg.c
1638
1639 =item i_img_destroy(C<img>)
1640
1641   i_img_destroy(img)
1642
1643 Destroy an image object
1644
1645
1646 =for comment
1647 From: File image.c
1648
1649
1650 =back
1651
1652 =head2 Image Implementation
1653
1654 =over
1655
1656 =item im_img_alloc(aIMCTX)
1657 X<im_img_alloc API>X<i_img_alloc API>
1658
1659   i_img *im = im_img_alloc(aIMCTX);
1660   i_img *im = i_img_alloc();
1661
1662 Allocates a new i_img structure.
1663
1664 When implementing a new image type perform the following steps in your
1665 image object creation function:
1666
1667 =over
1668
1669 =item 1.
1670
1671 allocate the image with i_img_alloc().
1672
1673 =item 2.
1674
1675 initialize any function pointers or other data as needed, you can
1676 overwrite the whole block if you need to.
1677
1678 =item 3.
1679
1680 initialize Imager's internal data by calling i_img_init() on the image
1681 object.
1682
1683 =back
1684
1685
1686 =for comment
1687 From: File image.c
1688
1689 =item im_img_init(aIMCTX, image)
1690 X<im_img_init API>X<i_img_init API>
1691
1692   im_img_init(aIMCTX, im);
1693   i_img_init(im);
1694
1695 Imager internal initialization of images.
1696
1697 See L</im_img_alloc(aIMCTX)> for more information.
1698
1699
1700 =for comment
1701 From: File image.c
1702
1703
1704 =back
1705
1706 =head2 Image Information
1707
1708 =over
1709
1710 =item i_img_color_channels(C<im>)
1711
1712
1713 The number of channels holding color information.
1714
1715
1716 =for comment
1717 From: File immacros.h
1718
1719 =item i_img_get_height(C<im>)
1720
1721   i_img_dim height = i_img_get_height(im);
1722
1723 Returns the height in pixels of the image.
1724
1725
1726 =for comment
1727 From: File image.c
1728
1729 =item i_img_get_width(C<im>)
1730
1731   i_img_dim width = i_img_get_width(im);
1732
1733 Returns the width in pixels of the image.
1734
1735
1736 =for comment
1737 From: File image.c
1738
1739 =item i_img_getchannels(C<im>)
1740
1741   int channels = i_img_getchannels(img);
1742
1743 Get the number of channels in C<im>.
1744
1745
1746 =for comment
1747 From: File image.c
1748
1749 =item i_img_getmask(C<im>)
1750
1751   int mask = i_img_getmask(img);
1752
1753 Get the image channel mask for C<im>.
1754
1755
1756 =for comment
1757 From: File image.c
1758
1759 =item i_img_has_alpha(C<im>)
1760
1761
1762 Return true if the image has an alpha channel.
1763
1764
1765 =for comment
1766 From: File immacros.h
1767
1768 =item i_img_is_monochrome(img, &zero_is_white)
1769
1770
1771 Tests an image to check it meets our monochrome tests.
1772
1773 The idea is that a file writer can use this to test where it should
1774 write the image in whatever bi-level format it uses, eg. C<pbm> for
1775 C<pnm>.
1776
1777 For performance of encoders we require monochrome images:
1778
1779 =over
1780
1781 =item *
1782
1783 be paletted
1784
1785 =item *
1786
1787 have a palette of two colors, containing only C<(0,0,0)> and
1788 C<(255,255,255)> in either order.
1789
1790 =back
1791
1792 C<zero_is_white> is set to non-zero if the first palette entry is white.
1793
1794
1795 =for comment
1796 From: File image.c
1797
1798 =item i_img_setmask(C<im>, C<ch_mask>)
1799
1800   // only channel 0 writable 
1801   i_img_setmask(img, 0x01);
1802
1803 Set the image channel mask for C<im> to C<ch_mask>.
1804
1805 The image channel mask gives some control over which channels can be
1806 written to in the image.
1807
1808
1809 =for comment
1810 From: File image.c
1811
1812
1813 =back
1814
1815 =head2 Image quantization
1816
1817 =over
1818
1819 =item i_quant_makemap(C<quant>, C<imgs>, C<count>)
1820
1821
1822 Analyzes the C<count> images in C<imgs> according to the rules in
1823 C<quant> to build a color map (optimal or not depending on
1824 C<< quant->make_colors >>).
1825
1826
1827 =for comment
1828 From: File quant.c
1829
1830 =item i_quant_translate(C<quant>, C<img>)
1831
1832
1833 Quantize the image given the palette in C<quant>.
1834
1835 On success returns a pointer to a memory block of C<< img->xsize *
1836 img->ysize >> C<i_palidx> entries.
1837
1838 On failure returns NULL.
1839
1840 You should call myfree() on the returned block when you're done with
1841 it.
1842
1843 This function will fail if the supplied palette contains no colors.
1844
1845
1846 =for comment
1847 From: File quant.c
1848
1849 =item i_quant_transparent(C<quant>, C<data>, C<img>, C<trans_index>)
1850
1851
1852 Dither the alpha channel on C<img> into the palette indexes in
1853 C<data>.  Pixels to be transparent are replaced with C<trans_pixel>.
1854
1855 The method used depends on the tr_* members of C<quant>.
1856
1857
1858 =for comment
1859 From: File quant.c
1860
1861
1862 =back
1863
1864 =head2 Logging
1865
1866 =over
1867
1868 =item i_lhead(file, line)
1869
1870 This is an internal function called by the mm_log() macro.
1871
1872
1873 =for comment
1874 From: File log.c
1875
1876 =item i_loog(level, format, ...)
1877
1878 This is an internal function called by the mm_log() macro.
1879
1880
1881 =for comment
1882 From: File log.c
1883
1884
1885 =back
1886
1887 =head2 Mutex functions
1888
1889 =over
1890
1891 =item i_mutex_new()
1892
1893   i_mutex_t m = i_mutex_new();
1894
1895 Create a mutex.
1896
1897 If a critical section cannot be created for whatever reason, Imager
1898 will abort.
1899
1900
1901 =for comment
1902 From: File mutexwin.c
1903
1904 =item i_mutex_destroy(m)
1905
1906   i_mutex_destroy(m);
1907
1908 Destroy a mutex.
1909
1910
1911 =for comment
1912 From: File mutexwin.c
1913
1914 =item i_mutex_lock(m)
1915
1916   i_mutex_lock(m);
1917
1918 Lock the mutex, waiting if another thread has the mutex locked.
1919
1920
1921 =for comment
1922 From: File mutexwin.c
1923
1924 =item i_mutex_unlock(m)
1925
1926   i_mutex_unlock(m);
1927
1928 Release the mutex.
1929
1930 The behavior of releasing a mutex you don't hold is unspecified.
1931
1932
1933 =for comment
1934 From: File mutexwin.c
1935
1936
1937 =back
1938
1939 =head2 Paletted images
1940
1941 =over
1942
1943 =item i_addcolors(im, colors, count)
1944
1945
1946 Adds colors to the image's palette.
1947
1948 On success returns the index of the lowest color added.
1949
1950 On failure returns -1.
1951
1952 Always fails for direct color images.
1953
1954
1955 =for comment
1956 From: File imext.c
1957
1958 =item i_colorcount(im)
1959
1960
1961 Returns the number of colors in the image's palette.
1962
1963 Returns -1 for direct images.
1964
1965
1966 =for comment
1967 From: File imext.c
1968
1969 =item i_findcolor(im, color, &entry)
1970
1971
1972 Searches the images palette for the given color.
1973
1974 On success sets *I<entry> to the index of the color, and returns true.
1975
1976 On failure returns false.
1977
1978 Always fails on direct color images.
1979
1980
1981 =for comment
1982 From: File imext.c
1983
1984 =item i_getcolors(im, index, colors, count)
1985
1986
1987 Retrieves I<count> colors starting from I<index> in the image's
1988 palette.
1989
1990 On success stores the colors into I<colors> and returns true.
1991
1992 On failure returns false.
1993
1994 Always fails for direct color images.
1995
1996 Fails if there are less than I<index>+I<count> colors in the image's
1997 palette.
1998
1999
2000 =for comment
2001 From: File imext.c
2002
2003 =item i_maxcolors(im)
2004
2005
2006 Returns the maximum number of colors the palette can hold for the
2007 image.
2008
2009 Returns -1 for direct color images.
2010
2011
2012 =for comment
2013 From: File imext.c
2014
2015 =item i_setcolors(im, index, colors, count)
2016
2017
2018 Sets I<count> colors starting from I<index> in the image's palette.
2019
2020 On success returns true.
2021
2022 On failure returns false.
2023
2024 The image must have at least I<index>+I<count> colors in it's palette
2025 for this to succeed.
2026
2027 Always fails on direct color images.
2028
2029
2030 =for comment
2031 From: File imext.c
2032
2033
2034 =back
2035
2036 =head2 Tags
2037
2038 =over
2039
2040 =item i_tags_delbycode(tags, code)
2041
2042
2043 Delete any tags with the given code.
2044
2045 Returns the number of tags deleted.
2046
2047
2048 =for comment
2049 From: File tags.c
2050
2051 =item i_tags_delbyname(tags, name)
2052
2053
2054 Delete any tags with the given name.
2055
2056 Returns the number of tags deleted.
2057
2058
2059 =for comment
2060 From: File tags.c
2061
2062 =item i_tags_delete(tags, index)
2063
2064
2065 Delete a tag by index.
2066
2067 Returns true on success.
2068
2069
2070 =for comment
2071 From: File tags.c
2072
2073 =item i_tags_destroy(tags)
2074
2075
2076 Destroys the given tags structure.  Called by i_img_destroy().
2077
2078
2079 =for comment
2080 From: File tags.c
2081
2082 =item i_tags_find(tags, name, start, &entry)
2083
2084
2085 Searches for a tag of the given I<name> starting from index I<start>.
2086
2087 On success returns true and sets *I<entry>.
2088
2089 On failure returns false.
2090
2091
2092 =for comment
2093 From: File tags.c
2094
2095 =item i_tags_findn(tags, code, start, &entry)
2096
2097
2098 Searches for a tag of the given I<code> starting from index I<start>.
2099
2100 On success returns true and sets *I<entry>.
2101
2102 On failure returns false.
2103
2104
2105 =for comment
2106 From: File tags.c
2107
2108 =item i_tags_get_color(tags, name, code, &value)
2109
2110
2111 Retrieve a tag specified by name or code as color.
2112
2113 On success sets the i_color *I<value> to the color and returns true.
2114
2115 On failure returns false.
2116
2117
2118 =for comment
2119 From: File tags.c
2120
2121 =item i_tags_get_float(tags, name, code, value)
2122
2123
2124 Retrieves a tag as a floating point value.  
2125
2126 If the tag has a string value then that is parsed as a floating point
2127 number, otherwise the integer value of the tag is used.
2128
2129 On success sets *I<value> and returns true.
2130
2131 On failure returns false.
2132
2133
2134 =for comment
2135 From: File tags.c
2136
2137 =item i_tags_get_int(tags, name, code, &value)
2138
2139
2140 Retrieve a tag specified by name or code as an integer.
2141
2142 On success sets the int *I<value> to the integer and returns true.
2143
2144 On failure returns false.
2145
2146
2147 =for comment
2148 From: File tags.c
2149
2150 =item i_tags_get_string(tags, name, code, value, value_size)
2151
2152
2153 Retrieves a tag by name or code as a string.
2154
2155 On success copies the string to value for a max of value_size and
2156 returns true.
2157
2158 On failure returns false.
2159
2160 value_size must be at least large enough for a string representation
2161 of an integer.
2162
2163 The copied value is always C<NUL> terminated.
2164
2165
2166 =for comment
2167 From: File tags.c
2168
2169 =item i_tags_new(i_img_tags *tags)
2170
2171
2172 Initialize a tags structure.  Should not be used if the tags structure
2173 has been previously used.
2174
2175 This should be called tags member of an i_img object on creation (in
2176 i_img_*_new() functions).
2177
2178 To destroy the contents use i_tags_destroy()
2179
2180
2181 =for comment
2182 From: File tags.c
2183
2184 =item i_tags_set(tags, name, data, size)
2185
2186   i_tags_set(&img->tags, "i_comment", -1);
2187
2188 Sets the given tag to the string I<data>
2189
2190 If size is -1 then the strlen(I<data>) bytes are stored.
2191
2192 Even on failure, if an existing tag I<name> exists, it will be
2193 removed.
2194
2195
2196 =for comment
2197 From: File tags.c
2198
2199 =item i_tags_set_color(tags, name, code, &value)
2200
2201
2202 Stores the given color as a tag with the given name and code.
2203
2204
2205 =for comment
2206 From: File tags.c
2207
2208 =item i_tags_set_float(tags, name, code, value)
2209
2210
2211 Equivalent to i_tags_set_float2(tags, name, code, value, 30).
2212
2213
2214 =for comment
2215 From: File tags.c
2216
2217 =item i_tags_set_float2(tags, name, code, value, places)
2218
2219
2220 Sets the tag with the given name and code to the given floating point
2221 value.
2222
2223 Since tags are strings or ints, we convert the value to a string before
2224 storage at the precision specified by C<places>.
2225
2226
2227 =for comment
2228 From: File tags.c
2229
2230 =item i_tags_setn(C<tags>, C<name>, C<idata>)
2231
2232   i_tags_setn(&img->tags, "i_xres", 204);
2233   i_tags_setn(&img->tags, "i_yres", 196);
2234
2235 Sets the given tag to the integer C<idata>
2236
2237 Even on failure, if an existing tag C<name> exists, it will be
2238 removed.
2239
2240
2241 =for comment
2242 From: File tags.c
2243
2244
2245 =back
2246
2247 =head2 Uncategorized functions
2248
2249 =over
2250
2251 =item i_utf8_advance(char **p, size_t *len)
2252
2253 Retrieve a C<UTF-8> character from the stream.
2254
2255 Modifies *p and *len to indicate the consumed characters.
2256
2257 This doesn't support the extended C<UTF-8> encoding used by later
2258 versions of Perl.  Since this is typically used to implement text
2259 output by font drivers, the strings supplied shouldn't have such out
2260 of range characters.
2261
2262 This doesn't check that the C<UTF-8> character is using the shortest
2263 possible representation.
2264
2265 Returns ~0UL on failure.
2266
2267
2268 =for comment
2269 From: File io.c
2270
2271 =item im_context_refdec(ctx, where)
2272 X<im_context_refdec API>
2273 =section Context objects
2274
2275   im_context_refdec(aIMCTX, "a description");
2276
2277 Remove a reference to the context, releasing it if all references have
2278 been removed.
2279
2280
2281 =for comment
2282 From: File context.c
2283
2284 =item im_context_refinc(ctx, where)
2285 X<im_context_refinc API>
2286 =section Context objects
2287
2288   im_context_refinc(aIMCTX, "a description");
2289
2290 Add a new reference to the context.
2291
2292
2293 =for comment
2294 From: File context.c
2295
2296 =item im_context_slot_get(ctx, slot)
2297
2298 Retrieve the value previously stored in the given slot of the context
2299 object.
2300
2301
2302 =for comment
2303 From: File context.c
2304
2305 =item im_context_slot_new(destructor)
2306
2307 Allocate a new context-local-storage slot.
2308
2309
2310 =for comment
2311 From: File context.c
2312
2313 =item im_context_slot_set(slot, value)
2314
2315 Set the value of a slot.
2316
2317 Returns true on success.
2318
2319 Aborts if the slot supplied is invalid.
2320
2321 If reallocation of slot storage fails, returns false.
2322
2323
2324 =for comment
2325 From: File context.c
2326
2327 =item im_errors(ctx)
2328
2329   i_errmsg *errors = im_errors(aIMCTX);
2330   i_errmsg *errors = i_errors();
2331
2332 Returns a pointer to the first element of an array of error messages,
2333 terminated by a NULL pointer.  The highest level message is first.
2334
2335 Also callable as C<i_errors()>.
2336
2337
2338 =for comment
2339 From: File error.c
2340
2341 =item im_get_context()
2342
2343 Retrieve the context object for the current thread.
2344
2345 Inside Imager itself this is just a function pointer, which the
2346 F<Imager.xs> BOOT handler initializes for use within perl.  If you're
2347 taking the Imager code and embedding it elsewhere you need to
2348 initialize the C<im_get_context> pointer at some point.
2349
2350
2351 =for comment
2352 From: File imext.c
2353
2354
2355
2356 =back
2357
2358
2359 =head1 UNDOCUMENTED
2360
2361 The following API functions are undocumented so far, hopefully this
2362 will change:
2363
2364 =over
2365
2366 =item *
2367
2368 B<im_lhead>
2369
2370 =item *
2371
2372 B<im_loog>
2373
2374 =item *
2375
2376 B<mm_log>
2377
2378
2379
2380 =back
2381
2382
2383 =head1 AUTHOR
2384
2385 Tony Cook <tonyc@cpan.org>
2386
2387 =head1 SEE ALSO
2388
2389 Imager, Imager::API, Imager::ExtUtils, Imager::Inline
2390
2391 =cut