Skip to main content

Crate ocio_rs

Crate ocio_rs 

Source
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

ModeFeature flagNotes
Stub (default)--no-default-featuresAPIs return safe defaults; no real color management
System--features systemRequires installed OpenColorIO and pkg-config
Bundled--features bundledBuilds 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 Config using OCIO’s baker API.
BuiltinConfigRegistry
Enumerates built-in OCIO configurations bundled with the upstream library.
BuiltinTransformRegistry
Enumerates the built-in transform styles provided by the linked OCIO build.
CPUProcessor
CPU implementation of a Processor.
ColorSpace
Describes a color space definition stored in a Config.
ColorSpaceMenuHelper
Read-only native color-space menu. Strings borrow the menu’s storage.
ColorSpaceMenuParameters
Mutable native options used to construct a color-space menu.
ColorSpaceSet
Mutable collection of ColorSpace handles used by OCIO set-style APIs.
Config
An OpenColorIO configuration.
ConfigIOProxy
Provider for OCIO config text and LUT file payloads.
ConfigMergerv2_5
An owned OCIOM merge controller. Returned params and configs are editable copies.
ConfigMergingParametersv2_5
Owned native configuration merge parameters.
ConstColorSpace
An owned, read-only reference to a native OCIO color space.
ConstColorSpaceSet
Read-only native result of a color-space set operation.
ConstConfig
Shared immutable native configuration, independent of later global replacement.
ConstConfigMergerv2_5
A retained read-only merger returned by native OCIO.
ConstContext
Shared, read-only OCIO context. Queries return owned text because a config may update its current context while this handle remains alive.
ConstFileRules
Shared read-only file rules. Text is borrowed from the native rules object.
ConstFormatMetadata
Shared read-only metadata retained by an OCIO processor or transform.
ConstGradingBSplineCurve
Borrowed read-only spline owned by a grading curve set.
ConstLook
Shared read-only native look. Borrowed text remains valid while this object is alive, provided external native code does not mutate the same object.
ConstNamedTransform
Shared read-only native named transform. Borrowed text remains valid while this object is alive, provided external native code does not mutate it.
ConstProcessorMetadata
Shared read-only native processor metadata.
ConstViewTransform
Shared read-only native view transform. Borrowed text remains valid while this object is alive, provided external native code does not mutate it.
ConstViewingRules
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.
CustomImageLayout
Interleaved image with independent channel offsets within each pixel.
DisplayViewFromFile
Inputs to the native helper that authors a display view from a transform file.
DynamicProperty
References a processor property that may be adjusted dynamically at runtime.
FileRules
Holds filename-based routing rules that map media paths to color spaces.
FormatMetadata
Structured metadata attached to transforms and baked outputs.
GPUProcessor
GPU implementation of a Processor.
GpuShaderCreator
A native OCIO shader creator with its real shared-ownership control block.
GpuShaderDesc
Collects parameters and emitted source for GPU shader extraction.
GpuShaderDescView
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.
GpuUniformCache
Cached OCIO uniform getters for repeated sampling without bridge allocations.
GradingBSplineCurve
An independently owned native OCIO grading spline.
GradingHueCurvev2_5
An independently owned native HUE grading curve set.
GradingRGBCurve
An independently owned native RGB grading curve set.
LegacyViewingPipeline
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.
MixingColorSpaceManager
Native mixing space and encoding selection.
MixingSlider
An exclusive borrow of the native manager’s slider, without an allocation.
NamedTransform
Names a reusable transform pair inside a config for interchange and lookup.
NativeImageDataPointers
First-pixel addresses returned by OCIO without reading pixel contents.
NativeImageDesc
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.
NativeImageDescInfo
Snapshot of a native image descriptor. This does not expose buffer addresses or certify that the descriptor is safe to process.
OptimizationFlags
Bit flags selecting processor optimization passes.
PackedConversionLayout
Packed source and destination layout for native-depth conversion.
PackedImageLayout
Packed image layout with signed pixel and row strides, in bytes.
PersistentPolicyCreator
A native creator whose Rust texture policy remains attached between calls.
PlanarByteLayout
Positive byte strides and native channel bit depth for a planar image.
PlanarBytes
Borrowed source channels for a planar conversion.
PlanarBytesMut
Borrowed destination channels for a planar conversion.
PlanarF32Layout
Positive F32 element strides for a planar image.
Processor
An immutable color-processing pipeline produced from a Config.
ProcessorCacheFlags
Bit flags controlling config-level processor-cache behavior.
ProcessorMetadata
Technical metadata collected while OCIO builds a processor.
ShaderCreatorOptions
Options for extracting with custom creator resource handling.
ShaderSections
Shader sections supplied by OCIO to a custom assembler during extraction.
ShaderTexture
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.
ShaderUniform
A uniform registered by OCIO during custom shader extraction.
ShaderUniformGetter
An owned live native uniform getter received during custom registration.
ShaderUniformRegistration
A native uniform registration request and its independently owned getter.
SharedGradingBSplineCurve
Read-only native shared spline that can outlive its original curve set.
SharedGradingHueCurvev2_5
A retained read-only OCIO hue curve value, without a deep copy.
SharedGradingRGBCurve
A retained read-only OCIO RGB curve value, without a deep copy.
SignedPlanarByteLayout
A planar image layout with signed byte strides and an origin in each plane.
SignedPlanarBytes
Immutable planar input with signed byte strides.
SignedPlanarBytesMut
Exclusively borrowed planar image with signed byte strides.
StaticCPUProcessor
A CPU processor proven to contain no dynamic properties.
SystemMonitors
Native operating-system monitor profile snapshot.
ViewTransform
A scene-to-display or display-to-scene view transform entry.
ViewWithAliasesv2_6
Borrowed arguments for authoring a display or shared view with aliases.
ViewingRules
Holds OCIO viewing rules used to select active views for color spaces.

Enums§

Allocation
Allocation domain used to map image values for processing.
BSplineTypev2_5
Type of the monotonic or periodic native grading spline.
BitDepth
Pixel sample bit depth understood by OCIO processors.
CDLStyle
ASC CDL clamping behavior.
ChannelOrdering
Channel memory ordering for OCIO packed image descriptors.
ColorSpaceDirection
Direction between a color space and its reference space.
ColorSpaceRef
Borrowed editable or read-only color space for OCIO operations.
ColorSpaceSetRef
A borrowed editable or read-only color-space set.
ColorSpaceVisibility
Visibility filter for color-space enumeration.
ConfigProcessorTarget
Destination of a processor connecting two read-only configurations.
ConfigRef
Borrow an editable or shared read-only configuration for native queries.
DynamicPropertyType
Runtime-adjustable OCIO processor property kind.
EnvironmentMode
Policy used to populate OCIO context variables from the environment.
ExposureContrastStyle
Domain in which exposure/contrast parameters are applied.
FixedFunctionStyle
Built-in OCIO fixed-function transform style.
GpuLanguage
Target shading language for OCIO GPU shader extraction.
GpuTextureChannel
Channel layout used by extracted 1D/2D GPU texture payloads.
GpuTextureDimensions
Dimensionality metadata for extracted 1D/2D GPU texture payloads.
GpuUniformCopy
Result of copying a cached live uniform into caller-owned storage.
GpuUniformType
Uniform value encoding reported by OCIO GPU shader extraction.
GpuUniformValue
Typed value payload for a GPU uniform extracted from OCIO.
GradingStyle
Grading domain used by OCIO grading transforms and values.
HSYTransformStylev2_5
HSY conversion style used by hue-curve operations.
HueCurveTypev2_5
One of OCIO’s hue-dependent grading curve families.
ImageDescChannel
Logical pixel channel queried by a Rust-defined native descriptor.
Interpolation
Interpolation algorithm used by LUT and related transforms.
LegacyViewingStage
Transform slots exposed by the native legacy viewing pipeline.
LoggingLevel
Verbosity level for OCIO’s process-global diagnostic logging.
Lut1DHueAdjust
Hue adjustment mode for one-dimensional LUT transforms.
MergeStrategyv2_5
Conflict policy used by OpenColorIO when merging a configuration section.
NamedTransformVisibility
Visibility filter for named-transform enumeration.
NativeImageLayout
Concrete layout of an existing OCIO image descriptor.
NegativeStyle
Treatment of negative values for transforms that require a policy.
OcioError
Unified error type for safe ocio-rs operations.
RGBCurveType
One of the RGB or master curves in a grading RGB curve transform.
RangeStyle
Whether a range transform clamps values at its domain boundaries.
ReferenceSpaceType
Reference space domain used by a color space or view transform.
SearchReferenceSpaceType
Domain filter used when searching for a color space.
ShaderCodeSection
Native shader code section currently being appended.
ShaderLifecycle
Lifecycle stages of a native shader-creator extraction.
ShaderTextureAction
Storage and optional binding choice for one native texture registration.
ShaderUniformAction
How a custom creator handles a native uniform registration request.
TransformDirection
Direction in which an OCIO transform or processor is evaluated.
TransformType
Runtime OCIO transform subtype represented by a generic transform handle.
ViewTransformDirection
Direction between a view transform and its reference space.
ViewType
Origin of a display/view entry in a config.

Traits§

ConfigIOProvider
On-demand provider for the OCIO config and its referenced LUTs.
ImageDescProvider
Implements OCIO’s virtual image descriptor getters in Rust.
OcioEnumText
Native OCIO text conversion for an enum or boolean.
ShaderCacheIdPolicy
Supplies the native creator’s cache ID during an opted-in query or extraction.
ShaderClonePolicy
Supplies the result of the native creator clone operation.
ShaderExtractionHooks
Synchronous customization hooks for OCIO shader extraction.
ShaderFinalizeControl
Optional synchronous replacement for OCIO’s native shader finalization stage.
ShaderTextureControl
Controls storage and binding of each texture registered by a persistent creator.
ShaderTexturePolicy
Synchronous policy for OCIO’s native texture-width and 1D-texture getters.
ShaderUniformControl
Custom control over native uniform registration during shader extraction.

Functions§

clear_all_cachesDeprecated
Clears OCIO’s process-global caches.
current_config⚠
Returns the process-global current OCIO config, if one is installed.
extract_ocioz_archive
Extract an .ocioz archive 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 true when the crate was built in stub mode instead of linking a real OpenColorIO implementation.
logging_level
Returns the current OCIO global logging level, or Unknown when called reentrantly from a logging callback. Use try_logging_level to distinguish that case.
metadata_id_elementv2_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_configDeprecated
Installs config as 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_levelDeprecated
Sets the OCIO global logging level.
set_logging_level_to_overrideDeprecated
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 config as 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.