From: Tony Cook <tony@develop-help.com>
Date: Thu, 16 Feb 2012 07:41:26 +0000 (+1100)
Subject: document setsamples() new capabilities
X-Git-Tag: v0.88~3^2~1
X-Git-Url: http://git.imager.perl.org/imager.git/commitdiff_plain/0c78633e3bd1f7188437d74ecef5966b53216f23

document setsamples() new capabilities
---

diff --git a/lib/Imager/Draw.pod b/lib/Imager/Draw.pod
index 8de680d9..5fbe72e6 100644
--- a/lib/Imager/Draw.pod
+++ b/lib/Imager/Draw.pod
@@ -1042,7 +1042,7 @@ samples provided will be written.
 
 C<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.
+This can be C<8bit>, C<float> or for 16-bit images only, C<16bit>.
 
 =item *
 
@@ -1051,24 +1051,63 @@ the first channel.  Default: C<< [ 0 .. $self->getchannels()-1 ] >>
 
 =item *
 
-C<data> - a reference to an array of samples to write.  Required.
+C<data> - for a type of C<8bit> or C<float> this can be a reference to
+an array of samples or a scalar containing packed samples.  If C<data>
+is a scalar it may only contain characters from \x00 to \xFF.
+
+For a type of C<16bit> this can only be a reference to an array of
+samples to write.
+
+Required.
 
 =item *
 
-C<offset> - the starting offset within the array referenced by I<data>
+C<offset> - the starting offset within the array referenced by
+I<data>.  If C<data> is a scalar containing packed samples this offset
+is in samples.
 
 =back
 
 Returns the number of samples written.
 
+  $targ->setsamples(y => $y, data => \@data);
+
+  $targ->setsamples(y => $y, data => \@data, offset => $src->getchannels);
+
+Copy from one image to another:
+
+  my $targ = Imager->new(xsize => $src->getwidth,
+        ysize => $src->getheight, channels => $src->getchannels);
+  for my $y (0 .. $targ->getheight()-1) {
+    my $row = $src->getsamples(y => $y)
+      or die $src->errstr;
+    $targ->setsamples(y => $y, data => $row)
+      or die $targ->errstr;;
+  }
+
+Compose an image from separate source channels:
+
+  my @src = ...; # images to work from, up to 4
+  my $targ = Imager->new(xsize => $src[0]->getwidth,
+     ysize => $src[0]->getheight, channels => scalar(@src));
+  for my $y (0 .. $targ->getheight()-1) {
+    for my $ch (0 .. $#src) {
+      my $row = $src[$ch]->getsamples(y => $y, channels => [ 0 ]);
+      $targ->setsamples(y => $y, data => $row, channels => [ $ch ] );
+    }
+  }
+
 =back
 
 =head1 Packed Color Data
 
-The getscanline() and setscanline() functions can work with pixels
+The getscanline() and setscanline() methods can work with pixels
 packed into scalars.  This is useful to remove the cost of creating
 color objects, but should only be used when performance is an issue.
 
+The getsamples() and setsamples() methods can work with samples packed
+into scalars.
+
 Packed data can either be 1 byte per sample or 1 double per sample.
 
 Each pixel returned by getscanline() or supplied to setscanline()