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. For non antialiasing operation all coordinates are
-rounded towards the nearest integer. For antialiased operations floating
+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
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.
-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:
+=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 ]);
-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
+=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' });
$img->line(color=>$green, x1=>10, x2=>100,
y1=>20, y2=>50, aa=>1, endp=>1 );
-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.
+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);
-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.
+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);
-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:
+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
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 );
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);
+ $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
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
-You can fill a region that all has the same color using the
-flood_fill() method, for example:
+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' });
-=item setpixel and getpixel
+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]);
-setpixel() is used to set one or more individual pixels, and
-getpixel() to retrieve the same.
+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.
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, arc, do not support antialiasing yet. Arc, is only filled as of
+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
-Imager(3), Imager::Cookbook(3)
+L<Imager>(3), L<Imager::Cookbook>(3)
-=back
+=head1 REVISION
+
+$Revision$
+
+=cut
projects / imager.git / blobdiff