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

Comparing OpenCL/OpenCL.pm (file contents):
Revision 1.10 by root, Thu Nov 17 02:10:39 2011 UTC vs.
Revision 1.11 by root, Thu Nov 17 02:54:14 2011 UTC

… …
18vendors) - usually there is only one. 18vendors) - usually there is only one.
19 19
20Each platform gives you access to a number of OpenCL::Device objects, e.g. 20Each platform gives you access to a number of OpenCL::Device objects, e.g.
21your graphics card. 21your graphics card.
22 22
23From a platform and some devices, you create an OpenCL::Context, which is 23From a platform and some device(s), you create an OpenCL::Context, which is
24a very central object in OpenCL: Once you have a context you can create 24a very central object in OpenCL: Once you have a context you can create
25most other objects: 25most other objects:
26 26
27OpenCL::Program objects, which store source code and, after building 27OpenCL::Program objects, which store source code and, after building for a
28("compiling and linking"), also binary programs. For each kernel function 28specific device ("compiling and linking"), also binary programs. For each
29in a program you can then create an OpenCL::Kernel object which represents 29kernel function in a program you can then create an OpenCL::Kernel object
30basically a function call with argument values. 30which represents basically a function call with argument values.
31 31
32OpenCL::Memory objects of various flavours: OpenCL::Buffers objects (flat 32OpenCL::Memory objects of various flavours: OpenCL::Buffers objects (flat
33memory areas, think array) and OpenCL::Image objects (think 2d or 3d 33memory areas, think array) and OpenCL::Image objects (think 2d or 3d
34array) for bulk data and input and output for kernels. 34array) for bulk data and input and output for kernels.
35 35
… …
54 54
55 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 56
57=head1 BASIC WORKFLOW 57=head1 BASIC WORKFLOW
58 58
59To get something done, you basically have to do this once: 59To get something done, you basically have to do this once (refer to the
60examples below for actual code, this is just a high-level description):
60 61
61Find some platform (e.g. the first one) and some device (e.g. the first 62Find some platform (e.g. the first one) and some device(s) (e.g. the first
62device you can find), and create a context from those. 63device of the platform), and create a context from those.
63 64
64Create a command queue from your context, and program objects from your 65Create program objects from your OpenCL source code, then build (compile)
65OpenCL source code, build the programs. 66the programs for each device you want to run them on.
66 67
67Create kernel objects for all kernels you want to use. 68Create kernel objects for all kernels you want to use (surprisingly, these
69are not device-specific).
68 70
69Then, to execute stuff, you repeat this: 71Then, to execute stuff, you repeat these steps, possibly resuing or
72sharing some buffers:
70 73
71Create some input and output buffers from your context. Initialise the 74Create some input and output buffers from your context. Set these as
72input buffers with data. Set these as arguments to your kernel. 75arguments to your kernel.
76
77Enqueue buffer writes to initialise your input buffers (when not
78initialised at creation time).
73 79
74Enqueue the kernel execution. 80Enqueue the kernel execution.
75 81
76Enqueue buffer reads for your output buffer to read results. 82Enqueue buffer reads for your output buffer to read results.
77 83
78The next section shows how this can be done.
79
80=head1 EXAMPLES 84=head1 EXAMPLES
81 85
82=head2 Enumerate all devices and get contexts for them. 86=head2 Enumerate all devices and get contexts for them.
87
88Best run this once to get a feel for the platforms and devices in your
89system.
83 90
84 for my $platform (OpenCL::platforms) { 91 for my $platform (OpenCL::platforms) {
85 printf "platform: %s\n", $platform->info (OpenCL::PLATFORM_NAME); 92 printf "platform: %s\n", $platform->info (OpenCL::PLATFORM_NAME);
86 printf "extensions: %s\n", $platform->info (OpenCL::PLATFORM_EXTENSIONS); 93 printf "extensions: %s\n", $platform->info (OpenCL::PLATFORM_EXTENSIONS);
87 for my $device ($platform->devices) { 94 for my $device ($platform->devices) {
… …
91 } 98 }
92 } 99 }
93 100
94=head2 Get a useful context and a command queue. 101=head2 Get a useful context and a command queue.
95 102
96 my $dev = ((OpenCL::platforms)[0]->devices)[0]; 103This is a useful boilerplate for any OpenCL program that only wants to use
97 my $ctx = $dev->context; 104one device,
98 my $queue = $ctx->queue ($dev); 105
106 my ($platform) = OpenCL::platforms; # find first platform
107 my ($dev) = $platform->devices; # find first device of platform
108 my $ctx = $platform->context (undef, [$dev]); # create context out of those
109 my $queue = $ctx->queue ($dev); # create a command queue for the device
99 110
100=head2 Print all supported image formats of a context. 111=head2 Print all supported image formats of a context.
112
113Best run this once for your context, to see whats available and how to
114gather information.
101 115
102 for my $type (OpenCL::MEM_OBJECT_IMAGE2D, OpenCL::MEM_OBJECT_IMAGE3D) { 116 for my $type (OpenCL::MEM_OBJECT_IMAGE2D, OpenCL::MEM_OBJECT_IMAGE3D) {
103 print "supported image formats for ", OpenCL::enum2str $type, "\n"; 117 print "supported image formats for ", OpenCL::enum2str $type, "\n";
104 118
105 for my $f ($ctx->supported_image_formats (0, $type)) { 119 for my $f ($ctx->supported_image_formats (0, $type)) {
… …
131 } 145 }
132 '; 146 ';
133 147
134 my $prog = $ctx->program_with_source ($src); 148 my $prog = $ctx->program_with_source ($src);
135 149
150 # build croaks on compile errors, so catch it and print the compile errors
136 eval { $prog->build ($dev); 1 } 151 eval { $prog->build ($dev); 1 }
137 or die $prog->build_info ($dev, OpenCL::PROGRAM_BUILD_LOG); 152 or die $prog->build_info ($dev, OpenCL::PROGRAM_BUILD_LOG);
138 153
139 my $kernel = $prog->kernel ("squareit"); 154 my $kernel = $prog->kernel ("squareit");
140 155
141=head2 Create some input and output float buffers, then call squareit on them. 156=head2 Create some input and output float buffers, then call the
157'squareit' kernel on them.
142 158
143 my $input = $ctx->buffer_sv (OpenCL::MEM_COPY_HOST_PTR, pack "f*", 1, 2, 3, 4.5); 159 my $input = $ctx->buffer_sv (OpenCL::MEM_COPY_HOST_PTR, pack "f*", 1, 2, 3, 4.5);
144 my $output = $ctx->buffer (0, OpenCL::SIZEOF_FLOAT * 5); 160 my $output = $ctx->buffer (0, OpenCL::SIZEOF_FLOAT * 5);
145 161
146 # set buffer 162 # set buffer
… …
245 261
246=over 4 262=over 4
247 263
248=item $int = OpenCL::errno 264=item $int = OpenCL::errno
249 265
250The last error returned by a function - it's only changed on errors. 266The last error returned by a function - it's only valid after an error occured
267and before calling another OpenCL function.
251 268
252=item $str = OpenCL::err2str $errval 269=item $str = OpenCL::err2str $errval
253 270
254Comverts an error value into a human readable string. 271Comverts an error value into a human readable string.
255 272
… …
297 314
298Returns a list of matching OpenCL::Device objects. 315Returns a list of matching OpenCL::Device objects.
299 316
300=item $ctx = $platform->context_from_type ($properties, $type = OpenCL::DEVICE_TYPE_DEFAULT, $notify = undef) 317=item $ctx = $platform->context_from_type ($properties, $type = OpenCL::DEVICE_TYPE_DEFAULT, $notify = undef)
301 318
302Tries to create a context. Never worked for me. 319Tries to create a context. Never worked for me, and you need devices explitly anyway.
303 320
304L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clCreateContextFromType.html> 321L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clCreateContextFromType.html>
305 322
323=item $ctx = $device->context ($properties = undef, @$devices, $notify = undef)
324
325Create a new OpenCL::Context object using the given device object(s)- a
326CL_CONTEXT_PLATFORM property is supplied automatically.
327
328L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clCreateContext.html>
329
306=back 330=back
307 331
308=head2 THE OpenCL::Device CLASS 332=head2 THE OpenCL::Device CLASS
309 333
310=over 4 334=over 4
… …
312=item $packed_value = $device->info ($name) 336=item $packed_value = $device->info ($name)
313 337
314See C<< $platform->info >> for details. 338See C<< $platform->info >> for details.
315 339
316L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clGetDeviceInfo.html> 340L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clGetDeviceInfo.html>
317
318=item $ctx = $device->context ($properties = undef, $notify = undef)
319
320Create a new OpenCL::Context object.
321
322L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clCreateContext.html>
323 341
324=back 342=back
325 343
326=head2 THE OpenCL::Context CLASS 344=head2 THE OpenCL::Context CLASS
327 345

Diff Legend

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