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

Comparing OpenCL/OpenCL.pm (file contents):
Revision 1.16 by root, Thu Nov 17 03:42:03 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 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.
… …
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 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
57Here's a tutorial from AMD (very AMD-centric, too), not sure how useful it 62Here's a tutorial from AMD (very AMD-centric, too), not sure how useful it
58is, but at least it's free of charge: 63is, but at least it's free of charge:
59 64
60 http://developer.amd.com/zones/OpenCLZone/courses/Documents/Introduction_to_OpenCL_Programming%20Training_Guide%20%28201005%29.pdf 65 http://developer.amd.com/zones/OpenCLZone/courses/Documents/Introduction_to_OpenCL_Programming%20Training_Guide%20%28201005%29.pdf
61 66
62If you are into UML class diagrams, the following diagram might help - if 67And here's NVIDIA's OpenCL Best Practises Guide:
63not, it will be mildly cofusing:
64 68
65 http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/classDiagram.html 69 http://developer.download.nvidia.com/compute/cuda/3_2/toolkit/docs/OpenCL_Best_Practices_Guide.pdf
66 70
67=head1 BASIC WORKFLOW 71=head1 BASIC WORKFLOW
68 72
69To 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
70examples below for actual code, this is just a high-level description): 74examples below for actual code, this is just a high-level description):
… …
222 226
223=item * Object lifetime managament is automatic - there is no need 227=item * Object lifetime managament is automatic - there is no need
224to free objects explicitly (C<clReleaseXXX>), the release function 228to free objects explicitly (C<clReleaseXXX>), the release function
225is called automatically once all Perl references to it go away. 229is called automatically once all Perl references to it go away.
226 230
227=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
228while this module uses underscores as word separator and often leaves out 233uses underscores as word separator and often leaves out prefixes
229prefixes (C<< $platform->info >>). 234(C<OpenCL::platforms>, C<< $platform->info >>).
230 235
231=item * OpenCL often specifies fixed vector function arguments as short 236=item * OpenCL often specifies fixed vector function arguments as short
232arrays (C<$origin[3]>), while this module explicitly expects the 237arrays (C<size_t origin[3]>), while this module explicitly expects the
233components as separate arguments- 238components as separate arguments (C<$orig_x, $orig_y, $orig_z>) in
239function calls.
234 240
235=item * Structures are often specified with their components, and returned 241=item * Structures are often specified by flattening out their components
236as arrayrefs. 242as with short vectors, and returned as arrayrefs.
237
238=item * Where possible, one of the pitch values is calculated from the
239perl scalar length and need not be specified.
240 243
241=item * When enqueuing commands, the wait list is specified by adding 244=item * When enqueuing commands, the wait list is specified by adding
242extra arguments to the function - anywhere a C<$wait_events...> argument 245extra arguments to the function - anywhere a C<$wait_events...> argument
243is documented this can be any number of event objects. 246is documented this can be any number of event objects.
244 247
… …
313 316
314=head2 THE OpenCL::Platform CLASS 317=head2 THE OpenCL::Platform CLASS
315 318
316=over 4 319=over 4
317 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
318=item $packed_value = $platform->info ($name) 338=item $packed_value = $platform->info ($name)
319 339
320Calls C<clGetPlatformInfo> and returns the packed, raw value - for 340Calls C<clGetPlatformInfo> and returns the packed, raw value - for
321strings, 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
322use 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.
323 346
324L<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>
325 348
326=item @devices = $platform->devices ($type = OpenCL::DEVICE_TYPE_ALL) 349=for gengetinfo begin platform
327 350
328Returns a list of matching OpenCL::Device objects.
329 351
330=item $ctx = $platform->context_from_type ($properties, $type = OpenCL::DEVICE_TYPE_DEFAULT, $notify = undef) 352=item $string = $platform->profile
331 353
332Tries 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).
333 355
334L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clCreateContextFromType.html> 356=item $string = $platform->version
335 357
336=item $ctx = $device->context ($properties = undef, @$devices, $notify = undef) 358Calls C<clGetPlatformInfo> with C<CL_PLATFORM_VERSION> and returns the result(s).
337 359
338Create a new OpenCL::Context object using the given device object(s)- a 360=item $string = $platform->name
339CL_CONTEXT_PLATFORM property is supplied automatically.
340 361
341L<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
342 372
343=back 373=back
344 374
345=head2 THE OpenCL::Device CLASS 375=head2 THE OpenCL::Device CLASS
346 376
… …
356 386
357=head2 THE OpenCL::Context CLASS 387=head2 THE OpenCL::Context CLASS
358 388
359=over 4 389=over 4
360 390
361=item $packed_value = $ctx->info ($name)
362
363See C<< $platform->info >> for details.
364
365L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clGetContextInfo.html>
366
367=item $queue = $ctx->queue ($device, $properties) 391=item $queue = $ctx->queue ($device, $properties)
368 392
369Create 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.
370 394
371L<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>
… …
384 408
385=item $buf = $ctx->buffer_sv ($flags, $data) 409=item $buf = $ctx->buffer_sv ($flags, $data)
386 410
387Creates 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.
388 412
389=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)
390 414
391Creates 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.
392 416
393L<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>
394 418
395=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)
396 420
397Creates 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.
398 422
399L<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>
400 424
… …
414=item $program = $ctx->program_with_source ($string) 438=item $program = $ctx->program_with_source ($string)
415 439
416Creates a new OpenCL::Program object from the given source code. 440Creates a new OpenCL::Program object from the given source code.
417 441
418L<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
419 453
420=back 454=back
421 455
422=head2 THE OpenCL::Queue CLASS 456=head2 THE OpenCL::Queue CLASS
423 457
… …
463 497
464=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...)
465 499
466L<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>
467 501
468=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...)
469 503
470L<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>
471 505
472=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, $wait_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...)
473 507
474Yeah. 508Yeah.
475 509
476L<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>
477 511
… …
545 579
546L<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>
547 581
548=back 582=back
549 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
550=head2 THE OpenCL::Sampler CLASS 601=head2 THE OpenCL::Sampler CLASS
551 602
552=over 4 603=over 4
553 604
554=item $packed_value = $sampler->info ($name) 605=item $packed_value = $sampler->info ($name)
… …
598=item $packed_value = $kernel->info ($name) 649=item $packed_value = $kernel->info ($name)
599 650
600See C<< $platform->info >> for details. 651See C<< $platform->info >> for details.
601 652
602L<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>
603 663
604=item $kernel->set_TYPE ($index, $value) 664=item $kernel->set_TYPE ($index, $value)
605 665
606This 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>.
607 667
… …
629 689
630See C<< $platform->info >> for details. 690See C<< $platform->info >> for details.
631 691
632L<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>
633 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
634=item $ev->wait 703=item $ev->wait
635 704
636Waits for the event to complete. 705Waits for the event to complete.
637 706
638L<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>
… …
656package OpenCL; 725package OpenCL;
657 726
658use common::sense; 727use common::sense;
659 728
660BEGIN { 729BEGIN {
661 our $VERSION = '0.14'; 730 our $VERSION = '0.15';
662 731
663 require XSLoader; 732 require XSLoader;
664 XSLoader::load (__PACKAGE__, $VERSION); 733 XSLoader::load (__PACKAGE__, $VERSION);
665 734
666 @OpenCL::Buffer::ISA = 735 @OpenCL::Buffer::ISA =

Diff Legend

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