A Rust adapter for the Khronos OpenCL API.
A functional, safe Rust interface to the Khronos
OpenCL 3.0 C API
based upon the opencl-sys OpenCL FFI bindings.
It is the foundation of the opencl3 crate
which provides a simpler, object based model of the OpenCL 3.0 API.
OpenCL 3.0
is a unified specification that adds little new functionality to previous OpenCL versions.
It specifies that all OpenCL 1.2 features are mandatory, while all
OpenCL 2.x and 3.0 features are now optional.
OpenCL also has extensions that enable other features such as OpenGL and Direct X interoperability, see OpenCL Extensions. This library includes FFI bindings to use OpenCL extensions.
This crate applies the adapter pattern
to convert OpenCL C API functions into Rust functions that return a
Result containing the desired result of
the C function or the OpenCL error code.
The only exception is svm_free, which just provides a safe wrapper for the
clSVMFree C API function.
Most of the modules are named after their equivalent "API" sections in
cl.h.
They contain Rust adapter functions for the OpenCL API C functions defined
in those sections with their associated types and constants.
For more information see the Rust documentation.
The API for OpenCL versions and extensions are controlled by Rust features such as "CL_VERSION_2_0" and "cl_khr_gl_sharing". To enable an OpenCL version, the feature for that version and all previous OpenCL versions must be enabled, e.g. for "CL_VERSION_2_0"; "CL_VERSION_1_1" and "CL_VERSION_1_2" must also be enabled.
The default features are "CL_VERSION_1_1" and "CL_VERSION_1_2".
Rust deprecation warnings are given for OpenCL API functions that are deprecated by an enabled OpenCL version e.g., clCreateCommandQueue is deprecated whenever "CL_VERSION_2_0" is enabled.
Ensure that an OpenCL Installable Client Driver (ICD) and the appropriate OpenCL hardware driver(s) are installed, see OpenCL Installation.
cl3 supports OpenCL 1.2 and 2.0 ICD loaders by default. If you have an
OpenCL 2.0 ICD loader then add the following to your project's Cargo.toml:
[dependencies]
cl3 = "0.9"If your OpenCL ICD loader supports higher versions of OpenCL then add the
appropriate features to cl3, e.g. for an OpenCL 2.1 ICD loader add the
following to your project's Cargo.toml instead:
[dependencies.cl3]
version = "0.9"
features = ["CL_VERSION_1_1", "CL_VERSION_1_2", "CL_VERSION_2_0", "CL_VERSION_2_1"]OpenCL extensions can also be enabled by adding their features, e.g.:
[dependencies.cl3]
version = "0.9"
features = ["cl_khr_gl_sharing", "cl_khr_dx9_media_sharing"]Whichever version of OpenCL ICD loader you use, add the following to your
crate root (lib.rs or main.rs):
extern crate cl3;The crate contains unit, documentation and integration tests.
The tests run the platform and device info functions (among others) so they
can provide useful information about OpenCL capabilities of the system.
It is recommended to run the tests in single-threaded mode, since some of them can interfere with each other when run multi-threaded, e.g.:
cargo test -- --test-threads=1 --show-outputThe integration tests are marked ignore so use the following command to
run them:
cargo test -- --test-threads=1 --show-output --ignoredThe tests provide examples of how the crate may be used, e.g. see: platform, device, context and integration_test.
If you want to contribute through code or documentation, the Contributing guide is the best place to start. If you have any questions, please feel free to ask. Just please abide by our Code of Conduct.
Licensed under the Apache License, Version 2.0, as per Khronos Group OpenCL.
You may obtain a copy of the License at: http://www.apache.org/licenses/LICENSE-2.0
Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be licensed as above, without any additional terms or conditions.
OpenCL and the OpenCL logo are trademarks of Apple Inc. used by permission by Khronos.