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

Comparing OpenCL/OpenCL.pm (file contents):
Revision 1.18 by root, Thu Nov 17 06:22:29 2011 UTC vs.
Revision 1.65 by root, Mon Apr 30 23:35:16 2012 UTC

… …
27OpenCL::Program objects, which store source code and, after building for a 27OpenCL::Program objects, which store source code and, after building for a
28specific device ("compiling and linking"), also binary programs. For each 28specific device ("compiling and linking"), also binary programs. For each
29kernel function in a program you can then create an OpenCL::Kernel object 29kernel function in a program you can then create an OpenCL::Kernel object
30which represents basically a function call with argument values. 30which represents basically a function call with argument values.
31 31
32OpenCL::Memory objects of various flavours: OpenCL::Buffers objects (flat 32OpenCL::Memory objects of various flavours: OpenCL::Buffer objects (flat
33memory areas, think arrays or structs) and OpenCL::Image objects (think 2d 33memory areas, think arrays or structs) and OpenCL::Image objects (think 2d
34or 3d array) for bulk data and input and output for kernels. 34or 3d array) for bulk data and input and output for kernels.
35 35
36OpenCL::Sampler objects, which are kind of like texture filter modes in 36OpenCL::Sampler objects, which are kind of like texture filter modes in
37OpenGL. 37OpenGL.
… …
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
… …
226 347
227=item * Object lifetime managament is automatic - there is no need 348=item * Object lifetime managament is automatic - there is no need
228to free objects explicitly (C<clReleaseXXX>), the release function 349to free objects explicitly (C<clReleaseXXX>), the release function
229is called automatically once all Perl references to it go away. 350is called automatically once all Perl references to it go away.
230 351
231=item * OpenCL uses CamelCase for function names (C<clGetPlatformInfo>), 352=item * OpenCL uses CamelCase for function names
353(e.g. C<clGetPlatformIDs>, C<clGetPlatformInfo>), while this module
232while this module uses underscores as word separator and often leaves out 354uses underscores as word separator and often leaves out prefixes
233prefixes (C<< $platform->info >>). 355(C<OpenCL::platforms>, C<< $platform->info >>).
234 356
235=item * OpenCL often specifies fixed vector function arguments as short 357=item * OpenCL often specifies fixed vector function arguments as short
236arrays (C<$origin[3]>), while this module explicitly expects the 358arrays (C<size_t origin[3]>), while this module explicitly expects the
237components as separate arguments- 359components as separate arguments (C<$orig_x, $orig_y, $orig_z>) in
360function calls.
238 361
239=item * Structures are often specified with their components, and returned 362=item * Structures are often specified by flattening out their components
240as arrayrefs. 363as with short vectors, and returned as arrayrefs.
241
242=item * Where possible, one of the pitch values is calculated from the
243perl scalar length and need not be specified.
244 364
245=item * When enqueuing commands, the wait list is specified by adding 365=item * When enqueuing commands, the wait list is specified by adding
246extra arguments to the function - anywhere a C<$wait_events...> argument 366extra arguments to the function - anywhere a C<$wait_events...> argument
247is 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.
248 370
249=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
250context, 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
251by the method. 373by the method.
252 374
… …
272 ulong IV - Q 394 ulong IV - Q
273 float NV float f 395 float NV float f
274 half IV ushort S 396 half IV ushort S
275 double NV double d 397 double NV double d
276 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
277=head2 THE OpenCL PACKAGE 564=head2 THE OpenCL PACKAGE
278 565
279=over 4 566=over 4
280 567
281=item $int = OpenCL::errno 568=item $int = OpenCL::errno
282 569
283The 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
284and before calling another OpenCL function. 571and before calling another OpenCL function.
285 572
286=item $str = OpenCL::err2str $errval 573=item $str = OpenCL::err2str [$errval]
287 574
288Comverts 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).
289 577
290=item $str = OpenCL::enum2str $enum 578=item $str = OpenCL::enum2str $enum
291 579
292Converts most enum values (inof parameter names, image format constants, 580Converts most enum values (of parameter names, image format constants,
293object types, addressing and filter modes, command types etc.) into a 581object types, addressing and filter modes, command types etc.) into a
294human readbale string. When confronted with some random integer it can be 582human readable string. When confronted with some random integer it can be
295very 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
296string out of it. 584string out of it.
297 585
298=item @platforms = OpenCL::platforms 586=item @platforms = OpenCL::platforms
299 587
300Returns all available OpenCL::Platform objects. 588Returns all available OpenCL::Platform objects.
301 589
302L<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>
303 591
304=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
305 593
306Tries 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.
307 595
308L<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>
309 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
310=item OpenCL::wait_for_events $wait_events... 605=item OpenCL::wait_for_events $wait_events...
311 606
312Waits for all events to complete. 607Waits for all events to complete.
313 608
314L<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>
315 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
316=back 648=back
317 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
318=head2 THE OpenCL::Platform CLASS 675=head2 THE OpenCL::Platform CLASS
319 676
320=over 4 677=over 4
321 678
322=item $packed_value = $platform->info ($name)
323
324Calls C<clGetPlatformInfo> and returns the packed, raw value - for
325strings, this will be the string, for other values you probably need to
326use the correct C<unpack>. This might get improved in the future. Hopefully.
327
328L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clGetPlatformInfo.html>
329
330=item @devices = $platform->devices ($type = OpenCL::DEVICE_TYPE_ALL) 679=item @devices = $platform->devices ($type = OpenCL::DEVICE_TYPE_ALL)
331 680
332Returns a list of matching OpenCL::Device objects. 681Returns a list of matching OpenCL::Device objects.
333 682
334=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)
335 684
336Tries to create a context. Never worked for me, and you need devices explitly anyway. 685Tries to create a context. Never worked for me, and you need devices explicitly anyway.
337 686
338L<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>
339 688
340=item $ctx = $device->context ($properties = undef, @$devices, $notify = undef) 689=item $ctx = $platform->context ($properties, \@devices, $callback->($err, $pvt) = $print_stderr)
341 690
342Create 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
343CL_CONTEXT_PLATFORM property is supplied automatically. 692CL_CONTEXT_PLATFORM property is supplied automatically.
344 693
345L<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>
346 695
696=item $packed_value = $platform->info ($name)
697
698Calls C<clGetPlatformInfo> and returns the packed, raw value - for
699strings, this will be the string (possibly including terminating \0), for
700other values you probably need to use the correct C<unpack>.
701
702It's best to avoid this method and use one of the following convenience
703wrappers.
704
705L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clGetPlatformInfo.html>
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
714=for gengetinfo begin platform
715
716=item $string = $platform->profile
717
718Calls C<clGetPlatformInfo> with C<CL_PLATFORM_PROFILE> and returns the result.
719
720=item $string = $platform->version
721
722Calls C<clGetPlatformInfo> with C<CL_PLATFORM_VERSION> and returns the result.
723
724=item $string = $platform->name
725
726Calls C<clGetPlatformInfo> with C<CL_PLATFORM_NAME> and returns the result.
727
728=item $string = $platform->vendor
729
730Calls C<clGetPlatformInfo> with C<CL_PLATFORM_VENDOR> and returns the result.
731
732=item $string = $platform->extensions
733
734Calls C<clGetPlatformInfo> with C<CL_PLATFORM_EXTENSIONS> and returns the result.
735
736=for gengetinfo end platform
737
347=back 738=back
348 739
349=head2 THE OpenCL::Device CLASS 740=head2 THE OpenCL::Device CLASS
350 741
351=over 4 742=over 4
… …
354 745
355See C<< $platform->info >> for details. 746See C<< $platform->info >> for details.
356 747
357L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clGetDeviceInfo.html> 748L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clGetDeviceInfo.html>
358 749
750=for gengetinfo begin device
751
752=item $device_type = $device->type
753
754Calls C<clGetDeviceInfo> with C<CL_DEVICE_TYPE> and returns the result.
755
756=item $uint = $device->vendor_id
757
758Calls C<clGetDeviceInfo> with C<CL_DEVICE_VENDOR_ID> and returns the result.
759
760=item $uint = $device->max_compute_units
761
762Calls C<clGetDeviceInfo> with C<CL_DEVICE_MAX_COMPUTE_UNITS> and returns the result.
763
764=item $uint = $device->max_work_item_dimensions
765
766Calls C<clGetDeviceInfo> with C<CL_DEVICE_MAX_WORK_ITEM_DIMENSIONS> and returns the result.
767
768=item $int = $device->max_work_group_size
769
770Calls C<clGetDeviceInfo> with C<CL_DEVICE_MAX_WORK_GROUP_SIZE> and returns the result.
771
772=item @ints = $device->max_work_item_sizes
773
774Calls C<clGetDeviceInfo> with C<CL_DEVICE_MAX_WORK_ITEM_SIZES> and returns the result.
775
776=item $uint = $device->preferred_vector_width_char
777
778Calls C<clGetDeviceInfo> with C<CL_DEVICE_PREFERRED_VECTOR_WIDTH_CHAR> and returns the result.
779
780=item $uint = $device->preferred_vector_width_short
781
782Calls C<clGetDeviceInfo> with C<CL_DEVICE_PREFERRED_VECTOR_WIDTH_SHORT> and returns the result.
783
784=item $uint = $device->preferred_vector_width_int
785
786Calls C<clGetDeviceInfo> with C<CL_DEVICE_PREFERRED_VECTOR_WIDTH_INT> and returns the result.
787
788=item $uint = $device->preferred_vector_width_long
789
790Calls C<clGetDeviceInfo> with C<CL_DEVICE_PREFERRED_VECTOR_WIDTH_LONG> and returns the result.
791
792=item $uint = $device->preferred_vector_width_float
793
794Calls C<clGetDeviceInfo> with C<CL_DEVICE_PREFERRED_VECTOR_WIDTH_FLOAT> and returns the result.
795
796=item $uint = $device->preferred_vector_width_double
797
798Calls C<clGetDeviceInfo> with C<CL_DEVICE_PREFERRED_VECTOR_WIDTH_DOUBLE> and returns the result.
799
800=item $uint = $device->max_clock_frequency
801
802Calls C<clGetDeviceInfo> with C<CL_DEVICE_MAX_CLOCK_FREQUENCY> and returns the result.
803
804=item $bitfield = $device->address_bits
805
806Calls C<clGetDeviceInfo> with C<CL_DEVICE_ADDRESS_BITS> and returns the result.
807
808=item $uint = $device->max_read_image_args
809
810Calls C<clGetDeviceInfo> with C<CL_DEVICE_MAX_READ_IMAGE_ARGS> and returns the result.
811
812=item $uint = $device->max_write_image_args
813
814Calls C<clGetDeviceInfo> with C<CL_DEVICE_MAX_WRITE_IMAGE_ARGS> and returns the result.
815
816=item $ulong = $device->max_mem_alloc_size
817
818Calls C<clGetDeviceInfo> with C<CL_DEVICE_MAX_MEM_ALLOC_SIZE> and returns the result.
819
820=item $int = $device->image2d_max_width
821
822Calls C<clGetDeviceInfo> with C<CL_DEVICE_IMAGE2D_MAX_WIDTH> and returns the result.
823
824=item $int = $device->image2d_max_height
825
826Calls C<clGetDeviceInfo> with C<CL_DEVICE_IMAGE2D_MAX_HEIGHT> and returns the result.
827
828=item $int = $device->image3d_max_width
829
830Calls C<clGetDeviceInfo> with C<CL_DEVICE_IMAGE3D_MAX_WIDTH> and returns the result.
831
832=item $int = $device->image3d_max_height
833
834Calls C<clGetDeviceInfo> with C<CL_DEVICE_IMAGE3D_MAX_HEIGHT> and returns the result.
835
836=item $int = $device->image3d_max_depth
837
838Calls C<clGetDeviceInfo> with C<CL_DEVICE_IMAGE3D_MAX_DEPTH> and returns the result.
839
840=item $uint = $device->image_support
841
842Calls C<clGetDeviceInfo> with C<CL_DEVICE_IMAGE_SUPPORT> and returns the result.
843
844=item $int = $device->max_parameter_size
845
846Calls C<clGetDeviceInfo> with C<CL_DEVICE_MAX_PARAMETER_SIZE> and returns the result.
847
848=item $uint = $device->max_samplers
849
850Calls C<clGetDeviceInfo> with C<CL_DEVICE_MAX_SAMPLERS> and returns the result.
851
852=item $uint = $device->mem_base_addr_align
853
854Calls C<clGetDeviceInfo> with C<CL_DEVICE_MEM_BASE_ADDR_ALIGN> and returns the result.
855
856=item $uint = $device->min_data_type_align_size
857
858Calls C<clGetDeviceInfo> with C<CL_DEVICE_MIN_DATA_TYPE_ALIGN_SIZE> and returns the result.
859
860=item $device_fp_config = $device->single_fp_config
861
862Calls C<clGetDeviceInfo> with C<CL_DEVICE_SINGLE_FP_CONFIG> and returns the result.
863
864=item $device_mem_cache_type = $device->global_mem_cache_type
865
866Calls C<clGetDeviceInfo> with C<CL_DEVICE_GLOBAL_MEM_CACHE_TYPE> and returns the result.
867
868=item $uint = $device->global_mem_cacheline_size
869
870Calls C<clGetDeviceInfo> with C<CL_DEVICE_GLOBAL_MEM_CACHELINE_SIZE> and returns the result.
871
872=item $ulong = $device->global_mem_cache_size
873
874Calls C<clGetDeviceInfo> with C<CL_DEVICE_GLOBAL_MEM_CACHE_SIZE> and returns the result.
875
876=item $ulong = $device->global_mem_size
877
878Calls C<clGetDeviceInfo> with C<CL_DEVICE_GLOBAL_MEM_SIZE> and returns the result.
879
880=item $ulong = $device->max_constant_buffer_size
881
882Calls C<clGetDeviceInfo> with C<CL_DEVICE_MAX_CONSTANT_BUFFER_SIZE> and returns the result.
883
884=item $uint = $device->max_constant_args
885
886Calls C<clGetDeviceInfo> with C<CL_DEVICE_MAX_CONSTANT_ARGS> and returns the result.
887
888=item $device_local_mem_type = $device->local_mem_type
889
890Calls C<clGetDeviceInfo> with C<CL_DEVICE_LOCAL_MEM_TYPE> and returns the result.
891
892=item $ulong = $device->local_mem_size
893
894Calls C<clGetDeviceInfo> with C<CL_DEVICE_LOCAL_MEM_SIZE> and returns the result.
895
896=item $boolean = $device->error_correction_support
897
898Calls C<clGetDeviceInfo> with C<CL_DEVICE_ERROR_CORRECTION_SUPPORT> and returns the result.
899
900=item $int = $device->profiling_timer_resolution
901
902Calls C<clGetDeviceInfo> with C<CL_DEVICE_PROFILING_TIMER_RESOLUTION> and returns the result.
903
904=item $boolean = $device->endian_little
905
906Calls C<clGetDeviceInfo> with C<CL_DEVICE_ENDIAN_LITTLE> and returns the result.
907
908=item $boolean = $device->available
909
910Calls C<clGetDeviceInfo> with C<CL_DEVICE_AVAILABLE> and returns the result.
911
912=item $boolean = $device->compiler_available
913
914Calls C<clGetDeviceInfo> with C<CL_DEVICE_COMPILER_AVAILABLE> and returns the result.
915
916=item $device_exec_capabilities = $device->execution_capabilities
917
918Calls C<clGetDeviceInfo> with C<CL_DEVICE_EXECUTION_CAPABILITIES> and returns the result.
919
920=item $command_queue_properties = $device->properties
921
922Calls C<clGetDeviceInfo> with C<CL_DEVICE_QUEUE_PROPERTIES> and returns the result.
923
924=item $ = $device->platform
925
926Calls C<clGetDeviceInfo> with C<CL_DEVICE_PLATFORM> and returns the result.
927
928=item $string = $device->name
929
930Calls C<clGetDeviceInfo> with C<CL_DEVICE_NAME> and returns the result.
931
932=item $string = $device->vendor
933
934Calls C<clGetDeviceInfo> with C<CL_DEVICE_VENDOR> and returns the result.
935
936=item $string = $device->driver_version
937
938Calls C<clGetDeviceInfo> with C<CL_DRIVER_VERSION> and returns the result.
939
940=item $string = $device->profile
941
942Calls C<clGetDeviceInfo> with C<CL_DEVICE_PROFILE> and returns the result.
943
944=item $string = $device->version
945
946Calls C<clGetDeviceInfo> with C<CL_DEVICE_VERSION> and returns the result.
947
948=item $string = $device->extensions
949
950Calls C<clGetDeviceInfo> with C<CL_DEVICE_EXTENSIONS> and returns the result.
951
952=item $uint = $device->preferred_vector_width_half
953
954Calls C<clGetDeviceInfo> with C<CL_DEVICE_PREFERRED_VECTOR_WIDTH_HALF> and returns the result.
955
956=item $uint = $device->native_vector_width_char
957
958Calls C<clGetDeviceInfo> with C<CL_DEVICE_NATIVE_VECTOR_WIDTH_CHAR> and returns the result.
959
960=item $uint = $device->native_vector_width_short
961
962Calls C<clGetDeviceInfo> with C<CL_DEVICE_NATIVE_VECTOR_WIDTH_SHORT> and returns the result.
963
964=item $uint = $device->native_vector_width_int
965
966Calls C<clGetDeviceInfo> with C<CL_DEVICE_NATIVE_VECTOR_WIDTH_INT> and returns the result.
967
968=item $uint = $device->native_vector_width_long
969
970Calls C<clGetDeviceInfo> with C<CL_DEVICE_NATIVE_VECTOR_WIDTH_LONG> and returns the result.
971
972=item $uint = $device->native_vector_width_float
973
974Calls C<clGetDeviceInfo> with C<CL_DEVICE_NATIVE_VECTOR_WIDTH_FLOAT> and returns the result.
975
976=item $uint = $device->native_vector_width_double
977
978Calls C<clGetDeviceInfo> with C<CL_DEVICE_NATIVE_VECTOR_WIDTH_DOUBLE> and returns the result.
979
980=item $uint = $device->native_vector_width_half
981
982Calls C<clGetDeviceInfo> with C<CL_DEVICE_NATIVE_VECTOR_WIDTH_HALF> and returns the result.
983
984=item $device_fp_config = $device->double_fp_config
985
986Calls C<clGetDeviceInfo> with C<CL_DEVICE_DOUBLE_FP_CONFIG> and returns the result.
987
988=item $device_fp_config = $device->half_fp_config
989
990Calls C<clGetDeviceInfo> with C<CL_DEVICE_HALF_FP_CONFIG> and returns the result.
991
992=item $boolean = $device->host_unified_memory
993
994Calls C<clGetDeviceInfo> with C<CL_DEVICE_HOST_UNIFIED_MEMORY> and returns the result.
995
996=item $device = $device->parent_device_ext
997
998Calls C<clGetDeviceInfo> with C<CL_DEVICE_PARENT_DEVICE_EXT> and returns the result.
999
1000=item @device_partition_property_exts = $device->partition_types_ext
1001
1002Calls C<clGetDeviceInfo> with C<CL_DEVICE_PARTITION_TYPES_EXT> and returns the result.
1003
1004=item @device_partition_property_exts = $device->affinity_domains_ext
1005
1006Calls C<clGetDeviceInfo> with C<CL_DEVICE_AFFINITY_DOMAINS_EXT> and returns the result.
1007
1008=item $uint = $device->reference_count_ext
1009
1010Calls C<clGetDeviceInfo> with C<CL_DEVICE_REFERENCE_COUNT_EXT> and returns the result.
1011
1012=item @device_partition_property_exts = $device->partition_style_ext
1013
1014Calls C<clGetDeviceInfo> with C<CL_DEVICE_PARTITION_STYLE_EXT> and returns the result.
1015
1016=for gengetinfo end device
1017
359=back 1018=back
360 1019
361=head2 THE OpenCL::Context CLASS 1020=head2 THE OpenCL::Context CLASS
362 1021
363=over 4 1022=over 4
364 1023
365=item $packed_value = $ctx->info ($name) 1024=item $prog = $ctx->build_program ($program, $options = "")
366 1025
367See C<< $platform->info >> for details. 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.
368 1029
369L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clGetContextInfo.html> 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}
370 1056
371=item $queue = $ctx->queue ($device, $properties) 1057=item $queue = $ctx->queue ($device, $properties)
372 1058
373Create 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.
374 1060
375L<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>
376 1062
1063Example: create an out-of-order queue.
1064
1065 $queue = $ctx->queue ($device, OpenCL::QUEUE_OUT_OF_ORDER_EXEC_MODE_ENABLE);
1066
377=item $ev = $ctx->user_event 1067=item $ev = $ctx->user_event
378 1068
379Creates a new OpenCL::UserEvent object. 1069Creates a new OpenCL::UserEvent object.
380 1070
381L<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>
382 1072
383=item $buf = $ctx->buffer ($flags, $len) 1073=item $buf = $ctx->buffer ($flags, $len)
384 1074
385Creates 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.
386 1077
387L<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>
388 1079
389=item $buf = $ctx->buffer_sv ($flags, $data) 1080=item $buf = $ctx->buffer_sv ($flags, $data)
390 1081
391Creates 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>
392 1091
393=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)
394 1093
395Creates 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.
396 1096
397L<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>
398 1098
399=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)
400 1100
401Creates 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.
402 1103
403L<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
404 1140
405=item @formats = $ctx->supported_image_formats ($flags, $image_type) 1141=item @formats = $ctx->supported_image_formats ($flags, $image_type)
406 1142
407Returns 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
408two values, $channel_order and $channel_type, in it. 1144two values, $channel_order and $channel_type, in it.
… …
419 1155
420Creates a new OpenCL::Program object from the given source code. 1156Creates a new OpenCL::Program object from the given source code.
421 1157
422L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clCreateProgramWithSource.html> 1158L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clCreateProgramWithSource.html>
423 1159
1160=item $packed_value = $ctx->info ($name)
1161
1162See C<< $platform->info >> for details.
1163
1164L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clGetContextInfo.html>
1165
1166=for gengetinfo begin context
1167
1168=item $uint = $context->reference_count
1169
1170Calls C<clGetContextInfo> with C<CL_CONTEXT_REFERENCE_COUNT> and returns the result.
1171
1172=item @devices = $context->devices
1173
1174Calls C<clGetContextInfo> with C<CL_CONTEXT_DEVICES> and returns the result.
1175
1176=item @property_ints = $context->properties
1177
1178Calls C<clGetContextInfo> with C<CL_CONTEXT_PROPERTIES> and returns the result.
1179
1180=item $uint = $context->num_devices
1181
1182Calls C<clGetContextInfo> with C<CL_CONTEXT_NUM_DEVICES> and returns the result.
1183
1184=for gengetinfo end context
1185
424=back 1186=back
425 1187
426=head2 THE OpenCL::Queue CLASS 1188=head2 THE OpenCL::Queue CLASS
427 1189
428An OpenCL::Queue represents an execution queue for OpenCL. You execute 1190An OpenCL::Queue represents an execution queue for OpenCL. You execute
429requests by calling their respective C<enqueue_xxx> method and waitinf for 1191requests by calling their respective method and waiting for it to complete
430it to complete in some way. 1192in some way.
431 1193
432All 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
433for completion, unless the method is called in void context, in which case 1195be used to wait for completion (optionally using a callback), unless
434no event object is created. 1196the method is called in void context, in which case no event object is
1197created.
435 1198
436They 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
437request 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
438event 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);
439 1207
440Queues execute in-order by default, without any parallelism, so in most 1208Queues execute in-order by default, without any parallelism, so in most
441cases (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
442create event objects. 1210create event objects, althoguh an our of order queue is often a bit
1211faster.
443 1212
444=over 4 1213=over 4
445 1214
446=item $packed_value = $ctx->info ($name)
447
448See C<< $platform->info >> for details.
449
450L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clGetCommandQueueInfo.html>
451
452=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...)
453 1216
454Reads data from buffer into the given string. 1217Reads data from buffer into the given string.
455 1218
456L<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>
457 1220
458=item $ev = $queue->enqueue_write_buffer ($buffer, $blocking, $offset, $data, $wait_events...) 1221=item $ev = $queue->write_buffer ($buffer, $blocking, $offset, $data, $wait_events...)
459 1222
460Writes data to buffer from the given string. 1223Writes data to buffer from the given string.
461 1224
462L<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>
463 1226
464=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...)
465 1228
466L<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>
467 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
468=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.
469 1247
470L<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>
471 1249
472=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...)
473 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.
474L<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>
475 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
476=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...)
477 1265
478Yeah. 1266Yeah.
479 1267
480L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clEnqueueCopyBufferRect.html>
481
482=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...)
483
484L<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>.
485 1269
486=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, ...)
487 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
488L<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>
489 1285
490=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...)
491
492L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clEnqueueCopyImageToBuffer.html>
493
494=item $ev = $queue->enqueue_task ($kernel, $wait_events...) 1286=item $ev = $queue->task ($kernel, $wait_events...)
495 1287
496L<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>
497 1289
498=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...)
499 1291
500Enqueues a kernel execution. 1292Enqueues a kernel execution.
501 1293
502@$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
503integers specifying the work sizes (element counts). 1295integers specifying the work sizes (element counts).
504 1296
505@$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
506are 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
507of elements as @$global_work_size. 1299of elements as \@global_work_size.
508 1300
509@$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
510implementation is supposed to choose good local work sizes), or a 1302implementation is supposed to choose good local work sizes), or a
511reference 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
512elements as @$global_work_size. 1304elements as \@global_work_size.
513 1305
514L<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>
515 1307
516=item $ev = $queue->enqueue_marker 1308=item $ev = $queue->acquire_gl_objects ([object, ...], $wait_events...)
517 1309
1310Enqueues a list (an array-ref of OpenCL::Memory objects) to be acquired
1311for subsequent OpenCL usage.
1312
518L<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>
519 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
520=item $ev = $queue->enqueue_wait_for_events ($wait_events...) 1322=item $ev = $queue->wait_for_events ($wait_events...)
521 1323
522L<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>
523 1325
524=item $queue->enqueue_barrier 1326=item $ev = $queue->marker ($wait_events...)
525 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
526L<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>
527 1333
528=item $queue->flush 1334=item $queue->flush
529 1335
530L<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>
531 1337
532=item $queue->finish 1338=item $queue->finish
533 1339
534L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clFinish.html> 1340L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clFinish.html>
535 1341
1342=item $packed_value = $queue->info ($name)
1343
1344See C<< $platform->info >> for details.
1345
1346L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clGetCommandQueueInfo.html>
1347
1348=for gengetinfo begin command_queue
1349
1350=item $ctx = $command_queue->context
1351
1352Calls C<clGetCommandQueueInfo> with C<CL_QUEUE_CONTEXT> and returns the result.
1353
1354=item $device = $command_queue->device
1355
1356Calls C<clGetCommandQueueInfo> with C<CL_QUEUE_DEVICE> and returns the result.
1357
1358=item $uint = $command_queue->reference_count
1359
1360Calls C<clGetCommandQueueInfo> with C<CL_QUEUE_REFERENCE_COUNT> and returns the result.
1361
1362=item $command_queue_properties = $command_queue->properties
1363
1364Calls C<clGetCommandQueueInfo> with C<CL_QUEUE_PROPERTIES> and returns the result.
1365
1366=for gengetinfo end command_queue
1367
536=back 1368=back
537 1369
538=head2 THE OpenCL::Memory CLASS 1370=head2 THE OpenCL::Memory CLASS
539 1371
540This the superclass of all memory objects - OpenCL::Buffer, OpenCL::Image, 1372This the superclass of all memory objects - OpenCL::Buffer, OpenCL::Image,
541OpenCL::Image2D and OpenCL::Image3D. The subclasses of this class 1373OpenCL::Image2D and OpenCL::Image3D.
542currently only exist to allow type-checking.
543 1374
544=over 4 1375=over 4
545 1376
546=item $packed_value = $memory->info ($name) 1377=item $packed_value = $memory->info ($name)
547 1378
548See C<< $platform->info >> for details. 1379See C<< $platform->info >> for details.
549 1380
550L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clGetMemObjectInfo.html> 1381L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clGetMemObjectInfo.html>
551 1382
1383=for gengetinfo begin mem
1384
1385=item $mem_object_type = $mem->type
1386
1387Calls C<clGetMemObjectInfo> with C<CL_MEM_TYPE> and returns the result.
1388
1389=item $mem_flags = $mem->flags
1390
1391Calls C<clGetMemObjectInfo> with C<CL_MEM_FLAGS> and returns the result.
1392
1393=item $int = $mem->size
1394
1395Calls C<clGetMemObjectInfo> with C<CL_MEM_SIZE> and returns the result.
1396
1397=item $ptr_value = $mem->host_ptr
1398
1399Calls C<clGetMemObjectInfo> with C<CL_MEM_HOST_PTR> and returns the result.
1400
1401=item $uint = $mem->map_count
1402
1403Calls C<clGetMemObjectInfo> with C<CL_MEM_MAP_COUNT> and returns the result.
1404
1405=item $uint = $mem->reference_count
1406
1407Calls C<clGetMemObjectInfo> with C<CL_MEM_REFERENCE_COUNT> and returns the result.
1408
1409=item $ctx = $mem->context
1410
1411Calls C<clGetMemObjectInfo> with C<CL_MEM_CONTEXT> and returns the result.
1412
1413=item $mem = $mem->associated_memobject
1414
1415Calls C<clGetMemObjectInfo> with C<CL_MEM_ASSOCIATED_MEMOBJECT> and returns the result.
1416
1417=item $int = $mem->offset
1418
1419Calls C<clGetMemObjectInfo> with C<CL_MEM_OFFSET> and returns the result.
1420
1421=for gengetinfo end mem
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
552=back 1430=back
553 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
1455=head2 THE OpenCL::Image CLASS
1456
1457This is the superclass of all image objects - OpenCL::Image1D,
1458OpenCL::Image1DArray, OpenCL::Image1DBuffer, OpenCL::Image2D,
1459OpenCL::Image2DArray and OpenCL::Image3D.
1460
1461=over 4
1462
1463=item $packed_value = $image->image_info ($name)
1464
1465See C<< $platform->info >> for details.
1466
1467The reason this method is not called C<info> is that there already is an
1468C<< ->info >> method inherited from C<OpenCL::Memory>.
1469
1470L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clGetImageInfo.html>
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
1477=for gengetinfo begin image
1478
1479=item $int = $image->element_size
1480
1481Calls C<clGetImageInfo> with C<CL_IMAGE_ELEMENT_SIZE> and returns the result.
1482
1483=item $int = $image->row_pitch
1484
1485Calls C<clGetImageInfo> with C<CL_IMAGE_ROW_PITCH> and returns the result.
1486
1487=item $int = $image->slice_pitch
1488
1489Calls C<clGetImageInfo> with C<CL_IMAGE_SLICE_PITCH> and returns the result.
1490
1491=item $int = $image->width
1492
1493Calls C<clGetImageInfo> with C<CL_IMAGE_WIDTH> and returns the result.
1494
1495=item $int = $image->height
1496
1497Calls C<clGetImageInfo> with C<CL_IMAGE_HEIGHT> and returns the result.
1498
1499=item $int = $image->depth
1500
1501Calls C<clGetImageInfo> with C<CL_IMAGE_DEPTH> and returns the result.
1502
1503=for gengetinfo end image
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
1517=back
1518
554=head2 THE OpenCL::Sampler CLASS 1519=head2 THE OpenCL::Sampler CLASS
555 1520
556=over 4 1521=over 4
557 1522
558=item $packed_value = $sampler->info ($name) 1523=item $packed_value = $sampler->info ($name)
559 1524
560See C<< $platform->info >> for details. 1525See C<< $platform->info >> for details.
561 1526
562L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clGetSamplerInfo.html> 1527L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clGetSamplerInfo.html>
563 1528
1529=for gengetinfo begin sampler
1530
1531=item $uint = $sampler->reference_count
1532
1533Calls C<clGetSamplerInfo> with C<CL_SAMPLER_REFERENCE_COUNT> and returns the result.
1534
1535=item $ctx = $sampler->context
1536
1537Calls C<clGetSamplerInfo> with C<CL_SAMPLER_CONTEXT> and returns the result.
1538
1539=item $addressing_mode = $sampler->normalized_coords
1540
1541Calls C<clGetSamplerInfo> with C<CL_SAMPLER_NORMALIZED_COORDS> and returns the result.
1542
1543=item $filter_mode = $sampler->addressing_mode
1544
1545Calls C<clGetSamplerInfo> with C<CL_SAMPLER_ADDRESSING_MODE> and returns the result.
1546
1547=item $boolean = $sampler->filter_mode
1548
1549Calls C<clGetSamplerInfo> with C<CL_SAMPLER_FILTER_MODE> and returns the result.
1550
1551=for gengetinfo end sampler
1552
564=back 1553=back
565 1554
566=head2 THE OpenCL::Program CLASS 1555=head2 THE OpenCL::Program CLASS
567 1556
568=over 4 1557=over 4
569 1558
570=item $packed_value = $program->info ($name) 1559=item $program->build (\@devices = undef, $options = "", $cb->($program) = undef)
571 1560
572See C<< $platform->info >> for details.
573
574L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clGetProgramInfo.html>
575
576=item $program->build ($device, $options = "")
577
578Tries 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.
579 1576
580L<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).
581 1583
582=item $packed_value = $program->build_info ($device, $name) 1584=item $packed_value = $program->build_info ($device, $name)
583 1585
584Similar to C<< $platform->info >>, but returns build info for a previous 1586Similar to C<< $platform->info >>, but returns build info for a previous
585build attempt for the given device. 1587build attempt for the given device.
… …
591Creates 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
592the program. 1594the program.
593 1595
594L<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>
595 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
1604=for gengetinfo begin program_build
1605
1606=item $build_status = $program->build_status ($device)
1607
1608Calls C<clGetProgramBuildInfo> with C<CL_PROGRAM_BUILD_STATUS> and returns the result.
1609
1610=item $string = $program->build_options ($device)
1611
1612Calls C<clGetProgramBuildInfo> with C<CL_PROGRAM_BUILD_OPTIONS> and returns the result.
1613
1614=item $string = $program->build_log ($device)
1615
1616Calls C<clGetProgramBuildInfo> with C<CL_PROGRAM_BUILD_LOG> and returns the result.
1617
1618=for gengetinfo end program_build
1619
1620=item $packed_value = $program->info ($name)
1621
1622See C<< $platform->info >> for details.
1623
1624L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clGetProgramInfo.html>
1625
1626=for gengetinfo begin program
1627
1628=item $uint = $program->reference_count
1629
1630Calls C<clGetProgramInfo> with C<CL_PROGRAM_REFERENCE_COUNT> and returns the result.
1631
1632=item $ctx = $program->context
1633
1634Calls C<clGetProgramInfo> with C<CL_PROGRAM_CONTEXT> and returns the result.
1635
1636=item $uint = $program->num_devices
1637
1638Calls C<clGetProgramInfo> with C<CL_PROGRAM_NUM_DEVICES> and returns the result.
1639
1640=item @devices = $program->devices
1641
1642Calls C<clGetProgramInfo> with C<CL_PROGRAM_DEVICES> and returns the result.
1643
1644=item $string = $program->source
1645
1646Calls C<clGetProgramInfo> with C<CL_PROGRAM_SOURCE> and returns the result.
1647
1648=item @ints = $program->binary_sizes
1649
1650Calls C<clGetProgramInfo> with C<CL_PROGRAM_BINARY_SIZES> and returns the result.
1651
1652=for gengetinfo end program
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
596=back 1665=back
597 1666
598=head2 THE OpenCL::Kernel CLASS 1667=head2 THE OpenCL::Kernel CLASS
599 1668
600=over 4 1669=over 4
… …
603 1672
604See C<< $platform->info >> for details. 1673See C<< $platform->info >> for details.
605 1674
606L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clGetKernelInfo.html> 1675L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clGetKernelInfo.html>
607 1676
1677=for gengetinfo begin kernel
1678
1679=item $string = $kernel->function_name
1680
1681Calls C<clGetKernelInfo> with C<CL_KERNEL_FUNCTION_NAME> and returns the result.
1682
1683=item $uint = $kernel->num_args
1684
1685Calls C<clGetKernelInfo> with C<CL_KERNEL_NUM_ARGS> and returns the result.
1686
1687=item $uint = $kernel->reference_count
1688
1689Calls C<clGetKernelInfo> with C<CL_KERNEL_REFERENCE_COUNT> and returns the result.
1690
1691=item $ctx = $kernel->context
1692
1693Calls C<clGetKernelInfo> with C<CL_KERNEL_CONTEXT> and returns the result.
1694
1695=item $program = $kernel->program
1696
1697Calls C<clGetKernelInfo> with C<CL_KERNEL_PROGRAM> and returns the result.
1698
1699=for gengetinfo end kernel
1700
1701=item $packed_value = $kernel->work_group_info ($device, $name)
1702
1703See C<< $platform->info >> for details.
1704
1705The reason this method is not called C<info> is that there already is an
1706C<< ->info >> method.
1707
1708L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clGetKernelWorkGroupInfo.html>
1709
1710=for gengetinfo begin kernel_work_group
1711
1712=item $int = $kernel->work_group_size ($device)
1713
1714Calls C<clGetKernelWorkGroupInfo> with C<CL_KERNEL_WORK_GROUP_SIZE> and returns the result.
1715
1716=item @ints = $kernel->compile_work_group_size ($device)
1717
1718Calls C<clGetKernelWorkGroupInfo> with C<CL_KERNEL_COMPILE_WORK_GROUP_SIZE> and returns the result.
1719
1720=item $ulong = $kernel->local_mem_size ($device)
1721
1722Calls C<clGetKernelWorkGroupInfo> with C<CL_KERNEL_LOCAL_MEM_SIZE> and returns the result.
1723
1724=item $int = $kernel->preferred_work_group_size_multiple ($device)
1725
1726Calls C<clGetKernelWorkGroupInfo> with C<CL_KERNEL_PREFERRED_WORK_GROUP_SIZE_MULTIPLE> and returns the result.
1727
1728=item $ulong = $kernel->private_mem_size ($device)
1729
1730Calls C<clGetKernelWorkGroupInfo> with C<CL_KERNEL_PRIVATE_MEM_SIZE> and returns the result.
1731
1732=for gengetinfo end kernel_work_group
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
608=item $kernel->set_TYPE ($index, $value) 1768=item $kernel->set_TYPE ($index, $value)
609 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
610This 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
611 1805C<$index> to the give C<$value>.
612TYPE is one of C<char>, C<uchar>, C<short>, C<ushort>, C<int>, C<uint>,
613C<long>, C<ulong>, C<half>, C<float>, C<double>, C<memory>, C<buffer>,
614C<image2d>, C<image3d>, C<sampler> or C<event>.
615 1806
616Chars and integers (including the half type) are specified as integers, 1807Chars and integers (including the half type) are specified as integers,
617float and double as floating point values, memory/buffer/image2d/image3d 1808float and double as floating point values, memory/buffer/image must be
618must 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
619objects 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.
620 1819
621L<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>
622 1821
623=back 1822=back
624 1823
… …
627This is the superclass for all event objects (including OpenCL::UserEvent 1826This is the superclass for all event objects (including OpenCL::UserEvent
628objects). 1827objects).
629 1828
630=over 4 1829=over 4
631 1830
1831=item $ev->wait
1832
1833Waits for the event to complete.
1834
1835L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clWaitForEvents.html>
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
632=item $packed_value = $ev->info ($name) 1844=item $packed_value = $ev->info ($name)
633 1845
634See C<< $platform->info >> for details. 1846See C<< $platform->info >> for details.
635 1847
636L<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>
637 1849
638=item $ev->wait 1850=for gengetinfo begin event
639 1851
640Waits for the event to complete. 1852=item $queue = $event->command_queue
641 1853
1854Calls C<clGetEventInfo> with C<CL_EVENT_COMMAND_QUEUE> and returns the result.
1855
1856=item $command_type = $event->command_type
1857
1858Calls C<clGetEventInfo> with C<CL_EVENT_COMMAND_TYPE> and returns the result.
1859
1860=item $uint = $event->reference_count
1861
1862Calls C<clGetEventInfo> with C<CL_EVENT_REFERENCE_COUNT> and returns the result.
1863
1864=item $uint = $event->command_execution_status
1865
1866Calls C<clGetEventInfo> with C<CL_EVENT_COMMAND_EXECUTION_STATUS> and returns the result.
1867
1868=item $ctx = $event->context
1869
1870Calls C<clGetEventInfo> with C<CL_EVENT_CONTEXT> and returns the result.
1871
1872=for gengetinfo end event
1873
1874=item $packed_value = $ev->profiling_info ($name)
1875
1876See C<< $platform->info >> for details.
1877
1878The reason this method is not called C<info> is that there already is an
1879C<< ->info >> method.
1880
642L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clWaitForEvents.html> 1881L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clGetProfilingInfo.html>
1882
1883=for gengetinfo begin profiling
1884
1885=item $ulong = $event->profiling_command_queued
1886
1887Calls C<clGetEventProfilingInfo> with C<CL_PROFILING_COMMAND_QUEUED> and returns the result.
1888
1889=item $ulong = $event->profiling_command_submit
1890
1891Calls C<clGetEventProfilingInfo> with C<CL_PROFILING_COMMAND_SUBMIT> and returns the result.
1892
1893=item $ulong = $event->profiling_command_start
1894
1895Calls C<clGetEventProfilingInfo> with C<CL_PROFILING_COMMAND_START> and returns the result.
1896
1897=item $ulong = $event->profiling_command_end
1898
1899Calls C<clGetEventProfilingInfo> with C<CL_PROFILING_COMMAND_END> and returns the result.
1900
1901=for gengetinfo end profiling
643 1902
644=back 1903=back
645 1904
646=head2 THE OpenCL::UserEvent CLASS 1905=head2 THE OpenCL::UserEvent CLASS
647 1906
… …
649 1908
650=over 4 1909=over 4
651 1910
652=item $ev->set_status ($execution_status) 1911=item $ev->set_status ($execution_status)
653 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
654L<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>
655 1917
656=back 1918=back
657 1919
658=cut 1920=cut
659
660package OpenCL;
661
662use common::sense;
663
664BEGIN {
665 our $VERSION = '0.15';
666
667 require XSLoader;
668 XSLoader::load (__PACKAGE__, $VERSION);
669
670 @OpenCL::Buffer::ISA =
671 @OpenCL::Image::ISA = OpenCL::Memory::;
672
673 @OpenCL::Image2D::ISA =
674 @OpenCL::Image3D::ISA = OpenCL::Image::;
675
676 @OpenCL::UserEvent::ISA = OpenCL::Event::;
677}
678 1921
6791; 19221;
680 1923
681=head1 AUTHOR 1924=head1 AUTHOR
682 1925

Diff Legend

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