1Imager::Draw(3) User Contributed Perl Documentation Imager::Draw(3)
2
6 Imager::Draw - Draw primitives to images
7
9 use Imager;
10 use Imager::Fill;
11 $img = ...;
13 $blue = Imager::Color->new( 0, 0, 255 );
14 $fill = Imager::Fill->new(hatch=>'stipple');
15 $img->line(color=>$blue, x1=>10, x2=>100,
17 y1=>20, y2=>50, aa=>1, endp=>1 );
18 $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 $img->box(color=> $blue, xmin=> 10, ymin=>30,
24 xmax=>200, ymax=>300, filled=>1);
25 $img->box(fill=>$fill);
26 $img->arc(color=>$blue, r=>20, x=>200, y=>100,
28 d1=>10, d2=>20 );
29 $img->circle(color=>$blue, r=>50, x=>200, y=>100);
31 $img->polygon(points=>[[$x0,$y0], [$x1,$y1], [$x2,$y2]],
33 color=>$blue);
34 $img->polygon(x=>[$x0,$x1,$x2], y=>[$y0,$y1,$y2]);
36 $img->flood_fill(x=>50, y=>50, color=>$color);
38 $img->setpixel(x=>50, y=>70, color=>$color);
40 $img->setpixel(x=>[ 50, 60, 70 ], y=>[20, 30, 40], color=>$color);
42 my $color = $img->getpixel(x=>50, y=>70);
44 my @colors = $img->getpixel(x=>[ 50, 60, 70 ], y=>[20, 30, 40]);
46 # 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 # 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 # low-level functions
66 my @colors = $img->getscanline(y=>50, x=>10, width=>20);
67 $img->setscanline(y=>60, x=>20, pixels=>\@colors);
69 my @samples = $img->getsamples(y=>50, x=>10, width=>20,
71 channels=>[ 2, 0 ]);
72
74 It is possible to draw with graphics primitives onto images. Such
75 primitives include boxes, arcs, circles, polygons and lines. The coor‐
76 dinate system in Imager has the origin "(0,0)" in the upper left corner
77 of an image with co-ordinates increasing to the right and bottom. For
78 non antialiasing operation all coordinates are rounded towards the
79 nearest integer. For antialiased operations floating point coordinates
80 are used.
81 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 usefull to think of "(10, 20)" as "(10.00, 20.00)" and consider the
86 consiquences.
87 Color Parameters
89 The "color" parameter for any of the drawing methods can be an
91 Imager::Color object, a simple scalar that Imager::Color can under‐
92 stand, a hashref of parameters that Imager::Color->new understands, or
93 an arrayref of red, green, blue values, for example:
94 $image->box(..., color=>'red');
96 $image->line(..., color=>'#FF0000');
97 $image->flood_fill(..., color=>[ 255, 0, 255 ]);
98 Fill Parameters
100 All filled primitives, i.e. "arc()", "box()", "circle()", "polygon()"
102 and the "flood_fill()" method can take a "fill" parameter instead of a
103 "color" parameter which can either be an Imager::Fill object, or a ref‐
104 erence to a hash containing the parameters used to create the fill, for
105 example:
106 $image->box(..., fill=>{ hatch => 'check1x1' });
108 my $fillimage = Imager->new;
109 $fillimage->read(file=>$somefile) or die;
110 $image->flood_fill(..., fill=>{ image=>$fillimage });
111 Currently you can create opaque or transparent plain color fills,
113 hatched fills, image based fills and fountain fills. See Imager::Fill
114 for more information.
115 List of primitives
117 line
119 $img->line(color=>$green, x1=>10, x2=>100,
120 y1=>20, y2=>50, aa=>1, endp=>1 );
121 Draws a line from (x1,y1) to (x2,y2). The endpoint (x2,y2) is
123 drawn by default. If endp of 0 is specified then the endpoint will
124 not be drawn. If "aa" is set then the line will be drawn
125 antialiased. The antialias parameter is still available for back‐
126 wards compatibility.
127 Parameters:
129 * x1, y1 - starting point of the line. Required.
131 * x2, y2 - end point of the line. Required.
133 * color - the color of the line. See "Color Parameters".
135 Default: black.
136 * endp - if zero the end point of the line is not drawn.
138 Default: 1 - the end point is drawn. This is useful to set to
139 0 when drawning a series of connected lines.
140 * aa - if true the line is drawn anti-aliased. Default: 0.
142 polyline
144 $img->polyline(points=>[[$x0,$y0],[$x1,$y1],[$x2,$y2]],color=>$red);
145 $img->polyline(x=>[$x0,$x1,$x2], y=>[$y0,$y1,$y2], aa=>1);
146 Polyline is used to draw multilple lines between a series of
148 points. The point set can either be specified as an arrayref to an
149 array of array references (where each such array represents a
150 point). The other way is to specify two array references.
151 The antialias parameter is still available for backwards compati‐
153 bility.
154 * points - a reference to an array of references to arrays con‐
156 taining the co-ordinates of the points in the line, for exam‐
157 ple:
158 my @points = ( [ 0, 0 ], [ 100, 0 ], [ 100, 100 ], [ 0, 100 ] );
160 $img->polyline(points => \@points);
161 * x, y - each is an array of x or y ordinates. This is an alter‐
163 native to supplying the "points" parameter.
164 # same as the above points example
166 my @x = ( 0, 100, 100, 0 );
167 my @y = ( 0, 0, 100, 100 );
168 $img->polyline(x => \@x, y => \@y);
169 * color - the color of the line. See "Color Parameters".
171 Default: black.
172 * aa - if true the line is drawn anti-aliased. Default: 0. Can
174 also be supplied as "antialias" for backward compatibility.
175 box
177 $blue = Imager::Color->new( 0, 0, 255 );
178 $img->box(color => $blue, xmin=>10, ymin=>30, xmax=>200, ymax=>300,
179 filled=>1);
180 If any of the edges of the box are ommited it will snap to the
182 outer edge of the image in that direction. If "filled" is ommited
183 the box is drawn as an outline. Instead of a color it is possible
184 to use a "fill" pattern:
185 $fill = Imager::Fill->new(hatch=>'stipple');
187 $img->box(fill=>$fill); # fill entire image with a given fill pattern
188 $img->box(xmin=>10, ymin=>30, xmax=>150, ymax=>60,
190 fill => { hatch=>'cross2' });
191 Also if a color is omitted a color with (255,255,255,255) is used
193 instead. [NOTE: This may change to use "$img->fgcolor()" in the
194 future].
195 Box does not support fractional coordinates yet.
197 Parameters:
199 * xmin - left side of the box. Default: 0 (left edge of the
201 image)
202 * ymin - top side of the box. Default: 0 (top edge of the image)
204 * xmax - right side of the box. Default: $img->getwidth-1.
206 (right edge of the image)
207 * ymax - bottom side of the box. Default: $img->getheight-1.
209 (bottom edge of the image)
210 Note: xmax and ymax are inclusive - the number of pixels drawn
212 for a filled box is (xmax-xmin+1) * (ymax-ymin+1).
213 * box - a reference to an array of (left, top, right, bottom)
215 co-ordinates. This is an alternative to supplying xmin, ymin,
216 xmax, ymax and overrides their values.
217 * color - the color of the line. See "Color Parameters".
219 Default: white. This is ignored if the filled parameter
220 * filled - if non-zero the box is filled with color instead of
222 outlined. Default: an outline is drawn.
223 * fill - the fill for the box. If this is supplied then the box
225 will be filled. See "Fill Parameters".
226 arc
228 $img->arc(color=>$red, r=>20, x=>200, y=>100, d1=>10, d2=>20 );
229 This creates a filled red arc with a 'center' at (200, 100) and
231 spans 10 degrees and the slice has a radius of 20. [NOTE: arc has a
232 BUG in it right now for large differences in angles.] It's also
233 possible to supply a "fill" parameter.
234 Parameters:
236 * x, y - center of the filled arc. Default: center of the image.
238 * r - radius of the arc. Default: 1/3 of min(image height, image
240 width).
241 * d1 - starting angle of the arc, in degrees. Default: 0
243 * d2 - ending angle of the arc, in degrees. Default: 361.
245 * color - the color of the filled arc. See "Color Parameters".
247 Default: white. Overridden by "fill".
248 * fill - the fill for the filled arc. See "Fill Parameters"
250 * aa - if true the filled arc is drawn anti-aliased. Default:
252 false.
253 Anti-aliased arc() is experimental for now, I'm not entirely
255 happy with the results in some cases.
256 # arc going through angle zero:
258 $img->arc(d1=>320, d2=>40, x=>100, y=>100, r=>50, color=>'blue');
259 # complex fill arc
261 $img->arc(d1=>135, d2=>45, x=>100, y=>150, r=>50,
262 fill=>{ solid=>'red', combine=>'diff' });
263 circle
265 $img->circle(color=>$green, r=>50, x=>200, y=>100, aa=>1, filled=>1);
266 This creates an antialiased green circle with its center at (200,
268 100) and has a radius of 50. It's also possible to supply a "fill"
269 parameter instead of a color parameter.
270 $img->circle(r => 50, x=> 150, y => 150, fill=>{ hatch => 'stipple' });
272 The circle is always filled but that might change, so always pass a
274 filled=>1 parameter if you want it to be filled.
275 * x, y - center of the filled circle. Default: center of the
277 image.
278 * r - radius of the circle. Default: 1/3 of min(image height,
280 image width).
281 * color - the color of the filled circle. See "Color Parame‐
283 ters". Default: white. Overridden by "fill".
284 * fill - the fill for the filled circle. See "Fill Parameters"
286 * aa - if true the filled circle is drawn anti-aliased. Default:
288 false.
289 polygon
291 $img->polygon(points=>[[$x0,$y0],[$x1,$y1],[$x2,$y2]],color=>$red);
292 $img->polygon(x=>[$x0,$x1,$x2], y=>[$y0,$y1,$y2], fill=>$fill);
293 Polygon is used to draw a filled polygon. Currently the polygon is
295 always drawn antialiased, although that will change in the future.
296 Like other antialiased drawing functions its coordinates can be
297 specified with floating point values. As with other filled shapes
298 it's possible to use a "fill" instead of a color.
299 * points - a reference to an array of references to arrays con‐
301 taining the co-ordinates of the points in the line, for exam‐
302 ple:
303 my @points = ( [ 0, 0 ], [ 100, 0 ], [ 100, 100 ], [ 0, 100 ] );
305 $img->polygon(points => \@points);
306 * x, y - each is an array of x or y ordinates. This is an alter‐
308 native to supplying the "points" parameter.
309 # same as the above points example
311 my @x = ( 0, 100, 100, 0 );
312 my @y = ( 0, 0, 100, 100 );
313 $img->polygon(x => \@x, y => \@y);
314 * color - the color of the filled polygon. See "Color Parame‐
316 ters". Default: black. Overridden by "fill".
317 * fill - the fill for the filled circle. See "Fill Parameters"
319 flood_fill
321 You can fill a region that all has the same color using the
322 flood_fill() method, for example:
323 $img->flood_fill(x=>50, y=>50, color=>$color);
325 will fill all regions the same color connected to the point (50,
327 50).
328 Alternatively you can fill a region limited by a given border
330 color:
331 # stop at the red border
333 $im->flood_fill(x=>50, y=>50, color=>$color, border=>"red");
334 You can also fill with a complex fill:
336 $img->flood_fill(x=>50, y=>50, fill=>{ hatch=>'cross1x1' });
338 Parameters:
340 * x, y - the start point of the fill.
342 * color - the color of the filled area. See "Color Parameters".
344 Default: white. Overridden by "fill".
345 * fill - the fill for the filled area. See "Fill Parameters"
347 * border - the border color of the region to be filled. If this
349 parameter is supplied flood_fill() will stop when it finds this
350 color. If this is not supplied then a normal fill is done.
351 "border" can be supplied as a "Color Parameter".
352 setpixel
354 $img->setpixel(x=>50, y=>70, color=>$color);
355 $img->setpixel(x=>[ 50, 60, 70 ], y=>[20, 30, 40], color=>$color);
356 setpixel() is used to set one or more individual pixels.
358 Parameters:
360 * x, y - either integers giving the co-ordinates of the pixel to
362 set or array references containing a set of pixels to be set.
363 * color - the color of the pixels drawn. See "Color Parameters".
365 Default: white.
366 When called with array parameters, returns the number of pixels
368 successfully set, or false if none.
369 When called with scalars for x and y, return $img on success, false
371 on failure.
372 getpixel
374 my $color = $img->getpixel(x=>50, y=>70);
375 my @colors = $img->getpixel(x=>[ 50, 60, 70 ], y=>[20, 30, 40]);
376 my $colors_ref = $img->getpixel(x=>[ 50, 60, 70 ], y=>[20, 30, 40]);
377 getpixel() is used to retrieve one or more individual pixels.
379 For either method you can supply a single set of co-ordinates as
381 scalar x and y parameters, or set each to an arrayref of ordinates.
382 When called with arrays, getpixel() will return a list of colors in
384 list context, and an arrayref in scalar context.
385 To receive floating point colors from getpixel, set the "type"
387 parameter to 'float'.
388 Parameters:
390 * x, y - either integers giving the co-ordinates of the pixel to
392 set or array references containing a set of pixels to be set.
393 * type - the type of color object to return, either '8bit' for
395 Imager::Color objects or 'float' for Imager::Color::Float
396 objects. Default: '8bit'.
397 string
399 my $font = Imager::Font->new(file=>"foo.ttf");
400 $img->string(x => 50, y => 70,
401 string => "Hello, World!",
402 font => $font,
403 size => 30,
404 aa => 1,
405 color => 'white');
406 Draws text on the image.
408 Parameters:
410 * x, y - the point to draw the text from. If "align" is 0 this
412 is the top left of the string. If "align" is 1 (the default)
413 then this is the left of the string on the baseline. Required.
414 * string - the text to draw. Required unless you supply the
416 "text" parameter.
417 * font - an Imager::Font object representing the font to draw the
419 text with. Required.
420 * aa - if non-zero the output will be anti-aliased. Default: the
422 value set in Imager::Font->new() or 0 if not set.
423 * align - if non-zero the point supplied in (x,y) will be on the
425 base-line, if zero then (x,y) will be at the top-left of the
426 string.
427 ie. if drawing the string "yA" and align is 0 the point (x,y)
429 will aligned with the top of the A. If align is 1 (the
430 default) it will be aligned with the baseline of the font, typ‐
431 ically bottom of the A, depending on the font used.
432 Default: the value set in Imager::Font->new, or 1 if not set.
434 * channel - if present, the text will be written to the specified
436 channel of the image and the color parameter will be ignore.
437 * color - the color to draw the text in. Default: the color sup‐
439 plied to Imager::Font->new, or red if none.
440 * size - the point size to draw the text at. Default: the size
442 supplied to Imager::Font->new, or 15.
443 * sizew - the width scaling to draw the text at. Default: the
445 value of "size".
446 * utf8 - for drivers that support it, treat the string as UTF8
448 encoded. For versions of perl that support Unicode (5.6 and
449 later), this will be enabled automatically if the "string"
450 parameter is already a UTF8 string. See "UTF8" in Imager::Font
451 for more information.
452 * vlayout - for drivers that support it, draw the text verti‐
454 cally. Note: I haven't found a font that has the appropriate
455 metrics yet.
456 * text - alias for the "string" parameter.
458 On error, string() returns false and you can use $img->errstr to
460 get the reason for the error.
461 align_string
463 Draws text aligned around a point on the image.
464 # "Hello" centered at 100, 100 in the image.
466 my ($left, $top, $right, $bottom) =
467 $img->align_string(string=>"Hello",
468 x=>100, y=>100,
469 halign=>'center', valign=>'center',
470 font=>$font);
471 Parameters:
473 * x, y - the point to draw the text from. If "align" is 0 this
475 is the top left of the string. If "align" is 1 (the default)
476 then this is the left of the string on the baseline. Required.
477 * string - the text to draw. Required unless you supply the
479 "text" parameter.
480 * font - an Imager::Font object representing the font to draw the
482 text with. Required.
483 * aa - if non-zero the output will be anti-aliased
485 * valign - vertical alignment of the text against (x,y)
487 * top - Point is at the top of the text.
489 * bottom - Point is at the bottom of the text.
491 * baseline - Point is on the baseline of the text. This is
493 the default.
494 * center - Point is vertically centered within the text.
496 * halign - horizontal alignment of the text against (x,y)
498 * left - The point is at the left of the text. This is the
500 default.
501 * start - The point is at the start point of the text.
503 * center - The point is horizontally centered within the
505 text.
506 * right - The point is at the right end of the text.
508 * end - The point is at the end point of the text.
510 * channel - if present, the text will be written to the specified
512 channel of the image and the color parameter will be ignore.
513 * color - the color to draw the text in. Default: the color sup‐
515 plied to Imager::Font->new, or red if none.
516 * size - the point size to draw the text at. Default: the size
518 supplied to Imager::Font->new, or 15.
519 * sizew - the width scaling to draw the text at. Default: the
521 value of "size".
522 * utf8 - for drivers that support it, treat the string as UTF8
524 encoded. For versions of perl that support Unicode (5.6 and
525 later), this will be enabled automatically if the "string"
526 parameter is already a UTF8 string. See "UTF8" in Imager::Font
527 for more information.
528 * vlayout - for drivers that support it, draw the text verti‐
530 cally. Note: I haven't found a font that has the appropriate
531 metrics yet.
532 * text - alias for the "string" parameter.
534 On success returns a list of bounds of the drawn text, in the order
536 left, top, right, bottom.
537 On error, align_string() returns an empty list and you can use
539 $img->errstr to get the reason for the error.
540 setscanline
542 Set all or part of a horizontal line of pixels to an image. This
543 method is most useful in conjuction with "getscanline".
544 The parameters you can pass are:
546 * y - vertical position of the scanline. This parameter is
548 required.
549 * x - position to start on the scanline. Default: 0
551 * pixels - either a reference to an array containing
553 Imager::Color objects, an reference to an array containing
554 Imager::Color::Float objects or a scalar containing packed
555 color data.
556 If "type" is "index" then this can either be a reference to an
558 array of palette color indexes or a scalar containing packed
559 indexes.
560 See "Packed Color Data" for information on the format of packed
562 color data.
563 * type - the type of pixel data supplied. If you supply an array
565 reference of object then this is determined automatically. If
566 you supply packed color data this defaults to '8bit', if your
567 data is packed floating point color data then set this to
568 'float'.
569 You can use float or 8bit samples with any image.
571 If this is 'index' then pixels should be either an array of
573 palette color indexes or a packed string of color indexes.
574 Returns the number of pixels set.
576 Each of the following sets 5 pixels from (5, 10) through (9, 10) to
578 blue, red, blue, red, blue:
579 my $red_color = Imager::Color->new(255, 0, 0);
581 my $blue_color = Imager::Color->new(0, 0, 255);
582 $image->setscanline(y=>10, x=>5, pixels=>
584 [ ($blue_color, $red_color) x 2, $blue_color ]);
585 # use floating point color instead, for 16-bit plus images
587 my $red_colorf = Imager::Color::Float->new(1.0, 0, 0);
588 my $blue_colorf = Imager::Color::Float->new(0, 0, 1.0);
589 $image->setscanline(y=>10, x=>5, pixels=>
591 [ ($blue_colorf, $red_colorf) x 2, $blue_colorf ]);
592 # packed 8-bit data
594 $image->setscanline(y=>10, x=>5, pixels=>
595 pack("C*", ((0, 0, 255, 255), (255, 0, 0, 255)) x 2,
596 (0, 0, 255, 255)));
597 # packed floating point samples
599 $image->setscanline(y=>10, x=>5, type=>'float', pixels=>
600 pack("d*", ((0, 0, 1.0, 1.0), (1.0, 0, 0, 1.0)) x 2,
601 (0, 0, 1.0, 1.0)));
602 Copy even rows from one image to another:
604 for (my $y = 0; $y < $im2->getheight; $y+=2) {
606 $im1->setscanline(y=>$y,
607 pixels=>scalar($im2->getscanline(y=>$y)));
608 }
609 Set the blue channel to 0 for all pixels in an image. This could
611 be done with convert too:
612 for my $y (0..$im->getheight-1) {
614 my $row = $im->getscanline(y=>$y);
615 $row =~ s/(..).(.)/$1\0$2/gs;
616 $im->setscanline(y=>$y, pixels=>$row);
617 }
618 getscanline
620 Read all or part of a horizontal line of pixels from an image.
621 This method is most useful in conjunction with "setscanline".
622 The parameters you can pass are:
624 * y - vertical position of the scanline. This parameter is
626 required.
627 * x - position to start on the scanline. Default: 0
629 * width - number of pixels to read. Default: $img->getwidth - x
631 * type - the type of pixel data to return. Default: "8bit".
633 Permited values are "8bit" and "float" and "index".
635 In list context this method will return a list of Imager::Color
637 objects when type is "8bit", or a list of Imager::Color::Float
638 objects when type if "float", or a list of integers when type is
639 "index".
640 In scalar context this returns a packed 8-bit pixels when type is
642 "8bit", or a list of packed floating point pixels when type is
643 "float", or packed palette color indexes when type is "index".
644 The values of samples for which the image does not have channels is
646 undefined. For example, for a single channel image the values of
647 channels 1 through 3 are undefined.
648 Check image for a given color:
650 my $found;
652 YLOOP: for my $y (0..$img->getheight-1) {
653 my @colors = $img->getscanline(y=>$y);
654 for my $color (@colors) {
655 my ($red, $green, $blue, $alpha) = $color->rgba;
656 if ($red == $test_red && $green == $test_green && $blue == $test_blue
657 && $alpha == $test_alpha) {
658 ++$found;
659 last YLOOP;
660 }
661 }
662 }
663 Or do it using packed data:
665 my $found;
667 my $test_packed = pack("CCCC", $test_red, $test_green, $test_blue,
668 $test_alpha);
669 YLOOP: for my $y (0..$img->getheight-1) {
670 my $colors = $img->getscanline(y=>$y);
671 while (length $colors) {
672 if (substr($colors, 0, 4, '') eq $test_packed) {
673 ++$found;
674 last YLOOP;
675 }
676 }
677 }
678 Some of the examples for "setscanline" for more examples.
680 getsamples
682 Read specified channels from all or part of a horizontal line of
683 pixels from an image.
684 The parameters you can pass are:
686 * y - vertical position of the scanline. This parameter is
688 required.
689 * x - position to start on the scanline. Default: 0
691 * width - number of pixels to read. Default: $img->getwidth - x
693 * type - the type of sample data to return. Default: "8bit".
695 Permited values are "8bit" and "float".
697 As of Imager 0.61 this can be "16bit" only for 16 bit images.
699 * channels - a reference to an array of channels to return, where
701 0 is the first channel. Default: " [ 0 .. $self-"getchan‐
702 nels()-1 ] >
703 * target - if an array reference is supplied in target then the
705 samples will be stored here instead of being returned.
706 * offset - the offset within the array referenced by target
708 In list context this will return a list of integers between 0 and
710 255 inclusive when type is "8bit", or a list of floating point num‐
711 bers between 0.0 and 1.0 inclusive when type is "float".
712 In scalar context this will return a string of packed bytes, as
714 with " pack("C*", ...) " when type is "8bit" or a string of packed
715 doubles as with " pack("d*", ...) " when type is "float".
716 If the target option is supplied then only a count of samples is
718 returned.
719 Example: Check if any pixels in an image have a non-zero alpha
721 channel:
722 my $has_coverage;
724 for my $y (0 .. $img->getheight()-1) {
725 my $alpha = $img->getsamples(y=>$y, channels=>[0]);
726 if ($alpha =~ /[^\0]/) {
727 ++$has_coverage;
728 last;
729 }
730 }
731 Example: Convert a 2 channel grey image into a 4 channel RGBA
733 image:
734 # this could be done with convert() instead
736 my $out = Imager->new(xsize => $src->getwidth(),
737 ysize => $src->getheight(),
738 channels => 4);
739 for my $y ( 0 .. $src->getheight()-1 ) {
740 my $data = $src->getsamples(y=>$y, channels=>[ 0, 0, 0, 1 ]);
741 $out->setscanline(y=>$y, pixels=>$data);
742 }
743 Retrieve 16-bit samples:
745 if ($img->bits == 16) {
747 my @samples;
748 $img->getsamples(x => 0, y => $y, target => \@samples, type => '16bit');
749 }
750 setsamples
752 This allows writing of samples back to some images. Currently this
753 is only supported for 16-bit/sample images.
754 Parameters:
756 * y - vertical position of the scanline. This parameter is
758 required.
759 * x - position to start on the scanline. Default: 0
761 * width - number of pixels to write. Default: $img->getwidth -
763 x. The minimum of this and the number of pixels represented by
764 the samples provided will be written.
765 * type - the type of sample data to write. This parameter is
767 required.
768 As of Imager 0.61 this can only be "16bit" only for 16 bit
770 images.
771 * channels - a reference to an array of channels to return, where
773 0 is the first channel. Default: " [ 0 .. $self-"getchan‐
774 nels()-1 ] >
775 * data - a reference to an array of samples to write. Required.
777 * offset - the starting offset within the array referenced by
779 data
780 Returns the number of samples written.
782
784 The getscanline() and setscanline() functions can work with pixels
785 packed into scalars. This is useful to remove the cost of creating
786 color objects, but should only be used when performance is an issue.
787 Packed data can either be 1 byte per sample or 1 double per sample.
789 Each pixel returned by getscanline() or supplied to setscanline() con‐
791 tains 4 samples, even if the image has fewer then 4 channels. The val‐
792 ues of the extra samples as returned by getscanline() is not specified.
793 The extra samples passed to setscanline() are ignored.
794 To produce packed 1 byte/sample pixels, use the pack "C" template:
796 my $packed_8bit_pixel = pack("CCCC", $red, $blue, $green, $alpha);
798 To produce packed double/sample pixels, use the pack "d" template:
800 my $packed_float_pixel = pack("dddd", $red, $blue, $green, $alpha);
802 If you use a type parameter of "index" then the values are palette
804 color indexes, not sample values:
805 my $im = Imager->new(xsize => 100, ysize => 100, type => 'paletted');
807 my $black_index = $im->addcolors(colors => [ 'black' ]);
808 my $red_index = $im->addcolors(colors => [ 'red' ]);
809 # 2 pixels
810 my $packed_index_data = pack("C*", $black_index, $red_index);
811 $im->setscanline(y => $y, pixels => $packed_index_data, type => 'index');
812
814 Some methods accept a "combine" parameter, this can be any of the fol‐
815 lowing:
816 none
818 The fill pixel replaces the target pixel.
819 normal
821 The fill pixels alpha value is used to combine it with the target
822 pixel.
823 multiply
825 mult
826 Each channel of fill and target is multiplied, and the result is
827 combined using the alpha channel of the fill pixel.
828 dissolve
830 If the alpha of the fill pixel is greater than a random number, the
831 fill pixel is alpha combined with the target pixel.
832 add The channels of the fill and target are added together, clamped to
834 the range of the samples and alpha combined with the target.
835 subtract
837 The channels of the fill are subtracted from the target, clamped to
838 be >= 0, and alpha combined with the target.
839 diff
841 The channels of the fill are subtracted from the target and the
842 absolute value taken this is alpha combined with the target.
843 lighten
845 The higher value is taken from each channel of the fill and target
846 pixels, which is then alpha combined with the target.
847 darken
849 The higher value is taken from each channel of the fill and target
850 pixels, which is then alpha combined with the target.
851 hue The combination of the saturation and value of the target is com‐
853 bined with the hue of the fill pixel, and is then alpha combined
854 with the target.
855 sat The combination of the hue and value of the target is combined with
857 the saturation of the fill pixel, and is then alpha combined with
858 the target.
859 value
861 The combination of the hue and value of the target is combined with
862 the value of the fill pixel, and is then alpha combined with the
863 target.
864 color
866 The combination of the value of the target is combined with the hue
867 and saturation of the fill pixel, and is then alpha combined with
868 the target.
869 combines
871 Returns a list of possible combine types.
872
874 box() does not support antialiasing yet. Arc, is only filled as of
875 yet. Default color is not unified yet.
876
878 Tony Cook <tony@imager.perl.org>, Arnar M. Hrafnkelsson.
879
881 Imager(3), Imager::Cookbook(3)
882
884 $Revision: 1465 $
885perl v5.8.8 2008-03-28 Imager::Draw(3)