ViewVC Help
View File | Revision Log | Show Annotations | Download File
/cvs/OpenCL/OpenCL.pm
(Generate patch)

Comparing OpenCL/OpenCL.pm (file contents):
Revision 1.22 by root, Sun Nov 20 10:25:17 2011 UTC vs.
Revision 1.64 by root, Mon Apr 30 23:12:43 2012 UTC

… …
43 43
44OpenCL::Event objects are used to signal when something is complete. 44OpenCL::Event objects are used to signal when something is complete.
45 45
46=head2 HELPFUL RESOURCES 46=head2 HELPFUL RESOURCES
47 47
48The OpenCL spec used to develop this module (1.2 spec was available, but 48The OpenCL specs used to develop this module:
49no implementation was available to me :).
50 49
51 http://www.khronos.org/registry/cl/specs/opencl-1.1.pdf 50 http://www.khronos.org/registry/cl/specs/opencl-1.1.pdf
51 http://www.khronos.org/registry/cl/specs/opencl-1.2.pdf
52 http://www.khronos.org/registry/cl/specs/opencl-1.2-extensions.pdf
52 53
53OpenCL manpages: 54OpenCL manpages:
54 55
55 http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/ 56 http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/
57 http://www.khronos.org/registry/cl/sdk/1.2/docs/man/xhtml/
56 58
57If you are into UML class diagrams, the following diagram might help - if 59If you are into UML class diagrams, the following diagram might help - if
58not, it will be mildly cobfusing: 60not, it will be mildly confusing (also, the class hierarchy of this module
61is much more fine-grained):
59 62
60 http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/classDiagram.html 63 http://www.khronos.org/registry/cl/sdk/1.2/docs/man/xhtml/classDiagram.html
61 64
62Here's a tutorial from AMD (very AMD-centric, too), not sure how useful it 65Here's a tutorial from AMD (very AMD-centric, too), not sure how useful it
63is, but at least it's free of charge: 66is, but at least it's free of charge:
64 67
65 http://developer.amd.com/zones/OpenCLZone/courses/Documents/Introduction_to_OpenCL_Programming%20Training_Guide%20%28201005%29.pdf 68 http://developer.amd.com/zones/OpenCLZone/courses/Documents/Introduction_to_OpenCL_Programming%20Training_Guide%20%28201005%29.pdf
… …
101 104
102Best run this once to get a feel for the platforms and devices in your 105Best run this once to get a feel for the platforms and devices in your
103system. 106system.
104 107
105 for my $platform (OpenCL::platforms) { 108 for my $platform (OpenCL::platforms) {
106 printf "platform: %s\n", $platform->info (OpenCL::PLATFORM_NAME); 109 printf "platform: %s\n", $platform->name;
107 printf "extensions: %s\n", $platform->info (OpenCL::PLATFORM_EXTENSIONS); 110 printf "extensions: %s\n", $platform->extensions;
108 for my $device ($platform->devices) { 111 for my $device ($platform->devices) {
109 printf "+ device: %s\n", $device->info (OpenCL::DEVICE_NAME); 112 printf "+ device: %s\n", $device->name;
110 my $ctx = $device->context; 113 my $ctx = $platform->context (undef, [$device]);
111 # do stuff 114 # do stuff
112 } 115 }
113 } 116 }
114 117
115=head2 Get a useful context and a command queue. 118=head2 Get a useful context and a command queue.
… …
138=head2 Create a buffer with some predefined data, read it back synchronously, 141=head2 Create a buffer with some predefined data, read it back synchronously,
139then asynchronously. 142then asynchronously.
140 143
141 my $buf = $ctx->buffer_sv (OpenCL::MEM_COPY_HOST_PTR, "helmut"); 144 my $buf = $ctx->buffer_sv (OpenCL::MEM_COPY_HOST_PTR, "helmut");
142 145
143 $queue->enqueue_read_buffer ($buf, 1, 1, 3, my $data); 146 $queue->read_buffer ($buf, 1, 1, 3, my $data);
144 print "$data\n"; 147 print "$data\n";
145 148
146 my $ev = $queue->enqueue_read_buffer ($buf, 0, 1, 3, my $data); 149 my $ev = $queue->read_buffer ($buf, 0, 1, 3, my $data);
147 $ev->wait; 150 $ev->wait;
148 print "$data\n"; # prints "elm" 151 print "$data\n"; # prints "elm"
149 152
150=head2 Create and build a program, then create a kernel out of one of its 153=head2 Create and build a program, then create a kernel out of one of its
151functions. 154functions.
152 155
153 my $src = ' 156 my $src = '
154 __kernel void 157 kernel void
155 squareit (__global float *input, __global float *output) 158 squareit (global float *input, global float *output)
156 { 159 {
157 $id = get_global_id (0); 160 $id = get_global_id (0);
158 output [id] = input [id] * input [id]; 161 output [id] = input [id] * input [id];
159 } 162 }
160 '; 163 ';
161 164
162 my $prog = $ctx->program_with_source ($src); 165 my $prog = $ctx->build_program ($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"); 166 my $kernel = $prog->kernel ("squareit");
169 167
170=head2 Create some input and output float buffers, then call the 168=head2 Create some input and output float buffers, then call the
171'squareit' kernel on them. 169'squareit' kernel on them.
172 170
… …
176 # set buffer 174 # set buffer
177 $kernel->set_buffer (0, $input); 175 $kernel->set_buffer (0, $input);
178 $kernel->set_buffer (1, $output); 176 $kernel->set_buffer (1, $output);
179 177
180 # execute it for all 4 numbers 178 # execute it for all 4 numbers
181 $queue->enqueue_nd_range_kernel ($kernel, undef, [4], undef); 179 $queue->nd_range_kernel ($kernel, undef, [4], undef);
182 180
183 # enqueue a synchronous read 181 # enqueue a synchronous read
184 $queue->enqueue_read_buffer ($output, 1, 0, OpenCL::SIZEOF_FLOAT * 4, my $data); 182 $queue->read_buffer ($output, 1, 0, OpenCL::SIZEOF_FLOAT * 4, my $data);
185 183
186 # print the results: 184 # print the results:
187 printf "%s\n", join ", ", unpack "f*", $data; 185 printf "%s\n", join ", ", unpack "f*", $data;
188 186
189=head2 The same enqueue operations as before, but assuming an out-of-order queue, 187=head2 The same enqueue operations as before, but assuming an out-of-order queue,
190showing off barriers. 188showing off barriers.
191 189
192 # execute it for all 4 numbers 190 # execute it for all 4 numbers
193 $queue->enqueue_nd_range_kernel ($kernel, undef, [4], undef); 191 $queue->nd_range_kernel ($kernel, undef, [4], undef);
194 192
195 # enqueue a barrier to ensure in-order execution 193 # enqueue a barrier to ensure in-order execution
196 $queue->enqueue_barrier; 194 $queue->barrier;
197 195
198 # enqueue an async read 196 # enqueue an async read
199 $queue->enqueue_read_buffer ($output, 0, 0, OpenCL::SIZEOF_FLOAT * 4, my $data); 197 $queue->read_buffer ($output, 0, 0, OpenCL::SIZEOF_FLOAT * 4, my $data);
200 198
201 # wait for all requests to finish 199 # wait for all requests to finish
202 $queue->finish; 200 $queue->finish;
203 201
204=head2 The same enqueue operations as before, but assuming an out-of-order queue, 202=head2 The same enqueue operations as before, but assuming an out-of-order queue,
205showing off event objects and wait lists. 203showing off event objects and wait lists.
206 204
207 # execute it for all 4 numbers 205 # execute it for all 4 numbers
208 my $ev = $queue->enqueue_nd_range_kernel ($kernel, undef, [4], undef); 206 my $ev = $queue->nd_range_kernel ($kernel, undef, [4], undef);
209 207
210 # enqueue an async read 208 # enqueue an async read
211 $ev = $queue->enqueue_read_buffer ($output, 0, 0, OpenCL::SIZEOF_FLOAT * 4, my $data, $ev); 209 $ev = $queue->read_buffer ($output, 0, 0, OpenCL::SIZEOF_FLOAT * 4, my $data, $ev);
212 210
213 # wait for the last event to complete 211 # wait for the last event to complete
214 $ev->wait; 212 $ev->wait;
213
214=head2 Use the OpenGL module to share a texture between OpenCL and OpenGL and draw some julia
215set tunnel effect.
216
217This is quite a long example to get you going - you can download it from
218L<http://cvs.schmorp.de/OpenCL/examples/juliaflight>.
219
220 use OpenGL ":all";
221 use OpenCL;
222
223 my $S = $ARGV[0] || 256; # window/texture size, smaller is faster
224
225 # open a window and create a gl texture
226 OpenGL::glpOpenWindow width => $S, height => $S;
227 my $texid = glGenTextures_p 1;
228 glBindTexture GL_TEXTURE_2D, $texid;
229 glTexImage2D_c GL_TEXTURE_2D, 0, GL_RGBA8, $S, $S, 0, GL_RGBA, GL_UNSIGNED_BYTE, 0;
230
231 # find and use the first opencl device that let's us get a shared opengl context
232 my $platform;
233 my $dev;
234 my $ctx;
235
236 for (OpenCL::platforms) {
237 $platform = $_;
238 for ($platform->devices) {
239 $dev = $_;
240 $ctx = $platform->context ([OpenCL::GLX_DISPLAY_KHR, undef, OpenCL::GL_CONTEXT_KHR, undef], [$dev])
241 and last;
242 }
243 }
244
245 $ctx
246 or die "cannot find suitable OpenCL device\n";
247
248 my $queue = $ctx->queue ($dev);
249
250 # now attach an opencl image2d object to the opengl texture
251 my $tex = $ctx->gl_texture2d (OpenCL::MEM_WRITE_ONLY, GL_TEXTURE_2D, 0, $texid);
252
253 # now the boring opencl code
254 my $src = <<EOF;
255 kernel void
256 juliatunnel (write_only image2d_t img, float time)
257 {
258 int2 xy = (int2)(get_global_id (0), get_global_id (1));
259 float2 p = convert_float2 (xy) / $S.f * 2.f - 1.f;
260
261 float2 m = (float2)(1.f, p.y) / fabs (p.x); // tunnel
262 m.x = fabs (fmod (m.x + time * 0.05f, 4.f) - 2.f);
263
264 float2 z = m;
265 float2 c = (float2)(sin (time * 0.01133f), cos (time * 0.02521f));
266
267 for (int i = 0; i < 25 && dot (z, z) < 4.f; ++i) // standard julia
268 z = (float2)(z.x * z.x - z.y * z.y, 2.f * z.x * z.y) + c;
269
270 float3 colour = (float3)(z.x, z.y, atan2 (z.y, z.x));
271 write_imagef (img, xy, (float4)(colour * p.x * p.x, 1.));
272 }
273 EOF
274
275 my $prog = $ctx->build_program ($src);
276 my $kernel = $prog->kernel ("juliatunnel");
277
278 # program compiled, kernel ready, now draw and loop
279
280 for (my $time; ; ++$time) {
281 # acquire objects from opengl
282 $queue->acquire_gl_objects ([$tex]);
283
284 # configure and run our kernel
285 $kernel->setf ("mf", $tex, $time*2); # mf = memory object, float
286 $queue->nd_range_kernel ($kernel, undef, [$S, $S], undef);
287
288 # release objects to opengl again
289 $queue->release_gl_objects ([$tex]);
290
291 # wait
292 $queue->finish;
293
294 # now draw the texture, the defaults should be all right
295 glTexParameterf GL_TEXTURE_2D, GL_TEXTURE_MIN_FILTER, GL_NEAREST;
296
297 glEnable GL_TEXTURE_2D;
298 glBegin GL_QUADS;
299 glTexCoord2f 0, 1; glVertex3i -1, -1, -1;
300 glTexCoord2f 0, 0; glVertex3i 1, -1, -1;
301 glTexCoord2f 1, 0; glVertex3i 1, 1, -1;
302 glTexCoord2f 1, 1; glVertex3i -1, 1, -1;
303 glEnd;
304
305 glXSwapBuffers;
306
307 select undef, undef, undef, 1/60;
308 }
215 309
216=head1 DOCUMENTATION 310=head1 DOCUMENTATION
217 311
218=head2 BASIC CONVENTIONS 312=head2 BASIC CONVENTIONS
219 313
… …
241=item * Structures are often specified by flattening out their components 335=item * Structures are often specified by flattening out their components
242as with short vectors, and returned as arrayrefs. 336as with short vectors, and returned as arrayrefs.
243 337
244=item * When enqueuing commands, the wait list is specified by adding 338=item * When enqueuing commands, the wait list is specified by adding
245extra arguments to the function - anywhere a C<$wait_events...> argument 339extra arguments to the function - anywhere a C<$wait_events...> argument
246is documented this can be any number of event objects. 340is documented this can be any number of event objects. As an extsnion
341implemented by this module, C<undef> values will be ignored in the event
342list.
247 343
248=item * When enqueuing commands, if the enqueue method is called in void 344=item * When enqueuing commands, if the enqueue method is called in void
249context, no event is created. In all other contexts an event is returned 345context, no event is created. In all other contexts an event is returned
250by the method. 346by the method.
251 347
… …
271 ulong IV - Q 367 ulong IV - Q
272 float NV float f 368 float NV float f
273 half IV ushort S 369 half IV ushort S
274 double NV double d 370 double NV double d
275 371
372=head2 GLX SUPPORT
373
374Due to the sad state that OpenGL support is in in Perl (mostly the OpenGL
375module, which has little to no documentation and has little to no support
376for glX), this module, as a special extension, treats context creation
377properties C<OpenCL::GLX_DISPLAY_KHR> and C<OpenCL::GL_CONTEXT_KHR>
378specially: If either or both of these are C<undef>, then the OpenCL
379module tries to dynamically resolve C<glXGetCurrentDisplay> and
380C<glXGetCurrentContext>, call these functions and use their return values
381instead.
382
383For this to work, the OpenGL library must be loaded, a GLX context must
384have been created and be made current, and C<dlsym> must be available and
385capable of finding the function via C<RTLD_DEFAULT>.
386
387=head2 EVENT SYSTEM
388
389OpenCL can generate a number of (potentially) asynchronous events, for
390example, after compiling a program, to signal a context-related error or,
391perhaps most important, to signal completion of queued jobs (by setting
392callbacks on OpenCL::Event objects).
393
394To facilitate this, this module maintains an event queue - each
395time an asynchronous event happens, it is queued, and perl will be
396interrupted. This is implemented via the L<Async::Interrupt> module. In
397addition, this module has L<AnyEvent> support, so it can seamlessly
398integrate itself into many event loops.
399
400Since this module is a bit hard to understand, here are some case examples:
401
402=head3 Don't use callbacks.
403
404When your program never uses any callbacks, then there will never be any
405notifications you need to take care of, and therefore no need to worry
406about all this.
407
408You can achieve a great deal by explicitly waiting for events, or using
409barriers and flush calls. In many programs, there is no need at all to
410tinker with asynchronous events.
411
412=head3 Use AnyEvent
413
414This module automatically registers a watcher that invokes all outstanding
415event callbacks when AnyEvent is initialised (and block asynchronous
416interruptions). Using this mode of operations is the safest and most
417recommended one.
418
419To use this, simply use AnyEvent and this module normally, make sure you
420have an event loop running:
421
422 use Gtk2 -init;
423 use AnyEvent;
424
425 # initialise AnyEvent, by creating a watcher, or:
426 AnyEvent::detect;
427
428 my $e = $queue->marker;
429 $e->cb (sub {
430 warn "opencl is finished\n";
431 })
432
433 main Gtk2;
434
435Note that this module will not initialise AnyEvent for you. Before
436AnyEvent is initialised, the module will asynchronously interrupt perl
437instead. To avoid any surprises, it's best to explicitly initialise
438AnyEvent.
439
440You can temporarily enable asynchronous interruptions (see next paragraph)
441by calling C<$OpenCL::INTERRUPT->unblock> and disable them again by
442calling C<$OpenCL::INTERRUPT->block>.
443
444=head3 Let yourself be interrupted at any time
445
446This mode is the default unless AnyEvent is loaded and initialised. In
447this mode, OpenCL asynchronously interrupts a running perl program. The
448emphasis is on both I<asynchronously> and I<running> here.
449
450Asynchronously means that perl might execute your callbacks at any
451time. For example, in the following code (I<THAT YOU SHOULD NOT COPY>),
452the C<until> loop following the marker call will be interrupted by the
453callback:
454
455 my $e = $queue->marker;
456 my $flag;
457 $e->cb (sub { $flag = 1 });
458 1 until $flag;
459 # $flag is now 1
460
461The reason why you shouldn't blindly copy the above code is that
462busy waiting is a really really bad thing, and really really bad for
463performance.
464
465While at first this asynchronous business might look exciting, it can be
466really hard, because you need to be prepared for the callback code to be
467executed at any time, which limits the amount of things the callback code
468can do safely.
469
470This can be mitigated somewhat by using C<<
471$OpenCL::INTERRUPT->scope_block >> (see the L<Async::Interrupt>
472documentation for details).
473
474The other problem is that your program must be actively I<running> to be
475interrupted. When you calculate stuff, your program is running. When you
476hang in some C functions or other block execution (by calling C<sleep>,
477C<select>, running an event loop and so on), your program is waiting, not
478running.
479
480One way around that would be to attach a read watcher to your event loop,
481listening for events on C<< $OpenCL::INTERRUPT->pipe_fileno >>, using a
482dummy callback (C<sub { }>) to temporarily execute some perl code.
483
484That is then awfully close to using the built-in AnyEvent support above,
485though, so consider that one instead.
486
487=head3 Be creative
488
489OpenCL exports the L<Async::Interrupt> object it uses in the global
490variable C<$OpenCL::INTERRUPT>. You can configure it in any way you like.
491
492So if you want to feel like a real pro, err, wait, if you feel no risk
493menas no fun, you can experiment by implementing your own mode of
494operations.
495
496=cut
497
498package OpenCL;
499
500use common::sense;
501use Carp ();
502use Async::Interrupt ();
503
504our $POLL_FUNC; # set by XS
505
506BEGIN {
507 our $VERSION = '0.98';
508
509 require XSLoader;
510 XSLoader::load (__PACKAGE__, $VERSION);
511
512 @OpenCL::Platform::ISA =
513 @OpenCL::Device::ISA =
514 @OpenCL::Context::ISA =
515 @OpenCL::Queue::ISA =
516 @OpenCL::Memory::ISA =
517 @OpenCL::Sampler::ISA =
518 @OpenCL::Program::ISA =
519 @OpenCL::Kernel::ISA =
520 @OpenCL::Event::ISA = OpenCL::Object::;
521
522 @OpenCL::Buffer::ISA =
523 @OpenCL::Image::ISA = OpenCL::Memory::;
524
525 @OpenCL::BufferObj::ISA = OpenCL::Buffer::;
526
527 @OpenCL::Image2D::ISA =
528 @OpenCL::Image3D::ISA =
529 @OpenCL::Image2DArray::ISA =
530 @OpenCL::Image1D::ISA =
531 @OpenCL::Image1DArray::ISA =
532 @OpenCL::Image1DBuffer::ISA = OpenCL::Image::;
533
534 @OpenCL::UserEvent::ISA = OpenCL::Event::;
535}
536
276=head2 THE OpenCL PACKAGE 537=head2 THE OpenCL PACKAGE
277 538
278=over 4 539=over 4
279 540
280=item $int = OpenCL::errno 541=item $int = OpenCL::errno
281 542
282The last error returned by a function - it's only valid after an error occured 543The last error returned by a function - it's only valid after an error occured
283and before calling another OpenCL function. 544and before calling another OpenCL function.
284 545
285=item $str = OpenCL::err2str $errval 546=item $str = OpenCL::err2str [$errval]
286 547
287Comverts an error value into a human readable string. 548Converts an error value into a human readable string. IF no error value is
549given, then the last error will be used (as returned by OpenCL::errno).
288 550
289=item $str = OpenCL::enum2str $enum 551=item $str = OpenCL::enum2str $enum
290 552
291Converts most enum values (inof parameter names, image format constants, 553Converts most enum values (of parameter names, image format constants,
292object types, addressing and filter modes, command types etc.) into a 554object types, addressing and filter modes, command types etc.) into a
293human readbale string. When confronted with some random integer it can be 555human readable string. When confronted with some random integer it can be
294very helpful to pass it through this function to maybe get some readable 556very helpful to pass it through this function to maybe get some readable
295string out of it. 557string out of it.
296 558
297=item @platforms = OpenCL::platforms 559=item @platforms = OpenCL::platforms
298 560
299Returns all available OpenCL::Platform objects. 561Returns all available OpenCL::Platform objects.
300 562
301L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clGetPlatformIDs.html> 563L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clGetPlatformIDs.html>
302 564
303=item $ctx = OpenCL::context_from_type $properties, $type = OpenCL::DEVICE_TYPE_DEFAULT, $notify = undef 565=item $ctx = OpenCL::context_from_type $properties, $type = OpenCL::DEVICE_TYPE_DEFAULT, $callback->($err, $pvt) = $print_stderr
304 566
305Tries to create a context from a default device and platform - never worked for me. 567Tries to create a context from a default device and platform type - never worked for me.
306 568
307L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clCreateContextFromType.html> 569L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clCreateContextFromType.html>
308 570
571=item $ctx = OpenCL::context $properties, \@devices, $callback->($err, $pvt) = $print_stderr)
572
573Create a new OpenCL::Context object using the given device object(s). This
574function isn't implemented yet, use C<< $platform->context >> instead.
575
576L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clCreateContext.html>
577
309=item OpenCL::wait_for_events $wait_events... 578=item OpenCL::wait_for_events $wait_events...
310 579
311Waits for all events to complete. 580Waits for all events to complete.
312 581
313L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clWaitForEvents.html> 582L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clWaitForEvents.html>
314 583
584=item OpenCL::poll
585
586Checks if there are any outstanding events (see L<EVENT SYSTEM>) and
587invokes their callbacks.
588
589=item $OpenCL::INTERRUPT
590
591The L<Async::Interrupt> object used to signal asynchronous events (see
592L<EVENT SYSTEM>).
593
594=cut
595
596our $INTERRUPT = new Async::Interrupt c_cb => [$POLL_FUNC, 0];
597
598&_eq_initialise ($INTERRUPT->signal_func);
599
600=item $OpenCL::WATCHER
601
602The L<AnyEvent> watcher object used to watch for asynchronous events (see
603L<EVENT SYSTEM>). This variable is C<undef> until L<AnyEvent> has been
604loaded I<and> initialised (e.g. by calling C<AnyEvent::detect>).
605
606=cut
607
608our $WATCHER;
609
610sub _init_anyevent {
611 $INTERRUPT->block;
612 $WATCHER = AE::io ($INTERRUPT->pipe_fileno, 0, sub { $INTERRUPT->handle });
613}
614
615if (defined $AnyEvent::MODEL) {
616 _init_anyevent;
617} else {
618 push @AnyEvent::post_detect, \&_init_anyevent;
619}
620
315=back 621=back
316 622
623=head2 THE OpenCL::Object CLASS
624
625This is the base class for all objects in the OpenCL module. The only
626method it implements is the C<id> method, which is only useful if you want
627to interface to OpenCL on the C level.
628
629=over 4
630
631=item $iv = $obj->id
632
633OpenCL objects are represented by pointers or integers on the C level. If
634you want to interface to an OpenCL object directly on the C level, then
635you need this value, which is returned by this method. You should use an
636C<IV> type in your code and cast that to the correct type.
637
638=cut
639
640sub OpenCL::Object::id {
641 ref $_[0] eq "SCALAR"
642 ? ${ $_[0] }
643 : $_[0][0]
644}
645
646=back
647
317=head2 THE OpenCL::Platform CLASS 648=head2 THE OpenCL::Platform CLASS
318 649
319=over 4 650=over 4
320 651
321=item @devices = $platform->devices ($type = OpenCL::DEVICE_TYPE_ALL) 652=item @devices = $platform->devices ($type = OpenCL::DEVICE_TYPE_ALL)
322 653
323Returns a list of matching OpenCL::Device objects. 654Returns a list of matching OpenCL::Device objects.
324 655
325=item $ctx = $platform->context_from_type ($properties, $type = OpenCL::DEVICE_TYPE_DEFAULT, $notify = undef) 656=item $ctx = $platform->context_from_type ($properties, $type = OpenCL::DEVICE_TYPE_DEFAULT, $callback->($err, $pvt) = $print_stderr)
326 657
327Tries to create a context. Never worked for me, and you need devices explicitly anyway. 658Tries to create a context. Never worked for me, and you need devices explicitly anyway.
328 659
329L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clCreateContextFromType.html> 660L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clCreateContextFromType.html>
330 661
331=item $ctx = $device->context ($properties = undef, @$devices, $notify = undef) 662=item $ctx = $platform->context ($properties, \@devices, $callback->($err, $pvt) = $print_stderr)
332 663
333Create a new OpenCL::Context object using the given device object(s)- a 664Create a new OpenCL::Context object using the given device object(s)- a
334CL_CONTEXT_PLATFORM property is supplied automatically. 665CL_CONTEXT_PLATFORM property is supplied automatically.
335 666
336L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clCreateContext.html> 667L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clCreateContext.html>
… …
344It's best to avoid this method and use one of the following convenience 675It's best to avoid this method and use one of the following convenience
345wrappers. 676wrappers.
346 677
347L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clGetPlatformInfo.html> 678L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clGetPlatformInfo.html>
348 679
680=item $platform->unload_compiler
681
682Attempts to unload the compiler for this platform, for endless
683profit. Does nothing on OpenCL 1.1.
684
685L<http://www.khronos.org/registry/cl/sdk/1.2/docs/man/xhtml/clUnloadPlatformCompiler.html>
686
349=for gengetinfo begin platform 687=for gengetinfo begin platform
350 688
351=item $string = $platform->profile 689=item $string = $platform->profile
352 690
353Calls C<clGetPlatformInfo> with C<CL_PLATFORM_PROFILE> and returns the result(s). 691Calls C<clGetPlatformInfo> with C<CL_PLATFORM_PROFILE> and returns the result.
354 692
355=item $string = $platform->version 693=item $string = $platform->version
356 694
357Calls C<clGetPlatformInfo> with C<CL_PLATFORM_VERSION> and returns the result(s). 695Calls C<clGetPlatformInfo> with C<CL_PLATFORM_VERSION> and returns the result.
358 696
359=item $string = $platform->name 697=item $string = $platform->name
360 698
361Calls C<clGetPlatformInfo> with C<CL_PLATFORM_NAME> and returns the result(s). 699Calls C<clGetPlatformInfo> with C<CL_PLATFORM_NAME> and returns the result.
362 700
363=item $string = $platform->vendor 701=item $string = $platform->vendor
364 702
365Calls C<clGetPlatformInfo> with C<CL_PLATFORM_VENDOR> and returns the result(s). 703Calls C<clGetPlatformInfo> with C<CL_PLATFORM_VENDOR> and returns the result.
366 704
367=item $string = $platform->extensions 705=item $string = $platform->extensions
368 706
369Calls C<clGetPlatformInfo> with C<CL_PLATFORM_EXTENSIONS> and returns the result(s). 707Calls C<clGetPlatformInfo> with C<CL_PLATFORM_EXTENSIONS> and returns the result.
370 708
371=for gengetinfo end platform 709=for gengetinfo end platform
372 710
373=back 711=back
374 712
… …
384 722
385=for gengetinfo begin device 723=for gengetinfo begin device
386 724
387=item $device_type = $device->type 725=item $device_type = $device->type
388 726
389Calls C<clGetDeviceInfo> with C<CL_DEVICE_TYPE> and returns the result(s). 727Calls C<clGetDeviceInfo> with C<CL_DEVICE_TYPE> and returns the result.
390 728
391=item $uint = $device->vendor_id 729=item $uint = $device->vendor_id
392 730
393Calls C<clGetDeviceInfo> with C<CL_DEVICE_VENDOR_ID> and returns the result(s). 731Calls C<clGetDeviceInfo> with C<CL_DEVICE_VENDOR_ID> and returns the result.
394 732
395=item $uint = $device->max_compute_units 733=item $uint = $device->max_compute_units
396 734
397Calls C<clGetDeviceInfo> with C<CL_DEVICE_MAX_COMPUTE_UNITS> and returns the result(s). 735Calls C<clGetDeviceInfo> with C<CL_DEVICE_MAX_COMPUTE_UNITS> and returns the result.
398 736
399=item $uint = $device->max_work_item_dimensions 737=item $uint = $device->max_work_item_dimensions
400 738
401Calls C<clGetDeviceInfo> with C<CL_DEVICE_MAX_WORK_ITEM_DIMENSIONS> and returns the result(s). 739Calls C<clGetDeviceInfo> with C<CL_DEVICE_MAX_WORK_ITEM_DIMENSIONS> and returns the result.
402 740
403=item $int = $device->max_work_group_size 741=item $int = $device->max_work_group_size
404 742
405Calls C<clGetDeviceInfo> with C<CL_DEVICE_MAX_WORK_GROUP_SIZE> and returns the result(s). 743Calls C<clGetDeviceInfo> with C<CL_DEVICE_MAX_WORK_GROUP_SIZE> and returns the result.
406 744
407=item @ints = $device->max_work_item_sizes 745=item @ints = $device->max_work_item_sizes
408 746
409Calls C<clGetDeviceInfo> with C<CL_DEVICE_MAX_WORK_ITEM_SIZES> and returns the result(s). 747Calls C<clGetDeviceInfo> with C<CL_DEVICE_MAX_WORK_ITEM_SIZES> and returns the result.
410 748
411=item $uint = $device->preferred_vector_width_char 749=item $uint = $device->preferred_vector_width_char
412 750
413Calls C<clGetDeviceInfo> with C<CL_DEVICE_PREFERRED_VECTOR_WIDTH_CHAR> and returns the result(s). 751Calls C<clGetDeviceInfo> with C<CL_DEVICE_PREFERRED_VECTOR_WIDTH_CHAR> and returns the result.
414 752
415=item $uint = $device->preferred_vector_width_short 753=item $uint = $device->preferred_vector_width_short
416 754
417Calls C<clGetDeviceInfo> with C<CL_DEVICE_PREFERRED_VECTOR_WIDTH_SHORT> and returns the result(s). 755Calls C<clGetDeviceInfo> with C<CL_DEVICE_PREFERRED_VECTOR_WIDTH_SHORT> and returns the result.
418 756
419=item $uint = $device->preferred_vector_width_int 757=item $uint = $device->preferred_vector_width_int
420 758
421Calls C<clGetDeviceInfo> with C<CL_DEVICE_PREFERRED_VECTOR_WIDTH_INT> and returns the result(s). 759Calls C<clGetDeviceInfo> with C<CL_DEVICE_PREFERRED_VECTOR_WIDTH_INT> and returns the result.
422 760
423=item $uint = $device->preferred_vector_width_long 761=item $uint = $device->preferred_vector_width_long
424 762
425Calls C<clGetDeviceInfo> with C<CL_DEVICE_PREFERRED_VECTOR_WIDTH_LONG> and returns the result(s). 763Calls C<clGetDeviceInfo> with C<CL_DEVICE_PREFERRED_VECTOR_WIDTH_LONG> and returns the result.
426 764
427=item $uint = $device->preferred_vector_width_float 765=item $uint = $device->preferred_vector_width_float
428 766
429Calls C<clGetDeviceInfo> with C<CL_DEVICE_PREFERRED_VECTOR_WIDTH_FLOAT> and returns the result(s). 767Calls C<clGetDeviceInfo> with C<CL_DEVICE_PREFERRED_VECTOR_WIDTH_FLOAT> and returns the result.
430 768
431=item $uint = $device->preferred_vector_width_double 769=item $uint = $device->preferred_vector_width_double
432 770
433Calls C<clGetDeviceInfo> with C<CL_DEVICE_PREFERRED_VECTOR_WIDTH_DOUBLE> and returns the result(s). 771Calls C<clGetDeviceInfo> with C<CL_DEVICE_PREFERRED_VECTOR_WIDTH_DOUBLE> and returns the result.
434 772
435=item $uint = $device->max_clock_frequency 773=item $uint = $device->max_clock_frequency
436 774
437Calls C<clGetDeviceInfo> with C<CL_DEVICE_MAX_CLOCK_FREQUENCY> and returns the result(s). 775Calls C<clGetDeviceInfo> with C<CL_DEVICE_MAX_CLOCK_FREQUENCY> and returns the result.
438 776
439=item $bitfield = $device->address_bits 777=item $bitfield = $device->address_bits
440 778
441Calls C<clGetDeviceInfo> with C<CL_DEVICE_ADDRESS_BITS> and returns the result(s). 779Calls C<clGetDeviceInfo> with C<CL_DEVICE_ADDRESS_BITS> and returns the result.
442 780
443=item $uint = $device->max_read_image_args 781=item $uint = $device->max_read_image_args
444 782
445Calls C<clGetDeviceInfo> with C<CL_DEVICE_MAX_READ_IMAGE_ARGS> and returns the result(s). 783Calls C<clGetDeviceInfo> with C<CL_DEVICE_MAX_READ_IMAGE_ARGS> and returns the result.
446 784
447=item $uint = $device->max_write_image_args 785=item $uint = $device->max_write_image_args
448 786
449Calls C<clGetDeviceInfo> with C<CL_DEVICE_MAX_WRITE_IMAGE_ARGS> and returns the result(s). 787Calls C<clGetDeviceInfo> with C<CL_DEVICE_MAX_WRITE_IMAGE_ARGS> and returns the result.
450 788
451=item $ulong = $device->max_mem_alloc_size 789=item $ulong = $device->max_mem_alloc_size
452 790
453Calls C<clGetDeviceInfo> with C<CL_DEVICE_MAX_MEM_ALLOC_SIZE> and returns the result(s). 791Calls C<clGetDeviceInfo> with C<CL_DEVICE_MAX_MEM_ALLOC_SIZE> and returns the result.
454 792
455=item $int = $device->image2d_max_width 793=item $int = $device->image2d_max_width
456 794
457Calls C<clGetDeviceInfo> with C<CL_DEVICE_IMAGE2D_MAX_WIDTH> and returns the result(s). 795Calls C<clGetDeviceInfo> with C<CL_DEVICE_IMAGE2D_MAX_WIDTH> and returns the result.
458 796
459=item $int = $device->image2d_max_height 797=item $int = $device->image2d_max_height
460 798
461Calls C<clGetDeviceInfo> with C<CL_DEVICE_IMAGE2D_MAX_HEIGHT> and returns the result(s). 799Calls C<clGetDeviceInfo> with C<CL_DEVICE_IMAGE2D_MAX_HEIGHT> and returns the result.
462 800
463=item $int = $device->image3d_max_width 801=item $int = $device->image3d_max_width
464 802
465Calls C<clGetDeviceInfo> with C<CL_DEVICE_IMAGE3D_MAX_WIDTH> and returns the result(s). 803Calls C<clGetDeviceInfo> with C<CL_DEVICE_IMAGE3D_MAX_WIDTH> and returns the result.
466 804
467=item $int = $device->image3d_max_height 805=item $int = $device->image3d_max_height
468 806
469Calls C<clGetDeviceInfo> with C<CL_DEVICE_IMAGE3D_MAX_HEIGHT> and returns the result(s). 807Calls C<clGetDeviceInfo> with C<CL_DEVICE_IMAGE3D_MAX_HEIGHT> and returns the result.
470 808
471=item $int = $device->image3d_max_depth 809=item $int = $device->image3d_max_depth
472 810
473Calls C<clGetDeviceInfo> with C<CL_DEVICE_IMAGE3D_MAX_DEPTH> and returns the result(s). 811Calls C<clGetDeviceInfo> with C<CL_DEVICE_IMAGE3D_MAX_DEPTH> and returns the result.
474 812
475=item $uint = $device->image_support 813=item $uint = $device->image_support
476 814
477Calls C<clGetDeviceInfo> with C<CL_DEVICE_IMAGE_SUPPORT> and returns the result(s). 815Calls C<clGetDeviceInfo> with C<CL_DEVICE_IMAGE_SUPPORT> and returns the result.
478 816
479=item $int = $device->max_parameter_size 817=item $int = $device->max_parameter_size
480 818
481Calls C<clGetDeviceInfo> with C<CL_DEVICE_MAX_PARAMETER_SIZE> and returns the result(s). 819Calls C<clGetDeviceInfo> with C<CL_DEVICE_MAX_PARAMETER_SIZE> and returns the result.
482 820
483=item $uint = $device->max_samplers 821=item $uint = $device->max_samplers
484 822
485Calls C<clGetDeviceInfo> with C<CL_DEVICE_MAX_SAMPLERS> and returns the result(s). 823Calls C<clGetDeviceInfo> with C<CL_DEVICE_MAX_SAMPLERS> and returns the result.
486 824
487=item $uint = $device->mem_base_addr_align 825=item $uint = $device->mem_base_addr_align
488 826
489Calls C<clGetDeviceInfo> with C<CL_DEVICE_MEM_BASE_ADDR_ALIGN> and returns the result(s). 827Calls C<clGetDeviceInfo> with C<CL_DEVICE_MEM_BASE_ADDR_ALIGN> and returns the result.
490 828
491=item $uint = $device->min_data_type_align_size 829=item $uint = $device->min_data_type_align_size
492 830
493Calls C<clGetDeviceInfo> with C<CL_DEVICE_MIN_DATA_TYPE_ALIGN_SIZE> and returns the result(s). 831Calls C<clGetDeviceInfo> with C<CL_DEVICE_MIN_DATA_TYPE_ALIGN_SIZE> and returns the result.
494 832
495=item $device_fp_config = $device->single_fp_config 833=item $device_fp_config = $device->single_fp_config
496 834
497Calls C<clGetDeviceInfo> with C<CL_DEVICE_SINGLE_FP_CONFIG> and returns the result(s). 835Calls C<clGetDeviceInfo> with C<CL_DEVICE_SINGLE_FP_CONFIG> and returns the result.
498 836
499=item $device_mem_cache_type = $device->global_mem_cache_type 837=item $device_mem_cache_type = $device->global_mem_cache_type
500 838
501Calls C<clGetDeviceInfo> with C<CL_DEVICE_GLOBAL_MEM_CACHE_TYPE> and returns the result(s). 839Calls C<clGetDeviceInfo> with C<CL_DEVICE_GLOBAL_MEM_CACHE_TYPE> and returns the result.
502 840
503=item $uint = $device->global_mem_cacheline_size 841=item $uint = $device->global_mem_cacheline_size
504 842
505Calls C<clGetDeviceInfo> with C<CL_DEVICE_GLOBAL_MEM_CACHELINE_SIZE> and returns the result(s). 843Calls C<clGetDeviceInfo> with C<CL_DEVICE_GLOBAL_MEM_CACHELINE_SIZE> and returns the result.
506 844
507=item $ulong = $device->global_mem_cache_size 845=item $ulong = $device->global_mem_cache_size
508 846
509Calls C<clGetDeviceInfo> with C<CL_DEVICE_GLOBAL_MEM_CACHE_SIZE> and returns the result(s). 847Calls C<clGetDeviceInfo> with C<CL_DEVICE_GLOBAL_MEM_CACHE_SIZE> and returns the result.
510 848
511=item $ulong = $device->global_mem_size 849=item $ulong = $device->global_mem_size
512 850
513Calls C<clGetDeviceInfo> with C<CL_DEVICE_GLOBAL_MEM_SIZE> and returns the result(s). 851Calls C<clGetDeviceInfo> with C<CL_DEVICE_GLOBAL_MEM_SIZE> and returns the result.
514 852
515=item $ulong = $device->max_constant_buffer_size 853=item $ulong = $device->max_constant_buffer_size
516 854
517Calls C<clGetDeviceInfo> with C<CL_DEVICE_MAX_CONSTANT_BUFFER_SIZE> and returns the result(s). 855Calls C<clGetDeviceInfo> with C<CL_DEVICE_MAX_CONSTANT_BUFFER_SIZE> and returns the result.
518 856
519=item $uint = $device->max_constant_args 857=item $uint = $device->max_constant_args
520 858
521Calls C<clGetDeviceInfo> with C<CL_DEVICE_MAX_CONSTANT_ARGS> and returns the result(s). 859Calls C<clGetDeviceInfo> with C<CL_DEVICE_MAX_CONSTANT_ARGS> and returns the result.
522 860
523=item $device_local_mem_type = $device->local_mem_type 861=item $device_local_mem_type = $device->local_mem_type
524 862
525Calls C<clGetDeviceInfo> with C<CL_DEVICE_LOCAL_MEM_TYPE> and returns the result(s). 863Calls C<clGetDeviceInfo> with C<CL_DEVICE_LOCAL_MEM_TYPE> and returns the result.
526 864
527=item $ulong = $device->local_mem_size 865=item $ulong = $device->local_mem_size
528 866
529Calls C<clGetDeviceInfo> with C<CL_DEVICE_LOCAL_MEM_SIZE> and returns the result(s). 867Calls C<clGetDeviceInfo> with C<CL_DEVICE_LOCAL_MEM_SIZE> and returns the result.
530 868
531=item $boolean = $device->error_correction_support 869=item $boolean = $device->error_correction_support
532 870
533Calls C<clGetDeviceInfo> with C<CL_DEVICE_ERROR_CORRECTION_SUPPORT> and returns the result(s). 871Calls C<clGetDeviceInfo> with C<CL_DEVICE_ERROR_CORRECTION_SUPPORT> and returns the result.
534 872
535=item $int = $device->profiling_timer_resolution 873=item $int = $device->profiling_timer_resolution
536 874
537Calls C<clGetDeviceInfo> with C<CL_DEVICE_PROFILING_TIMER_RESOLUTION> and returns the result(s). 875Calls C<clGetDeviceInfo> with C<CL_DEVICE_PROFILING_TIMER_RESOLUTION> and returns the result.
538 876
539=item $boolean = $device->endian_little 877=item $boolean = $device->endian_little
540 878
541Calls C<clGetDeviceInfo> with C<CL_DEVICE_ENDIAN_LITTLE> and returns the result(s). 879Calls C<clGetDeviceInfo> with C<CL_DEVICE_ENDIAN_LITTLE> and returns the result.
542 880
543=item $boolean = $device->available 881=item $boolean = $device->available
544 882
545Calls C<clGetDeviceInfo> with C<CL_DEVICE_AVAILABLE> and returns the result(s). 883Calls C<clGetDeviceInfo> with C<CL_DEVICE_AVAILABLE> and returns the result.
546 884
547=item $boolean = $device->compiler_available 885=item $boolean = $device->compiler_available
548 886
549Calls C<clGetDeviceInfo> with C<CL_DEVICE_COMPILER_AVAILABLE> and returns the result(s). 887Calls C<clGetDeviceInfo> with C<CL_DEVICE_COMPILER_AVAILABLE> and returns the result.
550 888
551=item $device_exec_capabilities = $device->execution_capabilities 889=item $device_exec_capabilities = $device->execution_capabilities
552 890
553Calls C<clGetDeviceInfo> with C<CL_DEVICE_EXECUTION_CAPABILITIES> and returns the result(s). 891Calls C<clGetDeviceInfo> with C<CL_DEVICE_EXECUTION_CAPABILITIES> and returns the result.
554 892
555=item $command_queue_properties = $device->properties 893=item $command_queue_properties = $device->properties
556 894
557Calls C<clGetDeviceInfo> with C<CL_DEVICE_QUEUE_PROPERTIES> and returns the result(s). 895Calls C<clGetDeviceInfo> with C<CL_DEVICE_QUEUE_PROPERTIES> and returns the result.
558 896
559=item $ = $device->platform 897=item $ = $device->platform
560 898
561Calls C<clGetDeviceInfo> with C<CL_DEVICE_PLATFORM> and returns the result(s). 899Calls C<clGetDeviceInfo> with C<CL_DEVICE_PLATFORM> and returns the result.
562 900
563=item $string = $device->name 901=item $string = $device->name
564 902
565Calls C<clGetDeviceInfo> with C<CL_DEVICE_NAME> and returns the result(s). 903Calls C<clGetDeviceInfo> with C<CL_DEVICE_NAME> and returns the result.
566 904
567=item $string = $device->vendor 905=item $string = $device->vendor
568 906
569Calls C<clGetDeviceInfo> with C<CL_DEVICE_VENDOR> and returns the result(s). 907Calls C<clGetDeviceInfo> with C<CL_DEVICE_VENDOR> and returns the result.
570 908
571=item $string = $device->driver_version 909=item $string = $device->driver_version
572 910
573Calls C<clGetDeviceInfo> with C<CL_DRIVER_VERSION> and returns the result(s). 911Calls C<clGetDeviceInfo> with C<CL_DRIVER_VERSION> and returns the result.
574 912
575=item $string = $device->profile 913=item $string = $device->profile
576 914
577Calls C<clGetDeviceInfo> with C<CL_DEVICE_PROFILE> and returns the result(s). 915Calls C<clGetDeviceInfo> with C<CL_DEVICE_PROFILE> and returns the result.
578 916
579=item $string = $device->version 917=item $string = $device->version
580 918
581Calls C<clGetDeviceInfo> with C<CL_DEVICE_VERSION> and returns the result(s). 919Calls C<clGetDeviceInfo> with C<CL_DEVICE_VERSION> and returns the result.
582 920
583=item $string = $device->extensions 921=item $string = $device->extensions
584 922
585Calls C<clGetDeviceInfo> with C<CL_DEVICE_EXTENSIONS> and returns the result(s). 923Calls C<clGetDeviceInfo> with C<CL_DEVICE_EXTENSIONS> and returns the result.
586 924
587=item $uint = $device->preferred_vector_width_half 925=item $uint = $device->preferred_vector_width_half
588 926
589Calls C<clGetDeviceInfo> with C<CL_DEVICE_PREFERRED_VECTOR_WIDTH_HALF> and returns the result(s). 927Calls C<clGetDeviceInfo> with C<CL_DEVICE_PREFERRED_VECTOR_WIDTH_HALF> and returns the result.
590 928
591=item $uint = $device->native_vector_width_char 929=item $uint = $device->native_vector_width_char
592 930
593Calls C<clGetDeviceInfo> with C<CL_DEVICE_NATIVE_VECTOR_WIDTH_CHAR> and returns the result(s). 931Calls C<clGetDeviceInfo> with C<CL_DEVICE_NATIVE_VECTOR_WIDTH_CHAR> and returns the result.
594 932
595=item $uint = $device->native_vector_width_short 933=item $uint = $device->native_vector_width_short
596 934
597Calls C<clGetDeviceInfo> with C<CL_DEVICE_NATIVE_VECTOR_WIDTH_SHORT> and returns the result(s). 935Calls C<clGetDeviceInfo> with C<CL_DEVICE_NATIVE_VECTOR_WIDTH_SHORT> and returns the result.
598 936
599=item $uint = $device->native_vector_width_int 937=item $uint = $device->native_vector_width_int
600 938
601Calls C<clGetDeviceInfo> with C<CL_DEVICE_NATIVE_VECTOR_WIDTH_INT> and returns the result(s). 939Calls C<clGetDeviceInfo> with C<CL_DEVICE_NATIVE_VECTOR_WIDTH_INT> and returns the result.
602 940
603=item $uint = $device->native_vector_width_long 941=item $uint = $device->native_vector_width_long
604 942
605Calls C<clGetDeviceInfo> with C<CL_DEVICE_NATIVE_VECTOR_WIDTH_LONG> and returns the result(s). 943Calls C<clGetDeviceInfo> with C<CL_DEVICE_NATIVE_VECTOR_WIDTH_LONG> and returns the result.
606 944
607=item $uint = $device->native_vector_width_float 945=item $uint = $device->native_vector_width_float
608 946
609Calls C<clGetDeviceInfo> with C<CL_DEVICE_NATIVE_VECTOR_WIDTH_FLOAT> and returns the result(s). 947Calls C<clGetDeviceInfo> with C<CL_DEVICE_NATIVE_VECTOR_WIDTH_FLOAT> and returns the result.
610 948
611=item $uint = $device->native_vector_width_double 949=item $uint = $device->native_vector_width_double
612 950
613Calls C<clGetDeviceInfo> with C<CL_DEVICE_NATIVE_VECTOR_WIDTH_DOUBLE> and returns the result(s). 951Calls C<clGetDeviceInfo> with C<CL_DEVICE_NATIVE_VECTOR_WIDTH_DOUBLE> and returns the result.
614 952
615=item $uint = $device->native_vector_width_half 953=item $uint = $device->native_vector_width_half
616 954
617Calls C<clGetDeviceInfo> with C<CL_DEVICE_NATIVE_VECTOR_WIDTH_HALF> and returns the result(s). 955Calls C<clGetDeviceInfo> with C<CL_DEVICE_NATIVE_VECTOR_WIDTH_HALF> and returns the result.
618 956
619=item $device_fp_config = $device->double_fp_config 957=item $device_fp_config = $device->double_fp_config
620 958
621Calls C<clGetDeviceInfo> with C<CL_DEVICE_DOUBLE_FP_CONFIG> and returns the result(s). 959Calls C<clGetDeviceInfo> with C<CL_DEVICE_DOUBLE_FP_CONFIG> and returns the result.
622 960
623=item $device_fp_config = $device->half_fp_config 961=item $device_fp_config = $device->half_fp_config
624 962
625Calls C<clGetDeviceInfo> with C<CL_DEVICE_HALF_FP_CONFIG> and returns the result(s). 963Calls C<clGetDeviceInfo> with C<CL_DEVICE_HALF_FP_CONFIG> and returns the result.
626 964
627=item $boolean = $device->host_unified_memory 965=item $boolean = $device->host_unified_memory
628 966
629Calls C<clGetDeviceInfo> with C<CL_DEVICE_HOST_UNIFIED_MEMORY> and returns the result(s). 967Calls C<clGetDeviceInfo> with C<CL_DEVICE_HOST_UNIFIED_MEMORY> and returns the result.
630 968
631=item $device = $device->parent_device_ext 969=item $device = $device->parent_device_ext
632 970
633Calls C<clGetDeviceInfo> with C<CL_DEVICE_PARENT_DEVICE_EXT> and returns the result(s). 971Calls C<clGetDeviceInfo> with C<CL_DEVICE_PARENT_DEVICE_EXT> and returns the result.
634 972
635=item @device_partition_property_exts = $device->partition_types_ext 973=item @device_partition_property_exts = $device->partition_types_ext
636 974
637Calls C<clGetDeviceInfo> with C<CL_DEVICE_PARTITION_TYPES_EXT> and returns the result(s). 975Calls C<clGetDeviceInfo> with C<CL_DEVICE_PARTITION_TYPES_EXT> and returns the result.
638 976
639=item @device_partition_property_exts = $device->affinity_domains_ext 977=item @device_partition_property_exts = $device->affinity_domains_ext
640 978
641Calls C<clGetDeviceInfo> with C<CL_DEVICE_AFFINITY_DOMAINS_EXT> and returns the result(s). 979Calls C<clGetDeviceInfo> with C<CL_DEVICE_AFFINITY_DOMAINS_EXT> and returns the result.
642 980
643=item $uint = $device->reference_count_ext 981=item $uint = $device->reference_count_ext
644 982
645Calls C<clGetDeviceInfo> with C<CL_DEVICE_REFERENCE_COUNT_EXT > and returns the result(s). 983Calls C<clGetDeviceInfo> with C<CL_DEVICE_REFERENCE_COUNT_EXT> and returns the result.
646 984
647=item @device_partition_property_exts = $device->partition_style_ext 985=item @device_partition_property_exts = $device->partition_style_ext
648 986
649Calls C<clGetDeviceInfo> with C<CL_DEVICE_PARTITION_STYLE_EXT> and returns the result(s). 987Calls C<clGetDeviceInfo> with C<CL_DEVICE_PARTITION_STYLE_EXT> and returns the result.
650 988
651=for gengetinfo end device 989=for gengetinfo end device
652 990
653=back 991=back
654 992
655=head2 THE OpenCL::Context CLASS 993=head2 THE OpenCL::Context CLASS
656 994
657=over 4 995=over 4
658 996
997=item $prog = $ctx->build_program ($program, $options = "")
998
999This convenience function tries to build the program on all devices in
1000the context. If the build fails, then the function will C<croak> with the
1001build log. Otherwise ti returns the program object.
1002
1003The C<$program> can either be a C<OpenCL::Program> object or a string
1004containing the program. In the latter case, a program objetc will be
1005created automatically.
1006
1007=cut
1008
1009sub OpenCL::Context::build_program {
1010 my ($self, $prog, $options) = @_;
1011
1012 $prog = $self->program_with_source ($prog)
1013 unless ref $prog;
1014
1015 eval { $prog->build (undef, $options); 1 }
1016 or errno == BUILD_PROGRAM_FAILURE
1017 or errno == INVALID_BINARY # workaround nvidia bug
1018 or Carp::croak "OpenCL::Context->build_program: " . err2str;
1019
1020 # we check status for all devices
1021 for my $dev ($self->devices) {
1022 $prog->build_status ($dev) == BUILD_SUCCESS
1023 or Carp::croak "Building OpenCL program for device '" . $dev->name . "' failed:\n"
1024 . $prog->build_log ($dev);
1025 }
1026
1027 $prog
1028}
1029
659=item $queue = $ctx->queue ($device, $properties) 1030=item $queue = $ctx->queue ($device, $properties)
660 1031
661Create a new OpenCL::Queue object from the context and the given device. 1032Create a new OpenCL::Queue object from the context and the given device.
662 1033
663L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clCreateCommandQueue.html> 1034L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clCreateCommandQueue.html>
664 1035
1036Example: create an out-of-order queue.
1037
1038 $queue = $ctx->queue ($device, OpenCL::QUEUE_OUT_OF_ORDER_EXEC_MODE_ENABLE);
1039
665=item $ev = $ctx->user_event 1040=item $ev = $ctx->user_event
666 1041
667Creates a new OpenCL::UserEvent object. 1042Creates a new OpenCL::UserEvent object.
668 1043
669L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clCreateUserEvent.html> 1044L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clCreateUserEvent.html>
670 1045
671=item $buf = $ctx->buffer ($flags, $len) 1046=item $buf = $ctx->buffer ($flags, $len)
672 1047
673Creates a new OpenCL::Buffer object with the given flags and octet-size. 1048Creates a new OpenCL::Buffer (actually OpenCL::BufferObj) object with the
1049given flags and octet-size.
674 1050
675L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clCreateBuffer.html> 1051L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clCreateBuffer.html>
676 1052
677=item $buf = $ctx->buffer_sv ($flags, $data) 1053=item $buf = $ctx->buffer_sv ($flags, $data)
678 1054
679Creates a new OpenCL::Buffer object and initialise it with the given data values. 1055Creates a new OpenCL::Buffer (actually OpenCL::BufferObj) object and
1056initialise it with the given data values.
1057
1058=item $img = $ctx->image ($self, $flags, $channel_order, $channel_type, $type, $width, $height, $depth = 0, $array_size = 0, $row_pitch = 0, $slice_pitch = 0, $num_mip_level = 0, $num_samples = 0, $*data = &PL_sv_undef)
1059
1060Creates a new OpenCL::Image object and optionally initialises it with
1061the given data values.
1062
1063L<http://www.khronos.org/registry/cl/sdk/1.2/docs/man/xhtml/clCreateImage.html>
680 1064
681=item $img = $ctx->image2d ($flags, $channel_order, $channel_type, $width, $height, $row_pitch = 0, $data = undef) 1065=item $img = $ctx->image2d ($flags, $channel_order, $channel_type, $width, $height, $row_pitch = 0, $data = undef)
682 1066
683Creates a new OpenCL::Image2D object and optionally initialises it with the given data values. 1067Creates a new OpenCL::Image2D object and optionally initialises it with
1068the given data values.
684 1069
685L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clCreateImage2D.html> 1070L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clCreateImage2D.html>
686 1071
687=item $img = $ctx->image3d ($flags, $channel_order, $channel_type, $width, $height, $depth, $row_pitch = 0, $slice_pitch = 0, $data = undef) 1072=item $img = $ctx->image3d ($flags, $channel_order, $channel_type, $width, $height, $depth, $row_pitch = 0, $slice_pitch = 0, $data = undef)
688 1073
689Creates a new OpenCL::Image3D object and optionally initialises it with the given data values. 1074Creates a new OpenCL::Image3D object and optionally initialises it with
1075the given data values.
690 1076
691L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clCreateImage3D.html> 1077L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clCreateImage3D.html>
1078
1079=item $buffer = $ctx->gl_buffer ($flags, $bufobj)
1080
1081Creates a new OpenCL::Buffer (actually OpenCL::BufferObj) object that refers to the given
1082OpenGL buffer object.
1083
1084http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clCreateFromGLBuffer.html
1085
1086=item $img = $ctx->gl_texture ($flags, $target, $miplevel, $texture)
1087
1088Creates a new OpenCL::Image object that refers to the given OpenGL
1089texture object or buffer.
1090
1091http://www.khronos.org/registry/cl/sdk/1.2/docs/man/xhtml/clCreateFromGLTexture.html
1092
1093=item $img = $ctx->gl_texture2d ($flags, $target, $miplevel, $texture)
1094
1095Creates a new OpenCL::Image2D object that refers to the given OpenGL
10962D texture object.
1097
1098http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clCreateFromGLTexture2D.html
1099
1100=item $img = $ctx->gl_texture3d ($flags, $target, $miplevel, $texture)
1101
1102Creates a new OpenCL::Image3D object that refers to the given OpenGL
11033D texture object.
1104
1105http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clCreateFromGLTexture3D.html
1106
1107=item $ctx->gl_renderbuffer ($flags, $renderbuffer)
1108
1109Creates a new OpenCL::Image2D object that refers to the given OpenGL
1110render buffer.
1111
1112http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clCreateFromGLRenderbuffer.html
692 1113
693=item @formats = $ctx->supported_image_formats ($flags, $image_type) 1114=item @formats = $ctx->supported_image_formats ($flags, $image_type)
694 1115
695Returns a list of matching image formats - each format is an arrayref with 1116Returns a list of matching image formats - each format is an arrayref with
696two values, $channel_order and $channel_type, in it. 1117two values, $channel_order and $channel_type, in it.
… …
717 1138
718=for gengetinfo begin context 1139=for gengetinfo begin context
719 1140
720=item $uint = $context->reference_count 1141=item $uint = $context->reference_count
721 1142
722Calls C<clGetContextInfo> with C<CL_CONTEXT_REFERENCE_COUNT> and returns the result(s). 1143Calls C<clGetContextInfo> with C<CL_CONTEXT_REFERENCE_COUNT> and returns the result.
723 1144
724=item @devices = $context->devices 1145=item @devices = $context->devices
725 1146
726Calls C<clGetContextInfo> with C<CL_CONTEXT_DEVICES> and returns the result(s). 1147Calls C<clGetContextInfo> with C<CL_CONTEXT_DEVICES> and returns the result.
727 1148
728=item @property_ints = $context->properties 1149=item @property_ints = $context->properties
729 1150
730Calls C<clGetContextInfo> with C<CL_CONTEXT_PROPERTIES> and returns the result(s). 1151Calls C<clGetContextInfo> with C<CL_CONTEXT_PROPERTIES> and returns the result.
731 1152
732=item $uint = $context->num_devices 1153=item $uint = $context->num_devices
733 1154
734Calls C<clGetContextInfo> with C<CL_CONTEXT_NUM_DEVICES> and returns the result(s). 1155Calls C<clGetContextInfo> with C<CL_CONTEXT_NUM_DEVICES> and returns the result.
735 1156
736=for gengetinfo end context 1157=for gengetinfo end context
737 1158
738=back 1159=back
739 1160
740=head2 THE OpenCL::Queue CLASS 1161=head2 THE OpenCL::Queue CLASS
741 1162
742An OpenCL::Queue represents an execution queue for OpenCL. You execute 1163An OpenCL::Queue represents an execution queue for OpenCL. You execute
743requests by calling their respective C<enqueue_xxx> method and waitinf for 1164requests by calling their respective method and waiting for it to complete
744it to complete in some way. 1165in some way.
745 1166
746All the enqueue methods return an event object that can be used to wait 1167Most methods that enqueue some request return an event object that can
747for completion, unless the method is called in void context, in which case 1168be used to wait for completion (optionally using a callback), unless
748no event object is created. 1169the method is called in void context, in which case no event object is
1170created.
749 1171
750They also allow you to specify any number of other event objects that this 1172They also allow you to specify any number of other event objects that this
751request has to wait for before it starts executing, by simply passing the 1173request has to wait for before it starts executing, by simply passing the
752event objects as extra parameters to the enqueue methods. 1174event objects as extra parameters to the enqueue methods. To simplify
1175program design, this module ignores any C<undef> values in the list of
1176events. This makes it possible to code operations such as this, without
1177having to put a valid event object into C<$event> first:
1178
1179 $event = $queue->xxx (..., $event);
753 1180
754Queues execute in-order by default, without any parallelism, so in most 1181Queues execute in-order by default, without any parallelism, so in most
755cases (i.e. you use only one queue) it's not necessary to wait for or 1182cases (i.e. you use only one queue) it's not necessary to wait for or
756create event objects. 1183create event objects, althoguh an our of order queue is often a bit
1184faster.
757 1185
758=over 4 1186=over 4
759 1187
760=item $ev = $queue->enqueue_read_buffer ($buffer, $blocking, $offset, $len, $data, $wait_events...) 1188=item $ev = $queue->read_buffer ($buffer, $blocking, $offset, $len, $data, $wait_events...)
761 1189
762Reads data from buffer into the given string. 1190Reads data from buffer into the given string.
763 1191
764L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clEnqueueReadBuffer.html> 1192L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clEnqueueReadBuffer.html>
765 1193
766=item $ev = $queue->enqueue_write_buffer ($buffer, $blocking, $offset, $data, $wait_events...) 1194=item $ev = $queue->write_buffer ($buffer, $blocking, $offset, $data, $wait_events...)
767 1195
768Writes data to buffer from the given string. 1196Writes data to buffer from the given string.
769 1197
770L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clEnqueueWriteBuffer.html> 1198L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clEnqueueWriteBuffer.html>
771 1199
772=item $ev = $queue->enqueue_copy_buffer ($src, $dst, $src_offset, $dst_offset, $len, $wait_events...) 1200=item $ev = $queue->copy_buffer ($src, $dst, $src_offset, $dst_offset, $len, $wait_events...)
773 1201
774L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clEnqueueCopyBuffer.html> 1202L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clEnqueueCopyBuffer.html>
775 1203
1204=item $ev = $queue->read_buffer_rect (OpenCL::Memory buf, cl_bool blocking, $buf_x, $buf_y, $buf_z, $host_x, $host_y, $host_z, $width, $height, $depth, $buf_row_pitch, $buf_slice_pitch, $host_row_pitch, $host_slice_pitch, $data, $wait_events...)
1205
1206http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clEnqueueReadBufferRect.html
1207
1208=item $ev = $queue->write_buffer_rect (OpenCL::Memory buf, cl_bool blocking, $buf_x, $buf_y, $buf_z, $host_x, $host_y, $host_z, $width, $height, $depth, $buf_row_pitch, $buf_slice_pitch, $host_row_pitch, $host_slice_pitch, $data, $wait_events...)
1209
1210http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clEnqueueWriteBufferRect.html
1211
776=item $ev = $queue->enqueue_read_image ($src, $blocking, $x, $y, $z, $width, $height, $depth, $row_pitch, $slice_pitch, $data, $wait_events...) 1212=item $ev = $queue->read_image ($src, $blocking, $x, $y, $z, $width, $height, $depth, $row_pitch, $slice_pitch, $data, $wait_events...)
1213
1214L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clEnqueueCopyBufferRect.html>
1215
1216=item $ev = $queue->copy_buffer_to_image ($src_buffer, $dst_image, $src_offset, $dst_x, $dst_y, $dst_z, $width, $height, $depth, $wait_events...)
777 1217
778L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clEnqueueReadImage.html> 1218L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clEnqueueReadImage.html>
779 1219
780=item $ev = $queue->enqueue_write_image ($src, $blocking, $x, $y, $z, $width, $height, $depth, $row_pitch, $slice_pitch, $data, $wait_events...) 1220=item $ev = $queue->write_image ($src, $blocking, $x, $y, $z, $width, $height, $depth, $row_pitch, $slice_pitch, $data, $wait_events...)
781 1221
782L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clEnqueueWriteImage.html> 1222L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clEnqueueWriteImage.html>
783 1223
1224=item $ev = $queue->copy_image ($src_image, $dst_image, $src_x, $src_y, $src_z, $dst_x, $dst_y, $dst_z, $width, $height, $depth, $wait_events...)
1225
1226L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clEnqueueCopyImage.html>
1227
1228=item $ev = $queue->copy_image_to_buffer ($src_image, $dst_image, $src_x, $src_y, $src_z, $width, $height, $depth, $dst_offset, $wait_events...)
1229
1230L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clEnqueueCopyImageToBuffer.html>
1231
784=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...) 1232=item $ev = $queue->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...)
785 1233
786Yeah. 1234Yeah.
787 1235
788L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clEnqueueCopyBufferRect.html>
789
790=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...)
791
792L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clEnqueueCopyBufferToImage.html>. 1236L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clEnqueueCopyBufferToImage.html>.
793 1237
794=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...) 1238=item $ev = $queue->fill_buffer ($mem, $pattern, $offset, $size, ...)
795 1239
1240Fills the given buffer object with repeated applications of C<$pattern>,
1241starting at C<$offset> for C<$size> octets.
1242
1243L<http://www.khronos.org/registry/cl/sdk/1.2/docs/man/xhtml/clEnqueueFillBuffer.html>
1244
1245=item $ev = $queue->fill_image ($img, $r, $g, $b, $a, $x, $y, $z, $width, $height, $depth, ...)
1246
1247Fills the given image area with the given rgba colour components. The
1248components are normally floating point values between C<0> and C<1>,
1249except when the image channel data type is a signe dor unsigned
1250unnormalised format, in which case the range is determined by the format.
1251
796L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clEnqueueCopyImage.html> 1252L<http://www.khronos.org/registry/cl/sdk/1.2/docs/man/xhtml/clEnqueueFillImage.html>
797 1253
798=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...)
799
800L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clEnqueueCopyImageToBuffer.html>
801
802=item $ev = $queue->enqueue_task ($kernel, $wait_events...) 1254=item $ev = $queue->task ($kernel, $wait_events...)
803 1255
804L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clEnqueueTask.html> 1256L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clEnqueueTask.html>
805 1257
806=item $ev = $queue->enqueue_nd_range_kernel ($kernel, @$global_work_offset, @$global_work_size, @$local_work_size, $wait_events...) 1258=item $ev = $queue->nd_range_kernel ($kernel, \@global_work_offset, \@global_work_size, \@local_work_size, $wait_events...)
807 1259
808Enqueues a kernel execution. 1260Enqueues a kernel execution.
809 1261
810@$global_work_size must be specified as a reference to an array of 1262\@global_work_size must be specified as a reference to an array of
811integers specifying the work sizes (element counts). 1263integers specifying the work sizes (element counts).
812 1264
813@$global_work_offset must be either C<undef> (in which case all offsets 1265\@global_work_offset must be either C<undef> (in which case all offsets
814are C<0>), or a reference to an array of work offsets, with the same number 1266are C<0>), or a reference to an array of work offsets, with the same number
815of elements as @$global_work_size. 1267of elements as \@global_work_size.
816 1268
817@$local_work_size must be either C<undef> (in which case the 1269\@local_work_size must be either C<undef> (in which case the
818implementation is supposed to choose good local work sizes), or a 1270implementation is supposed to choose good local work sizes), or a
819reference to an array of local work sizes, with the same number of 1271reference to an array of local work sizes, with the same number of
820elements as @$global_work_size. 1272elements as \@global_work_size.
821 1273
822L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clEnqueueNDRangeKernel.html> 1274L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clEnqueueNDRangeKernel.html>
823 1275
824=item $ev = $queue->enqueue_marker 1276=item $ev = $queue->acquire_gl_objects ([object, ...], $wait_events...)
825 1277
1278Enqueues a list (an array-ref of OpenCL::Memory objects) to be acquired
1279for subsequent OpenCL usage.
1280
826L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clEnqueueMarker.html> 1281L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clEnqueueAcquireGLObjects.html>
827 1282
1283=item $ev = $queue->release_gl_objects ([object, ...], $wait_events...)
1284
1285Enqueues a list (an array-ref of OpenCL::Memory objects) to be released
1286for subsequent OpenGL usage.
1287
1288L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clEnqueueReleaseGLObjects.html>
1289
828=item $ev = $queue->enqueue_wait_for_events ($wait_events...) 1290=item $ev = $queue->wait_for_events ($wait_events...)
829 1291
830L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clEnqueueWaitForEvents.html> 1292L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clEnqueueWaitForEvents.html>
831 1293
832=item $queue->enqueue_barrier 1294=item $ev = $queue->marker ($wait_events...)
833 1295
1296L<http://www.khronos.org/registry/cl/sdk/1.2/docs/man/xhtml/clEnqueueMarkerWithWaitList.html>
1297
1298=item $ev = $queue->barrier ($wait_events...)
1299
834L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clEnqueueBarrier.html> 1300L<http://www.khronos.org/registry/cl/sdk/1.2/docs/man/xhtml/clEnqueueBarrierWithWaitList.html>
835 1301
836=item $queue->flush 1302=item $queue->flush
837 1303
838L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clFlush.html> 1304L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clFlush.html>
839 1305
… …
849 1315
850=for gengetinfo begin command_queue 1316=for gengetinfo begin command_queue
851 1317
852=item $ctx = $command_queue->context 1318=item $ctx = $command_queue->context
853 1319
854Calls C<clGetCommandQueueInfo> with C<CL_QUEUE_CONTEXT> and returns the result(s). 1320Calls C<clGetCommandQueueInfo> with C<CL_QUEUE_CONTEXT> and returns the result.
855 1321
856=item $device = $command_queue->device 1322=item $device = $command_queue->device
857 1323
858Calls C<clGetCommandQueueInfo> with C<CL_QUEUE_DEVICE> and returns the result(s). 1324Calls C<clGetCommandQueueInfo> with C<CL_QUEUE_DEVICE> and returns the result.
859 1325
860=item $uint = $command_queue->reference_count 1326=item $uint = $command_queue->reference_count
861 1327
862Calls C<clGetCommandQueueInfo> with C<CL_QUEUE_REFERENCE_COUNT> and returns the result(s). 1328Calls C<clGetCommandQueueInfo> with C<CL_QUEUE_REFERENCE_COUNT> and returns the result.
863 1329
864=item $command_queue_properties = $command_queue->properties 1330=item $command_queue_properties = $command_queue->properties
865 1331
866Calls C<clGetCommandQueueInfo> with C<CL_QUEUE_PROPERTIES> and returns the result(s). 1332Calls C<clGetCommandQueueInfo> with C<CL_QUEUE_PROPERTIES> and returns the result.
867 1333
868=for gengetinfo end command_queue 1334=for gengetinfo end command_queue
869 1335
870=back 1336=back
871 1337
… …
884 1350
885=for gengetinfo begin mem 1351=for gengetinfo begin mem
886 1352
887=item $mem_object_type = $mem->type 1353=item $mem_object_type = $mem->type
888 1354
889Calls C<clGetMemObjectInfo> with C<CL_MEM_TYPE> and returns the result(s). 1355Calls C<clGetMemObjectInfo> with C<CL_MEM_TYPE> and returns the result.
890 1356
891=item $mem_flags = $mem->flags 1357=item $mem_flags = $mem->flags
892 1358
893Calls C<clGetMemObjectInfo> with C<CL_MEM_FLAGS> and returns the result(s). 1359Calls C<clGetMemObjectInfo> with C<CL_MEM_FLAGS> and returns the result.
894 1360
895=item $int = $mem->size 1361=item $int = $mem->size
896 1362
897Calls C<clGetMemObjectInfo> with C<CL_MEM_SIZE> and returns the result(s). 1363Calls C<clGetMemObjectInfo> with C<CL_MEM_SIZE> and returns the result.
898 1364
899=item $ptr_value = $mem->host_ptr 1365=item $ptr_value = $mem->host_ptr
900 1366
901Calls C<clGetMemObjectInfo> with C<CL_MEM_HOST_PTR> and returns the result(s). 1367Calls C<clGetMemObjectInfo> with C<CL_MEM_HOST_PTR> and returns the result.
902 1368
903=item $uint = $mem->map_count 1369=item $uint = $mem->map_count
904 1370
905Calls C<clGetMemObjectInfo> with C<CL_MEM_MAP_COUNT> and returns the result(s). 1371Calls C<clGetMemObjectInfo> with C<CL_MEM_MAP_COUNT> and returns the result.
906 1372
907=item $uint = $mem->reference_count 1373=item $uint = $mem->reference_count
908 1374
909Calls C<clGetMemObjectInfo> with C<CL_MEM_REFERENCE_COUNT> and returns the result(s). 1375Calls C<clGetMemObjectInfo> with C<CL_MEM_REFERENCE_COUNT> and returns the result.
910 1376
911=item $ctx = $mem->context 1377=item $ctx = $mem->context
912 1378
913Calls C<clGetMemObjectInfo> with C<CL_MEM_CONTEXT> and returns the result(s). 1379Calls C<clGetMemObjectInfo> with C<CL_MEM_CONTEXT> and returns the result.
914 1380
915=item $mem = $mem->associated_memobject 1381=item $mem = $mem->associated_memobject
916 1382
917Calls C<clGetMemObjectInfo> with C<CL_MEM_ASSOCIATED_MEMOBJECT> and returns the result(s). 1383Calls C<clGetMemObjectInfo> with C<CL_MEM_ASSOCIATED_MEMOBJECT> and returns the result.
918 1384
919=item $int = $mem->offset 1385=item $int = $mem->offset
920 1386
921Calls C<clGetMemObjectInfo> with C<CL_MEM_OFFSET> and returns the result(s). 1387Calls C<clGetMemObjectInfo> with C<CL_MEM_OFFSET> and returns the result.
922 1388
923=for gengetinfo end mem 1389=for gengetinfo end mem
924 1390
1391=item ($type, $name) = $mem->gl_object_info
1392
1393Returns the OpenGL object type (e.g. OpenCL::GL_OBJECT_TEXTURE2D) and the
1394object "name" (e.g. the texture name) used to create this memory object.
1395
1396L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clGetGLObjectInfo.html>
1397
925=back 1398=back
926 1399
1400=head2 THE OpenCL::Buffer CLASS
1401
1402This is a subclass of OpenCL::Memory, and the superclass of
1403OpenCL::BufferObj. Its purpose is simply to distinguish between buffers
1404and sub-buffers.
1405
1406=head2 THE OpenCL::BufferObj CLASS
1407
1408This is a subclass of OpenCL::Buffer and thus OpenCL::Memory. It exists
1409because one cna create sub buffers of OpenLC::BufferObj objects, but not
1410sub buffers from these sub buffers.
1411
1412=over 4
1413
1414=item $subbuf = $buf_obj->sub_buffer_region ($flags, $origin, $size)
1415
1416Creates an OpenCL::Buffer objects from this buffer and returns it. The
1417C<buffer_create_type> is assumed to be C<CL_BUFFER_CREATE_TYPE_REGION>.
1418
1419L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clCreateSubBuffer.html>
1420
1421=back
1422
927=head2 THE OpenCL::Image CLASS 1423=head2 THE OpenCL::Image CLASS
928 1424
929This is the superclass of all image objects - OpenCL::Image2D and OpenCL::Image3D. 1425This is the superclass of all image objects - OpenCL::Image1D,
1426OpenCL::Image1DArray, OpenCL::Image1DBuffer, OpenCL::Image2D,
1427OpenCL::Image2DArray and OpenCL::Image3D.
930 1428
931=over 4 1429=over 4
932 1430
933=item $packed_value = $ev->image_info ($name) 1431=item $packed_value = $image->image_info ($name)
934 1432
935See C<< $platform->info >> for details. 1433See C<< $platform->info >> for details.
936 1434
937The reason this method is not called C<info> is that there already is an 1435The reason this method is not called C<info> is that there already is an
938C<< ->info >> method inherited from C<OpenCL::Memory>. 1436C<< ->info >> method inherited from C<OpenCL::Memory>.
939 1437
940L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clGetImageInfo.html> 1438L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clGetImageInfo.html>
941 1439
1440=item ($channel_order, $channel_data_type) = $image->format
1441
1442Returns the channel order and type used to create the image by calling
1443C<clGetImageInfo> with C<CL_IMAGE_FORMAT>.
1444
942=for gengetinfo begin image 1445=for gengetinfo begin image
943 1446
944=item $int = $image->element_size 1447=item $int = $image->element_size
945 1448
946Calls C<clGetImageInfo> with C<CL_IMAGE_ELEMENT_SIZE> and returns the result(s). 1449Calls C<clGetImageInfo> with C<CL_IMAGE_ELEMENT_SIZE> and returns the result.
947 1450
948=item $int = $image->row_pitch 1451=item $int = $image->row_pitch
949 1452
950Calls C<clGetImageInfo> with C<CL_IMAGE_ROW_PITCH> and returns the result(s). 1453Calls C<clGetImageInfo> with C<CL_IMAGE_ROW_PITCH> and returns the result.
951 1454
952=item $int = $image->slice_pitch 1455=item $int = $image->slice_pitch
953 1456
954Calls C<clGetImageInfo> with C<CL_IMAGE_SLICE_PITCH> and returns the result(s). 1457Calls C<clGetImageInfo> with C<CL_IMAGE_SLICE_PITCH> and returns the result.
955 1458
956=item $int = $image->width 1459=item $int = $image->width
957 1460
958Calls C<clGetImageInfo> with C<CL_IMAGE_WIDTH> and returns the result(s). 1461Calls C<clGetImageInfo> with C<CL_IMAGE_WIDTH> and returns the result.
959 1462
960=item $int = $image->height 1463=item $int = $image->height
961 1464
962Calls C<clGetImageInfo> with C<CL_IMAGE_HEIGHT> and returns the result(s). 1465Calls C<clGetImageInfo> with C<CL_IMAGE_HEIGHT> and returns the result.
963 1466
964=item $int = $image->depth 1467=item $int = $image->depth
965 1468
966Calls C<clGetImageInfo> with C<CL_IMAGE_DEPTH> and returns the result(s). 1469Calls C<clGetImageInfo> with C<CL_IMAGE_DEPTH> and returns the result.
967 1470
968=for gengetinfo end image 1471=for gengetinfo end image
969 1472
1473=for gengetinfo begin gl_texture
1474
1475=item $GLenum = $gl_texture->target
1476
1477Calls C<clGetGLTextureInfo> with C<CL_GL_TEXTURE_TARGET> and returns the result.
1478
1479=item $GLint = $gl_texture->gl_mipmap_level
1480
1481Calls C<clGetGLTextureInfo> with C<CL_GL_MIPMAP_LEVEL> and returns the result.
1482
1483=for gengetinfo end gl_texture
1484
970=back 1485=back
971 1486
972=head2 THE OpenCL::Sampler CLASS 1487=head2 THE OpenCL::Sampler CLASS
973 1488
974=over 4 1489=over 4
… …
981 1496
982=for gengetinfo begin sampler 1497=for gengetinfo begin sampler
983 1498
984=item $uint = $sampler->reference_count 1499=item $uint = $sampler->reference_count
985 1500
986Calls C<clGetSamplerInfo> with C<CL_SAMPLER_REFERENCE_COUNT> and returns the result(s). 1501Calls C<clGetSamplerInfo> with C<CL_SAMPLER_REFERENCE_COUNT> and returns the result.
987 1502
988=item $ctx = $sampler->context 1503=item $ctx = $sampler->context
989 1504
990Calls C<clGetSamplerInfo> with C<CL_SAMPLER_CONTEXT> and returns the result(s). 1505Calls C<clGetSamplerInfo> with C<CL_SAMPLER_CONTEXT> and returns the result.
991 1506
992=item $addressing_mode = $sampler->normalized_coords 1507=item $addressing_mode = $sampler->normalized_coords
993 1508
994Calls C<clGetSamplerInfo> with C<CL_SAMPLER_NORMALIZED_COORDS> and returns the result(s). 1509Calls C<clGetSamplerInfo> with C<CL_SAMPLER_NORMALIZED_COORDS> and returns the result.
995 1510
996=item $filter_mode = $sampler->addressing_mode 1511=item $filter_mode = $sampler->addressing_mode
997 1512
998Calls C<clGetSamplerInfo> with C<CL_SAMPLER_ADDRESSING_MODE> and returns the result(s). 1513Calls C<clGetSamplerInfo> with C<CL_SAMPLER_ADDRESSING_MODE> and returns the result.
999 1514
1000=item $boolean = $sampler->filter_mode 1515=item $boolean = $sampler->filter_mode
1001 1516
1002Calls C<clGetSamplerInfo> with C<CL_SAMPLER_FILTER_MODE> and returns the result(s). 1517Calls C<clGetSamplerInfo> with C<CL_SAMPLER_FILTER_MODE> and returns the result.
1003 1518
1004=for gengetinfo end sampler 1519=for gengetinfo end sampler
1005 1520
1006=back 1521=back
1007 1522
1008=head2 THE OpenCL::Program CLASS 1523=head2 THE OpenCL::Program CLASS
1009 1524
1010=over 4 1525=over 4
1011 1526
1012=item $program->build ($device, $options = "") 1527=item $program->build (\@devices = undef, $options = "", $cb->($program) = undef)
1013 1528
1014Tries to build the program with the givne options. 1529Tries to build the program with the given options. See also the
1530C<$ctx->build> convenience function.
1531
1532If a callback is specified, then it will be called when compilation is
1533finished. Note that many OpenCL implementations block your program while
1534compiling whether you use a callback or not. See C<build_async> if you
1535want to make sure the build is done in the background.
1536
1537Note that some OpenCL implementations act up badly, and don't call the
1538callback in some error cases (but call it in others). This implementation
1539assumes the callback will always be called, and leaks memory if this is
1540not so. So best make sure you don't pass in invalid values.
1541
1542Some implementations fail with C<OpenCL::INVALID_BINARY> when the
1543compilation state is successful but some later stage fails.
1015 1544
1016L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clBuildProgram.html> 1545L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clBuildProgram.html>
1546
1547=item $program->build_async (\@devices = undef, $options = "", $cb->($program) = undef)
1548
1549Similar to C<< ->build >>, except it starts a thread, and never fails (you
1550need to check the compilation status form the callback, or by polling).
1017 1551
1018=item $packed_value = $program->build_info ($device, $name) 1552=item $packed_value = $program->build_info ($device, $name)
1019 1553
1020Similar to C<< $platform->info >>, but returns build info for a previous 1554Similar to C<< $platform->info >>, but returns build info for a previous
1021build attempt for the given device. 1555build attempt for the given device.
… …
1027Creates an OpenCL::Kernel object out of the named C<__kernel> function in 1561Creates an OpenCL::Kernel object out of the named C<__kernel> function in
1028the program. 1562the program.
1029 1563
1030L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clCreateKernel.html> 1564L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clCreateKernel.html>
1031 1565
1566=item @kernels = $program->kernels_in_program
1567
1568Returns all kernels successfully compiled for all devices in program.
1569
1570http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clCreateKernelsInProgram.html
1571
1032=for gengetinfo begin program_build 1572=for gengetinfo begin program_build
1033 1573
1034=item $build_status = $program->build_status ($device) 1574=item $build_status = $program->build_status ($device)
1035 1575
1036Calls C<clGetProgramBuildInfo> with C<CL_PROGRAM_BUILD_STATUS> and returns the result(s). 1576Calls C<clGetProgramBuildInfo> with C<CL_PROGRAM_BUILD_STATUS> and returns the result.
1037 1577
1038=item $string = $program->build_options ($device) 1578=item $string = $program->build_options ($device)
1039 1579
1040Calls C<clGetProgramBuildInfo> with C<CL_PROGRAM_BUILD_OPTIONS> and returns the result(s). 1580Calls C<clGetProgramBuildInfo> with C<CL_PROGRAM_BUILD_OPTIONS> and returns the result.
1041 1581
1042=item $string = $program->build_log ($device) 1582=item $string = $program->build_log ($device)
1043 1583
1044Calls C<clGetProgramBuildInfo> with C<CL_PROGRAM_BUILD_LOG> and returns the result(s). 1584Calls C<clGetProgramBuildInfo> with C<CL_PROGRAM_BUILD_LOG> and returns the result.
1045 1585
1046=for gengetinfo end program_build 1586=for gengetinfo end program_build
1047 1587
1048=item $packed_value = $program->info ($name) 1588=item $packed_value = $program->info ($name)
1049 1589
… …
1053 1593
1054=for gengetinfo begin program 1594=for gengetinfo begin program
1055 1595
1056=item $uint = $program->reference_count 1596=item $uint = $program->reference_count
1057 1597
1058Calls C<clGetProgramInfo> with C<CL_PROGRAM_REFERENCE_COUNT> and returns the result(s). 1598Calls C<clGetProgramInfo> with C<CL_PROGRAM_REFERENCE_COUNT> and returns the result.
1059 1599
1060=item $ctx = $program->context 1600=item $ctx = $program->context
1061 1601
1062Calls C<clGetProgramInfo> with C<CL_PROGRAM_CONTEXT> and returns the result(s). 1602Calls C<clGetProgramInfo> with C<CL_PROGRAM_CONTEXT> and returns the result.
1063 1603
1064=item $uint = $program->num_devices 1604=item $uint = $program->num_devices
1065 1605
1066Calls C<clGetProgramInfo> with C<CL_PROGRAM_NUM_DEVICES> and returns the result(s). 1606Calls C<clGetProgramInfo> with C<CL_PROGRAM_NUM_DEVICES> and returns the result.
1067 1607
1068=item @devices = $program->devices 1608=item @devices = $program->devices
1069 1609
1070Calls C<clGetProgramInfo> with C<CL_PROGRAM_DEVICES> and returns the result(s). 1610Calls C<clGetProgramInfo> with C<CL_PROGRAM_DEVICES> and returns the result.
1071 1611
1072=item $string = $program->source 1612=item $string = $program->source
1073 1613
1074Calls C<clGetProgramInfo> with C<CL_PROGRAM_SOURCE> and returns the result(s). 1614Calls C<clGetProgramInfo> with C<CL_PROGRAM_SOURCE> and returns the result.
1075 1615
1076=item @ints = $program->binary_sizes 1616=item @ints = $program->binary_sizes
1077 1617
1078Calls C<clGetProgramInfo> with C<CL_PROGRAM_BINARY_SIZES> and returns the result(s). 1618Calls C<clGetProgramInfo> with C<CL_PROGRAM_BINARY_SIZES> and returns the result.
1079 1619
1080=for gengetinfo end program 1620=for gengetinfo end program
1081 1621
1622=item @blobs = $program->binaries
1623
1624Returns a string for the compiled binary for every device associated with
1625the program, empty strings indicate missing programs, and an empty result
1626means no program binaries are available.
1627
1628These "binaries" are often, in fact, informative low-level assembly
1629sources.
1630
1631L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clGetProgramInfo.html>
1632
1082=back 1633=back
1083 1634
1084=head2 THE OpenCL::Kernel CLASS 1635=head2 THE OpenCL::Kernel CLASS
1085 1636
1086=over 4 1637=over 4
… …
1093 1644
1094=for gengetinfo begin kernel 1645=for gengetinfo begin kernel
1095 1646
1096=item $string = $kernel->function_name 1647=item $string = $kernel->function_name
1097 1648
1098Calls C<clGetKernelInfo> with C<CL_KERNEL_FUNCTION_NAME> and returns the result(s). 1649Calls C<clGetKernelInfo> with C<CL_KERNEL_FUNCTION_NAME> and returns the result.
1099 1650
1100=item $uint = $kernel->num_args 1651=item $uint = $kernel->num_args
1101 1652
1102Calls C<clGetKernelInfo> with C<CL_KERNEL_NUM_ARGS> and returns the result(s). 1653Calls C<clGetKernelInfo> with C<CL_KERNEL_NUM_ARGS> and returns the result.
1103 1654
1104=item $uint = $kernel->reference_count 1655=item $uint = $kernel->reference_count
1105 1656
1106Calls C<clGetKernelInfo> with C<CL_KERNEL_REFERENCE_COUNT> and returns the result(s). 1657Calls C<clGetKernelInfo> with C<CL_KERNEL_REFERENCE_COUNT> and returns the result.
1107 1658
1108=item $ctx = $kernel->context 1659=item $ctx = $kernel->context
1109 1660
1110Calls C<clGetKernelInfo> with C<CL_KERNEL_CONTEXT> and returns the result(s). 1661Calls C<clGetKernelInfo> with C<CL_KERNEL_CONTEXT> and returns the result.
1111 1662
1112=item $program = $kernel->program 1663=item $program = $kernel->program
1113 1664
1114Calls C<clGetKernelInfo> with C<CL_KERNEL_PROGRAM> and returns the result(s). 1665Calls C<clGetKernelInfo> with C<CL_KERNEL_PROGRAM> and returns the result.
1115 1666
1116=for gengetinfo end kernel 1667=for gengetinfo end kernel
1117 1668
1118=item $packed_value = $kernel->work_group_info ($device, $name) 1669=item $packed_value = $kernel->work_group_info ($device, $name)
1119 1670
… …
1126 1677
1127=for gengetinfo begin kernel_work_group 1678=for gengetinfo begin kernel_work_group
1128 1679
1129=item $int = $kernel->work_group_size ($device) 1680=item $int = $kernel->work_group_size ($device)
1130 1681
1131Calls C<clGetKernelWorkGroupInfo> with C<CL_KERNEL_WORK_GROUP_SIZE> and returns the result(s). 1682Calls C<clGetKernelWorkGroupInfo> with C<CL_KERNEL_WORK_GROUP_SIZE> and returns the result.
1132 1683
1133=item @ints = $kernel->compile_work_group_size ($device) 1684=item @ints = $kernel->compile_work_group_size ($device)
1134 1685
1135Calls C<clGetKernelWorkGroupInfo> with C<CL_KERNEL_COMPILE_WORK_GROUP_SIZE> and returns the result(s). 1686Calls C<clGetKernelWorkGroupInfo> with C<CL_KERNEL_COMPILE_WORK_GROUP_SIZE> and returns the result.
1136 1687
1137=item $ulong = $kernel->local_mem_size ($device) 1688=item $ulong = $kernel->local_mem_size ($device)
1138 1689
1139Calls C<clGetKernelWorkGroupInfo> with C<CL_KERNEL_LOCAL_MEM_SIZE> and returns the result(s). 1690Calls C<clGetKernelWorkGroupInfo> with C<CL_KERNEL_LOCAL_MEM_SIZE> and returns the result.
1140 1691
1141=item $int = $kernel->preferred_work_group_size_multiple ($device) 1692=item $int = $kernel->preferred_work_group_size_multiple ($device)
1142 1693
1143Calls C<clGetKernelWorkGroupInfo> with C<CL_KERNEL_PREFERRED_WORK_GROUP_SIZE_MULTIPLE> and returns the result(s). 1694Calls C<clGetKernelWorkGroupInfo> with C<CL_KERNEL_PREFERRED_WORK_GROUP_SIZE_MULTIPLE> and returns the result.
1144 1695
1145=item $ulong = $kernel->private_mem_size ($device) 1696=item $ulong = $kernel->private_mem_size ($device)
1146 1697
1147Calls C<clGetKernelWorkGroupInfo> with C<CL_KERNEL_PRIVATE_MEM_SIZE> and returns the result(s). 1698Calls C<clGetKernelWorkGroupInfo> with C<CL_KERNEL_PRIVATE_MEM_SIZE> and returns the result.
1148 1699
1149=for gengetinfo end kernel_work_group 1700=for gengetinfo end kernel_work_group
1150 1701
1702=item $kernel->setf ($format, ...)
1703
1704Sets the arguments of a kernel. Since OpenCL 1.1 doesn't have a generic
1705way to set arguments (and with OpenCL 1.2 it might be rather slow), you
1706need to specify a format argument, much as with C<printf>, to tell OpenCL
1707what type of argument it is.
1708
1709The format arguments are single letters:
1710
1711 c char
1712 C unsigned char
1713 s short
1714 S unsigned short
1715 i int
1716 I unsigned int
1717 l long
1718 L unsigned long
1719
1720 h half float (0..65535)
1721 f float
1722 d double
1723
1724 z local (octet size)
1725
1726 m memory object (buffer or image)
1727 a sampler
1728 e event
1729
1730Space characters in the format string are ignored.
1731
1732Example: set the arguments for a kernel that expects an int, two floats, a buffer and an image.
1733
1734 $kernel->setf ("i ff mm", 5, 0.5, 3, $buffer, $image);
1735
1151=item $kernel->set_TYPE ($index, $value) 1736=item $kernel->set_TYPE ($index, $value)
1152 1737
1738=item $kernel->set_char ($index, $value)
1739
1740=item $kernel->set_uchar ($index, $value)
1741
1742=item $kernel->set_short ($index, $value)
1743
1744=item $kernel->set_ushort ($index, $value)
1745
1746=item $kernel->set_int ($index, $value)
1747
1748=item $kernel->set_uint ($index, $value)
1749
1750=item $kernel->set_long ($index, $value)
1751
1752=item $kernel->set_ulong ($index, $value)
1753
1754=item $kernel->set_half ($index, $value)
1755
1756=item $kernel->set_float ($index, $value)
1757
1758=item $kernel->set_double ($index, $value)
1759
1760=item $kernel->set_memory ($index, $value)
1761
1762=item $kernel->set_buffer ($index, $value)
1763
1764=item $kernel->set_image ($index, $value)
1765
1766=item $kernel->set_sampler ($index, $value)
1767
1768=item $kernel->set_local ($index, $value)
1769
1770=item $kernel->set_event ($index, $value)
1771
1153This is a family of methods to set the kernel argument with the number C<$index> to the give C<$value>. 1772This is a family of methods to set the kernel argument with the number
1154 1773C<$index> to the give C<$value>.
1155TYPE is one of C<char>, C<uchar>, C<short>, C<ushort>, C<int>, C<uint>,
1156C<long>, C<ulong>, C<half>, C<float>, C<double>, C<memory>, C<buffer>,
1157C<image2d>, C<image3d>, C<sampler> or C<event>.
1158 1774
1159Chars and integers (including the half type) are specified as integers, 1775Chars and integers (including the half type) are specified as integers,
1160float and double as floating point values, memory/buffer/image2d/image3d 1776float and double as floating point values, memory/buffer/image must be
1161must be an object of that type or C<undef>, and sampler and event must be 1777an object of that type or C<undef>, local-memory arguments are set by
1162objects of that type. 1778specifying the size, and sampler and event must be objects of that type.
1779
1780Note that C<set_memory> works for all memory objects (all types of buffers
1781and images) - the main purpose of the more specific C<set_TYPE> functions
1782is type checking.
1783
1784Setting an argument for a kernel does NOT keep a reference to the object -
1785for example, if you set an argument to some image object, free the image,
1786and call the kernel, you will run into undefined behaviour.
1163 1787
1164L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clSetKernelArg.html> 1788L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clSetKernelArg.html>
1165 1789
1166=back 1790=back
1167 1791
… …
1176 1800
1177Waits for the event to complete. 1801Waits for the event to complete.
1178 1802
1179L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clWaitForEvents.html> 1803L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clWaitForEvents.html>
1180 1804
1805=item $ev->cb ($exec_callback_type, $callback->($event, $event_command_exec_status))
1806
1807Adds a callback to the callback stack for the given event type. There is
1808no way to remove a callback again.
1809
1810L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clSetEventCallback.html>
1811
1181=item $packed_value = $ev->info ($name) 1812=item $packed_value = $ev->info ($name)
1182 1813
1183See C<< $platform->info >> for details. 1814See C<< $platform->info >> for details.
1184 1815
1185L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clGetEventInfo.html> 1816L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clGetEventInfo.html>
1186 1817
1187=for gengetinfo begin event 1818=for gengetinfo begin event
1188 1819
1189=item $queue = $event->command_queue 1820=item $queue = $event->command_queue
1190 1821
1191Calls C<clGetEventInfo> with C<CL_EVENT_COMMAND_QUEUE> and returns the result(s). 1822Calls C<clGetEventInfo> with C<CL_EVENT_COMMAND_QUEUE> and returns the result.
1192 1823
1193=item $command_type = $event->command_type 1824=item $command_type = $event->command_type
1194 1825
1195Calls C<clGetEventInfo> with C<CL_EVENT_COMMAND_TYPE> and returns the result(s). 1826Calls C<clGetEventInfo> with C<CL_EVENT_COMMAND_TYPE> and returns the result.
1196 1827
1197=item $uint = $event->reference_count 1828=item $uint = $event->reference_count
1198 1829
1199Calls C<clGetEventInfo> with C<CL_EVENT_REFERENCE_COUNT> and returns the result(s). 1830Calls C<clGetEventInfo> with C<CL_EVENT_REFERENCE_COUNT> and returns the result.
1200 1831
1201=item $uint = $event->command_execution_status 1832=item $uint = $event->command_execution_status
1202 1833
1203Calls C<clGetEventInfo> with C<CL_EVENT_COMMAND_EXECUTION_STATUS> and returns the result(s). 1834Calls C<clGetEventInfo> with C<CL_EVENT_COMMAND_EXECUTION_STATUS> and returns the result.
1204 1835
1205=item $ctx = $event->context 1836=item $ctx = $event->context
1206 1837
1207Calls C<clGetEventInfo> with C<CL_EVENT_CONTEXT> and returns the result(s). 1838Calls C<clGetEventInfo> with C<CL_EVENT_CONTEXT> and returns the result.
1208 1839
1209=for gengetinfo end event 1840=for gengetinfo end event
1210 1841
1211=item $packed_value = $ev->profiling_info ($name) 1842=item $packed_value = $ev->profiling_info ($name)
1212 1843
… …
1219 1850
1220=for gengetinfo begin profiling 1851=for gengetinfo begin profiling
1221 1852
1222=item $ulong = $event->profiling_command_queued 1853=item $ulong = $event->profiling_command_queued
1223 1854
1224Calls C<clGetEventProfilingInfo> with C<CL_PROFILING_COMMAND_QUEUED> and returns the result(s). 1855Calls C<clGetEventProfilingInfo> with C<CL_PROFILING_COMMAND_QUEUED> and returns the result.
1225 1856
1226=item $ulong = $event->profiling_command_submit 1857=item $ulong = $event->profiling_command_submit
1227 1858
1228Calls C<clGetEventProfilingInfo> with C<CL_PROFILING_COMMAND_SUBMIT> and returns the result(s). 1859Calls C<clGetEventProfilingInfo> with C<CL_PROFILING_COMMAND_SUBMIT> and returns the result.
1229 1860
1230=item $ulong = $event->profiling_command_start 1861=item $ulong = $event->profiling_command_start
1231 1862
1232Calls C<clGetEventProfilingInfo> with C<CL_PROFILING_COMMAND_START> and returns the result(s). 1863Calls C<clGetEventProfilingInfo> with C<CL_PROFILING_COMMAND_START> and returns the result.
1233 1864
1234=item $ulong = $event->profiling_command_end 1865=item $ulong = $event->profiling_command_end
1235 1866
1236Calls C<clGetEventProfilingInfo> with C<CL_PROFILING_COMMAND_END> and returns the result(s). 1867Calls C<clGetEventProfilingInfo> with C<CL_PROFILING_COMMAND_END> and returns the result.
1237 1868
1238=for gengetinfo end profiling 1869=for gengetinfo end profiling
1239 1870
1240=back 1871=back
1241 1872
… …
1245 1876
1246=over 4 1877=over 4
1247 1878
1248=item $ev->set_status ($execution_status) 1879=item $ev->set_status ($execution_status)
1249 1880
1881Sets the execution status of the user event. Can only be called once,
1882either with OpenCL::COMPLETE or a negative number as status.
1883
1250L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clSetUserEventStatus.html> 1884L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clSetUserEventStatus.html>
1251 1885
1252=back 1886=back
1253 1887
1254=cut 1888=cut
1255
1256package OpenCL;
1257
1258use common::sense;
1259
1260BEGIN {
1261 our $VERSION = '0.55';
1262
1263 require XSLoader;
1264 XSLoader::load (__PACKAGE__, $VERSION);
1265
1266 @OpenCL::Buffer::ISA =
1267 @OpenCL::Image::ISA = OpenCL::Memory::;
1268
1269 @OpenCL::Image2D::ISA =
1270 @OpenCL::Image3D::ISA = OpenCL::Image::;
1271
1272 @OpenCL::UserEvent::ISA = OpenCL::Event::;
1273}
1274 1889
12751; 18901;
1276 1891
1277=head1 AUTHOR 1892=head1 AUTHOR
1278 1893

Diff Legend

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