Move freetype 2 support into its own module
[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;
24 i_img_dim x;
bd8052a6 25
92bda632
TC
26 # Drawing
27 i_arc(im, 50, 50, 20, 45, 135, &color);
6cfee9d1 28 i_arc_cfill(im, 50, 50, 35, 90, 135, fill);
92bda632
TC
29 i_arc_aa(im, 50, 50, 35, 90, 135, &color);
30 i_arc_aa_cfill(im, 50, 50, 35, 90, 135, fill);
6cfee9d1 31 i_circle_aa(im, 50, 50, 45, &color);
92bda632 32 i_box(im, 0, 0, im->xsize-1, im->ysize-1, &color).
92bda632 33 i_box_filled(im, 0, 0, im->xsize-1, im->ysize-1, &color);
6cfee9d1 34 i_box_cfill(im, 0, 0, im->xsize-1, im->ysize-1, fill);
92bda632 35 i_flood_fill(im, 50, 50, &color);
6cfee9d1 36 i_flood_cfill(im, 50, 50, fill);
3efb0915 37 i_flood_fill_border(im, 50, 50, &color, &border);
6cfee9d1 38 i_flood_cfill_border(im, 50, 50, fill, border);
92bda632
TC
39
40 # Error handling
6cfee9d1
TC
41 i_clear_error();
42 i_push_error(0, "Yep, it's broken");
43 i_push_error(errno, "Error writing");
44 i_push_errorf(errno, "Cannot open file %s: %d", filename, errno);
92bda632 45
87deb14c 46 # Files
6cfee9d1 47 i_set_image_file_limits(500, 500, 1000000);
87deb14c
TC
48 i_get_image_file_limits(&width, &height, &bytes)
49 i_i_int_check_image_file_limits(width, height, channels, sizeof(i_sample_t))
87deb14c 50
92bda632 51 # Fills
6cfee9d1
TC
52 i_fill_t *fill = i_new_fill_solidf(&fcolor, combine);
53 i_fill_t *fill = i_new_fill_solid(&color, combine);
9167a5c6
TC
54 i_fill_t *fill = i_new_fill_hatch(&fg_color, &bg_color, combine, hatch, custom_hatch, dx, dy);
55 i_fill_t *fill = i_new_fill_hatchf(&fg_fcolor, &bg_fcolor, combine, hatch, custom_hatch, dx, dy);
56 i_fill_t *fill = i_new_fill_image(src_img, matrix, x_offset, y_offset, combine);
6cfee9d1
TC
57 fill = i_new_fill_fount(0, 0, 100, 100, i_ft_linear, i_ft_linear,
58 i_fr_triangle, 0, i_fts_grid, 9, 1, segs);
59 i_fill_destroy(fill);
92bda632
TC
60
61 # Image
62
bd8052a6 63 # Image creation/destruction
9167a5c6 64 i_img *img = i_img_8_new(width, height, channels);
9167a5c6
TC
65 i_img *img = i_sametype(src, width, height);
66 i_img *img = i_sametype_chans(src, width, height, channels);
6cfee9d1
TC
67 i_img *img = i_img_pal_new(width, height, channels, max_palette_size)
68 i_img *img = i_img_double_new(width, height, channels);
69 i_img *img = i_img_16_new(width, height, channels);
70 i_img_destroy(img)
92bda632 71
bd8052a6
TC
72 # Image Implementation
73
bea65b1f 74 # Image Information
6cfee9d1
TC
75 // only channel 0 writeable
76 i_img_setmask(img, 0x01);
77 int mask = i_img_getmask(img);
78 int channels = i_img_getchannels(img);
79 i_img_dim width = i_img_get_width(im);
80 i_img_dim height = i_img_get_height(im);
bea65b1f 81
92bda632
TC
82 # Image quantization
83
bd8052a6
TC
84 # Logging
85
92bda632
TC
86 # Paletted images
87
88 # Tags
6cfee9d1
TC
89 i_tags_set(&img->tags, "i_comment", -1);
90 i_tags_setn(&img->tags, "i_xres", 204);
91 i_tags_setn(&img->tags, "i_yres", 196);
92bda632 92
92bda632
TC
93=head1 DESCRIPTION
94
50c75381
TC
95=head2 Blit tools
96
97=over
98
99=item i_render_color(r, x, y, width, source, color)
100
101Render the given color with the coverage specified by C<source[0]> to
102C<source[width-1]>.
103
104Renders in normal combine mode.
105
106
107=for comment
108From: File render.im
109
110=item i_render_delete(r)
111
112Release an C<i_render> object.
113
114
115=for comment
116From: File render.im
117
118=item i_render_fill(r, x, y, width, source, fill)
119
120Render the given fill with the coverage in C<source[0]> through
121C<source[width-1]>.
122
123
124=for comment
125From: File render.im
126
127=item i_render_line(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_linef(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_new(im, width)
146
147Allocate a new C<i_render> object and initialize it.
148
149
150=for comment
151From: File render.im
152
153
154=back
155
bd8052a6
TC
156=head2 Data Types
157
158=over
159
160=item i_img
161
162This is Imager's image type.
163
164It contains the following members:
165
166=over
167
168=item *
169
5715f7c3 170C<channels> - the number of channels in the image
bd8052a6
TC
171
172=item *
173
5715f7c3 174C<xsize>, C<ysize> - the width and height of the image in pixels
bd8052a6
TC
175
176=item *
177
5715f7c3 178C<bytes> - the number of bytes used to store the image data. Undefined
bd8052a6
TC
179where virtual is non-zero.
180
181=item *
182
5715f7c3 183C<ch_mask> - a mask of writable channels. eg. if this is 6 then only
bd8052a6
TC
184channels 1 and 2 are writable. There may be bits set for which there
185are no channels in the image.
186
187=item *
188
5715f7c3 189C<bits> - the number of bits stored per sample. Should be one of
bd8052a6
TC
190i_8_bits, i_16_bits, i_double_bits.
191
192=item *
193
5715f7c3 194C<type> - either i_direct_type for direct color images, or i_palette_type
bd8052a6
TC
195for paletted images.
196
197=item *
198
5715f7c3
TC
199C<virtual> - if zero then this image is-self contained. If non-zero
200then this image could be an interface to some other implementation.
bd8052a6
TC
201
202=item *
203
5715f7c3 204C<idata> - the image data. This should not be directly accessed. A new
bd8052a6
TC
205image implementation can use this to store its image data.
206i_img_destroy() will myfree() this pointer if it's non-null.
207
208=item *
209
5715f7c3 210C<tags> - a structure storing the image's tags. This should only be
bd8052a6
TC
211accessed via the i_tags_*() functions.
212
213=item *
214
5715f7c3 215C<ext_data> - a pointer for use internal to an image implementation.
bd8052a6
TC
216This should be freed by the image's destroy handler.
217
218=item *
219
5715f7c3 220C<im_data> - data internal to Imager. This is initialized by
bd8052a6
TC
221i_img_init().
222
223=item *
224
225i_f_ppix, i_f_ppixf, i_f_plin, i_f_plinf, i_f_gpix, i_f_gpixf,
226i_f_glin, i_f_glinf, i_f_gsamp, i_f_gampf - implementations for each
227of the required image functions. An image implementation should
228initialize these between calling i_img_alloc() and i_img_init().
229
230=item *
231
232i_f_gpal, i_f_ppal, i_f_addcolors, i_f_getcolors, i_f_colorcount,
233i_f_maxcolors, i_f_findcolor, i_f_setcolors - implementations for each
234paletted image function.
235
236=item *
237
238i_f_destroy - custom image destruction function. This should be used
239to release memory if necessary.
240
241=item *
242
243i_f_gsamp_bits - implements i_gsamp_bits() for this image.
244
245=item *
246
247i_f_psamp_bits - implements i_psamp_bits() for this image.
248
249=back
250
251
6cfee9d1
TC
252=for comment
253From: File imdatatypes.h
254
255=item i_color
256
257Type for 8-bit/sample color.
258
259Samples as per;
260
261 i_color c;
262
263i_color is a union of:
264
265=over
266
267=item *
268
5715f7c3 269gray - contains a single element gray_color, eg. C<c.gray.gray_color>
6cfee9d1
TC
270
271=item *
272
5715f7c3 273C<rgb> - contains three elements C<r>, C<g>, C<b>, eg. C<c.rgb.r>
6cfee9d1
TC
274
275=item *
276
5715f7c3 277C<rgba> - contains four elements C<r>, C<g>, C<b>, C<a>, eg. C<c.rgba.a>
6cfee9d1
TC
278
279=item *
280
5715f7c3
TC
281C<cmyk> - contains four elements C<c>, C<m>, C<y>, C<k>,
282eg. C<c.cmyk.y>. Note that Imager never uses CMYK colors except when
283reading/writing files.
6cfee9d1
TC
284
285=item *
286
287channels - an array of four channels, eg C<c.channels[2]>.
288
289=back
290
291
292=for comment
293From: File imdatatypes.h
294
295=item i_fcolor
296
297This is the double/sample color type.
298
299Its layout exactly corresponds to i_color.
300
301
302=for comment
303From: File imdatatypes.h
304
305=item i_fill_t
306
307This is the "abstract" base type for Imager's fill types.
308
309Unless you're implementing a new fill type you'll typically treat this
310as an opaque type.
311
312
313=for comment
314From: File imdatatypes.h
315
316=item i_img_dim
317
318A signed integer type that represents an image dimension or ordinate.
319
320May be larger than int on some platforms.
321
322
bd8052a6
TC
323=for comment
324From: File imdatatypes.h
325
326
327=back
328
92bda632
TC
329=head2 Drawing
330
331=over
332
333=item i_arc(im, x, y, rad, d1, d2, color)
334
335
336Fills an arc centered at (x,y) with radius I<rad> covering the range
337of angles in degrees from d1 to d2, with the color.
338
339
340=for comment
5ca7e2ab 341From: File draw.c
92bda632
TC
342
343=item i_arc_aa(im, x, y, rad, d1, d2, color)
344
345
5715f7c3 346Anti-alias fills an arc centered at (x,y) with radius I<rad> covering
92bda632
TC
347the range of angles in degrees from d1 to d2, with the color.
348
349
350=for comment
5ca7e2ab 351From: File draw.c
92bda632
TC
352
353=item i_arc_aa_cfill(im, x, y, rad, d1, d2, fill)
354
355
5715f7c3 356Anti-alias fills an arc centered at (x,y) with radius I<rad> covering
92bda632
TC
357the range of angles in degrees from d1 to d2, with the fill object.
358
359
360=for comment
5ca7e2ab 361From: File draw.c
92bda632
TC
362
363=item i_arc_cfill(im, x, y, rad, d1, d2, fill)
364
365
366Fills an arc centered at (x,y) with radius I<rad> covering the range
367of angles in degrees from d1 to d2, with the fill object.
368
369
370=for comment
5ca7e2ab 371From: File draw.c
92bda632
TC
372
373=item i_box(im, x1, y1, x2, y2, color)
374
375
376Outlines the box from (x1,y1) to (x2,y2) inclusive with I<color>.
377
378
379=for comment
5ca7e2ab 380From: File draw.c
92bda632
TC
381
382=item i_box_cfill(im, x1, y1, x2, y2, fill)
383
384
385Fills the box from (x1,y1) to (x2,y2) inclusive with fill.
386
387
388=for comment
5ca7e2ab 389From: File draw.c
92bda632
TC
390
391=item i_box_filled(im, x1, y1, x2, y2, color)
392
393
394Fills the box from (x1,y1) to (x2,y2) inclusive with color.
395
396
397=for comment
5ca7e2ab 398From: File draw.c
92bda632
TC
399
400=item i_circle_aa(im, x, y, rad, color)
401
402
5715f7c3 403Anti-alias fills a circle centered at (x,y) for radius I<rad> with
92bda632
TC
404color.
405
406
407=for comment
5ca7e2ab 408From: File draw.c
92bda632 409
5715f7c3 410=item i_flood_cfill(C<im>, C<seedx>, C<seedy>, C<fill>)
92bda632
TC
411
412
5715f7c3
TC
413Flood fills the 4-connected region starting from the point (C<seedx>,
414C<seedy>) with C<fill>.
92bda632 415
5715f7c3 416Returns false if (C<seedx>, C<seedy>) are outside the image.
92bda632
TC
417
418
419=for comment
5ca7e2ab 420From: File draw.c
3efb0915 421
5715f7c3 422=item i_flood_cfill_border(C<im>, C<seedx>, C<seedy>, C<fill>, C<border>)
3efb0915
TC
423
424
5715f7c3
TC
425Flood fills the 4-connected region starting from the point (C<seedx>,
426C<seedy>) with C<fill>, the fill stops when it reaches pixels of color
427C<border>.
3efb0915 428
5715f7c3 429Returns false if (C<seedx>, C<seedy>) are outside the image.
3efb0915
TC
430
431
432=for comment
5ca7e2ab 433From: File draw.c
92bda632 434
5715f7c3 435=item i_flood_fill(C<im>, C<seedx>, C<seedy>, C<color>)
92bda632
TC
436
437
5715f7c3
TC
438Flood fills the 4-connected region starting from the point (C<seedx>,
439C<seedy>) with I<color>.
92bda632 440
5715f7c3 441Returns false if (C<seedx>, C<seedy>) are outside the image.
92bda632
TC
442
443
444=for comment
5ca7e2ab 445From: File draw.c
3efb0915 446
5715f7c3 447=item i_flood_fill_border(C<im>, C<seedx>, C<seedy>, C<color>, C<border>)
3efb0915
TC
448
449
5715f7c3
TC
450Flood fills the 4-connected region starting from the point (C<seedx>,
451C<seedy>) with C<color>, fill stops when the fill reaches a pixels
452with color C<border>.
3efb0915 453
5715f7c3 454Returns false if (C<seedx>, C<seedy>) are outside the image.
3efb0915
TC
455
456
457=for comment
5ca7e2ab 458From: File draw.c
92bda632
TC
459
460=item i_glin(im, l, r, y, colors)
461
462
463Retrieves (r-l) pixels starting from (l,y) into I<colors>.
464
465Returns the number of pixels retrieved.
466
467
468=for comment
5ca7e2ab 469From: File imext.c
92bda632
TC
470
471=item i_glinf(im, l, r, y, colors)
472
473
474Retrieves (r-l) pixels starting from (l,y) into I<colors> as floating
475point colors.
476
477Returns the number of pixels retrieved.
478
479
480=for comment
5ca7e2ab 481From: File imext.c
92bda632 482
5715f7c3 483=item i_gpal(im, left, right, y, indexes)
92bda632
TC
484
485
5715f7c3
TC
486Reads palette indexes for the horizontal line (left, y) to (right-1,
487y) into C<indexes>.
92bda632
TC
488
489Returns the number of indexes read.
490
491Always returns 0 for direct color images.
492
493
494=for comment
5ca7e2ab 495From: File imext.c
92bda632 496
5715f7c3 497=item i_gpix(im, C<x>, C<y>, C<color>)
92bda632
TC
498
499
5715f7c3 500Retrieves the C<color> of the pixel (x,y).
92bda632
TC
501
502Returns 0 if the pixel was retrieved, or -1 if not.
503
504
505=for comment
5ca7e2ab 506From: File imext.c
92bda632 507
5715f7c3 508=item i_gpixf(im, C<x>, C<y>, C<fcolor>)
92bda632
TC
509
510
511Retrieves the color of the pixel (x,y) as a floating point color into
5715f7c3 512C<fcolor>.
92bda632
TC
513
514Returns 0 if the pixel was retrieved, or -1 if not.
515
516
517=for comment
5ca7e2ab 518From: File imext.c
92bda632 519
5715f7c3 520=item i_gsamp(im, left, right, y, samples, channels, channel_count)
92bda632
TC
521
522
5715f7c3
TC
523Reads sample values from C<im> for the horizontal line (left, y) to
524(right-1,y) for the channels specified by C<channels>, an array of int
525with C<channel_count> elements.
92bda632 526
5715f7c3 527If channels is NULL then the first channels_count channels are retrieved for
92bda632
TC
528each pixel.
529
5715f7c3
TC
530Returns the number of samples read (which should be (right-left) *
531channel_count)
92bda632
TC
532
533
534=for comment
5ca7e2ab 535From: File imext.c
92bda632 536
50c75381
TC
537=item i_gsamp_bg(im, l, r, y, samples, out_channels, background)
538
539
540Like C<i_gsampf()> but applies the source image color over a supplied
541background color.
542
543This is intended for output to image formats that don't support alpha
544channels.
545
546
547=for comment
548From: File paste.im
549
5715f7c3 550=item i_gsampf(im, left, right, y, samples, channels, channel_count)
92bda632
TC
551
552
5715f7c3
TC
553Reads floating point sample values from C<im> for the horizontal line
554(left, y) to (right-1,y) for the channels specified by C<channels>, an
555array of int with channel_count elements.
92bda632 556
5715f7c3
TC
557If C<channels> is NULL then the first C<channel_count> channels are
558retrieved for each pixel.
92bda632 559
5715f7c3
TC
560Returns the number of samples read (which should be (C<right>-C<left>)
561* C<channel_count>)
92bda632
TC
562
563
564=for comment
5ca7e2ab 565From: File imext.c
92bda632 566
797a9f9c
TC
567=item i_gsampf_bg(im, l, r, y, samples, out_channels, background)
568
569
570Like C<i_gsampf()> but applies the source image color over a supplied
571background color.
572
573This is intended for output to image formats that don't support alpha
574channels.
575
576
577=for comment
578From: File paste.im
579
5715f7c3
TC
580=item i_line(C<im>, C<x1>, C<y1>, C<x2>, C<y2>, C<color>, C<endp>)
581
92bda632 582
5715f7c3 583=for stopwords Bresenham's
92bda632 584
5715f7c3 585Draw a line to image using Bresenham's line drawing algorithm
92bda632 586
5715f7c3
TC
587 im - image to draw to
588 x1 - starting x coordinate
589 y1 - starting x coordinate
590 x2 - starting x coordinate
591 y2 - starting x coordinate
592 color - color to write to image
593 endp - endpoint flag (boolean)
92bda632
TC
594
595
596=for comment
5ca7e2ab 597From: File draw.c
92bda632 598
5715f7c3 599=item i_line_aa(C<im>, C<x1>, C<x2>, C<y1>, C<y2>, C<color>, C<endp>)
92bda632
TC
600
601
5715f7c3 602Anti-alias draws a line from (x1,y1) to (x2, y2) in color.
92bda632 603
5715f7c3 604The point (x2, y2) is drawn only if C<endp> is set.
92bda632
TC
605
606
607=for comment
5ca7e2ab 608From: File draw.c
92bda632
TC
609
610=item i_plin(im, l, r, y, colors)
611
612
613Sets (r-l) pixels starting from (l,y) using (r-l) values from
614I<colors>.
615
616Returns the number of pixels set.
617
618
619=for comment
5ca7e2ab 620From: File imext.c
92bda632 621
5715f7c3 622=item i_plinf(im, C<left>, C<right>, C<fcolors>)
92bda632
TC
623
624
5715f7c3
TC
625Sets (right-left) pixels starting from (left,y) using (right-left)
626floating point colors from C<fcolors>.
92bda632
TC
627
628Returns the number of pixels set.
629
630
631=for comment
5ca7e2ab 632From: File imext.c
92bda632 633
5715f7c3 634=item i_ppal(im, left, right, y, indexes)
92bda632
TC
635
636
5715f7c3
TC
637Writes palette indexes for the horizontal line (left, y) to (right-1,
638y) from C<indexes>.
92bda632
TC
639
640Returns the number of indexes written.
641
642Always returns 0 for direct color images.
643
644
645=for comment
5ca7e2ab 646From: File imext.c
92bda632
TC
647
648=item i_ppix(im, x, y, color)
649
650
651Sets the pixel at (x,y) to I<color>.
652
653Returns 0 if the pixel was drawn, or -1 if not.
654
655Does no alpha blending, just copies the channels from the supplied
656color to the image.
657
658
659=for comment
5ca7e2ab 660From: File imext.c
92bda632 661
5715f7c3 662=item i_ppixf(im, C<x>, C<y>, C<fcolor>)
92bda632
TC
663
664
5715f7c3 665Sets the pixel at (C<x>,C<y>) to the floating point color C<fcolor>.
92bda632
TC
666
667Returns 0 if the pixel was drawn, or -1 if not.
668
669Does no alpha blending, just copies the channels from the supplied
670color to the image.
671
672
673=for comment
5ca7e2ab 674From: File imext.c
92bda632
TC
675
676
677=back
678
679=head2 Error handling
680
681=over
682
683=item i_clear_error()
684
92bda632
TC
685Clears the error stack.
686
5715f7c3 687Called by any Imager function before doing any other processing.
92bda632
TC
688
689
690=for comment
5ca7e2ab 691From: File error.c
92bda632
TC
692
693=item i_push_error(int code, char const *msg)
694
6cfee9d1 695Called by an Imager function to push an error message onto the stack.
92bda632
TC
696
697No message is pushed if the stack is full (since this means someone
698forgot to call i_clear_error(), or that a function that doesn't do
699error handling is calling function that does.).
700
701
702=for comment
5ca7e2ab 703From: File error.c
92bda632
TC
704
705=item i_push_errorf(int code, char const *fmt, ...)
706
5715f7c3 707A version of i_push_error() that does printf() like formatting.
92bda632 708
6cfee9d1
TC
709Does not support perl specific format codes.
710
92bda632
TC
711
712=for comment
5ca7e2ab 713From: File error.c
92bda632 714
5715f7c3 715=item i_push_errorvf(int C<code>, char const *C<fmt>, va_list C<ap>)
92bda632
TC
716
717
718Intended for use by higher level functions, takes a varargs pointer
719and a format to produce the finally pushed error message.
720
6cfee9d1
TC
721Does not support perl specific format codes.
722
92bda632
TC
723
724=for comment
5ca7e2ab 725From: File error.c
92bda632
TC
726
727
87deb14c
TC
728=back
729
730=head2 Files
731
732=over
733
797a9f9c
TC
734=item i_get_file_background(im, &bg)
735
736
737Retrieve the file write background color tag from the image.
738
739If not present, returns black.
740
741
742=for comment
743From: File image.c
744
745=item i_get_file_backgroundf(im, &bg)
746
747
748Retrieve the file write background color tag from the image as a
749floating point color.
750
751Implemented in terms of i_get_file_background().
752
753If not present, returns black.
754
755
756=for comment
757From: File image.c
758
87deb14c
TC
759=item i_get_image_file_limits(&width, &height, &bytes)
760
761
762Retrieves the file limits set by i_set_image_file_limits().
763
764
765=for comment
5ca7e2ab 766From: File limits.c
87deb14c
TC
767
768=item i_int_check_image_file_limits(width, height, channels, sample_size)
769
770
771Checks the size of a file in memory against the configured image file
772limits.
773
774This also range checks the values to those permitted by Imager and
775checks for overflows in calculating the size.
776
777Returns non-zero if the file is within limits.
778
779This function is intended to be called by image file read functions.
780
781
782=for comment
5ca7e2ab 783From: File limits.c
87deb14c
TC
784
785=item i_set_image_file_limits(width, height, bytes)
786
787
788Set limits on the sizes of images read by Imager.
789
790Setting a limit to 0 means that limit is ignored.
791
792Negative limits result in failure.
793
794Returns non-zero on success.
795
796
797=for comment
5ca7e2ab 798From: File limits.c
87deb14c
TC
799
800
92bda632
TC
801=back
802
803=head2 Fills
804
805=over
806
5715f7c3 807=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
808
809
810
811Creates a new general fill which fills with a fountain fill.
812
813
814=for comment
bea65b1f 815From: File filters.im
92bda632 816
5715f7c3 817=item i_new_fill_hatch(C<fg>, C<bg>, C<combine>, C<hatch>, C<cust_hatch>, C<dx>, C<dy>)
92bda632
TC
818
819
5715f7c3
TC
820Creates a new hatched fill with the C<fg> color used for the 1 bits in
821the hatch and C<bg> for the 0 bits. If C<combine> is non-zero alpha
822values will be combined.
92bda632 823
5715f7c3 824If C<cust_hatch> is non-NULL it should be a pointer to 8 bytes of the
92bda632
TC
825hash definition, with the high-bits to the left.
826
5715f7c3 827If C<cust_hatch> is NULL then one of the standard hatches is used.
92bda632 828
5715f7c3
TC
829(C<dx>, C<dy>) are an offset into the hatch which can be used to hatch
830adjoining areas out of alignment, or to align the origin of a hatch
831with the the side of a filled area.
92bda632
TC
832
833
834=for comment
5ca7e2ab 835From: File fills.c
92bda632 836
5715f7c3 837=item i_new_fill_hatchf(C<fg>, C<bg>, C<combine>, C<hatch>, C<cust_hatch>, C<dx>, C<dy>)
92bda632
TC
838
839
5715f7c3
TC
840Creates a new hatched fill with the C<fg> color used for the 1 bits in
841the hatch and C<bg> for the 0 bits. If C<combine> is non-zero alpha
842values will be combined.
92bda632 843
5715f7c3 844If C<cust_hatch> is non-NULL it should be a pointer to 8 bytes of the
92bda632
TC
845hash definition, with the high-bits to the left.
846
5715f7c3 847If C<cust_hatch> is NULL then one of the standard hatches is used.
92bda632 848
5715f7c3
TC
849(C<dx>, C<dy>) are an offset into the hatch which can be used to hatch
850adjoining areas out of alignment, or to align the origin of a hatch
851with the the side of a filled area.
92bda632
TC
852
853
854=for comment
5ca7e2ab 855From: File fills.c
92bda632 856
5715f7c3 857=item i_new_fill_image(C<im>, C<matrix>, C<xoff>, C<yoff>, C<combine>)
92bda632
TC
858
859
860Create an image based fill.
861
862matrix is an array of 9 doubles representing a transformation matrix.
863
5715f7c3 864C<xoff> and C<yoff> are the offset into the image to start filling from.
92bda632
TC
865
866
867=for comment
5ca7e2ab 868From: File fills.c
92bda632
TC
869
870=item i_new_fill_solid(color, combine)
871
872
873Create a solid fill based on an 8-bit color.
874
875If combine is non-zero then alpha values will be combined.
876
877
878=for comment
5ca7e2ab 879From: File fills.c
92bda632
TC
880
881=item i_new_fill_solidf(color, combine)
882
883
884Create a solid fill based on a float color.
885
886If combine is non-zero then alpha values will be combined.
887
888
6cfee9d1
TC
889=for comment
890From: File fills.c
891
892=item i_fill_destroy(fill)
893
894Call to destroy any fill object.
895
896
92bda632 897=for comment
5ca7e2ab 898From: File fills.c
92bda632
TC
899
900
901=back
902
903=head2 Image
904
905=over
906
5715f7c3 907=item i_copy(source)
92bda632
TC
908
909
5715f7c3 910Creates a new image that is a copy of the image C<source>.
92bda632
TC
911
912Tags are not copied, only the image data.
913
914Returns: i_img *
915
916
917=for comment
5ca7e2ab 918From: File image.c
92bda632 919
5715f7c3 920=item i_copyto(C<dest>, C<src>, C<x1>, C<y1>, C<x2>, C<y2>, C<tx>, C<ty>)
92bda632
TC
921
922
5715f7c3
TC
923Copies image data from the area (C<x1>,C<y1>)-[C<x2>,C<y2>] in the
924source image to a rectangle the same size with it's top-left corner at
925(C<tx>,C<ty>) in the destination image.
92bda632 926
5715f7c3
TC
927If C<x1> > C<x2> or C<y1> > C<y2> then the corresponding co-ordinates
928are swapped.
92bda632
TC
929
930
931=for comment
9b1ec2b8 932From: File paste.im
92bda632 933
5715f7c3 934=item i_copyto_trans(C<im>, C<src>, C<x1>, C<y1>, C<x2>, C<y2>, C<tx>, C<ty>, C<trans>)
92bda632
TC
935
936
5715f7c3
TC
937(C<x1>,C<y1>) (C<x2>,C<y2>) specifies the region to copy (in the
938source coordinates) (C<tx>,C<ty>) specifies the upper left corner for
939the target image. pass NULL in C<trans> for non transparent i_colors.
92bda632
TC
940
941
92bda632 942=for comment
5ca7e2ab 943From: File image.c
92bda632
TC
944
945=item i_img_info(im, info)
946
947
948Return image information
949
950 im - Image pointer
951 info - pointer to array to return data
952
953info is an array of 4 integers with the following values:
954
955 info[0] - width
956 info[1] - height
957 info[2] - channels
958 info[3] - channel mask
959
960
961=for comment
5ca7e2ab 962From: File image.c
92bda632 963
5715f7c3 964=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
965
966
5715f7c3
TC
967Takes the sub image C<src>[C<src_minx>, C<src_maxx>)[C<src_miny>, C<src_maxy>)> and
968overlays it at (C<tx>,C<ty>) on the image object.
92bda632 969
5715f7c3
TC
970The alpha channel of each pixel in C<src> is used to control how much
971the existing color in C<im> is replaced, if it is 255 then the color
972is completely replaced, if it is 0 then the original color is left
92bda632
TC
973unmodified.
974
975
976=for comment
fe415ad2 977From: File rubthru.im
92bda632
TC
978
979
980=back
981
6cfee9d1 982=head2 Image creation/destruction
92bda632
TC
983
984=over
985
986=item i_img_16_new(x, y, ch)
987
988
989Create a new 16-bit/sample image.
990
991Returns the image on success, or NULL on failure.
992
993
994=for comment
5ca7e2ab 995From: File img16.c
92bda632
TC
996
997=item i_img_8_new(x, y, ch)
998
999
9167a5c6 1000
92bda632
TC
1001Creates a new image object I<x> pixels wide, and I<y> pixels high with
1002I<ch> channels.
1003
1004
1005=for comment
5ca7e2ab 1006From: File image.c
92bda632
TC
1007
1008=item i_img_double_new(int x, int y, int ch)
1009
92bda632
TC
1010Creates a new double per sample image.
1011
1012
1013=for comment
5ca7e2ab 1014From: File imgdouble.c
92bda632 1015
5715f7c3 1016=item i_img_pal_new(C<x>, C<y>, C<channels>, C<maxpal>)
92bda632
TC
1017
1018
1019Creates a new paletted image of the supplied dimensions.
1020
5715f7c3 1021C<maxpal> is the maximum palette size and should normally be 256.
9167a5c6 1022
92bda632
TC
1023Returns a new image or NULL on failure.
1024
1025
1026=for comment
5ca7e2ab 1027From: File palimg.c
92bda632 1028
5715f7c3 1029=item i_sametype(C<im>, C<xsize>, C<ysize>)
92bda632
TC
1030
1031
1032Returns an image of the same type (sample size, channels, paletted/direct).
1033
1034For paletted images the palette is copied from the source.
1035
1036
1037=for comment
5ca7e2ab 1038From: File image.c
92bda632 1039
5715f7c3 1040=item i_sametype_chans(C<im>, C<xsize>, C<ysize>, C<channels>)
92bda632
TC
1041
1042
1043Returns an image of the same type (sample size).
1044
1045For paletted images the equivalent direct type is returned.
1046
1047
6cfee9d1
TC
1048=for comment
1049From: File image.c
1050
5715f7c3 1051=item i_img_destroy(C<img>)
6cfee9d1
TC
1052
1053Destroy an image object
1054
1055
92bda632 1056=for comment
5ca7e2ab 1057From: File image.c
92bda632
TC
1058
1059
bd8052a6
TC
1060=back
1061
1062=head2 Image Implementation
1063
1064=over
1065
1066=item i_img_alloc()
1067
1068Allocates a new i_img structure.
1069
1070When implementing a new image type perform the following steps in your
1071image object creation function:
1072
1073=over
1074
1075=item 1.
1076
1077allocate the image with i_img_alloc().
1078
1079=item 2.
1080
1081initialize any function pointers or other data as needed, you can
1082overwrite the whole block if you need to.
1083
1084=item 3.
1085
1086initialize Imager's internal data by calling i_img_init() on the image
1087object.
1088
1089=back
1090
1091
1092=for comment
1093From: File image.c
1094
5715f7c3 1095=item i_img_init(C<img>)
bd8052a6 1096
5715f7c3 1097Imager internal initialization of images.
bd8052a6
TC
1098
1099Currently this does very little, in the future it may be used to
1100support threads, or color profiles.
1101
1102
1103=for comment
1104From: File image.c
1105
1106
bea65b1f
TC
1107=back
1108
1109=head2 Image Information
1110
1111=over
1112
5715f7c3 1113=item i_img_color_channels(C<im>)
bea65b1f
TC
1114
1115
1116The number of channels holding color information.
1117
1118
1119=for comment
1120From: File immacros.h
1121
5715f7c3 1122=item i_img_get_height(C<im>)
6cfee9d1
TC
1123
1124Returns the height in pixels of the image.
1125
1126
1127=for comment
1128From: File image.c
1129
5715f7c3 1130=item i_img_get_width(C<im>)
6cfee9d1
TC
1131
1132Returns the width in pixels of the image.
1133
1134
1135=for comment
1136From: File image.c
1137
5715f7c3 1138=item i_img_getchannels(C<im>)
6cfee9d1 1139
5715f7c3 1140Get the number of channels in C<im>.
6cfee9d1
TC
1141
1142
1143=for comment
1144From: File image.c
1145
5715f7c3 1146=item i_img_getmask(C<im>)
6cfee9d1 1147
5715f7c3 1148Get the image channel mask for C<im>.
6cfee9d1
TC
1149
1150
1151=for comment
1152From: File image.c
1153
5715f7c3 1154=item i_img_has_alpha(C<im>)
bea65b1f
TC
1155
1156
1157Return true if the image has an alpha channel.
1158
1159
1160=for comment
1161From: File immacros.h
1162
e5ee047b
TC
1163=item i_img_is_monochrome(img, &zero_is_white)
1164
1165
1166Tests an image to check it meets our monochrome tests.
1167
1168The idea is that a file writer can use this to test where it should
1169write the image in whatever bi-level format it uses, eg. C<pbm> for
1170C<pnm>.
1171
1172For performance of encoders we require monochrome images:
1173
1174=over
1175
1176=item *
1177
1178be paletted
1179
1180=item *
1181
1182have a palette of two colors, containing only C<(0,0,0)> and
1183C<(255,255,255)> in either order.
1184
1185=back
1186
1187C<zero_is_white> is set to non-zero if the first palette entry is white.
1188
1189
1190=for comment
1191From: File image.c
1192
5715f7c3 1193=item i_img_setmask(C<im>, C<ch_mask>)
6cfee9d1 1194
5715f7c3 1195Set the image channel mask for C<im> to C<ch_mask>.
6cfee9d1
TC
1196
1197The image channel mask gives some control over which channels can be
1198written to in the image.
1199
1200
1201=for comment
1202From: File image.c
1203
bea65b1f 1204
92bda632
TC
1205=back
1206
1207=head2 Image quantization
1208
1209=over
1210
5715f7c3 1211=item i_quant_makemap(C<quant>, C<imgs>, C<count>)
92bda632
TC
1212
1213
5715f7c3
TC
1214Analyzes the C<count> images in C<imgs> according to the rules in
1215C<quant> to build a color map (optimal or not depending on
1216C<< quant->make_colors >>).
92bda632
TC
1217
1218
1219=for comment
5ca7e2ab 1220From: File quant.c
92bda632 1221
5715f7c3 1222=item i_quant_translate(C<quant>, C<img>)
92bda632
TC
1223
1224
5715f7c3 1225Quantize the image given the palette in C<quant>.
92bda632 1226
5715f7c3
TC
1227On success returns a pointer to a memory block of C<< img->xsize *
1228img->ysize >> C<i_palidx> entries.
92bda632
TC
1229
1230On failure returns NULL.
1231
1232You should call myfree() on the returned block when you're done with
1233it.
1234
1235This function will fail if the supplied palette contains no colors.
1236
1237
1238=for comment
5ca7e2ab 1239From: File quant.c
92bda632 1240
5715f7c3 1241=item i_quant_transparent(C<quant>, C<data>, C<img>, C<trans_index>)
92bda632
TC
1242
1243
5715f7c3
TC
1244Dither the alpha channel on C<img> into the palette indexes in
1245C<data>. Pixels to be transparent are replaced with C<trans_pixel>.
92bda632 1246
5715f7c3 1247The method used depends on the tr_* members of C<quant>.
92bda632
TC
1248
1249
1250=for comment
5ca7e2ab 1251From: File quant.c
92bda632
TC
1252
1253
bd8052a6
TC
1254=back
1255
1256=head2 Logging
1257
1258=over
1259
6cfee9d1
TC
1260=item i_lhead(file, line)
1261
1262This is an internal function called by the mm_log() macro.
1263
1264
1265=for comment
1266From: File log.c
1267
bd8052a6
TC
1268=item i_loog(level, format, ...)
1269
1270This is an internal function called by the mm_log() macro.
1271
1272
1273=for comment
1274From: File log.c
1275
1276=item mm_log((level, format, ...))
1277
1278This is the main entry point to logging. Note that the extra set of
1279parentheses are required due to limitations in C89 macros.
1280
1281This will format a string with the current file and line number to the
1282log file if logging is enabled.
1283
1284
1285=for comment
1286From: File log.h
1287
1288
92bda632
TC
1289=back
1290
1291=head2 Paletted images
1292
1293=over
1294
1295=item i_addcolors(im, colors, count)
1296
1297
1298Adds colors to the image's palette.
1299
1300On success returns the index of the lowest color added.
1301
1302On failure returns -1.
1303
1304Always fails for direct color images.
1305
1306
1307=for comment
5ca7e2ab 1308From: File imext.c
92bda632
TC
1309
1310=item i_colorcount(im)
1311
1312
1313Returns the number of colors in the image's palette.
1314
1315Returns -1 for direct images.
1316
1317
1318=for comment
5ca7e2ab 1319From: File imext.c
92bda632
TC
1320
1321=item i_findcolor(im, color, &entry)
1322
1323
1324Searches the images palette for the given color.
1325
1326On success sets *I<entry> to the index of the color, and returns true.
1327
1328On failure returns false.
1329
1330Always fails on direct color images.
1331
1332
1333=for comment
5ca7e2ab 1334From: File imext.c
92bda632
TC
1335
1336=item i_getcolors(im, index, colors, count)
1337
1338
1339Retrieves I<count> colors starting from I<index> in the image's
1340palette.
1341
1342On success stores the colors into I<colors> and returns true.
1343
1344On failure returns false.
1345
1346Always fails for direct color images.
1347
1348Fails if there are less than I<index>+I<count> colors in the image's
1349palette.
1350
1351
1352=for comment
5ca7e2ab 1353From: File imext.c
92bda632
TC
1354
1355=item i_maxcolors(im)
1356
1357
1358Returns the maximum number of colors the palette can hold for the
1359image.
1360
1361Returns -1 for direct color images.
1362
1363
1364=for comment
5ca7e2ab 1365From: File imext.c
92bda632
TC
1366
1367=item i_setcolors(im, index, colors, count)
1368
1369
1370Sets I<count> colors starting from I<index> in the image's palette.
1371
5715f7c3 1372On success returns true.
92bda632
TC
1373
1374On failure returns false.
1375
1376The image must have at least I<index>+I<count> colors in it's palette
1377for this to succeed.
1378
1379Always fails on direct color images.
1380
1381
1382=for comment
5ca7e2ab 1383From: File imext.c
92bda632
TC
1384
1385
1386=back
1387
1388=head2 Tags
1389
1390=over
1391
1392=item i_tags_delbycode(tags, code)
1393
1394
1395Delete any tags with the given code.
1396
1397Returns the number of tags deleted.
1398
1399
1400=for comment
5ca7e2ab 1401From: File tags.c
92bda632
TC
1402
1403=item i_tags_delbyname(tags, name)
1404
1405
1406Delete any tags with the given name.
1407
1408Returns the number of tags deleted.
1409
1410
1411=for comment
5ca7e2ab 1412From: File tags.c
92bda632
TC
1413
1414=item i_tags_delete(tags, index)
1415
1416
1417Delete a tag by index.
1418
1419Returns true on success.
1420
1421
1422=for comment
5ca7e2ab 1423From: File tags.c
92bda632
TC
1424
1425=item i_tags_destroy(tags)
1426
1427
1428Destroys the given tags structure. Called by i_img_destroy().
1429
1430
1431=for comment
5ca7e2ab 1432From: File tags.c
92bda632
TC
1433
1434=item i_tags_find(tags, name, start, &entry)
1435
1436
5715f7c3 1437Searches for a tag of the given I<name> starting from index I<start>.
92bda632
TC
1438
1439On success returns true and sets *I<entry>.
1440
1441On failure returns false.
1442
1443
1444=for comment
5ca7e2ab 1445From: File tags.c
92bda632
TC
1446
1447=item i_tags_findn(tags, code, start, &entry)
1448
1449
5715f7c3 1450Searches for a tag of the given I<code> starting from index I<start>.
92bda632
TC
1451
1452On success returns true and sets *I<entry>.
1453
1454On failure returns false.
1455
1456
1457=for comment
5ca7e2ab 1458From: File tags.c
92bda632
TC
1459
1460=item i_tags_get_color(tags, name, code, &value)
1461
1462
1463Retrieve a tag specified by name or code as color.
1464
1465On success sets the i_color *I<value> to the color and returns true.
1466
1467On failure returns false.
1468
1469
1470=for comment
5ca7e2ab 1471From: File tags.c
92bda632
TC
1472
1473=item i_tags_get_float(tags, name, code, value)
1474
1475
1476Retrieves a tag as a floating point value.
1477
1478If the tag has a string value then that is parsed as a floating point
1479number, otherwise the integer value of the tag is used.
1480
1481On success sets *I<value> and returns true.
1482
1483On failure returns false.
1484
1485
1486=for comment
5ca7e2ab 1487From: File tags.c
92bda632
TC
1488
1489=item i_tags_get_int(tags, name, code, &value)
1490
1491
1492Retrieve a tag specified by name or code as an integer.
1493
3efb0915 1494On success sets the int *I<value> to the integer and returns true.
92bda632
TC
1495
1496On failure returns false.
1497
1498
1499=for comment
5ca7e2ab 1500From: File tags.c
92bda632
TC
1501
1502=item i_tags_get_string(tags, name, code, value, value_size)
1503
1504
1505Retrieves a tag by name or code as a string.
1506
1507On success copies the string to value for a max of value_size and
1508returns true.
1509
1510On failure returns false.
1511
1512value_size must be at least large enough for a string representation
1513of an integer.
1514
5715f7c3 1515The copied value is always C<NUL> terminated.
92bda632
TC
1516
1517
1518=for comment
5ca7e2ab 1519From: File tags.c
92bda632
TC
1520
1521=item i_tags_new(i_img_tags *tags)
1522
1523
1524Initialize a tags structure. Should not be used if the tags structure
1525has been previously used.
1526
1527This should be called tags member of an i_img object on creation (in
1528i_img_*_new() functions).
1529
1530To destroy the contents use i_tags_destroy()
1531
1532
1533=for comment
5ca7e2ab 1534From: File tags.c
92bda632
TC
1535
1536=item i_tags_set(tags, name, data, size)
1537
92bda632
TC
1538Sets the given tag to the string I<data>
1539
6cfee9d1
TC
1540If size is -1 then the strlen(I<data>) bytes are stored.
1541
1542Even on failure, if an existing tag I<name> exists, it will be
1543removed.
1544
92bda632
TC
1545
1546=for comment
5ca7e2ab 1547From: File tags.c
92bda632
TC
1548
1549=item i_tags_set_color(tags, name, code, &value)
1550
1551
1552Stores the given color as a tag with the given name and code.
1553
1554
1555=for comment
5ca7e2ab 1556From: File tags.c
92bda632
TC
1557
1558=item i_tags_set_float(tags, name, code, value)
1559
1560
1561Equivalent to i_tags_set_float2(tags, name, code, value, 30).
1562
1563
1564=for comment
5ca7e2ab 1565From: File tags.c
92bda632
TC
1566
1567=item i_tags_set_float2(tags, name, code, value, places)
1568
1569
1570Sets the tag with the given name and code to the given floating point
1571value.
1572
1573Since tags are strings or ints, we convert the value to a string before
1574storage at the precision specified by C<places>.
1575
1576
1577=for comment
5ca7e2ab 1578From: File tags.c
92bda632 1579
5715f7c3 1580=item i_tags_setn(C<tags>, C<name>, C<idata>)
92bda632 1581
5715f7c3 1582Sets the given tag to the integer C<idata>
92bda632 1583
5715f7c3 1584Even on failure, if an existing tag C<name> exists, it will be
6cfee9d1 1585removed.
d5477d3d
TC
1586
1587
1588=for comment
6cfee9d1 1589From: File tags.c
d5477d3d
TC
1590
1591
797a9f9c
TC
1592=back
1593
50c75381 1594=head2 Uncategorized functions
797a9f9c 1595
50c75381 1596=over
797a9f9c 1597
50c75381 1598=item i_utf8_advance(char **p, size_t *len)
797a9f9c 1599
50c75381 1600Retrieve a C<UTF-8> character from the stream.
797a9f9c 1601
50c75381 1602Modifies *p and *len to indicate the consumed characters.
797a9f9c 1603
50c75381
TC
1604This doesn't support the extended C<UTF-8> encoding used by later
1605versions of Perl.
1606
1607This doesn't check that the C<UTF-8> character is using the shortest
1608possible representation.
797a9f9c 1609
718b8c97 1610
50c75381
TC
1611=for comment
1612From: File io.c
718b8c97 1613
797a9f9c
TC
1614
1615
92bda632
TC
1616=back
1617
1618
1619=head1 AUTHOR
1620
1621Tony Cook <tony@imager.perl.org>
1622
1623=head1 SEE ALSO
1624
1625Imager, Imager::ExtUtils, Imager::Inline
1626
1627=cut