… | |
… | |
27 | OpenCL::Program objects, which store source code and, after building for a |
27 | OpenCL::Program objects, which store source code and, after building for a |
28 | specific device ("compiling and linking"), also binary programs. For each |
28 | specific device ("compiling and linking"), also binary programs. For each |
29 | kernel function in a program you can then create an OpenCL::Kernel object |
29 | kernel function in a program you can then create an OpenCL::Kernel object |
30 | which represents basically a function call with argument values. |
30 | which represents basically a function call with argument values. |
31 | |
31 | |
32 | OpenCL::Memory objects of various flavours: OpenCL::Buffers objects (flat |
32 | OpenCL::Memory objects of various flavours: OpenCL::Buffer objects (flat |
33 | memory areas, think arrays or structs) and OpenCL::Image objects (think 2d |
33 | memory areas, think arrays or structs) and OpenCL::Image objects (think 2d |
34 | or 3d array) for bulk data and input and output for kernels. |
34 | or 3d array) for bulk data and input and output for kernels. |
35 | |
35 | |
36 | OpenCL::Sampler objects, which are kind of like texture filter modes in |
36 | OpenCL::Sampler objects, which are kind of like texture filter modes in |
37 | OpenGL. |
37 | OpenGL. |
… | |
… | |
52 | |
52 | |
53 | OpenCL manpages: |
53 | OpenCL 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 | |
|
|
57 | If you are into UML class diagrams, the following diagram might help - if |
|
|
58 | not, it will be mildly cobfusing: |
|
|
59 | |
|
|
60 | http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/classDiagram.html |
|
|
61 | |
57 | Here's a tutorial from AMD (very AMD-centric, too), not sure how useful it |
62 | Here's a tutorial from AMD (very AMD-centric, too), not sure how useful it |
58 | is, but at least it's free of charge: |
63 | is, 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 | |
62 | If you are into UML class diagrams, the following diagram might help - if |
67 | And here's NVIDIA's OpenCL Best Practises Guide: |
63 | not, 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 | |
69 | To get something done, you basically have to do this once (refer to the |
73 | To get something done, you basically have to do this once (refer to the |
70 | examples below for actual code, this is just a high-level description): |
74 | examples 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 |
224 | to free objects explicitly (C<clReleaseXXX>), the release function |
228 | to free objects explicitly (C<clReleaseXXX>), the release function |
225 | is called automatically once all Perl references to it go away. |
229 | is 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 |
228 | while this module uses underscores as word separator and often leaves out |
233 | uses underscores as word separator and often leaves out prefixes |
229 | prefixes (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 |
232 | arrays (C<$origin[3]>), while this module explicitly expects the |
237 | arrays (C<size_t origin[3]>), while this module explicitly expects the |
233 | components as separate arguments- |
238 | components as separate arguments (C<$orig_x, $orig_y, $orig_z>) in |
|
|
239 | function 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 |
236 | as arrayrefs. |
242 | as with short vectors, and returned as arrayrefs. |
237 | |
|
|
238 | =item * Where possible, one of the pitch values is calculated from the |
|
|
239 | perl 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 |
242 | extra arguments to the function - anywhere a C<$wait_events...> argument |
245 | extra arguments to the function - anywhere a C<$wait_events...> argument |
243 | is documented this can be any number of event objects. |
246 | is 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 | |
|
|
323 | Returns a list of matching OpenCL::Device objects. |
|
|
324 | |
|
|
325 | =item $ctx = $platform->context_from_type ($properties, $type = OpenCL::DEVICE_TYPE_DEFAULT, $notify = undef) |
|
|
326 | |
|
|
327 | Tries to create a context. Never worked for me, and you need devices explitly anyway. |
|
|
328 | |
|
|
329 | L<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 | |
|
|
333 | Create a new OpenCL::Context object using the given device object(s)- a |
|
|
334 | CL_CONTEXT_PLATFORM property is supplied automatically. |
|
|
335 | |
|
|
336 | L<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 | |
320 | Calls C<clGetPlatformInfo> and returns the packed, raw value - for |
340 | Calls C<clGetPlatformInfo> and returns the packed, raw value - for |
321 | strings, this will be the string, for other values you probably need to |
341 | strings, this will be the string, for other values you probably need to |
322 | use the correct C<unpack>. This might get improved in the future. Hopefully. |
342 | use the correct C<unpack>. |
|
|
343 | |
|
|
344 | It's best to avoid this method and use one of the predefined C<get_*> |
|
|
345 | methods. |
323 | |
346 | |
324 | L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clGetPlatformInfo.html> |
347 | L<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 | |
328 | Returns 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 | |
332 | Tries to create a context. Never worked for me, and you need devices explitly anyway. |
354 | Calls C<clGetPlatformInfo> with C<CL_PLATFORM_PROFILE> and returns the result(s). |
333 | |
355 | |
334 | L<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) |
358 | Calls C<clGetPlatformInfo> with C<CL_PLATFORM_VERSION> and returns the result(s). |
337 | |
359 | |
338 | Create a new OpenCL::Context object using the given device object(s)- a |
360 | =item $string = $platform->name |
339 | CL_CONTEXT_PLATFORM property is supplied automatically. |
|
|
340 | |
361 | |
341 | L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clCreateContext.html> |
362 | Calls C<clGetPlatformInfo> with C<CL_PLATFORM_NAME> and returns the result(s). |
|
|
363 | |
|
|
364 | =item $string = $platform->vendor |
|
|
365 | |
|
|
366 | Calls C<clGetPlatformInfo> with C<CL_PLATFORM_VENDOR> and returns the result(s). |
|
|
367 | |
|
|
368 | =item $string = $platform->extensions |
|
|
369 | |
|
|
370 | Calls 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 | |
|
|
363 | See C<< $platform->info >> for details. |
|
|
364 | |
|
|
365 | L<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 | |
369 | Create a new OpenCL::Queue object from the context and the given device. |
393 | Create a new OpenCL::Queue object from the context and the given device. |
370 | |
394 | |
371 | L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clCreateCommandQueue.html> |
395 | L<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 | |
387 | Creates a new OpenCL::Buffer object and initialise it with the given data values. |
411 | Creates 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 | |
391 | Creates a new OpenCL::Image2D object and optionally initialises it with the given data values. |
415 | Creates a new OpenCL::Image2D object and optionally initialises it with the given data values. |
392 | |
416 | |
393 | L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clCreateImage2D.html> |
417 | L<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 | |
397 | Creates a new OpenCL::Image3D object and optionally initialises it with the given data values. |
421 | Creates a new OpenCL::Image3D object and optionally initialises it with the given data values. |
398 | |
422 | |
399 | L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clCreateImage3D.html> |
423 | L<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 | |
416 | Creates a new OpenCL::Program object from the given source code. |
440 | Creates a new OpenCL::Program object from the given source code. |
417 | |
441 | |
418 | L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clCreateProgramWithSource.html> |
442 | L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clCreateProgramWithSource.html> |
|
|
443 | |
|
|
444 | =item $packed_value = $ctx->info ($name) |
|
|
445 | |
|
|
446 | See C<< $platform->info >> for details. |
|
|
447 | |
|
|
448 | L<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 | |
466 | L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clEnqueueReadImage.html> |
500 | L<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 | |
470 | L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clEnqueueWriteImage.html> |
504 | L<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 | |
474 | Yeah. |
508 | Yeah. |
475 | |
509 | |
476 | L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clEnqueueCopyBufferRect.html> |
510 | L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clEnqueueCopyBufferRect.html> |
477 | |
511 | |
… | |
… | |
545 | |
579 | |
546 | L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clGetMemObjectInfo.html> |
580 | L<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 | |
|
|
586 | This 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 | |
|
|
592 | See C<< $platform->info >> for details. |
|
|
593 | |
|
|
594 | The reason this method is not called C<info> is that there already is an |
|
|
595 | C<< ->info >> method inherited from C<OpenCL::Memory>. |
|
|
596 | |
|
|
597 | L<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 | |
600 | See C<< $platform->info >> for details. |
651 | See C<< $platform->info >> for details. |
601 | |
652 | |
602 | L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clGetKernelInfo.html> |
653 | L<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 | |
|
|
657 | See C<< $platform->info >> for details. |
|
|
658 | |
|
|
659 | The reason this method is not called C<info> is that there already is an |
|
|
660 | C<< ->info >> method. |
|
|
661 | |
|
|
662 | L<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 | |
606 | This is a family of methods to set the kernel argument with the number C<$index> to the give C<$value>. |
666 | This is a family of methods to set the kernel argument with the number C<$index> to the give C<$value>. |
607 | |
667 | |
… | |
… | |
629 | |
689 | |
630 | See C<< $platform->info >> for details. |
690 | See C<< $platform->info >> for details. |
631 | |
691 | |
632 | L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clGetEventInfo.html> |
692 | L<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 | |
|
|
696 | See C<< $platform->info >> for details. |
|
|
697 | |
|
|
698 | The reason this method is not called C<info> is that there already is an |
|
|
699 | C<< ->info >> method. |
|
|
700 | |
|
|
701 | L<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 | |
636 | Waits for the event to complete. |
705 | Waits for the event to complete. |
637 | |
706 | |
638 | L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clWaitForEvents.html> |
707 | L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clWaitForEvents.html> |
… | |
… | |
656 | package OpenCL; |
725 | package OpenCL; |
657 | |
726 | |
658 | use common::sense; |
727 | use common::sense; |
659 | |
728 | |
660 | BEGIN { |
729 | BEGIN { |
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 = |