[ViewVC] Diff of: cvs/OpenCL/OpenCL.pm

Comparing OpenCL/OpenCL.pm (file contents):
Revision 1.77 by root, Sat May 5 12:54:03 2012 UTC vs.
Revision 1.88 by root, Tue Oct 22 17:25:38 2013 UTC

 specific device ("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::Buffer objects (flat
-memory areas, think arrays or structs) and OpenCL::Image objects (think 2d
+memory areas, think arrays or structs) and OpenCL::Image objects (think 2D
-or 3d array) for bulk data and input and output for kernels.
+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
 initialised at creation time).
 Enqueue the kernel execution.
 Enqueue buffer reads for your output buffer to read results.
-=head1 OPENCL 1.1 VS. OPENCL 1.2
-This module supports both OpenCL version 1.1 and 1.2, although the OpenCL
-1.2 interface hasn't been tested much for lack of availability of an
-actual implementation.
-Every function or method in this manual page that interfaces to a
-particular OpenCL function has a link to the its C manual page.
-If the link contains a F<1.1>, then this function is an OpenCL 1.1
-function. Most but not all also exist in OpenCL 1.2, and this module
-tries to emulate the missing ones for you, when told to do so at
-compiletime. You cna check whether a function was removed in OpenCL 1.2 by
-replacing the F<1.1> component in the URL by F<1.2>.
-If the link contains a F<1.2>, then this is a OpenCL 1.2-only
-function. Even if the module was compiled with OpenCL 1.2 header files
-and has an 1.2 OpenCL library, calling such a function on a platform that
-doesn't implement 1.2 causes undefined behaviour, usually a crash (But
-this is not guaranteed).
-You can find out whether this module was compiled to prefer 1.1
-functionality by ooking at C<OpenCL::PREFER_1_1> - if it is true, then
-1.1 functions generally are implemented using 1.1 OpenCL functions. If it
-is false, then 1.1 functions missing from 1.2 are emulated by calling 1.2
-fucntions.
-This is a somewhat sorry state of affairs, but the Khronos group choose to
-make every release of OpenCL source and binary incompatible with previous
-releases.
 =head1 EXAMPLES
 =head2 Enumerate all devices and get contexts for them.
    $ev->wait;
 =head2 Use the OpenGL module to share a texture between OpenCL and OpenGL and draw some julia
 set flight effect.
-This is quite a long example to get you going - you can download it from
+This is quite a long example to get you going - you can also download it
-L<http://cvs.schmorp.de/OpenCL/examples/juliaflight>.
+from L<http://cvs.schmorp.de/OpenCL/examples/juliaflight>.
    use OpenGL ":all";
    use OpenCL;
    my $S = $ARGV[0] || 256; # window/texture size, smaller is faster
    # find and use the first opencl device that let's us get a shared opengl context
    my $platform;
    my $dev;
    my $ctx;
+   sub get_context {
-   for (OpenCL::platforms) {
+      for (OpenCL::platforms) {
-      $platform = $_;
+         $platform = $_;
-      for ($platform->devices) {
+         for ($platform->devices) {
-         $dev = $_;
+            $dev = $_;
-         $ctx = $platform->context ([OpenCL::GLX_DISPLAY_KHR, undef, OpenCL::GL_CONTEXT_KHR, undef], [$dev])
+            $ctx = eval { $platform->context ([OpenCL::GLX_DISPLAY_KHR, undef, OpenCL::GL_CONTEXT_KHR, undef], [$dev]) }
-            and last;
+               and return;
+         }
       }
+      die "cannot find suitable OpenCL device\n";
    }
-   $ctx
+   get_context;
-      or die "cannot find suitable OpenCL device\n";
    my $queue = $ctx->queue ($dev);
    # now attach an opencl image2d object to the opengl texture
    my $tex = $ctx->gl_texture2d (OpenCL::MEM_WRITE_ONLY, GL_TEXTURE_2D, 0, $texid);
 =item * When enqueuing commands, if the enqueue method is called in void
 context, no event is created. In all other contexts an event is returned
 by the method.
-=item * This module expects all functions to return C<CL_SUCCESS>. If any
+=item * This module expects all functions to return C<OpenCL::SUCCESS>. If any
 other status is returned the function will throw an exception, so you
 don't normally have to to any error checking.
 =back
+=head2 CONSTANTS
+All C<CL_xxx> constants that this module supports are always available
+in the C<OpenCL> namespace as C<OpenCL::xxx> (i.e. without the C<CL_>
+prefix). Constants which are not defined in the header files used during
+compilation, or otherwise are not available, will have the value C<0> (in
+some cases, this will make them indistinguishable from real constants,
+sorry).
+The latest version of this module knows and exports the constants
+listed in L<http://cvs.schmorp.de/OpenCL/constiv.h>.
+=head2 OPENCL 1.1 VS. OPENCL 1.2
+This module supports both OpenCL version 1.1 and 1.2, although the OpenCL
+1.2 interface hasn't been tested much for lack of availability of an
+actual implementation.
+Every function or method in this manual page that interfaces to a
+particular OpenCL function has a link to the its C manual page.
+If the link contains a F<1.1>, then this function is an OpenCL 1.1
+function. Most but not all also exist in OpenCL 1.2, and this module
+tries to emulate the missing ones for you, when told to do so at
+compiletime. You can check whether a function was removed in OpenCL 1.2 by
+replacing the F<1.1> component in the URL by F<1.2>.
+If the link contains a F<1.2>, then this is a OpenCL 1.2-only
+function. Even if the module was compiled with OpenCL 1.2 header files
+and has an 1.2 OpenCL library, calling such a function on a platform that
+doesn't implement 1.2 causes undefined behaviour, usually a crash (But
+this is not guaranteed).
+You can find out whether this module was compiled to prefer 1.1
+functionality by ooking at C<OpenCL::PREFER_1_1> - if it is true, then
+1.1 functions generally are implemented using 1.1 OpenCL functions. If it
+is false, then 1.1 functions missing from 1.2 are emulated by calling 1.2
+fucntions.
+This is a somewhat sorry state of affairs, but the Khronos group choose to
+make every release of OpenCL source and binary incompatible with previous
+releases.
 =head2 PERL AND OPENCL TYPES
 This handy(?) table lists OpenCL types and their perl, PDL and pack/unpack
 format equivalents:
 use Async::Interrupt ();
 our $POLL_FUNC; # set by XS
 BEGIN {
-   our $VERSION = '0.99';
+   our $VERSION = '1.01';
    require XSLoader;
    XSLoader::load (__PACKAGE__, $VERSION);
    @OpenCL::Platform::ISA      =
 The last error returned by a function - it's only valid after an error occured
 and before calling another OpenCL function.
 =item $str = OpenCL::err2str [$errval]
-Converts an error value into a human readable string. IF no error value is
+Converts an error value into a human readable string. If no error value is
 given, then the last error will be used (as returned by OpenCL::errno).
+The latest version of this module knows the error constants
+listed in L<http://cvs.schmorp.de/OpenCL/errstr.h>.
 =item $str = OpenCL::enum2str $enum
 Converts most enum values (of parameter names, image format constants,
 object types, addressing and filter modes, command types etc.) into a
 human readable string. When confronted with some random integer it can be
 very helpful to pass it through this function to maybe get some readable
 string out of it.
+The latest version of this module knows the enumaration constants
+listed in L<http://cvs.schmorp.de/OpenCL/enumstr.h>.
 =item @platforms = OpenCL::platforms
 Returns all available OpenCL::Platform objects.
 L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clGetPlatformIDs.html>
 L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clCreateContextFromType.html>
 =item $ctx = $platform->context ($properties, \@devices, $callback->($err, $pvt) = $print_stderr)
 Create a new OpenCL::Context object using the given device object(s)- a
-CL_CONTEXT_PLATFORM property is supplied automatically.
+OpenCL::CONTEXT_PLATFORM property is supplied automatically.
 L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clCreateContext.html>
 =item $packed_value = $platform->info ($name)
 =over 4
 =item $packed_value = $device->info ($name)
 See C<< $platform->info >> for details.
+type: OpenCL::DEVICE_TYPE_DEFAULT, OpenCL::DEVICE_TYPE_CPU,
+OpenCL::DEVICE_TYPE_GPU, OpenCL::DEVICE_TYPE_ACCELERATOR,
+OpenCL::DEVICE_TYPE_CUSTOM, OpenCL::DEVICE_TYPE_ALL.
+fp_config: OpenCL::FP_DENORM, OpenCL::FP_INF_NAN, OpenCL::FP_ROUND_TO_NEAREST,
+OpenCL::FP_ROUND_TO_ZERO, OpenCL::FP_ROUND_TO_INF, OpenCL::FP_FMA,
+OpenCL::FP_SOFT_FLOAT, OpenCL::FP_CORRECTLY_ROUNDED_DIVIDE_SQRT.
+mem_cache_type: OpenCL::NONE, OpenCL::READ_ONLY_CACHE, OpenCL::READ_WRITE_CACHE.
+local_mem_type: OpenCL::LOCAL, OpenCL::GLOBAL.
+exec_capabilities: OpenCL::EXEC_KERNEL, OpenCL::EXEC_NATIVE_KERNEL.
+command_queue_properties: OpenCL::QUEUE_OUT_OF_ORDER_EXEC_MODE_ENABLE,
+OpenCL::QUEUE_PROFILING_ENABLE.
+partition_properties: OpenCL::DEVICE_PARTITION_EQUALLY,
+OpenCL::DEVICE_PARTITION_BY_COUNTS, OpenCL::DEVICE_PARTITION_BY_COUNTS_LIST_END,
+OpenCL::DEVICE_PARTITION_BY_AFFINITY_DOMAIN.
+affinity_domain: OpenCL::DEVICE_AFFINITY_DOMAIN_NUMA,
+OpenCL::DEVICE_AFFINITY_DOMAIN_L4_CACHE, OpenCL::DEVICE_AFFINITY_DOMAIN_L3_CACHE,
+OpenCL::DEVICE_AFFINITY_DOMAIN_L2_CACHE, OpenCL::DEVICE_AFFINITY_DOMAIN_L1_CACHE,
+OpenCL::DEVICE_AFFINITY_DOMAIN_NEXT_PARTITIONABLE.
 L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clGetDeviceInfo.html>
 =item @devices = $device->sub_devices (\@properties)
 OpenCL::MEM_USE_HOST_PTR, OpenCL::MEM_ALLOC_HOST_PTR, OpenCL::MEM_COPY_HOST_PTR,
 OpenCL::MEM_HOST_WRITE_ONLY, OpenCL::MEM_HOST_READ_ONLY, OpenCL::MEM_HOST_NO_ACCESS.
 L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clCreateBuffer.html>
+A somewhat informative thread on the flags is:
+L<http://www.khronos.org/message_boards/viewtopic.php?f=28&t=2440>
 =item $buf = $ctx->buffer_sv ($flags, $data)
 Creates a new OpenCL::Buffer (actually OpenCL::BufferObj) object and
 initialise it with the given data values.
 channel_type: OpenCL::SNORM_INT8, OpenCL::SNORM_INT16, OpenCL::UNORM_INT8,
 OpenCL::UNORM_INT16, OpenCL::UNORM_SHORT_565, OpenCL::UNORM_SHORT_555,
 OpenCL::UNORM_INT_101010, OpenCL::SIGNED_INT8, OpenCL::SIGNED_INT16,
 OpenCL::SIGNED_INT32, OpenCL::UNSIGNED_INT8, OpenCL::UNSIGNED_INT16,
 OpenCL::UNSIGNED_INT32, OpenCL::HALF_FLOAT, OpenCL::FLOAT.
 type: OpenCL::MEM_OBJECT_BUFFER, OpenCL::MEM_OBJECT_IMAGE2D,
 OpenCL::MEM_OBJECT_IMAGE3D, OpenCL::MEM_OBJECT_IMAGE2D_ARRAY,
 OpenCL::MEM_OBJECT_IMAGE1D, OpenCL::MEM_OBJECT_IMAGE1D_ARRAY,
 OpenCL::MEM_OBJECT_IMAGE1D_BUFFER.
 =item $ev = $queue->copy_buffer ($src, $dst, $src_offset, $dst_offset, $len, $wait_events...)
 L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clEnqueueCopyBuffer.html>
-=item $ev = $queue->read_buffer_rect (OpenCL::Memory buf, cl_bool blocking, $buf_x, $buf_y, $buf_z, $host_x, $host_y, $host_z, $width, $height, $depth, $buf_row_pitch, $buf_slice_pitch, $host_row_pitch, $host_slice_pitch, $data, $wait_events...)
+$eue->read_buffer_rect ($buf, cl_bool blocking, $buf_x, $buf_y, $buf_z, $host_x, $host_y, $host_z, $width, $height, $depth, $buf_row_pitch, $buf_slice_pitch, $host_row_pitch, $host_slice_pitch, $data, $wait_events...)
 http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clEnqueueReadBufferRect.html
-=item $ev = $queue->write_buffer_rect (OpenCL::Memory buf, cl_bool blocking, $buf_x, $buf_y, $buf_z, $host_x, $host_y, $host_z, $width, $height, $depth, $buf_row_pitch, $buf_slice_pitch, $host_row_pitch, $host_slice_pitch, $data, $wait_events...)
+=item $ev = $queue->write_buffer_rect ($buf, $blocking, $buf_y, $host_x, $host_z, $height, $buf_row_pitch, $host_row_pitch, $data, $wait_events...)
 http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clEnqueueWriteBufferRect.html
 =item $ev = $queue->copy_buffer_to_image ($src_buffer, $dst_image, $src_offset, $dst_x, $dst_y, $dst_z, $width, $height, $depth, $wait_events...)
 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)
+   $mapped->write ($_ * $mapped->row_pitch, pack "C", 5)
-      for 0..$image->height;
+      for 0 .. $mapped->height - 1;
    $mapped->unmap;.
    $mapped->wait; # only needed for out of order queues normally
 =item $ev = $queue->unmap ($mapped, $wait_events...)
 See C<< $platform->info >> for details.
 L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clGetMemObjectInfo.html>
+=item $memory->destructor_callback ($cb->())
+Sets a callback that will be invoked after the memory object is destructed.
+L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clSetMemObjectDestructorCallback.html>
 =for gengetinfo begin mem
 =item $mem_object_type = $mem->type
 Calls C<clGetMemObjectInfo> with C<OpenCL::MEM_TYPE> and returns the result.
 =over 4
 =item $subbuf = $buf_obj->sub_buffer_region ($flags, $origin, $size)
 Creates an OpenCL::Buffer objects from this buffer and returns it. The
-C<buffer_create_type> is assumed to be C<CL_BUFFER_CREATE_TYPE_REGION>.
+C<buffer_create_type> is assumed to be C<OpenCL::BUFFER_CREATE_TYPE_REGION>.
 L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clCreateSubBuffer.html>
 =back
 L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clGetImageInfo.html>
 =item ($channel_order, $channel_data_type) = $image->format
 Returns the channel order and type used to create the image by calling
-C<clGetImageInfo> with C<CL_IMAGE_FORMAT>.
+C<clGetImageInfo> with C<OpenCL::IMAGE_FORMAT>.
 =for gengetinfo begin image
 =item $int = $image->element_size
 =item $packed_value = $program->build_info ($device, $name)
 Similar to C<< $platform->info >>, but returns build info for a previous
 build attempt for the given device.
+binary_type: OpenCL::PROGRAM_BINARY_TYPE_NONE,
+OpenCL::PROGRAM_BINARY_TYPE_COMPILED_OBJECT,
+OpenCL::PROGRAM_BINARY_TYPE_LIBRARY,
+OpenCL::PROGRAM_BINARY_TYPE_EXECUTABLE.
 L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clGetBuildInfo.html>
 =item $kernel = $program->kernel ($function_name)
 Creates an OpenCL::Kernel object out of the named C<__kernel> function in
 Calls C<clGetProgramBuildInfo> with C<OpenCL::PROGRAM_BUILD_OPTIONS> and returns the result.
 =item $string = $program->build_log ($device)
 Calls C<clGetProgramBuildInfo> with C<OpenCL::PROGRAM_BUILD_LOG> and returns the result.
+=item $binary_type = $program->binary_type ($device)
+Calls C<clGetProgramBuildInfo> with C<OpenCL::PROGRAM_BINARY_TYPE> and returns the result.
 =for gengetinfo end program_build
 =item $packed_value = $program->info ($name)
 This is a subclass of OpenCL::Mapped, representing mapped images.
 =over 4
+=item $pixels = $mapped->width
+=item $pixels = $mapped->height
+=item $pixels = $mapped->depth
+Return the width/height/depth of the mapped image region, in pixels.
 =item $bytes = $mapped->row_pitch
 =item $bytes = $mapped->slice_pitch
 Return the row or slice pitch of the image that has been mapped.
+=item $bytes = $mapped->element_size
+Return the size of a single pixel.
+=item $data = $mapped->get_row ($count, $x=0, $y=0, $z=0)
+Return C<$count> pixels from the given coordinates. The pixel data must
+be completely contained within a single row.
+If C<$count> is C<undef>, then all the remaining pixels in that row are
+returned.
+=item $mapped->set_row ($data, $x=0, $y=0, $z=0)
+Write the given pixel data at the given coordinate. The pixel data must
+be completely contained within a single row.
 =back
 =cut
 1;

Diff Legend

-–
+Removed lines
-+
+Added lines
-<
+Changed lines
->
+Changed lines

Comparing OpenCL/OpenCL.pm (file contents): Revision 1.77 by root, Sat May 5 12:54:03 2012 UTC vs. Revision 1.88 by root, Tue Oct 22 17:25:38 2013 UTC

Diff Legend

Comparing OpenCL/OpenCL.pm (file contents):
Revision 1.77 by root, Sat May 5 12:54:03 2012 UTC vs.
Revision 1.88 by root, Tue Oct 22 17:25:38 2013 UTC