hatched fills, image based fills and fountain fills. See
L<Imager::Fill> for more information.
+=head2 Polygon Fill Modes
+
+When filling a polygon that overlaps itself, or when filling several
+polygons with polypolygon() that overlap each other, you can supply a
+C<mode> parameter that controls how the overlap is resolved. This can
+have one of two possible values:
+
+=over
+
+=item *
+
+C<evenodd> - if areas overlap an odd number of times, they are filled,
+and are otherwise unfilled. This is the default and the historical
+Imager polygon fill mode.
+
+=item *
+
+C<nonzero> - areas that have an unbalanced clockwise and
+anti-clockwise boundary are filled. This is the same as
+C<WindingRule> for X and C<WINDING> for Win32 GDI.
+
+=back
+
+C<nonzero> allows polygons to overlap, either with itself, or with
+another polygon in the same polypolygon() call, without producing
+unfilled area in the overlap, and also allows areas to be cut out of
+the area by specifying the points making up a cut-out in the opposite
+order.
+
=head2 List of primitives
=over
C<fill> - the fill for the filled circle. See L</"Fill Parameters">
+=item *
+
+C<mode> - fill mode for the polygon. See L</"Polygon Fill Modes">
+
+=back
+
+Note: the points specified are as offsets from the top-left of the
+image, I<not> as pixel locations. This means that:
+
+ $img->polygon(points => [ [ 0, 0 ], [ 1, 0 ], [ 1, 1 ], [ 0, 1 ] ]);
+
+fills only a single pixel at C<(0, 0)>, not four.
+
+=item polypolygon()
+X<polypolygon() method>X<methods, polypolygon>
+
+ $img->polypolygon(points => $points, color => $color);
+
+Draw multiple polygons, either filled or unfilled.
+
+=over
+
+=item *
+
+C<points> - is an array reference containing polygon definitions, each
+polygon definition is a reference to an array containing two arrays,
+one each for the C<x> and C<y> co-ordinates.
+
+=item *
+
+C<filled> - if true, fill the polygons with the color defined by
+C<color>.
+
+=item *
+
+C<color> - the color to draw the polygons with if C<fill> is not
+supplied.
+
+=item *
+
+C<fill> - fill the polygons with this fill if supplied.
+
+=item *
+
+C<mode> - fill mode for the polygon. See L</"Polygon Fill Modes">
+
=back
+Note: the points specified are as offsets from the top-left of the
+image, I<not> as pixel locations. This means that:
+
+ $img->polypolygon(points => [ [ [ 0, 1, 1, 0 ], [ 0, 0, 1, 1 ] ] ],
+ filled => 1);
+
+fills only a single pixel at C<(0, 0)>, not four.
+
=item flood_fill()
X<flood_fill>You can fill a region that all has the same color using
=back
-When called with an array reference in either C<x> or C<y>, returns
-the number of pixels successfully set, or false if none.
+Returns the number of pixels drawn, if no pixels were drawn, but none
+of the errors below occur, returns C<"0 but true">.
-When called with scalars for x and y, return $img on success, false on
-failure.
+For other errors, setpixel() returns an empty list and sets errstr().
Possible errors conditions include:
=back
-On any of these errors, setpixel() returns an empty list and sets
-errstr().
-
=item getpixel()
my $color = $img->getpixel(x=>50, y=>70); my @colors =
=item *
-x, y - either integers giving the co-ordinates of the pixel to set or
+C<x>, C<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'>.
+C<type> - the type of color object to return, either C<'8bit'> for
+L<Imager::Color> objects or C<'float'> for L<Imager::Color::Float>
+objects. Default: C<'8bit'>.
=back
If a supplied co-ordinate is outside the image then C<undef> is
returned for the pixel.
+Each color is returned as an L<Imager::Color> object or as an
+L<Imager::Color::Float> object if C<type> is set to C<"float">.
+
Possible errors conditions include:
=over
=item *
C<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 C<'8bit'>, if your data is
-packed floating point color data then set this to C<'float'>.
+reference then this is determined automatically. If you supply packed
+color data this defaults to C<'8bit'>, if your data is packed floating
+point color data then you need to set this to C<'float'>.
You can use C<float> or C<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.
+If this is C<index> then C<pixels> should be either an array of
+palette color indexes or a packed string of color indexes.
=back
=item setsamples()
-This allows writing of samples back to some images. Currently this is
-only supported for 16-bit/sample images.
+This allows writing of samples to an image.
Parameters:
my $packed_float_pixel = pack("dddd", $red, $blue, $green, $alpha);
+Note that double/sample data is always stored using the C C<double>
+type, never C<long double>, even if C<perl> is built with
+C<-Duselongdouble>.
+
If you use a I<type> parameter of C<index> then the values are palette
color indexes, not sample values:
projects / imager.git / blobdiff