Pure OpenCL™ bindings and interfaces for Rust. Makes easy to use the most common features of OpenCL. All interfaces are virtually zero-cost and perform on a par with the C++ bindings.
Interfaces are still mildly unstable. Changes are now being documented in RELEASES.md.
To provide: - A simple and intuitive interface with OpenCL devices - The full functionality of the OpenCL API - An absolute minimum of boilerplate - Zero or virtually zero performance overhead - Thread-safe and automatic management of API pointers and resources
Ensure that an OpenCL library is installed for your platform and that clinfo
or some other diagnostic command will run. Add the following to your project's
Cargo.toml:
rust
[dependencies]
ocl = "0.8"
And add the following to your crate root (lib.rs or main.rs):
rust
extern crate ocl;
From [examples/trivial.rs]:
```rust
extern crate ocl;
use ocl::ProQue;
fn main() { let src = r#" kernel void add(global float* buffer, float scalar) { buffer[getglobalid(0)] += scalar; } "#;
let pro_que = ProQue::builder()
.src(src)
.dims([2 << 20])
.build().unwrap();
let buffer = pro_que.create_buffer::<f32>().unwrap();
let kernel = pro_que.create_kernel("add").unwrap()
.arg_buf(&buffer)
.arg_scl(10.0f32);
kernel.enq().unwrap();
let mut vec = vec![0.0f32; buffer.len()];
buffer.read(&mut vec).enq().unwrap();
println!("The value at index [{}] is now '{}'!", 200007, vec[200007]);
} ///////////// See the original file for more ///////////// ```
See the the remainder of [examples/trivial.rs] for much more.
Already familiar with the standard OpenCL core API? See the [core] module
for access to the complete feature set in the conventional API style with
Rust's safety and convenience.
1.1 support is intact but intentionally disabled for simplicity. If this support is needed, please file an [issue] and it will be reenabled. Automatic best-version support for versions going all the way back to 1.0 will eventually be added.
The OpenCL API already posesses all of the new attributes of the Vulkan API such as low-overhead, high performance, and unfettered hardware access. For all practical purposes, Vulkan is simply a graphics-focused superset of OpenCL's features (sorta kinda). OpenCL 2.1+ and Vulkan kernels/shaders now both compile into SPIR-V making the device side of things the same. I wouldn't be suprised if most driver vendors implement the two host APIs identically.
In the future it's possible the two may completely merge (or that Vulkan will
absorb OpenCL). Whatever happens, not much will change as far as the front end
of this library is concerned (though the core module functions / types could
get some very minor renaming, etc. but it wouldn't be for a very long time...
version 2.0...). This library will maintain it's focus on the compute side of
things. For the graphics side, see the excellent OpenGL library, [glium], and
its younger sibling, [vulkano].
If troubleshooting your vendor's drivers:
git clone https://github.com/cogciprocate/ocl.git.cd ocl.cargo run --example info and/or cargo run
--example info_core.Other things to try (linux): check that /usr/lib/libOpenCL.so.1 exists. Go
ahead and link /usr/lib/libOpenCL.so -> libOpenCL.so.1 just in case it's not
already done (some vendors don't create this link).
If you're still having trouble getting your GPU to work, Intel and AMD also have OpenCL libraries for your CPU: [amd-app-sdk], [intel-win64], [intel-linux64-redhat-suse], [intel-linux64-ubuntu]. [amd-app-sdk] works well on both Intel and AMD processors and is great if you don't mind installing all of the extra tools (which are pretty decent by the way).
A short HOWTO for getting OpenCL drivers installed properly and working with
Rust-Windows-GNU (MSVC too eventually) is in the works. For now just be sure
to put a copy of the platform-agnostic ICD loader, OpenCL.dll, usually found
somewhere within the C:\Windows folder tree, into the Rust library folder
(defaults to C:\Program Files\{Rust
folder}\lib\rustlib\x86_64-pc-windows-gnu\lib) and make sure your platform
drivers are installed correctly (there's a registry setting + they must be in
the PATH).
Due to buggy and/or intentionally crippled drivers, functionality involving
multiple host threads, multiple devices, or asynchronous callbacks may not
work on NVIDIA hardware. Until NVIDIA's implementation is corrected, tests and
examples involving multiple asynchronous tasks may occasionally fail or
produce erroneous results (you are suffering from this if the events.rs test
fails when you run cargo test). It's reccommended that you use Intel or AMD
CPU drivers in the meanwhile and switch if/when NVIDIA ever gets their act
together.
Please ask questions and provide feedback by opening an [issue].
“OpenCL and the OpenCL logo are trademarks of Apple Inc. used by permission by Khronos.” “Vulkan and the Vulkan logo are trademarks of the Khronos Group Inc.”