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

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

Diff Legend

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