1Imager::Draw(3)       User Contributed Perl Documentation      Imager::Draw(3)
2
3
4

NAME

6       Imager::Draw - Draw primitives to images
7

SYNOPSIS

9         use Imager;
10         use Imager::Fill;
11
12         $img = ...;
13         $blue = Imager::Color->new( 0, 0, 255 );
14         $fill = Imager::Fill->new(hatch=>'stipple');
15
16         $img->line(color=>$blue, x1=>10, x2=>100,
17                                  y1=>20, y2=>50, aa=>1, endp=>1 );
18
19         $img->polyline(points=>[[$x0,$y0], [$x1,$y1], [$x2,$y2]],
20                        color=>$blue);
21         $img->polyline(x=>[$x0,$x1,$x2], y=>[$y0,$y1,$y2], aa=>1);
22
23         $img->box(color=> $blue, xmin=> 10, ymin=>30,
24                                  xmax=>200, ymax=>300, filled=>1);
25         $img->box(fill=>$fill);
26
27         $img->arc(color=>$blue, r=>20, x=>200, y=>100,
28                   d1=>10, d2=>20 );
29
30         $img->circle(color=>$blue, r=>50, x=>200, y=>100);
31
32         $img->polygon(points=>[[$x0,$y0], [$x1,$y1], [$x2,$y2]],
33                       color=>$blue);
34
35         $img->polygon(x=>[$x0,$x1,$x2], y=>[$y0,$y1,$y2]);
36
37         $img->flood_fill(x=>50, y=>50, color=>$color);
38
39         $img->setpixel(x=>50, y=>70, color=>$color);
40
41         $img->setpixel(x=>[ 50, 60, 70 ], y=>[20, 30, 40], color=>$color);
42
43         my $color = $img->getpixel(x=>50, y=>70);
44
45         my @colors = $img->getpixel(x=>[ 50, 60, 70 ], y=>[20, 30, 40]);
46
47         # drawing text
48         my $font = Imager::Font->new(...) or die;
49         $img->string(x => 50, y => 70,
50                      font => $font,
51                      string => "Hello, World!",
52                      color => 'red',
53                      size => 30,
54                      aa => 1);
55
56         # bottom right-hand corner of the image
57         $img->align_string(x => $img->getwidth() - 1,
58                            y => $img->getheight() - 1,
59                            halign => 'right',
60                            valign => 'bottom',
61                            string => 'Imager',
62                            font => $font,
63                            size => 12);
64
65         # low-level functions
66         my @colors = $img->getscanline(y=>50, x=>10, width=>20);
67
68         $img->setscanline(y=>60, x=>20, pixels=>\@colors);
69
70         my @samples = $img->getsamples(y=>50, x=>10, width=>20,
71                                        channels=>[ 2, 0 ]);
72

DESCRIPTION

74       It is possible to draw with graphics primitives onto images.  Such
75       primitives include boxes, arcs, circles, polygons and lines.  The
76       coordinate system in Imager has the origin "(0,0)" in the upper left
77       corner of an image with co-ordinates increasing to the right and
78       bottom.  For non anti-aliasing operation all coordinates are rounded
79       towards the nearest integer.  For anti-aliased operations floating
80       point coordinates are used.
81
82       Drawing is assumed to take place in a coordinate system of infinite
83       resolution.  This is the typical convention and really only matters
84       when it is necessary to check for off-by-one cases.  Typically it's
85       useful to think of "(10, 20)" as "(10.00, 20.00)" and consider the
86       consequences.
87
88   Color Parameters
89       The "color" parameter for any of the drawing methods can be an
90       Imager::Color object, a simple scalar that Imager::Color can
91       understand, a hashref of parameters that Imager::Color->new
92       understands, or an arrayref of red, green, blue values, for example:
93
94         $image->box(..., color=>'red');
95         $image->line(..., color=>'#FF0000');
96         $image->flood_fill(..., color=>[ 255, 0, 255 ]);
97
98       While supplying colors as names, array references or CSS color
99       specifiers is convenient, for maximum performance you should supply the
100       color as an Imager::Color object:
101
102         my @colors = map Imager::Color->new($_), qw/red green blue/
103         for my $i (1..1000) {
104           $image->box(..., color => $colors[rand @colors]);
105         }
106
107   Fill Parameters
108       All filled primitives, i.e. "arc()", "box()", "circle()", "polygon()"
109       and the "flood_fill()" method can take a "fill" parameter instead of a
110       "color" parameter which can either be an Imager::Fill object, or a
111       reference to a hash containing the parameters used to create the fill,
112       for example:
113
114         $image->box(..., fill=>{ hatch => 'check1x1' });
115         my $fillimage = Imager->new;
116         $fillimage->read(file=>$somefile) or die;
117         $image->flood_fill(..., fill=>{ image=>$fillimage });
118
119       Currently you can create opaque or transparent plain color fills,
120       hatched fills, image based fills and fountain fills.  See Imager::Fill
121       for more information.
122
123   Polygon Fill Modes
124       When filling a polygon that overlaps itself, or when filling several
125       polygons with polypolygon() that overlap each other, you can supply a
126       "mode" parameter that controls how the overlap is resolved.  This can
127       have one of two possible values:
128
129       •   "evenodd" - if areas overlap an odd number of times, they are
130           filled, and are otherwise unfilled.  This is the default and the
131           historical Imager polygon fill mode.
132
133       •   "nonzero" - areas that have an unbalanced clockwise and anti-
134           clockwise boundary are filled.  This is the same as "WindingRule"
135           for X and "WINDING" for Win32 GDI.
136
137       "nonzero" allows polygons to overlap, either with itself, or with
138       another polygon in the same polypolygon() call, without producing
139       unfilled area in the overlap, and also allows areas to be cut out of
140       the area by specifying the points making up a cut-out in the opposite
141       order.
142
143   List of primitives
144       line()
145             $img->line(color=>$green, x1=>10, x2=>100,
146                                       y1=>20, y2=>50, aa=>1, endp=>1 );
147
148           Draws a line from (x1,y1) to (x2,y2).  The endpoint (x2,y2) is
149           drawn by default.  If "endp" of 0 is specified then the endpoint
150           will not be drawn.  If "aa" is set then the line will be drawn
151           anti-aliased.  The "antialias" parameter is still available for
152           backwards compatibility.
153
154           Parameters:
155
156           •   "x1", "y1" - starting point of the line.  Required.
157
158           •   "x2", "y2" - end point of the line. Required.
159
160           •   "color" - the color of the line.  See "Color Parameters".
161               Default: black.
162
163           •   "endp" - if zero the end point of the line is not drawn.
164               Default: 1 - the end point is drawn.  This is useful to set to
165               0 when drawing a series of connected lines.
166
167           •   "aa" - if true the line is drawn anti-aliased.  Default: 0.
168
169       polyline()
170             $img->polyline(points=>[[$x0,$y0],[$x1,$y1],[$x2,$y2]],color=>$red);
171             $img->polyline(x=>[$x0,$x1,$x2], y=>[$y0,$y1,$y2], aa=>1);
172
173           "polyline" is used to draw multiple lines between a series of
174           points.  The point set can either be specified as an arrayref to an
175           array of array references (where each such array represents a
176           point).  The other way is to specify two array references.
177
178           The "antialias" parameter is still available for backwards
179           compatibility.
180
181           •   points - a reference to an array of references to arrays
182               containing the co-ordinates of the points in the line, for
183               example:
184
185                 my @points = ( [ 0, 0 ], [ 100, 0 ], [ 100, 100 ], [ 0, 100 ] );
186                 $img->polyline(points => \@points);
187
188           •   x, y - each is an array of x or y ordinates.  This is an
189               alternative to supplying the "points" parameter.
190
191                 # same as the above points example
192                 my @x = ( 0, 100, 100, 0 );
193                 my @y = ( 0, 0, 100, 100 );
194                 $img->polyline(x => \@x, y => \@y);
195
196           •   "color" - the color of the line.  See "Color Parameters".
197               Default: black.
198
199           •   "aa" - if true the line is drawn anti-aliased.  Default: 0.
200               Can also be supplied as "antialias" for backward compatibility.
201
202       box()
203             $blue = Imager::Color->new( 0, 0, 255 );
204             $img->box(color => $blue, xmin=>10, ymin=>30, xmax=>200, ymax=>300,
205                       filled=>1);
206
207           If any of the edges of the box are omitted it will snap to the
208           outer edge of the image in that direction.  If "filled" is omitted
209           the box is drawn as an outline.  Instead of a color it is possible
210           to use a "fill" pattern:
211
212             $fill = Imager::Fill->new(hatch=>'stipple');
213             $img->box(fill=>$fill);  # fill entire image with a given fill pattern
214
215             $img->box(xmin=>10, ymin=>30, xmax=>150, ymax=>60,
216                       fill => { hatch=>'cross2' });
217
218           Also if a color is omitted a color with (255,255,255,255) is used
219           instead.  [NOTE: This may change to use "$img->fgcolor()" in the
220           future].
221
222           Box does not support fractional coordinates yet.
223
224           Parameters:
225
226           •   "xmin" - left side of the box.  Default: 0 (left edge of the
227               image)
228
229           •   "ymin" - top side of the box.  Default: 0 (top edge of the
230               image)
231
232           •   "xmax" - right side of the box.  Default: "$img->getwidth-1".
233               (right edge of the image)
234
235           •   "ymax" - bottom side of the box.  Default: "$img->getheight-1".
236               (bottom edge of the image)
237
238               Note: "xmax" and "ymax" are inclusive - the number of pixels
239               drawn for a filled box is "(xmax-xmin+1) * (ymax-ymin+1)".
240
241           •   "box" - a reference to an array of (left, top, right, bottom)
242               co-ordinates.  This is an alternative to supplying "xmin",
243               "ymin", "xmax", "ymax" and overrides their values.
244
245           •   "color" - the color of the line.  See "Color Parameters".
246               Default: white.  This is ignored if the filled parameter
247
248           •   "filled" - if non-zero the box is filled with color instead of
249               outlined.  Default: an outline is drawn.
250
251           •   "fill" - the fill for the box.  If this is supplied then the
252               box will be filled.  See "Fill Parameters".
253
254       arc()
255             $img->arc(color=>$red, r=>20, x=>200, y=>100, d1=>10, d2=>20 );
256
257           This creates a filled red arc with a 'center' at (200, 100) and
258           spans 10 degrees and the slice has a radius of 20.
259
260           It's also possible to supply a "fill" parameter.
261
262           To draw just an arc outline - just the curve, not the radius lines,
263           set filled to 0:
264
265           Parameters:
266
267             $img->arc(color=>$red, r=>20, x=>200, y=>100, d1=>10, d2=>20, filled=>0 );
268
269           •   "x", "y" - center of the filled arc.  Default: center of the
270               image.
271
272           •   "r" - radius of the arc.  Default: 1/3 of min(image height,
273               image width).
274
275           •   "d1" - starting angle of the arc, in degrees.  Default: 0
276
277           •   "d2" - ending angle of the arc, in degrees.  Default: 361.
278
279           •   "color" - the color of the filled arc.  See "Color Parameters".
280               Default: white.  Overridden by "fill".
281
282           •   "fill" - the fill for the filled arc.  See "Fill Parameters"
283
284           •   "aa" - if true the filled arc is drawn anti-aliased.  Default:
285               false.
286
287               Anti-aliased arc() is experimental for now, I'm not entirely
288               happy with the results in some cases.
289
290           •   "filled" - set to 0 to draw only an outline.
291
292             # arc going through angle zero:
293             $img->arc(d1=>320, d2=>40, x=>100, y=>100, r=>50, color=>'blue');
294
295             # complex fill arc
296             $img->arc(d1=>135, d2=>45, x=>100, y=>150, r=>50,
297                       fill=>{ solid=>'red', combine=>'diff' });
298
299             # draw an anti-aliased circle outline
300             $img->arc(x => 100, y => 150, r => 150, filled => 0,
301                       color => '#F00', aa => 1);
302
303             # draw an anti-aliased arc
304             $img->arc(x => 100, y => 150, r => 90, filled => 0,
305                       color => '#0f0', aa => 1, d1 => 90, d2 => 180);
306
307       circle()
308             $img->circle(color=>$green, r=>50, x=>200, y=>100, aa=>1, filled=>1);
309
310           This creates an anti-aliased green circle with its center at (200,
311           100) and has a radius of 50.  It's also possible to supply a "fill"
312           parameter instead of a color parameter.
313
314             $img->circle(r => 50, x=> 150, y => 150, fill=>{ hatch => 'stipple' });
315
316           To draw a circular outline, set "filled" to 0:
317
318             $img->circle(color=>$green, r=>50, x=>200, y=>100, aa=>1, filled=>0);
319
320           •   "x", "y" - center of the filled circle.  Default: center of the
321               image.
322
323           •   "r" - radius of the circle.  Default: 1/3 of min(image height,
324               image width).
325
326           •   "color" - the color of the filled circle.  See "Color
327               Parameters".  Default: white.  Overridden by "fill".
328
329           •   "fill" - the fill for the filled circle.  See "Fill Parameters"
330
331           •   "aa" - if true the filled circle is drawn anti-aliased.
332               Default: false.
333
334           •   "filled" - set to 0 to just draw an outline.
335
336       polygon()
337             $img->polygon(points=>[[$x0,$y0],[$x1,$y1],[$x2,$y2]],color=>$red);
338             $img->polygon(x=>[$x0,$x1,$x2], y=>[$y0,$y1,$y2], fill=>$fill);
339
340           Polygon is used to draw a filled polygon.  Currently the polygon is
341           always drawn anti-aliased, although that will change in the future.
342           Like other anti-aliased drawing functions its coordinates can be
343           specified with floating point values.  As with other filled shapes
344           it's possible to use a "fill" instead of a color.
345
346           •   "points" - a reference to an array of references to arrays
347               containing the co-ordinates of the points in the line, for
348               example:
349
350                 my @points = ( [ 0, 0 ], [ 100, 0 ], [ 100, 100 ], [ 0, 100 ] );
351                 $img->polygon(points => \@points);
352
353           •   "x", "y" - each is an array of x or y ordinates.  This is an
354               alternative to supplying the "points" parameter.
355
356                 # same as the above points example
357                 my @x = ( 0, 100, 100, 0 );
358                 my @y = ( 0, 0, 100, 100 );
359                 $img->polygon(x => \@x, y => \@y);
360
361           •   "color" - the color of the filled polygon.  See "Color
362               Parameters".  Default: black.  Overridden by "fill".
363
364           •   "fill" - the fill for the filled circle.  See "Fill Parameters"
365
366           •   "mode" - fill mode for the polygon.  See "Polygon Fill Modes"
367
368           Note: the points specified are as offsets from the top-left of the
369           image, not as pixel locations.  This means that:
370
371             $img->polygon(points => [ [ 0, 0 ], [ 1, 0 ], [ 1, 1 ], [ 0, 1 ] ]);
372
373           fills only a single pixel at "(0, 0)", not four.
374
375       polypolygon()
376             $img->polypolygon(points => $points, color => $color);
377
378           Draw multiple polygons, either filled or unfilled.
379
380           •   "points" - is an array reference containing polygon
381               definitions, each polygon definition is a reference to an array
382               containing two arrays, one each for the "x" and "y" co-
383               ordinates.
384
385           •   "filled" - if true, fill the polygons with the color defined by
386               "color".
387
388           •   "color" - the color to draw the polygons with if "fill" is not
389               supplied.
390
391           •   "fill" - fill the polygons with this fill if supplied.
392
393           •   "mode" - fill mode for the polygon.  See "Polygon Fill Modes"
394
395           Note: the points specified are as offsets from the top-left of the
396           image, not as pixel locations.  This means that:
397
398             $img->polypolygon(points => [ [ [ 0, 1, 1, 0 ], [ 0, 0, 1, 1 ] ] ],
399                               filled => 1);
400
401           fills only a single pixel at "(0, 0)", not four.
402
403       flood_fill()
404           You can fill a region that all has the same color using the
405           flood_fill() method, for example:
406
407             $img->flood_fill(x=>50, y=>50, color=>$color);
408
409           will fill all regions the same color connected to the point (50,
410           50).
411
412           Alternatively you can fill a region limited by a given border
413           color:
414
415             # stop at the red border
416             $im->flood_fill(x=>50, y=>50, color=>$color, border=>"red");
417
418           You can also fill with a complex fill:
419
420             $img->flood_fill(x=>50, y=>50, fill=>{ hatch=>'cross1x1' });
421
422           Parameters:
423
424           •   "x", "y" - the start point of the fill.
425
426           •   "color" - the color of the filled area.  See "Color
427               Parameters".  Default: white.  Overridden by "fill".
428
429           •   "fill" - the fill for the filled area.  See "Fill Parameters"
430
431           •   "border" - the border color of the region to be filled.  If
432               this parameter is supplied flood_fill() will stop when it finds
433               this color.  If this is not supplied then a normal fill is
434               done.  "border" can be supplied as a "Color Parameters".
435
436       setpixel()
437             $img->setpixel(x=>50, y=>70, color=>$color);
438             $img->setpixel(x=>[ 50, 60, 70 ], y=>[20, 30, 40], color=>$color);
439
440           setpixel() is used to set one or more individual pixels.
441
442           You can supply a single set of co-ordinates as scalar "x" and "y"
443           parameters, or set either to an arrayref of ordinates.
444
445           If one array is shorter than another the final value in the shorter
446           will be duplicated until they match in length.
447
448           If only one of "x" or "y" is an array reference then setpixel()
449           will behave as if the non-reference value were an array reference
450           containing only that value.
451
452           eg.
453
454             my $count = $img->setpixel(x => 1, y => [ 0 .. 3 ], color => $color);
455
456           behaves like:
457
458             my $count = $img->setpixel(x => [ 1 ], y => [ 0 .. 3 ], color => $color);
459
460           and since the final element in the shorter array is duplicated,
461           this behaves like:
462
463             my $count = $img->setpixel(x => [ 1, 1, 1, 1 ], y => [ 0 .. 3 ],
464                                        color => $color);
465
466           Parameters:
467
468           •   x, y - either integers giving the co-ordinates of the pixel to
469               set or array references containing a set of pixels to be set.
470
471           •   color - the color of the pixels drawn.  See "Color Parameters".
472               Default: white.
473
474           Returns the number of pixels drawn, if no pixels were drawn, but
475           none of the errors below occur, returns "0 but true".
476
477           For other errors, setpixel() returns an empty list and sets
478           errstr().
479
480           Possible errors conditions include:
481
482           •   the image supplied is empty
483
484           •   a reference to an empty array was supplied for "x" or "y"
485
486           •   "x" or "y" wasn't supplied
487
488           •   "color" isn't a valid color, and can't be converted to a color.
489
490       getpixel()
491             my $color = $img->getpixel(x=>50, y=>70); my @colors =
492             $img->getpixel(x=>[ 50, 60, 70 ], y=>[20, 30, 40]); my $colors_ref =
493             $img->getpixel(x=>[ 50, 60, 70 ], y=>[20, 30, 40]);
494
495           getpixel() is used to retrieve one or more individual pixels.
496
497           You can supply a single set of co-ordinates as scalar "x" and "y"
498           parameters, or set each to an arrayref of ordinates.
499
500           If one array is shorter than another the final value in the shorter
501           will be duplicated until they match in length.
502
503           If only one of "x" or "y" is an array reference then getpixel()
504           will behave as if the non-reference value were an array reference
505           containing only that value.
506
507           eg.
508
509             my @colors = $img->getpixel(x => 0, y => [ 0 .. 3 ]);
510
511           behaves like:
512
513             my @colors = $img->getpixel(x => [ 0 ], y => [ 0 .. 3 ]);
514
515           and since the final element in the shorter array is duplicated,
516           this behaves like:
517
518             my @colors = $img->getpixel(x => [ 0, 0, 0, 0 ], y => [ 0 .. 3 ]);
519
520           To receive floating point colors from getpixel(), set the "type"
521           parameter to 'float'.
522
523           Parameters:
524
525           •   "x", "y" - either integers giving the co-ordinates of the pixel
526               to set or array references containing a set of pixels to be
527               set.
528
529           •   "type" - the type of color object to return, either '8bit' for
530               Imager::Color objects or 'float' for Imager::Color::Float
531               objects.  Default: '8bit'.
532
533           When called with an array reference for either or "x" or "y",
534           getpixel() will return a list of colors in list context, and an
535           arrayref in scalar context.
536
537           If a supplied co-ordinate is outside the image then "undef" is
538           returned for the pixel.
539
540           Each color is returned as an Imager::Color object or as an
541           Imager::Color::Float object if "type" is set to "float".
542
543           Possible errors conditions include:
544
545           •   the image supplied is empty
546
547           •   a reference to an empty array was supplied for "x" or "y"
548
549           •   "x" or "y" wasn't supplied
550
551           •   "type" isn't a valid value.
552
553           For any of these errors getpixel() returns an empty list.
554
555       string()
556             my $font = Imager::Font->new(file=>"foo.ttf");
557             $img->string(x => 50, y => 70,
558                          string => "Hello, World!",
559                          font => $font,
560                          size => 30,
561                          aa => 1,
562                          color => 'white');
563
564           Draws text on the image.
565
566           Parameters:
567
568           •   "x", "y" - the point to draw the text from.  If "align" is 0
569               this is the top left of the string.  If "align" is 1 (the
570               default) then this is the left of the string on the baseline.
571               Required.
572
573           •   "string" - the text to draw.  Required unless you supply the
574               "text" parameter.
575
576           •   "font" - an Imager::Font object representing the font to draw
577               the text with.  Required.
578
579           •   "aa" - if non-zero the output will be anti-aliased.  Default:
580               the value set in Imager::Font->new() or 0 if not set.
581
582           •   "align" - if non-zero the point supplied in (x,y) will be on
583               the base-line, if zero then (x,y) will be at the top-left of
584               the string.
585
586               i.e. if drawing the string "yA" and align is 0 the point (x,y)
587               will aligned with the top of the A.  If align is 1 (the
588               default) it will be aligned with the baseline of the font,
589               typically bottom of the A, depending on the font used.
590
591               Default: the value set in Imager::Font->new, or 1 if not set.
592
593           •   "channel" - if present, the text will be written to the
594               specified channel of the image and the color parameter will be
595               ignore.
596
597           •   "color" - the color to draw the text in.  Default: the color
598               supplied to Imager::Font->new, or red if none.
599
600           •   "size" - the point size to draw the text at.  Default: the size
601               supplied to Imager::Font->new, or 15.
602
603           •   "sizew" - the width scaling to draw the text at.  Default: the
604               value of "size".
605
606           •   "utf8" - for drivers that support it, treat the string as UTF-8
607               encoded.  For versions of perl that support Unicode (5.6 and
608               later), this will be enabled automatically if the "string"
609               parameter is already a UTF-8 string. See "UTF-8" in
610               Imager::Font for more information.
611
612           •   "vlayout" - for drivers that support it, draw the text
613               vertically.  Note: I haven't found a font that has the
614               appropriate metrics yet.
615
616           •   "text" - alias for the "string" parameter.
617
618           On error, string() returns false and you can use $img->errstr to
619           get the reason for the error.
620
621       align_string()
622           Draws text aligned around a point on the image.
623
624             # "Hello" centered at 100, 100 in the image.
625             my ($left, $top, $right, $bottom) =
626               $img->align_string(string=>"Hello",
627                                  x=>100, y=>100,
628                                  halign=>'center', valign=>'center',
629                                  font=>$font);
630
631           Parameters:
632
633           •   "x", "y" - the point to draw the text from.  If "align" is 0
634               this is the top left of the string.  If "align" is 1 (the
635               default) then this is the left of the string on the baseline.
636               Required.
637
638           •   "string" - the text to draw.  Required unless you supply the
639               "text" parameter.
640
641           •   "font" - an Imager::Font object representing the font to draw
642               the text with.  Required.
643
644           •   "aa" - if non-zero the output will be anti-aliased
645
646           •   "valign" - vertical alignment of the text against (x,y)
647
648               •   "top" - Point is at the top of the text.
649
650               •   "bottom" - Point is at the bottom of the text.
651
652               •   "baseline" - Point is on the baseline of the text.  This is
653                   the default.
654
655               •   "center" - Point is vertically centered within the text.
656
657           •   "halign" - horizontal alignment of the text against (x,y)
658
659               •   "left" - The point is at the left of the text.  This is the
660                   default.
661
662               •   "start" - The point is at the start point of the text.
663
664               •   "center" - The point is horizontally centered within the
665                   text.
666
667               •   "right" - The point is at the right end of the text.
668
669               •   "end" - The point is at the end point of the text.
670
671           •   "channel" - if present, the text will be written to the
672               specified channel of the image and the color parameter will be
673               ignore.
674
675           •   "color" - the color to draw the text in.  Default: the color
676               supplied to Imager::Font->new, or red if none.
677
678           •   "size" - the point size to draw the text at.  Default: the size
679               supplied to Imager::Font->new, or 15.
680
681           •   "sizew" - the width scaling to draw the text at.  Default: the
682               value of "size".
683
684           •   "utf8" - for drivers that support it, treat the string as UTF-8
685               encoded.  For versions of perl that support Unicode (5.6 and
686               later), this will be enabled automatically if the "string"
687               parameter is already a UTF-8 string. See "UTF-8" in
688               Imager::Font for more information.
689
690           •   "vlayout" - for drivers that support it, draw the text
691               vertically.  Note: I haven't found a font that has the
692               appropriate metrics yet.
693
694           •   "text" - alias for the "string" parameter.
695
696           On success returns a list of bounds of the drawn text, in the order
697           left, top, right, bottom.
698
699           On error, align_string() returns an empty list and you can use
700           "$img->errstr" to get the reason for the error.
701
702       setscanline()
703           Set all or part of a horizontal line of pixels to an image.  This
704           method is most useful in conjunction with "getscanline()".
705
706           The parameters you can pass are:
707
708           •   "y" - vertical position of the scan line.  This parameter is
709               required.
710
711           •   "x" - position to start on the scan line.  Default: 0
712
713           •   "pixels" - either a reference to an array containing
714               Imager::Color objects, an reference to an array containing
715               Imager::Color::Float objects or a scalar containing packed
716               color data.
717
718               If "type" is "index" then this can either be a reference to an
719               array of palette color indexes or a scalar containing packed
720               indexes.
721
722               See "Packed Color Data" for information on the format of packed
723               color data.
724
725           •   "type" - the type of pixel data supplied.  If you supply an
726               array reference then this is determined automatically.  If you
727               supply packed color data this defaults to '8bit', if your data
728               is packed floating point color data then you need to set this
729               to 'float'.
730
731               You can use "float" or "8bit" samples with any image.
732
733               If this is "index" then "pixels" should be either an array of
734               palette color indexes or a packed string of color indexes.
735
736           Returns the number of pixels set.
737
738           Each of the following sets 5 pixels from (5, 10) through (9, 10) to
739           blue, red, blue, red, blue:
740
741             my $red_color = Imager::Color->new(255, 0, 0);
742             my $blue_color = Imager::Color->new(0, 0, 255);
743
744             $image->setscanline(y=>10, x=>5, pixels=>
745                                 [ ($blue_color, $red_color) x 2, $blue_color ]);
746
747             # use floating point color instead, for 16-bit plus images
748             my $red_colorf = Imager::Color::Float->new(1.0, 0, 0);
749             my $blue_colorf = Imager::Color::Float->new(0, 0, 1.0);
750
751             $image->setscanline(y=>10, x=>5, pixels=>
752                                 [ ($blue_colorf, $red_colorf) x 2, $blue_colorf ]);
753
754             # packed 8-bit data
755             $image->setscanline(y=>10, x=>5, pixels=>
756                                 pack("C*", ((0, 0, 255, 255), (255, 0, 0, 255)) x 2,
757                                       (0, 0, 255, 255)));
758
759             # packed floating point samples
760             $image->setscanline(y=>10, x=>5, type=>'float', pixels=>
761                                 pack("d*", ((0, 0, 1.0, 1.0), (1.0, 0, 0, 1.0)) x 2,
762                                       (0, 0, 1.0, 1.0)));
763
764           Copy even rows from one image to another:
765
766             for (my $y = 0; $y < $im2->getheight; $y+=2) {
767               $im1->setscanline(y=>$y,
768                                 pixels=>scalar($im2->getscanline(y=>$y)));
769             }
770
771           Set the blue channel to 0 for all pixels in an image.  This could
772           be done with convert too:
773
774             for my $y (0..$im->getheight-1) {
775               my $row = $im->getscanline(y=>$y);
776               $row =~ s/(..).(.)/$1\0$2/gs;
777               $im->setscanline(y=>$y, pixels=>$row);
778             }
779
780       getscanline()
781           Read all or part of a horizontal line of pixels from an image.
782           This method is most useful in conjunction with "setscanline()".
783
784           The parameters you can pass are:
785
786           •   "y" - vertical position of the scan line.  This parameter is
787               required.
788
789           •   "x" - position to start on the scan line.  Default: 0
790
791           •   "width" - number of pixels to read.  Default: $img->getwidth -
792               x
793
794           •   "type" - the type of pixel data to return.  Default: "8bit".
795
796               Permitted values are "8bit" and "float" and "index".
797
798           In list context this method will return a list of Imager::Color
799           objects when type is "8bit", or a list of Imager::Color::Float
800           objects when type if "float", or a list of integers when type is
801           "index".
802
803           In scalar context this returns a packed 8-bit pixels when type is
804           "8bit", or a list of packed floating point pixels when type is
805           "float", or packed palette color indexes when type is "index".
806
807           The values of samples for which the image does not have channels is
808           undefined.  For example, for a single channel image the values of
809           channels 1 through 3 are undefined.
810
811           Check image for a given color:
812
813             my $found;
814             YLOOP: for my $y (0..$img->getheight-1) {
815               my @colors = $img->getscanline(y=>$y);
816               for my $color (@colors) {
817                 my ($red, $green, $blue, $alpha) = $color->rgba;
818                 if ($red == $test_red && $green == $test_green && $blue == $test_blue
819                     && $alpha == $test_alpha) {
820                   ++$found;
821                   last YLOOP;
822                 }
823               }
824             }
825
826           Or do it using packed data:
827
828             my $found;
829             my $test_packed = pack("CCCC", $test_red, $test_green, $test_blue,
830                                    $test_alpha);
831             YLOOP: for my $y (0..$img->getheight-1) {
832               my $colors = $img->getscanline(y=>$y);
833               while (length $colors) {
834                 if (substr($colors, 0, 4, '') eq $test_packed) {
835                   ++$found;
836                   last YLOOP;
837                 }
838               }
839             }
840
841           Some of the examples for "setscanline()" for more examples.
842
843       getsamples()
844           Read specified channels from all or part of a horizontal line of
845           pixels from an image.
846
847           The parameters you can pass are:
848
849           •   "y" - vertical position of the scan line.  This parameter is
850               required.
851
852           •   "x" - position to start on the scan line.  Default: 0
853
854           •   "width" - number of pixels to read.  Default: "$img->getwidth -
855               x"
856
857           •   "type" - the type of sample data to return.  Default: "8bit".
858
859               Permitted values are "8bit" and "float".
860
861               As of Imager 0.61 this can be "16bit" only for 16 bit images.
862
863           •   "channels" - a reference to an array of channels to return,
864               where 0 is the first channel.  Default: "[ 0 ..
865               $self->getchannels()-1 ]"
866
867           •   "target" - if an array reference is supplied in target then the
868               samples will be stored here instead of being returned.
869
870           •   "offset" - the offset within the array referenced by target
871
872           In list context this will return a list of integers between 0 and
873           255 inclusive when type is "8bit", or a list of floating point
874           numbers between 0.0 and 1.0 inclusive when type is "float".
875
876           In scalar context this will return a string of packed bytes, as
877           with " pack("C*", ...) " when type is "8bit" or a string of packed
878           doubles as with " pack("d*", ...) " when type is "float".
879
880           If the target option is supplied then only a count of samples is
881           returned.
882
883           Example: Check if any pixels in an image have a non-zero alpha
884           channel:
885
886             my $has_coverage;
887             for my $y (0 .. $img->getheight()-1) {
888               my $alpha = $img->getsamples(y=>$y, channels=>[0]);
889               if ($alpha =~ /[^\0]/) {
890                 ++$has_coverage;
891                 last;
892               }
893             }
894
895           Example: Convert a 2 channel gray image into a 4 channel RGBA
896           image:
897
898             # this could be done with convert() instead
899             my $out = Imager->new(xsize => $src->getwidth(),
900                                   ysize => $src->getheight(),
901                                   channels => 4);
902             for my $y ( 0 .. $src->getheight()-1 ) {
903               my $data = $src->getsamples(y=>$y, channels=>[ 0, 0, 0, 1 ]);
904               $out->setscanline(y=>$y, pixels=>$data);
905             }
906
907           Retrieve 16-bit samples:
908
909             if ($img->bits == 16) {
910               my @samples;
911               $img->getsamples(x => 0, y => $y, target => \@samples, type => '16bit');
912             }
913
914       setsamples()
915           This allows writing of samples to an image.
916
917           Parameters:
918
919           •   "y" - vertical position of the scan line.  This parameter is
920               required.
921
922           •   "x" - position to start on the scan line.  Default: 0
923
924           •   "width" - number of pixels to write.  Default: "$img->getwidth
925               - x".  The minimum of this and the number of pixels represented
926               by the samples provided will be written.
927
928           •   "type" - the type of sample data to write.  This parameter is
929               required.
930
931               This can be "8bit", "float" or for 16-bit images only, "16bit".
932
933           •   "channels" - a reference to an array of channels to return,
934               where 0 is the first channel.  Default: "[ 0 ..
935               $self->getchannels()-1 ]"
936
937           •   "data" - for a type of "8bit" or "float" this can be a
938               reference to an array of samples or a scalar containing packed
939               samples.  If "data" is a scalar it may only contain characters
940               from \x00 to \xFF.
941
942               For a type of "16bit" this can only be a reference to an array
943               of samples to write.
944
945               Required.
946
947           •   "offset" - the starting offset within the array referenced by
948               data.  If "data" is a scalar containing packed samples this
949               offset is in samples.
950
951           Returns the number of samples written.
952
953             $targ->setsamples(y => $y, data => \@data);
954
955             $targ->setsamples(y => $y, data => \@data, offset => $src->getchannels);
956
957           Copy from one image to another:
958
959             my $targ = Imager->new(xsize => $src->getwidth,
960                   ysize => $src->getheight, channels => $src->getchannels);
961             for my $y (0 .. $targ->getheight()-1) {
962               my $row = $src->getsamples(y => $y)
963                 or die $src->errstr;
964               $targ->setsamples(y => $y, data => $row)
965                 or die $targ->errstr;;
966             }
967
968           Compose an image from separate source channels:
969
970             my @src = ...; # images to work from, up to 4
971             my $targ = Imager->new(xsize => $src[0]->getwidth,
972                ysize => $src[0]->getheight, channels => scalar(@src));
973             for my $y (0 .. $targ->getheight()-1) {
974               for my $ch (0 .. $#src) {
975                 my $row = $src[$ch]->getsamples(y => $y, channels => [ 0 ]);
976                 $targ->setsamples(y => $y, data => $row, channels => [ $ch ] );
977               }
978             }
979

Packed Color Data

981       The getscanline() and setscanline() methods can work with pixels packed
982       into scalars.  This is useful to remove the cost of creating color
983       objects, but should only be used when performance is an issue.
984
985       The getsamples() and setsamples() methods can work with samples packed
986       into scalars.
987
988       Packed data can either be 1 byte per sample or 1 double per sample.
989
990       Each pixel returned by getscanline() or supplied to setscanline()
991       contains 4 samples, even if the image has fewer then 4 channels.  The
992       values of the extra samples as returned by getscanline() is not
993       specified.  The extra samples passed to setscanline() are ignored.
994
995       To produce packed 1 byte/sample pixels, use the pack "C" template:
996
997         my $packed_8bit_pixel = pack("CCCC", $red, $blue, $green, $alpha);
998
999       To produce packed double/sample pixels, use the pack "d" template:
1000
1001         my $packed_float_pixel = pack("dddd", $red, $blue, $green, $alpha);
1002
1003       Note that double/sample data is always stored using the C "double"
1004       type, never "long double", even if "perl" is built with
1005       "-Duselongdouble".
1006
1007       If you use a type parameter of "index" then the values are palette
1008       color indexes, not sample values:
1009
1010         my $im = Imager->new(xsize => 100, ysize => 100, type => 'paletted');
1011         my $black_index = $im->addcolors(colors => [ 'black' ]);
1012         my $red_index = $im->addcolors(colors => [ 'red' ]);
1013         # 2 pixels
1014         my $packed_index_data = pack("C*", $black_index, $red_index);
1015         $im->setscanline(y => $y, pixels => $packed_index_data, type => 'index');
1016

Combine Types

1018       Some methods accept a "combine" parameter, this can be any of the
1019       following:
1020
1021       "none"
1022           The fill pixel replaces the target pixel.
1023
1024       "normal"
1025           The fill pixels alpha value is used to combine it with the target
1026           pixel.
1027
1028       "multiply"
1029       "mult"
1030           Each channel of fill and target is multiplied, and the result is
1031           combined using the alpha channel of the fill pixel.
1032
1033       "dissolve"
1034           If the alpha of the fill pixel is greater than a random number, the
1035           fill pixel is alpha combined with the target pixel.
1036
1037       "add"
1038           The channels of the fill and target are added together, clamped to
1039           the range of the samples and alpha combined with the target.
1040
1041       "subtract"
1042           The channels of the fill are subtracted from the target, clamped to
1043           be >= 0, and alpha combined with the target.
1044
1045       "diff"
1046           The channels of the fill are subtracted from the target and the
1047           absolute value taken this is alpha combined with the target.
1048
1049       "lighten"
1050           The higher value is taken from each channel of the fill and target
1051           pixels, which is then alpha combined with the target.
1052
1053       "darken"
1054           The higher value is taken from each channel of the fill and target
1055           pixels, which is then alpha combined with the target.
1056
1057       "hue"
1058           The combination of the saturation and value of the target is
1059           combined with the hue of the fill pixel, and is then alpha combined
1060           with the target.
1061
1062       "sat"
1063           The combination of the hue and value of the target is combined with
1064           the saturation of the fill pixel, and is then alpha combined with
1065           the target.
1066
1067       "value"
1068           The combination of the hue and value of the target is combined with
1069           the value of the fill pixel, and is then alpha combined with the
1070           target.
1071
1072       "color"
1073           The combination of the value of the target is combined with the hue
1074           and saturation of the fill pixel, and is then alpha combined with
1075           the target.
1076
1077       combines()
1078           Returns a list of possible combine types.
1079

BUGS

1081       box() does not support anti-aliasing yet.  Default color is not unified
1082       yet.
1083

AUTHOR

1085       Tony Cook <tonyc@cpan.org>, Arnar M. Hrafnkelsson.
1086

SEE ALSO

1088       Imager(3), Imager::Cookbook(3)
1089

REVISION

1091       $Revision$
1092
1093
1094
1095perl v5.32.1                      2021-01-27                   Imager::Draw(3)
Impressum