--- OpenCL/OpenCL.pm	2012/05/01 22:04:56	1.67
+++ OpenCL/OpenCL.pm	2012/05/03 23:30:08	1.69
@@ -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 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.
+Maps the given image area into host memory and return an
+C<OpenCL::MappedImage> object.
+
+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
@@ -2022,27 +2056,25 @@
 
 =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.
 
 =item $mapped->set ($offset, $data)
 
 Replaces the data at the given C<$offset> in the memory area by the new
-C<$data>. This method is safer but slower than direct manipulation of
-C<$$mapped> with substr.
+C<$data>. This method is safer than direct manipulation of C<$mapped>
+because it does bounds-checking, but also slower.
 
 =item $data = $mapped->get ($offset, $length)
 
 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:
+the following substr, except much slower;
 
    $data = substr $$mapped, $offset, $length
 
-#TODO: really?
-
 =cut
 
-sub get {
+sub OpenCL::Mapped::get {
    substr ${$_[0]}, $_[1], $_[2]
 }