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

Diff Legend

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