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

Comparing OpenCL/OpenCL.pm (file contents):
Revision 1.72 by root, Fri May 4 14:49:42 2012 UTC vs.
Revision 1.79 by root, Sat May 5 13:30:07 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
388 419
389=item * When enqueuing commands, if the enqueue method is called in void 420=item * When enqueuing commands, if the enqueue method is called in void
390context, no event is created. In all other contexts an event is returned 421context, no event is created. In all other contexts an event is returned
391by the method. 422by the method.
392 423
393=item * This module expects all functions to return C<CL_SUCCESS>. If any 424=item * This module expects all functions to return C<OpenCL::SUCCESS>. If any
394other status is returned the function will throw an exception, so you 425other status is returned the function will throw an exception, so you
395don't normally have to to any error checking. 426don't normally have to to any error checking.
396 427
397=back 428=back
398 429
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
713L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clCreateContextFromType.html> 752L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clCreateContextFromType.html>
714 753
715=item $ctx = $platform->context ($properties, \@devices, $callback->($err, $pvt) = $print_stderr) 754=item $ctx = $platform->context ($properties, \@devices, $callback->($err, $pvt) = $print_stderr)
716 755
717Create a new OpenCL::Context object using the given device object(s)- a 756Create a new OpenCL::Context object using the given device object(s)- a
718CL_CONTEXT_PLATFORM property is supplied automatically. 757OpenCL::CONTEXT_PLATFORM property is supplied automatically.
719 758
720L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clCreateContext.html> 759L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clCreateContext.html>
721 760
722=item $packed_value = $platform->info ($name) 761=item $packed_value = $platform->info ($name)
723 762
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
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>
1268 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>
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
1273L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clGetContextInfo.html> 1344L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clGetContextInfo.html>
1630=over 4 1701=over 4
1631 1702
1632=item $subbuf = $buf_obj->sub_buffer_region ($flags, $origin, $size) 1703=item $subbuf = $buf_obj->sub_buffer_region ($flags, $origin, $size)
1633 1704
1634Creates an OpenCL::Buffer objects from this buffer and returns it. The 1705Creates an OpenCL::Buffer objects from this buffer and returns it. The
1635C<buffer_create_type> is assumed to be C<CL_BUFFER_CREATE_TYPE_REGION>. 1706C<buffer_create_type> is assumed to be C<OpenCL::BUFFER_CREATE_TYPE_REGION>.
1636 1707
1637L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clCreateSubBuffer.html> 1708L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clCreateSubBuffer.html>
1638 1709
1639=back 1710=back
1640 1711
1656L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clGetImageInfo.html> 1727L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clGetImageInfo.html>
1657 1728
1658=item ($channel_order, $channel_data_type) = $image->format 1729=item ($channel_order, $channel_data_type) = $image->format
1659 1730
1660Returns the channel order and type used to create the image by calling 1731Returns the channel order and type used to create the image by calling
1661C<clGetImageInfo> with C<CL_IMAGE_FORMAT>. 1732C<clGetImageInfo> with C<OpenCL::IMAGE_FORMAT>.
1662 1733
1663=for gengetinfo begin image 1734=for gengetinfo begin image
1664 1735
1665=item $int = $image->element_size 1736=item $int = $image->element_size
1666 1737
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
1778build_status: OpenCL::BUILD_SUCCESS, OpenCL::BUILD_NONE, 1852=item $program->compile (\@devices = undef, $options = "", \%headers = undef, $cb->($program) = undef)
1779OpenCL::BUILD_ERROR, OpenCL::BUILD_IN_PROGRESS. 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>
1780 1859
1781=item $packed_value = $program->build_info ($device, $name) 1860=item $packed_value = $program->build_info ($device, $name)
1782 1861
1783Similar to C<< $platform->info >>, but returns build info for a previous 1862Similar to C<< $platform->info >>, but returns build info for a previous
1784build attempt for the given device. 1863build attempt for the given device.
1785 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
1786L<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>
1787 1871
1788=item $kernel = $program->kernel ($function_name) 1872=item $kernel = $program->kernel ($function_name)
1789 1873
1790Creates 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
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
1811=item $string = $program->build_log ($device) 1895=item $string = $program->build_log ($device)
1812 1896
1813Calls C<clGetProgramBuildInfo> with C<OpenCL::PROGRAM_BUILD_LOG> and returns the result. 1897Calls C<clGetProgramBuildInfo> with C<OpenCL::PROGRAM_BUILD_LOG> and returns the result.
1898
1899=item $binary_type = $program->binary_type ($device)
1900
1901Calls C<clGetProgramBuildInfo> with C<OpenCL::PROGRAM_BINARY_TYPE> and returns the result.
1814 1902
1815=for gengetinfo end program_build 1903=for gengetinfo end program_build
1816 1904
1817=item $packed_value = $program->info ($name) 1905=item $packed_value = $program->info ($name)
1818 1906
1897 1985
1898=item $packed_value = $kernel->work_group_info ($device, $name) 1986=item $packed_value = $kernel->work_group_info ($device, $name)
1899 1987
1900See C<< $platform->info >> for details. 1988See C<< $platform->info >> for details.
1901 1989
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> 1990L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clGetKernelWorkGroupInfo.html>
1906 1991
1907=for gengetinfo begin kernel_work_group 1992=for gengetinfo begin kernel_work_group
1908 1993
1909=item $int = $kernel->work_group_size ($device) 1994=item $int = $kernel->work_group_size ($device)
1926 2011
1927Calls C<clGetKernelWorkGroupInfo> with C<OpenCL::KERNEL_PRIVATE_MEM_SIZE> and returns the result. 2012Calls C<clGetKernelWorkGroupInfo> with C<OpenCL::KERNEL_PRIVATE_MEM_SIZE> and returns the result.
1928 2013
1929=for gengetinfo end kernel_work_group 2014=for gengetinfo end kernel_work_group
1930 2015
2016=item $packed_value = $kernel->arg_info ($idx, $name)
2017
2018See C<< $platform->info >> for details.
2019
2020L<http://www.khronos.org/registry/cl/sdk/1.2/docs/man/xhtml/clGetKernelArgInfo.html>
2021
1931=for gengetinfo begin kernel_arg_info 2022=for gengetinfo begin kernel_arg
1932 2023
2024=item $kernel_arg_address_qualifier = $kernel->arg_address_qualifier ($idx)
2025
2026Calls C<clGetKernelArgInfo> with C<OpenCL::KERNEL_ARG_ADDRESS_QUALIFIER> and returns the result.
2027
2028=item $kernel_arg_access_qualifier = $kernel->arg_access_qualifier ($idx)
2029
2030Calls C<clGetKernelArgInfo> with C<OpenCL::KERNEL_ARG_ACCESS_QUALIFIER> and returns the result.
2031
2032=item $string = $kernel->arg_type_name ($idx)
2033
2034Calls C<clGetKernelArgInfo> with C<OpenCL::KERNEL_ARG_TYPE_NAME> and returns the result.
2035
2036=item $kernel_arg_type_qualifier = $kernel->arg_type_qualifier ($idx)
2037
2038Calls C<clGetKernelArgInfo> with C<OpenCL::KERNEL_ARG_TYPE_QUALIFIER> and returns the result.
2039
2040=item $string = $kernel->arg_name ($idx)
2041
2042Calls C<clGetKernelArgInfo> with C<OpenCL::KERNEL_ARG_NAME> and returns the result.
2043
1933=for gengetinfo end kernel_arg_info 2044=for gengetinfo end kernel_arg
1934 2045
1935=item $kernel->setf ($format, ...) 2046=item $kernel->setf ($format, ...)
1936 2047
1937Sets the arguments of a kernel. Since OpenCL 1.1 doesn't have a generic 2048Sets the arguments of a kernel. Since OpenCL 1.1 doesn't have a generic
1938way to set arguments (and with OpenCL 1.2 it might be rather slow), you 2049way to set arguments (and with OpenCL 1.2 it might be rather slow), you

Diff Legend

Removed lines
+ Added lines
< Changed lines
> Changed lines