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

Comparing OpenCL/OpenCL.pm (file contents):
Revision 1.71 by root, Fri May 4 14:29:35 2012 UTC vs.
Revision 1.78 by root, Sat May 5 13:07:19 2012 UTC

… …
96initialised at creation time). 96initialised at creation time).
97 97
98Enqueue the kernel execution. 98Enqueue the kernel execution.
99 99
100Enqueue buffer reads for your output buffer to read results. 100Enqueue buffer reads for your output buffer to read results.
101
102=head1 OPENCL 1.1 VS. OPENCL 1.2
103
104This module supports both OpenCL version 1.1 and 1.2, although the OpenCL
1051.2 interface hasn't been tested much for lack of availability of an
106actual implementation.
107
108Every function or method in this manual page that interfaces to a
109particular OpenCL function has a link to the its C manual page.
110
111If the link contains a F<1.1>, then this function is an OpenCL 1.1
112function. Most but not all also exist in OpenCL 1.2, and this module
113tries to emulate the missing ones for you, when told to do so at
114compiletime. You cna check whether a function was removed in OpenCL 1.2 by
115replacing the F<1.1> component in the URL by F<1.2>.
116
117If the link contains a F<1.2>, then this is a OpenCL 1.2-only
118function. Even if the module was compiled with OpenCL 1.2 header files
119and has an 1.2 OpenCL library, calling such a function on a platform that
120doesn't implement 1.2 causes undefined behaviour, usually a crash (But
121this is not guaranteed).
122
123You can find out whether this module was compiled to prefer 1.1
124functionality by ooking at C<OpenCL::PREFER_1_1> - if it is true, then
1251.1 functions generally are implemented using 1.1 OpenCL functions. If it
126is false, then 1.1 functions missing from 1.2 are emulated by calling 1.2
127fucntions.
128
129This is a somewhat sorry state of affairs, but the Khronos group choose to
130make every release of OpenCL source and binary incompatible with previous
131releases.
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
… …
434OpenCL can generate a number of (potentially) asynchronous events, for 465OpenCL can generate a number of (potentially) asynchronous events, for
435example, after compiling a program, to signal a context-related error or, 466example, after compiling a program, to signal a context-related error or,
436perhaps most important, to signal completion of queued jobs (by setting 467perhaps most important, to signal completion of queued jobs (by setting
437callbacks on OpenCL::Event objects). 468callbacks on OpenCL::Event objects).
438 469
470The OpenCL module converts all these callbacks into events - you can
471still register callbacks, but they are not executed when your OpenCL
472implementation calls the actual callback, but only later. Therefore, none
473of the limitations of OpenCL callbacks apply to the perl implementation:
474it is perfectly safe to make blocking operations from event callbacks, and
475enqueued operations don't need to be flushed.
476
439To facilitate this, this module maintains an event queue - each 477To facilitate this, this module maintains an event queue - each
440time an asynchronous event happens, it is queued, and perl will be 478time an asynchronous event happens, it is queued, and perl will be
441interrupted. This is implemented via the L<Async::Interrupt> module. In 479interrupted. This is implemented via the L<Async::Interrupt> module. In
442addition, this module has L<AnyEvent> support, so it can seamlessly 480addition, this module has L<AnyEvent> support, so it can seamlessly
443integrate itself into many event loops. 481integrate itself into many event loops.
444 482
445Since this module is a bit hard to understand, here are some case examples: 483Since 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
449When your program never uses any callbacks, then there will never be any 487When your program never uses any callbacks, then there will never be any
450notifications you need to take care of, and therefore no need to worry 488notifications you need to take care of, and therefore no need to worry
… …
613L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clGetPlatformIDs.html> 651L<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
617Tries to create a context from a default device and platform type - never worked for me. 655Tries to create a context from a default device and platform type - never worked for me.
656Consider using C<< $platform->context_from_type >> instead.
618 657
619type: OpenCL::DEVICE_TYPE_DEFAULT, OpenCL::DEVICE_TYPE_CPU, OpenCL::DEVICE_TYPE_GPU, 658type: OpenCL::DEVICE_TYPE_DEFAULT, OpenCL::DEVICE_TYPE_CPU, OpenCL::DEVICE_TYPE_GPU,
620OpenCL::DEVICE_TYPE_ACCELERATOR, OpenCL::DEVICE_TYPE_CUSTOM, OpenCL::DEVICE_TYPE_ALL. 659OpenCL::DEVICE_TYPE_ACCELERATOR, OpenCL::DEVICE_TYPE_CUSTOM, OpenCL::DEVICE_TYPE_ALL.
621 660
622L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clCreateContextFromType.html> 661L<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
626Create a new OpenCL::Context object using the given device object(s). This 665Create a new OpenCL::Context object using the given device object(s).
627function isn't implemented yet, use C<< $platform->context >> instead. 666Consider using C<< $platform->context >> instead.
628 667
629L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clCreateContext.html> 668L<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
… …
768=over 4 807=over 4
769 808
770=item $packed_value = $device->info ($name) 809=item $packed_value = $device->info ($name)
771 810
772See C<< $platform->info >> for details. 811See C<< $platform->info >> for details.
812
813type: OpenCL::DEVICE_TYPE_DEFAULT, OpenCL::DEVICE_TYPE_CPU,
814OpenCL::DEVICE_TYPE_GPU, OpenCL::DEVICE_TYPE_ACCELERATOR,
815OpenCL::DEVICE_TYPE_CUSTOM, OpenCL::DEVICE_TYPE_ALL.
816
817fp_config: OpenCL::FP_DENORM, OpenCL::FP_INF_NAN, OpenCL::FP_ROUND_TO_NEAREST,
818OpenCL::FP_ROUND_TO_ZERO, OpenCL::FP_ROUND_TO_INF, OpenCL::FP_FMA,
819OpenCL::FP_SOFT_FLOAT, OpenCL::FP_CORRECTLY_ROUNDED_DIVIDE_SQRT.
820
821mem_cache_type: OpenCL::NONE, OpenCL::READ_ONLY_CACHE, OpenCL::READ_WRITE_CACHE.
822
823local_mem_type: OpenCL::LOCAL, OpenCL::GLOBAL.
824
825exec_capabilities: OpenCL::EXEC_KERNEL, OpenCL::EXEC_NATIVE_KERNEL.
826
827command_queue_properties: OpenCL::QUEUE_OUT_OF_ORDER_EXEC_MODE_ENABLE,
828OpenCL::QUEUE_PROFILING_ENABLE.
829
830partition_properties: OpenCL::DEVICE_PARTITION_EQUALLY,
831OpenCL::DEVICE_PARTITION_BY_COUNTS, OpenCL::DEVICE_PARTITION_BY_COUNTS_LIST_END,
832OpenCL::DEVICE_PARTITION_BY_AFFINITY_DOMAIN.
833
834affinity_domain: OpenCL::DEVICE_AFFINITY_DOMAIN_NUMA,
835OpenCL::DEVICE_AFFINITY_DOMAIN_L4_CACHE, OpenCL::DEVICE_AFFINITY_DOMAIN_L3_CACHE,
836OpenCL::DEVICE_AFFINITY_DOMAIN_L2_CACHE, OpenCL::DEVICE_AFFINITY_DOMAIN_L1_CACHE,
837OpenCL::DEVICE_AFFINITY_DOMAIN_NEXT_PARTITIONABLE.
773 838
774L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clGetDeviceInfo.html> 839L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clGetDeviceInfo.html>
775 840
776=item @devices = $device->sub_devices (\@properties) 841=item @devices = $device->sub_devices (\@properties)
777 842
… …
1157OpenCL::UNORM_INT16, OpenCL::UNORM_SHORT_565, OpenCL::UNORM_SHORT_555, 1222OpenCL::UNORM_INT16, OpenCL::UNORM_SHORT_565, OpenCL::UNORM_SHORT_555,
1158OpenCL::UNORM_INT_101010, OpenCL::SIGNED_INT8, OpenCL::SIGNED_INT16, 1223OpenCL::UNORM_INT_101010, OpenCL::SIGNED_INT8, OpenCL::SIGNED_INT16,
1159OpenCL::SIGNED_INT32, OpenCL::UNSIGNED_INT8, OpenCL::UNSIGNED_INT16, 1224OpenCL::SIGNED_INT32, OpenCL::UNSIGNED_INT8, OpenCL::UNSIGNED_INT16,
1160OpenCL::UNSIGNED_INT32, OpenCL::HALF_FLOAT, OpenCL::FLOAT. 1225OpenCL::UNSIGNED_INT32, OpenCL::HALF_FLOAT, OpenCL::FLOAT.
1161 1226
1162
1163type: OpenCL::MEM_OBJECT_BUFFER, OpenCL::MEM_OBJECT_IMAGE2D, 1227type: OpenCL::MEM_OBJECT_BUFFER, OpenCL::MEM_OBJECT_IMAGE2D,
1164OpenCL::MEM_OBJECT_IMAGE3D, OpenCL::MEM_OBJECT_IMAGE2D_ARRAY, 1228OpenCL::MEM_OBJECT_IMAGE3D, OpenCL::MEM_OBJECT_IMAGE2D_ARRAY,
1165OpenCL::MEM_OBJECT_IMAGE1D, OpenCL::MEM_OBJECT_IMAGE1D_ARRAY, 1229OpenCL::MEM_OBJECT_IMAGE1D, OpenCL::MEM_OBJECT_IMAGE1D_ARRAY,
1166OpenCL::MEM_OBJECT_IMAGE1D_BUFFER. 1230OpenCL::MEM_OBJECT_IMAGE1D_BUFFER.
1167 1231
… …
1263=item $program = $ctx->program_with_built_in_kernels (\@devices, $kernel_names) 1327=item $program = $ctx->program_with_built_in_kernels (\@devices, $kernel_names)
1264 1328
1265Creates a new OpenCL::Program object from the given built-in kernel names. 1329Creates a new OpenCL::Program object from the given built-in kernel names.
1266 1330
1267L<http://www.khronos.org/registry/cl/sdk/1.2/docs/man/xhtml/clCreateProgramWithBuiltInKernels.html> 1331L<http://www.khronos.org/registry/cl/sdk/1.2/docs/man/xhtml/clCreateProgramWithBuiltInKernels.html>
1332
1333=item $program = $ctx->link_program (\@devices, $options, \@programs, $cb->($program) = undef)
1334
1335Links all (already compiled) program objects specified in C<@programs>
1336together and returns a new OpenCL::Program object with the result.
1337
1338L<http://www.khronos.org/registry/cl/sdk/1.2/docs/man/xhtml/clLinkProgram.html>
1268 1339
1269=item $packed_value = $ctx->info ($name) 1340=item $packed_value = $ctx->info ($name)
1270 1341
1271See C<< $platform->info >> for details. 1342See C<< $platform->info >> for details.
1272 1343
… …
1766C<-cl-mad-enable>, C<-cl-no-signed-zeros>, C<-cl-unsafe-math-optimizations>, 1837C<-cl-mad-enable>, C<-cl-no-signed-zeros>, C<-cl-unsafe-math-optimizations>,
1767C<-cl-finite-math-only>, C<-cl-fast-relaxed-math>, 1838C<-cl-finite-math-only>, C<-cl-fast-relaxed-math>,
1768C<-w>, C<-Werror>, C<-cl-std=CL1.1/CL1.2>, C<-cl-kernel-arg-info>, 1839C<-w>, C<-Werror>, C<-cl-std=CL1.1/CL1.2>, C<-cl-kernel-arg-info>,
1769C<-create-library>, C<-enable-link-options>. 1840C<-create-library>, C<-enable-link-options>.
1770 1841
1842build_status: OpenCL::BUILD_SUCCESS, OpenCL::BUILD_NONE,
1843OpenCL::BUILD_ERROR, OpenCL::BUILD_IN_PROGRESS.
1844
1771L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clBuildProgram.html> 1845L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clBuildProgram.html>
1772 1846
1773=item $program->build_async (\@devices = undef, $options = "", $cb->($program) = undef) 1847=item $program->build_async (\@devices = undef, $options = "", $cb->($program) = undef)
1774 1848
1775Similar to C<< ->build >>, except it starts a thread, and never fails (you 1849Similar to C<< ->build >>, except it starts a thread, and never fails (you
1776need to check the compilation status form the callback, or by polling). 1850need to check the compilation status form the callback, or by polling).
1777 1851
1852=item $program->compile (\@devices = undef, $options = "", \%headers = undef, $cb->($program) = undef)
1853
1854Compiles the given program for the given devices (or all devices if
1855undef). If C<$headers> is given, it must be a hashref with include name =>
1856OpenCL::Program pairs.
1857
1858L<http://www.khronos.org/registry/cl/sdk/1.2/docs/man/xhtml/clCompileProgram.html>
1859
1778=item $packed_value = $program->build_info ($device, $name) 1860=item $packed_value = $program->build_info ($device, $name)
1779 1861
1780Similar to C<< $platform->info >>, but returns build info for a previous 1862Similar to C<< $platform->info >>, but returns build info for a previous
1781build attempt for the given device. 1863build attempt for the given device.
1782 1864
1865binary_type: OpenCL::PROGRAM_BINARY_TYPE_NONE,
1866OpenCL::PROGRAM_BINARY_TYPE_COMPILED_OBJECT,
1867OpenCL::PROGRAM_BINARY_TYPE_LIBRARY,
1868OpenCL::PROGRAM_BINARY_TYPE_EXECUTABLE.
1869
1783L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clGetBuildInfo.html> 1870L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clGetBuildInfo.html>
1784 1871
1785=item $kernel = $program->kernel ($function_name) 1872=item $kernel = $program->kernel ($function_name)
1786 1873
1787Creates an OpenCL::Kernel object out of the named C<__kernel> function in 1874Creates an OpenCL::Kernel object out of the named C<__kernel> function in
… …
1798=for gengetinfo begin program_build 1885=for gengetinfo begin program_build
1799 1886
1800=item $build_status = $program->build_status ($device) 1887=item $build_status = $program->build_status ($device)
1801 1888
1802Calls C<clGetProgramBuildInfo> with C<OpenCL::PROGRAM_BUILD_STATUS> and returns the result. 1889Calls C<clGetProgramBuildInfo> with C<OpenCL::PROGRAM_BUILD_STATUS> and returns the result.
1803
1804build_status: OpenCL::BUILD_SUCCESS, OpenCL::BUILD_NONE,
1805OpenCL::BUILD_ERROR, OpenCL::BUILD_IN_PROGRESS.
1806 1890
1807=item $string = $program->build_options ($device) 1891=item $string = $program->build_options ($device)
1808 1892
1809Calls C<clGetProgramBuildInfo> with C<OpenCL::PROGRAM_BUILD_OPTIONS> and returns the result. 1893Calls C<clGetProgramBuildInfo> with C<OpenCL::PROGRAM_BUILD_OPTIONS> and returns the result.
1810 1894
… …
1897 1981
1898=item $packed_value = $kernel->work_group_info ($device, $name) 1982=item $packed_value = $kernel->work_group_info ($device, $name)
1899 1983
1900See C<< $platform->info >> for details. 1984See C<< $platform->info >> for details.
1901 1985
1902The reason this method is not called C<info> is that there already is an
1903C<< ->info >> method.
1904
1905L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clGetKernelWorkGroupInfo.html> 1986L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clGetKernelWorkGroupInfo.html>
1906 1987
1907=for gengetinfo begin kernel_work_group 1988=for gengetinfo begin kernel_work_group
1908 1989
1909=item $int = $kernel->work_group_size ($device) 1990=item $int = $kernel->work_group_size ($device)
… …
1925=item $ulong = $kernel->private_mem_size ($device) 2006=item $ulong = $kernel->private_mem_size ($device)
1926 2007
1927Calls C<clGetKernelWorkGroupInfo> with C<OpenCL::KERNEL_PRIVATE_MEM_SIZE> and returns the result. 2008Calls C<clGetKernelWorkGroupInfo> with C<OpenCL::KERNEL_PRIVATE_MEM_SIZE> and returns the result.
1928 2009
1929=for gengetinfo end kernel_work_group 2010=for gengetinfo end kernel_work_group
2011
2012=item $packed_value = $kernel->arg_info ($idx, $name)
2013
2014See C<< $platform->info >> for details.
2015
2016L<http://www.khronos.org/registry/cl/sdk/1.2/docs/man/xhtml/clGetKernelArgInfo.html>
2017
2018=for gengetinfo begin kernel_arg
2019
2020=item $kernel_arg_address_qualifier = $kernel->arg_address_qualifier ($idx)
2021
2022Calls C<clGetKernelArgInfo> with C<OpenCL::KERNEL_ARG_ADDRESS_QUALIFIER> and returns the result.
2023
2024=item $kernel_arg_access_qualifier = $kernel->arg_access_qualifier ($idx)
2025
2026Calls C<clGetKernelArgInfo> with C<OpenCL::KERNEL_ARG_ACCESS_QUALIFIER> and returns the result.
2027
2028=item $string = $kernel->arg_type_name ($idx)
2029
2030Calls C<clGetKernelArgInfo> with C<OpenCL::KERNEL_ARG_TYPE_NAME> and returns the result.
2031
2032=item $kernel_arg_type_qualifier = $kernel->arg_type_qualifier ($idx)
2033
2034Calls C<clGetKernelArgInfo> with C<OpenCL::KERNEL_ARG_TYPE_QUALIFIER> and returns the result.
2035
2036=item $string = $kernel->arg_name ($idx)
2037
2038Calls C<clGetKernelArgInfo> with C<OpenCL::KERNEL_ARG_NAME> and returns the result.
2039
2040=for gengetinfo end kernel_arg
1930 2041
1931=item $kernel->setf ($format, ...) 2042=item $kernel->setf ($format, ...)
1932 2043
1933Sets the arguments of a kernel. Since OpenCL 1.1 doesn't have a generic 2044Sets the arguments of a kernel. Since OpenCL 1.1 doesn't have a generic
1934way to set arguments (and with OpenCL 1.2 it might be rather slow), you 2045way to set arguments (and with OpenCL 1.2 it might be rather slow), you

Diff Legend

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