--- OpenCL/OpenCL.pm	2012/05/01 16:37:23	1.66
+++ OpenCL/OpenCL.pm	2012/05/03 23:30:08	1.69
@@ -560,8 +560,8 @@
 
    @OpenCL::UserEvent::ISA     = OpenCL::Event::;
 
-   @OpenCL::MappedBuffer       =
-   @OpenCL::MappedImage        = OpenCL::Mapped::;
+   @OpenCL::MappedBuffer::ISA  =
+   @OpenCL::MappedImage::ISA   = OpenCL::Mapped::;
 }
 
 =head2 THE OpenCL PACKAGE
@@ -1160,6 +1160,17 @@
 
 L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clCreateProgramWithSource.html>
 
+=item ($program, \@status) = $ctx->program_with_binary (\@devices, \@binaries)
+
+Creates a new OpenCL::Program object from the given binaries.
+
+L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clCreateProgramWithBinary.html>
+
+Example: clone an existing program object that contains a successfully
+compiled program, no matter how useless this is.
+
+   my $clone = $ctx->program_with_binary ([$prog->devices], [$prog->binaries]);
+
 =item $packed_value = $ctx->info ($name)
 
 See C<< $platform->info >> for details.
@@ -1376,7 +1387,7 @@
 scalars). This is done much like reading or copying a buffer, by enqueuing
 a map or unmap operation on the command queue.
 
-The map operations return a C<OpenCL::Mapped> object - see L<THE
+The map operations return an C<OpenCL::Mapped> object - see L<THE
 OpenCL::Mapped CLASS> section for details on what to do with these
 objects.
 
@@ -1387,21 +1398,44 @@
 
 =over 4
 
-=item $mapped_buffer = $queue->map_buffer ($buf, $data, $blocking=1, $map_flags=OpenCL::MAP_READ|OpenCL::MAP_WRITE, $offset=0, $size=0, $wait_events...)
+=item $mapped_buffer = $queue->map_buffer ($buf, $blocking=1, $map_flags=OpenCL::MAP_READ|OpenCL::MAP_WRITE, $offset=0, $size=undef, $wait_events...)
 
-Maps the given buffer into host memory and returns a C<OpenCL::MappedBuffer> object.
+Maps the given buffer into host memory and returns an
+C<OpenCL::MappedBuffer> object. If C<$size> is specified as undef, then
+the map will extend to the end of the buffer.
 
 L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clEnqueueMapBuffer.html>
 
-=item $mapped_image = $queue->map_image ($img, $data, $blocking=1, $map_flags=OpenCL::MAP_READ|OpenCL::MAP_WRITE, $x=0, $y=0, $z=0, $width=0, $height=0, $depth=0, $wait_events...)
+Example: map the buffer $buf fully and replace the first 4 bytes by "abcd", then unmap.
+
+   {
+     my $mapped = $queue->map_buffer ($buf, 1, OpenCL::MAP_WRITE);
+     substr $$mapped, 0, 4, "abcd";
+   } # asynchronously unmap because $mapped is destroyed
+
+=item $mapped_image = $queue->map_image ($img, $blocking=1, $map_flags=OpenCL::MAP_READ|OpenCL::MAP_WRITE, $x=0, $y=0, $z=0, $width=undef, $height=undef, $depth=undef, $wait_events...)
+
+Maps the given image area into host memory and return an
+C<OpenCL::MappedImage> object.
 
-Maps the given image area into host memory and return a
-C<OpenCL::MappedImage> object. Although there are default values for most
-arguments, you currently have to specify all arguments, otherwise the call
-will fail.
+If any of C<$width>, C<$height> and/or C<$depth> are C<undef> then they
+will be replaced by the maximum possible value.
 
 L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clEnqueueMapImage.html>
 
+Example: map an image (with OpenCL::UNSIGNED_INT8 channel type) and set
+the first channel of the leftmost column to 5, then explicitly unmap
+it. You are not necessarily meant to do it this way, this example just
+shows you the accessors to use :)
+
+   my $mapped = $queue->map_image ($image, 1, OpenCL::MAP_WRITE);
+
+   $mapped->set ($_ * $mapped->row_pitch, pack "C", 5)
+      for 0..$image->height;
+
+   $mapped->unmap;.
+   $mapped->wait; # only needed for out of order queues normally
+
 =item $ev = $queue->unmap ($mapped, $wait_events...)
 
 Unmaps the data from host memory. You must not call any methods that
@@ -1979,6 +2013,10 @@
 When the object is destroyed it will enqueue an implicit unmap operation
 on the queue that was used to create it.
 
+Keep in mind that you I<need> to unmap (or destroy) mapped objects before
+OpenCL sees the changes, even if some implementations don't need this
+sometimes.
+
 Example, replace the first two floats in the mapped buffer by 1 and 2.
 
    my $mapped = $queue->map_buffer ($buf, ...
@@ -1991,6 +2029,11 @@
 
 =over 4
 
+=item $ev = $mapped->unmap ($wait_events...)
+
+Unmaps the mapped memory object, using the queue originally used to create
+it, quite similarly to C<< $queue->unmap ($mapped, ...) >>.
+
 =item $bool = $mapped->mapped
 
 Returns whether the object is still mapped - true before an C<unmap> is
@@ -2013,24 +2056,46 @@
 
 =item $ptr = $mapped->ptr
 
-Returns the raw memory address of the mapped area - same as C<$mapped+0>.
+Returns the raw memory address of the mapped area.
 
-=back
+=item $mapped->set ($offset, $data)
 
-=head2 THE OpenCL::MappedBuffer CLASS
+Replaces the data at the given C<$offset> in the memory area by the new
+C<$data>. This method is safer than direct manipulation of C<$mapped>
+because it does bounds-checking, but also slower.
 
-This is a subclass of OpenCL::Mapped, representing mapped buffers.
+=item $data = $mapped->get ($offset, $length)
 
-=over 4
+Returns (without copying) a scalar representing the data at the given
+C<$offset> and C<$length> in the mapped memory area. This is the same as
+the following substr, except much slower;
+
+   $data = substr $$mapped, $offset, $length
+
+=cut
+
+sub OpenCL::Mapped::get {
+   substr ${$_[0]}, $_[1], $_[2]
+}
 
 =back
 
+=head2 THE OpenCL::MappedBuffer CLASS
+
+This is a subclass of OpenCL::Mapped, representing mapped buffers.
+
 =head2 THE OpenCL::MappedImage CLASS
 
 This is a subclass of OpenCL::Mapped, representing mapped images.
 
 =over 4
 
+=item $bytes = $mapped->row_pitch
+
+=item $bytes = $mapped->slice_pitch
+
+Return the row or slice pitch of the image that has been mapped.
+
 =back