Expand description
Thin wrappers for the OpenCL
FFI functions and types.
Allows access to OpenCL
FFI functions with a minimal layer of zero-cost
abstraction, providing, safety, performance, and convenience. The ocl
crate contains higher level and easier to use interfaces to the
functionality contained within.
§Even Lower Level: cl-sys
If there’s still something missing or for some reason you need direct FFI
access, use the functions in the cl-sys
module. The pointers used by
cl-sys
functions can be wrapped in ocl-core
wrappers
(ocl_core::PlatformId
, ocl_core::Context
, etc.) and passed to
ocl-core
module functions. Likewise the other way around (using, for
example: [EventRaw::as_ptr
]).
§Performance
Performance between all three interface layers, cl-sys
, ocl-core
,
and the ‘standard’ (ocl
) types, is identical or virtually identical
(if not, please file an issue).
§Safety
Running any kernel at all is inherently unsafe. The guarantee we aim to
make in this library is that if there is a segfault or invalid memory
access, the fault lies within the kernel. No effort is or will be made to
verify or sanitize kernels. Consider all kernels within user-supplied
programs just as if you would an unsafe fn
.
§Length vs Size
No, not that…
Quantifiers passed to functions in the OpenCL
API are generally
expressed in bytes. Units passed to functions in this library are
expected to be bytes / sizeof(T)
(corresponding with units returned by
the ubiquitous .len()
method). The suffix ‘_size’ or ‘_bytes’ is
generally used when a parameter deviates from this convention.
§Version Control
The version control system is in place to ensure that you don’t call functions that your hardware/driver does not support.
Functions in this crate with the [Version Controlled: OpenCL {...}+]
tag
in the description require an additional parameter, device_version
or
device_versions
: a parsed result (or slice of results) of
DeviceInfo::Version
. This is a runtime check to ensure that the device
supports the function being called. Calling a function which a particular
device does not support will likely cause a segmentation fault and
possibly data corruption.
Saving the OpenclVersion
returned from device_version()
for your
device(s) at the start of your program and passing it each time you call
a version controlled function is the fastest and safest method (see the
ocl
library for an example). The cost of this check is little more than
a single if
statement.
Passing None
for device_version
will cause an automated version check
which has a small cost (calling info function, parsing the version number
etc.) but is a safe option if you are not sure what to do.
Passing the result of a call to OpenclVersion::max()
or passing a fake
version will bypass any safety checks and has all of the risks described
above. Only do this if you’re absolutely sure you know what you’re doing
and are not concerned about segfaults and data integrity.
§More Documentation
As most of the functions here are minimally documented, please refer to
the official OpenCL
documentation linked below. Although there isn’t a
precise 1:1 parameter mapping between the core
and original functions,
it’s close enough (modulo the size/len difference discussed above) to help
sort out any questions you may have until a more thorough documentation
pass can be made. View the source code in src/types/functions.rs
for
more mapping details.
‘OpenCL’ 1.2 SDK Reference: https://www.khronos.org/registry/cl/sdk/1.2/docs/man/xhtml/
Re-exports§
pub extern crate cl_sys as ffi;
pub use self::error::Error;
pub use self::error::Result;
pub use self::error::ErrorKind;
pub use self::types::abs::ClWaitListPtr;
pub use self::types::abs::ClNullEventPtr;
pub use self::types::abs::ClEventPtrRef;
pub use self::types::abs::ClPlatformIdPtr;
pub use self::types::abs::ClDeviceIdPtr;
pub use self::types::abs::ClContextPtr;
pub use self::types::abs::EventRefWrapper;
pub use self::types::abs::PlatformId;
pub use self::types::abs::DeviceId;
pub use self::types::abs::Context;
pub use self::types::abs::CommandQueue;
pub use self::types::abs::Mem;
pub use self::types::abs::Program;
pub use self::types::abs::Kernel;
pub use self::types::abs::Event;
pub use self::types::abs::Sampler;
pub use self::types::abs::ClVersions;
pub use self::types::abs::AsMem;
pub use self::types::abs::MemCmdRw;
pub use self::types::abs::MemCmdAll;
pub use self::types::abs::MemMap;
pub use self::types::structs;
pub use self::types::structs::OpenclVersion;
pub use self::types::structs::ContextProperties;
pub use self::types::structs::ImageFormatParseError;
pub use self::types::structs::ImageFormatParseResult;
pub use self::types::structs::ImageFormat;
pub use self::types::structs::ImageDescriptor;
pub use self::types::structs::BufferRegion;
pub use self::types::structs::ContextPropertyValue;
pub use self::types::structs::ArgVal;
pub use self::types::enums::EmptyInfoResultError;
pub use self::types::enums::PlatformInfoResult;
pub use self::types::enums::DeviceInfoResult;
pub use self::types::enums::ContextInfoResult;
pub use self::types::enums::GlContextInfoResult;
pub use self::types::enums::CommandQueueInfoResult;
pub use self::types::enums::MemInfoResult;
pub use self::types::enums::ImageInfoResult;
pub use self::types::enums::SamplerInfoResult;
pub use self::types::enums::ProgramInfoResult;
pub use self::types::enums::ProgramBuildInfoResult;
pub use self::types::enums::KernelInfoResult;
pub use self::types::enums::KernelArgInfoResult;
pub use self::types::enums::KernelWorkGroupInfoResult;
pub use self::types::enums::EventInfoResult;
pub use self::types::enums::ProfilingInfoResult;
Modules§
- Standard error type for ocl.
- Utility and debugging functions.
Structs§
- cl_command_queue_properties - bitfield
- cl_device_affinity_domain
- cl_device_exec_capabilities - bitfield
- cl_device_fp_config - bitfield
- cl_device_type - bitfield
- cl_kernel_arg_type_qualifer
- cl_map_flags - bitfield
- cl_mem_flags - bitfield
- cl_mem_migration_flags - bitfield
- cl_program_binary_type
Enums§
- cl_addressing_mode
- cl_buffer_create_type
- cl_bool
- cl_channel_type
- command execution status
- cl_command_queue_info
- cl_command_type
- cl_context_info
- cl_context_info + cl_context_properties
- cl_context_info + cl_context_properties
- cl_device_info
- cl_device_local_mem_type
- cl_mem_cache_type
- [INCOMPLETE] cl_device_partition_property
- cl_event_info
- cl_filter_mode
- cl_gl_context_info
- specify the texture target type
- Describes the size of the channel data type. The number of bits per element determined by the image_channel_data_type and image_channel_order must be a power of two. The list of supported values is described in the table below. (from SDK)
- Specifies the number of channels and the channel layout i.e. the memory layout in which channels are stored in the image. Valid values are described in the table below. (from SDK)
- cl_image_info
- cl_kernel_arg_access_qualifier
- cl_kernel_arg_address_qualifier
- cl_kernel_arg_info
- cl_kernel_info
- cl_kernel_work_group_info
- cl_mem_info
- cl_mem_object_type
- cl_platform_info
- cl_bool: Polling
- cl_profiling_info
- cl_program_build_info
- cl_build_status
- cl_program_info
- cl_sampler_info
- The status of an OpenCL API call. Used for returning success/error codes.
Constants§
Traits§
- A set of traits common to numeric built-in OpenCL scalar and vector primitives.
- A primitive type usable within
OpenCL
kernels. - A scalar type usable within OpenCL kernels.
- A vector type usable within
OpenCL
kernels.
Functions§
- If
event_status
isCommandExecutionStatus::Complete
, thecl_event
pointed to byuser_data
will be set to the same. - Don’t be a dummy. Buckle your
_dummy_callback
. - Builds a program.
- Compiles a program’s source for all the devices or a specific device(s) in the OpenCL context associated with program.
- Returns a new buffer pointer with size (bytes):
len
* sizeof(T). - Creates, builds, and returns a new program pointer from
src_strings
. - Returns a new command queue pointer.
- Creates a new context pointer valid for all devices in
device_ids
. - Creates a new context pointer for all devices of a specific type.
- Return a buffer pointer from a
OpenGL
buffer object. - Return a renderbuffer pointer from a
OpenGL
renderbuffer object. - Return a texture2D pointer from a
OpenGL
texture2D object. - Return a texture2D pointer from a
OpenGL
texture2D object. - Return a texture3D pointer from a
OpenGL
texture3D object. - Returns a new image (mem) pointer.
- Returns a new kernel.
- [UNIMPLEMENTED: Please implement me]
- Creates a program object for a context, and loads the binary bits specified by binary into the program object.
- [UNIMPLEMENTED: Please implement me]
- Creates a new program.
- Creates and returns a new sampler object.
- Creates a new buffer object (referred to as a sub-buffer object) from an existing buffer object.
- [UNIMPLEMENTED: Please implement me]
- Creates an event not already associated with any command.
- Returns the default device type bitflags as specified by environment variable or else
DEVICE_TYPE_ALL
. - Returns the default or first platform.
- Returns the default platform if set by an environment variable or config file.
- Returns a list of versions for devices.
- Acquire OpenCL memory objects (buffers and images) that have been created from OpenGL objects.
- A synchronization point that enqueues a barrier operation.
- Copies the contents of one buffer to another.
- Enqueues a command to copy a rectangular region from a buffer object to another buffer object.
- Enqueues a command to copy a buffer object to an image object.
- Enqueues a command to copy image objects.
- Enqueues a command to copy an image object to a buffer object.
- Enqueues a command to fill a buffer object with a pattern of a given pattern size.
- Enqueues a command to fill an image object with a specified color.
- Enqueues a command to execute a kernel on a device.
- Enqueues a command to map a region of the buffer object given by
buffer
into the host address space and returns a pointer to this mapped region. - Enqueues a command to map a region of the image object given by
image
into the host address space and returns a pointer to this mapped region. - Enqueues a marker command which waits for either a list of events to complete, or all previously enqueued commands to complete.
- Enqueues a command to indicate which device a set of memory objects should be associated with.
- [UNIMPLEMENTED: Please implement me]
- Enqueues a read from device memory referred to by
buffer
to device memory,data
. - Enqueues a command to read from a rectangular region from a buffer object to host memory.
- Reads an image from device to host memory.
- Release OpenCL memory objects (buffers and images) that have been created from OpenGL objects.
- Enqueues a command to execute a kernel on a device.
- Enqueues a command to unmap a previously mapped region of a memory object.
- Enqueues a write from host memory,
data
, to device memory referred to bybuffer
. - Enqueues a command to write from a rectangular region from host memory to a buffer object.
- Enqueues a command to write to an image or image array object from host memory.
- Returns true if an event is complete, false if not complete.
- Returns the status of
event
. - Waits for a queue to finish.
- Flushes a command queue.
- Returns information about a command queue
- Returns various kinds of context information.
- Returns the platform for a context.
- Returns a list of available devices for a particular platform.
- Returns information about a device.
- Returns raw information about a device, as a vector of bytes.
- Get event info.
- Get event profiling info (for debugging / benchmarking).
- Returns the address of the extension function named by
func_name
for a given platform. - [INOPERATIVE: Needs troubleshooting] Returns OpenGL context information.
- Get image info.
- Get kernel arg info.
- Get kernel info.
- Get kernel work group info.
- Get mem object info.
- Returns a list of available platforms as ‘core’ objects.
- Returns platform information of the requested type.
- Get program build info.
- Get program info.
- Returns information about the sampler object.
- Returns a list of supported image formats.
- Links a set of compiled program objects and libraries for all the devices or a specific device(s) in the OpenCL context and creates an executable.
- If the program pointed to by
cl_program
for any of the devices listed indevice_ids
has a build log of any length, it will be returned as an errcode result. - Decrements the reference count of a command queue.
- Decrements reference count of a context.
- Decrements the reference count of a device.
- Decrements an event’s reference counter.
- Decrements a kernel reference counter.
- Decrements the reference counter of a mem object.
- Decrements a program reference counter.
- Decrements a sampler reference counter.
- Increments the reference count of a command queue.
- Increments the reference count of a context.
- Increments the reference count of a device.
- Increments an event’s reference counter.
- Increments a kernel reference counter.
- Increments the reference counter of a mem object.
- Increments a program reference counter.
- Increments a sampler reference counter.
- Sets a callback function which is called as soon as the
callback_trigger
status is reached. - Sets the argument value for the kernel argument at
index
. - [UNIMPLEMENTED: Please implement me]
- Updates a user events status.
- Verifies that the
context
is in fact a context object pointer. - Blocks until an event is complete.
- Blocks until the first
num_events
events inevent_list
are complete.