… | |
… | |
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. |
101 | |
132 | |
102 | =head1 EXAMPLES |
133 | =head1 EXAMPLES |
103 | |
134 | |
104 | =head2 Enumerate all devices and get contexts for them. |
135 | =head2 Enumerate all devices and get contexts for them. |
105 | |
136 | |
… | |
… | |
434 | OpenCL can generate a number of (potentially) asynchronous events, for |
465 | OpenCL can generate a number of (potentially) asynchronous events, for |
435 | example, after compiling a program, to signal a context-related error or, |
466 | example, after compiling a program, to signal a context-related error or, |
436 | perhaps most important, to signal completion of queued jobs (by setting |
467 | perhaps most important, to signal completion of queued jobs (by setting |
437 | callbacks on OpenCL::Event objects). |
468 | callbacks on OpenCL::Event objects). |
438 | |
469 | |
|
|
470 | The OpenCL module converts all these callbacks into events - you can |
|
|
471 | still register callbacks, but they are not executed when your OpenCL |
|
|
472 | implementation calls the actual callback, but only later. Therefore, none |
|
|
473 | of the limitations of OpenCL callbacks apply to the perl implementation: |
|
|
474 | it is perfectly safe to make blocking operations from event callbacks, and |
|
|
475 | enqueued operations don't need to be flushed. |
|
|
476 | |
439 | To facilitate this, this module maintains an event queue - each |
477 | To facilitate this, this module maintains an event queue - each |
440 | time an asynchronous event happens, it is queued, and perl will be |
478 | time an asynchronous event happens, it is queued, and perl will be |
441 | interrupted. This is implemented via the L<Async::Interrupt> module. In |
479 | interrupted. This is implemented via the L<Async::Interrupt> module. In |
442 | addition, this module has L<AnyEvent> support, so it can seamlessly |
480 | addition, this module has L<AnyEvent> support, so it can seamlessly |
443 | integrate itself into many event loops. |
481 | integrate itself into many event loops. |
444 | |
482 | |
445 | Since this module is a bit hard to understand, here are some case examples: |
483 | Since L<Async::Interrupt> is a bit hard to understand, here are some case examples: |
446 | |
484 | |
447 | =head3 Don't use callbacks. |
485 | =head3 Don't use callbacks. |
448 | |
486 | |
449 | When your program never uses any callbacks, then there will never be any |
487 | When your program never uses any callbacks, then there will never be any |
450 | notifications you need to take care of, and therefore no need to worry |
488 | notifications you need to take care of, and therefore no need to worry |
… | |
… | |
613 | L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clGetPlatformIDs.html> |
651 | L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clGetPlatformIDs.html> |
614 | |
652 | |
615 | =item $ctx = OpenCL::context_from_type $properties, $type = OpenCL::DEVICE_TYPE_DEFAULT, $callback->($err, $pvt) = $print_stderr |
653 | =item $ctx = OpenCL::context_from_type $properties, $type = OpenCL::DEVICE_TYPE_DEFAULT, $callback->($err, $pvt) = $print_stderr |
616 | |
654 | |
617 | Tries to create a context from a default device and platform type - never worked for me. |
655 | Tries to create a context from a default device and platform type - never worked for me. |
|
|
656 | Consider using C<< $platform->context_from_type >> instead. |
618 | |
657 | |
619 | type: OpenCL::DEVICE_TYPE_DEFAULT, OpenCL::DEVICE_TYPE_CPU, OpenCL::DEVICE_TYPE_GPU, |
658 | type: OpenCL::DEVICE_TYPE_DEFAULT, OpenCL::DEVICE_TYPE_CPU, OpenCL::DEVICE_TYPE_GPU, |
620 | OpenCL::DEVICE_TYPE_ACCELERATOR, OpenCL::DEVICE_TYPE_CUSTOM, OpenCL::DEVICE_TYPE_ALL. |
659 | OpenCL::DEVICE_TYPE_ACCELERATOR, OpenCL::DEVICE_TYPE_CUSTOM, OpenCL::DEVICE_TYPE_ALL. |
621 | |
660 | |
622 | L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clCreateContextFromType.html> |
661 | L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clCreateContextFromType.html> |
623 | |
662 | |
624 | =item $ctx = OpenCL::context $properties, \@devices, $callback->($err, $pvt) = $print_stderr) |
663 | =item $ctx = OpenCL::context $properties, \@devices, $callback->($err, $pvt) = $print_stderr) |
625 | |
664 | |
626 | Create a new OpenCL::Context object using the given device object(s). This |
665 | Create a new OpenCL::Context object using the given device object(s). |
627 | function isn't implemented yet, use C<< $platform->context >> instead. |
666 | Consider using C<< $platform->context >> instead. |
628 | |
667 | |
629 | L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clCreateContext.html> |
668 | L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clCreateContext.html> |
630 | |
669 | |
631 | =item OpenCL::wait_for_events $wait_events... |
670 | =item OpenCL::wait_for_events $wait_events... |
632 | |
671 | |
… | |
… | |
1263 | =item $program = $ctx->program_with_built_in_kernels (\@devices, $kernel_names) |
1302 | =item $program = $ctx->program_with_built_in_kernels (\@devices, $kernel_names) |
1264 | |
1303 | |
1265 | Creates a new OpenCL::Program object from the given built-in kernel names. |
1304 | Creates a new OpenCL::Program object from the given built-in kernel names. |
1266 | |
1305 | |
1267 | L<http://www.khronos.org/registry/cl/sdk/1.2/docs/man/xhtml/clCreateProgramWithBuiltInKernels.html> |
1306 | L<http://www.khronos.org/registry/cl/sdk/1.2/docs/man/xhtml/clCreateProgramWithBuiltInKernels.html> |
|
|
1307 | |
|
|
1308 | =item $program = $ctx->link_program (\@devices, $options, \@programs, $cb->($program) = undef) |
|
|
1309 | |
|
|
1310 | Links all (already compiled) program objects specified in C<@programs> |
|
|
1311 | together and returns a new OpenCL::Program object with the result. |
|
|
1312 | |
|
|
1313 | L<http://www.khronos.org/registry/cl/sdk/1.2/docs/man/xhtml/clLinkProgram.html> |
1268 | |
1314 | |
1269 | =item $packed_value = $ctx->info ($name) |
1315 | =item $packed_value = $ctx->info ($name) |
1270 | |
1316 | |
1271 | See C<< $platform->info >> for details. |
1317 | See C<< $platform->info >> for details. |
1272 | |
1318 | |
… | |
… | |
1766 | C<-cl-mad-enable>, C<-cl-no-signed-zeros>, C<-cl-unsafe-math-optimizations>, |
1812 | C<-cl-mad-enable>, C<-cl-no-signed-zeros>, C<-cl-unsafe-math-optimizations>, |
1767 | C<-cl-finite-math-only>, C<-cl-fast-relaxed-math>, |
1813 | C<-cl-finite-math-only>, C<-cl-fast-relaxed-math>, |
1768 | C<-w>, C<-Werror>, C<-cl-std=CL1.1/CL1.2>, C<-cl-kernel-arg-info>, |
1814 | C<-w>, C<-Werror>, C<-cl-std=CL1.1/CL1.2>, C<-cl-kernel-arg-info>, |
1769 | C<-create-library>, C<-enable-link-options>. |
1815 | C<-create-library>, C<-enable-link-options>. |
1770 | |
1816 | |
|
|
1817 | build_status: OpenCL::BUILD_SUCCESS, OpenCL::BUILD_NONE, |
|
|
1818 | OpenCL::BUILD_ERROR, OpenCL::BUILD_IN_PROGRESS. |
|
|
1819 | |
1771 | L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clBuildProgram.html> |
1820 | L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clBuildProgram.html> |
1772 | |
1821 | |
1773 | =item $program->build_async (\@devices = undef, $options = "", $cb->($program) = undef) |
1822 | =item $program->build_async (\@devices = undef, $options = "", $cb->($program) = undef) |
1774 | |
1823 | |
1775 | Similar to C<< ->build >>, except it starts a thread, and never fails (you |
1824 | Similar to C<< ->build >>, except it starts a thread, and never fails (you |
1776 | need to check the compilation status form the callback, or by polling). |
1825 | need to check the compilation status form the callback, or by polling). |
1777 | |
1826 | |
|
|
1827 | =item $program->compile (\@devices = undef, $options = "", \%headers = undef, $cb->($program) = undef) |
|
|
1828 | |
|
|
1829 | Compiles the given program for the given devices (or all devices if |
|
|
1830 | undef). If C<$headers> is given, it must be a hashref with include name => |
|
|
1831 | OpenCL::Program pairs. |
|
|
1832 | |
|
|
1833 | L<http://www.khronos.org/registry/cl/sdk/1.2/docs/man/xhtml/clCompileProgram.html> |
|
|
1834 | |
1778 | =item $packed_value = $program->build_info ($device, $name) |
1835 | =item $packed_value = $program->build_info ($device, $name) |
1779 | |
1836 | |
1780 | Similar to C<< $platform->info >>, but returns build info for a previous |
1837 | Similar to C<< $platform->info >>, but returns build info for a previous |
1781 | build attempt for the given device. |
1838 | build attempt for the given device. |
1782 | |
1839 | |
… | |
… | |
1798 | =for gengetinfo begin program_build |
1855 | =for gengetinfo begin program_build |
1799 | |
1856 | |
1800 | =item $build_status = $program->build_status ($device) |
1857 | =item $build_status = $program->build_status ($device) |
1801 | |
1858 | |
1802 | Calls C<clGetProgramBuildInfo> with C<OpenCL::PROGRAM_BUILD_STATUS> and returns the result. |
1859 | Calls C<clGetProgramBuildInfo> with C<OpenCL::PROGRAM_BUILD_STATUS> and returns the result. |
1803 | |
|
|
1804 | build_status: OpenCL::BUILD_SUCCESS, OpenCL::BUILD_NONE, |
|
|
1805 | OpenCL::BUILD_ERROR, OpenCL::BUILD_IN_PROGRESS. |
|
|
1806 | |
1860 | |
1807 | =item $string = $program->build_options ($device) |
1861 | =item $string = $program->build_options ($device) |
1808 | |
1862 | |
1809 | Calls C<clGetProgramBuildInfo> with C<OpenCL::PROGRAM_BUILD_OPTIONS> and returns the result. |
1863 | Calls C<clGetProgramBuildInfo> with C<OpenCL::PROGRAM_BUILD_OPTIONS> and returns the result. |
1810 | |
1864 | |
… | |
… | |
1897 | |
1951 | |
1898 | =item $packed_value = $kernel->work_group_info ($device, $name) |
1952 | =item $packed_value = $kernel->work_group_info ($device, $name) |
1899 | |
1953 | |
1900 | See C<< $platform->info >> for details. |
1954 | See C<< $platform->info >> for details. |
1901 | |
1955 | |
1902 | The reason this method is not called C<info> is that there already is an |
|
|
1903 | C<< ->info >> method. |
|
|
1904 | |
|
|
1905 | L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clGetKernelWorkGroupInfo.html> |
1956 | L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clGetKernelWorkGroupInfo.html> |
1906 | |
1957 | |
1907 | =for gengetinfo begin kernel_work_group |
1958 | =for gengetinfo begin kernel_work_group |
1908 | |
1959 | |
1909 | =item $int = $kernel->work_group_size ($device) |
1960 | =item $int = $kernel->work_group_size ($device) |
… | |
… | |
1925 | =item $ulong = $kernel->private_mem_size ($device) |
1976 | =item $ulong = $kernel->private_mem_size ($device) |
1926 | |
1977 | |
1927 | Calls C<clGetKernelWorkGroupInfo> with C<OpenCL::KERNEL_PRIVATE_MEM_SIZE> and returns the result. |
1978 | Calls C<clGetKernelWorkGroupInfo> with C<OpenCL::KERNEL_PRIVATE_MEM_SIZE> and returns the result. |
1928 | |
1979 | |
1929 | =for gengetinfo end kernel_work_group |
1980 | =for gengetinfo end kernel_work_group |
|
|
1981 | |
|
|
1982 | =item $packed_value = $kernel->arg_info ($idx, $name) |
|
|
1983 | |
|
|
1984 | See C<< $platform->info >> for details. |
|
|
1985 | |
|
|
1986 | L<http://www.khronos.org/registry/cl/sdk/1.2/docs/man/xhtml/clGetKernelArgInfo.html> |
|
|
1987 | |
|
|
1988 | =for gengetinfo begin kernel_arg |
|
|
1989 | |
|
|
1990 | =item $kernel_arg_address_qualifier = $kernel->arg_address_qualifier ($idx) |
|
|
1991 | |
|
|
1992 | Calls C<clGetKernelArgInfo> with C<OpenCL::KERNEL_ARG_ADDRESS_QUALIFIER> and returns the result. |
|
|
1993 | |
|
|
1994 | =item $kernel_arg_access_qualifier = $kernel->arg_access_qualifier ($idx) |
|
|
1995 | |
|
|
1996 | Calls C<clGetKernelArgInfo> with C<OpenCL::KERNEL_ARG_ACCESS_QUALIFIER> and returns the result. |
|
|
1997 | |
|
|
1998 | =item $string = $kernel->arg_type_name ($idx) |
|
|
1999 | |
|
|
2000 | Calls C<clGetKernelArgInfo> with C<OpenCL::KERNEL_ARG_TYPE_NAME> and returns the result. |
|
|
2001 | |
|
|
2002 | =item $kernel_arg_type_qualifier = $kernel->arg_type_qualifier ($idx) |
|
|
2003 | |
|
|
2004 | Calls C<clGetKernelArgInfo> with C<OpenCL::KERNEL_ARG_TYPE_QUALIFIER> and returns the result. |
|
|
2005 | |
|
|
2006 | =item $string = $kernel->arg_name ($idx) |
|
|
2007 | |
|
|
2008 | Calls C<clGetKernelArgInfo> with C<OpenCL::KERNEL_ARG_NAME> and returns the result. |
|
|
2009 | |
|
|
2010 | =for gengetinfo end kernel_arg |
1930 | |
2011 | |
1931 | =item $kernel->setf ($format, ...) |
2012 | =item $kernel->setf ($format, ...) |
1932 | |
2013 | |
1933 | Sets the arguments of a kernel. Since OpenCL 1.1 doesn't have a generic |
2014 | Sets the arguments of a kernel. Since OpenCL 1.1 doesn't have a generic |
1934 | way to set arguments (and with OpenCL 1.2 it might be rather slow), you |
2015 | way to set arguments (and with OpenCL 1.2 it might be rather slow), you |