--- OpenCL/OpenCL.pm	2011/11/16 00:35:30	1.5
+++ OpenCL/OpenCL.pm	2011/11/17 01:36:52	1.9
@@ -8,9 +8,42 @@
 
 =head1 DESCRIPTION
 
-This is an early release which might be useful, but hasn't seen any testing.
+This is an early release which might be useful, but hasn't seen much testing.
 
-=head1 HELPFUL RESOURCES
+=head2 OpenCL FROM 10000 FEET HEIGHT
+
+Here is a high level overview of OpenCL:
+
+First you need to find one or more OpenCL::Platforms (kind of like
+vendors) - usually there is only one.
+
+Each platform gives you access to a number of OpenCL::Device objects, e.g.
+your graphics card.
+
+From a platform and some devices, you create an OpenCL::Context, which is
+a very central object in OpenCL: Once you have a context you can create
+most other objects:
+
+OpenCL::Program objects, which store source code and, after building
+("compiling and linking"), also binary programs. For each kernel function
+in a program you can then create an OpenCL::Kernel object which represents
+basically a function call with argument values.
+
+OpenCL::Memory objects of various flavours: OpenCL::Buffers objects (flat
+memory areas, think array) and OpenCL::Image objects (think 2d or 3d
+array) for bulk data and input and output for kernels.
+
+OpenCL::Sampler objects, which are kind of like texture filter modes in
+OpenGL.
+
+OpenCL::Queue objects - command queues, which allow you to submit memory
+reads, writes and copies, as well as kernel calls to your devices. They
+also offer a variety of methods to synchronise request execution, for
+example with barriers or OpenCL::Event objects.
+
+OpenCL::Event objects are used to signal when something is complete.
+
+=head2 HELPFUL RESOURCES
 
 The OpenCL spec used to develop this module (1.2 spec was available, but
 no implementation was available to me :).
@@ -21,6 +54,29 @@
 
    http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/
 
+=head1 BASIC WORKFLOW
+
+To get something done, you basically have to do this once:
+
+Find some platform (e.g. the first one) and some device (e.g. the first
+device you can find), and create a context from those.
+
+Create a command queue from your context, and program objects from your
+OpenCL source code, build the programs.
+
+Create kernel objects for all kernels you want to use.
+
+Then, to execute stuff, you repeat this:
+
+Create some input and output buffers from your context. Initialise the
+input buffers with data. Set these as arguments to your kernel.
+
+Enqueue the kernel execution.
+
+Enqueue buffer reads for your output buffer to read results.
+
+The next section shows how this can be done.
+
 =head1 EXAMPLES
 
 =head2 Enumerate all devices and get contexts for them.
@@ -39,7 +95,7 @@
 
    my $dev = ((OpenCL::platforms)[0]->devices)[0];
    my $ctx = $dev->context_simple;
-   my $queue = $ctx->command_queue_simple ($dev);
+   my $queue = $ctx->queue ($dev);
 
 =head2 Print all supported image formats of a context.
 
@@ -150,11 +206,11 @@
 arrays (C<size_t origin[3]>), while this module explicitly expects the
 components as separate arguments-
 
-=item * Where possible, the row_pitch value is calculated from the perl
-scalar length and need not be specified.
+=item * Where possible, one of the pitch values is calculated from the
+perl scalar length and need not be specified.
 
 =item * When enqueuing commands, the wait list is specified by adding
-extra arguments to the function - everywhere a C<$wait_events...> argument
+extra arguments to the function - anywhere a C<$wait_events...> argument
 is documented this can be any number of event objects.
 
 =item * When enqueuing commands, if the enqueue method is called in void
@@ -167,6 +223,24 @@
 
 =back
 
+=head2 PERL AND OPENCL TYPES
+
+This handy(?) table lists OpenCL types and their perl, PDL and pack/unpack
+format equivalents:
+
+   OpenCL    perl   PDL       pack/unpack
+   char      IV     -         c
+   uchar     IV     byte      C
+   short     IV     short     s
+   ushort    IV     ushort    S
+   int       IV     long?     l
+   uint      IV     -         L
+   long      IV     longlong  q
+   ulong     IV     -         Q
+   float     NV     float     f
+   half      IV     ushort    S
+   double    NV     double    d
+
 =head2 THE OpenCL PACKAGE
 
 =over 4
@@ -179,7 +253,7 @@
 
 Comverts an error value into a human readable string.
 
-=item $str = OpenCL::err2str $enum
+=item $str = OpenCL::enum2str $enum
 
 Converts most enum values (inof parameter names, image format constants,
 object types, addressing and filter modes, command types etc.) into a
@@ -259,9 +333,9 @@
 
 L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clGetContextInfo.html>
 
-=item $queue = $ctx->command_queue_simple ($device)
+=item $queue = $ctx->queue ($device, $properties)
 
-Convenience function to create a new OpenCL::Queue object from the context and the given device.
+Create a new OpenCL::Queue object from the context and the given device.
 
 L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clCreateCommandQueue.html>
 
@@ -329,7 +403,8 @@
 event objects as extra parameters to the enqueue methods.
 
 Queues execute in-order by default, without any parallelism, so in most
-cases it's not necessary to wait for or create event objects.
+cases (i.e. you use only one queue) it's not necessary to wait for or
+create event objects.
 
 =over 4