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
impl GPUProcessor
Sourcepub fn try_extract_to_creator(
&self,
creator: &mut GpuShaderCreator<'_>,
) -> Result<()>
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.
Sourcepub fn try_extract_with_assembler<F>(
&self,
template: &GpuShaderDesc,
assemble: F,
) -> Result<GpuShaderDesc>
pub fn try_extract_with_assembler<F>( &self, template: &GpuShaderDesc, assemble: F, ) -> Result<GpuShaderDesc>
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"));Sourcepub fn try_extract_with_texture_callback<F, G>(
&self,
template: &GpuShaderDesc,
assemble: F,
texture: G,
) -> Result<GpuShaderDesc>where
F: FnMut(ShaderSections<'_>) -> Result<String>,
G: FnMut(ShaderTexture<'_>) -> Result<Option<u32>>,
pub fn try_extract_with_texture_callback<F, G>(
&self,
template: &GpuShaderDesc,
assemble: F,
texture: G,
) -> Result<GpuShaderDesc>where
F: FnMut(ShaderSections<'_>) -> Result<String>,
G: FnMut(ShaderTexture<'_>) -> Result<Option<u32>>,
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);Sourcepub fn try_extract_with_resource_callbacks<F, G, H>(
&self,
template: &GpuShaderDesc,
assemble: F,
texture: G,
uniform: H,
) -> Result<GpuShaderDesc>where
F: FnMut(ShaderSections<'_>) -> Result<String>,
G: FnMut(ShaderTexture<'_>) -> Result<Option<u32>>,
H: FnMut(ShaderUniform<'_>) -> Result<()>,
pub fn try_extract_with_resource_callbacks<F, G, H>(
&self,
template: &GpuShaderDesc,
assemble: F,
texture: G,
uniform: H,
) -> Result<GpuShaderDesc>where
F: FnMut(ShaderSections<'_>) -> Result<String>,
G: FnMut(ShaderTexture<'_>) -> Result<Option<u32>>,
H: FnMut(ShaderUniform<'_>) -> Result<()>,
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);Sourcepub fn try_extract_with_lifecycle_callbacks<F, G, H, L>(
&self,
template: &GpuShaderDesc,
assemble: F,
texture: G,
uniform: H,
lifecycle: L,
) -> Result<GpuShaderDesc>where
F: FnMut(ShaderSections<'_>) -> Result<String>,
G: FnMut(ShaderTexture<'_>) -> Result<Option<u32>>,
H: FnMut(ShaderUniform<'_>) -> Result<()>,
L: FnMut(ShaderLifecycle<'_>) -> Result<()>,
pub fn try_extract_with_lifecycle_callbacks<F, G, H, L>(
&self,
template: &GpuShaderDesc,
assemble: F,
texture: G,
uniform: H,
lifecycle: L,
) -> Result<GpuShaderDesc>where
F: FnMut(ShaderSections<'_>) -> Result<String>,
G: FnMut(ShaderTexture<'_>) -> Result<Option<u32>>,
H: FnMut(ShaderUniform<'_>) -> Result<()>,
L: FnMut(ShaderLifecycle<'_>) -> Result<()>,
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);Sourcepub fn try_extract_with_hooks<H: ShaderExtractionHooks>(
&self,
template: &GpuShaderDesc,
hooks: &mut H,
) -> Result<GpuShaderDesc>
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.
Sourcepub fn try_extract_with_streamed_textures<H, T>(
&self,
template: &GpuShaderDesc,
hooks: &mut H,
texture: T,
) -> Result<GpuShaderDesc>
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:?}");Sourcepub fn try_extract_with_uniform_control<H: ShaderUniformControl>(
&self,
template: &GpuShaderDesc,
hooks: &mut H,
) -> Result<GpuShaderDesc>
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.
Sourcepub fn try_extract_with_uniform_control_and_streamed_textures<H, T>(
&self,
template: &GpuShaderDesc,
hooks: &mut H,
texture: T,
) -> Result<GpuShaderDesc>
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.
Sourcepub fn try_extract_with_creator_options<H, T>(
&self,
template: &GpuShaderDesc,
hooks: &mut H,
options: ShaderCreatorOptions<'_>,
texture: T,
) -> Result<GpuShaderDesc>
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.
Sourcepub fn try_extract_with_texture_control<H, T>(
&self,
template: &GpuShaderDesc,
hooks: &mut H,
cache_id_override: Option<&CStr>,
texture: T,
) -> Result<GpuShaderDesc>
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.
Sourcepub fn try_extract_with_finalize_control<H, T>(
&self,
template: &GpuShaderDesc,
hooks: &mut H,
cache_id_override: Option<&CStr>,
texture: T,
) -> Result<GpuShaderDesc>
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.
Sourcepub 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>where
H: ShaderFinalizeControl + ?Sized,
P: ShaderTexturePolicy + ?Sized,
T: FnMut(ShaderTexture<'_>) -> Result<ShaderTextureAction>,
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>where
H: ShaderFinalizeControl + ?Sized,
P: ShaderTexturePolicy + ?Sized,
T: FnMut(ShaderTexture<'_>) -> Result<ShaderTextureAction>,
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.
Sourcepub 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>where
H: ShaderFinalizeControl + ?Sized,
P: ShaderTexturePolicy + ?Sized,
T: FnMut(ShaderTexture<'_>) -> Result<ShaderTextureAction>,
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>where
H: ShaderFinalizeControl + ?Sized,
P: ShaderTexturePolicy + ?Sized,
T: FnMut(ShaderTexture<'_>) -> Result<ShaderTextureAction>,
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.
Sourcepub fn is_no_op(&self) -> bool
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.
Sourcepub fn try_is_no_op(&self) -> Result<bool>
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.
Sourcepub fn has_channel_crosstalk(&self) -> bool
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.
Sourcepub fn try_has_channel_crosstalk(&self) -> Result<bool>
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.
Sourcepub fn cache_id(&self) -> Option<String>
pub fn cache_id(&self) -> Option<String>
Return OCIO’s cache identifier for this GPU processor instance.
Sourcepub fn try_cache_id(&self) -> Result<Option<String>>
pub fn try_cache_id(&self) -> Result<Option<String>>
Return OCIO’s cache identifier, preserving bridge errors.
Sourcepub fn extract_shader_info(&self, shader_desc: &mut GpuShaderDesc)
👎Deprecated since 0.2.0: panics on OCIO errors; prefer try_extract_shader_info()
pub fn extract_shader_info(&self, shader_desc: &mut GpuShaderDesc)
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.
Sourcepub fn try_extract_shader_info(
&self,
shader_desc: &mut GpuShaderDesc,
) -> Result<()>
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.
Sourcepub fn try_extract_shader_info_checked(
&self,
shader_desc: &mut GpuShaderDesc,
) -> Result<()>
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.
Sourcepub fn validate_shader_texture_layout(
&self,
shader_desc: &GpuShaderDesc,
) -> Result<()>
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)?;