Struct RuntimeShader 

pub struct RuntimeShader { /* private fields */ }

A custom WGSL shader effect, analogous to Android’s RuntimeShader.

The shader source must be a complete WGSL module that declares:

@group(0) @binding(0) var input_texture: texture_2d<f32>;
@group(0) @binding(1) var input_sampler: sampler;
@group(1) @binding(0) var<uniform> u: array<vec4<f32>, 64>;

Float uniforms are packed linearly into the u array. Access them in WGSL as u[index / 4][index % 4] for individual floats, or u[index / 4].xy for vec2, etc. User uniforms may use indices 0..224; slots 224..256 are reserved for renderer metadata:

slots	content
224..236	substrate regions (x, y, w, h) in input texels, the third at 224, the second at 228, the first at 232; zero = none
236..240	source region (x, y, w, h) in input texels; zero = whole
240..244	composite mask rect (x, y, w, h) in region pixels; zero = none
244..248	composite mask corner radii (top-left, top-right, bottom-left, bottom-right)
248..252	effect rect (x, y, w, h) in region pixels
252..254	logical size the input represents; zero = its texel size
254	composite alpha

A shader that reads the source region, mask and alpha slots declares it with set_batched_source; one that reads a low-frequency copy of its source declares each with set_substrates and samples it through its substrate region, held to that region’s texel centers, so one tap stands for a neighbourhood the shader would otherwise walk tap by tap. The renderer then packs its input edge to edge beside other effects’ inputs in one texture and draws it straight into the final pass with its clip applied. Such a shader holds every sample coordinate to its region’s texel centers: the texels beside the region belong to other effects, or to no one. Every other shader is given the whole texture as its input and uv spans it.

RuntimeShader pipelines operate on premultiplied-alpha textures. Custom shaders should preserve premultiplied output semantics.

Implementations

impl RuntimeShader

pub const MAX_UNIFORMS: usize = 256

Total uniform storage size in floats (64 vec4s = 256 floats).

The final slots are reserved for renderer-managed data.

pub const RESERVED_UNIFORM_START: usize = 224

First renderer-reserved uniform slot.

pub const SUBSTRATE_REGION_UNIFORMS: [usize; 3]

Reserved slots of the substrate regions (x, y, w, h) in input texels, in declaration order.

pub const SOURCE_REGION_UNIFORM: usize = 236

Reserved slot of the source region (x, y, w, h) in input texels.

pub const MASK_RECT_UNIFORM: usize = 240

Reserved slot of the composite mask rect (x, y, w, h) in region pixels.

pub const MASK_RADII_UNIFORM: usize = 244

Reserved slot of the composite mask corner radii.

pub const EFFECT_RECT_UNIFORM: usize = 248

Reserved slot of the effect rect (x, y, w, h) in region pixels.

pub const LOGICAL_SIZE_UNIFORM: usize = 252

Reserved slot of the logical size the input represents.

pub const ALPHA_UNIFORM: usize = 254

Reserved slot of the composite alpha.

pub const MAX_USER_UNIFORMS: usize = Self::RESERVED_UNIFORM_START

Maximum user-addressable uniform count.

pub fn new(wgsl_source: &str) -> RuntimeShader

Create a new RuntimeShader from WGSL source code.

pub fn from_shared_source(source: Arc<str>) -> RuntimeShader

Create a RuntimeShader from shared WGSL source code.

This avoids repeatedly copying large shader modules for animated effects that rebuild only their uniform payload every frame.

pub fn set_override(&mut self, name: &'static str, value: f64)

Fixes a pipeline-overridable constant (override NAME: T = ...; in the WGSL) for every pipeline compiled from this shader. The value is converted to the constant’s declared scalar type the way WebGPU does (a bool is value != 0). Each distinct override set compiles its own pipeline; renderers use this to fold a material’s inactive features away without changing the shader text.

pub fn clear_override(&mut self, name: &str) -> bool

Removes a pipeline override by name, returning whether one was present.

pub fn overrides(&self) -> &[(&'static str, f64)]

The pipeline-overridable constants fixed by Self::set_override, ordered by name.

pub fn overrides_hash(&self) -> u64

Hash of the fixed override set; zero when no override is fixed.

pub fn set_input_padding(&mut self, padding: f32)

Declares how far the shader may sample outside its effect rect, in logical pixels. Backdrop rendering uses this to capture enough input around refractive and displacement shaders.

pub fn input_padding(&self) -> f32

Returns the declared input padding in logical pixels.

pub fn set_output_padding(&mut self, padding: f32)

Declares how far the shader WRITES outside its effect rect, in logical pixels. Backdrop compositing widens its scissor by this amount so SDF-driven coverage (rim glow, wobble, glued neighbor shapes) can extend past the node bounds instead of being clipped to them.

pub fn output_padding(&self) -> f32

Returns the declared output padding in logical pixels.

pub fn set_output_support(&mut self, support: Option<Rect>)

Declares the rect outside which the shader writes nothing: every pixel its coverage can make nonzero at its current uniforms, the output padding’s reach included, in logical pixels with the origin at the effect rect’s top-left. A renderer composites only the part of the effect rect inside it; the capture it reads stays whole, so a node that carries headroom around a smaller material pays the composite for the material alone. It says nothing about sampling: see Self::set_sample_domain. None, the default, means the whole effect rect and its output padding. A rect with a non-finite side clears the declaration.

pub fn output_support(&self) -> Option<Rect>

The declared output support, when the shader gave one.

pub fn set_sample_domain(&mut self, domain: Option<Rect>)

Declares the rect outside which the shader never samples its input, in logical pixels with the origin at the effect rect’s top-left. A renderer may leave the input outside it unresolved: a blur feeding this shader need only write the domain. The default, None, is the whole effect rect and its input padding, which the input padding contract already promises; an output support says nothing about sampling, so a shader that shades a small region but reads a far one keeps the default. A rect with a non-finite side clears it.

pub fn sample_domain(&self) -> Option<Rect>

The declared sample domain, when the shader gave one.

pub fn set_float(&mut self, index: usize, value: f32)

Set a single float uniform at the given index.

Invalid renderer-reserved ranges are ignored. Use Self::try_set_float when the caller needs to handle invalid uniform writes explicitly.

pub fn try_set_float( &mut self, index: usize, value: f32, ) -> Result<(), RuntimeShaderUniformError>

Set a single float uniform at the given index.

pub fn set_float2(&mut self, index: usize, x: f32, y: f32)

Set a vec2 uniform at the given index (consumes indices [index, index+1]).

Invalid renderer-reserved ranges are ignored. Use Self::try_set_float2 when the caller needs to handle invalid uniform writes explicitly.

pub fn try_set_float2( &mut self, index: usize, x: f32, y: f32, ) -> Result<(), RuntimeShaderUniformError>

Set a vec2 uniform at the given index (consumes indices [index, index+1]).

pub fn set_float4(&mut self, index: usize, x: f32, y: f32, z: f32, w: f32)

Set a vec4 uniform at the given index (consumes indices [index..index+4]).

Invalid renderer-reserved ranges are ignored. Use Self::try_set_float4 when the caller needs to handle invalid uniform writes explicitly.

pub fn try_set_float4( &mut self, index: usize, x: f32, y: f32, z: f32, w: f32, ) -> Result<(), RuntimeShaderUniformError>

Set a vec4 uniform at the given index (consumes indices [index..index+4]).

pub fn set_batched_source(&mut self, batched: bool)

Declares that the shader reads the reserved source region, mask and alpha slots and samples only within its region’s texel centers, so the renderer may hand it an input region packed edge to edge beside others and draw it straight into the final pass with its clip applied.

pub fn batched_source(&self) -> bool

Whether the shader reads the reserved source region, mask and alpha slots.

pub fn set_substrates(&mut self, substrates: Vec<SubstrateSpec>)

Declares the low-frequency copies of its source the shader reads through the reserved substrate region slots, in slot order. Only a batched shader packed with its stage is handed them; a shader without finds the slots zero and samples the source itself.

Panics

When more than MAX_SUBSTRATES are declared.

pub fn substrates(&self) -> &[SubstrateSpec]

The substrates the shader declared, in slot order.

pub fn hash_substrates<H>(&self, state: &mut H)

where H: Hasher,

Hashes the declared substrates and the draw split into state.

pub fn set_draw_split(&mut self, override_name: Option<&'static str>)

Declares an override NAME: i32 the renderer sets to 1 and 2 to draw the shader twice in the final pass, once for its interior and once for its rim, each pipeline compiled without the other’s work and discarding the other’s fragments before its fetches. Nothing else about the draw changes: the two draws partition the pixels the one draw shaded and land on the same bits.

pub fn draw_split(&self) -> Option<&'static str>

The override selecting the interior or the rim draw, when declared.

pub fn source(&self) -> &str

Get the WGSL source code.

pub fn uniforms(&self) -> &[f32]

Get the uniform data as a float slice (for uploading to GPU).

pub fn uniforms_padded(&self) -> [f32; 256]

Get the uniform data padded to full 256-float array (for GPU uniform buffer).

pub fn source_hash(&self) -> u64

Compute a hash of the shader source for pipeline caching.

Trait Implementations

impl Clone for RuntimeShader

fn clone(&self) -> RuntimeShader

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for RuntimeShader

fn fmt(&self, f: &mut Formatter<'_>) -> Result<(), Error>

Formats the value using the given formatter.

impl PartialEq for RuntimeShader

fn eq(&self, other: &RuntimeShader) -> bool

Equality operator ==.

fn ne(&self, other: &Rhs) -> bool

Inequality operator !=.

impl RenderHash for RuntimeShader

fn render_hash(&self) -> u64