auto-convert the "other" parameter for opacity fills

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

diff --git a/lib/Imager/Draw.pod b/lib/Imager/Draw.pod
index fca9fc0d22812f28f80ed0c3b09a0e9e2419c46f..60ac552e86de837b618994f8baa4736c260dca80 100644 (file)
--- a/lib/Imager/Draw.pod
+++ b/lib/Imager/Draw.pod
@@ -472,6 +472,12 @@ Default: white.
 
 =back
 
 
 =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);
 =item getpixel
 
   my $color = $img->getpixel(x=>50, y=>70);


@@ -749,6 +755,9 @@ 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.
 
 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.
 
 See L</"Packed Color Data"> for information on the format of packed
 color data.
 


@@ -761,6 +770,9 @@ packed floating point color data then set this to 'float'.
 
 You can use float or 8bit samples with any image.
 
 
 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.
 =back
 
 Returns the number of pixels set.


@@ -811,7 +823,7 @@ done with convert too:
 
 =item getscanline
 
 
 =item getscanline
 

-Read all or part of a horizonatal line of pixels from an image.  This
+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:
 method is most useful in conjunction with L</setscanline>.
 
 The parameters you can pass are:


@@ -834,17 +846,18 @@ width - number of pixels to read.  Default: $img->getwidth - x
 
 type - the type of pixel data to return.  Default: C<8bit>.
 
 
 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
 
 =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
 
 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
 
 The values of samples for which the image does not have channels is
 undefined.  For example, for a single channel image the values of


@@ -909,11 +922,22 @@ type - the type of sample data to return.  Default: C<8bit>.
 
 Permited values are C<8bit> and C<float>.
 
 
 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 *
 
 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
 =back
 
 In list context this will return a list of integers between 0 and 255


@@ -924,6 +948,9 @@ 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>.
 
 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:
 
 Example: Check if any pixels in an image have a non-zero alpha
 channel:
 


@@ -947,6 +974,59 @@ Example: Convert a 2 channel grey image into a 4 channel RGBA image:
     $out->setscanline(y=>$y, pixels=>$data);
   }
 
     $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
 =back
 
 =head1 Packed Color Data


@@ -970,9 +1050,104 @@ To produce packed double/sample pixels, use the pack C<d> template:
 
   my $packed_float_pixel = pack("dddd", $red, $blue, $green, $alpha);
 
 
   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
 
 =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
 yet.  Default color is not unified yet.
 
 =head1 AUTHOR