Crate cl3

source ·
Expand description

crates.io docs.io OpenCL 3.0 License Rust

A Rust adapter for the Khronos OpenCL API.

§Description

A functional, safe Rust interface to the Khronos OpenCL 3.0 C API based upon the opencl-sys OpenCL FFI bindings.

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 OpenCL 3.0 features are now optional.

§Design

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 exception is svm_free, which just provides a safe wrapper for the clSVMFree C API function.

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.

Most of the modules are named after their equivalent OpenCL “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. The exceptions are:

  • error_codes - contains the OpenCL API error codes from cl.h and a function (error_text) to convert an error code to it’s enum name from cl.h.
  • info_type - contains a Rust enum (InfoType) to hold the OpenCL types that can be returned from OpenCL “Info” functions, e.g. clGetPlatformInfo, clGetDeviceInfo, clGetProgramInfo, etc.
  • macros - contains Rust macros to call the OpenCL “Info” functions and return the appropriate InfoType in a Rust Result.

It is vital to call the correct InfoType method type when decoding the result of “Info” functions, since the methods will panic if called with the wrong type, see info_type.

§Use

See cl3.

§License

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

OpenCL and the OpenCL logo are trademarks of Apple Inc. used under license by Khronos.

Modules§

  • command_queue
    OpenCL Command Queue API.
  • context
    OpenCL Context API.
  • d3d10
    FFI bindings for cl_d3d10.h
    cl_d3d10.h contains OpenCL extensions that provide interoperability with Direct3D 10. OpenCL extensions are documented in the OpenCL-Registry
  • d3d11
    FFI bindings for cl_d3d11.h
    cl_d3d11.h contains OpenCL extensions that provide interoperability with Direct3D 11.
    OpenCL extensions are documented in the OpenCL-Registry
  • device
    OpenCL Device API.
  • dx9_media_sharing
    FFI bindings for cl_dx9_media_sharing.h
    cl_ecl_dx9_media_sharing.h contains OpenCL extensions that provide interoperability with Direct3D 9.
    OpenCL extensions are documented in the OpenCL-Registry
  • egl
    OpenCL OpenGL ES Interoperability API.
  • error_codes
    OpenCL API Error Codes.
  • event
    OpenCL Event Object API.
  • ext
    OpenCL extensions that don’t have external (OpenGL, D3D) dependencies. See: OpenCL Extension Specification
  • gl
    OpenCL OpenGL Interoperability API.
  • info_type
  • kernel
    OpenCL Kernel Object API.
  • macros
  • memory
    OpenCL Memory Object API.
  • platform
    OpenCL Platform API.
  • program
    OpenCL Program Object API.
  • sampler
    OpenCL Sampler API.
  • types
    OpenCL API data types.

Macros§