Skip to main content

GPUProcessor

Struct GPUProcessor 

Source
pub struct GPUProcessor { /* private fields */ }
Expand description

GPU implementation of a Processor.

Wraps a GPU-ready color pipeline and provides extract_shader_info to populate a GpuShaderDesc with OCIO-generated shader text, textures, and uniforms.

The typical usage is:

let config = Config::from_file("config.ocio")?;
let processor = config.processor("scene_linear", "srgb_texture")?;
let gpu = processor.default_gpu_processor()?;

let mut desc = GpuShaderDesc::create()?;
desc.set_language(GpuLanguage::Glsl1_2)?;

gpu.try_extract_shader_info(&mut desc)?;

let shader_text = desc.shader_text().unwrap_or_default();
// Use shader_text in your rendering pipeline...

This handle is thread-confined; see Processor.

ⓘ
fn require_send<T: Send>() {}
require_send::<GPUProcessor>();

Implementations§

Source§

impl GPUProcessor

Source

pub fn try_extract_to_creator( &self, creator: &mut GpuShaderCreator<'_>, ) -> Result<()>

Extract through the native creator overload using shared ownership. OCIO may leave partially generated state on failure.

Source

pub fn try_extract_with_assembler<F>( &self, template: &GpuShaderDesc, assemble: F, ) -> Result<GpuShaderDesc>
where F: FnMut(ShaderSections<'_>) -> Result<String>,

Extract a fresh descriptor while assembling its shader text in Rust.

The template supplies language, resource names, binding settings and texture preferences; existing template resources are not copied. OCIO retains ownership of resources and live dynamic properties in the result. The callback runs synchronously and must return the complete shader text. Callback errors and panics are returned as errors without crossing FFI. OCIO holds its GPU processor lock during the callback; do not reenter extraction on the same processor. For Vulkan, the callback must include any desired uniform-buffer wrapper around parameters itself.

let desc = gpu.try_extract_with_assembler(template, |parts| {
    Ok(format!("// custom\n{}{}{}{}{}{}", parts.parameters, parts.textures,
        parts.helpers, parts.header, parts.body, parts.footer))
})?;
assert!(desc.shader_text().unwrap().starts_with("// custom"));
Source

pub fn try_extract_with_texture_callback<F, G>( &self, template: &GpuShaderDesc, assemble: F, texture: G, ) -> Result<GpuShaderDesc>

Extract a shader with synchronous Rust assembly and texture callbacks.

The texture callback receives a temporary borrow of each native LUT and may return Some(binding) to override OCIO’s proposed binding on 2.5+. Return None to keep the native binding; OCIO 2.4 requires None. Binding zero and duplicate bindings are rejected. Callback errors and panics abort extraction, but external uploads already performed by the callback remain the caller’s responsibility. Do not reenter extraction on this GPU processor from either callback.

Borrowed texture values cannot escape the callback:

ⓘ
let mut saved = None;
let _ = gpu.try_extract_with_texture_callback(template,
    |_| Ok(String::new()), |texture| { saved = Some(texture.values); Ok(None) });
println!("{:?}", saved);
Source

pub fn try_extract_with_resource_callbacks<F, G, H>( &self, template: &GpuShaderDesc, assemble: F, texture: G, uniform: H, ) -> Result<GpuShaderDesc>

Extract with synchronous shader assembly, texture, and uniform callbacks.

Uniform events are sent only for newly registered uniforms, before shader assembly. Use the reported index to query current dynamic values from the returned descriptor; OCIO retains the getters. Names are borrowed only for the callback. OCIO 2.4 does not expose vector maximum sizes or uniform-buffer offsets. Callback errors and panics abort extraction; already performed external resource allocations remain the caller’s responsibility. Do not reenter extraction on this GPU processor from any callback.

ⓘ
let mut saved = None;
let _ = gpu.try_extract_with_resource_callbacks(desc, |_| Ok(String::new()),
    |_| Ok(None), |uniform| { saved = Some(uniform.name); Ok(()) });
println!("{:?}", saved);
Source

pub fn try_extract_with_lifecycle_callbacks<F, G, H, L>( &self, template: &GpuShaderDesc, assemble: F, texture: G, uniform: H, lifecycle: L, ) -> Result<GpuShaderDesc>

Extract with shader, texture, uniform, and creator-lifecycle callbacks.

Events occur synchronously in OCIO order: Begin, zero or more resource callbacks, shader assembly, Finalized, then End. If an extraction callback fails after Begin, OCIO still calls End; an error from Begin itself does not trigger End. The first callback error is preserved if cleanup also fails. IDs are borrowed for the callback only. Do not reenter extraction on this processor.

ⓘ
let mut saved = None;
let _ = gpu.try_extract_with_lifecycle_callbacks(desc, |_| Ok(String::new()),
    |_| Ok(None), |_| Ok(()), |event| {
        if let ShaderLifecycle::Begin { unique_id } = event { saved = Some(unique_id); }
        Ok(())
    });
println!("{:?}", saved);
Source

pub fn try_extract_with_hooks<H: ShaderExtractionHooks>( &self, template: &GpuShaderDesc, hooks: &mut H, ) -> Result<GpuShaderDesc>

Extract using a single hooks object for code, resources, and lifecycle.

Events are synchronous; callback errors and panics abort extraction and any already-created external resources remain the caller’s responsibility. On OCIO 2.4 declaration events are combined into Declarations.

Source

pub fn try_extract_with_streamed_textures<H, T>( &self, template: &GpuShaderDesc, hooks: &mut H, texture: T, ) -> Result<GpuShaderDesc>

Extract using hooks while streaming texture data directly to the caller.

The required texture sink must upload or copy the borrowed data before it returns; the returned descriptor does not retain or report these textures. Uniforms and shader text remain available on the descriptor. On failure, cleanup of any resources created by hooks is the caller’s responsibility. The hooks object’s texture method is not called; binding overrides come from the supplied sink.

ⓘ
let mut saved = None;
let _ = gpu.try_extract_with_streamed_textures(desc, &mut Hooks, |texture| {
    saved = Some(texture.values);
    Ok(None)
});
println!("{saved:?}");
Source

pub fn try_extract_with_uniform_control<H: ShaderUniformControl>( &self, template: &GpuShaderDesc, hooks: &mut H, ) -> Result<GpuShaderDesc>

Extract using hooks that control native uniform registration.

External uniforms are not included in the descriptor’s uniform list or buffer offsets. The caller must retain their getters and manage storage, layout and cleanup. Callback errors and panics abort extraction; owned getters already transferred to the caller remain usable. Do not reenter extraction on the same GPU processor from a callback.

Source

pub fn try_extract_with_uniform_control_and_streamed_textures<H, T>( &self, template: &GpuShaderDesc, hooks: &mut H, texture: T, ) -> Result<GpuShaderDesc>

Control uniform registration and stream textures in the same extraction.

External uniforms and streamed textures are not enumerated by the returned descriptor. The sink must copy or upload each texture before returning, and retained uniform getters keep their native owner alive. As with Self::try_extract_with_streamed_textures, the hooks object’s texture method is not called. Callers own cleanup on failure.

Source

pub fn try_extract_with_creator_options<H, T>( &self, template: &GpuShaderDesc, hooks: &mut H, options: ShaderCreatorOptions<'_>, texture: T, ) -> Result<GpuShaderDesc>

Extract with custom registration, texture handling and creator options.

The texture callback receives each LUT synchronously whether or not streaming is selected. In streaming mode it must copy or upload the borrowed data before returning. A custom cache ID remains in effect on the returned descriptor; see ShaderCreatorOptions for invalidation responsibility. Callback and external resource cleanup rules are the same as Self::try_extract_with_uniform_control_and_streamed_textures.

Source

pub fn try_extract_with_texture_control<H, T>( &self, template: &GpuShaderDesc, hooks: &mut H, cache_id_override: Option<&CStr>, texture: T, ) -> Result<GpuShaderDesc>

Choose storage separately for each texture and control uniform registration.

External textures are not returned by the descriptor; their data must be copied or uploaded before the callback returns. On 2.5+, bindings are shared across all texture types, including external textures. A binding override is not supported on 2.4. Callback errors and panics abort extraction; external resources already created remain the caller’s responsibility. The hooks object’s texture method is not called. Do not reenter extraction.

Source

pub fn try_extract_with_finalize_control<H, T>( &self, template: &GpuShaderDesc, hooks: &mut H, cache_id_override: Option<&CStr>, texture: T, ) -> Result<GpuShaderDesc>

Extract with independent texture/uniform storage and optional custom finalization.

A custom finalizer receives control before OCIO performs its language wrapping. It must return a complete shader, including any required declarations and language-specific wrappers. Returning None delegates finalization and assembly to the ordinary native path. This control is scoped to the extraction and is not retained by the returned descriptor. Finalizer errors and panics abort extraction; already-created external resources remain the caller’s responsibility. Do not reenter extraction from callbacks.

Source

pub fn try_extract_with_texture_policy<H, P, T>( &self, template: &GpuShaderDesc, hooks: &mut H, policy: &mut P, cache_id: &CStr, texture: T, ) -> Result<GpuShaderDesc>

Extract with independently controlled texture policy, resource storage, uniforms and finalization. Policy callbacks are synchronous and detached on every return path. Do not reenter the same processor from callbacks.

The native width getter is noexcept: on a callback failure or panic, extraction uses a conservative temporary fallback and then returns the original error. Other callbacks and external uploads may have occurred before failure and their cleanup remains the caller’s responsibility. Policy values may vary during extraction, so a template-only layout probe cannot prove them safe; consider Self::try_extract_with_texture_policy_checked. cache_id must be nonempty and uniquely represent the policy and output; update it whenever they change to avoid native resource-key collisions.

Source

pub fn try_extract_with_texture_policy_checked<H, P, T>( &self, template: &GpuShaderDesc, hooks: &mut H, policy: &mut P, cache_id: &CStr, texture: T, ) -> Result<GpuShaderDesc>

Conservatively probe optimized texture lengths, then validate every width returned by policy against every probed length before OCIO uses it.

This generates the shader twice and may reject non-LUT 1D/2D resources. It relies on the native 2.4–2.6 LUT length limit and does not validate newer versions or arbitrary native creators. The processor and any state capable of changing generated resources must remain unchanged across the probe and actual extraction, including inside user callbacks. External resources created before a later policy error remain caller-owned. cache_id has the same requirements as on Self::try_extract_with_texture_policy.

Source

pub fn is_no_op(&self) -> bool

Return whether the GPU path is an identity/no-op transform.

Returns false if OCIO reports an error. Use Self::try_is_no_op to distinguish that case from a non-identity processor.

Source

pub fn try_is_no_op(&self) -> Result<bool>

Fallible variant of Self::is_no_op.

Returns an error when the underlying OCIO query throws.

Source

pub fn has_channel_crosstalk(&self) -> bool

Return whether the GPU path mixes color channels.

Returns false if OCIO reports an error. Use Self::try_has_channel_crosstalk to distinguish that case from a lane-wise processor.

Source

pub fn try_has_channel_crosstalk(&self) -> Result<bool>

Fallible variant of Self::has_channel_crosstalk.

Returns an error when the underlying OCIO query throws.

Source

pub fn cache_id(&self) -> Option<String>

Return OCIO’s cache identifier for this GPU processor instance.

Source

pub fn try_cache_id(&self) -> Result<Option<String>>

Return OCIO’s cache identifier, preserving bridge errors.

Source

pub fn extract_shader_info(&self, shader_desc: &mut GpuShaderDesc)

👎Deprecated since 0.2.0:

panics on OCIO errors; prefer try_extract_shader_info()

Fill shader_desc with OCIO-generated shader text, uniforms, and textures.

Panics when OCIO rejects extraction. Use Self::try_extract_shader_info when extraction failures should be handled by the caller.

Source

pub fn try_extract_shader_info( &self, shader_desc: &mut GpuShaderDesc, ) -> Result<()>

Try to fill shader_desc with OCIO-generated shader text, uniforms, and textures.

This calls the native generator directly. The repository’s vendored source fixes the multi-row LUT allocation. When linking an unpatched system library or building from unpatched external source, use Self::try_extract_shader_info_checked for untrusted or unknown LUT lengths.

Source

pub fn try_extract_shader_info_checked( &self, shader_desc: &mut GpuShaderDesc, ) -> Result<()>

Probe optimized texture resources before extracting into shader_desc.

Unpatched OCIO 2.4–2.6 can underflow while packing some 1D LUT lengths into 2D textures. This check remains conservative with the patched vendored source. The probe uses a temporary descriptor wide enough for every 1D LUT accepted by these versions, streams its textures without storing them, and checks their lengths against the requested width before the real extraction. The target descriptor is untouched if probing fails.

On OCIO 2.5+, it also checks the binding range needed by the probed textures and the target’s existing textures before modifying the target. This assumes resource generation does not change between the probe and extraction; custom descriptors with noncontiguous bindings may be rejected conservatively. It does not validate arbitrary native creators.

This performs shader generation twice and allocates OCIO’s temporary texture data. It conservatively checks all 1D/2D resources with height one, including non-LUT resources, so it can reject a safe processor. It relies on the 1,048,576-entry limit of supported OCIO 2.4–2.6 and must be re-audited before supporting a newer native version.

Source

pub fn validate_shader_texture_layout( &self, shader_desc: &GpuShaderDesc, ) -> Result<()>

Conservatively check the optimized processor’s texture layouts before extraction with template. This performs a probe extraction, but does not invoke the caller’s shader hooks or retain probe textures.

The probe has the cost and version/false-positive limitations documented on Self::try_extract_shader_info_checked. It may be followed by any of this library’s synchronous custom extraction APIs using the same processor and unchanged template settings. It does not validate arbitrary native creators with independently implemented texture-policy methods.

gpu.validate_shader_texture_layout(template)?;
let shader = gpu.try_extract_with_hooks(template, hooks)?;

Trait Implementations§

Source§

impl Drop for GPUProcessor

Source§

fn drop(&mut self)

Executes the destructor for this type. Read more
Source§

fn pin_drop(self: Pin<&mut Self>)

🔬This is a nightly-only experimental API. (pin_ergonomics)
Execute the destructor for this type, but different to Drop::drop, it requires self to be pinned. Read more

Auto Trait Implementations§

Blanket Implementations§

Source§

impl<T> Any for T
where T: 'static + ?Sized,

Source§

fn type_id(&self) -> TypeId

Gets the TypeId of self. Read more
Source§

impl<T> Borrow<T> for T
where T: ?Sized,

Source§

fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more
Source§

impl<T> BorrowMut<T> for T
where T: ?Sized,

Source§

fn borrow_mut(&mut self) -> &mut T

Mutably borrows from an owned value. Read more
Source§

impl<T> From<T> for T

Source§

fn from(t: T) -> T

Returns the argument unchanged.

Source§

impl<T, U> Into<U> for T
where U: From<T>,

Source§

fn into(self) -> U

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

Source§

impl<T, U> TryFrom<U> for T
where U: Into<T>,

Source§

type Error = !

The type returned in the event of a conversion error.
Source§

fn try_from(value: U) -> Result<T, !>

Performs the conversion.
Source§

impl<T, U> TryInto<U> for T
where U: TryFrom<T>,

Source§

type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.
Source§

fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>

Performs the conversion.