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