--- OpenCL/OpenCL.pm	2012/04/30 23:35:16	1.65
+++ OpenCL/OpenCL.pm	2012/05/01 16:37:23	1.66
@@ -307,7 +307,7 @@
       select undef, undef, undef, 1/60;
    }
 
-=item How to modify the previous example to not rely on GL sharing.
+=head2 How to modify the previous example to not rely on GL sharing.
 
 For those poor souls with only a sucky CPU OpenCL implementation, you
 currently have to read the image into some perl scalar, and then modify a
@@ -559,6 +559,9 @@
    @OpenCL::Image1DBuffer::ISA = OpenCL::Image::;
 
    @OpenCL::UserEvent::ISA     = OpenCL::Event::;
+
+   @OpenCL::MappedBuffer       =
+   @OpenCL::MappedImage        = OpenCL::Mapped::;
 }
 
 =head2 THE OpenCL PACKAGE
@@ -1367,6 +1370,50 @@
 
 =back
 
+=head3 MEMORY MAPPED BUFFERS
+
+OpenCL allows you to map buffers and images to host memory (read: perl
+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
+OpenCL::Mapped CLASS> section for details on what to do with these
+objects.
+
+The object will be unmapped automatically when the mapped object is
+destroyed (you can use a barrier to make sure the unmap has finished,
+before using the buffer in a kernel), but you can also enqueue an unmap
+operation manually.
+
+=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...)
+
+Maps the given buffer into host memory and returns a C<OpenCL::MappedBuffer> object.
+
+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...)
+
+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.
+
+L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clEnqueueMapImage.html>
+
+=item $ev = $queue->unmap ($mapped, $wait_events...)
+
+Unmaps the data from host memory. You must not call any methods that
+modify the data, or modify the data scalar directly, after calling this
+method.
+
+The mapped event object will always be passed as part of the
+$wait_events. The mapped event object will be replaced by the new event
+object that this request creates.
+
+=back
+
 =head2 THE OpenCL::Memory CLASS
 
 This the superclass of all memory objects - OpenCL::Buffer, OpenCL::Image,
@@ -1917,6 +1964,76 @@
 
 =back
 
+=head2 THE OpenCL::Mapped CLASS
+
+This class represents objects mapped into host memory. They are
+represented by a blessed string scalar. The string data is the mapped
+memory area, that is, if you read or write it, then the mapped object is
+accessed directly.
+
+You must only ever use operations that modify the string in-place - for
+example, a C<substr> that doesn't change the length, or maybe a regex that
+doesn't change the length. Any other operation might cause the data to be
+copied.
+
+When the object is destroyed it will enqueue an implicit unmap operation
+on the queue that was used to create it.
+
+Example, replace the first two floats in the mapped buffer by 1 and 2.
+
+   my $mapped = $queue->map_buffer ($buf, ...
+   $mapped->event->wait; # make sure it's there
+
+   # now replace first 8 bytes by new data, which is exactly 8 bytes long
+   # we blindly assume device endianness to equal host endianness
+   # (and of course, we assume iee 754 single precision floats :)
+   substr $$mapped, 0, 8, pack "f*", 1, 2;
+
+=over 4
+
+=item $bool = $mapped->mapped
+
+Returns whether the object is still mapped - true before an C<unmap> is
+enqueued, false afterwards.
+
+=item $ev = $mapped->event
+
+Return the event object associated with the mapped object. Initially, this
+will be the event object created when mapping the object, and after an
+unmap, this will be the event object that the unmap operation created.
+
+=item $mapped->wait
+
+Same as C<< $mapped->event->wait >> - makes sure no operations on this
+mapped object are outstanding.
+
+=item $bytes = $mapped->size
+
+Returns the size of the mapped area, in bytes. Same as C<length $$mapped>.
+
+=item $ptr = $mapped->ptr
+
+Returns the raw memory address of the mapped area - same as C<$mapped+0>.
+
+=back
+
+=head2 THE OpenCL::MappedBuffer CLASS
+
+This is a subclass of OpenCL::Mapped, representing mapped buffers.
+
+=over 4
+
+=back
+
+=head2 THE OpenCL::MappedImage CLASS
+
+This is a subclass of OpenCL::Mapped, representing mapped images.
+
+=over 4
+
+=back
+
+
 =cut
 
 1;