=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);
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.
=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:
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
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 *
+
+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
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:
$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
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
-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
projects / imager.git / blobdiff