setpixel() is used to set one or more individual pixels.
+You can supply a single set of co-ordinates as scalar C<x> and C<y>
+parameters, or set either to an arrayref of ordinates.
+
+If one array is shorter than another the final value in the shorter
+will be duplicated until they match in length.
+
+If only one of C<x> or C<y> is an array reference then setpixel() will
+behave as if the non-reference value were an array reference
+containing only that value.
+
+eg.
+
+ my $count = $img->setpixel(x => 1, y => [ 0 .. 3 ], color => $color);
+
+behaves like:
+
+ my $count = $img->setpixel(x => [ 1 ], y => [ 0 .. 3 ], color => $color);
+
+and since the final element in the shorter array is duplicated, this
+behaves like:
+
+ my $count = $img->setpixel(x => [ 1, 1, 1, 1 ], y => [ 0 .. 3 ],
+ color => $color);
+
Parameters:
=over
=back
-When called with array parameters, returns the number of pixels
-successfully set, or false if none.
+When called with an array reference in either C<x> or C<y>, 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.
+Possible errors conditions include:
+
+=over
+
+=item * the image supplied is empty
+
+=item * a reference to an empty array was supplied for C<x> or C<y>
+
+=item * C<x> or C<y> wasn't supplied
+
+=item * C<color> isn't a valid color, and can't be converted to a
+color.
+
+=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 = $img->getpixel(x=>[ 50, 60, 70 ], y=>[20, 30, 40]);
- my $colors_ref = $img->getpixel(x=>[ 50, 60, 70 ], y=>[20, 30, 40]);
+ 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.
+You can supply a single set of co-ordinates as scalar C<x> and C<y>
+parameters, or set each to an arrayref of ordinates.
+
+If one array is shorter than another the final value in the shorter
+will be duplicated until they match in length.
-When called with arrays, getpixel() will return a list of colors in
-list context, and an arrayref in scalar context.
+If only one of C<x> or C<y> is an array reference then getpixel() will
+behave as if the non-reference value were an array reference
+containing only that value.
+
+eg.
+
+ my @colors = $img->getpixel(x => 0, y => [ 0 .. 3 ]);
+
+behaves like:
+
+ my @colors = $img->getpixel(x => [ 0 ], y => [ 0 .. 3 ]);
+
+and since the final element in the shorter array is duplicated, this
+behaves like:
+
+ my @colors = $img->getpixel(x => [ 0, 0, 0, 0 ], y => [ 0 .. 3 ]);
To receive floating point colors from getpixel(), set the C<type>
parameter to 'float'.
=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
+When called with an array reference for either or C<x> or C<y>,
+getpixel() will return a list of colors in list context, and an
+arrayref in scalar context.
+
+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 * the image supplied is empty
+
+=item * a reference to an empty array was supplied for C<x> or C<y>
+
+=item * C<x> or C<y> wasn't supplied
+
+=item * C<type> isn't a valid value.
+
+=back
+
+For any of these errors getpixel() returns an empty list.
+
=item string()
my $font = Imager::Font->new(file=>"foo.ttf");
=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