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);
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
+
+=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
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.
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.
type - the type of pixel data to return. Default: C<8bit>.
-Permited values are C<8bit> and C<float>.
+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>.
+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>.
+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
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 BUGS
box, arc, do 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)
+
+=head1 REVISION
+
+$Revision$
=cut
projects / imager.git / blobdiff