ocio-rs
Rust bindings for OpenColorIO.
Version 0.4 supports OpenColorIO >= 2.4.1, < 2.7 (newer APIs are
opt-in via the v2_5 and v2_6 Cargo features; see Compatibility below).
The core OCIO Rust wrapper surface
is now broadly in place, including bundled real-OCIO builds, bridge parity
across the exposed API surface, and broad safe-wrapper coverage. The remaining
work is mostly release hardening and longer-tail behavioral validation rather
than missing core binding coverage.
Breaking API updates are tracked in docs/MIGRATION.md.
Recent bundled validation now covers more than linkability and smoke tests for several high-use runtime paths, including:
Configmulti-config/display-view behavior and virtual/shared-view metadataFileRulesinsertion, regex/custom-key round trips, and config attachmentViewingRulessafe wrapper behavior, editable-copy independence, and config attachmentDynamicPropertyruntime behavior acrossProcessor,CPUProcessor, and extracted GPU descriptorsGpuShaderDescextraction structure, resource metadata, creator settings, descriptor-side dynamic-property access, manual shader-text assembly, and manual texture and uniform insertionCPUProcessorpacked/pixel execution paths, including stride-preserving behavior forRGB(A)buffers
For a system OpenColorIO installation:
[]
= { = "0.4", = ["system"] }
This configuration uses an installed OpenColorIO. Distribution packages and
plugins such as GStreamer should normally use this backend. For shared-library
linking, set OCIO_RS_LINK=dynamic in the build environment and install the
OpenColorIO development package plus pkg-config. For a source build instead,
use features = ["bundled"]. Add "v2_5" only when your code needs 2.5 APIs.
The 0.4 interface and breaking changes are described in the
migration notes; 0.3 supports OCIO versions below 2.6.
Build
cargo build uses deterministic stub mode by default, where APIs return
safe defaults for API-shape testing and CI but perform no real color
management. Stub builds
report their OCIO-dependent tests as ignored rather than passed, so a green run
is never mistaken for a verified one.
Real OCIO mode:
# Build the vendored OCIO source and link statically
# Build bundled OCIO as shared libraries
OCIO_RS_LINK=dynamic
# Use a pre-installed OCIO discoverable through pkg-config
# Legacy equivalent retained for compatibility
OCIO_RS_ENABLE_REAL=1
# Use a pre-installed OCIO from a custom prefix
OCIO_INSTALL_DIR=/path/to/ocio
# Use a pre-installed shared OCIO library instead of static libs
OCIO_INSTALL_DIR=/path/to/ocio OCIO_RS_LINK=dynamic
# Force the default stub backend explicitly for legacy scripts
OCIO_RS_ENABLE_REAL=0
OCIO_SOURCE_DIR is currently only consumed by the bundled build path; setting
it by itself does not enable real OCIO mode.
Installed mode accepts OpenColorIO >= 2.4.1, < 2.7, raised to
>= 2.5.1, < 2.7 by v2_5 and >= 2.6.0, < 2.7 by v2_6. It first probes
opencolorio / OpenColorIO through pkg-config. OCIO_INSTALL_DIR prepends
the prefix's lib/pkgconfig, lib64/pkgconfig, and share/pkgconfig
directories; for older installations without a .pc file, the conventional
include, lib, and lib64 layout remains supported. PKG_CONFIG_PATH can
also be set directly.
Backend features are additive, as Cargo requires for dependency unification:
no backend feature is deterministic stub mode, system requires an installed
library, and bundled adds the source-build Adapter and takes precedence when
combined with system. OCIO_RS_ENABLE_REAL=0/1 remains as a legacy adapter,
but invalid values and conflicts with real-backend features fail the build.
The bundled feature builds the vendored source by default, preserving its
historical behavior. Set
SYSTEM_DEPS_OPENCOLORIO_BUILD_INTERNAL=auto to prefer a compatible installed
OpenColorIO and fall back to the bundled source only when probing fails.
Installed-library discovery requires a pkg-config executable. The bundled
source build describes its own install prefix directly and does not require
pkg-config, including on Windows.
OCIO_RS_LINK defaults to static for compatibility. Set it to dynamic
(shared and dylib are also accepted) when OCIO_INSTALL_DIR points at an
OpenColorIO install with shared libraries. Make sure your platform loader can
find the OCIO runtime library at execution time, for example via
LD_LIBRARY_PATH, DYLD_LIBRARY_PATH, PATH, or your package manager's normal
runtime setup.
The ocio-sys package vendors the upstream OpenColorIO source tree
plus the transitive dependency sources used by the current bundled build
configuration. The packaged ocio-sys crate is validated with
cargo build --features bundled --offline during release hardening, after
Cargo's Rust dependency cache has been populated.
Examples
# Stub-friendly API walkthrough
# Load a real sample config and run CPU processing
# Verify real processing without external config files
OCIO_RS_LINK=dynamic
Architecture
ocio-rs/
├── ocio-sys/ C++ bridge • stub/real dual mode • auto-generated
├── src/ Safe Rust wrappers
├── tools/generator/ Code generator (from OCIO headers)
├── tests/ Integration tests
└── benches/ Benchmarks
Compatibility
The baseline API works with OpenColorIO >= 2.4.1, < 2.7. API added in newer OCIO
versions is opt-in through additive vX_Y cargo features; enabling one raises
the version requirement checked against the OpenColorIO resolved at build
time, failing with a clear error on mismatch.
| feature | OCIO API level | gates |
|---|---|---|
| (none) | 2.4.1 | everything else |
v2_5 |
2.5.1 | hue-curve grading, interchange attributes, view/display list management, GPU uniform buffers and shader binding indexes |
v2_6 |
2.6.0 | display/view aliases, color interop lookup, HDR compatibility, HMJ fixed function and CLF ID metadata |
v2_6 implies v2_5. Use system,v2_6 with an installed 2.6 library or
bundled,v2_6 with OCIO_SOURCE_DIR pointing to a 2.6 source checkout.
The vendored 2.5.2 source remains the default for builds without v2_6.
With native 2.5.0, the baseline interface remains available, but texture
insertion does not report a shader binding index: upstream returns a per-kind
texture index and does not provide the binding-query virtual methods added in
2.5.1. Enable v2_5 with 2.5.1 or newer for the binding APIs.
The vendored 2.5.2 source includes a fix for an upstream multi-row GPU LUT
packing error; installed libraries and external source overrides do not
inherit it. For an unpatched external build with unknown LUT lengths, use
GPUProcessor::try_extract_shader_info_checked or
validate_shader_texture_layout before custom extraction. These conservative
checks generate shader resources twice, may reject non-LUT textures, and
require resource-generating state to remain unchanged between the probe and
extraction. Ordinary extraction retains native behavior.
Vendored OCIO per release:
| ocio-rs | OCIO |
|---|---|
| 0.4.0 | v2.5.2 |
| 0.3.0 | v2.5.2 |
| 0.2.1 | v2.5.2 |
| 0.2.0 | v2.5.2 |
| 0.1.1 | v2.5.2 |
| 0.1.0 | v2.5.1 |
OCIO upgrade workflow: update submodule -> run code generator -> fix compile errors -> release.
main is the default branch and release line. Development pull requests target
develop; releases are promoted from develop to main. See
CONTRIBUTING.md for checks and branch conventions.
See STATUS.md for the current validation matrix and the remaining release caveats for specific runtime paths.
License
OpenColorIO is a trademark of the Academy Software Foundation. This project is not affiliated with ASWF.