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

Comparing OpenCL/OpenCL.pm (file contents):
Revision 1.12 by root, Thu Nov 17 02:56:47 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 * Where possible, one of the pitch values is calculated from the 241=item * Structures are often specified by flattening out their components
226perl scalar length and need not be specified. 242as with short vectors, and returned as arrayrefs.
227 243
228=item * When enqueuing commands, the wait list is specified by adding 244=item * When enqueuing commands, the wait list is specified by adding
229extra arguments to the function - anywhere a C<$wait_events...> argument 245extra arguments to the function - anywhere a C<$wait_events...> argument
230is documented this can be any number of event objects. 246is documented this can be any number of event objects.
231 247
… …
300 316
301=head2 THE OpenCL::Platform CLASS 317=head2 THE OpenCL::Platform CLASS
302 318
303=over 4 319=over 4
304 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
305=item $packed_value = $platform->info ($name) 338=item $packed_value = $platform->info ($name)
306 339
307Calls C<clGetPlatformInfo> and returns the packed, raw value - for 340Calls C<clGetPlatformInfo> and returns the packed, raw value - for
308strings, 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
309use 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.
310 346
311L<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>
312 348
313=item @devices = $platform->devices ($type = OpenCL::DEVICE_TYPE_ALL) 349=for gengetinfo begin platform
314 350
315Returns a list of matching OpenCL::Device objects.
316 351
317=item $ctx = $platform->context_from_type ($properties, $type = OpenCL::DEVICE_TYPE_DEFAULT, $notify = undef) 352=item $string = $platform->profile
318 353
319Tries 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).
320 355
321L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clCreateContextFromType.html> 356=item $string = $platform->version
322 357
323=item $ctx = $device->context ($properties = undef, @$devices, $notify = undef) 358Calls C<clGetPlatformInfo> with C<CL_PLATFORM_VERSION> and returns the result(s).
324 359
325Create a new OpenCL::Context object using the given device object(s)- a 360=item $string = $platform->name
326CL_CONTEXT_PLATFORM property is supplied automatically.
327 361
328L<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
329 372
330=back 373=back
331 374
332=head2 THE OpenCL::Device CLASS 375=head2 THE OpenCL::Device CLASS
333 376
… …
343 386
344=head2 THE OpenCL::Context CLASS 387=head2 THE OpenCL::Context CLASS
345 388
346=over 4 389=over 4
347 390
348=item $packed_value = $ctx->info ($name)
349
350See C<< $platform->info >> for details.
351
352L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clGetContextInfo.html>
353
354=item $queue = $ctx->queue ($device, $properties) 391=item $queue = $ctx->queue ($device, $properties)
355 392
356Create 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.
357 394
358L<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>
… …
371 408
372=item $buf = $ctx->buffer_sv ($flags, $data) 409=item $buf = $ctx->buffer_sv ($flags, $data)
373 410
374Creates 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.
375 412
376=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)
377 414
378Creates 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.
379 416
380L<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>
381 418
382=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)
383 420
384Creates 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.
385 422
386L<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>
387 424
… …
401=item $program = $ctx->program_with_source ($string) 438=item $program = $ctx->program_with_source ($string)
402 439
403Creates a new OpenCL::Program object from the given source code. 440Creates a new OpenCL::Program object from the given source code.
404 441
405L<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
406 453
407=back 454=back
408 455
409=head2 THE OpenCL::Queue CLASS 456=head2 THE OpenCL::Queue CLASS
410 457
… …
450 497
451=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...)
452 499
453L<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>
454 501
455=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...)
456 503
457L<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>
458 505
459=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...)
460 507
461Yeah. 508Yeah.
462 509
463L<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>
464 511
465=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...)
466 513
467L<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>.
468 515
469=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...)
470 517
471L<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>
472 519
473=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...)
474 521
475L<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>
476 523
477=item $ev = $queue->enqueue_task ($kernel, $wait_events...) 524=item $ev = $queue->enqueue_task ($kernel, $wait_events...)
478 525
… …
532 579
533L<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>
534 581
535=back 582=back
536 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
537=head2 THE OpenCL::Sampler CLASS 601=head2 THE OpenCL::Sampler CLASS
538 602
539=over 4 603=over 4
540 604
541=item $packed_value = $sampler->info ($name) 605=item $packed_value = $sampler->info ($name)
… …
585=item $packed_value = $kernel->info ($name) 649=item $packed_value = $kernel->info ($name)
586 650
587See C<< $platform->info >> for details. 651See C<< $platform->info >> for details.
588 652
589L<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>
590 663
591=item $kernel->set_TYPE ($index, $value) 664=item $kernel->set_TYPE ($index, $value)
592 665
593This 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>.
594 667
… …
616 689
617See C<< $platform->info >> for details. 690See C<< $platform->info >> for details.
618 691
619L<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>
620 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
621=item $ev->wait 703=item $ev->wait
622 704
623Waits for the event to complete. 705Waits for the event to complete.
624 706
625L<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>
… …
643package OpenCL; 725package OpenCL;
644 726
645use common::sense; 727use common::sense;
646 728
647BEGIN { 729BEGIN {
648 our $VERSION = '0.14'; 730 our $VERSION = '0.15';
649 731
650 require XSLoader; 732 require XSLoader;
651 XSLoader::load (__PACKAGE__, $VERSION); 733 XSLoader::load (__PACKAGE__, $VERSION);
652 734
653 @OpenCL::Buffer::ISA = 735 @OpenCL::Buffer::ISA =

Diff Legend

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