ViewVC Help
View File | Revision Log | Show Annotations | Download File
/cvs/OpenCL/OpenCL.pm
Revision: 1.20
Committed: Sun Nov 20 01:09:48 2011 UTC (12 years, 6 months ago) by root
Branch: MAIN
Changes since 1.19: +85 -18 lines
Log Message:
*** empty log message ***

File Contents

# 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.9 =head2 OpenCL FROM 10000 FEET HEIGHT
14    
15     Here is a high level overview of OpenCL:
16    
17     First you need to find one or more OpenCL::Platforms (kind of like
18     vendors) - usually there is only one.
19    
20     Each platform gives you access to a number of OpenCL::Device objects, e.g.
21     your graphics card.
22    
23 root 1.11 From a platform and some device(s), you create an OpenCL::Context, which is
24 root 1.9 a very central object in OpenCL: Once you have a context you can create
25     most other objects:
26    
27 root 1.11 OpenCL::Program objects, which store source code and, after building for a
28     specific device ("compiling and linking"), also binary programs. For each
29     kernel function in a program you can then create an OpenCL::Kernel object
30     which represents basically a function call with argument values.
31 root 1.9
32 root 1.20 OpenCL::Memory objects of various flavours: OpenCL::Buffer objects (flat
33 root 1.16 memory areas, think arrays or structs) and OpenCL::Image objects (think 2d
34     or 3d array) for bulk data and input and output for kernels.
35 root 1.9
36     OpenCL::Sampler objects, which are kind of like texture filter modes in
37     OpenGL.
38    
39     OpenCL::Queue objects - command queues, which allow you to submit memory
40     reads, writes and copies, as well as kernel calls to your devices. They
41     also offer a variety of methods to synchronise request execution, for
42     example with barriers or OpenCL::Event objects.
43    
44     OpenCL::Event objects are used to signal when something is complete.
45    
46     =head2 HELPFUL RESOURCES
47 root 1.3
48 root 1.5 The OpenCL spec used to develop this module (1.2 spec was available, but
49 root 1.3 no implementation was available to me :).
50    
51     http://www.khronos.org/registry/cl/specs/opencl-1.1.pdf
52    
53     OpenCL manpages:
54    
55     http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/
56    
57 root 1.18 If you are into UML class diagrams, the following diagram might help - if
58     not, it will be mildly cobfusing:
59    
60     http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/classDiagram.html
61    
62 root 1.16 Here's a tutorial from AMD (very AMD-centric, too), not sure how useful it
63     is, but at least it's free of charge:
64    
65     http://developer.amd.com/zones/OpenCLZone/courses/Documents/Introduction_to_OpenCL_Programming%20Training_Guide%20%28201005%29.pdf
66    
67 root 1.18 And here's NVIDIA's OpenCL Best Practises Guide:
68 root 1.16
69 root 1.18 http://developer.download.nvidia.com/compute/cuda/3_2/toolkit/docs/OpenCL_Best_Practices_Guide.pdf
70 root 1.16
71 root 1.9 =head1 BASIC WORKFLOW
72    
73 root 1.11 To get something done, you basically have to do this once (refer to the
74     examples below for actual code, this is just a high-level description):
75 root 1.9
76 root 1.11 Find some platform (e.g. the first one) and some device(s) (e.g. the first
77     device of the platform), and create a context from those.
78 root 1.9
79 root 1.11 Create program objects from your OpenCL source code, then build (compile)
80     the programs for each device you want to run them on.
81 root 1.9
82 root 1.11 Create kernel objects for all kernels you want to use (surprisingly, these
83     are not device-specific).
84 root 1.9
85 root 1.11 Then, to execute stuff, you repeat these steps, possibly resuing or
86     sharing some buffers:
87 root 1.9
88 root 1.11 Create some input and output buffers from your context. Set these as
89     arguments to your kernel.
90    
91     Enqueue buffer writes to initialise your input buffers (when not
92     initialised at creation time).
93 root 1.9
94     Enqueue the kernel execution.
95    
96     Enqueue buffer reads for your output buffer to read results.
97    
98 root 1.3 =head1 EXAMPLES
99    
100 root 1.5 =head2 Enumerate all devices and get contexts for them.
101 root 1.1
102 root 1.11 Best run this once to get a feel for the platforms and devices in your
103     system.
104    
105 root 1.1 for my $platform (OpenCL::platforms) {
106 root 1.10 printf "platform: %s\n", $platform->info (OpenCL::PLATFORM_NAME);
107     printf "extensions: %s\n", $platform->info (OpenCL::PLATFORM_EXTENSIONS);
108 root 1.1 for my $device ($platform->devices) {
109 root 1.10 printf "+ device: %s\n", $device->info (OpenCL::DEVICE_NAME);
110     my $ctx = $device->context;
111 root 1.1 # do stuff
112     }
113     }
114    
115 root 1.5 =head2 Get a useful context and a command queue.
116 root 1.1
117 root 1.11 This is a useful boilerplate for any OpenCL program that only wants to use
118     one device,
119    
120     my ($platform) = OpenCL::platforms; # find first platform
121     my ($dev) = $platform->devices; # find first device of platform
122     my $ctx = $platform->context (undef, [$dev]); # create context out of those
123     my $queue = $ctx->queue ($dev); # create a command queue for the device
124 root 1.1
125 root 1.5 =head2 Print all supported image formats of a context.
126    
127 root 1.11 Best run this once for your context, to see whats available and how to
128     gather information.
129    
130 root 1.5 for my $type (OpenCL::MEM_OBJECT_IMAGE2D, OpenCL::MEM_OBJECT_IMAGE3D) {
131 root 1.10 print "supported image formats for ", OpenCL::enum2str $type, "\n";
132 root 1.5
133     for my $f ($ctx->supported_image_formats (0, $type)) {
134     printf " %-10s %-20s\n", OpenCL::enum2str $f->[0], OpenCL::enum2str $f->[1];
135     }
136     }
137    
138     =head2 Create a buffer with some predefined data, read it back synchronously,
139     then asynchronously.
140 root 1.3
141     my $buf = $ctx->buffer_sv (OpenCL::MEM_COPY_HOST_PTR, "helmut");
142    
143     $queue->enqueue_read_buffer ($buf, 1, 1, 3, my $data);
144 root 1.10 print "$data\n";
145 root 1.3
146     my $ev = $queue->enqueue_read_buffer ($buf, 0, 1, 3, my $data);
147     $ev->wait;
148 root 1.10 print "$data\n"; # prints "elm"
149 root 1.3
150 root 1.5 =head2 Create and build a program, then create a kernel out of one of its
151     functions.
152 root 1.3
153     my $src = '
154     __kernel void
155     squareit (__global float *input, __global float *output)
156     {
157 root 1.15 $id = get_global_id (0);
158 root 1.3 output [id] = input [id] * input [id];
159     }
160     ';
161    
162     my $prog = $ctx->program_with_source ($src);
163    
164 root 1.11 # build croaks on compile errors, so catch it and print the compile errors
165 root 1.3 eval { $prog->build ($dev); 1 }
166     or die $prog->build_info ($dev, OpenCL::PROGRAM_BUILD_LOG);
167    
168     my $kernel = $prog->kernel ("squareit");
169    
170 root 1.11 =head2 Create some input and output float buffers, then call the
171     'squareit' kernel on them.
172 root 1.4
173     my $input = $ctx->buffer_sv (OpenCL::MEM_COPY_HOST_PTR, pack "f*", 1, 2, 3, 4.5);
174     my $output = $ctx->buffer (0, OpenCL::SIZEOF_FLOAT * 5);
175    
176     # set buffer
177     $kernel->set_buffer (0, $input);
178     $kernel->set_buffer (1, $output);
179    
180     # execute it for all 4 numbers
181     $queue->enqueue_nd_range_kernel ($kernel, undef, [4], undef);
182    
183 root 1.5 # enqueue a synchronous read
184     $queue->enqueue_read_buffer ($output, 1, 0, OpenCL::SIZEOF_FLOAT * 4, my $data);
185    
186     # print the results:
187 root 1.10 printf "%s\n", join ", ", unpack "f*", $data;
188 root 1.5
189     =head2 The same enqueue operations as before, but assuming an out-of-order queue,
190     showing off barriers.
191    
192     # execute it for all 4 numbers
193     $queue->enqueue_nd_range_kernel ($kernel, undef, [4], undef);
194    
195     # enqueue a barrier to ensure in-order execution
196 root 1.4 $queue->enqueue_barrier;
197    
198 root 1.5 # enqueue an async read
199     $queue->enqueue_read_buffer ($output, 0, 0, OpenCL::SIZEOF_FLOAT * 4, my $data);
200    
201     # wait for all requests to finish
202     $queue->finish;
203    
204     =head2 The same enqueue operations as before, but assuming an out-of-order queue,
205     showing off event objects and wait lists.
206    
207     # execute it for all 4 numbers
208     my $ev = $queue->enqueue_nd_range_kernel ($kernel, undef, [4], undef);
209    
210     # enqueue an async read
211     $ev = $queue->enqueue_read_buffer ($output, 0, 0, OpenCL::SIZEOF_FLOAT * 4, my $data, $ev);
212    
213     # wait for the last event to complete
214 root 1.4 $ev->wait;
215    
216 root 1.5 =head1 DOCUMENTATION
217    
218     =head2 BASIC CONVENTIONS
219    
220 root 1.14 This is not a one-to-one C-style translation of OpenCL to Perl - instead
221     I attempted to make the interface as type-safe as possible by introducing
222 root 1.5 object syntax where it makes sense. There are a number of important
223     differences between the OpenCL C API and this module:
224    
225     =over 4
226    
227     =item * Object lifetime managament is automatic - there is no need
228     to free objects explicitly (C<clReleaseXXX>), the release function
229     is called automatically once all Perl references to it go away.
230    
231 root 1.20 =item * OpenCL uses CamelCase for function names
232     (e.g. C<clGetPlatformIDs>, C<clGetPlatformInfo>), while this module
233     uses underscores as word separator and often leaves out prefixes
234     (C<OpenCL::platforms>, C<< $platform->info >>).
235 root 1.5
236     =item * OpenCL often specifies fixed vector function arguments as short
237 root 1.19 arrays (C<size_t origin[3]>), while this module explicitly expects the
238     components as separate arguments (C<$orig_x, $orig_y, $orig_z>) in
239     function calls.
240 root 1.5
241 root 1.19 =item * Structures are often specified by flattening out their components
242     as with short vectors, and returned as arrayrefs.
243 root 1.5
244     =item * When enqueuing commands, the wait list is specified by adding
245 root 1.9 extra arguments to the function - anywhere a C<$wait_events...> argument
246 root 1.5 is documented this can be any number of event objects.
247    
248     =item * When enqueuing commands, if the enqueue method is called in void
249     context, no event is created. In all other contexts an event is returned
250     by the method.
251    
252     =item * This module expects all functions to return C<CL_SUCCESS>. If any
253     other status is returned the function will throw an exception, so you
254     don't normally have to to any error checking.
255    
256     =back
257    
258 root 1.7 =head2 PERL AND OPENCL TYPES
259    
260 root 1.8 This handy(?) table lists OpenCL types and their perl, PDL and pack/unpack
261 root 1.7 format equivalents:
262    
263 root 1.8 OpenCL perl PDL pack/unpack
264     char IV - c
265     uchar IV byte C
266     short IV short s
267     ushort IV ushort S
268     int IV long? l
269     uint IV - L
270     long IV longlong q
271     ulong IV - Q
272     float NV float f
273     half IV ushort S
274     double NV double d
275 root 1.7
276 root 1.5 =head2 THE OpenCL PACKAGE
277    
278     =over 4
279    
280     =item $int = OpenCL::errno
281    
282 root 1.11 The last error returned by a function - it's only valid after an error occured
283     and before calling another OpenCL function.
284 root 1.5
285     =item $str = OpenCL::err2str $errval
286    
287     Comverts an error value into a human readable string.
288    
289 root 1.9 =item $str = OpenCL::enum2str $enum
290 root 1.5
291     Converts most enum values (inof parameter names, image format constants,
292     object types, addressing and filter modes, command types etc.) into a
293     human readbale string. When confronted with some random integer it can be
294     very helpful to pass it through this function to maybe get some readable
295     string out of it.
296    
297     =item @platforms = OpenCL::platforms
298    
299     Returns all available OpenCL::Platform objects.
300    
301     L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clGetPlatformIDs.html>
302    
303 root 1.10 =item $ctx = OpenCL::context_from_type $properties, $type = OpenCL::DEVICE_TYPE_DEFAULT, $notify = undef
304 root 1.5
305     Tries to create a context from a default device and platform - never worked for me.
306    
307     L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clCreateContextFromType.html>
308    
309     =item OpenCL::wait_for_events $wait_events...
310    
311     Waits for all events to complete.
312    
313     L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clWaitForEvents.html>
314    
315     =back
316    
317     =head2 THE OpenCL::Platform CLASS
318    
319     =over 4
320    
321     =item @devices = $platform->devices ($type = OpenCL::DEVICE_TYPE_ALL)
322    
323     Returns a list of matching OpenCL::Device objects.
324    
325 root 1.10 =item $ctx = $platform->context_from_type ($properties, $type = OpenCL::DEVICE_TYPE_DEFAULT, $notify = undef)
326 root 1.5
327 root 1.11 Tries to create a context. Never worked for me, and you need devices explitly anyway.
328 root 1.5
329     L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clCreateContextFromType.html>
330    
331 root 1.11 =item $ctx = $device->context ($properties = undef, @$devices, $notify = undef)
332    
333     Create a new OpenCL::Context object using the given device object(s)- a
334     CL_CONTEXT_PLATFORM property is supplied automatically.
335    
336     L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clCreateContext.html>
337    
338 root 1.20 =item $packed_value = $platform->info ($name)
339    
340     Calls C<clGetPlatformInfo> and returns the packed, raw value - for
341     strings, this will be the string, for other values you probably need to
342     use the correct C<unpack>.
343    
344     It's best to avoid this method and use one of the predefined C<get_*>
345     methods.
346    
347     L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clGetPlatformInfo.html>
348    
349     =for gengetinfo begin platform
350    
351    
352     =item $string = $platform->profile
353    
354     Calls C<clGetPlatformInfo> with C<CL_PLATFORM_PROFILE> and returns the result(s).
355    
356     =item $string = $platform->version
357    
358     Calls C<clGetPlatformInfo> with C<CL_PLATFORM_VERSION> and returns the result(s).
359    
360     =item $string = $platform->name
361    
362     Calls C<clGetPlatformInfo> with C<CL_PLATFORM_NAME> and returns the result(s).
363    
364     =item $string = $platform->vendor
365    
366     Calls C<clGetPlatformInfo> with C<CL_PLATFORM_VENDOR> and returns the result(s).
367    
368     =item $string = $platform->extensions
369    
370     Calls C<clGetPlatformInfo> with C<CL_PLATFORM_EXTENSIONS> and returns the result(s).
371     =for gengetinfo end platform
372    
373 root 1.5 =back
374    
375     =head2 THE OpenCL::Device CLASS
376    
377     =over 4
378    
379     =item $packed_value = $device->info ($name)
380    
381     See C<< $platform->info >> for details.
382    
383     L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clGetDeviceInfo.html>
384    
385     =back
386    
387     =head2 THE OpenCL::Context CLASS
388    
389     =over 4
390    
391 root 1.9 =item $queue = $ctx->queue ($device, $properties)
392 root 1.5
393 root 1.9 Create a new OpenCL::Queue object from the context and the given device.
394 root 1.5
395     L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clCreateCommandQueue.html>
396    
397     =item $ev = $ctx->user_event
398    
399     Creates a new OpenCL::UserEvent object.
400    
401     L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clCreateUserEvent.html>
402    
403     =item $buf = $ctx->buffer ($flags, $len)
404    
405     Creates a new OpenCL::Buffer object with the given flags and octet-size.
406    
407     L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clCreateBuffer.html>
408    
409     =item $buf = $ctx->buffer_sv ($flags, $data)
410    
411     Creates a new OpenCL::Buffer object and initialise it with the given data values.
412    
413 root 1.18 =item $img = $ctx->image2d ($flags, $channel_order, $channel_type, $width, $height, $row_pitch = 0, $data = undef)
414 root 1.5
415     Creates a new OpenCL::Image2D object and optionally initialises it with the given data values.
416    
417     L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clCreateImage2D.html>
418    
419 root 1.18 =item $img = $ctx->image3d ($flags, $channel_order, $channel_type, $width, $height, $depth, $row_pitch = 0, $slice_pitch = 0, $data = undef)
420 root 1.5
421     Creates a new OpenCL::Image3D object and optionally initialises it with the given data values.
422    
423     L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clCreateImage3D.html>
424    
425     =item @formats = $ctx->supported_image_formats ($flags, $image_type)
426    
427     Returns a list of matching image formats - each format is an arrayref with
428     two values, $channel_order and $channel_type, in it.
429    
430     L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clGetSupportedImageFormats.html>
431    
432     =item $sampler = $ctx->sampler ($normalized_coords, $addressing_mode, $filter_mode)
433    
434     Creates a new OpenCL::Sampler object.
435    
436     L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clCreateSampler.html>
437    
438     =item $program = $ctx->program_with_source ($string)
439    
440     Creates a new OpenCL::Program object from the given source code.
441    
442     L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clCreateProgramWithSource.html>
443    
444 root 1.20 =item $packed_value = $ctx->info ($name)
445    
446     See C<< $platform->info >> for details.
447    
448     L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clGetContextInfo.html>
449    
450     =for gengetinfo begin context
451    
452     =for gengetinfo end context
453    
454 root 1.5 =back
455    
456     =head2 THE OpenCL::Queue CLASS
457    
458     An OpenCL::Queue represents an execution queue for OpenCL. You execute
459     requests by calling their respective C<enqueue_xxx> method and waitinf for
460     it to complete in some way.
461    
462     All the enqueue methods return an event object that can be used to wait
463     for completion, unless the method is called in void context, in which case
464     no event object is created.
465    
466     They also allow you to specify any number of other event objects that this
467     request has to wait for before it starts executing, by simply passing the
468     event objects as extra parameters to the enqueue methods.
469    
470     Queues execute in-order by default, without any parallelism, so in most
471 root 1.6 cases (i.e. you use only one queue) it's not necessary to wait for or
472     create event objects.
473 root 1.5
474     =over 4
475    
476     =item $packed_value = $ctx->info ($name)
477    
478     See C<< $platform->info >> for details.
479    
480     L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clGetCommandQueueInfo.html>
481    
482     =item $ev = $queue->enqueue_read_buffer ($buffer, $blocking, $offset, $len, $data, $wait_events...)
483    
484     Reads data from buffer into the given string.
485    
486     L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clEnqueueReadBuffer.html>
487    
488     =item $ev = $queue->enqueue_write_buffer ($buffer, $blocking, $offset, $data, $wait_events...)
489    
490     Writes data to buffer from the given string.
491    
492     L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clEnqueueWriteBuffer.html>
493    
494     =item $ev = $queue->enqueue_copy_buffer ($src, $dst, $src_offset, $dst_offset, $len, $wait_events...)
495    
496     L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clEnqueueCopyBuffer.html>
497    
498     =item $ev = $queue->enqueue_read_image ($src, $blocking, $x, $y, $z, $width, $height, $depth, $row_pitch, $slice_pitch, $data, $wait_events...)
499    
500     L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clEnqueueReadImage.html>
501    
502 root 1.17 =item $ev = $queue->enqueue_write_image ($src, $blocking, $x, $y, $z, $width, $height, $depth, $row_pitch, $slice_pitch, $data, $wait_events...)
503 root 1.5
504     L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clEnqueueWriteImage.html>
505    
506 root 1.17 =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, $dst_row_pitch, $dst_slice_pitch, $wait_event...)
507 root 1.5
508     Yeah.
509    
510     L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clEnqueueCopyBufferRect.html>
511    
512 root 1.15 =item $ev = $queue->enqueue_copy_buffer_to_image ($src_buffer, $dst_image, $src_offset, $dst_x, $dst_y, $dst_z, $width, $height, $depth, $wait_events...)
513 root 1.5
514     L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clEnqueueCopyBufferToImage.html>.
515    
516 root 1.15 =item $ev = $queue->enqueue_copy_image ($src_image, $dst_image, $src_x, $src_y, $src_z, $dst_x, $dst_y, $dst_z, $width, $height, $depth, $wait_events...)
517 root 1.5
518     L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clEnqueueCopyImage.html>
519    
520 root 1.15 =item $ev = $queue->enqueue_copy_image_to_buffer ($src_image, $dst_image, $src_x, $src_y, $src_z, $width, $height, $depth, $dst_offset, $wait_events...)
521 root 1.5
522     L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clEnqueueCopyImageToBuffer.html>
523    
524     =item $ev = $queue->enqueue_task ($kernel, $wait_events...)
525    
526     L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clEnqueueTask.html>
527    
528     =item $ev = $queue->enqueue_nd_range_kernel ($kernel, @$global_work_offset, @$global_work_size, @$local_work_size, $wait_events...)
529    
530     Enqueues a kernel execution.
531    
532     @$global_work_size must be specified as a reference to an array of
533     integers specifying the work sizes (element counts).
534    
535     @$global_work_offset must be either C<undef> (in which case all offsets
536     are C<0>), or a reference to an array of work offsets, with the same number
537     of elements as @$global_work_size.
538    
539     @$local_work_size must be either C<undef> (in which case the
540     implementation is supposed to choose good local work sizes), or a
541     reference to an array of local work sizes, with the same number of
542     elements as @$global_work_size.
543    
544     L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clEnqueueNDRangeKernel.html>
545    
546     =item $ev = $queue->enqueue_marker
547    
548     L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clEnqueueMarker.html>
549    
550     =item $ev = $queue->enqueue_wait_for_events ($wait_events...)
551    
552     L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clEnqueueWaitForEvents.html>
553    
554     =item $queue->enqueue_barrier
555    
556     L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clEnqueueBarrier.html>
557    
558     =item $queue->flush
559    
560     L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clFlush.html>
561    
562     =item $queue->finish
563    
564     L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clFinish.html>
565    
566     =back
567    
568     =head2 THE OpenCL::Memory CLASS
569    
570     This the superclass of all memory objects - OpenCL::Buffer, OpenCL::Image,
571     OpenCL::Image2D and OpenCL::Image3D. The subclasses of this class
572     currently only exist to allow type-checking.
573    
574     =over 4
575    
576     =item $packed_value = $memory->info ($name)
577    
578     See C<< $platform->info >> for details.
579    
580     L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clGetMemObjectInfo.html>
581    
582     =back
583    
584 root 1.20 =head2 THE OpenCL::Image CLASS
585    
586     This is the superclass of all image objects - OpenCL::Image2D and OpenCL::Image3D.
587    
588     =over 4
589    
590     =item $packed_value = $ev->image_info ($name)
591    
592     See C<< $platform->info >> for details.
593    
594     The reason this method is not called C<info> is that there already is an
595     C<< ->info >> method inherited from C<OpenCL::Memory>.
596    
597     L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clGetImageInfo.html>
598    
599     =back
600    
601 root 1.5 =head2 THE OpenCL::Sampler CLASS
602    
603     =over 4
604    
605     =item $packed_value = $sampler->info ($name)
606    
607     See C<< $platform->info >> for details.
608    
609     L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clGetSamplerInfo.html>
610    
611     =back
612    
613     =head2 THE OpenCL::Program CLASS
614    
615     =over 4
616    
617     =item $packed_value = $program->info ($name)
618    
619     See C<< $platform->info >> for details.
620    
621     L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clGetProgramInfo.html>
622    
623     =item $program->build ($device, $options = "")
624    
625     Tries to build the program with the givne options.
626    
627     L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clBuildProgram.html>
628    
629     =item $packed_value = $program->build_info ($device, $name)
630    
631     Similar to C<< $platform->info >>, but returns build info for a previous
632     build attempt for the given device.
633    
634     L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clGetBuildInfo.html>
635    
636     =item $kernel = $program->kernel ($function_name)
637    
638     Creates an OpenCL::Kernel object out of the named C<__kernel> function in
639     the program.
640    
641     L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clCreateKernel.html>
642    
643     =back
644    
645     =head2 THE OpenCL::Kernel CLASS
646    
647     =over 4
648    
649     =item $packed_value = $kernel->info ($name)
650    
651     See C<< $platform->info >> for details.
652    
653     L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clGetKernelInfo.html>
654    
655 root 1.20 =item $packed_value = $kernel->work_group_info ($device, $name)
656    
657     See C<< $platform->info >> for details.
658    
659     The reason this method is not called C<info> is that there already is an
660     C<< ->info >> method.
661    
662     L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clGetKernelWorkGroupInfo.html>
663    
664 root 1.5 =item $kernel->set_TYPE ($index, $value)
665    
666     This is a family of methods to set the kernel argument with the number C<$index> to the give C<$value>.
667    
668     TYPE is one of C<char>, C<uchar>, C<short>, C<ushort>, C<int>, C<uint>,
669     C<long>, C<ulong>, C<half>, C<float>, C<double>, C<memory>, C<buffer>,
670     C<image2d>, C<image3d>, C<sampler> or C<event>.
671    
672     Chars and integers (including the half type) are specified as integers,
673     float and double as floating point values, memory/buffer/image2d/image3d
674     must be an object of that type or C<undef>, and sampler and event must be
675     objects of that type.
676    
677     L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clSetKernelArg.html>
678    
679     =back
680    
681     =head2 THE OpenCL::Event CLASS
682    
683     This is the superclass for all event objects (including OpenCL::UserEvent
684     objects).
685    
686     =over 4
687    
688     =item $packed_value = $ev->info ($name)
689    
690     See C<< $platform->info >> for details.
691    
692     L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clGetEventInfo.html>
693    
694 root 1.20 =item $packed_value = $ev->profiling_info ($name)
695    
696     See C<< $platform->info >> for details.
697    
698     The reason this method is not called C<info> is that there already is an
699     C<< ->info >> method.
700    
701     L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clGetProfilingInfo.html>
702    
703 root 1.5 =item $ev->wait
704    
705     Waits for the event to complete.
706    
707     L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clWaitForEvents.html>
708    
709     =back
710    
711     =head2 THE OpenCL::UserEvent CLASS
712    
713     This is a subclass of OpenCL::Event.
714 root 1.4
715 root 1.1 =over 4
716    
717 root 1.5 =item $ev->set_status ($execution_status)
718    
719     L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clSetUserEventStatus.html>
720    
721     =back
722    
723 root 1.1 =cut
724    
725     package OpenCL;
726    
727 root 1.2 use common::sense;
728    
729 root 1.1 BEGIN {
730 root 1.18 our $VERSION = '0.15';
731 root 1.1
732     require XSLoader;
733     XSLoader::load (__PACKAGE__, $VERSION);
734 root 1.3
735 root 1.5 @OpenCL::Buffer::ISA =
736     @OpenCL::Image::ISA = OpenCL::Memory::;
737 root 1.3
738 root 1.5 @OpenCL::Image2D::ISA =
739     @OpenCL::Image3D::ISA = OpenCL::Image::;
740    
741     @OpenCL::UserEvent::ISA = OpenCL::Event::;
742 root 1.1 }
743    
744     1;
745    
746     =head1 AUTHOR
747    
748     Marc Lehmann <schmorp@schmorp.de>
749     http://home.schmorp.de/
750    
751     =cut
752