Expand description
Safe Rust bindings for OpenColorIO (OCIO 2.4.1 through 2.6.x).
This crate wraps the OpenColorIO C++ API through a generated FFI layer
(ocio_sys) and exposes safe Rust types for configuration, color-space
queries, processor creation, CPU/GPU execution, GPU shader extraction, and
transform composition.
§OCIO version support
The baseline API works with OpenColorIO >= 2.4.1 and < 2.7. API added in newer
OCIO versions is opt-in through additive vX_Y cargo features (e.g.
v2_5 for hue-curve grading, interchange attributes, and GPU uniform
buffers); enabling one raises the OpenColorIO version requirement checked
at build time.
§Getting started
use ocio_rs::Config;
// Load an OCIO config from a file (real OCIO mode required).
let config = Config::from_file("/path/to/config.ocio")?;
// Create a processor between two color spaces.
let processor = config.processor("scene_linear", "srgb_texture")?;
// Apply the default CPU path to a single RGBA pixel.
let mut pixel = [0.5f32, 0.5, 0.5, 1.0];
processor.default_cpu_processor()?.apply_rgba(&mut pixel);§Project status
This crate targets broad OpenColorIO 2.5 coverage. The low-level FFI and safe-wrapper layers are available for most of the exposed OCIO 2.5 surface, while release hardening and long-tail behavioral validation are still in progress.
§Build modes
| Mode | Feature flag | Notes |
|---|---|---|
| Stub (default) | --no-default-features | APIs return safe defaults; no real color management |
| System | --features system | Requires installed OpenColorIO and pkg-config |
| Bundled | --features bundled | Builds vendored OCIO; static linking by default |
Set OCIO_RS_LINK=dynamic for shared linking. With neither backend feature
nor legacy environment override, the backend is stub and performs no color
processing. OCIO_RS_ENABLE_REAL=0/1 remains a legacy override.
# Stub mode (CI, API-shape testing)
cargo build
# Bundled real-OCIO build
cargo build --features bundled
# Use an installed OCIO
OCIO_INSTALL_DIR=/path/to/ocio cargo build --features system§Crate-level helpers
Free functions such as current_config, set_current_config,
version, and clear_all_caches operate on the process-global OCIO
config. Use them when your application maintains a single shared config
rather than passing Config handles through every call site.
Re-exports§
pub use processor::CPUProcessor;pub use processor::DynamicProperty;pub use processor::GPUProcessor;pub use processor::GpuShaderCreator;pub use processor::GpuShaderDesc;pub use processor::GpuShaderDescView;pub use processor::GpuTexture2D;pub use processor::GpuTexture3D;pub use processor::GpuTextureChannel;pub use processor::GpuTextureDimensions;pub use processor::GpuUniform;pub use processor::GpuUniformCache;pub use processor::GpuUniformCopy;pub use processor::GpuUniformType;pub use processor::GpuUniformValue;pub use processor::PackedConversionLayout;pub use processor::PackedImageLayout;pub use processor::PlanarByteLayout;pub use processor::PlanarBytes;pub use processor::PlanarBytesMut;pub use processor::PlanarF32Layout;pub use processor::Processor;pub use processor::SignedPlanarByteLayout;pub use processor::SignedPlanarBytes;pub use processor::SignedPlanarBytesMut;pub use processor::StaticCPUProcessor;pub use ocio_sys;
Modules§
- constants
- Standard OCIO names and identifiers, as defined by OpenColorIO 2.4–2.6.
- grading
- Grading value types shared across grading transforms.
- transform
- OCIO transform wrappers.
Structs§
- Baker
- Builds LUT and shader outputs from a
Configusing OCIO’s baker API. - Builtin
Config Registry - Enumerates built-in OCIO configurations bundled with the upstream library.
- Builtin
Transform Registry - Enumerates the built-in transform styles provided by the linked OCIO build.
- CPUProcessor
- CPU implementation of a
Processor. - Color
Space - Describes a color space definition stored in a
Config. - Color
Space Menu Helper - Read-only native color-space menu. Strings borrow the menu’s storage.
- Color
Space Menu Parameters - Mutable native options used to construct a color-space menu.
- Color
Space Set - Mutable collection of
ColorSpacehandles used by OCIO set-style APIs. - Config
- An OpenColorIO configuration.
- ConfigIO
Proxy - Provider for OCIO config text and LUT file payloads.
- Config
Merger v2_5 - An owned OCIOM merge controller. Returned params and configs are editable copies.
- Config
Merging Parameters v2_5 - Owned native configuration merge parameters.
- Const
Color Space - An owned, read-only reference to a native OCIO color space.
- Const
Color Space Set - Read-only native result of a color-space set operation.
- Const
Config - Shared immutable native configuration, independent of later global replacement.
- Const
Config Merger v2_5 - A retained read-only merger returned by native OCIO.
- Const
Context - Shared, read-only OCIO context. Queries return owned text because a config may update its current context while this handle remains alive.
- Const
File Rules - Shared read-only file rules. Text is borrowed from the native rules object.
- Const
Format Metadata - Shared read-only metadata retained by an OCIO processor or transform.
- Const
GradingB Spline Curve - Borrowed read-only spline owned by a grading curve set.
- Const
Look - Shared read-only native look. Borrowed text remains valid while this object is alive, provided external native code does not mutate the same object.
- Const
Named Transform - Shared read-only native named transform. Borrowed text remains valid while this object is alive, provided external native code does not mutate it.
- Const
Processor Metadata - Shared read-only native processor metadata.
- Const
View Transform - Shared read-only native view transform. Borrowed text remains valid while this object is alive, provided external native code does not mutate it.
- Const
Viewing Rules - Shared read-only viewing rules. Text is borrowed from the native rules object.
- Context
- Resolves search paths, environment variables, and working context for file-based operations.
- Custom
Image Layout - Interleaved image with independent channel offsets within each pixel.
- Display
View From File - Inputs to the native helper that authors a display view from a transform file.
- Dynamic
Property - References a processor property that may be adjusted dynamically at runtime.
- File
Rules - Holds filename-based routing rules that map media paths to color spaces.
- Format
Metadata - Structured metadata attached to transforms and baked outputs.
- GPUProcessor
- GPU implementation of a
Processor. - GpuShader
Creator - A native OCIO shader creator with its real shared-ownership control block.
- GpuShader
Desc - Collects parameters and emitted source for GPU shader extraction.
- GpuShader
Desc View - Scoped access to a creator’s native descriptor. It cannot be moved out or
used after the creator borrow ends; shared references to its normal
descriptor methods are available via
Deref. - GpuTexture2D
- Texture payload and metadata for a 1D/2D GPU LUT resource.
- GpuTexture3D
- Texture payload and metadata for a 3D GPU LUT resource.
- GpuUniform
- GPU uniform metadata and current value payload extracted from OCIO.
- GpuUniform
Cache - Cached OCIO uniform getters for repeated sampling without bridge allocations.
- GradingB
Spline Curve - An independently owned native OCIO grading spline.
- Grading
HueCurve v2_5 - An independently owned native HUE grading curve set.
- GradingRGB
Curve - An independently owned native RGB grading curve set.
- Legacy
Viewing Pipeline - Native OCIO v1-style viewing pipeline for applications that need its correction stages.
- Look
- Wraps an OCIO look definition with forward and inverse transform slots.
- Mixing
Color Space Manager - Native mixing space and encoding selection.
- Mixing
Slider - An exclusive borrow of the native manager’s slider, without an allocation.
- Named
Transform - Names a reusable transform pair inside a config for interchange and lookup.
- Native
Image Data Pointers - First-pixel addresses returned by OCIO without reading pixel contents.
- Native
Image Desc - An owned OCIO descriptor with exclusive access to its pixel storage. Fixed-layout descriptors do not own their pixels. Callback descriptors own their Rust provider, which may itself own or borrow the storage.
- Native
Image Desc Info - Snapshot of a native image descriptor. This does not expose buffer addresses or certify that the descriptor is safe to process.
- Optimization
Flags - Bit flags selecting processor optimization passes.
- Packed
Conversion Layout - Packed source and destination layout for native-depth conversion.
- Packed
Image Layout - Packed image layout with signed pixel and row strides, in bytes.
- Persistent
Policy Creator - A native creator whose Rust texture policy remains attached between calls.
- Planar
Byte Layout - Positive byte strides and native channel bit depth for a planar image.
- Planar
Bytes - Borrowed source channels for a planar conversion.
- Planar
Bytes Mut - Borrowed destination channels for a planar conversion.
- Planar
F32Layout - Positive F32 element strides for a planar image.
- Processor
- An immutable color-processing pipeline produced from a
Config. - Processor
Cache Flags - Bit flags controlling config-level processor-cache behavior.
- Processor
Metadata - Technical metadata collected while OCIO builds a processor.
- Shader
Creator Options - Options for extracting with custom creator resource handling.
- Shader
Sections - Shader sections supplied by OCIO to a custom assembler during extraction.
- Shader
Texture - A texture supplied by OCIO during shader extraction. Data is borrowed only for the duration of the callback and may be uploaded without a Rust copy.
- Shader
Uniform - A uniform registered by OCIO during custom shader extraction.
- Shader
Uniform Getter - An owned live native uniform getter received during custom registration.
- Shader
Uniform Registration - A native uniform registration request and its independently owned getter.
- Shared
GradingB Spline Curve - Read-only native shared spline that can outlive its original curve set.
- Shared
Grading HueCurve v2_5 - A retained read-only OCIO hue curve value, without a deep copy.
- Shared
GradingRGB Curve - A retained read-only OCIO RGB curve value, without a deep copy.
- Signed
Planar Byte Layout - A planar image layout with signed byte strides and an origin in each plane.
- Signed
Planar Bytes - Immutable planar input with signed byte strides.
- Signed
Planar Bytes Mut - Exclusively borrowed planar image with signed byte strides.
- StaticCPU
Processor - A CPU processor proven to contain no dynamic properties.
- System
Monitors - Native operating-system monitor profile snapshot.
- View
Transform - A scene-to-display or display-to-scene view transform entry.
- View
With Aliases v2_6 - Borrowed arguments for authoring a display or shared view with aliases.
- Viewing
Rules - Holds OCIO viewing rules used to select active views for color spaces.
Enums§
- Allocation
- Allocation domain used to map image values for processing.
- BSpline
Type v2_5 - Type of the monotonic or periodic native grading spline.
- BitDepth
- Pixel sample bit depth understood by OCIO processors.
- CDLStyle
- ASC CDL clamping behavior.
- Channel
Ordering - Channel memory ordering for OCIO packed image descriptors.
- Color
Space Direction - Direction between a color space and its reference space.
- Color
Space Ref - Borrowed editable or read-only color space for OCIO operations.
- Color
Space SetRef - A borrowed editable or read-only color-space set.
- Color
Space Visibility - Visibility filter for color-space enumeration.
- Config
Processor Target - Destination of a processor connecting two read-only configurations.
- Config
Ref - Borrow an editable or shared read-only configuration for native queries.
- Dynamic
Property Type - Runtime-adjustable OCIO processor property kind.
- Environment
Mode - Policy used to populate OCIO context variables from the environment.
- Exposure
Contrast Style - Domain in which exposure/contrast parameters are applied.
- Fixed
Function Style - Built-in OCIO fixed-function transform style.
- GpuLanguage
- Target shading language for OCIO GPU shader extraction.
- GpuTexture
Channel - Channel layout used by extracted 1D/2D GPU texture payloads.
- GpuTexture
Dimensions - Dimensionality metadata for extracted 1D/2D GPU texture payloads.
- GpuUniform
Copy - Result of copying a cached live uniform into caller-owned storage.
- GpuUniform
Type - Uniform value encoding reported by OCIO GPU shader extraction.
- GpuUniform
Value - Typed value payload for a GPU uniform extracted from OCIO.
- Grading
Style - Grading domain used by OCIO grading transforms and values.
- HSYTransform
Style v2_5 - HSY conversion style used by hue-curve operations.
- HueCurve
Type v2_5 - One of OCIO’s hue-dependent grading curve families.
- Image
Desc Channel - Logical pixel channel queried by a Rust-defined native descriptor.
- Interpolation
- Interpolation algorithm used by LUT and related transforms.
- Legacy
Viewing Stage - Transform slots exposed by the native legacy viewing pipeline.
- Logging
Level - Verbosity level for OCIO’s process-global diagnostic logging.
- Lut1D
HueAdjust - Hue adjustment mode for one-dimensional LUT transforms.
- Merge
Strategy v2_5 - Conflict policy used by OpenColorIO when merging a configuration section.
- Named
Transform Visibility - Visibility filter for named-transform enumeration.
- Native
Image Layout - Concrete layout of an existing OCIO image descriptor.
- Negative
Style - Treatment of negative values for transforms that require a policy.
- Ocio
Error - Unified error type for safe
ocio-rsoperations. - RGBCurve
Type - One of the RGB or master curves in a grading RGB curve transform.
- Range
Style - Whether a range transform clamps values at its domain boundaries.
- Reference
Space Type - Reference space domain used by a color space or view transform.
- Search
Reference Space Type - Domain filter used when searching for a color space.
- Shader
Code Section - Native shader code section currently being appended.
- Shader
Lifecycle - Lifecycle stages of a native shader-creator extraction.
- Shader
Texture Action - Storage and optional binding choice for one native texture registration.
- Shader
Uniform Action - How a custom creator handles a native uniform registration request.
- Transform
Direction - Direction in which an OCIO transform or processor is evaluated.
- Transform
Type - Runtime OCIO transform subtype represented by a generic transform handle.
- View
Transform Direction - Direction between a view transform and its reference space.
- View
Type - Origin of a display/view entry in a config.
Traits§
- ConfigIO
Provider - On-demand provider for the OCIO config and its referenced LUTs.
- Image
Desc Provider - Implements OCIO’s virtual image descriptor getters in Rust.
- Ocio
Enum Text - Native OCIO text conversion for an enum or boolean.
- Shader
Cache IdPolicy - Supplies the native creator’s cache ID during an opted-in query or extraction.
- Shader
Clone Policy - Supplies the result of the native creator clone operation.
- Shader
Extraction Hooks - Synchronous customization hooks for OCIO shader extraction.
- Shader
Finalize Control - Optional synchronous replacement for OCIO’s native shader finalization stage.
- Shader
Texture Control - Controls storage and binding of each texture registered by a persistent creator.
- Shader
Texture Policy - Synchronous policy for OCIO’s native texture-width and 1D-texture getters.
- Shader
Uniform Control - Custom control over native uniform registration during shader extraction.
Functions§
- clear_
all_ caches Deprecated - Clears OCIO’s process-global caches.
- current_
config ⚠ - Returns the process-global current OCIO config, if one is installed.
- extract_
ocioz_ archive - Extract an
.ociozarchive into a destination directory. - get_
current_ ⚠config Deprecated - Safety
- get_
env_ ⚠variable - Read an OCIO process environment variable.
- is_
env_ ⚠variable_ present - Return whether an OCIO process environment variable is present.
- is_
stub_ build - Returns
truewhen the crate was built in stub mode instead of linking a real OpenColorIO implementation. - logging_
level - Returns the current OCIO global logging level, or
Unknownwhen called reentrantly from a logging callback. Usetry_logging_levelto distinguish that case. - metadata_
id_ element v2_6 - Native metadata element name for a CLF ID, absent in a stub build.
- processor_
cache_ ⚠flags - Returns the processor cache flags from the current global config.
- reset_
compute_ ⚠hash_ callback - Restore OCIO’s default process-global compute-hash function.
- reset_
logging_ callback - Restore OCIO’s default process-global logging function.
- reset_
logging_ ⚠callback_ unchecked - Reset a logger on versions without synchronized replacement.
- resolve_
config_ path - Resolve an OCIO configuration path to its current persistent form.
- set_
compute_ ⚠hash_ callback - Install a process-global OCIO compute-hash callback.
- set_
current_ config Deprecated - Installs
configas the process-global current OCIO config. - set_
env_ ⚠variable - Set an OCIO process environment variable.
- set_
logging_ callback - Install a process-global Rust callback for OCIO log messages.
- set_
logging_ ⚠callback_ unchecked - Install a logger even on versions whose logger replacement is not synchronized.
- set_
logging_ level Deprecated - Sets the OCIO global logging level.
- set_
logging_ level_ to_ override Deprecated - Compatibility alias for overriding the OCIO global logging level.
- set_
processor_ ⚠cache_ flags Deprecated - Updates the processor cache flags on the current global config, if any.
- try_
clear_ all_ caches - Try to clear OCIO’s process-global caches.
- try_
const_ ⚠current_ config - Return a separate read-only snapshot of the process-global config.
- try_
const_ ⚠current_ config_ shared - Retain the native global config without copying it.
- try_
current_ ⚠config - Try to get the process-global current OCIO config.
- try_
current_ ⚠config_ native_ copy - Return OCIO’s native editable copy of the process-global config.
- try_
log_ message - Send a message through OCIO’s configured logging function.
- try_
logging_ level - Get the global logging level, reporting attempts to reenter from a callback.
- try_
set_ const_ current_ config - Install a shared read-only config as the process-global current config.
- try_
set_ current_ config - Try to install
configas the process-global current OCIO config. - try_
set_ logging_ level - Try to set the OCIO global logging level.
- try_
set_ ⚠processor_ cache_ flags - Try to update processor-cache flags on the current global config.
- unset_
env_ ⚠variable - Remove an OCIO process environment variable.
- version
- Returns the linked OpenColorIO version string, if available.
- version_
hex - Returns the linked OpenColorIO version as an integer hex constant.
Type Aliases§
- Result
- Crate-local result alias used by the safe wrapper layer.