isabella232 / fil-ocl

OpenCL for Rust

ocl

Documentation | Change Log

Pure OpenCL™ bindings and interfaces for Rust.

Goals

To provide:

• A simple and intuitive interface to OpenCL devices
• The full functionality and power 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

Usage

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:

[dependencies]
ocl = "0.19"

And add the following to your crate root (lib.rs or main.rs):

extern crate ocl;

Example

From examples/trivial.rs:

extern crate ocl;
use ocl::ProQue;

fn trivial() -> ocl::Result<()> {
    let src = r#"
        __kernel void add(__global float* buffer, float scalar) {
            buffer[get_global_id(0)] += scalar;
        }
    "#;

    let pro_que = ProQue::builder()
        .src(src)
        .dims(1 << 20)
        .build()?;

    let buffer = pro_que.create_buffer::<f32>()?;

    let kernel = pro_que.kernel_builder("add")
        .arg(&buffer)
        .arg(10.0f32)
        .build()?;

    unsafe { kernel.enq()?; }

    let mut vec = vec![0.0f32; buffer.len()];
    buffer.read(&mut vec).enq()?;

    println!("The value at index [{}] is now '{}'!", 200007, vec[200007]);
    Ok(())
}

See the the remainder of examples/trivial.rs for more information about how this library leverages Rust's zero-cost abstractions to provide the full power and performance of the C API in a simple package.

Recent Changes

• 0.18.0: Creating a Kernel now requires the use of the new KernelBuilder. See the change log for more information.

Introduction to OpenCL

For a quick but thorough primer on the basics of OpenCL, please see Matthew Scarpino's excellent article, 'A Gentle Introduction to OpenCL' at drdobbs.com (his book is great too).

Diving Deeper

Already familiar with the standard OpenCL core API? See the ocl-core crate for access to the complete feature set in the conventional API style with Rust's safety and convenience.

Version Support

OpenCL versions 1.1 and above are supported. OpenCL version 1.0 is not supported due to its inherent thread unsafety.

Vulkan™ and the Future

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, nothing will change as far as the front end of this library is concerned. This library will maintain its focus on the compute side of things. For the graphics side, see the voodoo library.

License

Licensed under either of:

• Apache License, Version 2.0, (LICENSE-APACHE or http://www.apache.org/licenses/LICENSE-2.0)
• MIT license (LICENSE-MIT or http://opensource.org/licenses/MIT)

at your option.

Contribution

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 dual licensed as above, without any additional terms or conditions.

“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.”