OpenCL/OpenCL.pm

=head1 NAME

OpenCL - Open Computing Language Bindings

=head1 SYNOPSIS

 use OpenCL;

=head1 DESCRIPTION

This is an early release which might be useful, but hasn't seen much testing.

=head1 HELPFUL RESOURCES

The OpenCL spec used to develop this module (1.2 spec was available, but
no implementation was available to me :).

   http://www.khronos.org/registry/cl/specs/opencl-1.1.pdf

OpenCL manpages:

   http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/

=head1 EXAMPLES

=head2 Enumerate all devices and get contexts for them.

   for my $platform (OpenCL::platforms) {
      warn $platform->info (OpenCL::PLATFORM_NAME);
      warn $platform->info (OpenCL::PLATFORM_EXTENSIONS);
      for my $device ($platform->devices) {
         warn $device->info (OpenCL::DEVICE_NAME);
         my $ctx = $device->context_simple;
         # do stuff
      }
   }

=head2 Get a useful context and a command queue.

   my $dev = ((OpenCL::platforms)[0]->devices)[0];
   my $ctx = $dev->context_simple;
   my $queue = $ctx->command_queue_simple ($dev);

=head2 Print all supported image formats of a context.

   for my $type (OpenCL::MEM_OBJECT_IMAGE2D, OpenCL::MEM_OBJECT_IMAGE3D) {
      say "supported image formats for ", OpenCL::enum2str $type;
      
      for my $f ($ctx->supported_image_formats (0, $type)) {
         printf "  %-10s %-20s\n", OpenCL::enum2str $f->[0], OpenCL::enum2str $f->[1];
      }
   }

=head2 Create a buffer with some predefined data, read it back synchronously,
then asynchronously.

   my $buf = $ctx->buffer_sv (OpenCL::MEM_COPY_HOST_PTR, "helmut");

   $queue->enqueue_read_buffer ($buf, 1, 1, 3, my $data);
   warn $data;

   my $ev = $queue->enqueue_read_buffer ($buf, 0, 1, 3, my $data);
   $ev->wait;
   warn $data;

=head2 Create and build a program, then create a kernel out of one of its
functions.

   my $src = '
      __kernel void
      squareit (__global float *input, __global float *output)
      {
        size_t id = get_global_id (0);
        output [id] = input [id] * input [id];
      }
   ';

   my $prog = $ctx->program_with_source ($src);

   eval { $prog->build ($dev); 1 }
      or die $prog->build_info ($dev, OpenCL::PROGRAM_BUILD_LOG);

   my $kernel = $prog->kernel ("squareit");

=head2 Create some input and output float buffers, then call squareit on them.

   my $input  = $ctx->buffer_sv (OpenCL::MEM_COPY_HOST_PTR, pack "f*", 1, 2, 3, 4.5);
   my $output = $ctx->buffer (0, OpenCL::SIZEOF_FLOAT * 5);

   # set buffer
   $kernel->set_buffer (0, $input);
   $kernel->set_buffer (1, $output);

   # execute it for all 4 numbers
   $queue->enqueue_nd_range_kernel ($kernel, undef, [4], undef);

   # enqueue a synchronous read
   $queue->enqueue_read_buffer ($output, 1, 0, OpenCL::SIZEOF_FLOAT * 4, my $data);

   # print the results:
   say join ", ", unpack "f*", $data;

=head2 The same enqueue operations as before, but assuming an out-of-order queue,
showing off barriers.

   # execute it for all 4 numbers
   $queue->enqueue_nd_range_kernel ($kernel, undef, [4], undef);

   # enqueue a barrier to ensure in-order execution
   $queue->enqueue_barrier;

   # enqueue an async read
   $queue->enqueue_read_buffer ($output, 0, 0, OpenCL::SIZEOF_FLOAT * 4, my $data);

   # wait for all requests to finish
   $queue->finish;

=head2 The same enqueue operations as before, but assuming an out-of-order queue,
showing off event objects and wait lists.

   # execute it for all 4 numbers
   my $ev = $queue->enqueue_nd_range_kernel ($kernel, undef, [4], undef);

   # enqueue an async read
   $ev = $queue->enqueue_read_buffer ($output, 0, 0, OpenCL::SIZEOF_FLOAT * 4, my $data, $ev);

   # wait for the last event to complete
   $ev->wait;

=head1 DOCUMENTATION

=head2 BASIC CONVENTIONS

This is not a 1:1 C-style translation of OpenCL to Perl - instead I
attempted to make the interface as type-safe as possible and introducing
object syntax where it makes sense. There are a number of important
differences between the OpenCL C API and this module:

=over 4

=item * Object lifetime managament is automatic - there is no need
to free objects explicitly (C<clReleaseXXX>), the release function
is called automatically once all Perl references to it go away.

=item * OpenCL uses CamelCase for function names (C<clGetPlatformInfo>),
while this module uses underscores as word separator and often leaves out
prefixes (C<< $platform->info >>).

=item * OpenCL often specifies fixed vector function arguments as short
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 * When enqueuing commands, the wait list is specified by adding
extra arguments to the function - everywhere 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
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
other status is returned the function will throw an exception, so you
don't normally have to to any error checking.

=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

=item $int = OpenCL::errno

The last error returned by a function - it's only changed on errors.

=item $str = OpenCL::err2str $errval

Comverts an error value into a human readable string.

=item $str = OpenCL::err2str $enum

Converts most enum values (inof parameter names, image format constants,
object types, addressing and filter modes, command types etc.) into a
human readbale 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.

=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>

=item $ctx = OpenCL::context_from_type_simple $type = OpenCL::DEVICE_TYPE_DEFAULT

Tries to create a context from a default device and platform - never worked for me.

L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clCreateContextFromType.html>

=item OpenCL::wait_for_events $wait_events...

Waits for all events to complete.

L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clWaitForEvents.html>

=back

=head2 THE OpenCL::Platform CLASS

=over 4

=item $packed_value = $platform->info ($name)

Calls C<clGetPlatformInfo> and returns the packed, raw value - for
strings, this will be the string, for other values you probably need to
use the correct C<unpack>. This might get improved in the future. Hopefully.

L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clGetPlatformInfo.html>

=item @devices = $platform->devices ($type = OpenCL::DEVICE_TYPE_ALL)

Returns a list of matching OpenCL::Device objects.

=item $ctx = $platform->context_from_type_simple ($type = OpenCL::DEVICE_TYPE_DEFAULT)

Tries to create a context. Never worked for me.

L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clCreateContextFromType.html>

=back

=head2 THE OpenCL::Device CLASS

=over 4

=item $packed_value = $device->info ($name)

See C<< $platform->info >> for details.

L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clGetDeviceInfo.html>

=item $ctx = $device->context_simple

Convenience function to create a new OpenCL::Context object.

L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clCreateContext.html>

=back

=head2 THE OpenCL::Context CLASS

=over 4

=item $packed_value = $ctx->info ($name)

See C<< $platform->info >> for details.

L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clGetContextInfo.html>

=item $queue = $ctx->command_queue_simple ($device)

Convenience function to 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>

=item $ev = $ctx->user_event

Creates a new OpenCL::UserEvent object.

L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clCreateUserEvent.html>

=item $buf = $ctx->buffer ($flags, $len)

Creates a new OpenCL::Buffer object with the given flags and octet-size.

L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clCreateBuffer.html>

=item $buf = $ctx->buffer_sv ($flags, $data)

Creates a new OpenCL::Buffer object and initialise it with the given data values.

=item $img = $ctx->image2d ($flags, $channel_order, $channel_type, $width, $height, $data)

Creates a new OpenCL::Image2D object and optionally initialises it with the given data values.

L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clCreateImage2D.html>

=item $img = $ctx->image3d ($flags, $channel_order, $channel_type, $width, $height, $depth, $slice_pitch, $data)

Creates a new OpenCL::Image3D object and optionally initialises it with the given data values.

L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clCreateImage3D.html>

=item @formats = $ctx->supported_image_formats ($flags, $image_type)

Returns a list of matching image formats - each format is an arrayref with
two values, $channel_order and $channel_type, in it.

L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clGetSupportedImageFormats.html>

=item $sampler = $ctx->sampler ($normalized_coords, $addressing_mode, $filter_mode)

Creates a new OpenCL::Sampler object.

L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clCreateSampler.html>

=item $program = $ctx->program_with_source ($string)

Creates a new OpenCL::Program object from the given source code.

L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clCreateProgramWithSource.html>

=back

=head2 THE OpenCL::Queue CLASS

An OpenCL::Queue represents an execution queue for OpenCL. You execute
requests by calling their respective C<enqueue_xxx> method and waitinf for
it to complete in some way.

All the enqueue methods return an event object that can be used to wait
for completion, unless the method is called in void context, in which case
no event object is created.

They also allow you to specify any number of other event objects that this
request has to wait for before it starts executing, by simply passing the
event objects as extra parameters to the enqueue methods.

Queues execute in-order by default, without any parallelism, so in most
cases (i.e. you use only one queue) it's not necessary to wait for or
create event objects.

=over 4

=item $packed_value = $ctx->info ($name)

See C<< $platform->info >> for details.

L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clGetCommandQueueInfo.html>

=item $ev = $queue->enqueue_read_buffer ($buffer, $blocking, $offset, $len, $data, $wait_events...)

Reads data from buffer into the given string.

L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clEnqueueReadBuffer.html>

=item $ev = $queue->enqueue_write_buffer ($buffer, $blocking, $offset, $data, $wait_events...)

Writes data to buffer from the given string.

L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clEnqueueWriteBuffer.html>

=item $ev = $queue->enqueue_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->enqueue_read_image ($src, $blocking, $x, $y, $z, $width, $height, $depth, $row_pitch, $slice_pitch, $data, $wait_events...)

L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clEnqueueReadImage.html>

=item $ev = $queue->enqueue_write_image ($src, $blocking, $x, $y, $z, $width, $height, $depth, $row_pitch, $data, $wait_events...)

L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clEnqueueWriteImage.html>

=item $ev = $queue->enqueue_copy_buffer_rect ($src, $dst, $src_x, $src_y, $src_z, $dst_x, $dst_y, $dst_z, $width, $height, $depth, $src_row_pitch, $src_slice_pitch, 4dst_row_pitch, $dst_slice_pitch, $ait_event...)

Yeah.

L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clEnqueueCopyBufferRect.html>

=item $ev = $queue->enqueue_copy_buffer_to_image (OpenCL::Buffer src, OpenCL::Image dst, size_t src_offset, size_t dst_x, size_t dst_y, size_t dst_z, size_t width, size_t height, size_t depth, ...)

L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clEnqueueCopyBufferToImage.html>.

=item $ev = $queue->enqueue_copy_image (OpenCL::Image src, OpenCL::Buffer dst, size_t src_x, size_t src_y, size_t src_z, size_t dst_x, size_t dst_y, size_t dst_z, size_t width, size_t height, size_t depth, ...)

L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clEnqueueCopyImage.html>

=item $ev = $queue->enqueue_copy_image_to_buffer (OpenCL::Image src, OpenCL::Buffer dst, size_t src_x, size_t src_y, size_t src_z, size_t width, size_t height, size_t depth, size_t dst_offset, ...)

L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clEnqueueCopyImageToBuffer.html>

=item $ev = $queue->enqueue_task ($kernel, $wait_events...)

L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clEnqueueTask.html>

=item $ev = $queue->enqueue_nd_range_kernel ($kernel, @$global_work_offset, @$global_work_size, @$local_work_size, $wait_events...)

Enqueues a kernel execution.

@$global_work_size must be specified as a reference to an array of
integers specifying the work sizes (element counts).

@$global_work_offset must be either C<undef> (in which case all offsets
are C<0>), or a reference to an array of work offsets, with the same number
of elements as @$global_work_size.

@$local_work_size must be either C<undef> (in which case the
implementation is supposed to choose good local work sizes), or a
reference to an array of local work sizes, with the same number of
elements as @$global_work_size.

L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clEnqueueNDRangeKernel.html>

=item $ev = $queue->enqueue_marker

L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clEnqueueMarker.html>

=item $ev = $queue->enqueue_wait_for_events ($wait_events...)

L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clEnqueueWaitForEvents.html>

=item $queue->enqueue_barrier

L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clEnqueueBarrier.html>

=item $queue->flush

L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clFlush.html>

=item $queue->finish

L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clFinish.html>

=back

=head2 THE OpenCL::Memory CLASS

This the superclass of all memory objects - OpenCL::Buffer, OpenCL::Image,
OpenCL::Image2D and OpenCL::Image3D. The subclasses of this class
currently only exist to allow type-checking.

=over 4

=item $packed_value = $memory->info ($name)

See C<< $platform->info >> for details.

L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clGetMemObjectInfo.html>

=back

=head2 THE OpenCL::Sampler CLASS

=over 4

=item $packed_value = $sampler->info ($name)

See C<< $platform->info >> for details.

L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clGetSamplerInfo.html>

=back

=head2 THE OpenCL::Program CLASS

=over 4

=item $packed_value = $program->info ($name)

See C<< $platform->info >> for details.

L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clGetProgramInfo.html>

=item $program->build ($device, $options = "")

Tries to build the program with the givne options.

L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clBuildProgram.html>

=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.

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
the program.

L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clCreateKernel.html>

=back

=head2 THE OpenCL::Kernel CLASS

=over 4

=item $packed_value = $kernel->info ($name)

See C<< $platform->info >> for details.

L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clGetKernelInfo.html>

=item $kernel->set_TYPE ($index, $value)

This is a family of methods to set the kernel argument with the number C<$index> to the give C<$value>.

TYPE is one of C<char>, C<uchar>, C<short>, C<ushort>, C<int>, C<uint>,
C<long>, C<ulong>, C<half>, C<float>, C<double>, C<memory>, C<buffer>,
C<image2d>, C<image3d>, C<sampler> or C<event>.

Chars and integers (including the half type) are specified as integers,
float and double as floating point values, memory/buffer/image2d/image3d
must be an object of that type or C<undef>, and sampler and event must be
objects of that type.

L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clSetKernelArg.html>

=back

=head2 THE OpenCL::Event CLASS

This is the superclass for all event objects (including OpenCL::UserEvent
objects).

=over 4

=item $packed_value = $ev->info ($name)

See C<< $platform->info >> for details.

L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clGetEventInfo.html>

=item $ev->wait

Waits for the event to complete.

L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clWaitForEvents.html>

=back

=head2 THE OpenCL::UserEvent CLASS

This is a subclass of OpenCL::Event.

=over 4

=item $ev->set_status ($execution_status)

L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clSetUserEventStatus.html>

=back

=cut

package OpenCL;

use common::sense;

BEGIN {
   our $VERSION = '0.03';

   require XSLoader;
   XSLoader::load (__PACKAGE__, $VERSION);

   @OpenCL::Buffer::ISA    =
   @OpenCL::Image::ISA     = OpenCL::Memory::;

   @OpenCL::Image2D::ISA   =
   @OpenCL::Image3D::ISA   = OpenCL::Image::;

   @OpenCL::UserEvent::ISA = OpenCL::Event::;
}

1;

=head1 AUTHOR

 Marc Lehmann <schmorp@schmorp.de>
 http://home.schmorp.de/

=cut

Revision:	1.8
Committed:	Wed Nov 16 06:22:20 2011 UTC (12 years, 6 months ago) by root
Branch:	MAIN
Changes since 1.7:	+13 -13 lines
Log Message:	* empty log message *
#	User	Rev	Content
1	root	1.1	=head1 NAME
2
3	root	1.5	OpenCL - Open Computing Language Bindings
4	root	1.1
5			=head1 SYNOPSIS
6
7			use OpenCL;
8
9			=head1 DESCRIPTION
10
11	root	1.7	This is an early release which might be useful, but hasn't seen much testing.
12	root	1.1
13	root	1.3	=head1 HELPFUL RESOURCES
14
15	root	1.5	The OpenCL spec used to develop this module (1.2 spec was available, but
16	root	1.3	no implementation was available to me :).
17
18			http://www.khronos.org/registry/cl/specs/opencl-1.1.pdf
19
20			OpenCL manpages:
21
22			http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/
23
24			=head1 EXAMPLES
25
26	root	1.5	=head2 Enumerate all devices and get contexts for them.
27	root	1.1
28			for my $platform (OpenCL::platforms) {
29			warn $platform->info (OpenCL::PLATFORM_NAME);
30			warn $platform->info (OpenCL::PLATFORM_EXTENSIONS);
31			for my $device ($platform->devices) {
32			warn $device->info (OpenCL::DEVICE_NAME);
33			my $ctx = $device->context_simple;
34			# do stuff
35			}
36			}
37
38	root	1.5	=head2 Get a useful context and a command queue.
39	root	1.1
40			my $dev = ((OpenCL::platforms)[0]->devices)[0];
41			my $ctx = $dev->context_simple;
42			my $queue = $ctx->command_queue_simple ($dev);
43
44	root	1.5	=head2 Print all supported image formats of a context.
45
46			for my $type (OpenCL::MEM_OBJECT_IMAGE2D, OpenCL::MEM_OBJECT_IMAGE3D) {
47			say "supported image formats for ", OpenCL::enum2str $type;
48
49			for my $f ($ctx->supported_image_formats (0, $type)) {
50			printf " %-10s %-20s\n", OpenCL::enum2str $f->[0], OpenCL::enum2str $f->[1];
51			}
52			}
53
54			=head2 Create a buffer with some predefined data, read it back synchronously,
55			then asynchronously.
56	root	1.3
57			my $buf = $ctx->buffer_sv (OpenCL::MEM_COPY_HOST_PTR, "helmut");
58
59			$queue->enqueue_read_buffer ($buf, 1, 1, 3, my $data);
60			warn $data;
61
62			my $ev = $queue->enqueue_read_buffer ($buf, 0, 1, 3, my $data);
63			$ev->wait;
64			warn $data;
65
66	root	1.5	=head2 Create and build a program, then create a kernel out of one of its
67			functions.
68	root	1.3
69			my $src = '
70			__kernel void
71			squareit (__global float input, __global float output)
72			{
73			size_t id = get_global_id (0);
74			output [id] = input [id] * input [id];
75			}
76			';
77
78			my $prog = $ctx->program_with_source ($src);
79
80			eval { $prog->build ($dev); 1 }
81			or die $prog->build_info ($dev, OpenCL::PROGRAM_BUILD_LOG);
82
83			my $kernel = $prog->kernel ("squareit");
84
85	root	1.5	=head2 Create some input and output float buffers, then call squareit on them.
86	root	1.4
87			my $input = $ctx->buffer_sv (OpenCL::MEM_COPY_HOST_PTR, pack "f*", 1, 2, 3, 4.5);
88			my $output = $ctx->buffer (0, OpenCL::SIZEOF_FLOAT * 5);
89
90			# set buffer
91			$kernel->set_buffer (0, $input);
92			$kernel->set_buffer (1, $output);
93
94			# execute it for all 4 numbers
95			$queue->enqueue_nd_range_kernel ($kernel, undef, [4], undef);
96
97	root	1.5	# enqueue a synchronous read
98			$queue->enqueue_read_buffer ($output, 1, 0, OpenCL::SIZEOF_FLOAT * 4, my $data);
99
100			# print the results:
101			say join ", ", unpack "f*", $data;
102
103			=head2 The same enqueue operations as before, but assuming an out-of-order queue,
104			showing off barriers.
105
106			# execute it for all 4 numbers
107			$queue->enqueue_nd_range_kernel ($kernel, undef, [4], undef);
108
109			# enqueue a barrier to ensure in-order execution
110	root	1.4	$queue->enqueue_barrier;
111
112	root	1.5	# enqueue an async read
113			$queue->enqueue_read_buffer ($output, 0, 0, OpenCL::SIZEOF_FLOAT * 4, my $data);
114
115			# wait for all requests to finish
116			$queue->finish;
117
118			=head2 The same enqueue operations as before, but assuming an out-of-order queue,
119			showing off event objects and wait lists.
120
121			# execute it for all 4 numbers
122			my $ev = $queue->enqueue_nd_range_kernel ($kernel, undef, [4], undef);
123
124			# enqueue an async read
125			$ev = $queue->enqueue_read_buffer ($output, 0, 0, OpenCL::SIZEOF_FLOAT * 4, my $data, $ev);
126
127			# wait for the last event to complete
128	root	1.4	$ev->wait;
129
130	root	1.5	=head1 DOCUMENTATION
131
132			=head2 BASIC CONVENTIONS
133
134			This is not a 1:1 C-style translation of OpenCL to Perl - instead I
135			attempted to make the interface as type-safe as possible and introducing
136			object syntax where it makes sense. There are a number of important
137			differences between the OpenCL C API and this module:
138
139			=over 4
140
141			=item * Object lifetime managament is automatic - there is no need
142			to free objects explicitly (C<clReleaseXXX>), the release function
143			is called automatically once all Perl references to it go away.
144
145			=item * OpenCL uses CamelCase for function names (C<clGetPlatformInfo>),
146			while this module uses underscores as word separator and often leaves out
147			prefixes (C<< $platform->info >>).
148
149			=item * OpenCL often specifies fixed vector function arguments as short
150			arrays (C<size_t origin[3]>), while this module explicitly expects the
151			components as separate arguments-
152
153			=item * Where possible, the row_pitch value is calculated from the perl
154			scalar length and need not be specified.
155
156			=item * When enqueuing commands, the wait list is specified by adding
157			extra arguments to the function - everywhere a C<$wait_events...> argument
158			is documented this can be any number of event objects.
159
160			=item * When enqueuing commands, if the enqueue method is called in void
161			context, no event is created. In all other contexts an event is returned
162			by the method.
163
164			=item * This module expects all functions to return C<CL_SUCCESS>. If any
165			other status is returned the function will throw an exception, so you
166			don't normally have to to any error checking.
167
168			=back
169
170	root	1.7	=head2 PERL AND OPENCL TYPES
171
172	root	1.8	This handy(?) table lists OpenCL types and their perl, PDL and pack/unpack
173	root	1.7	format equivalents:
174
175	root	1.8	OpenCL perl PDL pack/unpack
176			char IV - c
177			uchar IV byte C
178			short IV short s
179			ushort IV ushort S
180			int IV long? l
181			uint IV - L
182			long IV longlong q
183			ulong IV - Q
184			float NV float f
185			half IV ushort S
186			double NV double d
187	root	1.7
188	root	1.5	=head2 THE OpenCL PACKAGE
189
190			=over 4
191
192			=item $int = OpenCL::errno
193
194			The last error returned by a function - it's only changed on errors.
195
196			=item $str = OpenCL::err2str $errval
197
198			Comverts an error value into a human readable string.
199
200			=item $str = OpenCL::err2str $enum
201
202			Converts most enum values (inof parameter names, image format constants,
203			object types, addressing and filter modes, command types etc.) into a
204			human readbale string. When confronted with some random integer it can be
205			very helpful to pass it through this function to maybe get some readable
206			string out of it.
207
208			=item @platforms = OpenCL::platforms
209
210			Returns all available OpenCL::Platform objects.
211
212			L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clGetPlatformIDs.html>
213
214			=item $ctx = OpenCL::context_from_type_simple $type = OpenCL::DEVICE_TYPE_DEFAULT
215
216			Tries to create a context from a default device and platform - never worked for me.
217
218			L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clCreateContextFromType.html>
219
220			=item OpenCL::wait_for_events $wait_events...
221
222			Waits for all events to complete.
223
224			L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clWaitForEvents.html>
225
226			=back
227
228			=head2 THE OpenCL::Platform CLASS
229
230			=over 4
231
232			=item $packed_value = $platform->info ($name)
233
234			Calls C<clGetPlatformInfo> and returns the packed, raw value - for
235			strings, this will be the string, for other values you probably need to
236			use the correct C<unpack>. This might get improved in the future. Hopefully.
237
238			L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clGetPlatformInfo.html>
239
240			=item @devices = $platform->devices ($type = OpenCL::DEVICE_TYPE_ALL)
241
242			Returns a list of matching OpenCL::Device objects.
243
244			=item $ctx = $platform->context_from_type_simple ($type = OpenCL::DEVICE_TYPE_DEFAULT)
245
246			Tries to create a context. Never worked for me.
247
248			L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clCreateContextFromType.html>
249
250			=back
251
252			=head2 THE OpenCL::Device CLASS
253
254			=over 4
255
256			=item $packed_value = $device->info ($name)
257
258			See C<< $platform->info >> for details.
259
260			L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clGetDeviceInfo.html>
261
262			=item $ctx = $device->context_simple
263
264			Convenience function to create a new OpenCL::Context object.
265
266			L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clCreateContext.html>
267
268			=back
269
270			=head2 THE OpenCL::Context CLASS
271
272			=over 4
273
274			=item $packed_value = $ctx->info ($name)
275
276			See C<< $platform->info >> for details.
277
278			L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clGetContextInfo.html>
279
280			=item $queue = $ctx->command_queue_simple ($device)
281
282			Convenience function to create a new OpenCL::Queue object from the context and the given device.
283
284			L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clCreateCommandQueue.html>
285
286			=item $ev = $ctx->user_event
287
288			Creates a new OpenCL::UserEvent object.
289
290			L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clCreateUserEvent.html>
291
292			=item $buf = $ctx->buffer ($flags, $len)
293
294			Creates a new OpenCL::Buffer object with the given flags and octet-size.
295
296			L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clCreateBuffer.html>
297
298			=item $buf = $ctx->buffer_sv ($flags, $data)
299
300			Creates a new OpenCL::Buffer object and initialise it with the given data values.
301
302			=item $img = $ctx->image2d ($flags, $channel_order, $channel_type, $width, $height, $data)
303
304			Creates a new OpenCL::Image2D object and optionally initialises it with the given data values.
305
306			L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clCreateImage2D.html>
307
308			=item $img = $ctx->image3d ($flags, $channel_order, $channel_type, $width, $height, $depth, $slice_pitch, $data)
309
310			Creates a new OpenCL::Image3D object and optionally initialises it with the given data values.
311
312			L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clCreateImage3D.html>
313
314			=item @formats = $ctx->supported_image_formats ($flags, $image_type)
315
316			Returns a list of matching image formats - each format is an arrayref with
317			two values, $channel_order and $channel_type, in it.
318
319			L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clGetSupportedImageFormats.html>
320
321			=item $sampler = $ctx->sampler ($normalized_coords, $addressing_mode, $filter_mode)
322
323			Creates a new OpenCL::Sampler object.
324
325			L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clCreateSampler.html>
326
327			=item $program = $ctx->program_with_source ($string)
328
329			Creates a new OpenCL::Program object from the given source code.
330
331			L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clCreateProgramWithSource.html>
332
333			=back
334
335			=head2 THE OpenCL::Queue CLASS
336
337			An OpenCL::Queue represents an execution queue for OpenCL. You execute
338			requests by calling their respective C<enqueue_xxx> method and waitinf for
339			it to complete in some way.
340
341			All the enqueue methods return an event object that can be used to wait
342			for completion, unless the method is called in void context, in which case
343			no event object is created.
344
345			They also allow you to specify any number of other event objects that this
346			request has to wait for before it starts executing, by simply passing the
347			event objects as extra parameters to the enqueue methods.
348
349			Queues execute in-order by default, without any parallelism, so in most
350	root	1.6	cases (i.e. you use only one queue) it's not necessary to wait for or
351			create event objects.
352	root	1.5
353			=over 4
354
355			=item $packed_value = $ctx->info ($name)
356
357			See C<< $platform->info >> for details.
358
359			L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clGetCommandQueueInfo.html>
360
361			=item $ev = $queue->enqueue_read_buffer ($buffer, $blocking, $offset, $len, $data, $wait_events...)
362
363			Reads data from buffer into the given string.
364
365			L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clEnqueueReadBuffer.html>
366
367			=item $ev = $queue->enqueue_write_buffer ($buffer, $blocking, $offset, $data, $wait_events...)
368
369			Writes data to buffer from the given string.
370
371			L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clEnqueueWriteBuffer.html>
372
373			=item $ev = $queue->enqueue_copy_buffer ($src, $dst, $src_offset, $dst_offset, $len, $wait_events...)
374
375			L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clEnqueueCopyBuffer.html>
376
377			=item $ev = $queue->enqueue_read_image ($src, $blocking, $x, $y, $z, $width, $height, $depth, $row_pitch, $slice_pitch, $data, $wait_events...)
378
379			L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clEnqueueReadImage.html>
380
381			=item $ev = $queue->enqueue_write_image ($src, $blocking, $x, $y, $z, $width, $height, $depth, $row_pitch, $data, $wait_events...)
382
383			L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clEnqueueWriteImage.html>
384
385			=item $ev = $queue->enqueue_copy_buffer_rect ($src, $dst, $src_x, $src_y, $src_z, $dst_x, $dst_y, $dst_z, $width, $height, $depth, $src_row_pitch, $src_slice_pitch, 4dst_row_pitch, $dst_slice_pitch, $ait_event...)
386
387			Yeah.
388
389			L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clEnqueueCopyBufferRect.html>
390
391			=item $ev = $queue->enqueue_copy_buffer_to_image (OpenCL::Buffer src, OpenCL::Image dst, size_t src_offset, size_t dst_x, size_t dst_y, size_t dst_z, size_t width, size_t height, size_t depth, ...)
392
393			L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clEnqueueCopyBufferToImage.html>.
394
395			=item $ev = $queue->enqueue_copy_image (OpenCL::Image src, OpenCL::Buffer dst, size_t src_x, size_t src_y, size_t src_z, size_t dst_x, size_t dst_y, size_t dst_z, size_t width, size_t height, size_t depth, ...)
396
397			L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clEnqueueCopyImage.html>
398
399			=item $ev = $queue->enqueue_copy_image_to_buffer (OpenCL::Image src, OpenCL::Buffer dst, size_t src_x, size_t src_y, size_t src_z, size_t width, size_t height, size_t depth, size_t dst_offset, ...)
400
401			L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clEnqueueCopyImageToBuffer.html>
402
403			=item $ev = $queue->enqueue_task ($kernel, $wait_events...)
404
405			L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clEnqueueTask.html>
406
407			=item $ev = $queue->enqueue_nd_range_kernel ($kernel, @$global_work_offset, @$global_work_size, @$local_work_size, $wait_events...)
408
409			Enqueues a kernel execution.
410
411			@$global_work_size must be specified as a reference to an array of
412			integers specifying the work sizes (element counts).
413
414			@$global_work_offset must be either C<undef> (in which case all offsets
415			are C<0>), or a reference to an array of work offsets, with the same number
416			of elements as @$global_work_size.
417
418			@$local_work_size must be either C<undef> (in which case the
419			implementation is supposed to choose good local work sizes), or a
420			reference to an array of local work sizes, with the same number of
421			elements as @$global_work_size.
422
423			L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clEnqueueNDRangeKernel.html>
424
425			=item $ev = $queue->enqueue_marker
426
427			L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clEnqueueMarker.html>
428
429			=item $ev = $queue->enqueue_wait_for_events ($wait_events...)
430
431			L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clEnqueueWaitForEvents.html>
432
433			=item $queue->enqueue_barrier
434
435			L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clEnqueueBarrier.html>
436
437			=item $queue->flush
438
439			L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clFlush.html>
440
441			=item $queue->finish
442
443			L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clFinish.html>
444
445			=back
446
447			=head2 THE OpenCL::Memory CLASS
448
449			This the superclass of all memory objects - OpenCL::Buffer, OpenCL::Image,
450			OpenCL::Image2D and OpenCL::Image3D. The subclasses of this class
451			currently only exist to allow type-checking.
452
453			=over 4
454
455			=item $packed_value = $memory->info ($name)
456
457			See C<< $platform->info >> for details.
458
459			L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clGetMemObjectInfo.html>
460
461			=back
462
463			=head2 THE OpenCL::Sampler CLASS
464
465			=over 4
466
467			=item $packed_value = $sampler->info ($name)
468
469			See C<< $platform->info >> for details.
470
471			L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clGetSamplerInfo.html>
472
473			=back
474
475			=head2 THE OpenCL::Program CLASS
476
477			=over 4
478
479			=item $packed_value = $program->info ($name)
480
481			See C<< $platform->info >> for details.
482
483			L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clGetProgramInfo.html>
484
485			=item $program->build ($device, $options = "")
486
487			Tries to build the program with the givne options.
488
489			L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clBuildProgram.html>
490
491			=item $packed_value = $program->build_info ($device, $name)
492
493			Similar to C<< $platform->info >>, but returns build info for a previous
494			build attempt for the given device.
495
496			L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clGetBuildInfo.html>
497
498			=item $kernel = $program->kernel ($function_name)
499
500			Creates an OpenCL::Kernel object out of the named C<__kernel> function in
501			the program.
502
503			L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clCreateKernel.html>
504
505			=back
506
507			=head2 THE OpenCL::Kernel CLASS
508
509			=over 4
510
511			=item $packed_value = $kernel->info ($name)
512
513			See C<< $platform->info >> for details.
514
515			L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clGetKernelInfo.html>
516
517			=item $kernel->set_TYPE ($index, $value)
518
519			This is a family of methods to set the kernel argument with the number C<$index> to the give C<$value>.
520
521			TYPE is one of C<char>, C<uchar>, C<short>, C<ushort>, C<int>, C<uint>,
522			C<long>, C<ulong>, C<half>, C<float>, C<double>, C<memory>, C<buffer>,
523			C<image2d>, C<image3d>, C<sampler> or C<event>.
524
525			Chars and integers (including the half type) are specified as integers,
526			float and double as floating point values, memory/buffer/image2d/image3d
527			must be an object of that type or C<undef>, and sampler and event must be
528			objects of that type.
529
530			L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clSetKernelArg.html>
531
532			=back
533
534			=head2 THE OpenCL::Event CLASS
535
536			This is the superclass for all event objects (including OpenCL::UserEvent
537			objects).
538
539			=over 4
540
541			=item $packed_value = $ev->info ($name)
542
543			See C<< $platform->info >> for details.
544
545			L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clGetEventInfo.html>
546
547			=item $ev->wait
548
549			Waits for the event to complete.
550
551			L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clWaitForEvents.html>
552
553			=back
554
555			=head2 THE OpenCL::UserEvent CLASS
556
557			This is a subclass of OpenCL::Event.
558	root	1.4
559	root	1.1	=over 4
560
561	root	1.5	=item $ev->set_status ($execution_status)
562
563			L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clSetUserEventStatus.html>
564
565			=back
566
567	root	1.1	=cut
568
569			package OpenCL;
570
571	root	1.2	use common::sense;
572
573	root	1.1	BEGIN {
574	root	1.5	our $VERSION = '0.03';
575	root	1.1
576			require XSLoader;
577			XSLoader::load (__PACKAGE__, $VERSION);
578	root	1.3
579	root	1.5	@OpenCL::Buffer::ISA =
580			@OpenCL::Image::ISA = OpenCL::Memory::;
581	root	1.3
582	root	1.5	@OpenCL::Image2D::ISA =
583			@OpenCL::Image3D::ISA = OpenCL::Image::;
584
585			@OpenCL::UserEvent::ISA = OpenCL::Event::;
586	root	1.1	}
587
588			1;
589
590			=head1 AUTHOR
591
592			Marc Lehmann <schmorp@schmorp.de>
593			http://home.schmorp.de/
594
595			=cut
596