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

Comparing OpenCL/OpenCL.pm (file contents):
Revision 1.11 by root, Thu Nov 17 02:54:14 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 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 - 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>.
336
202=head1 DOCUMENTATION 337=head1 DOCUMENTATION
203 338
204=head2 BASIC CONVENTIONS 339=head2 BASIC CONVENTIONS
205 340
206This is not a 1:1 C-style translation of OpenCL to Perl - instead I 341This 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 342I attempted to make the interface as type-safe as possible by introducing
208object syntax where it makes sense. There are a number of important 343object syntax where it makes sense. There are a number of important
209differences between the OpenCL C API and this module: 344differences between the OpenCL C API and this module:
210 345
211=over 4 346=over 4
212 347
213=item * Object lifetime managament is automatic - there is no need 348=item * Object lifetime managament is automatic - there is no need
214to free objects explicitly (C<clReleaseXXX>), the release function 349to free objects explicitly (C<clReleaseXXX>), the release function
215is called automatically once all Perl references to it go away. 350is called automatically once all Perl references to it go away.
216 351
217=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
218while this module uses underscores as word separator and often leaves out 354uses underscores as word separator and often leaves out prefixes
219prefixes (C<< $platform->info >>). 355(C<OpenCL::platforms>, C<< $platform->info >>).
220 356
221=item * OpenCL often specifies fixed vector function arguments as short 357=item * OpenCL often specifies fixed vector function arguments as short
222arrays (C<size_t origin[3]>), while this module explicitly expects the 358arrays (C<size_t origin[3]>), while this module explicitly expects the
223components as separate arguments- 359components as separate arguments (C<$orig_x, $orig_y, $orig_z>) in
360function calls.
224 361
225=item * Where possible, one of the pitch values is calculated from the 362=item * Structures are often specified by flattening out their components
226perl scalar length and need not be specified. 363as with short vectors, and returned as arrayrefs.
227 364
228=item * When enqueuing commands, the wait list is specified by adding 365=item * When enqueuing commands, the wait list is specified by adding
229extra arguments to the function - anywhere a C<$wait_events...> argument 366extra arguments to the function - anywhere a C<$wait_events...> argument
230is 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.
231 370
232=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
233context, 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
234by the method. 373by the method.
235 374
… …
255 ulong IV - Q 394 ulong IV - Q
256 float NV float f 395 float NV float f
257 half IV ushort S 396 half IV ushort S
258 double NV double d 397 double NV double d
259 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
260=head2 THE OpenCL PACKAGE 564=head2 THE OpenCL PACKAGE
261 565
262=over 4 566=over 4
263 567
264=item $int = OpenCL::errno 568=item $int = OpenCL::errno
265 569
266The 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
267and before calling another OpenCL function. 571and before calling another OpenCL function.
268 572
269=item $str = OpenCL::err2str $errval 573=item $str = OpenCL::err2str [$errval]
270 574
271Comverts 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).
272 577
273=item $str = OpenCL::enum2str $enum 578=item $str = OpenCL::enum2str $enum
274 579
275Converts most enum values (inof parameter names, image format constants, 580Converts most enum values (of parameter names, image format constants,
276object types, addressing and filter modes, command types etc.) into a 581object types, addressing and filter modes, command types etc.) into a
277human readbale string. When confronted with some random integer it can be 582human readable string. When confronted with some random integer it can be
278very 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
279string out of it. 584string out of it.
280 585
281=item @platforms = OpenCL::platforms 586=item @platforms = OpenCL::platforms
282 587
283Returns all available OpenCL::Platform objects. 588Returns all available OpenCL::Platform objects.
284 589
285L<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>
286 591
287=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
288 593
289Tries 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.
290 595
291L<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>
292 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
293=item OpenCL::wait_for_events $wait_events... 605=item OpenCL::wait_for_events $wait_events...
294 606
295Waits for all events to complete. 607Waits for all events to complete.
296 608
297L<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>
298 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
299=back 648=back
300 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
301=head2 THE OpenCL::Platform CLASS 675=head2 THE OpenCL::Platform CLASS
302 676
303=over 4 677=over 4
304 678
305=item $packed_value = $platform->info ($name)
306
307Calls C<clGetPlatformInfo> and returns the packed, raw value - for
308strings, this will be the string, for other values you probably need to
309use the correct C<unpack>. This might get improved in the future. Hopefully.
310
311L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clGetPlatformInfo.html>
312
313=item @devices = $platform->devices ($type = OpenCL::DEVICE_TYPE_ALL) 679=item @devices = $platform->devices ($type = OpenCL::DEVICE_TYPE_ALL)
314 680
315Returns a list of matching OpenCL::Device objects. 681Returns a list of matching OpenCL::Device objects.
316 682
317=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)
318 684
319Tries 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.
320 686
321L<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>
322 688
323=item $ctx = $device->context ($properties = undef, @$devices, $notify = undef) 689=item $ctx = $platform->context ($properties, \@devices, $callback->($err, $pvt) = $print_stderr)
324 690
325Create 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
326CL_CONTEXT_PLATFORM property is supplied automatically. 692CL_CONTEXT_PLATFORM property is supplied automatically.
327 693
328L<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>
329 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
330=back 738=back
331 739
332=head2 THE OpenCL::Device CLASS 740=head2 THE OpenCL::Device CLASS
333 741
334=over 4 742=over 4
… …
337 745
338See C<< $platform->info >> for details. 746See C<< $platform->info >> for details.
339 747
340L<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>
341 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
342=back 1018=back
343 1019
344=head2 THE OpenCL::Context CLASS 1020=head2 THE OpenCL::Context CLASS
345 1021
346=over 4 1022=over 4
347 1023
348=item $packed_value = $ctx->info ($name) 1024=item $prog = $ctx->build_program ($program, $options = "")
349 1025
350See 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.
351 1029
352L<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}
353 1056
354=item $queue = $ctx->queue ($device, $properties) 1057=item $queue = $ctx->queue ($device, $properties)
355 1058
356Create 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.
357 1060
358L<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>
359 1062
1063Example: create an out-of-order queue.
1064
1065 $queue = $ctx->queue ($device, OpenCL::QUEUE_OUT_OF_ORDER_EXEC_MODE_ENABLE);
1066
360=item $ev = $ctx->user_event 1067=item $ev = $ctx->user_event
361 1068
362Creates a new OpenCL::UserEvent object. 1069Creates a new OpenCL::UserEvent object.
363 1070
364L<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>
365 1072
366=item $buf = $ctx->buffer ($flags, $len) 1073=item $buf = $ctx->buffer ($flags, $len)
367 1074
368Creates 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.
369 1077
370L<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>
371 1079
372=item $buf = $ctx->buffer_sv ($flags, $data) 1080=item $buf = $ctx->buffer_sv ($flags, $data)
373 1081
374Creates 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.
375 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>
1091
376=item $img = $ctx->image2d ($flags, $channel_order, $channel_type, $width, $height, $data) 1092=item $img = $ctx->image2d ($flags, $channel_order, $channel_type, $width, $height, $row_pitch = 0, $data = undef)
377 1093
378Creates 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.
379 1096
380L<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>
381 1098
382=item $img = $ctx->image3d ($flags, $channel_order, $channel_type, $width, $height, $depth, $slice_pitch, $data) 1099=item $img = $ctx->image3d ($flags, $channel_order, $channel_type, $width, $height, $depth, $row_pitch = 0, $slice_pitch = 0, $data = undef)
383 1100
384Creates 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.
385 1103
386L<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
387 1140
388=item @formats = $ctx->supported_image_formats ($flags, $image_type) 1141=item @formats = $ctx->supported_image_formats ($flags, $image_type)
389 1142
390Returns 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
391two values, $channel_order and $channel_type, in it. 1144two values, $channel_order and $channel_type, in it.
… …
402 1155
403Creates a new OpenCL::Program object from the given source code. 1156Creates a new OpenCL::Program object from the given source code.
404 1157
405L<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>
406 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
407=back 1186=back
408 1187
409=head2 THE OpenCL::Queue CLASS 1188=head2 THE OpenCL::Queue CLASS
410 1189
411An OpenCL::Queue represents an execution queue for OpenCL. You execute 1190An OpenCL::Queue represents an execution queue for OpenCL. You execute
412requests by calling their respective C<enqueue_xxx> method and waitinf for 1191requests by calling their respective method and waiting for it to complete
413it to complete in some way. 1192in some way.
414 1193
415All 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
416for completion, unless the method is called in void context, in which case 1195be used to wait for completion (optionally using a callback), unless
417no event object is created. 1196the method is called in void context, in which case no event object is
1197created.
418 1198
419They 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
420request 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
421event 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);
422 1207
423Queues execute in-order by default, without any parallelism, so in most 1208Queues execute in-order by default, without any parallelism, so in most
424cases (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
425create event objects. 1210create event objects, althoguh an our of order queue is often a bit
1211faster.
426 1212
427=over 4 1213=over 4
428 1214
429=item $packed_value = $ctx->info ($name)
430
431See C<< $platform->info >> for details.
432
433L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clGetCommandQueueInfo.html>
434
435=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...)
436 1216
437Reads data from buffer into the given string. 1217Reads data from buffer into the given string.
438 1218
439L<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>
440 1220
441=item $ev = $queue->enqueue_write_buffer ($buffer, $blocking, $offset, $data, $wait_events...) 1221=item $ev = $queue->write_buffer ($buffer, $blocking, $offset, $data, $wait_events...)
442 1222
443Writes data to buffer from the given string. 1223Writes data to buffer from the given string.
444 1224
445L<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>
446 1226
447=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...)
448 1228
449L<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>
450 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
451=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.
452 1247
453L<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>
454 1249
455=item $ev = $queue->enqueue_write_image ($src, $blocking, $x, $y, $z, $width, $height, $depth, $row_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...)
456 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.
457L<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>
458 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
459=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...) 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...)
460 1265
461Yeah. 1266Yeah.
462 1267
463L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clEnqueueCopyBufferRect.html>
464
465=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, ...)
466
467L<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>.
468 1269
469=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, ...) 1270=item $ev = $queue->fill_buffer ($mem, $pattern, $offset, $size, ...)
470 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
471L<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>
472 1285
473=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, ...)
474
475L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clEnqueueCopyImageToBuffer.html>
476
477=item $ev = $queue->enqueue_task ($kernel, $wait_events...) 1286=item $ev = $queue->task ($kernel, $wait_events...)
478 1287
479L<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>
480 1289
481=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...)
482 1291
483Enqueues a kernel execution. 1292Enqueues a kernel execution.
484 1293
485@$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
486integers specifying the work sizes (element counts). 1295integers specifying the work sizes (element counts).
487 1296
488@$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
489are 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
490of elements as @$global_work_size. 1299of elements as \@global_work_size.
491 1300
492@$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
493implementation is supposed to choose good local work sizes), or a 1302implementation is supposed to choose good local work sizes), or a
494reference 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
495elements as @$global_work_size. 1304elements as \@global_work_size.
496 1305
497L<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>
498 1307
499=item $ev = $queue->enqueue_marker 1308=item $ev = $queue->acquire_gl_objects ([object, ...], $wait_events...)
500 1309
1310Enqueues a list (an array-ref of OpenCL::Memory objects) to be acquired
1311for subsequent OpenCL usage.
1312
501L<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>
502 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
503=item $ev = $queue->enqueue_wait_for_events ($wait_events...) 1322=item $ev = $queue->wait_for_events ($wait_events...)
504 1323
505L<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>
506 1325
507=item $queue->enqueue_barrier 1326=item $ev = $queue->marker ($wait_events...)
508 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
509L<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>
510 1333
511=item $queue->flush 1334=item $queue->flush
512 1335
513L<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>
514 1337
515=item $queue->finish 1338=item $queue->finish
516 1339
517L<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>
518 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
519=back 1368=back
520 1369
521=head2 THE OpenCL::Memory CLASS 1370=head2 THE OpenCL::Memory CLASS
522 1371
523This the superclass of all memory objects - OpenCL::Buffer, OpenCL::Image, 1372This the superclass of all memory objects - OpenCL::Buffer, OpenCL::Image,
524OpenCL::Image2D and OpenCL::Image3D. The subclasses of this class 1373OpenCL::Image2D and OpenCL::Image3D.
525currently only exist to allow type-checking.
526 1374
527=over 4 1375=over 4
528 1376
529=item $packed_value = $memory->info ($name) 1377=item $packed_value = $memory->info ($name)
530 1378
531See C<< $platform->info >> for details. 1379See C<< $platform->info >> for details.
532 1380
533L<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>
534 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
535=back 1430=back
536 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
537=head2 THE OpenCL::Sampler CLASS 1519=head2 THE OpenCL::Sampler CLASS
538 1520
539=over 4 1521=over 4
540 1522
541=item $packed_value = $sampler->info ($name) 1523=item $packed_value = $sampler->info ($name)
542 1524
543See C<< $platform->info >> for details. 1525See C<< $platform->info >> for details.
544 1526
545L<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>
546 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
547=back 1553=back
548 1554
549=head2 THE OpenCL::Program CLASS 1555=head2 THE OpenCL::Program CLASS
550 1556
551=over 4 1557=over 4
552 1558
553=item $packed_value = $program->info ($name) 1559=item $program->build (\@devices = undef, $options = "", $cb->($program) = undef)
554 1560
555See C<< $platform->info >> for details.
556
557L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clGetProgramInfo.html>
558
559=item $program->build ($device, $options = "")
560
561Tries 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.
562 1576
563L<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).
564 1583
565=item $packed_value = $program->build_info ($device, $name) 1584=item $packed_value = $program->build_info ($device, $name)
566 1585
567Similar to C<< $platform->info >>, but returns build info for a previous 1586Similar to C<< $platform->info >>, but returns build info for a previous
568build attempt for the given device. 1587build attempt for the given device.
… …
574Creates 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
575the program. 1594the program.
576 1595
577L<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>
578 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
579=back 1665=back
580 1666
581=head2 THE OpenCL::Kernel CLASS 1667=head2 THE OpenCL::Kernel CLASS
582 1668
583=over 4 1669=over 4
… …
586 1672
587See C<< $platform->info >> for details. 1673See C<< $platform->info >> for details.
588 1674
589L<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>
590 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
591=item $kernel->set_TYPE ($index, $value) 1768=item $kernel->set_TYPE ($index, $value)
592 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
593This 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
594 1805C<$index> to the give C<$value>.
595TYPE is one of C<char>, C<uchar>, C<short>, C<ushort>, C<int>, C<uint>,
596C<long>, C<ulong>, C<half>, C<float>, C<double>, C<memory>, C<buffer>,
597C<image2d>, C<image3d>, C<sampler> or C<event>.
598 1806
599Chars and integers (including the half type) are specified as integers, 1807Chars and integers (including the half type) are specified as integers,
600float and double as floating point values, memory/buffer/image2d/image3d 1808float and double as floating point values, memory/buffer/image must be
601must 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
602objects 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.
603 1819
604L<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>
605 1821
606=back 1822=back
607 1823
… …
610This is the superclass for all event objects (including OpenCL::UserEvent 1826This is the superclass for all event objects (including OpenCL::UserEvent
611objects). 1827objects).
612 1828
613=over 4 1829=over 4
614 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
615=item $packed_value = $ev->info ($name) 1844=item $packed_value = $ev->info ($name)
616 1845
617See C<< $platform->info >> for details. 1846See C<< $platform->info >> for details.
618 1847
619L<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>
620 1849
621=item $ev->wait 1850=for gengetinfo begin event
622 1851
623Waits for the event to complete. 1852=item $queue = $event->command_queue
624 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
625L<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
626 1902
627=back 1903=back
628 1904
629=head2 THE OpenCL::UserEvent CLASS 1905=head2 THE OpenCL::UserEvent CLASS
630 1906
… …
632 1908
633=over 4 1909=over 4
634 1910
635=item $ev->set_status ($execution_status) 1911=item $ev->set_status ($execution_status)
636 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
637L<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>
638 1917
639=back 1918=back
640 1919
641=cut 1920=cut
642
643package OpenCL;
644
645use common::sense;
646
647BEGIN {
648 our $VERSION = '0.03';
649
650 require XSLoader;
651 XSLoader::load (__PACKAGE__, $VERSION);
652
653 @OpenCL::Buffer::ISA =
654 @OpenCL::Image::ISA = OpenCL::Memory::;
655
656 @OpenCL::Image2D::ISA =
657 @OpenCL::Image3D::ISA = OpenCL::Image::;
658
659 @OpenCL::UserEvent::ISA = OpenCL::Event::;
660}
661 1921
6621; 19221;
663 1923
664=head1 AUTHOR 1924=head1 AUTHOR
665 1925

Diff Legend

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