… | |
… | |
28 | specific device ("compiling and linking"), also binary programs. For each |
28 | specific device ("compiling and linking"), also binary programs. For each |
29 | kernel function in a program you can then create an OpenCL::Kernel object |
29 | kernel function in a program you can then create an OpenCL::Kernel object |
30 | which represents basically a function call with argument values. |
30 | which represents basically a function call with argument values. |
31 | |
31 | |
32 | OpenCL::Memory objects of various flavours: OpenCL::Buffer objects (flat |
32 | OpenCL::Memory objects of various flavours: OpenCL::Buffer objects (flat |
33 | memory areas, think arrays or structs) and OpenCL::Image objects (think 2d |
33 | memory areas, think arrays or structs) and OpenCL::Image objects (think 2D |
34 | or 3d array) for bulk data and input and output for kernels. |
34 | or 3D array) for bulk data and input and output for kernels. |
35 | |
35 | |
36 | OpenCL::Sampler objects, which are kind of like texture filter modes in |
36 | OpenCL::Sampler objects, which are kind of like texture filter modes in |
37 | OpenGL. |
37 | OpenGL. |
38 | |
38 | |
39 | OpenCL::Queue objects - command queues, which allow you to submit memory |
39 | OpenCL::Queue objects - command queues, which allow you to submit memory |
… | |
… | |
96 | initialised at creation time). |
96 | initialised at creation time). |
97 | |
97 | |
98 | Enqueue the kernel execution. |
98 | Enqueue the kernel execution. |
99 | |
99 | |
100 | Enqueue buffer reads for your output buffer to read results. |
100 | Enqueue buffer reads for your output buffer to read results. |
101 | |
|
|
102 | =head1 OPENCL 1.1 VS. OPENCL 1.2 |
|
|
103 | |
|
|
104 | This module supports both OpenCL version 1.1 and 1.2, although the OpenCL |
|
|
105 | 1.2 interface hasn't been tested much for lack of availability of an |
|
|
106 | actual implementation. |
|
|
107 | |
|
|
108 | Every function or method in this manual page that interfaces to a |
|
|
109 | particular OpenCL function has a link to the its C manual page. |
|
|
110 | |
|
|
111 | If the link contains a F<1.1>, then this function is an OpenCL 1.1 |
|
|
112 | function. Most but not all also exist in OpenCL 1.2, and this module |
|
|
113 | tries to emulate the missing ones for you, when told to do so at |
|
|
114 | compiletime. You cna check whether a function was removed in OpenCL 1.2 by |
|
|
115 | replacing the F<1.1> component in the URL by F<1.2>. |
|
|
116 | |
|
|
117 | If the link contains a F<1.2>, then this is a OpenCL 1.2-only |
|
|
118 | function. Even if the module was compiled with OpenCL 1.2 header files |
|
|
119 | and has an 1.2 OpenCL library, calling such a function on a platform that |
|
|
120 | doesn't implement 1.2 causes undefined behaviour, usually a crash (But |
|
|
121 | this is not guaranteed). |
|
|
122 | |
|
|
123 | You can find out whether this module was compiled to prefer 1.1 |
|
|
124 | functionality by ooking at C<OpenCL::PREFER_1_1> - if it is true, then |
|
|
125 | 1.1 functions generally are implemented using 1.1 OpenCL functions. If it |
|
|
126 | is false, then 1.1 functions missing from 1.2 are emulated by calling 1.2 |
|
|
127 | fucntions. |
|
|
128 | |
|
|
129 | This is a somewhat sorry state of affairs, but the Khronos group choose to |
|
|
130 | make every release of OpenCL source and binary incompatible with previous |
|
|
131 | releases. |
|
|
132 | |
101 | |
133 | =head1 EXAMPLES |
102 | =head1 EXAMPLES |
134 | |
103 | |
135 | =head2 Enumerate all devices and get contexts for them. |
104 | =head2 Enumerate all devices and get contexts for them. |
136 | |
105 | |
… | |
… | |
244 | $ev->wait; |
213 | $ev->wait; |
245 | |
214 | |
246 | =head2 Use the OpenGL module to share a texture between OpenCL and OpenGL and draw some julia |
215 | =head2 Use the OpenGL module to share a texture between OpenCL and OpenGL and draw some julia |
247 | set flight effect. |
216 | set flight effect. |
248 | |
217 | |
249 | This is quite a long example to get you going - you can download it from |
218 | This is quite a long example to get you going - you can also download it |
250 | L<http://cvs.schmorp.de/OpenCL/examples/juliaflight>. |
219 | from L<http://cvs.schmorp.de/OpenCL/examples/juliaflight>. |
251 | |
220 | |
252 | use OpenGL ":all"; |
221 | use OpenGL ":all"; |
253 | use OpenCL; |
222 | use OpenCL; |
254 | |
223 | |
255 | my $S = $ARGV[0] || 256; # window/texture size, smaller is faster |
224 | my $S = $ARGV[0] || 256; # window/texture size, smaller is faster |
… | |
… | |
424 | =item * This module expects all functions to return C<OpenCL::SUCCESS>. If any |
393 | =item * This module expects all functions to return C<OpenCL::SUCCESS>. If any |
425 | other status is returned the function will throw an exception, so you |
394 | other status is returned the function will throw an exception, so you |
426 | don't normally have to to any error checking. |
395 | don't normally have to to any error checking. |
427 | |
396 | |
428 | =back |
397 | =back |
|
|
398 | |
|
|
399 | =head2 CONSTANTS |
|
|
400 | |
|
|
401 | All C<CL_xxx> constants that this module supports are always available |
|
|
402 | in the C<OpenCL> namespace as C<OpenCL::xxx> (i.e. without the C<CL_> |
|
|
403 | prefix). Constants which are not defined in the header files used during |
|
|
404 | compilation, or otherwise are not available, will have the value C<-1>. |
|
|
405 | |
|
|
406 | The latest version of this module knows and exports the constants |
|
|
407 | listed in L<http://cvs.schmorp.de/OpenCL/constiv.h>. |
|
|
408 | |
|
|
409 | =head2 OPENCL 1.1 VS. OPENCL 1.2 |
|
|
410 | |
|
|
411 | This module supports both OpenCL version 1.1 and 1.2, although the OpenCL |
|
|
412 | 1.2 interface hasn't been tested much for lack of availability of an |
|
|
413 | actual implementation. |
|
|
414 | |
|
|
415 | Every function or method in this manual page that interfaces to a |
|
|
416 | particular OpenCL function has a link to the its C manual page. |
|
|
417 | |
|
|
418 | If the link contains a F<1.1>, then this function is an OpenCL 1.1 |
|
|
419 | function. Most but not all also exist in OpenCL 1.2, and this module |
|
|
420 | tries to emulate the missing ones for you, when told to do so at |
|
|
421 | compiletime. You can check whether a function was removed in OpenCL 1.2 by |
|
|
422 | replacing the F<1.1> component in the URL by F<1.2>. |
|
|
423 | |
|
|
424 | If the link contains a F<1.2>, then this is a OpenCL 1.2-only |
|
|
425 | function. Even if the module was compiled with OpenCL 1.2 header files |
|
|
426 | and has an 1.2 OpenCL library, calling such a function on a platform that |
|
|
427 | doesn't implement 1.2 causes undefined behaviour, usually a crash (But |
|
|
428 | this is not guaranteed). |
|
|
429 | |
|
|
430 | You can find out whether this module was compiled to prefer 1.1 |
|
|
431 | functionality by ooking at C<OpenCL::PREFER_1_1> - if it is true, then |
|
|
432 | 1.1 functions generally are implemented using 1.1 OpenCL functions. If it |
|
|
433 | is false, then 1.1 functions missing from 1.2 are emulated by calling 1.2 |
|
|
434 | fucntions. |
|
|
435 | |
|
|
436 | This is a somewhat sorry state of affairs, but the Khronos group choose to |
|
|
437 | make every release of OpenCL source and binary incompatible with previous |
|
|
438 | releases. |
429 | |
439 | |
430 | =head2 PERL AND OPENCL TYPES |
440 | =head2 PERL AND OPENCL TYPES |
431 | |
441 | |
432 | This handy(?) table lists OpenCL types and their perl, PDL and pack/unpack |
442 | This handy(?) table lists OpenCL types and their perl, PDL and pack/unpack |
433 | format equivalents: |
443 | format equivalents: |
… | |
… | |
631 | The last error returned by a function - it's only valid after an error occured |
641 | The last error returned by a function - it's only valid after an error occured |
632 | and before calling another OpenCL function. |
642 | and before calling another OpenCL function. |
633 | |
643 | |
634 | =item $str = OpenCL::err2str [$errval] |
644 | =item $str = OpenCL::err2str [$errval] |
635 | |
645 | |
636 | Converts an error value into a human readable string. IF no error value is |
646 | Converts an error value into a human readable string. If no error value is |
637 | given, then the last error will be used (as returned by OpenCL::errno). |
647 | given, then the last error will be used (as returned by OpenCL::errno). |
|
|
648 | |
|
|
649 | The latest version of this module knows the error constants |
|
|
650 | listed in L<http://cvs.schmorp.de/OpenCL/errstr.h>. |
638 | |
651 | |
639 | =item $str = OpenCL::enum2str $enum |
652 | =item $str = OpenCL::enum2str $enum |
640 | |
653 | |
641 | Converts most enum values (of parameter names, image format constants, |
654 | Converts most enum values (of parameter names, image format constants, |
642 | object types, addressing and filter modes, command types etc.) into a |
655 | object types, addressing and filter modes, command types etc.) into a |
643 | human readable string. When confronted with some random integer it can be |
656 | human readable string. When confronted with some random integer it can be |
644 | very helpful to pass it through this function to maybe get some readable |
657 | very helpful to pass it through this function to maybe get some readable |
645 | string out of it. |
658 | string out of it. |
|
|
659 | |
|
|
660 | The latest version of this module knows the enumaration constants |
|
|
661 | listed in L<http://cvs.schmorp.de/OpenCL/enumstr.h>. |
646 | |
662 | |
647 | =item @platforms = OpenCL::platforms |
663 | =item @platforms = OpenCL::platforms |
648 | |
664 | |
649 | Returns all available OpenCL::Platform objects. |
665 | Returns all available OpenCL::Platform objects. |
650 | |
666 | |
… | |
… | |
1406 | |
1422 | |
1407 | =item $ev = $queue->copy_buffer ($src, $dst, $src_offset, $dst_offset, $len, $wait_events...) |
1423 | =item $ev = $queue->copy_buffer ($src, $dst, $src_offset, $dst_offset, $len, $wait_events...) |
1408 | |
1424 | |
1409 | L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clEnqueueCopyBuffer.html> |
1425 | L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clEnqueueCopyBuffer.html> |
1410 | |
1426 | |
1411 | =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...) |
1427 | $eue->read_buffer_rect ($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...) |
1412 | |
1428 | |
1413 | http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clEnqueueReadBufferRect.html |
1429 | http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clEnqueueReadBufferRect.html |
1414 | |
1430 | |
1415 | =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...) |
1431 | =item $ev = $queue->write_buffer_rect ($buf, $blocking, $buf_y, $host_x, $host_z, $height, $buf_row_pitch, $host_row_pitch, $data, $wait_events...) |
1416 | |
1432 | |
1417 | http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clEnqueueWriteBufferRect.html |
1433 | http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clEnqueueWriteBufferRect.html |
1418 | |
1434 | |
1419 | =item $ev = $queue->copy_buffer_to_image ($src_buffer, $dst_image, $src_offset, $dst_x, $dst_y, $dst_z, $width, $height, $depth, $wait_events...) |
1435 | =item $ev = $queue->copy_buffer_to_image ($src_buffer, $dst_image, $src_offset, $dst_x, $dst_y, $dst_z, $width, $height, $depth, $wait_events...) |
1420 | |
1436 | |
… | |
… | |
1604 | it. You are not necessarily meant to do it this way, this example just |
1620 | it. You are not necessarily meant to do it this way, this example just |
1605 | shows you the accessors to use :) |
1621 | shows you the accessors to use :) |
1606 | |
1622 | |
1607 | my $mapped = $queue->map_image ($image, 1, OpenCL::MAP_WRITE); |
1623 | my $mapped = $queue->map_image ($image, 1, OpenCL::MAP_WRITE); |
1608 | |
1624 | |
1609 | $mapped->set ($_ * $mapped->row_pitch, pack "C", 5) |
1625 | $mapped->write ($_ * $mapped->row_pitch, pack "C", 5) |
1610 | for 0..$image->height; |
1626 | for 0 .. $mapped->height - 1; |
1611 | |
1627 | |
1612 | $mapped->unmap;. |
1628 | $mapped->unmap;. |
1613 | $mapped->wait; # only needed for out of order queues normally |
1629 | $mapped->wait; # only needed for out of order queues normally |
1614 | |
1630 | |
1615 | =item $ev = $queue->unmap ($mapped, $wait_events...) |
1631 | =item $ev = $queue->unmap ($mapped, $wait_events...) |
… | |
… | |
1634 | =item $packed_value = $memory->info ($name) |
1650 | =item $packed_value = $memory->info ($name) |
1635 | |
1651 | |
1636 | See C<< $platform->info >> for details. |
1652 | See C<< $platform->info >> for details. |
1637 | |
1653 | |
1638 | L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clGetMemObjectInfo.html> |
1654 | L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clGetMemObjectInfo.html> |
|
|
1655 | |
|
|
1656 | =item $memory->destructor_callback ($cb->()) |
|
|
1657 | |
|
|
1658 | Sets a callback that will be invoked after the memory object is destructed. |
|
|
1659 | |
|
|
1660 | L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clSetMemObjectDestructorCallback.html> |
1639 | |
1661 | |
1640 | =for gengetinfo begin mem |
1662 | =for gengetinfo begin mem |
1641 | |
1663 | |
1642 | =item $mem_object_type = $mem->type |
1664 | =item $mem_object_type = $mem->type |
1643 | |
1665 | |
… | |
… | |
2321 | |
2343 | |
2322 | This is a subclass of OpenCL::Mapped, representing mapped images. |
2344 | This is a subclass of OpenCL::Mapped, representing mapped images. |
2323 | |
2345 | |
2324 | =over 4 |
2346 | =over 4 |
2325 | |
2347 | |
|
|
2348 | =item $pixels = $mapped->width |
|
|
2349 | |
|
|
2350 | =item $pixels = $mapped->height |
|
|
2351 | |
|
|
2352 | =item $pixels = $mapped->depth |
|
|
2353 | |
|
|
2354 | Return the width/height/depth of the mapped image region, in pixels. |
|
|
2355 | |
2326 | =item $bytes = $mapped->row_pitch |
2356 | =item $bytes = $mapped->row_pitch |
2327 | |
2357 | |
2328 | =item $bytes = $mapped->slice_pitch |
2358 | =item $bytes = $mapped->slice_pitch |
2329 | |
2359 | |
2330 | Return the row or slice pitch of the image that has been mapped. |
2360 | Return the row or slice pitch of the image that has been mapped. |
2331 | |
2361 | |
|
|
2362 | =item $bytes = $mapped->element_size |
|
|
2363 | |
|
|
2364 | Return the size of a single pixel. |
|
|
2365 | |
|
|
2366 | =item $data = $mapped->get_row ($count, $x=0, $y=0, $z=0) |
|
|
2367 | |
|
|
2368 | Return C<$count> pixels from the given coordinates. The pixel data must |
|
|
2369 | be completely contained within a single row. |
|
|
2370 | |
|
|
2371 | If C<$count> is C<undef>, then all the remaining pixels in that row are |
|
|
2372 | returned. |
|
|
2373 | |
|
|
2374 | =item $mapped->set_row ($data, $x=0, $y=0, $z=0) |
|
|
2375 | |
|
|
2376 | Write the given pixel data at the given coordinate. The pixel data must |
|
|
2377 | be completely contained within a single row. |
|
|
2378 | |
2332 | =back |
2379 | =back |
2333 | |
|
|
2334 | |
2380 | |
2335 | =cut |
2381 | =cut |
2336 | |
2382 | |
2337 | 1; |
2383 | 1; |
2338 | |
2384 | |