--- OpenCL/OpenCL.pm	2012/04/21 19:48:58	1.47
+++ OpenCL/OpenCL.pm	2012/04/24 13:45:58	1.51
@@ -159,12 +159,7 @@
       }
    ';
 
-   my $prog = $ctx->program_with_source ($src);
-
-   # build croaks on compile errors, so catch it and print the compile errors
-   eval { $prog->build ($dev, "-cl-fast-relaxed-math"); 1 }
-      or die $prog->build_log;
-
+   my $prog = $ctx->build_program ($src);
    my $kernel = $prog->kernel ("squareit");
 
 =head2 Create some input and output float buffers, then call the
@@ -269,10 +264,8 @@
      write_imagef (img, (int2)(get_global_id (0), get_global_id (1)), (float4)(colour * p.x * p.x, 1.));
    }
    EOF
-   my $prog = $ctx->program_with_source ($src);
-   eval { $prog->build ($dev); 1 }
-      or die $prog->build_log ($dev);
 
+   my $prog = $ctx->build_program ($src);
    my $kernel = $prog->kernel ("juliatunnel");
 
    # program compiled, kernel ready, now draw and loop
@@ -458,6 +451,13 @@
 
 L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clGetPlatformInfo.html>
 
+=item $platform->unload_compiler
+
+Attempts to unload the compiler for this platform, for endless
+profit. Does nothing on OpenCL 1.1.
+
+L<http://www.khronos.org/registry/cl/sdk/1.2/docs/man/xhtml/clUnloadPlatformCompiler.html>
+
 =for gengetinfo begin platform
 
 =item $string = $platform->profile
@@ -754,7 +754,7 @@
 
 =item $uint = $device->reference_count_ext
 
-Calls C<clGetDeviceInfo> with C<CL_DEVICE_REFERENCE_COUNT_EXT > and returns the result.
+Calls C<clGetDeviceInfo> with C<CL_DEVICE_REFERENCE_COUNT_EXT> and returns the result.
 
 =item @device_partition_property_exts = $device->partition_style_ext
 
@@ -768,6 +768,33 @@
 
 =over 4
 
+=item $prog = $ctx->build_program ($program, $options = "")
+
+This convenience function tries to build the program on all devices in
+the context. If the build fails, then the function will C<croak> with the
+build log. Otherwise ti returns the program object.
+
+The C<$program> can either be a C<OpenCL::Program> object or a string
+containing the program. In the latter case, a program objetc will be
+created automatically.
+
+=cut
+
+sub OpenCL::Context::build_program {
+   my ($self, $prog, $options) = @_;
+
+   $prog = $self->program_with_source ($prog)
+      unless ref $prog;
+
+   for my $dev ($self->devices) {
+      eval { $prog->build ($dev, $options); 1 }
+         or Carp::croak "Building OpenCL program for device '" . $dev->name . "' failed:\n"
+                      . $prog->build_log ($dev);
+   }
+
+   $prog
+}
+
 =item $queue = $ctx->queue ($device, $properties)
 
 Create a new OpenCL::Queue object from the context and the given device.
@@ -796,6 +823,13 @@
 Creates a new OpenCL::Buffer (actually OpenCL::BufferObj) object and
 initialise it with the given data values.
 
+=item $img = $ctx->image ($self, $flags, $channel_order, $channel_type, $type, $width, $height, $depth, $array_size = 0, $row_pitch = 0, $slice_pitch = 0, $num_mip_level = 0, $num_samples = 0, $*data = &PL_sv_undef)
+
+Creates a new OpenCL::Image object and optionally initialises it with
+the given data values.
+
+L<http://www.khronos.org/registry/cl/sdk/1.2/docs/man/xhtml/clCreateImage.html>
+
 =item $img = $ctx->image2d ($flags, $channel_order, $channel_type, $width, $height, $row_pitch = 0, $data = undef)
 
 Creates a new OpenCL::Image2D object and optionally initialises it with
@@ -1238,7 +1272,8 @@
 
 =item $program->build ($device, $options = "")
 
-Tries to build the program with the givne options.
+Tries to build the program with the given options. See also the
+C<$ctx->build> convenience function.
 
 L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clBuildProgram.html>
 
@@ -1256,6 +1291,12 @@
 
 L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clCreateKernel.html>
 
+=item @kernels = $program->kernels_in_program
+
+Returns all kernels successfully compiled for all devices in program.
+
+http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clCreateKernelsInProgram.html
+
 =for gengetinfo begin program_build
 
 =item $build_status = $program->build_status ($device)
@@ -1400,6 +1441,10 @@
 set by specifying the size, and sampler and event must be objects of that
 type.
 
+Setting an argument for a kernel does NOT keep a reference to the object -
+for example, if you set an argument to some image object, free the image,
+and call the kernel, you will run into undefined behaviour.
+
 L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clSetKernelArg.html>
 
 =back