sacrifice a chicken to the spell-checker gods

[imager.git] / lib / Imager / Draw.pod

diff --git a/lib/Imager/Draw.pod b/lib/Imager/Draw.pod
index 4bf6773424e82571fc5e24403715878a2389d0e4..057a129c59acddbec2491e43ba7681deea3c15ee 100644 (file)
--- a/lib/Imager/Draw.pod
+++ b/lib/Imager/Draw.pod
@@ -527,11 +527,10 @@ Default: white.
 
 =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:
 
@@ -548,9 +547,6 @@ 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 =
@@ -591,14 +587,14 @@ Parameters:
 
 =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
 
@@ -609,6 +605,9 @@ 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
@@ -880,14 +879,14 @@ color data.
 =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
 
@@ -1099,8 +1098,7 @@ Retrieve 16-bit samples:
 
 =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:
 
@@ -1205,6 +1203,10 @@ To produce packed double/sample pixels, use the pack C<d> template:
 
   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: