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

Comparing OpenCL/OpenCL.pm (file contents):
Revision 1.77 by root, Sat May 5 12:54:03 2012 UTC vs.
Revision 1.80 by root, Sat May 5 13:55:59 2012 UTC

… …
28specific device ("compiling and linking"), also binary programs. For each 28specific device ("compiling and linking"), also binary programs. For each
29kernel function in a program you can then create an OpenCL::Kernel object 29kernel function in a program you can then create an OpenCL::Kernel object
30which represents basically a function call with argument values. 30which represents basically a function call with argument values.
31 31
32OpenCL::Memory objects of various flavours: OpenCL::Buffer objects (flat 32OpenCL::Memory objects of various flavours: OpenCL::Buffer objects (flat
33memory areas, think arrays or structs) and OpenCL::Image objects (think 2d 33memory areas, think arrays or structs) and OpenCL::Image objects (think 2D
34or 3d array) for bulk data and input and output for kernels. 34or 3D array) for bulk data and input and output for kernels.
35 35
36OpenCL::Sampler objects, which are kind of like texture filter modes in 36OpenCL::Sampler objects, which are kind of like texture filter modes in
37OpenGL. 37OpenGL.
38 38
39OpenCL::Queue objects - command queues, which allow you to submit memory 39OpenCL::Queue objects - command queues, which allow you to submit memory
… …
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.
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
… …
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
421context, no event is created. In all other contexts an event is returned 390context, no event is created. In all other contexts an event is returned
422by the method. 391by 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
425other status is returned the function will throw an exception, so you 394other status is returned the function will throw an exception, so you
426don't normally have to to any error checking. 395don't normally have to to any error checking.
427 396
428=back 397=back
398
399=head2 CONSTANTS
400
401All C<CL_xxx> constants that this module supports are always available
402in the C<OpenCL> namespace as C<OpenCL::xxx> (i.e. without the C<CL_>
403prefix). Constants which are not defined in the heaer files used during
404compilation, or otherwise are not available, will have the value C<-1>.
405
406=head2 OPENCL 1.1 VS. OPENCL 1.2
407
408This module supports both OpenCL version 1.1 and 1.2, although the OpenCL
4091.2 interface hasn't been tested much for lack of availability of an
410actual implementation.
411
412Every function or method in this manual page that interfaces to a
413particular OpenCL function has a link to the its C manual page.
414
415If the link contains a F<1.1>, then this function is an OpenCL 1.1
416function. Most but not all also exist in OpenCL 1.2, and this module
417tries to emulate the missing ones for you, when told to do so at
418compiletime. You cna check whether a function was removed in OpenCL 1.2 by
419replacing the F<1.1> component in the URL by F<1.2>.
420
421If the link contains a F<1.2>, then this is a OpenCL 1.2-only
422function. Even if the module was compiled with OpenCL 1.2 header files
423and has an 1.2 OpenCL library, calling such a function on a platform that
424doesn't implement 1.2 causes undefined behaviour, usually a crash (But
425this is not guaranteed).
426
427You can find out whether this module was compiled to prefer 1.1
428functionality by ooking at C<OpenCL::PREFER_1_1> - if it is true, then
4291.1 functions generally are implemented using 1.1 OpenCL functions. If it
430is false, then 1.1 functions missing from 1.2 are emulated by calling 1.2
431fucntions.
432
433This is a somewhat sorry state of affairs, but the Khronos group choose to
434make every release of OpenCL source and binary incompatible with previous
435releases.
429 436
430=head2 PERL AND OPENCL TYPES 437=head2 PERL AND OPENCL TYPES
431 438
432This handy(?) table lists OpenCL types and their perl, PDL and pack/unpack 439This handy(?) table lists OpenCL types and their perl, PDL and pack/unpack
433format equivalents: 440format equivalents:
… …
752L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clCreateContextFromType.html> 759L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clCreateContextFromType.html>
753 760
754=item $ctx = $platform->context ($properties, \@devices, $callback->($err, $pvt) = $print_stderr) 761=item $ctx = $platform->context ($properties, \@devices, $callback->($err, $pvt) = $print_stderr)
755 762
756Create a new OpenCL::Context object using the given device object(s)- a 763Create a new OpenCL::Context object using the given device object(s)- a
757CL_CONTEXT_PLATFORM property is supplied automatically. 764OpenCL::CONTEXT_PLATFORM property is supplied automatically.
758 765
759L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clCreateContext.html> 766L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clCreateContext.html>
760 767
761=item $packed_value = $platform->info ($name) 768=item $packed_value = $platform->info ($name)
762 769
… …
807=over 4 814=over 4
808 815
809=item $packed_value = $device->info ($name) 816=item $packed_value = $device->info ($name)
810 817
811See C<< $platform->info >> for details. 818See C<< $platform->info >> for details.
819
820type: OpenCL::DEVICE_TYPE_DEFAULT, OpenCL::DEVICE_TYPE_CPU,
821OpenCL::DEVICE_TYPE_GPU, OpenCL::DEVICE_TYPE_ACCELERATOR,
822OpenCL::DEVICE_TYPE_CUSTOM, OpenCL::DEVICE_TYPE_ALL.
823
824fp_config: OpenCL::FP_DENORM, OpenCL::FP_INF_NAN, OpenCL::FP_ROUND_TO_NEAREST,
825OpenCL::FP_ROUND_TO_ZERO, OpenCL::FP_ROUND_TO_INF, OpenCL::FP_FMA,
826OpenCL::FP_SOFT_FLOAT, OpenCL::FP_CORRECTLY_ROUNDED_DIVIDE_SQRT.
827
828mem_cache_type: OpenCL::NONE, OpenCL::READ_ONLY_CACHE, OpenCL::READ_WRITE_CACHE.
829
830local_mem_type: OpenCL::LOCAL, OpenCL::GLOBAL.
831
832exec_capabilities: OpenCL::EXEC_KERNEL, OpenCL::EXEC_NATIVE_KERNEL.
833
834command_queue_properties: OpenCL::QUEUE_OUT_OF_ORDER_EXEC_MODE_ENABLE,
835OpenCL::QUEUE_PROFILING_ENABLE.
836
837partition_properties: OpenCL::DEVICE_PARTITION_EQUALLY,
838OpenCL::DEVICE_PARTITION_BY_COUNTS, OpenCL::DEVICE_PARTITION_BY_COUNTS_LIST_END,
839OpenCL::DEVICE_PARTITION_BY_AFFINITY_DOMAIN.
840
841affinity_domain: OpenCL::DEVICE_AFFINITY_DOMAIN_NUMA,
842OpenCL::DEVICE_AFFINITY_DOMAIN_L4_CACHE, OpenCL::DEVICE_AFFINITY_DOMAIN_L3_CACHE,
843OpenCL::DEVICE_AFFINITY_DOMAIN_L2_CACHE, OpenCL::DEVICE_AFFINITY_DOMAIN_L1_CACHE,
844OpenCL::DEVICE_AFFINITY_DOMAIN_NEXT_PARTITIONABLE.
812 845
813L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clGetDeviceInfo.html> 846L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clGetDeviceInfo.html>
814 847
815=item @devices = $device->sub_devices (\@properties) 848=item @devices = $device->sub_devices (\@properties)
816 849
… …
1196OpenCL::UNORM_INT16, OpenCL::UNORM_SHORT_565, OpenCL::UNORM_SHORT_555, 1229OpenCL::UNORM_INT16, OpenCL::UNORM_SHORT_565, OpenCL::UNORM_SHORT_555,
1197OpenCL::UNORM_INT_101010, OpenCL::SIGNED_INT8, OpenCL::SIGNED_INT16, 1230OpenCL::UNORM_INT_101010, OpenCL::SIGNED_INT8, OpenCL::SIGNED_INT16,
1198OpenCL::SIGNED_INT32, OpenCL::UNSIGNED_INT8, OpenCL::UNSIGNED_INT16, 1231OpenCL::SIGNED_INT32, OpenCL::UNSIGNED_INT8, OpenCL::UNSIGNED_INT16,
1199OpenCL::UNSIGNED_INT32, OpenCL::HALF_FLOAT, OpenCL::FLOAT. 1232OpenCL::UNSIGNED_INT32, OpenCL::HALF_FLOAT, OpenCL::FLOAT.
1200 1233
1201
1202type: OpenCL::MEM_OBJECT_BUFFER, OpenCL::MEM_OBJECT_IMAGE2D, 1234type: OpenCL::MEM_OBJECT_BUFFER, OpenCL::MEM_OBJECT_IMAGE2D,
1203OpenCL::MEM_OBJECT_IMAGE3D, OpenCL::MEM_OBJECT_IMAGE2D_ARRAY, 1235OpenCL::MEM_OBJECT_IMAGE3D, OpenCL::MEM_OBJECT_IMAGE2D_ARRAY,
1204OpenCL::MEM_OBJECT_IMAGE1D, OpenCL::MEM_OBJECT_IMAGE1D_ARRAY, 1236OpenCL::MEM_OBJECT_IMAGE1D, OpenCL::MEM_OBJECT_IMAGE1D_ARRAY,
1205OpenCL::MEM_OBJECT_IMAGE1D_BUFFER. 1237OpenCL::MEM_OBJECT_IMAGE1D_BUFFER.
1206 1238
… …
1676=over 4 1708=over 4
1677 1709
1678=item $subbuf = $buf_obj->sub_buffer_region ($flags, $origin, $size) 1710=item $subbuf = $buf_obj->sub_buffer_region ($flags, $origin, $size)
1679 1711
1680Creates an OpenCL::Buffer objects from this buffer and returns it. The 1712Creates an OpenCL::Buffer objects from this buffer and returns it. The
1681C<buffer_create_type> is assumed to be C<CL_BUFFER_CREATE_TYPE_REGION>. 1713C<buffer_create_type> is assumed to be C<OpenCL::BUFFER_CREATE_TYPE_REGION>.
1682 1714
1683L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clCreateSubBuffer.html> 1715L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clCreateSubBuffer.html>
1684 1716
1685=back 1717=back
1686 1718
… …
1702L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clGetImageInfo.html> 1734L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clGetImageInfo.html>
1703 1735
1704=item ($channel_order, $channel_data_type) = $image->format 1736=item ($channel_order, $channel_data_type) = $image->format
1705 1737
1706Returns the channel order and type used to create the image by calling 1738Returns the channel order and type used to create the image by calling
1707C<clGetImageInfo> with C<CL_IMAGE_FORMAT>. 1739C<clGetImageInfo> with C<OpenCL::IMAGE_FORMAT>.
1708 1740
1709=for gengetinfo begin image 1741=for gengetinfo begin image
1710 1742
1711=item $int = $image->element_size 1743=item $int = $image->element_size
1712 1744
… …
1835=item $packed_value = $program->build_info ($device, $name) 1867=item $packed_value = $program->build_info ($device, $name)
1836 1868
1837Similar to C<< $platform->info >>, but returns build info for a previous 1869Similar to C<< $platform->info >>, but returns build info for a previous
1838build attempt for the given device. 1870build attempt for the given device.
1839 1871
1872binary_type: OpenCL::PROGRAM_BINARY_TYPE_NONE,
1873OpenCL::PROGRAM_BINARY_TYPE_COMPILED_OBJECT,
1874OpenCL::PROGRAM_BINARY_TYPE_LIBRARY,
1875OpenCL::PROGRAM_BINARY_TYPE_EXECUTABLE.
1876
1840L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clGetBuildInfo.html> 1877L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clGetBuildInfo.html>
1841 1878
1842=item $kernel = $program->kernel ($function_name) 1879=item $kernel = $program->kernel ($function_name)
1843 1880
1844Creates an OpenCL::Kernel object out of the named C<__kernel> function in 1881Creates an OpenCL::Kernel object out of the named C<__kernel> function in
… …
1863Calls C<clGetProgramBuildInfo> with C<OpenCL::PROGRAM_BUILD_OPTIONS> and returns the result. 1900Calls C<clGetProgramBuildInfo> with C<OpenCL::PROGRAM_BUILD_OPTIONS> and returns the result.
1864 1901
1865=item $string = $program->build_log ($device) 1902=item $string = $program->build_log ($device)
1866 1903
1867Calls C<clGetProgramBuildInfo> with C<OpenCL::PROGRAM_BUILD_LOG> and returns the result. 1904Calls C<clGetProgramBuildInfo> with C<OpenCL::PROGRAM_BUILD_LOG> and returns the result.
1905
1906=item $binary_type = $program->binary_type ($device)
1907
1908Calls C<clGetProgramBuildInfo> with C<OpenCL::PROGRAM_BINARY_TYPE> and returns the result.
1868 1909
1869=for gengetinfo end program_build 1910=for gengetinfo end program_build
1870 1911
1871=item $packed_value = $program->info ($name) 1912=item $packed_value = $program->info ($name)
1872 1913

Diff Legend

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