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