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->name;
printf "extensions: %s\n", $platform->extensions;
for my $device ($platform->devices) {
printf "+ device: %s\n", $device->name;
my $ctx = $platform->context (undef, [$device]);
# 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_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;
Use the OpenGL module to share a texture between OpenCL and OpenGL and draw some julia set tunnel effect.
This is quite a long example to get you going.
use OpenGL ":all";
use OpenCL;
# open a window and create a gl texture
OpenGL::glpOpenWindow width => 256, height => 256;
my $texid = glGenTextures_p 1;
glBindTexture GL_TEXTURE_2D, $texid;
glTexImage2D_c GL_TEXTURE_2D, 0, GL_RGBA8, 256, 256, 0, GL_RGBA, GL_UNSIGNED_BYTE, 0;
# find and use the first opencl device that let's us get a shared opengl context
my $platform;
my $dev;
my $ctx;
for (OpenCL::platforms) {
$platform = $_;
for ($platform->devices) {
$dev = $_;
$ctx = $platform->context ([OpenCL::GLX_DISPLAY_KHR, undef, OpenCL::GL_CONTEXT_KHR, undef], [$dev])
and last;
}
}
$ctx
or die "cannot find suitable OpenCL device\n";
my $queue = $ctx->queue ($dev);
# now attach an opencl image2d object to the opengl texture
my $tex = $ctx->gl_texture2d (OpenCL::MEM_WRITE_ONLY, GL_TEXTURE_2D, 0, $texid);
# now the boring opencl code
my $src = <<EOF;
kernel void
juliatunnel (write_only image2d_t img, float time)
{
float2 p = (float2)(get_global_id (0), get_global_id (1)) / 256.f * 2.f - 1.f;
float2 m = (float2)(1.f, p.y) / fabs (p.x);
m.x = fabs (fmod (m.x + time * 0.05f, 4.f)) - 2.f;
float2 z = m;
float2 c = (float2)(sin (time * 0.05005), cos (time * 0.06001));
for (int i = 0; i < 25 && dot (z, z) < 4.f; ++i)
z = (float2)(z.x * z.x - z.y * z.y, 2.f * z.x * z.y) + c;
float3 colour = (float3)(z.x, z.y, z.x * z.y);
write_imagef (img, (int2)(get_global_id (0), get_global_id (1)), (float4)(colour * p.x * p.x, 1.));
}
EOF
my $prog = $ctx->program_with_source ($src);
eval { $prog->build ($dev); 1 }
or die $prog->build_log ($dev);
my $kernel = $prog->kernel ("juliatunnel");
# program compiled, kernel ready, now draw and loop
for (my $time; ; ++$time) {
# acquire objects from opengl
$queue->enqueue_acquire_gl_objects ([$tex]);
# configure and run our kernel
$kernel->set_image2d (0, $tex);
$kernel->set_float (1, $time);
$queue->enqueue_nd_range_kernel ($kernel, undef, [256, 256], undef);
# release objects to opengl again
$queue->enqueue_release_gl_objects ([$tex]);
# wait
$queue->flush;
# now draw the texture, the defaults should be all right
glTexParameterf GL_TEXTURE_2D, GL_TEXTURE_MIN_FILTER, GL_NEAREST;
glEnable GL_TEXTURE_2D;
glBegin GL_QUADS;
glTexCoord2f 0, 1; glVertex3i -1, -1, -1;
glTexCoord2f 0, 0; glVertex3i 1, -1, -1;
glTexCoord2f 1, 0; glVertex3i 1, 1, -1;
glTexCoord2f 1, 1; glVertex3i -1, 1, -1;
glEnd;
glXSwapBuffers;
select undef, undef, undef, 1/60;
}
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
GLX SUPPORT
Due to the sad state that OpenGL support is in in Perl (mostly the OpenGL module, which has little to no documentation and has little to no support for glX), this module, as a special extension, treats context creation properties OpenCL::GLX_DISPLAY_KHR and OpenCL::GL_CONTEXT_KHR specially: If either or both of these are undef, then the OpenCL module tries to dynamically resolve glXGetCurrentDisplay and glXGetCurrentContext, call these functions and use their return values instead.
For this to work, the OpenGL library must be loaded, a GLX context must have been created and be made current, and dlsym must be available and capable of finding the function via RTLD_DEFAULT.
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 (of parameter names, image format constants, object types, addressing and filter modes, command types etc.) into a human readable 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 explicitly anyway.
http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clCreateContextFromType.html
- $ctx = $platform->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
clGetPlatformInfoand returns the packed, raw value - for strings, this will be the string (possibly including terminating \0), for other values you probably need to use the correctunpack.It's best to avoid this method and use one of the following convenience wrappers.
http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clGetPlatformInfo.html
- $string = $platform->profile
-
Calls
clGetPlatformInfowithCL_PLATFORM_PROFILEand returns the result. - $string = $platform->version
-
Calls
clGetPlatformInfowithCL_PLATFORM_VERSIONand returns the result. - $string = $platform->name
-
Calls
clGetPlatformInfowithCL_PLATFORM_NAMEand returns the result. - $string = $platform->vendor
-
Calls
clGetPlatformInfowithCL_PLATFORM_VENDORand returns the result. - $string = $platform->extensions
-
Calls
clGetPlatformInfowithCL_PLATFORM_EXTENSIONSand returns the result.
THE OpenCL::Device CLASS
- $packed_value = $device->info ($name)
-
See
$platform->infofor details.http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clGetDeviceInfo.html
- $device_type = $device->type
-
Calls
clGetDeviceInfowithCL_DEVICE_TYPEand returns the result. - $uint = $device->vendor_id
-
Calls
clGetDeviceInfowithCL_DEVICE_VENDOR_IDand returns the result. - $uint = $device->max_compute_units
-
Calls
clGetDeviceInfowithCL_DEVICE_MAX_COMPUTE_UNITSand returns the result. - $uint = $device->max_work_item_dimensions
-
Calls
clGetDeviceInfowithCL_DEVICE_MAX_WORK_ITEM_DIMENSIONSand returns the result. - $int = $device->max_work_group_size
-
Calls
clGetDeviceInfowithCL_DEVICE_MAX_WORK_GROUP_SIZEand returns the result. - @ints = $device->max_work_item_sizes
-
Calls
clGetDeviceInfowithCL_DEVICE_MAX_WORK_ITEM_SIZESand returns the result. - $uint = $device->preferred_vector_width_char
-
Calls
clGetDeviceInfowithCL_DEVICE_PREFERRED_VECTOR_WIDTH_CHARand returns the result. - $uint = $device->preferred_vector_width_short
-
Calls
clGetDeviceInfowithCL_DEVICE_PREFERRED_VECTOR_WIDTH_SHORTand returns the result. - $uint = $device->preferred_vector_width_int
-
Calls
clGetDeviceInfowithCL_DEVICE_PREFERRED_VECTOR_WIDTH_INTand returns the result. - $uint = $device->preferred_vector_width_long
-
Calls
clGetDeviceInfowithCL_DEVICE_PREFERRED_VECTOR_WIDTH_LONGand returns the result. - $uint = $device->preferred_vector_width_float
-
Calls
clGetDeviceInfowithCL_DEVICE_PREFERRED_VECTOR_WIDTH_FLOATand returns the result. - $uint = $device->preferred_vector_width_double
-
Calls
clGetDeviceInfowithCL_DEVICE_PREFERRED_VECTOR_WIDTH_DOUBLEand returns the result. - $uint = $device->max_clock_frequency
-
Calls
clGetDeviceInfowithCL_DEVICE_MAX_CLOCK_FREQUENCYand returns the result. - $bitfield = $device->address_bits
-
Calls
clGetDeviceInfowithCL_DEVICE_ADDRESS_BITSand returns the result. - $uint = $device->max_read_image_args
-
Calls
clGetDeviceInfowithCL_DEVICE_MAX_READ_IMAGE_ARGSand returns the result. - $uint = $device->max_write_image_args
-
Calls
clGetDeviceInfowithCL_DEVICE_MAX_WRITE_IMAGE_ARGSand returns the result. - $ulong = $device->max_mem_alloc_size
-
Calls
clGetDeviceInfowithCL_DEVICE_MAX_MEM_ALLOC_SIZEand returns the result. - $int = $device->image2d_max_width
-
Calls
clGetDeviceInfowithCL_DEVICE_IMAGE2D_MAX_WIDTHand returns the result. - $int = $device->image2d_max_height
-
Calls
clGetDeviceInfowithCL_DEVICE_IMAGE2D_MAX_HEIGHTand returns the result. - $int = $device->image3d_max_width
-
Calls
clGetDeviceInfowithCL_DEVICE_IMAGE3D_MAX_WIDTHand returns the result. - $int = $device->image3d_max_height
-
Calls
clGetDeviceInfowithCL_DEVICE_IMAGE3D_MAX_HEIGHTand returns the result. - $int = $device->image3d_max_depth
-
Calls
clGetDeviceInfowithCL_DEVICE_IMAGE3D_MAX_DEPTHand returns the result. - $uint = $device->image_support
-
Calls
clGetDeviceInfowithCL_DEVICE_IMAGE_SUPPORTand returns the result. - $int = $device->max_parameter_size
-
Calls
clGetDeviceInfowithCL_DEVICE_MAX_PARAMETER_SIZEand returns the result. - $uint = $device->max_samplers
-
Calls
clGetDeviceInfowithCL_DEVICE_MAX_SAMPLERSand returns the result. - $uint = $device->mem_base_addr_align
-
Calls
clGetDeviceInfowithCL_DEVICE_MEM_BASE_ADDR_ALIGNand returns the result. - $uint = $device->min_data_type_align_size
-
Calls
clGetDeviceInfowithCL_DEVICE_MIN_DATA_TYPE_ALIGN_SIZEand returns the result. - $device_fp_config = $device->single_fp_config
-
Calls
clGetDeviceInfowithCL_DEVICE_SINGLE_FP_CONFIGand returns the result. - $device_mem_cache_type = $device->global_mem_cache_type
-
Calls
clGetDeviceInfowithCL_DEVICE_GLOBAL_MEM_CACHE_TYPEand returns the result. - $uint = $device->global_mem_cacheline_size
-
Calls
clGetDeviceInfowithCL_DEVICE_GLOBAL_MEM_CACHELINE_SIZEand returns the result. - $ulong = $device->global_mem_cache_size
-
Calls
clGetDeviceInfowithCL_DEVICE_GLOBAL_MEM_CACHE_SIZEand returns the result. - $ulong = $device->global_mem_size
-
Calls
clGetDeviceInfowithCL_DEVICE_GLOBAL_MEM_SIZEand returns the result. - $ulong = $device->max_constant_buffer_size
-
Calls
clGetDeviceInfowithCL_DEVICE_MAX_CONSTANT_BUFFER_SIZEand returns the result. - $uint = $device->max_constant_args
-
Calls
clGetDeviceInfowithCL_DEVICE_MAX_CONSTANT_ARGSand returns the result. - $device_local_mem_type = $device->local_mem_type
-
Calls
clGetDeviceInfowithCL_DEVICE_LOCAL_MEM_TYPEand returns the result. - $ulong = $device->local_mem_size
-
Calls
clGetDeviceInfowithCL_DEVICE_LOCAL_MEM_SIZEand returns the result. - $boolean = $device->error_correction_support
-
Calls
clGetDeviceInfowithCL_DEVICE_ERROR_CORRECTION_SUPPORTand returns the result. - $int = $device->profiling_timer_resolution
-
Calls
clGetDeviceInfowithCL_DEVICE_PROFILING_TIMER_RESOLUTIONand returns the result. - $boolean = $device->endian_little
-
Calls
clGetDeviceInfowithCL_DEVICE_ENDIAN_LITTLEand returns the result. - $boolean = $device->available
-
Calls
clGetDeviceInfowithCL_DEVICE_AVAILABLEand returns the result. - $boolean = $device->compiler_available
-
Calls
clGetDeviceInfowithCL_DEVICE_COMPILER_AVAILABLEand returns the result. - $device_exec_capabilities = $device->execution_capabilities
-
Calls
clGetDeviceInfowithCL_DEVICE_EXECUTION_CAPABILITIESand returns the result. - $command_queue_properties = $device->properties
-
Calls
clGetDeviceInfowithCL_DEVICE_QUEUE_PROPERTIESand returns the result. - $ = $device->platform
-
Calls
clGetDeviceInfowithCL_DEVICE_PLATFORMand returns the result. - $string = $device->name
-
Calls
clGetDeviceInfowithCL_DEVICE_NAMEand returns the result. - $string = $device->vendor
-
Calls
clGetDeviceInfowithCL_DEVICE_VENDORand returns the result. - $string = $device->driver_version
-
Calls
clGetDeviceInfowithCL_DRIVER_VERSIONand returns the result. - $string = $device->profile
-
Calls
clGetDeviceInfowithCL_DEVICE_PROFILEand returns the result. - $string = $device->version
-
Calls
clGetDeviceInfowithCL_DEVICE_VERSIONand returns the result. - $string = $device->extensions
-
Calls
clGetDeviceInfowithCL_DEVICE_EXTENSIONSand returns the result. - $uint = $device->preferred_vector_width_half
-
Calls
clGetDeviceInfowithCL_DEVICE_PREFERRED_VECTOR_WIDTH_HALFand returns the result. - $uint = $device->native_vector_width_char
-
Calls
clGetDeviceInfowithCL_DEVICE_NATIVE_VECTOR_WIDTH_CHARand returns the result. - $uint = $device->native_vector_width_short
-
Calls
clGetDeviceInfowithCL_DEVICE_NATIVE_VECTOR_WIDTH_SHORTand returns the result. - $uint = $device->native_vector_width_int
-
Calls
clGetDeviceInfowithCL_DEVICE_NATIVE_VECTOR_WIDTH_INTand returns the result. - $uint = $device->native_vector_width_long
-
Calls
clGetDeviceInfowithCL_DEVICE_NATIVE_VECTOR_WIDTH_LONGand returns the result. - $uint = $device->native_vector_width_float
-
Calls
clGetDeviceInfowithCL_DEVICE_NATIVE_VECTOR_WIDTH_FLOATand returns the result. - $uint = $device->native_vector_width_double
-
Calls
clGetDeviceInfowithCL_DEVICE_NATIVE_VECTOR_WIDTH_DOUBLEand returns the result. - $uint = $device->native_vector_width_half
-
Calls
clGetDeviceInfowithCL_DEVICE_NATIVE_VECTOR_WIDTH_HALFand returns the result. - $device_fp_config = $device->double_fp_config
-
Calls
clGetDeviceInfowithCL_DEVICE_DOUBLE_FP_CONFIGand returns the result. - $device_fp_config = $device->half_fp_config
-
Calls
clGetDeviceInfowithCL_DEVICE_HALF_FP_CONFIGand returns the result. - $boolean = $device->host_unified_memory
-
Calls
clGetDeviceInfowithCL_DEVICE_HOST_UNIFIED_MEMORYand returns the result. - $device = $device->parent_device_ext
-
Calls
clGetDeviceInfowithCL_DEVICE_PARENT_DEVICE_EXTand returns the result. - @device_partition_property_exts = $device->partition_types_ext
-
Calls
clGetDeviceInfowithCL_DEVICE_PARTITION_TYPES_EXTand returns the result. - @device_partition_property_exts = $device->affinity_domains_ext
-
Calls
clGetDeviceInfowithCL_DEVICE_AFFINITY_DOMAINS_EXTand returns the result. - $uint = $device->reference_count_ext
-
Calls
clGetDeviceInfowithCL_DEVICE_REFERENCE_COUNT_EXTand returns the result. - @device_partition_property_exts = $device->partition_style_ext
-
Calls
clGetDeviceInfowithCL_DEVICE_PARTITION_STYLE_EXTand returns the result.
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 (actually OpenCL::BufferObj) 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 (actually OpenCL::BufferObj) 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
- $buffer = $ctx->gl_buffer ($flags, $bufobj)
-
Creates a new OpenCL::Buffer (actually OpenCL::BufferObj) object that refers to the given OpenGL buffer object.
http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clCreateFromGLBuffer.html
- $ctx->gl_texture2d ($flags, $target, $miplevel, $texture)
-
Creates a new OpenCL::Image2D object that refers to the given OpenGL 2D texture object.
http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clCreateFromGLTexture2D.html
- $ctx->gl_texture3d ($flags, $target, $miplevel, $texture)
-
Creates a new OpenCL::Image3D object that refers to the given OpenGL 3D texture object.
http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clCreateFromGLTexture3D.html
- $ctx->gl_renderbuffer ($flags, $renderbuffer)
-
Creates a new OpenCL::Image2D object that refers to the given OpenGL render buffer.
http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clCreateFromGLRenderbuffer.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->infofor details.http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clGetContextInfo.html
- $uint = $context->reference_count
-
Calls
clGetContextInfowithCL_CONTEXT_REFERENCE_COUNTand returns the result. - @devices = $context->devices
-
Calls
clGetContextInfowithCL_CONTEXT_DEVICESand returns the result. - @property_ints = $context->properties
-
Calls
clGetContextInfowithCL_CONTEXT_PROPERTIESand returns the result. - $uint = $context->num_devices
-
Calls
clGetContextInfowithCL_CONTEXT_NUM_DEVICESand returns the result.
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_buffer_rect (OpenCL::Memory buf, cl_bool blocking, $buf_x, $buf_y, $buf_z, $host_x, $host_y, $host_z, $width, $height, $depth, $buf_row_pitch, $buf_slice_pitch, $host_row_pitch, $host_slice_pitch, $data, $wait_events...)
-
http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clEnqueueReadBufferRect.html
- $ev = $queue->enqueue_write_buffer_rect (OpenCL::Memory buf, cl_bool blocking, $buf_x, $buf_y, $buf_z, $host_x, $host_y, $host_z, $width, $height, $depth, $buf_row_pitch, $buf_slice_pitch, $host_row_pitch, $host_slice_pitch, $data, $wait_events...)
-
http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clEnqueueWriteBufferRect.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/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/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_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_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/clEnqueueCopyBufferToImage.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 are0), 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 ($wait_events...)
-
http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clEnqueueMarker.html
- $ev = $queue->enqueue_acquire_gl_objects ([object, ...], $wait_events...)
-
Enqueues a list (an array-ref of OpenCL::Memory objects) to be acquired for subsequent OpenCL usage.
http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clEnqueueAcquireGLObjects.html
- $ev = $queue->enqueue_release_gl_objects ([object, ...], $wait_events...)
-
Enqueues a list (an array-ref of OpenCL::Memory objects) to be released for subsequent OpenGL usage.
http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clEnqueueReleaseGLObjects.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->infofor details.http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clGetCommandQueueInfo.html
- $ctx = $command_queue->context
-
Calls
clGetCommandQueueInfowithCL_QUEUE_CONTEXTand returns the result. - $device = $command_queue->device
-
Calls
clGetCommandQueueInfowithCL_QUEUE_DEVICEand returns the result. - $uint = $command_queue->reference_count
-
Calls
clGetCommandQueueInfowithCL_QUEUE_REFERENCE_COUNTand returns the result. - $command_queue_properties = $command_queue->properties
-
Calls
clGetCommandQueueInfowithCL_QUEUE_PROPERTIESand returns the result.
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->infofor details.http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clGetMemObjectInfo.html
- $mem_object_type = $mem->type
-
Calls
clGetMemObjectInfowithCL_MEM_TYPEand returns the result. - $mem_flags = $mem->flags
-
Calls
clGetMemObjectInfowithCL_MEM_FLAGSand returns the result. - $int = $mem->size
-
Calls
clGetMemObjectInfowithCL_MEM_SIZEand returns the result. - $ptr_value = $mem->host_ptr
-
Calls
clGetMemObjectInfowithCL_MEM_HOST_PTRand returns the result. - $uint = $mem->map_count
-
Calls
clGetMemObjectInfowithCL_MEM_MAP_COUNTand returns the result. - $uint = $mem->reference_count
-
Calls
clGetMemObjectInfowithCL_MEM_REFERENCE_COUNTand returns the result. - $ctx = $mem->context
-
Calls
clGetMemObjectInfowithCL_MEM_CONTEXTand returns the result. - $mem = $mem->associated_memobject
-
Calls
clGetMemObjectInfowithCL_MEM_ASSOCIATED_MEMOBJECTand returns the result. - $int = $mem->offset
-
Calls
clGetMemObjectInfowithCL_MEM_OFFSETand returns the result. - ($type, $name) = $mem->gl_object_info
-
Returns the OpenGL object type (e.g. OpenCL::GL_OBJECT_TEXTURE2D) and the object "name" (e.g. the texture name) used to create this memory object.
http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clGetGLObjectInfo.html
THE OpenCL::Buffer CLASS
This is a subclass of OpenCL::Memory, and the superclass of OpenCL::BufferObj. Its purpose is simply to distinguish between buffers and sub-buffers.
THE OpenCL::BufferObj CLASS
This is a subclass of OpenCL::Buffer and thus OpenCL::Memory. It exists because one cna create sub buffers of OpenLC::BufferObj objects, but not sub buffers from these sub buffers.
- $subbuf = $buf_obj->sub_buffer_region ($flags, $origin, $size)
-
Creates an OpenCL::Buffer objects from this buffer and returns it. The
buffer_create_typeis assumed to beCL_BUFFER_CREATE_TYPE_REGION.http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clCreateSubBuffer.html
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->infofor details.The reason this method is not called
infois that there already is an->infomethod inherited fromOpenCL::Memory.http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clGetImageInfo.html
- $int = $image->element_size
-
Calls
clGetImageInfowithCL_IMAGE_ELEMENT_SIZEand returns the result. - $int = $image->row_pitch
-
Calls
clGetImageInfowithCL_IMAGE_ROW_PITCHand returns the result. - $int = $image->slice_pitch
-
Calls
clGetImageInfowithCL_IMAGE_SLICE_PITCHand returns the result. - $int = $image->width
-
Calls
clGetImageInfowithCL_IMAGE_WIDTHand returns the result. - $int = $image->height
-
Calls
clGetImageInfowithCL_IMAGE_HEIGHTand returns the result. - $int = $image->depth
-
Calls
clGetImageInfowithCL_IMAGE_DEPTHand returns the result. - $GLenum = $gl_texture->target
-
Calls
clGetGLTextureInfowithCL_GL_TEXTURE_TARGETand returns the result. - $GLint = $gl_texture->gl_mipmap_level
-
Calls
clGetGLTextureInfowithCL_GL_MIPMAP_LEVELand returns the result.
THE OpenCL::Sampler CLASS
- $packed_value = $sampler->info ($name)
-
See
$platform->infofor details.http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clGetSamplerInfo.html
- $uint = $sampler->reference_count
-
Calls
clGetSamplerInfowithCL_SAMPLER_REFERENCE_COUNTand returns the result. - $ctx = $sampler->context
-
Calls
clGetSamplerInfowithCL_SAMPLER_CONTEXTand returns the result. - $addressing_mode = $sampler->normalized_coords
-
Calls
clGetSamplerInfowithCL_SAMPLER_NORMALIZED_COORDSand returns the result. - $filter_mode = $sampler->addressing_mode
-
Calls
clGetSamplerInfowithCL_SAMPLER_ADDRESSING_MODEand returns the result. - $boolean = $sampler->filter_mode
-
Calls
clGetSamplerInfowithCL_SAMPLER_FILTER_MODEand returns the result.
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
__kernelfunction in the program.http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clCreateKernel.html
- $build_status = $program->build_status ($device)
-
Calls
clGetProgramBuildInfowithCL_PROGRAM_BUILD_STATUSand returns the result. - $string = $program->build_options ($device)
-
Calls
clGetProgramBuildInfowithCL_PROGRAM_BUILD_OPTIONSand returns the result. - $string = $program->build_log ($device)
-
Calls
clGetProgramBuildInfowithCL_PROGRAM_BUILD_LOGand returns the result. - $packed_value = $program->info ($name)
-
See
$platform->infofor details.http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clGetProgramInfo.html
- $uint = $program->reference_count
-
Calls
clGetProgramInfowithCL_PROGRAM_REFERENCE_COUNTand returns the result. - $ctx = $program->context
-
Calls
clGetProgramInfowithCL_PROGRAM_CONTEXTand returns the result. - $uint = $program->num_devices
-
Calls
clGetProgramInfowithCL_PROGRAM_NUM_DEVICESand returns the result. - @devices = $program->devices
-
Calls
clGetProgramInfowithCL_PROGRAM_DEVICESand returns the result. - $string = $program->source
-
Calls
clGetProgramInfowithCL_PROGRAM_SOURCEand returns the result. - @ints = $program->binary_sizes
-
Calls
clGetProgramInfowithCL_PROGRAM_BINARY_SIZESand returns the result. - @blobs = $program->binaries
-
Returns a string for the compiled binary for every device associated with the program, empty strings indicate missing programs, and an empty result means no program binaries are available.
These "binaries" are often, in fact, informative low-level assembly sources.
http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clGetProgramInfo.html
THE OpenCL::Kernel CLASS
- $packed_value = $kernel->info ($name)
-
See
$platform->infofor details.http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clGetKernelInfo.html
- $string = $kernel->function_name
-
Calls
clGetKernelInfowithCL_KERNEL_FUNCTION_NAMEand returns the result. - $uint = $kernel->num_args
-
Calls
clGetKernelInfowithCL_KERNEL_NUM_ARGSand returns the result. - $uint = $kernel->reference_count
-
Calls
clGetKernelInfowithCL_KERNEL_REFERENCE_COUNTand returns the result. - $ctx = $kernel->context
-
Calls
clGetKernelInfowithCL_KERNEL_CONTEXTand returns the result. - $program = $kernel->program
-
Calls
clGetKernelInfowithCL_KERNEL_PROGRAMand returns the result. - $packed_value = $kernel->work_group_info ($device, $name)
-
See
$platform->infofor details.The reason this method is not called
infois that there already is an->infomethod.http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clGetKernelWorkGroupInfo.html
- $int = $kernel->work_group_size ($device)
-
Calls
clGetKernelWorkGroupInfowithCL_KERNEL_WORK_GROUP_SIZEand returns the result. - @ints = $kernel->compile_work_group_size ($device)
-
Calls
clGetKernelWorkGroupInfowithCL_KERNEL_COMPILE_WORK_GROUP_SIZEand returns the result. - $ulong = $kernel->local_mem_size ($device)
-
Calls
clGetKernelWorkGroupInfowithCL_KERNEL_LOCAL_MEM_SIZEand returns the result. - $int = $kernel->preferred_work_group_size_multiple ($device)
-
Calls
clGetKernelWorkGroupInfowithCL_KERNEL_PREFERRED_WORK_GROUP_SIZE_MULTIPLEand returns the result. - $ulong = $kernel->private_mem_size ($device)
-
Calls
clGetKernelWorkGroupInfowithCL_KERNEL_PRIVATE_MEM_SIZEand returns the result. - $kernel->set_TYPE ($index, $value)
-
This is a family of methods to set the kernel argument with the number
$indexto the give$value.TYPE is one of
char,uchar,short,ushort,int,uint,long,ulong,half,float,double,memory,buffer,image2d,image3d,samplerorevent.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->infofor details.http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clGetEventInfo.html
- $queue = $event->command_queue
-
Calls
clGetEventInfowithCL_EVENT_COMMAND_QUEUEand returns the result. - $command_type = $event->command_type
-
Calls
clGetEventInfowithCL_EVENT_COMMAND_TYPEand returns the result. - $uint = $event->reference_count
-
Calls
clGetEventInfowithCL_EVENT_REFERENCE_COUNTand returns the result. - $uint = $event->command_execution_status
-
Calls
clGetEventInfowithCL_EVENT_COMMAND_EXECUTION_STATUSand returns the result. - $ctx = $event->context
-
Calls
clGetEventInfowithCL_EVENT_CONTEXTand returns the result. - $packed_value = $ev->profiling_info ($name)
-
See
$platform->infofor details.The reason this method is not called
infois that there already is an->infomethod.http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clGetProfilingInfo.html
- $ulong = $event->profiling_command_queued
-
Calls
clGetEventProfilingInfowithCL_PROFILING_COMMAND_QUEUEDand returns the result. - $ulong = $event->profiling_command_submit
-
Calls
clGetEventProfilingInfowithCL_PROFILING_COMMAND_SUBMITand returns the result. - $ulong = $event->profiling_command_start
-
Calls
clGetEventProfilingInfowithCL_PROFILING_COMMAND_STARTand returns the result. - $ulong = $event->profiling_command_end
-
Calls
clGetEventProfilingInfowithCL_PROFILING_COMMAND_ENDand returns the result.
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/