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

# Content
1 =head1 NAME
2
3 OpenCL - Open Computing Language Bindings
4
5 =head1 SYNOPSIS
6
7 use OpenCL;
8
9 =head1 DESCRIPTION
10
11 This is an early release which might be useful, but hasn't seen much testing.
12
13 =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 From a platform and some device(s), you create an OpenCL::Context, which is
24 a very central object in OpenCL: Once you have a context you can create
25 most other objects:
26
27 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
32 OpenCL::Memory objects of various flavours: OpenCL::Buffer objects (flat
33 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
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
48 The OpenCL spec used to develop this module (1.2 spec was available, but
49 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 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 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 And here's NVIDIA's OpenCL Best Practises Guide:
68
69 http://developer.download.nvidia.com/compute/cuda/3_2/toolkit/docs/OpenCL_Best_Practices_Guide.pdf
70
71 =head1 BASIC WORKFLOW
72
73 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
76 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
79 Create program objects from your OpenCL source code, then build (compile)
80 the programs for each device you want to run them on.
81
82 Create kernel objects for all kernels you want to use (surprisingly, these
83 are not device-specific).
84
85 Then, to execute stuff, you repeat these steps, possibly resuing or
86 sharing some buffers:
87
88 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
94 Enqueue the kernel execution.
95
96 Enqueue buffer reads for your output buffer to read results.
97
98 =head1 EXAMPLES
99
100 =head2 Enumerate all devices and get contexts for them.
101
102 Best run this once to get a feel for the platforms and devices in your
103 system.
104
105 for my $platform (OpenCL::platforms) {
106 printf "platform: %s\n", $platform->info (OpenCL::PLATFORM_NAME);
107 printf "extensions: %s\n", $platform->info (OpenCL::PLATFORM_EXTENSIONS);
108 for my $device ($platform->devices) {
109 printf "+ device: %s\n", $device->info (OpenCL::DEVICE_NAME);
110 my $ctx = $device->context;
111 # do stuff
112 }
113 }
114
115 =head2 Get a useful context and a command queue.
116
117 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
125 =head2 Print all supported image formats of a context.
126
127 Best run this once for your context, to see whats available and how to
128 gather information.
129
130 for my $type (OpenCL::MEM_OBJECT_IMAGE2D, OpenCL::MEM_OBJECT_IMAGE3D) {
131 print "supported image formats for ", OpenCL::enum2str $type, "\n";
132
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
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 print "$data\n";
145
146 my $ev = $queue->enqueue_read_buffer ($buf, 0, 1, 3, my $data);
147 $ev->wait;
148 print "$data\n"; # prints "elm"
149
150 =head2 Create and build a program, then create a kernel out of one of its
151 functions.
152
153 my $src = '
154 __kernel void
155 squareit (__global float *input, __global float *output)
156 {
157 $id = get_global_id (0);
158 output [id] = input [id] * input [id];
159 }
160 ';
161
162 my $prog = $ctx->program_with_source ($src);
163
164 # build croaks on compile errors, so catch it and print the compile errors
165 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 =head2 Create some input and output float buffers, then call the
171 'squareit' kernel on them.
172
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 # enqueue a synchronous read
184 $queue->enqueue_read_buffer ($output, 1, 0, OpenCL::SIZEOF_FLOAT * 4, my $data);
185
186 # print the results:
187 printf "%s\n", join ", ", unpack "f*", $data;
188
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 $queue->enqueue_barrier;
197
198 # 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 $ev->wait;
215
216 =head1 DOCUMENTATION
217
218 =head2 BASIC CONVENTIONS
219
220 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 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 =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
236 =item * OpenCL often specifies fixed vector function arguments as short
237 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
241 =item * Structures are often specified by flattening out their components
242 as with short vectors, and returned as arrayrefs.
243
244 =item * When enqueuing commands, the wait list is specified by adding
245 extra arguments to the function - anywhere a C<$wait_events...> argument
246 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 =head2 PERL AND OPENCL TYPES
259
260 This handy(?) table lists OpenCL types and their perl, PDL and pack/unpack
261 format equivalents:
262
263 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
276 =head2 THE OpenCL PACKAGE
277
278 =over 4
279
280 =item $int = OpenCL::errno
281
282 The last error returned by a function - it's only valid after an error occured
283 and before calling another OpenCL function.
284
285 =item $str = OpenCL::err2str $errval
286
287 Comverts an error value into a human readable string.
288
289 =item $str = OpenCL::enum2str $enum
290
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 =item $ctx = OpenCL::context_from_type $properties, $type = OpenCL::DEVICE_TYPE_DEFAULT, $notify = undef
304
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 =item $ctx = $platform->context_from_type ($properties, $type = OpenCL::DEVICE_TYPE_DEFAULT, $notify = undef)
326
327 Tries to create a context. Never worked for me, and you need devices explitly anyway.
328
329 L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clCreateContextFromType.html>
330
331 =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 =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 =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 =item $queue = $ctx->queue ($device, $properties)
392
393 Create a new OpenCL::Queue object from the context and the given device.
394
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 =item $img = $ctx->image2d ($flags, $channel_order, $channel_type, $width, $height, $row_pitch = 0, $data = undef)
414
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 =item $img = $ctx->image3d ($flags, $channel_order, $channel_type, $width, $height, $depth, $row_pitch = 0, $slice_pitch = 0, $data = undef)
420
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 =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 =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 cases (i.e. you use only one queue) it's not necessary to wait for or
472 create event objects.
473
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 =item $ev = $queue->enqueue_write_image ($src, $blocking, $x, $y, $z, $width, $height, $depth, $row_pitch, $slice_pitch, $data, $wait_events...)
503
504 L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clEnqueueWriteImage.html>
505
506 =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
508 Yeah.
509
510 L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clEnqueueCopyBufferRect.html>
511
512 =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
514 L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clEnqueueCopyBufferToImage.html>.
515
516 =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
518 L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clEnqueueCopyImage.html>
519
520 =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
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 =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 =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 =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 =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 =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 =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
715 =over 4
716
717 =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 =cut
724
725 package OpenCL;
726
727 use common::sense;
728
729 BEGIN {
730 our $VERSION = '0.15';
731
732 require XSLoader;
733 XSLoader::load (__PACKAGE__, $VERSION);
734
735 @OpenCL::Buffer::ISA =
736 @OpenCL::Image::ISA = OpenCL::Memory::;
737
738 @OpenCL::Image2D::ISA =
739 @OpenCL::Image3D::ISA = OpenCL::Image::;
740
741 @OpenCL::UserEvent::ISA = OpenCL::Event::;
742 }
743
744 1;
745
746 =head1 AUTHOR
747
748 Marc Lehmann <schmorp@schmorp.de>
749 http://home.schmorp.de/
750
751 =cut
752