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

Comparing OpenCL/OpenCL.pm (file contents):
Revision 1.76 by root, Sat May 5 02:45:38 2012 UTC vs.
Revision 1.84 by root, Sat May 5 16:44:02 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
… …
213 $ev->wait; 213 $ev->wait;
214 214
215=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
216set flight effect. 216set flight effect.
217 217
218This is quite a long example to get you going - you can download it from 218This is quite a long example to get you going - you can also download it
219L<http://cvs.schmorp.de/OpenCL/examples/juliaflight>. 219from L<http://cvs.schmorp.de/OpenCL/examples/juliaflight>.
220 220
221 use OpenGL ":all"; 221 use OpenGL ":all";
222 use OpenCL; 222 use OpenCL;
223 223
224 my $S = $ARGV[0] || 256; # window/texture size, smaller is faster 224 my $S = $ARGV[0] || 256; # window/texture size, smaller is faster
… …
388 388
389=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
390context, 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
391by the method. 391by the method.
392 392
393=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
394other status is returned the function will throw an exception, so you 394other status is returned the function will throw an exception, so you
395don't normally have to to any error checking. 395don't normally have to to any error checking.
396 396
397=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 header files used during
404compilation, or otherwise are not available, will have the value C<-1>.
405
406The latest version of this module knows and exports the constants
407listed in L<http://cvs.schmorp.de/OpenCL/constiv.h>.
408
409=head2 OPENCL 1.1 VS. OPENCL 1.2
410
411This module supports both OpenCL version 1.1 and 1.2, although the OpenCL
4121.2 interface hasn't been tested much for lack of availability of an
413actual implementation.
414
415Every function or method in this manual page that interfaces to a
416particular OpenCL function has a link to the its C manual page.
417
418If the link contains a F<1.1>, then this function is an OpenCL 1.1
419function. Most but not all also exist in OpenCL 1.2, and this module
420tries to emulate the missing ones for you, when told to do so at
421compiletime. You can check whether a function was removed in OpenCL 1.2 by
422replacing the F<1.1> component in the URL by F<1.2>.
423
424If the link contains a F<1.2>, then this is a OpenCL 1.2-only
425function. Even if the module was compiled with OpenCL 1.2 header files
426and has an 1.2 OpenCL library, calling such a function on a platform that
427doesn't implement 1.2 causes undefined behaviour, usually a crash (But
428this is not guaranteed).
429
430You can find out whether this module was compiled to prefer 1.1
431functionality by ooking at C<OpenCL::PREFER_1_1> - if it is true, then
4321.1 functions generally are implemented using 1.1 OpenCL functions. If it
433is false, then 1.1 functions missing from 1.2 are emulated by calling 1.2
434fucntions.
435
436This is a somewhat sorry state of affairs, but the Khronos group choose to
437make every release of OpenCL source and binary incompatible with previous
438releases.
398 439
399=head2 PERL AND OPENCL TYPES 440=head2 PERL AND OPENCL TYPES
400 441
401This handy(?) table lists OpenCL types and their perl, PDL and pack/unpack 442This handy(?) table lists OpenCL types and their perl, PDL and pack/unpack
402format equivalents: 443format equivalents:
… …
600The last error returned by a function - it's only valid after an error occured 641The last error returned by a function - it's only valid after an error occured
601and before calling another OpenCL function. 642and before calling another OpenCL function.
602 643
603=item $str = OpenCL::err2str [$errval] 644=item $str = OpenCL::err2str [$errval]
604 645
605Converts an error value into a human readable string. IF no error value is 646Converts an error value into a human readable string. If no error value is
606given, then the last error will be used (as returned by OpenCL::errno). 647given, then the last error will be used (as returned by OpenCL::errno).
648
649The latest version of this module knows the error constants
650listed in L<http://cvs.schmorp.de/OpenCL/errstr.h>.
607 651
608=item $str = OpenCL::enum2str $enum 652=item $str = OpenCL::enum2str $enum
609 653
610Converts most enum values (of parameter names, image format constants, 654Converts most enum values (of parameter names, image format constants,
611object types, addressing and filter modes, command types etc.) into a 655object types, addressing and filter modes, command types etc.) into a
612human readable string. When confronted with some random integer it can be 656human readable string. When confronted with some random integer it can be
613very helpful to pass it through this function to maybe get some readable 657very helpful to pass it through this function to maybe get some readable
614string out of it. 658string out of it.
615 659
660The latest version of this module knows the enumaration constants
661listed in L<http://cvs.schmorp.de/OpenCL/enumstr.h>.
662
616=item @platforms = OpenCL::platforms 663=item @platforms = OpenCL::platforms
617 664
618Returns all available OpenCL::Platform objects. 665Returns all available OpenCL::Platform objects.
619 666
620L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clGetPlatformIDs.html> 667L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clGetPlatformIDs.html>
… …
721L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clCreateContextFromType.html> 768L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clCreateContextFromType.html>
722 769
723=item $ctx = $platform->context ($properties, \@devices, $callback->($err, $pvt) = $print_stderr) 770=item $ctx = $platform->context ($properties, \@devices, $callback->($err, $pvt) = $print_stderr)
724 771
725Create a new OpenCL::Context object using the given device object(s)- a 772Create a new OpenCL::Context object using the given device object(s)- a
726CL_CONTEXT_PLATFORM property is supplied automatically. 773OpenCL::CONTEXT_PLATFORM property is supplied automatically.
727 774
728L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clCreateContext.html> 775L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clCreateContext.html>
729 776
730=item $packed_value = $platform->info ($name) 777=item $packed_value = $platform->info ($name)
731 778
… …
776=over 4 823=over 4
777 824
778=item $packed_value = $device->info ($name) 825=item $packed_value = $device->info ($name)
779 826
780See C<< $platform->info >> for details. 827See C<< $platform->info >> for details.
828
829type: OpenCL::DEVICE_TYPE_DEFAULT, OpenCL::DEVICE_TYPE_CPU,
830OpenCL::DEVICE_TYPE_GPU, OpenCL::DEVICE_TYPE_ACCELERATOR,
831OpenCL::DEVICE_TYPE_CUSTOM, OpenCL::DEVICE_TYPE_ALL.
832
833fp_config: OpenCL::FP_DENORM, OpenCL::FP_INF_NAN, OpenCL::FP_ROUND_TO_NEAREST,
834OpenCL::FP_ROUND_TO_ZERO, OpenCL::FP_ROUND_TO_INF, OpenCL::FP_FMA,
835OpenCL::FP_SOFT_FLOAT, OpenCL::FP_CORRECTLY_ROUNDED_DIVIDE_SQRT.
836
837mem_cache_type: OpenCL::NONE, OpenCL::READ_ONLY_CACHE, OpenCL::READ_WRITE_CACHE.
838
839local_mem_type: OpenCL::LOCAL, OpenCL::GLOBAL.
840
841exec_capabilities: OpenCL::EXEC_KERNEL, OpenCL::EXEC_NATIVE_KERNEL.
842
843command_queue_properties: OpenCL::QUEUE_OUT_OF_ORDER_EXEC_MODE_ENABLE,
844OpenCL::QUEUE_PROFILING_ENABLE.
845
846partition_properties: OpenCL::DEVICE_PARTITION_EQUALLY,
847OpenCL::DEVICE_PARTITION_BY_COUNTS, OpenCL::DEVICE_PARTITION_BY_COUNTS_LIST_END,
848OpenCL::DEVICE_PARTITION_BY_AFFINITY_DOMAIN.
849
850affinity_domain: OpenCL::DEVICE_AFFINITY_DOMAIN_NUMA,
851OpenCL::DEVICE_AFFINITY_DOMAIN_L4_CACHE, OpenCL::DEVICE_AFFINITY_DOMAIN_L3_CACHE,
852OpenCL::DEVICE_AFFINITY_DOMAIN_L2_CACHE, OpenCL::DEVICE_AFFINITY_DOMAIN_L1_CACHE,
853OpenCL::DEVICE_AFFINITY_DOMAIN_NEXT_PARTITIONABLE.
781 854
782L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clGetDeviceInfo.html> 855L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clGetDeviceInfo.html>
783 856
784=item @devices = $device->sub_devices (\@properties) 857=item @devices = $device->sub_devices (\@properties)
785 858
… …
1165OpenCL::UNORM_INT16, OpenCL::UNORM_SHORT_565, OpenCL::UNORM_SHORT_555, 1238OpenCL::UNORM_INT16, OpenCL::UNORM_SHORT_565, OpenCL::UNORM_SHORT_555,
1166OpenCL::UNORM_INT_101010, OpenCL::SIGNED_INT8, OpenCL::SIGNED_INT16, 1239OpenCL::UNORM_INT_101010, OpenCL::SIGNED_INT8, OpenCL::SIGNED_INT16,
1167OpenCL::SIGNED_INT32, OpenCL::UNSIGNED_INT8, OpenCL::UNSIGNED_INT16, 1240OpenCL::SIGNED_INT32, OpenCL::UNSIGNED_INT8, OpenCL::UNSIGNED_INT16,
1168OpenCL::UNSIGNED_INT32, OpenCL::HALF_FLOAT, OpenCL::FLOAT. 1241OpenCL::UNSIGNED_INT32, OpenCL::HALF_FLOAT, OpenCL::FLOAT.
1169 1242
1170
1171type: OpenCL::MEM_OBJECT_BUFFER, OpenCL::MEM_OBJECT_IMAGE2D, 1243type: OpenCL::MEM_OBJECT_BUFFER, OpenCL::MEM_OBJECT_IMAGE2D,
1172OpenCL::MEM_OBJECT_IMAGE3D, OpenCL::MEM_OBJECT_IMAGE2D_ARRAY, 1244OpenCL::MEM_OBJECT_IMAGE3D, OpenCL::MEM_OBJECT_IMAGE2D_ARRAY,
1173OpenCL::MEM_OBJECT_IMAGE1D, OpenCL::MEM_OBJECT_IMAGE1D_ARRAY, 1245OpenCL::MEM_OBJECT_IMAGE1D, OpenCL::MEM_OBJECT_IMAGE1D_ARRAY,
1174OpenCL::MEM_OBJECT_IMAGE1D_BUFFER. 1246OpenCL::MEM_OBJECT_IMAGE1D_BUFFER.
1175 1247
… …
1350 1422
1351=item $ev = $queue->copy_buffer ($src, $dst, $src_offset, $dst_offset, $len, $wait_events...) 1423=item $ev = $queue->copy_buffer ($src, $dst, $src_offset, $dst_offset, $len, $wait_events...)
1352 1424
1353L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clEnqueueCopyBuffer.html> 1425L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clEnqueueCopyBuffer.html>
1354 1426
1355=item $ev = $queue->read_buffer_rect (OpenCL::Memory buf, cl_bool blocking, $buf_x, $buf_y, $buf_z, $host_x, $host_y, $host_z, $width, $height, $depth, $buf_row_pitch, $buf_slice_pitch, $host_row_pitch, $host_slice_pitch, $data, $wait_events...) 1427$eue->read_buffer_rect ($buf, cl_bool blocking, $buf_x, $buf_y, $buf_z, $host_x, $host_y, $host_z, $width, $height, $depth, $buf_row_pitch, $buf_slice_pitch, $host_row_pitch, $host_slice_pitch, $data, $wait_events...)
1356 1428
1357http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clEnqueueReadBufferRect.html 1429http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clEnqueueReadBufferRect.html
1358 1430
1359=item $ev = $queue->write_buffer_rect (OpenCL::Memory buf, cl_bool blocking, $buf_x, $buf_y, $buf_z, $host_x, $host_y, $host_z, $width, $height, $depth, $buf_row_pitch, $buf_slice_pitch, $host_row_pitch, $host_slice_pitch, $data, $wait_events...) 1431=item $ev = $queue->write_buffer_rect ($buf, $blocking, $buf_y, $host_x, $host_z, $height, $buf_row_pitch, $host_row_pitch, $data, $wait_events...)
1360 1432
1361http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clEnqueueWriteBufferRect.html 1433http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clEnqueueWriteBufferRect.html
1362 1434
1363=item $ev = $queue->copy_buffer_to_image ($src_buffer, $dst_image, $src_offset, $dst_x, $dst_y, $dst_z, $width, $height, $depth, $wait_events...) 1435=item $ev = $queue->copy_buffer_to_image ($src_buffer, $dst_image, $src_offset, $dst_x, $dst_y, $dst_z, $width, $height, $depth, $wait_events...)
1364 1436
… …
1548it. You are not necessarily meant to do it this way, this example just 1620it. You are not necessarily meant to do it this way, this example just
1549shows you the accessors to use :) 1621shows you the accessors to use :)
1550 1622
1551 my $mapped = $queue->map_image ($image, 1, OpenCL::MAP_WRITE); 1623 my $mapped = $queue->map_image ($image, 1, OpenCL::MAP_WRITE);
1552 1624
1553 $mapped->set ($_ * $mapped->row_pitch, pack "C", 5) 1625 $mapped->write ($_ * $mapped->row_pitch, pack "C", 5)
1554 for 0..$image->height; 1626 for 0 .. $mapped->height - 1;
1555 1627
1556 $mapped->unmap;. 1628 $mapped->unmap;.
1557 $mapped->wait; # only needed for out of order queues normally 1629 $mapped->wait; # only needed for out of order queues normally
1558 1630
1559=item $ev = $queue->unmap ($mapped, $wait_events...) 1631=item $ev = $queue->unmap ($mapped, $wait_events...)
… …
1579 1651
1580See C<< $platform->info >> for details. 1652See C<< $platform->info >> for details.
1581 1653
1582L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clGetMemObjectInfo.html> 1654L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clGetMemObjectInfo.html>
1583 1655
1656=item $memory->destructor_callback ($cb->())
1657
1658Sets a callback that will be invoked after the memory object is destructed.
1659
1660L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clSetMemObjectDestructorCallback.html>
1661
1584=for gengetinfo begin mem 1662=for gengetinfo begin mem
1585 1663
1586=item $mem_object_type = $mem->type 1664=item $mem_object_type = $mem->type
1587 1665
1588Calls C<clGetMemObjectInfo> with C<OpenCL::MEM_TYPE> and returns the result. 1666Calls C<clGetMemObjectInfo> with C<OpenCL::MEM_TYPE> and returns the result.
… …
1645=over 4 1723=over 4
1646 1724
1647=item $subbuf = $buf_obj->sub_buffer_region ($flags, $origin, $size) 1725=item $subbuf = $buf_obj->sub_buffer_region ($flags, $origin, $size)
1648 1726
1649Creates an OpenCL::Buffer objects from this buffer and returns it. The 1727Creates an OpenCL::Buffer objects from this buffer and returns it. The
1650C<buffer_create_type> is assumed to be C<CL_BUFFER_CREATE_TYPE_REGION>. 1728C<buffer_create_type> is assumed to be C<OpenCL::BUFFER_CREATE_TYPE_REGION>.
1651 1729
1652L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clCreateSubBuffer.html> 1730L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clCreateSubBuffer.html>
1653 1731
1654=back 1732=back
1655 1733
… …
1671L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clGetImageInfo.html> 1749L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clGetImageInfo.html>
1672 1750
1673=item ($channel_order, $channel_data_type) = $image->format 1751=item ($channel_order, $channel_data_type) = $image->format
1674 1752
1675Returns the channel order and type used to create the image by calling 1753Returns the channel order and type used to create the image by calling
1676C<clGetImageInfo> with C<CL_IMAGE_FORMAT>. 1754C<clGetImageInfo> with C<OpenCL::IMAGE_FORMAT>.
1677 1755
1678=for gengetinfo begin image 1756=for gengetinfo begin image
1679 1757
1680=item $int = $image->element_size 1758=item $int = $image->element_size
1681 1759
… …
1804=item $packed_value = $program->build_info ($device, $name) 1882=item $packed_value = $program->build_info ($device, $name)
1805 1883
1806Similar to C<< $platform->info >>, but returns build info for a previous 1884Similar to C<< $platform->info >>, but returns build info for a previous
1807build attempt for the given device. 1885build attempt for the given device.
1808 1886
1887binary_type: OpenCL::PROGRAM_BINARY_TYPE_NONE,
1888OpenCL::PROGRAM_BINARY_TYPE_COMPILED_OBJECT,
1889OpenCL::PROGRAM_BINARY_TYPE_LIBRARY,
1890OpenCL::PROGRAM_BINARY_TYPE_EXECUTABLE.
1891
1809L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clGetBuildInfo.html> 1892L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clGetBuildInfo.html>
1810 1893
1811=item $kernel = $program->kernel ($function_name) 1894=item $kernel = $program->kernel ($function_name)
1812 1895
1813Creates an OpenCL::Kernel object out of the named C<__kernel> function in 1896Creates an OpenCL::Kernel object out of the named C<__kernel> function in
… …
1832Calls C<clGetProgramBuildInfo> with C<OpenCL::PROGRAM_BUILD_OPTIONS> and returns the result. 1915Calls C<clGetProgramBuildInfo> with C<OpenCL::PROGRAM_BUILD_OPTIONS> and returns the result.
1833 1916
1834=item $string = $program->build_log ($device) 1917=item $string = $program->build_log ($device)
1835 1918
1836Calls C<clGetProgramBuildInfo> with C<OpenCL::PROGRAM_BUILD_LOG> and returns the result. 1919Calls C<clGetProgramBuildInfo> with C<OpenCL::PROGRAM_BUILD_LOG> and returns the result.
1920
1921=item $binary_type = $program->binary_type ($device)
1922
1923Calls C<clGetProgramBuildInfo> with C<OpenCL::PROGRAM_BINARY_TYPE> and returns the result.
1837 1924
1838=for gengetinfo end program_build 1925=for gengetinfo end program_build
1839 1926
1840=item $packed_value = $program->info ($name) 1927=item $packed_value = $program->info ($name)
1841 1928
… …
2256 2343
2257This is a subclass of OpenCL::Mapped, representing mapped images. 2344This is a subclass of OpenCL::Mapped, representing mapped images.
2258 2345
2259=over 4 2346=over 4
2260 2347
2348=item $pixels = $mapped->width
2349
2350=item $pixels = $mapped->height
2351
2352=item $pixels = $mapped->depth
2353
2354Return the width/height/depth of the mapped image region, in pixels.
2355
2261=item $bytes = $mapped->row_pitch 2356=item $bytes = $mapped->row_pitch
2262 2357
2263=item $bytes = $mapped->slice_pitch 2358=item $bytes = $mapped->slice_pitch
2264 2359
2265Return the row or slice pitch of the image that has been mapped. 2360Return the row or slice pitch of the image that has been mapped.
2266 2361
2362=item $bytes = $mapped->element_size
2363
2364Return the size of a single pixel.
2365
2366=item $data = $mapped->get_row ($count, $x=0, $y=0, $z=0)
2367
2368Return C<$count> pixels from the given coordinates. The pixel data must
2369be completely contained within a single row.
2370
2371If C<$count> is C<undef>, then all the remaining pixels in that row are
2372returned.
2373
2374=item $mapped->set_row ($data, $x=0, $y=0, $z=0)
2375
2376Write the given pixel data at the given coordinate. The pixel data must
2377be completely contained within a single row.
2378
2267=back 2379=back
2268
2269 2380
2270=cut 2381=cut
2271 2382
22721; 23831;
2273 2384

Diff Legend

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