NAME

OpenCL - Open Computing Language Bindings

SYNOPSIS

 use OpenCL;

DESCRIPTION

This is an early release which might be useful, but hasn't seen much testing.

OpenCL FROM 10000 FEET HEIGHT

Here is a high level overview of OpenCL:

First you need to find one or more OpenCL::Platforms (kind of like vendors) - usually there is only one.

Each platform gives you access to a number of OpenCL::Device objects, e.g. your graphics card.

From a platform and some device(s), you create an OpenCL::Context, which is a very central object in OpenCL: Once you have a context you can create most other objects:

OpenCL::Program objects, which store source code and, after building for a specific device ("compiling and linking"), also binary programs. For each kernel function in a program you can then create an OpenCL::Kernel object which represents basically a function call with argument values.

OpenCL::Memory objects of various flavours: OpenCL::Buffer objects (flat memory areas, think arrays or structs) and OpenCL::Image objects (think 2d or 3d array) for bulk data and input and output for kernels.

OpenCL::Sampler objects, which are kind of like texture filter modes in OpenGL.

OpenCL::Queue objects - command queues, which allow you to submit memory reads, writes and copies, as well as kernel calls to your devices. They also offer a variety of methods to synchronise request execution, for example with barriers or OpenCL::Event objects.

OpenCL::Event objects are used to signal when something is complete.

HELPFUL RESOURCES

The OpenCL spec used to develop this module (1.2 spec was available, but no implementation was available to me :).

   http://www.khronos.org/registry/cl/specs/opencl-1.1.pdf

OpenCL manpages:

   http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/

If you are into UML class diagrams, the following diagram might help - if not, it will be mildly cobfusing:

   http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/classDiagram.html

Here's a tutorial from AMD (very AMD-centric, too), not sure how useful it is, but at least it's free of charge:

   http://developer.amd.com/zones/OpenCLZone/courses/Documents/Introduction_to_OpenCL_Programming%20Training_Guide%20%28201005%29.pdf

And here's NVIDIA's OpenCL Best Practises Guide:

   http://developer.download.nvidia.com/compute/cuda/3_2/toolkit/docs/OpenCL_Best_Practices_Guide.pdf

BASIC WORKFLOW

To get something done, you basically have to do this once (refer to the examples below for actual code, this is just a high-level description):

Find some platform (e.g. the first one) and some device(s) (e.g. the first device of the platform), and create a context from those.

Create program objects from your OpenCL source code, then build (compile) the programs for each device you want to run them on.

Create kernel objects for all kernels you want to use (surprisingly, these are not device-specific).

Then, to execute stuff, you repeat these steps, possibly resuing or sharing some buffers:

Create some input and output buffers from your context. Set these as arguments to your kernel.

Enqueue buffer writes to initialise your input buffers (when not initialised at creation time).

Enqueue the kernel execution.

Enqueue buffer reads for your output buffer to read results.

EXAMPLES

Enumerate all devices and get contexts for them.

Best run this once to get a feel for the platforms and devices in your system.

   for my $platform (OpenCL::platforms) {
      printf "platform: %s\n", $platform->info (OpenCL::PLATFORM_NAME);
      printf "extensions: %s\n", $platform->info (OpenCL::PLATFORM_EXTENSIONS);
      for my $device ($platform->devices) {
         printf "+ device: %s\n", $device->info (OpenCL::DEVICE_NAME);
         my $ctx = $device->context;
         # do stuff
      }
   }

Get a useful context and a command queue.

This is a useful boilerplate for any OpenCL program that only wants to use one device,

   my ($platform) = OpenCL::platforms; # find first platform
   my ($dev) = $platform->devices;     # find first device of platform
   my $ctx = $platform->context (undef, [$dev]); # create context out of those
   my $queue = $ctx->queue ($dev);     # create a command queue for the device

Print all supported image formats of a context.

Best run this once for your context, to see whats available and how to gather information.

   for my $type (OpenCL::MEM_OBJECT_IMAGE2D, OpenCL::MEM_OBJECT_IMAGE3D) {
      print "supported image formats for ", OpenCL::enum2str $type, "\n";
      
      for my $f ($ctx->supported_image_formats (0, $type)) {
         printf "  %-10s %-20s\n", OpenCL::enum2str $f->[0], OpenCL::enum2str $f->[1];
      }
   }

Create a buffer with some predefined data, read it back synchronously, then asynchronously.

   my $buf = $ctx->buffer_sv (OpenCL::MEM_COPY_HOST_PTR, "helmut");

   $queue->enqueue_read_buffer ($buf, 1, 1, 3, my $data);
   print "$data\n";

   my $ev = $queue->enqueue_read_buffer ($buf, 0, 1, 3, my $data);
   $ev->wait;
   print "$data\n"; # prints "elm"

Create and build a program, then create a kernel out of one of its functions.

   my $src = '
      __kernel void
      squareit (__global float *input, __global float *output)
      {
        $id = get_global_id (0);
        output [id] = input [id] * input [id];
      }
   ';

   my $prog = $ctx->program_with_source ($src);

   # build croaks on compile errors, so catch it and print the compile errors
   eval { $prog->build ($dev); 1 }
      or die $prog->build_info ($dev, OpenCL::PROGRAM_BUILD_LOG);

   my $kernel = $prog->kernel ("squareit");

Create some input and output float buffers, then call the 'squareit' kernel on them.

   my $input  = $ctx->buffer_sv (OpenCL::MEM_COPY_HOST_PTR, pack "f*", 1, 2, 3, 4.5);
   my $output = $ctx->buffer (0, OpenCL::SIZEOF_FLOAT * 5);

   # set buffer
   $kernel->set_buffer (0, $input);
   $kernel->set_buffer (1, $output);

   # execute it for all 4 numbers
   $queue->enqueue_nd_range_kernel ($kernel, undef, [4], undef);

   # enqueue a synchronous read
   $queue->enqueue_read_buffer ($output, 1, 0, OpenCL::SIZEOF_FLOAT * 4, my $data);

   # print the results:
   printf "%s\n", join ", ", unpack "f*", $data;

The same enqueue operations as before, but assuming an out-of-order queue, showing off barriers.

   # execute it for all 4 numbers
   $queue->enqueue_nd_range_kernel ($kernel, undef, [4], undef);

   # enqueue a barrier to ensure in-order execution
   $queue->enqueue_barrier;

   # enqueue an async read
   $queue->enqueue_read_buffer ($output, 0, 0, OpenCL::SIZEOF_FLOAT * 4, my $data);

   # wait for all requests to finish
   $queue->finish;

The same enqueue operations as before, but assuming an out-of-order queue, showing off event objects and wait lists.

   # execute it for all 4 numbers
   my $ev = $queue->enqueue_nd_range_kernel ($kernel, undef, [4], undef);

   # enqueue an async read
   $ev = $queue->enqueue_read_buffer ($output, 0, 0, OpenCL::SIZEOF_FLOAT * 4, my $data, $ev);

   # wait for the last event to complete
   $ev->wait;

DOCUMENTATION

BASIC CONVENTIONS

This is not a one-to-one C-style translation of OpenCL to Perl - instead I attempted to make the interface as type-safe as possible by introducing object syntax where it makes sense. There are a number of important differences between the OpenCL C API and this module:

Object lifetime managament is automatic - there is no need to free objects explicitly (clReleaseXXX), the release function is called automatically once all Perl references to it go away.
OpenCL uses CamelCase for function names (e.g. clGetPlatformIDs, clGetPlatformInfo), while this module uses underscores as word separator and often leaves out prefixes (OpenCL::platforms, $platform->info).
OpenCL often specifies fixed vector function arguments as short arrays (size_t origin[3]), while this module explicitly expects the components as separate arguments ($orig_x, $orig_y, $orig_z) in function calls.
Structures are often specified by flattening out their components as with short vectors, and returned as arrayrefs.
When enqueuing commands, the wait list is specified by adding extra arguments to the function - anywhere a $wait_events... argument is documented this can be any number of event objects.
When enqueuing commands, if the enqueue method is called in void context, no event is created. In all other contexts an event is returned by the method.
This module expects all functions to return CL_SUCCESS. If any other status is returned the function will throw an exception, so you don't normally have to to any error checking.

PERL AND OPENCL TYPES

This handy(?) table lists OpenCL types and their perl, PDL and pack/unpack format equivalents:

   OpenCL    perl   PDL       pack/unpack
   char      IV     -         c
   uchar     IV     byte      C
   short     IV     short     s
   ushort    IV     ushort    S
   int       IV     long?     l
   uint      IV     -         L
   long      IV     longlong  q
   ulong     IV     -         Q
   float     NV     float     f
   half      IV     ushort    S
   double    NV     double    d

THE OpenCL PACKAGE

$int = OpenCL::errno

The last error returned by a function - it's only valid after an error occured and before calling another OpenCL function.

$str = OpenCL::err2str $errval

Comverts an error value into a human readable string.

$str = OpenCL::enum2str $enum

Converts most enum values (inof parameter names, image format constants, object types, addressing and filter modes, command types etc.) into a human readbale string. When confronted with some random integer it can be very helpful to pass it through this function to maybe get some readable string out of it.

@platforms = OpenCL::platforms

Returns all available OpenCL::Platform objects.

http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clGetPlatformIDs.html

$ctx = OpenCL::context_from_type $properties, $type = OpenCL::DEVICE_TYPE_DEFAULT, $notify = undef

Tries to create a context from a default device and platform - never worked for me.

http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clCreateContextFromType.html

OpenCL::wait_for_events $wait_events...

Waits for all events to complete.

http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clWaitForEvents.html

THE OpenCL::Platform CLASS

@devices = $platform->devices ($type = OpenCL::DEVICE_TYPE_ALL)

Returns a list of matching OpenCL::Device objects.

$ctx = $platform->context_from_type ($properties, $type = OpenCL::DEVICE_TYPE_DEFAULT, $notify = undef)

Tries to create a context. Never worked for me, and you need devices explitly anyway.

http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clCreateContextFromType.html

$ctx = $device->context ($properties = undef, @$devices, $notify = undef)

Create a new OpenCL::Context object using the given device object(s)- a CL_CONTEXT_PLATFORM property is supplied automatically.

http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clCreateContext.html

$packed_value = $platform->info ($name)

Calls clGetPlatformInfo and returns the packed, raw value - for strings, this will be the string, for other values you probably need to use the correct unpack.

It's best to avoid this method and use one of the predefined get_* methods.

http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clGetPlatformInfo.html

$string = $platform->profile

Calls clGetPlatformInfo with CL_PLATFORM_PROFILE and returns the result(s).

$string = $platform->version

Calls clGetPlatformInfo with CL_PLATFORM_VERSION and returns the result(s).

$string = $platform->name

Calls clGetPlatformInfo with CL_PLATFORM_NAME and returns the result(s).

$string = $platform->vendor

Calls clGetPlatformInfo with CL_PLATFORM_VENDOR and returns the result(s).

$string = $platform->extensions

Calls clGetPlatformInfo with CL_PLATFORM_EXTENSIONS and returns the result(s).

THE OpenCL::Device CLASS

$packed_value = $device->info ($name)

See $platform->info for details.

http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clGetDeviceInfo.html

$device_type = $device->type

Calls clGetDeviceInfo with CL_DEVICE_TYPE and returns the result(s).

$uint = $device->vendor_id

Calls clGetDeviceInfo with CL_DEVICE_VENDOR_ID and returns the result(s).

$uint = $device->max_compute_units

Calls clGetDeviceInfo with CL_DEVICE_MAX_COMPUTE_UNITS and returns the result(s).

$uint = $device->max_work_item_dimensions

Calls clGetDeviceInfo with CL_DEVICE_MAX_WORK_ITEM_DIMENSIONS and returns the result(s).

$int = $device->max_work_group_size

Calls clGetDeviceInfo with CL_DEVICE_MAX_WORK_GROUP_SIZE and returns the result(s).

@ints = $device->max_work_item_sizes

Calls clGetDeviceInfo with CL_DEVICE_MAX_WORK_ITEM_SIZES and returns the result(s).

$uint = $device->preferred_vector_width_char

Calls clGetDeviceInfo with CL_DEVICE_PREFERRED_VECTOR_WIDTH_CHAR and returns the result(s).

$uint = $device->preferred_vector_width_short

Calls clGetDeviceInfo with CL_DEVICE_PREFERRED_VECTOR_WIDTH_SHORT and returns the result(s).

$uint = $device->preferred_vector_width_int

Calls clGetDeviceInfo with CL_DEVICE_PREFERRED_VECTOR_WIDTH_INT and returns the result(s).

$uint = $device->preferred_vector_width_long

Calls clGetDeviceInfo with CL_DEVICE_PREFERRED_VECTOR_WIDTH_LONG and returns the result(s).

$uint = $device->preferred_vector_width_float

Calls clGetDeviceInfo with CL_DEVICE_PREFERRED_VECTOR_WIDTH_FLOAT and returns the result(s).

$uint = $device->preferred_vector_width_double

Calls clGetDeviceInfo with CL_DEVICE_PREFERRED_VECTOR_WIDTH_DOUBLE and returns the result(s).

$uint = $device->max_clock_frequency

Calls clGetDeviceInfo with CL_DEVICE_MAX_CLOCK_FREQUENCY and returns the result(s).

$bitfield = $device->address_bits

Calls clGetDeviceInfo with CL_DEVICE_ADDRESS_BITS and returns the result(s).

$uint = $device->max_read_image_args

Calls clGetDeviceInfo with CL_DEVICE_MAX_READ_IMAGE_ARGS and returns the result(s).

$uint = $device->max_write_image_args

Calls clGetDeviceInfo with CL_DEVICE_MAX_WRITE_IMAGE_ARGS and returns the result(s).

$ulong = $device->max_mem_alloc_size

Calls clGetDeviceInfo with CL_DEVICE_MAX_MEM_ALLOC_SIZE and returns the result(s).

$int = $device->image2d_max_width

Calls clGetDeviceInfo with CL_DEVICE_IMAGE2D_MAX_WIDTH and returns the result(s).

$int = $device->image2d_max_height

Calls clGetDeviceInfo with CL_DEVICE_IMAGE2D_MAX_HEIGHT and returns the result(s).

$int = $device->image3d_max_width

Calls clGetDeviceInfo with CL_DEVICE_IMAGE3D_MAX_WIDTH and returns the result(s).

$int = $device->image3d_max_height

Calls clGetDeviceInfo with CL_DEVICE_IMAGE3D_MAX_HEIGHT and returns the result(s).

$int = $device->image3d_max_depth

Calls clGetDeviceInfo with CL_DEVICE_IMAGE3D_MAX_DEPTH and returns the result(s).

$uint = $device->image_support

Calls clGetDeviceInfo with CL_DEVICE_IMAGE_SUPPORT and returns the result(s).

$int = $device->max_parameter_size

Calls clGetDeviceInfo with CL_DEVICE_MAX_PARAMETER_SIZE and returns the result(s).

$uint = $device->max_samplers

Calls clGetDeviceInfo with CL_DEVICE_MAX_SAMPLERS and returns the result(s).

$uint = $device->mem_base_addr_align

Calls clGetDeviceInfo with CL_DEVICE_MEM_BASE_ADDR_ALIGN and returns the result(s).

$uint = $device->min_data_type_align_size

Calls clGetDeviceInfo with CL_DEVICE_MIN_DATA_TYPE_ALIGN_SIZE and returns the result(s).

$device_fp_config = $device->single_fp_config

Calls clGetDeviceInfo with CL_DEVICE_SINGLE_FP_CONFIG and returns the result(s).

$device_mem_cache_type = $device->global_mem_cache_type

Calls clGetDeviceInfo with CL_DEVICE_GLOBAL_MEM_CACHE_TYPE and returns the result(s).

$uint = $device->global_mem_cacheline_size

Calls clGetDeviceInfo with CL_DEVICE_GLOBAL_MEM_CACHELINE_SIZE and returns the result(s).

$ulong = $device->global_mem_cache_size

Calls clGetDeviceInfo with CL_DEVICE_GLOBAL_MEM_CACHE_SIZE and returns the result(s).

$ulong = $device->global_mem_size

Calls clGetDeviceInfo with CL_DEVICE_GLOBAL_MEM_SIZE and returns the result(s).

$ulong = $device->max_constant_buffer_size

Calls clGetDeviceInfo with CL_DEVICE_MAX_CONSTANT_BUFFER_SIZE and returns the result(s).

$uint = $device->max_constant_args

Calls clGetDeviceInfo with CL_DEVICE_MAX_CONSTANT_ARGS and returns the result(s).

$device_local_mem_type = $device->local_mem_type

Calls clGetDeviceInfo with CL_DEVICE_LOCAL_MEM_TYPE and returns the result(s).

$ulong = $device->local_mem_size

Calls clGetDeviceInfo with CL_DEVICE_LOCAL_MEM_SIZE and returns the result(s).

$boolean = $device->error_correction_support

Calls clGetDeviceInfo with CL_DEVICE_ERROR_CORRECTION_SUPPORT and returns the result(s).

$int = $device->profiling_timer_resolution

Calls clGetDeviceInfo with CL_DEVICE_PROFILING_TIMER_RESOLUTION and returns the result(s).

$boolean = $device->endian_little

Calls clGetDeviceInfo with CL_DEVICE_ENDIAN_LITTLE and returns the result(s).

$boolean = $device->available

Calls clGetDeviceInfo with CL_DEVICE_AVAILABLE and returns the result(s).

$boolean = $device->compiler_available

Calls clGetDeviceInfo with CL_DEVICE_COMPILER_AVAILABLE and returns the result(s).

$device_exec_capabilities = $device->execution_capabilities

Calls clGetDeviceInfo with CL_DEVICE_EXECUTION_CAPABILITIES and returns the result(s).

$command_queue_properties = $device->properties

Calls clGetDeviceInfo with CL_DEVICE_QUEUE_PROPERTIES and returns the result(s).

$ = $device->platform

Calls clGetDeviceInfo with CL_DEVICE_PLATFORM and returns the result(s).

$string = $device->name

Calls clGetDeviceInfo with CL_DEVICE_NAME and returns the result(s).

$string = $device->vendor

Calls clGetDeviceInfo with CL_DEVICE_VENDOR and returns the result(s).

$string = $device->driver_version

Calls clGetDeviceInfo with CL_DRIVER_VERSION and returns the result(s).

$string = $device->profile

Calls clGetDeviceInfo with CL_DEVICE_PROFILE and returns the result(s).

$string = $device->version

Calls clGetDeviceInfo with CL_DEVICE_VERSION and returns the result(s).

$string = $device->extensions

Calls clGetDeviceInfo with CL_DEVICE_EXTENSIONS and returns the result(s).

$uint = $device->preferred_vector_width_half

Calls clGetDeviceInfo with CL_DEVICE_PREFERRED_VECTOR_WIDTH_HALF and returns the result(s).

$uint = $device->native_vector_width_char

Calls clGetDeviceInfo with CL_DEVICE_NATIVE_VECTOR_WIDTH_CHAR and returns the result(s).

$uint = $device->native_vector_width_short

Calls clGetDeviceInfo with CL_DEVICE_NATIVE_VECTOR_WIDTH_SHORT and returns the result(s).

$uint = $device->native_vector_width_int

Calls clGetDeviceInfo with CL_DEVICE_NATIVE_VECTOR_WIDTH_INT and returns the result(s).

$uint = $device->native_vector_width_long

Calls clGetDeviceInfo with CL_DEVICE_NATIVE_VECTOR_WIDTH_LONG and returns the result(s).

$uint = $device->native_vector_width_float

Calls clGetDeviceInfo with CL_DEVICE_NATIVE_VECTOR_WIDTH_FLOAT and returns the result(s).

$uint = $device->native_vector_width_double

Calls clGetDeviceInfo with CL_DEVICE_NATIVE_VECTOR_WIDTH_DOUBLE and returns the result(s).

$uint = $device->native_vector_width_half

Calls clGetDeviceInfo with CL_DEVICE_NATIVE_VECTOR_WIDTH_HALF and returns the result(s).

$device_fp_config = $device->double_fp_config

Calls clGetDeviceInfo with CL_DEVICE_DOUBLE_FP_CONFIG and returns the result(s).

$device_fp_config = $device->half_fp_config

Calls clGetDeviceInfo with CL_DEVICE_HALF_FP_CONFIG and returns the result(s).

$boolean = $device->host_unified_memory

Calls clGetDeviceInfo with CL_DEVICE_HOST_UNIFIED_MEMORY and returns the result(s).

$device = $device->parent_device_ext

Calls clGetDeviceInfo with CL_DEVICE_PARENT_DEVICE_EXT and returns the result(s).

@device_partition_property_exts = $device->partition_types_ext

Calls clGetDeviceInfo with CL_DEVICE_PARTITION_TYPES_EXT and returns the result(s).

@device_partition_property_exts = $device->affinity_domains_ext

Calls clGetDeviceInfo with CL_DEVICE_AFFINITY_DOMAINS_EXT and returns the result(s).

$uint = $device->reference_count_ext

Calls clGetDeviceInfo with CL_DEVICE_REFERENCE_COUNT_EXT and returns the result(s).

@device_partition_property_exts = $device->partition_style_ext

Calls clGetDeviceInfo with CL_DEVICE_PARTITION_STYLE_EXT and returns the result(s).

THE OpenCL::Context CLASS

$queue = $ctx->queue ($device, $properties)

Create a new OpenCL::Queue object from the context and the given device.

http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clCreateCommandQueue.html

$ev = $ctx->user_event

Creates a new OpenCL::UserEvent object.

http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clCreateUserEvent.html

$buf = $ctx->buffer ($flags, $len)

Creates a new OpenCL::Buffer object with the given flags and octet-size.

http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clCreateBuffer.html

$buf = $ctx->buffer_sv ($flags, $data)

Creates a new OpenCL::Buffer object and initialise it with the given data values.

$img = $ctx->image2d ($flags, $channel_order, $channel_type, $width, $height, $row_pitch = 0, $data = undef)

Creates a new OpenCL::Image2D object and optionally initialises it with the given data values.

http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clCreateImage2D.html

$img = $ctx->image3d ($flags, $channel_order, $channel_type, $width, $height, $depth, $row_pitch = 0, $slice_pitch = 0, $data = undef)

Creates a new OpenCL::Image3D object and optionally initialises it with the given data values.

http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clCreateImage3D.html

@formats = $ctx->supported_image_formats ($flags, $image_type)

Returns a list of matching image formats - each format is an arrayref with two values, $channel_order and $channel_type, in it.

http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clGetSupportedImageFormats.html

$sampler = $ctx->sampler ($normalized_coords, $addressing_mode, $filter_mode)

Creates a new OpenCL::Sampler object.

http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clCreateSampler.html

$program = $ctx->program_with_source ($string)

Creates a new OpenCL::Program object from the given source code.

http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clCreateProgramWithSource.html

$packed_value = $ctx->info ($name)

See $platform->info for details.

http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clGetContextInfo.html

$uint = $context->reference_count

Calls clGetContextInfo with CL_CONTEXT_REFERENCE_COUNT and returns the result(s).

@devices = $context->devices

Calls clGetContextInfo with CL_CONTEXT_DEVICES and returns the result(s).

@property_ints = $context->properties

Calls clGetContextInfo with CL_CONTEXT_PROPERTIES and returns the result(s).

$uint = $context->num_devices

Calls clGetContextInfo with CL_CONTEXT_NUM_DEVICES and returns the result(s).

THE OpenCL::Queue CLASS

An OpenCL::Queue represents an execution queue for OpenCL. You execute requests by calling their respective enqueue_xxx method and waitinf for it to complete in some way.

All the enqueue methods return an event object that can be used to wait for completion, unless the method is called in void context, in which case no event object is created.

They also allow you to specify any number of other event objects that this request has to wait for before it starts executing, by simply passing the event objects as extra parameters to the enqueue methods.

Queues execute in-order by default, without any parallelism, so in most cases (i.e. you use only one queue) it's not necessary to wait for or create event objects.

$ev = $queue->enqueue_read_buffer ($buffer, $blocking, $offset, $len, $data, $wait_events...)

Reads data from buffer into the given string.

http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clEnqueueReadBuffer.html

$ev = $queue->enqueue_write_buffer ($buffer, $blocking, $offset, $data, $wait_events...)

Writes data to buffer from the given string.

http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clEnqueueWriteBuffer.html

$ev = $queue->enqueue_copy_buffer ($src, $dst, $src_offset, $dst_offset, $len, $wait_events...)

http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clEnqueueCopyBuffer.html

$ev = $queue->enqueue_read_image ($src, $blocking, $x, $y, $z, $width, $height, $depth, $row_pitch, $slice_pitch, $data, $wait_events...)

http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clEnqueueReadImage.html

$ev = $queue->enqueue_write_image ($src, $blocking, $x, $y, $z, $width, $height, $depth, $row_pitch, $slice_pitch, $data, $wait_events...)

http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clEnqueueWriteImage.html

$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...)

Yeah.

http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clEnqueueCopyBufferRect.html

$ev = $queue->enqueue_copy_buffer_to_image ($src_buffer, $dst_image, $src_offset, $dst_x, $dst_y, $dst_z, $width, $height, $depth, $wait_events...)

http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clEnqueueCopyBufferToImage.html.

$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...)

http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clEnqueueCopyImage.html

$ev = $queue->enqueue_copy_image_to_buffer ($src_image, $dst_image, $src_x, $src_y, $src_z, $width, $height, $depth, $dst_offset, $wait_events...)

http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clEnqueueCopyImageToBuffer.html

$ev = $queue->enqueue_task ($kernel, $wait_events...)

http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clEnqueueTask.html

$ev = $queue->enqueue_nd_range_kernel ($kernel, @$global_work_offset, @$global_work_size, @$local_work_size, $wait_events...)

Enqueues a kernel execution.

@$global_work_size must be specified as a reference to an array of integers specifying the work sizes (element counts).

@$global_work_offset must be either undef (in which case all offsets are 0), or a reference to an array of work offsets, with the same number of elements as @$global_work_size.

@$local_work_size must be either undef (in which case the implementation is supposed to choose good local work sizes), or a reference to an array of local work sizes, with the same number of elements as @$global_work_size.

http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clEnqueueNDRangeKernel.html

$ev = $queue->enqueue_marker

http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clEnqueueMarker.html

$ev = $queue->enqueue_wait_for_events ($wait_events...)

http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clEnqueueWaitForEvents.html

$queue->enqueue_barrier

http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clEnqueueBarrier.html

$queue->flush

http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clFlush.html

$queue->finish

http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clFinish.html

$packed_value = $queue->info ($name)

See $platform->info for details.

http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clGetCommandQueueInfo.html

$ctx = $command_queue->context

Calls clGetCommandQueueInfo with CL_QUEUE_CONTEXT and returns the result(s).

$device = $command_queue->device

Calls clGetCommandQueueInfo with CL_QUEUE_DEVICE and returns the result(s).

$uint = $command_queue->reference_count

Calls clGetCommandQueueInfo with CL_QUEUE_REFERENCE_COUNT and returns the result(s).

$command_queue_properties = $command_queue->properties

Calls clGetCommandQueueInfo with CL_QUEUE_PROPERTIES and returns the result(s).

THE OpenCL::Memory CLASS

This the superclass of all memory objects - OpenCL::Buffer, OpenCL::Image, OpenCL::Image2D and OpenCL::Image3D.

$packed_value = $memory->info ($name)

See $platform->info for details.

http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clGetMemObjectInfo.html

$mem_object_type = $mem->type

Calls clGetMemObjectInfo with CL_MEM_TYPE and returns the result(s).

$mem_flags = $mem->flags

Calls clGetMemObjectInfo with CL_MEM_FLAGS and returns the result(s).

$int = $mem->size

Calls clGetMemObjectInfo with CL_MEM_SIZE and returns the result(s).

$ptr_value = $mem->host_ptr

Calls clGetMemObjectInfo with CL_MEM_HOST_PTR and returns the result(s).

$uint = $mem->map_count

Calls clGetMemObjectInfo with CL_MEM_MAP_COUNT and returns the result(s).

$uint = $mem->reference_count

Calls clGetMemObjectInfo with CL_MEM_REFERENCE_COUNT and returns the result(s).

$ctx = $mem->context

Calls clGetMemObjectInfo with CL_MEM_CONTEXT and returns the result(s).

$mem = $mem->associated_memobject

Calls clGetMemObjectInfo with CL_MEM_ASSOCIATED_MEMOBJECT and returns the result(s).

$int = $mem->offset

Calls clGetMemObjectInfo with CL_MEM_OFFSET and returns the result(s).

THE OpenCL::Image CLASS

This is the superclass of all image objects - OpenCL::Image2D and OpenCL::Image3D.

$packed_value = $ev->image_info ($name)

See $platform->info for details.

The reason this method is not called info is that there already is an ->info method inherited from OpenCL::Memory.

http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clGetImageInfo.html

$int = $image->element_size

Calls clGetImageInfo with CL_IMAGE_ELEMENT_SIZE and returns the result(s).

$int = $image->row_pitch

Calls clGetImageInfo with CL_IMAGE_ROW_PITCH and returns the result(s).

$int = $image->slice_pitch

Calls clGetImageInfo with CL_IMAGE_SLICE_PITCH and returns the result(s).

$int = $image->width

Calls clGetImageInfo with CL_IMAGE_WIDTH and returns the result(s).

$int = $image->height

Calls clGetImageInfo with CL_IMAGE_HEIGHT and returns the result(s).

$int = $image->depth

Calls clGetImageInfo with CL_IMAGE_DEPTH and returns the result(s).

THE OpenCL::Sampler CLASS

$packed_value = $sampler->info ($name)

See $platform->info for details.

http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clGetSamplerInfo.html

$uint = $sampler->reference_count

Calls clGetSamplerInfo with CL_SAMPLER_REFERENCE_COUNT and returns the result(s).

$ctx = $sampler->context

Calls clGetSamplerInfo with CL_SAMPLER_CONTEXT and returns the result(s).

$addressing_mode = $sampler->normalized_coords

Calls clGetSamplerInfo with CL_SAMPLER_NORMALIZED_COORDS and returns the result(s).

$filter_mode = $sampler->addressing_mode

Calls clGetSamplerInfo with CL_SAMPLER_ADDRESSING_MODE and returns the result(s).

$boolean = $sampler->filter_mode

Calls clGetSamplerInfo with CL_SAMPLER_FILTER_MODE and returns the result(s).

THE OpenCL::Program CLASS

$program->build ($device, $options = "")

Tries to build the program with the givne options.

http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clBuildProgram.html

$packed_value = $program->build_info ($device, $name)

Similar to $platform->info, but returns build info for a previous build attempt for the given device.

http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clGetBuildInfo.html

$kernel = $program->kernel ($function_name)

Creates an OpenCL::Kernel object out of the named __kernel function in the program.

http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clCreateKernel.html

$build_status = $program->build_status ($device)

Calls clGetProgramBuildInfo with CL_PROGRAM_BUILD_STATUS and returns the result(s).

$string = $program->build_options ($device)

Calls clGetProgramBuildInfo with CL_PROGRAM_BUILD_OPTIONS and returns the result(s).

$string = $program->build_log ($device)

Calls clGetProgramBuildInfo with CL_PROGRAM_BUILD_LOG and returns the result(s).

$packed_value = $program->info ($name)

See $platform->info for details.

http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clGetProgramInfo.html

$uint = $program->reference_count

Calls clGetProgramInfo with CL_PROGRAM_REFERENCE_COUNT and returns the result(s).

$ctx = $program->context

Calls clGetProgramInfo with CL_PROGRAM_CONTEXT and returns the result(s).

$uint = $program->num_devices

Calls clGetProgramInfo with CL_PROGRAM_NUM_DEVICES and returns the result(s).

@devices = $program->devices

Calls clGetProgramInfo with CL_PROGRAM_DEVICES and returns the result(s).

$string = $program->source

Calls clGetProgramInfo with CL_PROGRAM_SOURCE and returns the result(s).

@ints = $program->binary_sizes

Calls clGetProgramInfo with CL_PROGRAM_BINARY_SIZES and returns the result(s).

THE OpenCL::Kernel CLASS

$packed_value = $kernel->info ($name)

See $platform->info for details.

http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clGetKernelInfo.html

$string = $kernel->function_name

Calls clGetKernelInfo with CL_KERNEL_FUNCTION_NAME and returns the result(s).

$uint = $kernel->num_args

Calls clGetKernelInfo with CL_KERNEL_NUM_ARGS and returns the result(s).

$uint = $kernel->reference_count

Calls clGetKernelInfo with CL_KERNEL_REFERENCE_COUNT and returns the result(s).

$ctx = $kernel->context

Calls clGetKernelInfo with CL_KERNEL_CONTEXT and returns the result(s).

$program = $kernel->program

Calls clGetKernelInfo with CL_KERNEL_PROGRAM and returns the result(s).

$packed_value = $kernel->work_group_info ($device, $name)

See $platform->info for details.

The reason this method is not called info is that there already is an ->info method.

http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clGetKernelWorkGroupInfo.html

$int = $kernel->work_group_size ($device)

Calls clGetKernelWorkGroupInfo with CL_KERNEL_WORK_GROUP_SIZE and returns the result(s).

@ints = $kernel->compile_work_group_size ($device)

Calls clGetKernelWorkGroupInfo with CL_KERNEL_COMPILE_WORK_GROUP_SIZE and returns the result(s).

$ulong = $kernel->local_mem_size ($device)

Calls clGetKernelWorkGroupInfo with CL_KERNEL_LOCAL_MEM_SIZE and returns the result(s).

$int = $kernel->preferred_work_group_size_multiple ($device)

Calls clGetKernelWorkGroupInfo with CL_KERNEL_PREFERRED_WORK_GROUP_SIZE_MULTIPLE and returns the result(s).

$ulong = $kernel->private_mem_size ($device)

Calls clGetKernelWorkGroupInfo with CL_KERNEL_PRIVATE_MEM_SIZE and returns the result(s).

$kernel->set_TYPE ($index, $value)

This is a family of methods to set the kernel argument with the number $index to the give $value.

TYPE is one of char, uchar, short, ushort, int, uint, long, ulong, half, float, double, memory, buffer, image2d, image3d, sampler or event.

Chars and integers (including the half type) are specified as integers, float and double as floating point values, memory/buffer/image2d/image3d must be an object of that type or undef, and sampler and event must be objects of that type.

http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clSetKernelArg.html

THE OpenCL::Event CLASS

This is the superclass for all event objects (including OpenCL::UserEvent objects).

$ev->wait

Waits for the event to complete.

http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clWaitForEvents.html

$packed_value = $ev->info ($name)

See $platform->info for details.

http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clGetEventInfo.html

$queue = $event->command_queue

Calls clGetEventInfo with CL_EVENT_COMMAND_QUEUE and returns the result(s).

$command_type = $event->command_type

Calls clGetEventInfo with CL_EVENT_COMMAND_TYPE and returns the result(s).

$uint = $event->reference_count

Calls clGetEventInfo with CL_EVENT_REFERENCE_COUNT and returns the result(s).

$uint = $event->command_execution_status

Calls clGetEventInfo with CL_EVENT_COMMAND_EXECUTION_STATUS and returns the result(s).

$ctx = $event->context

Calls clGetEventInfo with CL_EVENT_CONTEXT and returns the result(s).

$packed_value = $ev->profiling_info ($name)

See $platform->info for details.

The reason this method is not called info is that there already is an ->info method.

http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clGetProfilingInfo.html

$ulong = $event->profiling_command_queued

Calls clGetEventProfilingInfo with CL_PROFILING_COMMAND_QUEUED and returns the result(s).

$ulong = $event->profiling_command_submit

Calls clGetEventProfilingInfo with CL_PROFILING_COMMAND_SUBMIT and returns the result(s).

$ulong = $event->profiling_command_start

Calls clGetEventProfilingInfo with CL_PROFILING_COMMAND_START and returns the result(s).

$ulong = $event->profiling_command_end

Calls clGetEventProfilingInfo with CL_PROFILING_COMMAND_END and returns the result(s).

THE OpenCL::UserEvent CLASS

This is a subclass of OpenCL::Event.

$ev->set_status ($execution_status): http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clSetUserEventStatus.html

AUTHOR

 Marc Lehmann <schmorp@schmorp.de>
 http://home.schmorp.de/

To install OpenCL, copy and paste the appropriate command in to your terminal.

cpanm

cpanm OpenCL

CPAN shell

perl -MCPAN -e shell
install OpenCL

For more information on module installation, please visit the detailed CPAN module installation guide.

	Global
`s`	Focus search bar
`?`	Bring up this help dialog

	GitHub
`g` `p`	Go to pull requests
`g` `i`	go to github issues (only if github is preferred repository)

	POD
`g` `a`	Go to author
`g` `c`	Go to changes
`g` `i`	Go to issues
`g` `d`	Go to dist
`g` `r`	Go to repository/SCM
`g` `s`	Go to source
`g` `b`	Go to file browse

	Search terms
module: (e.g. module:Plugin)
distribution: (e.g. distribution:Dancer auth)
author: (e.g. author:SONGMU Redis)
version: (e.g. version:1.00)

NAME

SYNOPSIS

DESCRIPTION

OpenCL FROM 10000 FEET HEIGHT

HELPFUL RESOURCES

BASIC WORKFLOW

EXAMPLES

Enumerate all devices and get contexts for them.

Get a useful context and a command queue.

Print all supported image formats of a context.

Create a buffer with some predefined data, read it back synchronously, then asynchronously.

Create and build a program, then create a kernel out of one of its functions.

Create some input and output float buffers, then call the 'squareit' kernel on them.

The same enqueue operations as before, but assuming an out-of-order queue, showing off barriers.

The same enqueue operations as before, but assuming an out-of-order queue, showing off event objects and wait lists.

DOCUMENTATION

BASIC CONVENTIONS

PERL AND OPENCL TYPES

THE OpenCL PACKAGE

THE OpenCL::Platform CLASS

THE OpenCL::Device CLASS

THE OpenCL::Context CLASS

THE OpenCL::Queue CLASS

THE OpenCL::Memory CLASS

THE OpenCL::Image CLASS

THE OpenCL::Sampler CLASS

THE OpenCL::Program CLASS

THE OpenCL::Kernel CLASS

THE OpenCL::Event CLASS

THE OpenCL::UserEvent CLASS

AUTHOR

Module Install Instructions