… | |
… | |
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 |
… | |
… | |
419 | |
388 | |
420 | =item * When enqueuing commands, if the enqueue method is called in void |
389 | =item * When enqueuing commands, if the enqueue method is called in void |
421 | context, no event is created. In all other contexts an event is returned |
390 | context, no event is created. In all other contexts an event is returned |
422 | by the method. |
391 | by the method. |
423 | |
392 | |
424 | =item * This module expects all functions to return C<CL_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. |
646 | |
659 | |
|
|
660 | The latest version of this module knows the enumaration constants |
|
|
661 | listed in L<http://cvs.schmorp.de/OpenCL/errstr.h>. |
|
|
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 | |
651 | L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clGetPlatformIDs.html> |
667 | L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clGetPlatformIDs.html> |
… | |
… | |
752 | L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clCreateContextFromType.html> |
768 | L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clCreateContextFromType.html> |
753 | |
769 | |
754 | =item $ctx = $platform->context ($properties, \@devices, $callback->($err, $pvt) = $print_stderr) |
770 | =item $ctx = $platform->context ($properties, \@devices, $callback->($err, $pvt) = $print_stderr) |
755 | |
771 | |
756 | Create a new OpenCL::Context object using the given device object(s)- a |
772 | Create a new OpenCL::Context object using the given device object(s)- a |
757 | CL_CONTEXT_PLATFORM property is supplied automatically. |
773 | OpenCL::CONTEXT_PLATFORM property is supplied automatically. |
758 | |
774 | |
759 | L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clCreateContext.html> |
775 | L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clCreateContext.html> |
760 | |
776 | |
761 | =item $packed_value = $platform->info ($name) |
777 | =item $packed_value = $platform->info ($name) |
762 | |
778 | |
… | |
… | |
807 | =over 4 |
823 | =over 4 |
808 | |
824 | |
809 | =item $packed_value = $device->info ($name) |
825 | =item $packed_value = $device->info ($name) |
810 | |
826 | |
811 | See C<< $platform->info >> for details. |
827 | See C<< $platform->info >> for details. |
|
|
828 | |
|
|
829 | type: OpenCL::DEVICE_TYPE_DEFAULT, OpenCL::DEVICE_TYPE_CPU, |
|
|
830 | OpenCL::DEVICE_TYPE_GPU, OpenCL::DEVICE_TYPE_ACCELERATOR, |
|
|
831 | OpenCL::DEVICE_TYPE_CUSTOM, OpenCL::DEVICE_TYPE_ALL. |
|
|
832 | |
|
|
833 | fp_config: OpenCL::FP_DENORM, OpenCL::FP_INF_NAN, OpenCL::FP_ROUND_TO_NEAREST, |
|
|
834 | OpenCL::FP_ROUND_TO_ZERO, OpenCL::FP_ROUND_TO_INF, OpenCL::FP_FMA, |
|
|
835 | OpenCL::FP_SOFT_FLOAT, OpenCL::FP_CORRECTLY_ROUNDED_DIVIDE_SQRT. |
|
|
836 | |
|
|
837 | mem_cache_type: OpenCL::NONE, OpenCL::READ_ONLY_CACHE, OpenCL::READ_WRITE_CACHE. |
|
|
838 | |
|
|
839 | local_mem_type: OpenCL::LOCAL, OpenCL::GLOBAL. |
|
|
840 | |
|
|
841 | exec_capabilities: OpenCL::EXEC_KERNEL, OpenCL::EXEC_NATIVE_KERNEL. |
|
|
842 | |
|
|
843 | command_queue_properties: OpenCL::QUEUE_OUT_OF_ORDER_EXEC_MODE_ENABLE, |
|
|
844 | OpenCL::QUEUE_PROFILING_ENABLE. |
|
|
845 | |
|
|
846 | partition_properties: OpenCL::DEVICE_PARTITION_EQUALLY, |
|
|
847 | OpenCL::DEVICE_PARTITION_BY_COUNTS, OpenCL::DEVICE_PARTITION_BY_COUNTS_LIST_END, |
|
|
848 | OpenCL::DEVICE_PARTITION_BY_AFFINITY_DOMAIN. |
|
|
849 | |
|
|
850 | affinity_domain: OpenCL::DEVICE_AFFINITY_DOMAIN_NUMA, |
|
|
851 | OpenCL::DEVICE_AFFINITY_DOMAIN_L4_CACHE, OpenCL::DEVICE_AFFINITY_DOMAIN_L3_CACHE, |
|
|
852 | OpenCL::DEVICE_AFFINITY_DOMAIN_L2_CACHE, OpenCL::DEVICE_AFFINITY_DOMAIN_L1_CACHE, |
|
|
853 | OpenCL::DEVICE_AFFINITY_DOMAIN_NEXT_PARTITIONABLE. |
812 | |
854 | |
813 | L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clGetDeviceInfo.html> |
855 | L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clGetDeviceInfo.html> |
814 | |
856 | |
815 | =item @devices = $device->sub_devices (\@properties) |
857 | =item @devices = $device->sub_devices (\@properties) |
816 | |
858 | |
… | |
… | |
1196 | OpenCL::UNORM_INT16, OpenCL::UNORM_SHORT_565, OpenCL::UNORM_SHORT_555, |
1238 | OpenCL::UNORM_INT16, OpenCL::UNORM_SHORT_565, OpenCL::UNORM_SHORT_555, |
1197 | OpenCL::UNORM_INT_101010, OpenCL::SIGNED_INT8, OpenCL::SIGNED_INT16, |
1239 | OpenCL::UNORM_INT_101010, OpenCL::SIGNED_INT8, OpenCL::SIGNED_INT16, |
1198 | OpenCL::SIGNED_INT32, OpenCL::UNSIGNED_INT8, OpenCL::UNSIGNED_INT16, |
1240 | OpenCL::SIGNED_INT32, OpenCL::UNSIGNED_INT8, OpenCL::UNSIGNED_INT16, |
1199 | OpenCL::UNSIGNED_INT32, OpenCL::HALF_FLOAT, OpenCL::FLOAT. |
1241 | OpenCL::UNSIGNED_INT32, OpenCL::HALF_FLOAT, OpenCL::FLOAT. |
1200 | |
1242 | |
1201 | |
|
|
1202 | type: OpenCL::MEM_OBJECT_BUFFER, OpenCL::MEM_OBJECT_IMAGE2D, |
1243 | type: OpenCL::MEM_OBJECT_BUFFER, OpenCL::MEM_OBJECT_IMAGE2D, |
1203 | OpenCL::MEM_OBJECT_IMAGE3D, OpenCL::MEM_OBJECT_IMAGE2D_ARRAY, |
1244 | OpenCL::MEM_OBJECT_IMAGE3D, OpenCL::MEM_OBJECT_IMAGE2D_ARRAY, |
1204 | OpenCL::MEM_OBJECT_IMAGE1D, OpenCL::MEM_OBJECT_IMAGE1D_ARRAY, |
1245 | OpenCL::MEM_OBJECT_IMAGE1D, OpenCL::MEM_OBJECT_IMAGE1D_ARRAY, |
1205 | OpenCL::MEM_OBJECT_IMAGE1D_BUFFER. |
1246 | OpenCL::MEM_OBJECT_IMAGE1D_BUFFER. |
1206 | |
1247 | |
… | |
… | |
1676 | =over 4 |
1717 | =over 4 |
1677 | |
1718 | |
1678 | =item $subbuf = $buf_obj->sub_buffer_region ($flags, $origin, $size) |
1719 | =item $subbuf = $buf_obj->sub_buffer_region ($flags, $origin, $size) |
1679 | |
1720 | |
1680 | Creates an OpenCL::Buffer objects from this buffer and returns it. The |
1721 | Creates an OpenCL::Buffer objects from this buffer and returns it. The |
1681 | C<buffer_create_type> is assumed to be C<CL_BUFFER_CREATE_TYPE_REGION>. |
1722 | C<buffer_create_type> is assumed to be C<OpenCL::BUFFER_CREATE_TYPE_REGION>. |
1682 | |
1723 | |
1683 | L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clCreateSubBuffer.html> |
1724 | L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clCreateSubBuffer.html> |
1684 | |
1725 | |
1685 | =back |
1726 | =back |
1686 | |
1727 | |
… | |
… | |
1702 | L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clGetImageInfo.html> |
1743 | L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clGetImageInfo.html> |
1703 | |
1744 | |
1704 | =item ($channel_order, $channel_data_type) = $image->format |
1745 | =item ($channel_order, $channel_data_type) = $image->format |
1705 | |
1746 | |
1706 | Returns the channel order and type used to create the image by calling |
1747 | Returns the channel order and type used to create the image by calling |
1707 | C<clGetImageInfo> with C<CL_IMAGE_FORMAT>. |
1748 | C<clGetImageInfo> with C<OpenCL::IMAGE_FORMAT>. |
1708 | |
1749 | |
1709 | =for gengetinfo begin image |
1750 | =for gengetinfo begin image |
1710 | |
1751 | |
1711 | =item $int = $image->element_size |
1752 | =item $int = $image->element_size |
1712 | |
1753 | |
… | |
… | |
1835 | =item $packed_value = $program->build_info ($device, $name) |
1876 | =item $packed_value = $program->build_info ($device, $name) |
1836 | |
1877 | |
1837 | Similar to C<< $platform->info >>, but returns build info for a previous |
1878 | Similar to C<< $platform->info >>, but returns build info for a previous |
1838 | build attempt for the given device. |
1879 | build attempt for the given device. |
1839 | |
1880 | |
|
|
1881 | binary_type: OpenCL::PROGRAM_BINARY_TYPE_NONE, |
|
|
1882 | OpenCL::PROGRAM_BINARY_TYPE_COMPILED_OBJECT, |
|
|
1883 | OpenCL::PROGRAM_BINARY_TYPE_LIBRARY, |
|
|
1884 | OpenCL::PROGRAM_BINARY_TYPE_EXECUTABLE. |
|
|
1885 | |
1840 | L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clGetBuildInfo.html> |
1886 | L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clGetBuildInfo.html> |
1841 | |
1887 | |
1842 | =item $kernel = $program->kernel ($function_name) |
1888 | =item $kernel = $program->kernel ($function_name) |
1843 | |
1889 | |
1844 | Creates an OpenCL::Kernel object out of the named C<__kernel> function in |
1890 | Creates an OpenCL::Kernel object out of the named C<__kernel> function in |
… | |
… | |
1863 | Calls C<clGetProgramBuildInfo> with C<OpenCL::PROGRAM_BUILD_OPTIONS> and returns the result. |
1909 | Calls C<clGetProgramBuildInfo> with C<OpenCL::PROGRAM_BUILD_OPTIONS> and returns the result. |
1864 | |
1910 | |
1865 | =item $string = $program->build_log ($device) |
1911 | =item $string = $program->build_log ($device) |
1866 | |
1912 | |
1867 | Calls C<clGetProgramBuildInfo> with C<OpenCL::PROGRAM_BUILD_LOG> and returns the result. |
1913 | Calls C<clGetProgramBuildInfo> with C<OpenCL::PROGRAM_BUILD_LOG> and returns the result. |
|
|
1914 | |
|
|
1915 | =item $binary_type = $program->binary_type ($device) |
|
|
1916 | |
|
|
1917 | Calls C<clGetProgramBuildInfo> with C<OpenCL::PROGRAM_BINARY_TYPE> and returns the result. |
1868 | |
1918 | |
1869 | =for gengetinfo end program_build |
1919 | =for gengetinfo end program_build |
1870 | |
1920 | |
1871 | =item $packed_value = $program->info ($name) |
1921 | =item $packed_value = $program->info ($name) |
1872 | |
1922 | |