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 any 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 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.6
Committed:	Wed Nov 16 00:36:40 2011 UTC (12 years, 6 months ago) by root
Branch:	MAIN
Changes since 1.5:	+2 -1 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.5	This is an early release which might be useful, but hasn't seen any 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			=head2 THE OpenCL PACKAGE
171
172			=over 4
173
174			=item $int = OpenCL::errno
175
176			The last error returned by a function - it's only changed on errors.
177
178			=item $str = OpenCL::err2str $errval
179
180			Comverts an error value into a human readable string.
181
182			=item $str = OpenCL::err2str $enum
183
184			Converts most enum values (inof parameter names, image format constants,
185			object types, addressing and filter modes, command types etc.) into a
186			human readbale string. When confronted with some random integer it can be
187			very helpful to pass it through this function to maybe get some readable
188			string out of it.
189
190			=item @platforms = OpenCL::platforms
191
192			Returns all available OpenCL::Platform objects.
193
194			L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clGetPlatformIDs.html>
195
196			=item $ctx = OpenCL::context_from_type_simple $type = OpenCL::DEVICE_TYPE_DEFAULT
197
198			Tries to create a context from a default device and platform - never worked for me.
199
200			L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clCreateContextFromType.html>
201
202			=item OpenCL::wait_for_events $wait_events...
203
204			Waits for all events to complete.
205
206			L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clWaitForEvents.html>
207
208			=back
209
210			=head2 THE OpenCL::Platform CLASS
211
212			=over 4
213
214			=item $packed_value = $platform->info ($name)
215
216			Calls C<clGetPlatformInfo> and returns the packed, raw value - for
217			strings, this will be the string, for other values you probably need to
218			use the correct C<unpack>. This might get improved in the future. Hopefully.
219
220			L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clGetPlatformInfo.html>
221
222			=item @devices = $platform->devices ($type = OpenCL::DEVICE_TYPE_ALL)
223
224			Returns a list of matching OpenCL::Device objects.
225
226			=item $ctx = $platform->context_from_type_simple ($type = OpenCL::DEVICE_TYPE_DEFAULT)
227
228			Tries to create a context. Never worked for me.
229
230			L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clCreateContextFromType.html>
231
232			=back
233
234			=head2 THE OpenCL::Device CLASS
235
236			=over 4
237
238			=item $packed_value = $device->info ($name)
239
240			See C<< $platform->info >> for details.
241
242			L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clGetDeviceInfo.html>
243
244			=item $ctx = $device->context_simple
245
246			Convenience function to create a new OpenCL::Context object.
247
248			L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clCreateContext.html>
249
250			=back
251
252			=head2 THE OpenCL::Context CLASS
253
254			=over 4
255
256			=item $packed_value = $ctx->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/clGetContextInfo.html>
261
262			=item $queue = $ctx->command_queue_simple ($device)
263
264			Convenience function to create a new OpenCL::Queue object from the context and the given device.
265
266			L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clCreateCommandQueue.html>
267
268			=item $ev = $ctx->user_event
269
270			Creates a new OpenCL::UserEvent object.
271
272			L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clCreateUserEvent.html>
273
274			=item $buf = $ctx->buffer ($flags, $len)
275
276			Creates a new OpenCL::Buffer object with the given flags and octet-size.
277
278			L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clCreateBuffer.html>
279
280			=item $buf = $ctx->buffer_sv ($flags, $data)
281
282			Creates a new OpenCL::Buffer object and initialise it with the given data values.
283
284			=item $img = $ctx->image2d ($flags, $channel_order, $channel_type, $width, $height, $data)
285
286			Creates a new OpenCL::Image2D object and optionally initialises it with the given data values.
287
288			L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clCreateImage2D.html>
289
290			=item $img = $ctx->image3d ($flags, $channel_order, $channel_type, $width, $height, $depth, $slice_pitch, $data)
291
292			Creates a new OpenCL::Image3D object and optionally initialises it with the given data values.
293
294			L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clCreateImage3D.html>
295
296			=item @formats = $ctx->supported_image_formats ($flags, $image_type)
297
298			Returns a list of matching image formats - each format is an arrayref with
299			two values, $channel_order and $channel_type, in it.
300
301			L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clGetSupportedImageFormats.html>
302
303			=item $sampler = $ctx->sampler ($normalized_coords, $addressing_mode, $filter_mode)
304
305			Creates a new OpenCL::Sampler object.
306
307			L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clCreateSampler.html>
308
309			=item $program = $ctx->program_with_source ($string)
310
311			Creates a new OpenCL::Program object from the given source code.
312
313			L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clCreateProgramWithSource.html>
314
315			=back
316
317			=head2 THE OpenCL::Queue CLASS
318
319			An OpenCL::Queue represents an execution queue for OpenCL. You execute
320			requests by calling their respective C<enqueue_xxx> method and waitinf for
321			it to complete in some way.
322
323			All the enqueue methods return an event object that can be used to wait
324			for completion, unless the method is called in void context, in which case
325			no event object is created.
326
327			They also allow you to specify any number of other event objects that this
328			request has to wait for before it starts executing, by simply passing the
329			event objects as extra parameters to the enqueue methods.
330
331			Queues execute in-order by default, without any parallelism, so in most
332	root	1.6	cases (i.e. you use only one queue) it's not necessary to wait for or
333			create event objects.
334	root	1.5
335			=over 4
336
337			=item $packed_value = $ctx->info ($name)
338
339			See C<< $platform->info >> for details.
340
341			L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clGetCommandQueueInfo.html>
342
343			=item $ev = $queue->enqueue_read_buffer ($buffer, $blocking, $offset, $len, $data, $wait_events...)
344
345			Reads data from buffer into the given string.
346
347			L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clEnqueueReadBuffer.html>
348
349			=item $ev = $queue->enqueue_write_buffer ($buffer, $blocking, $offset, $data, $wait_events...)
350
351			Writes data to buffer from the given string.
352
353			L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clEnqueueWriteBuffer.html>
354
355			=item $ev = $queue->enqueue_copy_buffer ($src, $dst, $src_offset, $dst_offset, $len, $wait_events...)
356
357			L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clEnqueueCopyBuffer.html>
358
359			=item $ev = $queue->enqueue_read_image ($src, $blocking, $x, $y, $z, $width, $height, $depth, $row_pitch, $slice_pitch, $data, $wait_events...)
360
361			L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clEnqueueReadImage.html>
362
363			=item $ev = $queue->enqueue_write_image ($src, $blocking, $x, $y, $z, $width, $height, $depth, $row_pitch, $data, $wait_events...)
364
365			L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clEnqueueWriteImage.html>
366
367			=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...)
368
369			Yeah.
370
371			L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clEnqueueCopyBufferRect.html>
372
373			=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, ...)
374
375			L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clEnqueueCopyBufferToImage.html>.
376
377			=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, ...)
378
379			L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clEnqueueCopyImage.html>
380
381			=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, ...)
382
383			L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clEnqueueCopyImageToBuffer.html>
384
385			=item $ev = $queue->enqueue_task ($kernel, $wait_events...)
386
387			L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clEnqueueTask.html>
388
389			=item $ev = $queue->enqueue_nd_range_kernel ($kernel, @$global_work_offset, @$global_work_size, @$local_work_size, $wait_events...)
390
391			Enqueues a kernel execution.
392
393			@$global_work_size must be specified as a reference to an array of
394			integers specifying the work sizes (element counts).
395
396			@$global_work_offset must be either C<undef> (in which case all offsets
397			are C<0>), or a reference to an array of work offsets, with the same number
398			of elements as @$global_work_size.
399
400			@$local_work_size must be either C<undef> (in which case the
401			implementation is supposed to choose good local work sizes), or a
402			reference to an array of local work sizes, with the same number of
403			elements as @$global_work_size.
404
405			L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clEnqueueNDRangeKernel.html>
406
407			=item $ev = $queue->enqueue_marker
408
409			L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clEnqueueMarker.html>
410
411			=item $ev = $queue->enqueue_wait_for_events ($wait_events...)
412
413			L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clEnqueueWaitForEvents.html>
414
415			=item $queue->enqueue_barrier
416
417			L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clEnqueueBarrier.html>
418
419			=item $queue->flush
420
421			L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clFlush.html>
422
423			=item $queue->finish
424
425			L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clFinish.html>
426
427			=back
428
429			=head2 THE OpenCL::Memory CLASS
430
431			This the superclass of all memory objects - OpenCL::Buffer, OpenCL::Image,
432			OpenCL::Image2D and OpenCL::Image3D. The subclasses of this class
433			currently only exist to allow type-checking.
434
435			=over 4
436
437			=item $packed_value = $memory->info ($name)
438
439			See C<< $platform->info >> for details.
440
441			L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clGetMemObjectInfo.html>
442
443			=back
444
445			=head2 THE OpenCL::Sampler CLASS
446
447			=over 4
448
449			=item $packed_value = $sampler->info ($name)
450
451			See C<< $platform->info >> for details.
452
453			L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clGetSamplerInfo.html>
454
455			=back
456
457			=head2 THE OpenCL::Program CLASS
458
459			=over 4
460
461			=item $packed_value = $program->info ($name)
462
463			See C<< $platform->info >> for details.
464
465			L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clGetProgramInfo.html>
466
467			=item $program->build ($device, $options = "")
468
469			Tries to build the program with the givne options.
470
471			L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clBuildProgram.html>
472
473			=item $packed_value = $program->build_info ($device, $name)
474
475			Similar to C<< $platform->info >>, but returns build info for a previous
476			build attempt for the given device.
477
478			L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clGetBuildInfo.html>
479
480			=item $kernel = $program->kernel ($function_name)
481
482			Creates an OpenCL::Kernel object out of the named C<__kernel> function in
483			the program.
484
485			L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clCreateKernel.html>
486
487			=back
488
489			=head2 THE OpenCL::Kernel CLASS
490
491			=over 4
492
493			=item $packed_value = $kernel->info ($name)
494
495			See C<< $platform->info >> for details.
496
497			L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clGetKernelInfo.html>
498
499			=item $kernel->set_TYPE ($index, $value)
500
501			This is a family of methods to set the kernel argument with the number C<$index> to the give C<$value>.
502
503			TYPE is one of C<char>, C<uchar>, C<short>, C<ushort>, C<int>, C<uint>,
504			C<long>, C<ulong>, C<half>, C<float>, C<double>, C<memory>, C<buffer>,
505			C<image2d>, C<image3d>, C<sampler> or C<event>.
506
507			Chars and integers (including the half type) are specified as integers,
508			float and double as floating point values, memory/buffer/image2d/image3d
509			must be an object of that type or C<undef>, and sampler and event must be
510			objects of that type.
511
512			L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clSetKernelArg.html>
513
514			=back
515
516			=head2 THE OpenCL::Event CLASS
517
518			This is the superclass for all event objects (including OpenCL::UserEvent
519			objects).
520
521			=over 4
522
523			=item $packed_value = $ev->info ($name)
524
525			See C<< $platform->info >> for details.
526
527			L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clGetEventInfo.html>
528
529			=item $ev->wait
530
531			Waits for the event to complete.
532
533			L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clWaitForEvents.html>
534
535			=back
536
537			=head2 THE OpenCL::UserEvent CLASS
538
539			This is a subclass of OpenCL::Event.
540	root	1.4
541	root	1.1	=over 4
542
543	root	1.5	=item $ev->set_status ($execution_status)
544
545			L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clSetUserEventStatus.html>
546
547			=back
548
549	root	1.1	=cut
550
551			package OpenCL;
552
553	root	1.2	use common::sense;
554
555	root	1.1	BEGIN {
556	root	1.5	our $VERSION = '0.03';
557	root	1.1
558			require XSLoader;
559			XSLoader::load (__PACKAGE__, $VERSION);
560	root	1.3
561	root	1.5	@OpenCL::Buffer::ISA =
562			@OpenCL::Image::ISA = OpenCL::Memory::;
563	root	1.3
564	root	1.5	@OpenCL::Image2D::ISA =
565			@OpenCL::Image3D::ISA = OpenCL::Image::;
566
567			@OpenCL::UserEvent::ISA = OpenCL::Event::;
568	root	1.1	}
569
570			1;
571
572			=head1 AUTHOR
573
574			Marc Lehmann <schmorp@schmorp.de>
575			http://home.schmorp.de/
576
577			=cut
578