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

Comparing OpenCL/OpenCL.pm (file contents):
Revision 1.8 by root, Wed Nov 16 06:22:20 2011 UTC vs.
Revision 1.9 by root, Thu Nov 17 01:36:52 2011 UTC

… …
8 8
9=head1 DESCRIPTION 9=head1 DESCRIPTION
10 10
11This is an early release which might be useful, but hasn't seen much testing. 11This is an early release which might be useful, but hasn't seen much testing.
12 12
13=head2 OpenCL FROM 10000 FEET HEIGHT
14
15Here is a high level overview of OpenCL:
16
17First you need to find one or more OpenCL::Platforms (kind of like
18vendors) - usually there is only one.
19
20Each platform gives you access to a number of OpenCL::Device objects, e.g.
21your graphics card.
22
23From a platform and some devices, you create an OpenCL::Context, which is
24a very central object in OpenCL: Once you have a context you can create
25most other objects:
26
27OpenCL::Program objects, which store source code and, after building
28("compiling and linking"), also binary programs. For each kernel function
29in a program you can then create an OpenCL::Kernel object which represents
30basically a function call with argument values.
31
32OpenCL::Memory objects of various flavours: OpenCL::Buffers objects (flat
33memory areas, think array) and OpenCL::Image objects (think 2d or 3d
34array) for bulk data and input and output for kernels.
35
36OpenCL::Sampler objects, which are kind of like texture filter modes in
37OpenGL.
38
39OpenCL::Queue objects - command queues, which allow you to submit memory
40reads, writes and copies, as well as kernel calls to your devices. They
41also offer a variety of methods to synchronise request execution, for
42example with barriers or OpenCL::Event objects.
43
44OpenCL::Event objects are used to signal when something is complete.
45
13=head1 HELPFUL RESOURCES 46=head2 HELPFUL RESOURCES
14 47
15The OpenCL spec used to develop this module (1.2 spec was available, but 48The OpenCL spec used to develop this module (1.2 spec was available, but
16no implementation was available to me :). 49no implementation was available to me :).
17 50
18 http://www.khronos.org/registry/cl/specs/opencl-1.1.pdf 51 http://www.khronos.org/registry/cl/specs/opencl-1.1.pdf
19 52
20OpenCL manpages: 53OpenCL manpages:
21 54
22 http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/ 55 http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/
56
57=head1 BASIC WORKFLOW
58
59To get something done, you basically have to do this once:
60
61Find some platform (e.g. the first one) and some device (e.g. the first
62device you can find), and create a context from those.
63
64Create a command queue from your context, and program objects from your
65OpenCL source code, build the programs.
66
67Create kernel objects for all kernels you want to use.
68
69Then, to execute stuff, you repeat this:
70
71Create some input and output buffers from your context. Initialise the
72input buffers with data. Set these as arguments to your kernel.
73
74Enqueue the kernel execution.
75
76Enqueue buffer reads for your output buffer to read results.
77
78The next section shows how this can be done.
23 79
24=head1 EXAMPLES 80=head1 EXAMPLES
25 81
26=head2 Enumerate all devices and get contexts for them. 82=head2 Enumerate all devices and get contexts for them.
27 83
… …
37 93
38=head2 Get a useful context and a command queue. 94=head2 Get a useful context and a command queue.
39 95
40 my $dev = ((OpenCL::platforms)[0]->devices)[0]; 96 my $dev = ((OpenCL::platforms)[0]->devices)[0];
41 my $ctx = $dev->context_simple; 97 my $ctx = $dev->context_simple;
42 my $queue = $ctx->command_queue_simple ($dev); 98 my $queue = $ctx->queue ($dev);
43 99
44=head2 Print all supported image formats of a context. 100=head2 Print all supported image formats of a context.
45 101
46 for my $type (OpenCL::MEM_OBJECT_IMAGE2D, OpenCL::MEM_OBJECT_IMAGE3D) { 102 for my $type (OpenCL::MEM_OBJECT_IMAGE2D, OpenCL::MEM_OBJECT_IMAGE3D) {
47 say "supported image formats for ", OpenCL::enum2str $type; 103 say "supported image formats for ", OpenCL::enum2str $type;
… …
148 204
149=item * OpenCL often specifies fixed vector function arguments as short 205=item * OpenCL often specifies fixed vector function arguments as short
150arrays (C<size_t origin[3]>), while this module explicitly expects the 206arrays (C<size_t origin[3]>), while this module explicitly expects the
151components as separate arguments- 207components as separate arguments-
152 208
153=item * Where possible, the row_pitch value is calculated from the perl 209=item * Where possible, one of the pitch values is calculated from the
154scalar length and need not be specified. 210perl scalar length and need not be specified.
155 211
156=item * When enqueuing commands, the wait list is specified by adding 212=item * When enqueuing commands, the wait list is specified by adding
157extra arguments to the function - everywhere a C<$wait_events...> argument 213extra arguments to the function - anywhere a C<$wait_events...> argument
158is documented this can be any number of event objects. 214is documented this can be any number of event objects.
159 215
160=item * When enqueuing commands, if the enqueue method is called in void 216=item * When enqueuing commands, if the enqueue method is called in void
161context, no event is created. In all other contexts an event is returned 217context, no event is created. In all other contexts an event is returned
162by the method. 218by the method.
… …
195 251
196=item $str = OpenCL::err2str $errval 252=item $str = OpenCL::err2str $errval
197 253
198Comverts an error value into a human readable string. 254Comverts an error value into a human readable string.
199 255
200=item $str = OpenCL::err2str $enum 256=item $str = OpenCL::enum2str $enum
201 257
202Converts most enum values (inof parameter names, image format constants, 258Converts most enum values (inof parameter names, image format constants,
203object types, addressing and filter modes, command types etc.) into a 259object types, addressing and filter modes, command types etc.) into a
204human readbale string. When confronted with some random integer it can be 260human readbale string. When confronted with some random integer it can be
205very helpful to pass it through this function to maybe get some readable 261very helpful to pass it through this function to maybe get some readable
… …
275 331
276See C<< $platform->info >> for details. 332See C<< $platform->info >> for details.
277 333
278L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clGetContextInfo.html> 334L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clGetContextInfo.html>
279 335
280=item $queue = $ctx->command_queue_simple ($device) 336=item $queue = $ctx->queue ($device, $properties)
281 337
282Convenience function to create a new OpenCL::Queue object from the context and the given device. 338Create a new OpenCL::Queue object from the context and the given device.
283 339
284L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clCreateCommandQueue.html> 340L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clCreateCommandQueue.html>
285 341
286=item $ev = $ctx->user_event 342=item $ev = $ctx->user_event
287 343

Diff Legend

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