OpenCL™ 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 any C++ libraries.
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 - As close as possible to zero performance overhead - Safe and painless management of API resources and pointers
Ensure that an OpenCL library is installed for your platform and that clinfo
or some other diagnostic command will run.
Add:
rust
[dependencies]
ocl = "0.6"
to your project's Cargo.toml.
From 'examples/trivial.rs': ```rust extern crate ocl; use ocl::{ProQue, SimpleDims, Buffer};
fn main() { // Define some program source code: let src = r#" kernel void multiply(global float* buffer, float coeff) { buffer[getglobalid(0)] *= coeff; } "#;
// Create an all-in-one context, program, and command queue:
let ocl_pq = ProQue::builder().src(src).build().unwrap();
// Set our work dimensions / data set size to something arbitrary:
let dims = SimpleDims::One(500000);
// Create a `Buffer` with a built-in `Vec` and initialize it with random
// floats between 0.0 and 20.0:
let mut buffer: Buffer<f32> = Buffer::with_vec_scrambled(
(0.0, 20.0), &dims, &ocl_pq.queue());
// Declare a value to multiply our buffer's contents by:
let scalar = 10.0f32;
// Create a kernel with arguments matching those in the source above:
let kern = ocl_pq.create_kernel("multiply", dims.work_dims()).unwrap()
.arg_buf(&buffer)
.arg_scl(scalar);
// Choose an element to keep track of:
let element_idx = 200007;
let element_original_value = buffer[element_idx];
// Run the kernel (the optional arguments are for event lists):
kern.enqueue(None, None);
// Read results from the device into our buffer's built-in vector:
buffer.fill_vec();
// Verify and print a result:
let element_final_value = buffer[element_idx];
assert!((element_final_value - (element_original_value * scalar)).abs() < 0.0001);
println!("The value at index [{}] was '{}' and is now '{}'!",
element_idx, element_original_value, element_final_value);
} ```
Tested so far only on Linux (and probably OS X - need confirmation). Windows support looks imminent. Please [provide feedback] about failures and successes on your platform.
Already familiar with the standard OpenCL core API? See the [core] module for
access to the complete feature set with Rust's safety and convenience.
Want to bring your OpenCL-ness to Rust but can't find the functionality you need? File an [issue] and let us know what should come next.
Due to this developer continuing to have problems getting 2.0 drivers to work properly with his multi-gpu AMD Linux configuration, 2.0 & 2.1 support is on hold. APIs are being designed with their future support in mind however.
On a side note. 1.1 support is intact but intentionally disabled for simplicity. If anyone needs this support for this please file an [issue] and I will reenable it right away. Automatic best-version support for versions going all the way back to 1.0 will eventually be included once some time can be spent on that.
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 will implement the two host APIs identically.
Moving forward 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 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 OpenCL drivers: 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 (AMD drivers sometimes don't create this link). Intel also has [OpenCL libraries for your CPU] if you're having trouble getting your GPU to work (AMD used to have some for CPUs too, can't find them anymore).
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.”