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

Comparing OpenCL/OpenCL.pm (file contents):
Revision 1.5 by root, Wed Nov 16 00:35:30 2011 UTC vs.
Revision 1.9 by root, Thu Nov 17 01:36:52 2011 UTC

… …
6 6
7 use OpenCL; 7 use OpenCL;
8 8
9=head1 DESCRIPTION 9=head1 DESCRIPTION
10 10
11This is an early release which might be useful, but hasn't seen any 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.
… …
165other status is returned the function will throw an exception, so you 221other status is returned the function will throw an exception, so you
166don't normally have to to any error checking. 222don't normally have to to any error checking.
167 223
168=back 224=back
169 225
226=head2 PERL AND OPENCL TYPES
227
228This handy(?) table lists OpenCL types and their perl, PDL and pack/unpack
229format equivalents:
230
231 OpenCL perl PDL pack/unpack
232 char IV - c
233 uchar IV byte C
234 short IV short s
235 ushort IV ushort S
236 int IV long? l
237 uint IV - L
238 long IV longlong q
239 ulong IV - Q
240 float NV float f
241 half IV ushort S
242 double NV double d
243
170=head2 THE OpenCL PACKAGE 244=head2 THE OpenCL PACKAGE
171 245
172=over 4 246=over 4
173 247
174=item $int = OpenCL::errno 248=item $int = OpenCL::errno
… …
177 251
178=item $str = OpenCL::err2str $errval 252=item $str = OpenCL::err2str $errval
179 253
180Comverts an error value into a human readable string. 254Comverts an error value into a human readable string.
181 255
182=item $str = OpenCL::err2str $enum 256=item $str = OpenCL::enum2str $enum
183 257
184Converts most enum values (inof parameter names, image format constants, 258Converts most enum values (inof parameter names, image format constants,
185object types, addressing and filter modes, command types etc.) into a 259object types, addressing and filter modes, command types etc.) into a
186human readbale string. When confronted with some random integer it can be 260human readbale string. When confronted with some random integer it can be
187very 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
… …
257 331
258See C<< $platform->info >> for details. 332See C<< $platform->info >> for details.
259 333
260L<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>
261 335
262=item $queue = $ctx->command_queue_simple ($device) 336=item $queue = $ctx->queue ($device, $properties)
263 337
264Convenience 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.
265 339
266L<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>
267 341
268=item $ev = $ctx->user_event 342=item $ev = $ctx->user_event
269 343
… …
327They also allow you to specify any number of other event objects that this 401They also allow you to specify any number of other event objects that this
328request has to wait for before it starts executing, by simply passing the 402request has to wait for before it starts executing, by simply passing the
329event objects as extra parameters to the enqueue methods. 403event objects as extra parameters to the enqueue methods.
330 404
331Queues execute in-order by default, without any parallelism, so in most 405Queues execute in-order by default, without any parallelism, so in most
332cases it's not necessary to wait for or create event objects. 406cases (i.e. you use only one queue) it's not necessary to wait for or
407create event objects.
333 408
334=over 4 409=over 4
335 410
336=item $packed_value = $ctx->info ($name) 411=item $packed_value = $ctx->info ($name)
337 412

Diff Legend

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