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

Comparing OpenCL/OpenCL.pm (file contents):
Revision 1.13 by root, Thu Nov 17 03:01:35 2011 UTC vs.
Revision 1.20 by root, Sun Nov 20 01:09:48 2011 UTC

… …
27OpenCL::Program objects, which store source code and, after building for a 27OpenCL::Program objects, which store source code and, after building for a
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::Buffers objects (flat 32OpenCL::Memory objects of various flavours: OpenCL::Buffer objects (flat
33memory areas, think array) and OpenCL::Image objects (think 2d or 3d 33memory areas, think arrays or structs) and OpenCL::Image objects (think 2d
34array) 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
… …
51 http://www.khronos.org/registry/cl/specs/opencl-1.1.pdf 51 http://www.khronos.org/registry/cl/specs/opencl-1.1.pdf
52 52
53OpenCL manpages: 53OpenCL manpages:
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
57If you are into UML class diagrams, the following diagram might help - if
58not, it will be mildly cobfusing:
59
60 http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/classDiagram.html
61
62Here's a tutorial from AMD (very AMD-centric, too), not sure how useful it
63is, but at least it's free of charge:
64
65 http://developer.amd.com/zones/OpenCLZone/courses/Documents/Introduction_to_OpenCL_Programming%20Training_Guide%20%28201005%29.pdf
66
67And here's NVIDIA's OpenCL Best Practises Guide:
68
69 http://developer.download.nvidia.com/compute/cuda/3_2/toolkit/docs/OpenCL_Best_Practices_Guide.pdf
56 70
57=head1 BASIC WORKFLOW 71=head1 BASIC WORKFLOW
58 72
59To get something done, you basically have to do this once (refer to the 73To 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): 74examples below for actual code, this is just a high-level description):
… …
138 152
139 my $src = ' 153 my $src = '
140 __kernel void 154 __kernel void
141 squareit (__global float *input, __global float *output) 155 squareit (__global float *input, __global float *output)
142 { 156 {
143 size_t id = get_global_id (0); 157 $id = get_global_id (0);
144 output [id] = input [id] * input [id]; 158 output [id] = input [id] * input [id];
145 } 159 }
146 '; 160 ';
147 161
148 my $prog = $ctx->program_with_source ($src); 162 my $prog = $ctx->program_with_source ($src);
… …
201 215
202=head1 DOCUMENTATION 216=head1 DOCUMENTATION
203 217
204=head2 BASIC CONVENTIONS 218=head2 BASIC CONVENTIONS
205 219
206This is not a 1:1 C-style translation of OpenCL to Perl - instead I 220This is not a one-to-one C-style translation of OpenCL to Perl - instead
207attempted to make the interface as type-safe as possible and introducing 221I attempted to make the interface as type-safe as possible by introducing
208object syntax where it makes sense. There are a number of important 222object syntax where it makes sense. There are a number of important
209differences between the OpenCL C API and this module: 223differences between the OpenCL C API and this module:
210 224
211=over 4 225=over 4
212 226
213=item * Object lifetime managament is automatic - there is no need 227=item * Object lifetime managament is automatic - there is no need
214to free objects explicitly (C<clReleaseXXX>), the release function 228to free objects explicitly (C<clReleaseXXX>), the release function
215is called automatically once all Perl references to it go away. 229is called automatically once all Perl references to it go away.
216 230
217=item * OpenCL uses CamelCase for function names (C<clGetPlatformInfo>), 231=item * OpenCL uses CamelCase for function names
232(e.g. C<clGetPlatformIDs>, C<clGetPlatformInfo>), while this module
218while this module uses underscores as word separator and often leaves out 233uses underscores as word separator and often leaves out prefixes
219prefixes (C<< $platform->info >>). 234(C<OpenCL::platforms>, C<< $platform->info >>).
220 235
221=item * OpenCL often specifies fixed vector function arguments as short 236=item * OpenCL often specifies fixed vector function arguments as short
222arrays (C<size_t origin[3]>), while this module explicitly expects the 237arrays (C<size_t origin[3]>), while this module explicitly expects the
223components as separate arguments- 238components as separate arguments (C<$orig_x, $orig_y, $orig_z>) in
239function calls.
224 240
225=item * Structures are often specified with their components, and returned 241=item * Structures are often specified by flattening out their components
226as arrayrefs. 242as with short vectors, and returned as arrayrefs.
227
228=item * Where possible, one of the pitch values is calculated from the
229perl scalar length and need not be specified.
230 243
231=item * When enqueuing commands, the wait list is specified by adding 244=item * When enqueuing commands, the wait list is specified by adding
232extra arguments to the function - anywhere a C<$wait_events...> argument 245extra arguments to the function - anywhere a C<$wait_events...> argument
233is documented this can be any number of event objects. 246is documented this can be any number of event objects.
234 247
… …
303 316
304=head2 THE OpenCL::Platform CLASS 317=head2 THE OpenCL::Platform CLASS
305 318
306=over 4 319=over 4
307 320
321=item @devices = $platform->devices ($type = OpenCL::DEVICE_TYPE_ALL)
322
323Returns a list of matching OpenCL::Device objects.
324
325=item $ctx = $platform->context_from_type ($properties, $type = OpenCL::DEVICE_TYPE_DEFAULT, $notify = undef)
326
327Tries to create a context. Never worked for me, and you need devices explitly anyway.
328
329L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clCreateContextFromType.html>
330
331=item $ctx = $device->context ($properties = undef, @$devices, $notify = undef)
332
333Create a new OpenCL::Context object using the given device object(s)- a
334CL_CONTEXT_PLATFORM property is supplied automatically.
335
336L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clCreateContext.html>
337
308=item $packed_value = $platform->info ($name) 338=item $packed_value = $platform->info ($name)
309 339
310Calls C<clGetPlatformInfo> and returns the packed, raw value - for 340Calls C<clGetPlatformInfo> and returns the packed, raw value - for
311strings, this will be the string, for other values you probably need to 341strings, this will be the string, for other values you probably need to
312use the correct C<unpack>. This might get improved in the future. Hopefully. 342use the correct C<unpack>.
343
344It's best to avoid this method and use one of the predefined C<get_*>
345methods.
313 346
314L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clGetPlatformInfo.html> 347L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clGetPlatformInfo.html>
315 348
316=item @devices = $platform->devices ($type = OpenCL::DEVICE_TYPE_ALL) 349=for gengetinfo begin platform
317 350
318Returns a list of matching OpenCL::Device objects.
319 351
320=item $ctx = $platform->context_from_type ($properties, $type = OpenCL::DEVICE_TYPE_DEFAULT, $notify = undef) 352=item $string = $platform->profile
321 353
322Tries to create a context. Never worked for me, and you need devices explitly anyway. 354Calls C<clGetPlatformInfo> with C<CL_PLATFORM_PROFILE> and returns the result(s).
323 355
324L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clCreateContextFromType.html> 356=item $string = $platform->version
325 357
326=item $ctx = $device->context ($properties = undef, @$devices, $notify = undef) 358Calls C<clGetPlatformInfo> with C<CL_PLATFORM_VERSION> and returns the result(s).
327 359
328Create a new OpenCL::Context object using the given device object(s)- a 360=item $string = $platform->name
329CL_CONTEXT_PLATFORM property is supplied automatically.
330 361
331L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clCreateContext.html> 362Calls C<clGetPlatformInfo> with C<CL_PLATFORM_NAME> and returns the result(s).
363
364=item $string = $platform->vendor
365
366Calls C<clGetPlatformInfo> with C<CL_PLATFORM_VENDOR> and returns the result(s).
367
368=item $string = $platform->extensions
369
370Calls C<clGetPlatformInfo> with C<CL_PLATFORM_EXTENSIONS> and returns the result(s).
371=for gengetinfo end platform
332 372
333=back 373=back
334 374
335=head2 THE OpenCL::Device CLASS 375=head2 THE OpenCL::Device CLASS
336 376
… …
346 386
347=head2 THE OpenCL::Context CLASS 387=head2 THE OpenCL::Context CLASS
348 388
349=over 4 389=over 4
350 390
351=item $packed_value = $ctx->info ($name)
352
353See C<< $platform->info >> for details.
354
355L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clGetContextInfo.html>
356
357=item $queue = $ctx->queue ($device, $properties) 391=item $queue = $ctx->queue ($device, $properties)
358 392
359Create a new OpenCL::Queue object from the context and the given device. 393Create a new OpenCL::Queue object from the context and the given device.
360 394
361L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clCreateCommandQueue.html> 395L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clCreateCommandQueue.html>
… …
374 408
375=item $buf = $ctx->buffer_sv ($flags, $data) 409=item $buf = $ctx->buffer_sv ($flags, $data)
376 410
377Creates a new OpenCL::Buffer object and initialise it with the given data values. 411Creates a new OpenCL::Buffer object and initialise it with the given data values.
378 412
379=item $img = $ctx->image2d ($flags, $channel_order, $channel_type, $width, $height, $data) 413=item $img = $ctx->image2d ($flags, $channel_order, $channel_type, $width, $height, $row_pitch = 0, $data = undef)
380 414
381Creates a new OpenCL::Image2D object and optionally initialises it with the given data values. 415Creates a new OpenCL::Image2D object and optionally initialises it with the given data values.
382 416
383L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clCreateImage2D.html> 417L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clCreateImage2D.html>
384 418
385=item $img = $ctx->image3d ($flags, $channel_order, $channel_type, $width, $height, $depth, $slice_pitch, $data) 419=item $img = $ctx->image3d ($flags, $channel_order, $channel_type, $width, $height, $depth, $row_pitch = 0, $slice_pitch = 0, $data = undef)
386 420
387Creates a new OpenCL::Image3D object and optionally initialises it with the given data values. 421Creates a new OpenCL::Image3D object and optionally initialises it with the given data values.
388 422
389L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clCreateImage3D.html> 423L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clCreateImage3D.html>
390 424
… …
404=item $program = $ctx->program_with_source ($string) 438=item $program = $ctx->program_with_source ($string)
405 439
406Creates a new OpenCL::Program object from the given source code. 440Creates a new OpenCL::Program object from the given source code.
407 441
408L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clCreateProgramWithSource.html> 442L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clCreateProgramWithSource.html>
443
444=item $packed_value = $ctx->info ($name)
445
446See C<< $platform->info >> for details.
447
448L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clGetContextInfo.html>
449
450=for gengetinfo begin context
451
452=for gengetinfo end context
409 453
410=back 454=back
411 455
412=head2 THE OpenCL::Queue CLASS 456=head2 THE OpenCL::Queue CLASS
413 457
… …
453 497
454=item $ev = $queue->enqueue_read_image ($src, $blocking, $x, $y, $z, $width, $height, $depth, $row_pitch, $slice_pitch, $data, $wait_events...) 498=item $ev = $queue->enqueue_read_image ($src, $blocking, $x, $y, $z, $width, $height, $depth, $row_pitch, $slice_pitch, $data, $wait_events...)
455 499
456L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clEnqueueReadImage.html> 500L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clEnqueueReadImage.html>
457 501
458=item $ev = $queue->enqueue_write_image ($src, $blocking, $x, $y, $z, $width, $height, $depth, $row_pitch, $data, $wait_events...) 502=item $ev = $queue->enqueue_write_image ($src, $blocking, $x, $y, $z, $width, $height, $depth, $row_pitch, $slice_pitch, $data, $wait_events...)
459 503
460L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clEnqueueWriteImage.html> 504L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clEnqueueWriteImage.html>
461 505
462=item $ev = $queue->enqueue_copy_buffer_rect ($src, $dst, $src_x, $src_y, $src_z, $dst_x, $dst_y, $dst_z, $width, $height, $depth, $src_row_pitch, $src_slice_pitch, 4dst_row_pitch, $dst_slice_pitch, $ait_event...) 506=item $ev = $queue->enqueue_copy_buffer_rect ($src, $dst, $src_x, $src_y, $src_z, $dst_x, $dst_y, $dst_z, $width, $height, $depth, $src_row_pitch, $src_slice_pitch, $dst_row_pitch, $dst_slice_pitch, $wait_event...)
463 507
464Yeah. 508Yeah.
465 509
466L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clEnqueueCopyBufferRect.html> 510L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clEnqueueCopyBufferRect.html>
467 511
468=item $ev = $queue->enqueue_copy_buffer_to_image (OpenCL::Buffer src, OpenCL::Image dst, size_t src_offset, size_t dst_x, size_t dst_y, size_t dst_z, size_t width, size_t height, size_t depth, ...) 512=item $ev = $queue->enqueue_copy_buffer_to_image ($src_buffer, $dst_image, $src_offset, $dst_x, $dst_y, $dst_z, $width, $height, $depth, $wait_events...)
469 513
470L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clEnqueueCopyBufferToImage.html>. 514L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clEnqueueCopyBufferToImage.html>.
471 515
472=item $ev = $queue->enqueue_copy_image (OpenCL::Image src, OpenCL::Buffer dst, size_t src_x, size_t src_y, size_t src_z, size_t dst_x, size_t dst_y, size_t dst_z, size_t width, size_t height, size_t depth, ...) 516=item $ev = $queue->enqueue_copy_image ($src_image, $dst_image, $src_x, $src_y, $src_z, $dst_x, $dst_y, $dst_z, $width, $height, $depth, $wait_events...)
473 517
474L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clEnqueueCopyImage.html> 518L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clEnqueueCopyImage.html>
475 519
476=item $ev = $queue->enqueue_copy_image_to_buffer (OpenCL::Image src, OpenCL::Buffer dst, size_t src_x, size_t src_y, size_t src_z, size_t width, size_t height, size_t depth, size_t dst_offset, ...) 520=item $ev = $queue->enqueue_copy_image_to_buffer ($src_image, $dst_image, $src_x, $src_y, $src_z, $width, $height, $depth, $dst_offset, $wait_events...)
477 521
478L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clEnqueueCopyImageToBuffer.html> 522L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clEnqueueCopyImageToBuffer.html>
479 523
480=item $ev = $queue->enqueue_task ($kernel, $wait_events...) 524=item $ev = $queue->enqueue_task ($kernel, $wait_events...)
481 525
… …
535 579
536L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clGetMemObjectInfo.html> 580L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clGetMemObjectInfo.html>
537 581
538=back 582=back
539 583
584=head2 THE OpenCL::Image CLASS
585
586This is the superclass of all image objects - OpenCL::Image2D and OpenCL::Image3D.
587
588=over 4
589
590=item $packed_value = $ev->image_info ($name)
591
592See C<< $platform->info >> for details.
593
594The reason this method is not called C<info> is that there already is an
595C<< ->info >> method inherited from C<OpenCL::Memory>.
596
597L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clGetImageInfo.html>
598
599=back
600
540=head2 THE OpenCL::Sampler CLASS 601=head2 THE OpenCL::Sampler CLASS
541 602
542=over 4 603=over 4
543 604
544=item $packed_value = $sampler->info ($name) 605=item $packed_value = $sampler->info ($name)
… …
588=item $packed_value = $kernel->info ($name) 649=item $packed_value = $kernel->info ($name)
589 650
590See C<< $platform->info >> for details. 651See C<< $platform->info >> for details.
591 652
592L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clGetKernelInfo.html> 653L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clGetKernelInfo.html>
654
655=item $packed_value = $kernel->work_group_info ($device, $name)
656
657See C<< $platform->info >> for details.
658
659The reason this method is not called C<info> is that there already is an
660C<< ->info >> method.
661
662L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clGetKernelWorkGroupInfo.html>
593 663
594=item $kernel->set_TYPE ($index, $value) 664=item $kernel->set_TYPE ($index, $value)
595 665
596This is a family of methods to set the kernel argument with the number C<$index> to the give C<$value>. 666This is a family of methods to set the kernel argument with the number C<$index> to the give C<$value>.
597 667
… …
619 689
620See C<< $platform->info >> for details. 690See C<< $platform->info >> for details.
621 691
622L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clGetEventInfo.html> 692L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clGetEventInfo.html>
623 693
694=item $packed_value = $ev->profiling_info ($name)
695
696See C<< $platform->info >> for details.
697
698The reason this method is not called C<info> is that there already is an
699C<< ->info >> method.
700
701L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clGetProfilingInfo.html>
702
624=item $ev->wait 703=item $ev->wait
625 704
626Waits for the event to complete. 705Waits for the event to complete.
627 706
628L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clWaitForEvents.html> 707L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clWaitForEvents.html>
… …
646package OpenCL; 725package OpenCL;
647 726
648use common::sense; 727use common::sense;
649 728
650BEGIN { 729BEGIN {
651 our $VERSION = '0.14'; 730 our $VERSION = '0.15';
652 731
653 require XSLoader; 732 require XSLoader;
654 XSLoader::load (__PACKAGE__, $VERSION); 733 XSLoader::load (__PACKAGE__, $VERSION);
655 734
656 @OpenCL::Buffer::ISA = 735 @OpenCL::Buffer::ISA =

Diff Legend

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