diff options
Diffstat (limited to 'Master/tlpkg/tlperl0/lib/Imager/Draw.pod')
-rwxr-xr-x | Master/tlpkg/tlperl0/lib/Imager/Draw.pod | 1165 |
1 files changed, 1165 insertions, 0 deletions
diff --git a/Master/tlpkg/tlperl0/lib/Imager/Draw.pod b/Master/tlpkg/tlperl0/lib/Imager/Draw.pod new file mode 100755 index 00000000000..c907627f6e1 --- /dev/null +++ b/Master/tlpkg/tlperl0/lib/Imager/Draw.pod @@ -0,0 +1,1165 @@ +=head1 NAME + +Imager::Draw - Draw primitives to images + +=head1 SYNOPSIS + + use Imager; + use Imager::Fill; + + $img = ...; + $blue = Imager::Color->new( 0, 0, 255 ); + $fill = Imager::Fill->new(hatch=>'stipple'); + + $img->line(color=>$blue, x1=>10, x2=>100, + y1=>20, y2=>50, aa=>1, endp=>1 ); + + $img->polyline(points=>[[$x0,$y0], [$x1,$y1], [$x2,$y2]], + color=>$blue); + $img->polyline(x=>[$x0,$x1,$x2], y=>[$y0,$y1,$y2], aa=>1); + + $img->box(color=> $blue, xmin=> 10, ymin=>30, + xmax=>200, ymax=>300, filled=>1); + $img->box(fill=>$fill); + + $img->arc(color=>$blue, r=>20, x=>200, y=>100, + d1=>10, d2=>20 ); + + $img->circle(color=>$blue, r=>50, x=>200, y=>100); + + $img->polygon(points=>[[$x0,$y0], [$x1,$y1], [$x2,$y2]], + color=>$blue); + + $img->polygon(x=>[$x0,$x1,$x2], y=>[$y0,$y1,$y2]); + + $img->flood_fill(x=>50, y=>50, color=>$color); + + $img->setpixel(x=>50, y=>70, color=>$color); + + $img->setpixel(x=>[ 50, 60, 70 ], y=>[20, 30, 40], color=>$color); + + my $color = $img->getpixel(x=>50, y=>70); + + my @colors = $img->getpixel(x=>[ 50, 60, 70 ], y=>[20, 30, 40]); + + # drawing text + my $font = Imager::Font->new(...) or die; + $img->string(x => 50, y => 70, + font => $font, + string => "Hello, World!", + color => 'red', + size => 30, + aa => 1); + + # bottom right-hand corner of the image + $img->align_string(x => $img->getwidth() - 1, + y => $img->getheight() - 1, + halign => 'right', + valign => 'bottom', + string => 'Imager', + font => $font, + size => 12); + + # low-level functions + my @colors = $img->getscanline(y=>50, x=>10, width=>20); + + $img->setscanline(y=>60, x=>20, pixels=>\@colors); + + my @samples = $img->getsamples(y=>50, x=>10, width=>20, + channels=>[ 2, 0 ]); + +=head1 DESCRIPTION + +It is possible to draw with graphics primitives onto images. Such +primitives include boxes, arcs, circles, polygons and lines. The +coordinate system in Imager has the origin C<(0,0)> in the upper left +corner of an image with co-ordinates increasing to the right and +bottom. For non antialiasing operation all coordinates are rounded +towards the nearest integer. For antialiased operations floating +point coordinates are used. + +Drawing is assumed to take place in a coordinate system of infinite +resolution. This is the typical convention and really only matters when +it is necessary to check for off-by-one cases. Typically it's usefull to +think of C<(10, 20)> as C<(10.00, 20.00)> and consider the consiquences. + +=head2 Color Parameters + +X<color parameters>The C<color> parameter for any of the drawing +methods can be an L<Imager::Color> object, a simple scalar that +Imager::Color can understand, a hashref of parameters that +Imager::Color->new understands, or an arrayref of red, green, blue +values, for example: + + $image->box(..., color=>'red'); + $image->line(..., color=>'#FF0000'); + $image->flood_fill(..., color=>[ 255, 0, 255 ]); + +=head2 Fill Parameters + +X<fill parameters>All filled primitives, i.e. C<arc()>, C<box()>, +C<circle()>, C<polygon()> and the C<flood_fill()> method can take a +C<fill> parameter instead of a C<color> parameter which can either be +an Imager::Fill object, or a reference to a hash containing the +parameters used to create the fill, for example: + + $image->box(..., fill=>{ hatch => 'check1x1' }); + my $fillimage = Imager->new; + $fillimage->read(file=>$somefile) or die; + $image->flood_fill(..., fill=>{ image=>$fillimage }); + +Currently you can create opaque or transparent plain color fills, +hatched fills, image based fills and fountain fills. See +L<Imager::Fill> for more information. + +=head2 List of primitives + +=over + +=item line + + $img->line(color=>$green, x1=>10, x2=>100, + y1=>20, y2=>50, aa=>1, endp=>1 ); + +X<line method>Draws a line from (x1,y1) to (x2,y2). The endpoint +(x2,y2) is drawn by default. If endp of 0 is specified then the +endpoint will not be drawn. If C<aa> is set then the line will be +drawn antialiased. The I<antialias> parameter is still available for +backwards compatibility. + +Parameters: + +=over + +=item * + +x1, y1 - starting point of the line. Required. + +=item * + +x2, y2 - end point of the line. Required. + +=item * + +color - the color of the line. See L<"Color Parameters">. Default: +black. + +=item * + +endp - if zero the end point of the line is not drawn. Default: 1 - +the end point is drawn. This is useful to set to 0 when drawning a +series of connected lines. + +=item * + +aa - if true the line is drawn anti-aliased. Default: 0. + +=back + +=item polyline + + $img->polyline(points=>[[$x0,$y0],[$x1,$y1],[$x2,$y2]],color=>$red); + $img->polyline(x=>[$x0,$x1,$x2], y=>[$y0,$y1,$y2], aa=>1); + +X<polyline method>Polyline is used to draw multilple lines between a +series of points. The point set can either be specified as an +arrayref to an array of array references (where each such array +represents a point). The other way is to specify two array +references. + +The I<antialias> parameter is still available for backwards compatibility. + +=over + +=item * + +points - a reference to an array of references to arrays containing +the co-ordinates of the points in the line, for example: + + my @points = ( [ 0, 0 ], [ 100, 0 ], [ 100, 100 ], [ 0, 100 ] ); + $img->polyline(points => \@points); + +=item * + +x, y - each is an array of x or y ordinates. This is an alternative +to supplying the C<points> parameter. + + # same as the above points example + my @x = ( 0, 100, 100, 0 ); + my @y = ( 0, 0, 100, 100 ); + $img->polyline(x => \@x, y => \@y); + +=item * + +color - the color of the line. See L<"Color Parameters">. Default: +black. + +=item * + +aa - if true the line is drawn anti-aliased. Default: 0. Can also be +supplied as C<antialias> for backward compatibility. + +=back + +=item box + + $blue = Imager::Color->new( 0, 0, 255 ); + $img->box(color => $blue, xmin=>10, ymin=>30, xmax=>200, ymax=>300, + filled=>1); + +X<box method>If any of the edges of the box are ommited it will snap +to the outer edge of the image in that direction. If C<filled> is +ommited the box is drawn as an outline. Instead of a color it is +possible to use a C<fill> pattern: + + $fill = Imager::Fill->new(hatch=>'stipple'); + $img->box(fill=>$fill); # fill entire image with a given fill pattern + + $img->box(xmin=>10, ymin=>30, xmax=>150, ymax=>60, + fill => { hatch=>'cross2' }); + +Also if a color is omitted a color with (255,255,255,255) is used +instead. [NOTE: This may change to use C<$img-E<gt>fgcolor()> in the future]. + +Box does not support fractional coordinates yet. + +Parameters: + +=over + +=item * + +xmin - left side of the box. Default: 0 (left edge of the image) + +=item * + +ymin - top side of the box. Default: 0 (top edge of the image) + +=item * + +xmax - right side of the box. Default: $img->getwidth-1. (right edge +of the image) + +=item * + +ymax - bottom side of the box. Default: $img->getheight-1. (bottom +edge of the image) + +Note: xmax and ymax are I<inclusive> - the number of pixels drawn for +a filled box is (xmax-xmin+1) * (ymax-ymin+1). + +=item * + +box - a reference to an array of (left, top, right, bottom) +co-ordinates. This is an alternative to supplying xmin, ymin, xmax, +ymax and overrides their values. + +=item * + +color - the color of the line. See L<"Color Parameters">. Default: +white. This is ignored if the filled parameter + +=item * + +filled - if non-zero the box is filled with I<color> instead of +outlined. Default: an outline is drawn. + +=item * + +fill - the fill for the box. If this is supplied then the box will be +filled. See L<"Fill Parameters">. + +=back + +=item arc + + $img->arc(color=>$red, r=>20, x=>200, y=>100, d1=>10, d2=>20 ); + +This creates a filled red arc with a 'center' at (200, 100) and spans +10 degrees and the slice has a radius of 20. [NOTE: arc has a BUG in +it right now for large differences in angles.] +It's also possible to supply a C<fill> parameter. + +Parameters: + +=over + +=item * + +x, y - center of the filled arc. Default: center of the image. + +=item * + +r - radius of the arc. Default: 1/3 of min(image height, image width). + +=item * + +d1 - starting angle of the arc, in degrees. Default: 0 + +=item * + +d2 - ending angle of the arc, in degrees. Default: 361. + +=item * + +color - the color of the filled arc. See L<"Color Parameters">. +Default: white. Overridden by C<fill>. + +=item * + +fill - the fill for the filled arc. See L<"Fill Parameters"> + +=item * + +aa - if true the filled arc is drawn anti-aliased. Default: false. + +Anti-aliased arc() is experimental for now, I'm not entirely happy +with the results in some cases. + +=back + + # arc going through angle zero: + $img->arc(d1=>320, d2=>40, x=>100, y=>100, r=>50, color=>'blue'); + + # complex fill arc + $img->arc(d1=>135, d2=>45, x=>100, y=>150, r=>50, + fill=>{ solid=>'red', combine=>'diff' }); + +=item circle + + $img->circle(color=>$green, r=>50, x=>200, y=>100, aa=>1, filled=>1); + +This creates an antialiased green circle with its center at (200, 100) +and has a radius of 50. It's also possible to supply a C<fill> parameter +instead of a color parameter. + + $img->circle(r => 50, x=> 150, y => 150, fill=>{ hatch => 'stipple' }); + +The circle is always filled but that might change, so always pass a +filled=>1 parameter if you want it to be filled. + +=over + +=item * + +x, y - center of the filled circle. Default: center of the image. + +=item * + +r - radius of the circle. Default: 1/3 of min(image height, image width). + +=item * + +color - the color of the filled circle. See L<"Color Parameters">. +Default: white. Overridden by C<fill>. + +=item * + +fill - the fill for the filled circle. See L<"Fill Parameters"> + +=item * + +aa - if true the filled circle is drawn anti-aliased. Default: false. + +=back + +=item polygon + + $img->polygon(points=>[[$x0,$y0],[$x1,$y1],[$x2,$y2]],color=>$red); + $img->polygon(x=>[$x0,$x1,$x2], y=>[$y0,$y1,$y2], fill=>$fill); + +Polygon is used to draw a filled polygon. Currently the polygon is +always drawn antialiased, although that will change in the future. +Like other antialiased drawing functions its coordinates can be +specified with floating point values. As with other filled shapes +it's possible to use a C<fill> instead of a color. + +=over + +=item * + +points - a reference to an array of references to arrays containing +the co-ordinates of the points in the line, for example: + + my @points = ( [ 0, 0 ], [ 100, 0 ], [ 100, 100 ], [ 0, 100 ] ); + $img->polygon(points => \@points); + +=item * + +x, y - each is an array of x or y ordinates. This is an alternative +to supplying the C<points> parameter. + + # same as the above points example + my @x = ( 0, 100, 100, 0 ); + my @y = ( 0, 0, 100, 100 ); + $img->polygon(x => \@x, y => \@y); + +=item * + +color - the color of the filled polygon. See L<"Color Parameters">. +Default: black. Overridden by C<fill>. + +=item * + +fill - the fill for the filled circle. See L<"Fill Parameters"> + +=back + +=item flood_fill + +X<flood_fill>You can fill a region that all has the same color using +the flood_fill() method, for example: + + $img->flood_fill(x=>50, y=>50, color=>$color); + +will fill all regions the same color connected to the point (50, 50). + +Alternatively you can fill a region limited by a given border color: + + # stop at the red border + $im->flood_fill(x=>50, y=>50, color=>$color, border=>"red"); + +You can also fill with a complex fill: + + $img->flood_fill(x=>50, y=>50, fill=>{ hatch=>'cross1x1' }); + +Parameters: + +=over + +=item * + +x, y - the start point of the fill. + +=item * + +color - the color of the filled area. See L<"Color Parameters">. +Default: white. Overridden by C<fill>. + +=item * + +fill - the fill for the filled area. See L<"Fill Parameters"> + +=item * + +border - the border color of the region to be filled. If this +parameter is supplied flood_fill() will stop when it finds this color. +If this is not supplied then a normal fill is done. C<border> can be +supplied as a L<"Color Parameter">. + +=back + +=item setpixel + + $img->setpixel(x=>50, y=>70, color=>$color); + $img->setpixel(x=>[ 50, 60, 70 ], y=>[20, 30, 40], color=>$color); + +setpixel() is used to set one or more individual pixels. + +Parameters: + +=over + +=item * + +x, y - either integers giving the co-ordinates of the pixel to set or +array references containing a set of pixels to be set. + +=item * + +color - the color of the pixels drawn. See L<"Color Parameters">. +Default: white. + +=back + +When called with array parameters, returns the number of pixels +successfully set, or false if none. + +When called with scalars for x and y, return $img on success, false on +failure. + +=item getpixel + + my $color = $img->getpixel(x=>50, y=>70); + my @colors = $img->getpixel(x=>[ 50, 60, 70 ], y=>[20, 30, 40]); + my $colors_ref = $img->getpixel(x=>[ 50, 60, 70 ], y=>[20, 30, 40]); + +getpixel() is used to retrieve one or more individual pixels. + +For either method you can supply a single set of co-ordinates as +scalar x and y parameters, or set each to an arrayref of ordinates. + +When called with arrays, getpixel() will return a list of colors in +list context, and an arrayref in scalar context. + +To receive floating point colors from getpixel, set the C<type> +parameter to 'float'. + +Parameters: + +=over + +=item * + +x, y - either integers giving the co-ordinates of the pixel to set or +array references containing a set of pixels to be set. + +=item * + +type - the type of color object to return, either C<'8bit'> for +Imager::Color objects or C<'float'> for Imager::Color::Float objects. +Default: C<'8bit'>. + +=back + +=item string + + my $font = Imager::Font->new(file=>"foo.ttf"); + $img->string(x => 50, y => 70, + string => "Hello, World!", + font => $font, + size => 30, + aa => 1, + color => 'white'); + +Draws text on the image. + +Parameters: + +=over + +=item * + +x, y - the point to draw the text from. If C<align> is 0 this is the +top left of the string. If C<align> is 1 (the default) then this is +the left of the string on the baseline. Required. + +=item * + +string - the text to draw. Required unless you supply the C<text> +parameter. + +=item * + +font - an L<Imager::Font> object representing the font to draw the +text with. Required. + +=item * + +aa - if non-zero the output will be anti-aliased. Default: the value +set in Imager::Font->new() or 0 if not set. + +=item * + +align - if non-zero the point supplied in (x,y) will be on the +base-line, if zero then (x,y) will be at the top-left of the string. + +ie. if drawing the string "yA" and align is 0 the point (x,y) will +aligned with the top of the A. If align is 1 (the default) it will be +aligned with the baseline of the font, typically bottom of the A, +depending on the font used. + +Default: the value set in Imager::Font->new, or 1 if not set. + +=item * + +channel - if present, the text will be written to the specified +channel of the image and the color parameter will be ignore. + +=item * + +color - the color to draw the text in. Default: the color supplied to +Imager::Font->new, or red if none. + +=item * + +size - the point size to draw the text at. Default: the size supplied +to Imager::Font->new, or 15. + +=item * + +sizew - the width scaling to draw the text at. Default: the value of +C<size>. + +=item * + +utf8 - for drivers that support it, treat the string as UTF8 encoded. +For versions of perl that support Unicode (5.6 and later), this will +be enabled automatically if the C<string> parameter is already a UTF8 +string. See L<Imager::Font/"UTF8"> for more information. + +=item * + +vlayout - for drivers that support it, draw the text vertically. +Note: I haven't found a font that has the appropriate metrics yet. + +=item * + +text - alias for the C<string> parameter. + +=back + +On error, string() returns false and you can use $img->errstr to get +the reason for the error. + +=item align_string + +Draws text aligned around a point on the image. + + # "Hello" centered at 100, 100 in the image. + my ($left, $top, $right, $bottom) = + $img->align_string(string=>"Hello", + x=>100, y=>100, + halign=>'center', valign=>'center', + font=>$font); + +Parameters: + +=over + +=item * + +x, y - the point to draw the text from. If C<align> is 0 this is the +top left of the string. If C<align> is 1 (the default) then this is +the left of the string on the baseline. Required. + +=item * + +string - the text to draw. Required unless you supply the C<text> parameter. + +=item * + +font - an L<Imager::Font> object representing the font to draw the +text with. Required. + +=item * + +aa - if non-zero the output will be anti-aliased + +=item * + +valign - vertical alignment of the text against (x,y) + +=over + +=item * + +top - Point is at the top of the text. + +=item * + +bottom - Point is at the bottom of the text. + +=item * + +baseline - Point is on the baseline of the text. This is the default. + +=item * + +center - Point is vertically centered within the text. + +=back + +=item * + +halign - horizontal alignment of the text against (x,y) + +=over + +=item * + +left - The point is at the left of the text. This is the default. + +=item * + +start - The point is at the start point of the text. + +=item * + +center - The point is horizontally centered within the text. + +=item * + +right - The point is at the right end of the text. + +=item * + +end - The point is at the end point of the text. + +=back + +=item * + +channel - if present, the text will be written to the specified +channel of the image and the color parameter will be ignore. + +=item * + +color - the color to draw the text in. Default: the color supplied to +Imager::Font->new, or red if none. + +=item * + +size - the point size to draw the text at. Default: the size supplied +to Imager::Font->new, or 15. + +=item * + +sizew - the width scaling to draw the text at. Default: the value of +C<size>. + +=item * + +utf8 - for drivers that support it, treat the string as UTF8 encoded. +For versions of perl that support Unicode (5.6 and later), this will +be enabled automatically if the C<string> parameter is already a UTF8 +string. See L<Imager::Font/"UTF8"> for more information. + +=item * + +vlayout - for drivers that support it, draw the text vertically. +Note: I haven't found a font that has the appropriate metrics yet. + +=item * + +text - alias for the C<string> parameter. + +=back + +On success returns a list of bounds of the drawn text, in the order +left, top, right, bottom. + +On error, align_string() returns an empty list and you can use +$img->errstr to get the reason for the error. + +=item setscanline + +Set all or part of a horizontal line of pixels to an image. This +method is most useful in conjuction with L</getscanline>. + +The parameters you can pass are: + +=over + +=item * + +y - vertical position of the scanline. This parameter is required. + +=item * + +x - position to start on the scanline. Default: 0 + +=item * + +pixels - either a reference to an array containing Imager::Color +objects, an reference to an array containing Imager::Color::Float +objects or a scalar containing packed color data. + +If C<type> is C<index> then this can either be a reference to an array +of palette color indexes or a scalar containing packed indexes. + +See L</"Packed Color Data"> for information on the format of packed +color data. + +=item * + +type - the type of pixel data supplied. If you supply an array +reference of object then this is determined automatically. If you +supply packed color data this defaults to '8bit', if your data is +packed floating point color data then set this to 'float'. + +You can use float or 8bit samples with any image. + +If this is 'index' then pixels should be either an array of palette +color indexes or a packed string of color indexes. + +=back + +Returns the number of pixels set. + +Each of the following sets 5 pixels from (5, 10) through (9, 10) to +blue, red, blue, red, blue: + + my $red_color = Imager::Color->new(255, 0, 0); + my $blue_color = Imager::Color->new(0, 0, 255); + + $image->setscanline(y=>10, x=>5, pixels=> + [ ($blue_color, $red_color) x 2, $blue_color ]); + + # use floating point color instead, for 16-bit plus images + my $red_colorf = Imager::Color::Float->new(1.0, 0, 0); + my $blue_colorf = Imager::Color::Float->new(0, 0, 1.0); + + $image->setscanline(y=>10, x=>5, pixels=> + [ ($blue_colorf, $red_colorf) x 2, $blue_colorf ]); + + # packed 8-bit data + $image->setscanline(y=>10, x=>5, pixels=> + pack("C*", ((0, 0, 255, 255), (255, 0, 0, 255)) x 2, + (0, 0, 255, 255))); + + # packed floating point samples + $image->setscanline(y=>10, x=>5, type=>'float', pixels=> + pack("d*", ((0, 0, 1.0, 1.0), (1.0, 0, 0, 1.0)) x 2, + (0, 0, 1.0, 1.0))); + + +Copy even rows from one image to another: + + for (my $y = 0; $y < $im2->getheight; $y+=2) { + $im1->setscanline(y=>$y, + pixels=>scalar($im2->getscanline(y=>$y))); + } + + +Set the blue channel to 0 for all pixels in an image. This could be +done with convert too: + + for my $y (0..$im->getheight-1) { + my $row = $im->getscanline(y=>$y); + $row =~ s/(..).(.)/$1\0$2/gs; + $im->setscanline(y=>$y, pixels=>$row); + } + +=item getscanline + +Read all or part of a horizontal line of pixels from an image. This +method is most useful in conjunction with L</setscanline>. + +The parameters you can pass are: + +=over + +=item * + +y - vertical position of the scanline. This parameter is required. + +=item * + +x - position to start on the scanline. Default: 0 + +=item * + +width - number of pixels to read. Default: $img->getwidth - x + +=item * + +type - the type of pixel data to return. Default: C<8bit>. + +Permited values are C<8bit> and C<float> and C<index>. + +=back + +In list context this method will return a list of Imager::Color +objects when I<type> is C<8bit>, or a list of Imager::Color::Float +objects when I<type> if C<float>, or a list of integers when I<type> +is C<index>. + +In scalar context this returns a packed 8-bit pixels when I<type> is +C<8bit>, or a list of packed floating point pixels when I<type> is +C<float>, or packed palette color indexes when I<type> is C<index>. + +The values of samples for which the image does not have channels is +undefined. For example, for a single channel image the values of +channels 1 through 3 are undefined. + +Check image for a given color: + + my $found; + YLOOP: for my $y (0..$img->getheight-1) { + my @colors = $img->getscanline(y=>$y); + for my $color (@colors) { + my ($red, $green, $blue, $alpha) = $color->rgba; + if ($red == $test_red && $green == $test_green && $blue == $test_blue + && $alpha == $test_alpha) { + ++$found; + last YLOOP; + } + } + } + +Or do it using packed data: + + my $found; + my $test_packed = pack("CCCC", $test_red, $test_green, $test_blue, + $test_alpha); + YLOOP: for my $y (0..$img->getheight-1) { + my $colors = $img->getscanline(y=>$y); + while (length $colors) { + if (substr($colors, 0, 4, '') eq $test_packed) { + ++$found; + last YLOOP; + } + } + } + +Some of the examples for L</setscanline> for more examples. + +=item getsamples + +Read specified channels from all or part of a horizontal line of +pixels from an image. + +The parameters you can pass are: + +=over + +=item * + +y - vertical position of the scanline. This parameter is required. + +=item * + +x - position to start on the scanline. Default: 0 + +=item * + +width - number of pixels to read. Default: $img->getwidth - x + +=item * + +type - the type of sample data to return. Default: C<8bit>. + +Permited values are C<8bit> and C<float>. + +As of Imager 0.61 this can be C<16bit> only for 16 bit images. + +=item * + +channels - a reference to an array of channels to return, where 0 is +the first channel. Default: C<< [ 0 .. $self->getchannels()-1 ] >> + +=item * + +target - if an array reference is supplied in target then the samples +will be stored here instead of being returned. + +=item * + +offset - the offset within the array referenced by I<target> + +=back + +In list context this will return a list of integers between 0 and 255 +inclusive when I<type> is C<8bit>, or a list of floating point numbers +between 0.0 and 1.0 inclusive when I<type> is C<float>. + +In scalar context this will return a string of packed bytes, as with +C< pack("C*", ...) > when I<type> is C<8bit> or a string of packed +doubles as with C< pack("d*", ...) > when I<type> is C<float>. + +If the I<target> option is supplied then only a count of samples is +returned. + +Example: Check if any pixels in an image have a non-zero alpha +channel: + + my $has_coverage; + for my $y (0 .. $img->getheight()-1) { + my $alpha = $img->getsamples(y=>$y, channels=>[0]); + if ($alpha =~ /[^\0]/) { + ++$has_coverage; + last; + } + } + +Example: Convert a 2 channel grey image into a 4 channel RGBA image: + + # this could be done with convert() instead + my $out = Imager->new(xsize => $src->getwidth(), + ysize => $src->getheight(), + channels => 4); + for my $y ( 0 .. $src->getheight()-1 ) { + my $data = $src->getsamples(y=>$y, channels=>[ 0, 0, 0, 1 ]); + $out->setscanline(y=>$y, pixels=>$data); + } + +Retrieve 16-bit samples: + + if ($img->bits == 16) { + my @samples; + $img->getsamples(x => 0, y => $y, target => \@samples, type => '16bit'); + } + +=item setsamples + +This allows writing of samples back to some images. Currently this is +only supported for 16-bit/sample images. + +Parameters: + +=over + +=item * + +y - vertical position of the scanline. This parameter is required. + +=item * + +x - position to start on the scanline. Default: 0 + +=item * + +width - number of pixels to write. Default: $img->getwidth - x. The +minimum of this and the number of pixels represented by the samples +provided will be written. + +=item * + +type - the type of sample data to write. This parameter is required. + +As of Imager 0.61 this can only be C<16bit> only for 16 bit images. + +=item * + +channels - a reference to an array of channels to return, where 0 is +the first channel. Default: C<< [ 0 .. $self->getchannels()-1 ] >> + +=item * + +data - a reference to an array of samples to write. Required. + +=item * + +offset - the starting offset within the array referenced by I<data> + +=back + +Returns the number of samples written. + +=back + +=head1 Packed Color Data + +The getscanline() and setscanline() functions can work with pixels +packed into scalars. This is useful to remove the cost of creating +color objects, but should only be used when performance is an issue. + +Packed data can either be 1 byte per sample or 1 double per sample. + +Each pixel returned by getscanline() or supplied to setscanline() +contains 4 samples, even if the image has fewer then 4 channels. The +values of the extra samples as returned by getscanline() is not +specified. The extra samples passed to setscanline() are ignored. + +To produce packed 1 byte/sample pixels, use the pack C<C> template: + + my $packed_8bit_pixel = pack("CCCC", $red, $blue, $green, $alpha); + +To produce packed double/sample pixels, use the pack C<d> template: + + my $packed_float_pixel = pack("dddd", $red, $blue, $green, $alpha); + +If you use a I<type> parameter of C<index> then the values are palette +color indexes, not sample values: + + my $im = Imager->new(xsize => 100, ysize => 100, type => 'paletted'); + my $black_index = $im->addcolors(colors => [ 'black' ]); + my $red_index = $im->addcolors(colors => [ 'red' ]); + # 2 pixels + my $packed_index_data = pack("C*", $black_index, $red_index); + $im->setscanline(y => $y, pixels => $packed_index_data, type => 'index'); + +=head1 Combine Types + +Some methods accept a C<combine> parameter, this can be any of the +following: + +=over + +=item none + +The fill pixel replaces the target pixel. + +=item normal + +The fill pixels alpha value is used to combine it with the target pixel. + +=item multiply + +=item mult + +Each channel of fill and target is multiplied, and the result is +combined using the alpha channel of the fill pixel. + +=item dissolve + +If the alpha of the fill pixel is greater than a random number, the +fill pixel is alpha combined with the target pixel. + +=item add + +The channels of the fill and target are added together, clamped to the range of the samples and alpha combined with the target. + +=item subtract + +The channels of the fill are subtracted from the target, clamped to be +>= 0, and alpha combined with the target. + +=item diff + +The channels of the fill are subtracted from the target and the +absolute value taken this is alpha combined with the target. + +=item lighten + +The higher value is taken from each channel of the fill and target +pixels, which is then alpha combined with the target. + +=item darken + +The higher value is taken from each channel of the fill and target +pixels, which is then alpha combined with the target. + +=item hue + +The combination of the saturation and value of the target is combined +with the hue of the fill pixel, and is then alpha combined with the +target. + +=item sat + +The combination of the hue and value of the target is combined +with the saturation of the fill pixel, and is then alpha combined with the +target. + +=item value + +The combination of the hue and value of the target is combined +with the value of the fill pixel, and is then alpha combined with the +target. + +=item color + +The combination of the value of the target is combined with the hue +and saturation of the fill pixel, and is then alpha combined with the +target. + +=back + +=over + +=item combines + +Returns a list of possible combine types. + +=back + +=head1 BUGS + +box() does not support antialiasing yet. Arc, is only filled as of +yet. Default color is not unified yet. + +=head1 AUTHOR + +Tony Cook <tony@imager.perl.org>, Arnar M. Hrafnkelsson. + +=head1 SEE ALSO + +L<Imager>(3), L<Imager::Cookbook>(3) + +=head1 REVISION + +$Revision: 1667 $ + +=cut |