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
Structs
Enums
Constants
Traits
OpenCL kernels.OpenCL kernels.Functions
event_status is CommandExecutionStatus::Complete, the cl_event
pointed to by user_data will be set to the same._dummy_callback.len * sizeof(T).src_strings.device_ids.OpenGL buffer object.OpenGL renderbuffer object.OpenGL texture2D object.OpenGL texture2D object.OpenGL texture3D object.DEVICE_TYPE_ALL.buffer into the host address space and returns a pointer to this
mapped region.image into
the host address space and returns a pointer to this mapped region.buffer to device memory,
data.data, to device memory referred to by
buffer.event.func_name for a given platform.cl_program for any of the devices listed in
device_ids has a build log of any length, it will be returned as an
errcode result.callback_trigger
status is reached.index.context is in fact a context object pointer.num_events events in event_list are complete.