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

Comparing OpenCL/OpenCL.pm (file contents):
Revision 1.79 by root, Sat May 5 13:30:07 2012 UTC vs.
Revision 1.85 by root, Sat May 5 16:52:17 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
… …
244 $ev->wait; 213 $ev->wait;
245 214
246=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
247set flight effect. 216set flight effect.
248 217
249This 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
250L<http://cvs.schmorp.de/OpenCL/examples/juliaflight>. 219from L<http://cvs.schmorp.de/OpenCL/examples/juliaflight>.
251 220
252 use OpenGL ":all"; 221 use OpenGL ":all";
253 use OpenCL; 222 use OpenCL;
254 223
255 my $S = $ARGV[0] || 256; # window/texture size, smaller is faster 224 my $S = $ARGV[0] || 256; # window/texture size, smaller is faster
… …
424=item * This module expects all functions to return C<OpenCL::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 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.
429 439
430=head2 PERL AND OPENCL TYPES 440=head2 PERL AND OPENCL TYPES
431 441
432This 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
433format equivalents: 443format equivalents:
… …
585use Async::Interrupt (); 595use Async::Interrupt ();
586 596
587our $POLL_FUNC; # set by XS 597our $POLL_FUNC; # set by XS
588 598
589BEGIN { 599BEGIN {
590 our $VERSION = '0.99'; 600 our $VERSION = '1.0';
591 601
592 require XSLoader; 602 require XSLoader;
593 XSLoader::load (__PACKAGE__, $VERSION); 603 XSLoader::load (__PACKAGE__, $VERSION);
594 604
595 @OpenCL::Platform::ISA = 605 @OpenCL::Platform::ISA =
… …
631The 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
632and before calling another OpenCL function. 642and before calling another OpenCL function.
633 643
634=item $str = OpenCL::err2str [$errval] 644=item $str = OpenCL::err2str [$errval]
635 645
636Converts 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
637given, 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>.
638 651
639=item $str = OpenCL::enum2str $enum 652=item $str = OpenCL::enum2str $enum
640 653
641Converts most enum values (of parameter names, image format constants, 654Converts most enum values (of parameter names, image format constants,
642object types, addressing and filter modes, command types etc.) into a 655object types, addressing and filter modes, command types etc.) into a
643human readable string. When confronted with some random integer it can be 656human readable string. When confronted with some random integer it can be
644very 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
645string out of it. 658string out of it.
659
660The latest version of this module knows the enumaration constants
661listed in L<http://cvs.schmorp.de/OpenCL/enumstr.h>.
646 662
647=item @platforms = OpenCL::platforms 663=item @platforms = OpenCL::platforms
648 664
649Returns all available OpenCL::Platform objects. 665Returns all available OpenCL::Platform objects.
650 666
… …
1406 1422
1407=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...)
1408 1424
1409L<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>
1410 1426
1411=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...)
1412 1428
1413http://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
1414 1430
1415=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...)
1416 1432
1417http://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
1418 1434
1419=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...)
1420 1436
… …
1604it. 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
1605shows you the accessors to use :) 1621shows you the accessors to use :)
1606 1622
1607 my $mapped = $queue->map_image ($image, 1, OpenCL::MAP_WRITE); 1623 my $mapped = $queue->map_image ($image, 1, OpenCL::MAP_WRITE);
1608 1624
1609 $mapped->set ($_ * $mapped->row_pitch, pack "C", 5) 1625 $mapped->write ($_ * $mapped->row_pitch, pack "C", 5)
1610 for 0..$image->height; 1626 for 0 .. $mapped->height - 1;
1611 1627
1612 $mapped->unmap;. 1628 $mapped->unmap;.
1613 $mapped->wait; # only needed for out of order queues normally 1629 $mapped->wait; # only needed for out of order queues normally
1614 1630
1615=item $ev = $queue->unmap ($mapped, $wait_events...) 1631=item $ev = $queue->unmap ($mapped, $wait_events...)
… …
1634=item $packed_value = $memory->info ($name) 1650=item $packed_value = $memory->info ($name)
1635 1651
1636See C<< $platform->info >> for details. 1652See C<< $platform->info >> for details.
1637 1653
1638L<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>
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>
1639 1661
1640=for gengetinfo begin mem 1662=for gengetinfo begin mem
1641 1663
1642=item $mem_object_type = $mem->type 1664=item $mem_object_type = $mem->type
1643 1665
… …
2321 2343
2322This is a subclass of OpenCL::Mapped, representing mapped images. 2344This is a subclass of OpenCL::Mapped, representing mapped images.
2323 2345
2324=over 4 2346=over 4
2325 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
2326=item $bytes = $mapped->row_pitch 2356=item $bytes = $mapped->row_pitch
2327 2357
2328=item $bytes = $mapped->slice_pitch 2358=item $bytes = $mapped->slice_pitch
2329 2359
2330Return 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.
2331 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
2332=back 2379=back
2333
2334 2380
2335=cut 2381=cut
2336 2382
23371; 23831;
2338 2384

Diff Legend

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