cranpose_ui_graphics/

render_effect.rs

//! Render effects that can be applied to graphics layers.
//!
//! Matches the Jetpack Compose `RenderEffect` API with extensions for custom
//! WGSL shaders (`RuntimeShader`).

use std::sync::{Arc, Mutex, OnceLock, Weak};

use crate::{LayerShape, Rect};

const RUNTIME_SHADER_INLINE_UNIFORMS: usize = 16;

/// Edge treatment for blur effects at the boundary of the blurred region.
#[derive(Clone, Copy, Debug, Default, PartialEq, Eq, Hash)]
pub enum TileMode {
    /// Clamp to the edge pixel color.
    #[default]
    Clamp,
    /// Repeat the gradient/effect from start to end.
    Repeated,
    /// Mirror the gradient/effect every other repetition.
    Mirror,
    /// Treat pixels outside the boundary as transparent.
    Decal,
}

/// Controls blur behavior outside source bounds.
///
/// This mirrors Compose's `BlurredEdgeTreatment`:
/// - bounded treatment (`shape != None`) clips blur output and uses `TileMode::Clamp`
/// - unbounded treatment (`shape == None`) does not clip and uses `TileMode::Decal`
#[derive(Clone, Copy, Debug, PartialEq)]
pub struct BlurredEdgeTreatment {
    shape: Option<LayerShape>,
}

impl BlurredEdgeTreatment {
    /// Bounded treatment that clips to a rectangle.
    pub const RECTANGLE: Self = Self {
        shape: Some(LayerShape::Rectangle),
    };

    /// Unbounded treatment that does not clip blurred output.
    pub const UNBOUNDED: Self = Self { shape: None };

    /// Bounded treatment with a specific clip shape.
    pub const fn with_shape(shape: LayerShape) -> Self {
        Self { shape: Some(shape) }
    }

    pub fn shape(self) -> Option<LayerShape> {
        self.shape
    }

    pub fn clip(self) -> bool {
        self.shape.is_some()
    }

    pub fn tile_mode(self) -> TileMode {
        if self.clip() {
            TileMode::Clamp
        } else {
            TileMode::Decal
        }
    }
}

impl Default for BlurredEdgeTreatment {
    fn default() -> Self {
        Self::RECTANGLE
    }
}

/// The vertex stage and bindings every runtime shader starts from: a
/// fullscreen triangle whose `uv` spans the input, the input texture and
/// sampler at group 0, and the 64 uniform vectors at group 1. A shader
/// source is this prelude followed by an `effect_fs` fragment stage.
pub const RUNTIME_SHADER_PRELUDE_WGSL: &str = concat!(
    include_str!("../shaders/fullscreen_quad_vs.wgsl"),
    include_str!("../shaders/runtime_shader_bindings.wgsl"),
);

/// A custom WGSL shader effect, analogous to Android's `RuntimeShader`.
///
/// The shader source must be a complete WGSL module that declares:
/// ```wgsl
/// @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`](Self::set_batched_source); one that reads a
/// low-frequency copy of its source declares each with
/// [`set_substrates`](Self::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.
#[derive(Clone, Debug)]
pub struct RuntimeShader {
    source: Arc<str>,
    source_hash: u64,
    uniforms: RuntimeShaderUniforms,
    overrides: Vec<(&'static str, f64)>,
    input_padding: f32,
    output_padding: f32,
    batched_source: bool,
    substrates: Vec<SubstrateSpec>,
    draw_split: Option<&'static str>,
    domains: Option<Box<ShaderDomains>>,
}

#[derive(Clone, Copy, Debug, Default, PartialEq)]
struct ShaderDomains {
    output_support: Option<Rect>,
    sample_domain: Option<Rect>,
}

fn finite_rect(rect: Option<Rect>) -> Option<Rect> {
    rect.filter(|rect| {
        rect.x.is_finite()
            && rect.y.is_finite()
            && rect.width.is_finite()
            && rect.height.is_finite()
    })
}

/// The most substrates one shader may declare.
pub const MAX_SUBSTRATES: usize = 3;

/// A low-frequency copy of a shader's source the renderer packs beside it
/// and hands the shader through a reserved substrate region slot.
#[derive(Clone, Copy, Debug, PartialEq)]
pub enum SubstrateSpec {
    /// The source averaged in blocks of `block` x `block` texels, one
    /// substrate texel per block.
    Average { block: u32 },
    /// The source blurred by a Gaussian of `radius_px` device pixels, kept
    /// at the blur's scratch resolution.
    Blur { radius_px: f32 },
}

impl SubstrateSpec {
    fn hash_bits<H: std::hash::Hasher>(&self, state: &mut H) {
        use std::hash::Hash;
        match self {
            Self::Average { block } => {
                0u8.hash(state);
                block.hash(state);
            }
            Self::Blur { radius_px } => {
                1u8.hash(state);
                radius_px.to_bits().hash(state);
            }
        }
    }
}

#[derive(Clone, Debug, PartialEq)]
struct RuntimeShaderUniforms {
    len: usize,
    inline: [f32; RUNTIME_SHADER_INLINE_UNIFORMS],
    heap: Option<Vec<f32>>,
}

impl RuntimeShaderUniforms {
    fn new() -> Self {
        Self {
            len: 0,
            inline: [0.0; RUNTIME_SHADER_INLINE_UNIFORMS],
            heap: None,
        }
    }

    fn as_slice(&self) -> &[f32] {
        if let Some(heap) = &self.heap {
            heap.as_slice()
        } else {
            &self.inline[..self.len]
        }
    }

    fn len(&self) -> usize {
        self.as_slice().len()
    }

    fn ensure_len(&mut self, min_len: usize) {
        if let Some(heap) = &mut self.heap {
            if heap.len() < min_len {
                heap.resize(min_len, 0.0);
            }
            return;
        }

        if min_len <= RUNTIME_SHADER_INLINE_UNIFORMS {
            self.len = self.len.max(min_len);
            return;
        }

        let mut heap = Vec::with_capacity(min_len);
        heap.extend_from_slice(&self.inline[..self.len]);
        heap.resize(min_len, 0.0);
        self.heap = Some(heap);
    }

    fn set(&mut self, index: usize, value: f32) {
        if let Some(heap) = &mut self.heap {
            heap[index] = value;
        } else {
            self.inline[index] = value;
        }
    }

    #[cfg(test)]
    fn is_inline(&self) -> bool {
        self.heap.is_none()
    }
}

/// Error returned when a shader uniform write targets renderer-owned storage.
#[derive(Clone, Copy, Debug, Eq, PartialEq, thiserror::Error)]
pub enum RuntimeShaderUniformError {
    #[error(
        "uniform range starting at {index} with width {width} exceeds user uniform range 0..{max_user_uniforms}; slots {reserved_start}..{max_uniforms} are reserved for renderer data"
    )]
    OutOfUserRange {
        index: usize,
        width: usize,
        max_user_uniforms: usize,
        reserved_start: usize,
        max_uniforms: usize,
    },
}

impl RuntimeShader {
    /// Total uniform storage size in floats (64 vec4s = 256 floats).
    ///
    /// The final slots are reserved for renderer-managed data.
    pub const MAX_UNIFORMS: usize = 256;
    /// First renderer-reserved uniform slot.
    pub const RESERVED_UNIFORM_START: usize = 224;
    /// Reserved slots of the substrate regions `(x, y, w, h)` in input
    /// texels, in declaration order.
    pub const SUBSTRATE_REGION_UNIFORMS: [usize; MAX_SUBSTRATES] = [232, 228, 224];
    /// Reserved slot of the source region `(x, y, w, h)` in input texels.
    pub const SOURCE_REGION_UNIFORM: usize = 236;
    /// Reserved slot of the composite mask rect `(x, y, w, h)` in region pixels.
    pub const MASK_RECT_UNIFORM: usize = 240;
    /// Reserved slot of the composite mask corner radii.
    pub const MASK_RADII_UNIFORM: usize = 244;
    /// Reserved slot of the effect rect `(x, y, w, h)` in region pixels.
    pub const EFFECT_RECT_UNIFORM: usize = 248;
    /// Reserved slot of the logical size the input represents.
    pub const LOGICAL_SIZE_UNIFORM: usize = 252;
    /// Reserved slot of the composite alpha.
    pub const ALPHA_UNIFORM: usize = 254;
    /// Maximum user-addressable uniform count.
    pub const MAX_USER_UNIFORMS: usize = Self::RESERVED_UNIFORM_START;

    /// Create a new RuntimeShader from WGSL source code.
    #[track_caller]
    pub fn new(wgsl_source: &str) -> Self {
        let (source, source_hash) =
            cached_shader_source(std::panic::Location::caller(), wgsl_source);
        Self::with_source(source, source_hash)
    }

    /// 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 from_shared_source(source: Arc<str>) -> Self {
        let source_hash = cached_shared_shader_source_hash(&source);
        Self::with_source(source, source_hash)
    }

    fn with_source(source: Arc<str>, source_hash: u64) -> Self {
        Self {
            source,
            source_hash,
            uniforms: RuntimeShaderUniforms::new(),
            overrides: Vec::new(),
            input_padding: 0.0,
            output_padding: 0.0,
            batched_source: false,
            substrates: Vec::new(),
            draw_split: None,
            domains: None,
        }
    }

    /// 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 set_override(&mut self, name: &'static str, value: f64) {
        match self
            .overrides
            .binary_search_by(|(existing, _)| existing.cmp(&name))
        {
            Ok(index) => self.overrides[index].1 = value,
            Err(index) => self.overrides.insert(index, (name, value)),
        }
    }

    /// Removes a pipeline override by name, returning whether one was present.
    pub fn clear_override(&mut self, name: &str) -> bool {
        let Ok(index) = self
            .overrides
            .binary_search_by(|(existing, _)| (*existing).cmp(name))
        else {
            return false;
        };
        self.overrides.remove(index);
        true
    }

    /// The pipeline-overridable constants fixed by [`Self::set_override`],
    /// ordered by name.
    pub fn overrides(&self) -> &[(&'static str, f64)] {
        &self.overrides
    }

    /// Hash of the fixed override set; zero when no override is fixed.
    pub fn overrides_hash(&self) -> u64 {
        if self.overrides.is_empty() {
            return 0;
        }
        let mut bytes = Vec::new();
        for (name, value) in &self.overrides {
            bytes.extend_from_slice(name.as_bytes());
            bytes.push(0);
            bytes.extend_from_slice(&value.to_bits().to_le_bytes());
        }
        hash_shader_bytes(&bytes)
    }

    /// 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 set_input_padding(&mut self, padding: f32) {
        self.input_padding = if padding.is_finite() {
            padding.max(0.0)
        } else {
            0.0
        };
    }

    /// Returns the declared input padding in logical pixels.
    pub fn input_padding(&self) -> f32 {
        self.input_padding
    }

    /// 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 set_output_padding(&mut self, padding: f32) {
        self.output_padding = if padding.is_finite() {
            padding.max(0.0)
        } else {
            0.0
        };
    }

    /// Returns the declared output padding in logical pixels.
    pub fn output_padding(&self) -> f32 {
        self.output_padding
    }

    /// 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 set_output_support(&mut self, support: Option<Rect>) {
        self.set_domains(ShaderDomains {
            output_support: finite_rect(support),
            sample_domain: self.sample_domain(),
        });
    }

    /// The declared output support, when the shader gave one.
    pub fn output_support(&self) -> Option<Rect> {
        self.domains
            .as_ref()
            .and_then(|domains| domains.output_support)
    }

    fn set_domains(&mut self, domains: ShaderDomains) {
        self.domains = (domains != ShaderDomains::default()).then(|| Box::new(domains));
    }

    /// 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 set_sample_domain(&mut self, domain: Option<Rect>) {
        self.set_domains(ShaderDomains {
            output_support: self.output_support(),
            sample_domain: finite_rect(domain),
        });
    }

    /// The declared sample domain, when the shader gave one.
    pub fn sample_domain(&self) -> Option<Rect> {
        self.domains
            .as_ref()
            .and_then(|domains| domains.sample_domain)
    }

    /// 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 set_float(&mut self, index: usize, value: f32) {
        let _ = self.try_set_float(index, value);
    }

    /// Set a single float uniform at the given index.
    pub fn try_set_float(
        &mut self,
        index: usize,
        value: f32,
    ) -> Result<(), RuntimeShaderUniformError> {
        self.try_ensure_capacity(index, 1)?;
        self.uniforms.set(index, value);
        Ok(())
    }

    /// 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 set_float2(&mut self, index: usize, x: f32, y: f32) {
        let _ = self.try_set_float2(index, x, y);
    }

    /// Set a vec2 uniform at the given index (consumes indices `[index, index+1]`).
    pub fn try_set_float2(
        &mut self,
        index: usize,
        x: f32,
        y: f32,
    ) -> Result<(), RuntimeShaderUniformError> {
        self.try_ensure_capacity(index, 2)?;
        self.uniforms.set(index, x);
        self.uniforms.set(index + 1, y);
        Ok(())
    }

    /// 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 set_float4(&mut self, index: usize, x: f32, y: f32, z: f32, w: f32) {
        let _ = self.try_set_float4(index, x, y, z, w);
    }

    /// Set a vec4 uniform at the given index (consumes indices `[index..index+4]`).
    pub fn try_set_float4(
        &mut self,
        index: usize,
        x: f32,
        y: f32,
        z: f32,
        w: f32,
    ) -> Result<(), RuntimeShaderUniformError> {
        self.try_ensure_capacity(index, 4)?;
        self.uniforms.set(index, x);
        self.uniforms.set(index + 1, y);
        self.uniforms.set(index + 2, z);
        self.uniforms.set(index + 3, w);
        Ok(())
    }

    /// 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 set_batched_source(&mut self, batched: bool) {
        self.batched_source = batched;
    }

    /// Whether the shader reads the reserved source region, mask and alpha
    /// slots.
    pub fn batched_source(&self) -> bool {
        self.batched_source
    }

    /// 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 set_substrates(&mut self, substrates: Vec<SubstrateSpec>) {
        assert!(
            substrates.len() <= MAX_SUBSTRATES,
            "a runtime shader declares at most {MAX_SUBSTRATES} substrates"
        );
        self.substrates = substrates;
    }

    /// The substrates the shader declared, in slot order.
    pub fn substrates(&self) -> &[SubstrateSpec] {
        &self.substrates
    }

    /// Hashes the declared substrates and the draw split into `state`.
    pub fn hash_substrates<H: std::hash::Hasher>(&self, state: &mut H) {
        use std::hash::Hash;
        self.substrates.len().hash(state);
        for substrate in &self.substrates {
            substrate.hash_bits(state);
        }
        self.draw_split.hash(state);
    }

    /// 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 set_draw_split(&mut self, override_name: Option<&'static str>) {
        self.draw_split = override_name;
    }

    /// The override selecting the interior or the rim draw, when declared.
    pub fn draw_split(&self) -> Option<&'static str> {
        self.draw_split
    }

    /// Get the WGSL source code.
    pub fn source(&self) -> &str {
        &self.source
    }

    /// Get the uniform data as a float slice (for uploading to GPU).
    pub fn uniforms(&self) -> &[f32] {
        self.uniforms.as_slice()
    }

    /// Get the uniform data padded to full 256-float array (for GPU uniform buffer).
    pub fn uniforms_padded(&self) -> [f32; Self::MAX_UNIFORMS] {
        let mut padded = [0.0f32; Self::MAX_UNIFORMS];
        let len = self.uniforms.len().min(Self::MAX_UNIFORMS);
        padded[..len].copy_from_slice(&self.uniforms.as_slice()[..len]);
        padded
    }

    /// Compute a hash of the shader source for pipeline caching.
    pub fn source_hash(&self) -> u64 {
        self.source_hash
    }

    fn try_ensure_capacity(
        &mut self,
        index: usize,
        width: usize,
    ) -> Result<(), RuntimeShaderUniformError> {
        let min_len = index
            .checked_add(width)
            .ok_or_else(|| Self::uniform_range_error(index, width))?;
        if min_len > Self::MAX_USER_UNIFORMS {
            return Err(Self::uniform_range_error(index, width));
        }
        self.uniforms.ensure_len(min_len);
        Ok(())
    }

    fn uniform_range_error(index: usize, width: usize) -> RuntimeShaderUniformError {
        RuntimeShaderUniformError::OutOfUserRange {
            index,
            width,
            max_user_uniforms: Self::MAX_USER_UNIFORMS,
            reserved_start: Self::RESERVED_UNIFORM_START,
            max_uniforms: Self::MAX_UNIFORMS,
        }
    }
}

impl PartialEq for RuntimeShader {
    fn eq(&self, other: &Self) -> bool {
        self.source_hash == other.source_hash
            && (Arc::ptr_eq(&self.source, &other.source)
                || self.source.as_ref() == other.source.as_ref())
            && self.uniforms == other.uniforms
            && self.overrides.len() == other.overrides.len()
            && self
                .overrides
                .iter()
                .zip(&other.overrides)
                .all(|(a, b)| a.0 == b.0 && a.1.to_bits() == b.1.to_bits())
            && self.input_padding.to_bits() == other.input_padding.to_bits()
            && self.output_padding.to_bits() == other.output_padding.to_bits()
            && self.batched_source == other.batched_source
            && self.substrates == other.substrates
            && self.draw_split == other.draw_split
            && self.domains == other.domains
    }
}

fn hash_shader_source(source: &str) -> u64 {
    hash_shader_bytes(source.as_bytes())
}

fn hash_shader_bytes(bytes: &[u8]) -> u64 {
    const FNV_OFFSET_BASIS: u64 = 0xcbf2_9ce4_8422_2325;
    const FNV_PRIME: u64 = 0x0000_0100_0000_01b3;

    bytes.iter().fold(FNV_OFFSET_BASIS, |hash, byte| {
        (hash ^ u64::from(*byte)).wrapping_mul(FNV_PRIME)
    })
}

#[derive(Clone, Copy, Debug, PartialEq, Eq)]
struct ShaderSourceCallsite {
    file: &'static str,
    line: u32,
    column: u32,
}

struct CachedShaderSource {
    callsite: ShaderSourceCallsite,
    source_hash: u64,
    source: Arc<str>,
}

struct CachedSharedShaderSourceHash {
    byte_ptr: usize,
    len: usize,
    source_hash: u64,
    source: Weak<str>,
}

fn cached_shared_shader_source_hash(source: &Arc<str>) -> u64 {
    static CACHE: OnceLock<Mutex<Vec<CachedSharedShaderSourceHash>>> = OnceLock::new();
    let byte_ptr = source.as_ptr() as usize;
    let len = source.len();
    let mut cache = CACHE
        .get_or_init(|| Mutex::new(Vec::new()))
        .lock()
        .unwrap_or_else(|poisoned| poisoned.into_inner());

    cache.retain(|entry| entry.source.strong_count() > 0);
    if let Some(entry) = cache.iter().find(|entry| {
        entry.byte_ptr == byte_ptr
            && entry.len == len
            && entry
                .source
                .upgrade()
                .is_some_and(|cached| Arc::ptr_eq(&cached, source))
    }) {
        return entry.source_hash;
    }

    let source_hash = hash_shader_source(source);
    cache.push(CachedSharedShaderSourceHash {
        byte_ptr,
        len,
        source_hash,
        source: Arc::downgrade(source),
    });
    source_hash
}

fn cached_shader_source(
    location: &'static std::panic::Location<'static>,
    source: &str,
) -> (Arc<str>, u64) {
    static CACHE: OnceLock<Mutex<Vec<CachedShaderSource>>> = OnceLock::new();
    let callsite = ShaderSourceCallsite {
        file: location.file(),
        line: location.line(),
        column: location.column(),
    };
    let mut cache = CACHE
        .get_or_init(|| Mutex::new(Vec::new()))
        .lock()
        .unwrap_or_else(|poisoned| poisoned.into_inner());

    if let Some(entry) = cache.iter_mut().find(|entry| entry.callsite == callsite) {
        if entry.source.as_ref() == source {
            return (entry.source.clone(), entry.source_hash);
        }
        let source_hash = hash_shader_source(source);
        entry.source_hash = source_hash;
        entry.source = Arc::<str>::from(source);
        return (entry.source.clone(), entry.source_hash);
    }

    let source_hash = hash_shader_source(source);
    let shared = Arc::<str>::from(source);
    cache.push(CachedShaderSource {
        callsite,
        source_hash,
        source: shared.clone(),
    });
    (shared, source_hash)
}

/// A render effect applied to a graphics layer's rendered content.
///
/// Matches Jetpack Compose's `RenderEffect` sealed class hierarchy,
/// extended with `Shader` for custom WGSL effects.
#[derive(Clone, Debug, PartialEq)]
pub enum RenderEffect {
    /// Gaussian blur applied to the layer's rendered content.
    Blur {
        radius_x: f32,
        radius_y: f32,
        edge_treatment: TileMode,
    },
    /// Offset the rendered content by a fixed amount.
    Offset { offset_x: f32, offset_y: f32 },
    /// Apply a custom WGSL shader effect.
    Shader { shader: RuntimeShader },
    /// Chain two effects: apply `first`, then apply `second` to the result.
    Chain {
        first: Box<RenderEffect>,
        second: Box<RenderEffect>,
    },
}

impl RenderEffect {
    /// Create a blur effect with equal radius in both directions.
    pub fn blur(radius: f32) -> Self {
        Self::blur_with_edge_treatment(radius, TileMode::default())
    }

    /// Create a blur effect with equal radius in both directions and explicit
    /// edge treatment semantics.
    pub fn blur_with_edge_treatment(radius: f32, edge_treatment: TileMode) -> Self {
        Self::Blur {
            radius_x: radius,
            radius_y: radius,
            edge_treatment,
        }
    }

    /// Create a blur effect with separate horizontal and vertical radii.
    pub fn blur_xy(radius_x: f32, radius_y: f32, edge_treatment: TileMode) -> Self {
        Self::Blur {
            radius_x,
            radius_y,
            edge_treatment,
        }
    }

    /// Create an offset effect.
    pub fn offset(offset_x: f32, offset_y: f32) -> Self {
        Self::Offset { offset_x, offset_y }
    }

    /// Create a custom shader effect from a RuntimeShader.
    pub fn runtime_shader(shader: RuntimeShader) -> Self {
        Self::Shader { shader }
    }

    /// Chain this effect with another: `self` is applied first, then `other`.
    pub fn then(self, other: RenderEffect) -> Self {
        Self::Chain {
            first: Box::new(self),
            second: Box::new(other),
        }
    }

    /// Returns `true` if this effect or any chained sub-effect is a
    /// `RuntimeShader`. Animated shaders produce different output every frame,
    /// so layer surface caching is counterproductive for them.
    pub fn contains_runtime_shader(&self) -> bool {
        match self {
            RenderEffect::Shader { .. } => true,
            RenderEffect::Chain { first, second } => {
                first.contains_runtime_shader() || second.contains_runtime_shader()
            }
            _ => false,
        }
    }

    /// Maximum logical-pixel input padding required by this effect.
    pub fn input_padding(&self) -> f32 {
        match self {
            RenderEffect::Blur {
                radius_x, radius_y, ..
            } => radius_x.abs().max(radius_y.abs()),
            RenderEffect::Offset { offset_x, offset_y } => offset_x.abs().max(offset_y.abs()),
            RenderEffect::Shader { shader } => shader.input_padding(),
            RenderEffect::Chain { first, second } => first.input_padding() + second.input_padding(),
        }
    }

    /// Maximum logical-pixel distance this effect WRITES outside its rect.
    /// Only runtime shaders may declare one (SDF coverage past node bounds);
    /// blur/offset stay confined to their tight rect.
    pub fn output_padding(&self) -> f32 {
        match self {
            RenderEffect::Blur { .. } | RenderEffect::Offset { .. } => 0.0,
            RenderEffect::Shader { shader } => shader.output_padding(),
            RenderEffect::Chain { first, second } => {
                first.output_padding() + second.output_padding()
            }
        }
    }

    /// The rect outside which this effect writes nothing, in its logical
    /// space with the origin at its rect's top-left, when the stage that
    /// produces its output declared one; blur and offset write their whole
    /// rect and declare none.
    pub fn output_support(&self) -> Option<Rect> {
        match self {
            RenderEffect::Blur { .. } | RenderEffect::Offset { .. } => None,
            RenderEffect::Shader { shader } => shader.output_support(),
            RenderEffect::Chain { second, .. } => second.output_support(),
        }
    }

    /// The rect outside which the stage that produces this effect's output
    /// never samples what it is given, when it declared one; the whole
    /// input otherwise. A blur samples everything it writes and more.
    pub fn sample_domain(&self) -> Option<Rect> {
        match self {
            RenderEffect::Blur { .. } | RenderEffect::Offset { .. } => None,
            RenderEffect::Shader { shader } => shader.sample_domain(),
            RenderEffect::Chain { second, .. } => second.sample_domain(),
        }
    }
}

#[cfg(test)]
mod tests {
    #[test]
    fn overrides_stay_sorted_and_replace_by_name() {
        let mut shader = super::RuntimeShader::new("// overrides");
        shader.set_override("ZETA", 1.0);
        shader.set_override("ALPHA", 0.0);
        shader.set_override("ZETA", 2.0);
        assert_eq!(shader.overrides(), &[("ALPHA", 0.0), ("ZETA", 2.0)]);
    }

    #[test]
    fn clear_override_removes_present_name_and_preserves_remaining_set() {
        let mut shader = super::RuntimeShader::new("");
        shader.set_override("ZETA", 1.0);
        shader.set_override("ALPHA", 2.0);
        let mut expected = super::RuntimeShader::new("");
        expected.set_override("ALPHA", 2.0);
        assert!(shader.clear_override("ZETA"));
        assert!(!shader.clear_override("MISSING"));
        assert_eq!(shader.overrides(), &[("ALPHA", 2.0)]);
        assert_eq!(shader.overrides_hash(), expected.overrides_hash());
        assert!(shader.clear_override("ALPHA"));
        assert!(shader.overrides().is_empty());
        assert_eq!(shader.overrides_hash(), 0);
    }

    #[test]
    fn overrides_distinguish_otherwise_equal_shaders() {
        let plain = super::RuntimeShader::new("// overrides-eq");
        let mut raised = plain.clone();
        raised.set_override("FLAG", 1.0);
        assert_eq!(plain.overrides_hash(), 0);
        assert_ne!(plain.overrides_hash(), raised.overrides_hash());
        assert_ne!(plain, raised);
        let mut lowered = raised.clone();
        lowered.set_override("FLAG", 0.0);
        assert_ne!(raised.overrides_hash(), lowered.overrides_hash());
        assert_ne!(raised, lowered);
    }

    use super::*;
    use crate::RoundedCornerShape;

    #[test]
    fn runtime_shader_set_uniforms() {
        let mut shader = RuntimeShader::new("// test");
        shader.set_float(0, 1.0);
        shader.set_float2(2, 3.0, 4.0);
        shader.set_float4(4, 5.0, 6.0, 7.0, 8.0);

        assert_eq!(shader.uniforms()[0], 1.0);
        assert_eq!(shader.uniforms()[1], 0.0);
        assert_eq!(shader.uniforms()[2], 3.0);
        assert_eq!(shader.uniforms()[3], 4.0);
        assert_eq!(shader.uniforms()[4], 5.0);
        assert_eq!(shader.uniforms()[5], 6.0);
        assert_eq!(shader.uniforms()[6], 7.0);
        assert_eq!(shader.uniforms()[7], 8.0);
    }

    #[test]
    fn runtime_shader_padded() {
        let mut shader = RuntimeShader::new("// test");
        shader.set_float(0, 42.0);
        let padded = shader.uniforms_padded();
        assert_eq!(padded[0], 42.0);
        assert_eq!(padded[1], 0.0);
        assert_eq!(padded[255], 0.0);
    }

    #[test]
    fn blur_and_offset_declare_input_padding() {
        assert_eq!(
            RenderEffect::blur_xy(6.0, 12.0, TileMode::Clamp).input_padding(),
            12.0
        );
        assert_eq!(RenderEffect::offset(-8.0, 3.0).input_padding(), 8.0);
    }

    #[test]
    fn chained_effect_padding_accumulates_sampling_ranges() {
        let mut shader = RuntimeShader::new("// test");
        shader.set_input_padding(9.0);
        let effect = RenderEffect::blur_xy(4.0, 6.0, TileMode::Clamp)
            .then(RenderEffect::runtime_shader(shader))
            .then(RenderEffect::offset(2.0, -5.0));

        assert_eq!(effect.input_padding(), 20.0);
    }

    #[test]
    fn runtime_shader_keeps_common_uniform_payload_inline() {
        let mut shader = RuntimeShader::new("// test");
        shader.set_float4(0, 1.0, 2.0, 3.0, 4.0);
        shader.set_float4(4, 5.0, 6.0, 7.0, 8.0);
        shader.set_float4(8, 9.0, 10.0, 11.0, 12.0);
        shader.set_float4(12, 13.0, 14.0, 15.0, 16.0);

        assert!(shader.uniforms.is_inline());
        assert_eq!(shader.uniforms().len(), 16);

        shader.set_float(16, 17.0);
        assert!(!shader.uniforms.is_inline());
        assert_eq!(shader.uniforms()[16], 17.0);
    }

    #[test]
    fn runtime_shader_try_set_reports_reserved_uniform_slots() {
        let mut shader = RuntimeShader::new("// test");

        let err = shader
            .try_set_float(RuntimeShader::RESERVED_UNIFORM_START, 1.0)
            .unwrap_err();
        assert_eq!(
            err,
            RuntimeShaderUniformError::OutOfUserRange {
                index: RuntimeShader::RESERVED_UNIFORM_START,
                width: 1,
                max_user_uniforms: RuntimeShader::MAX_USER_UNIFORMS,
                reserved_start: RuntimeShader::RESERVED_UNIFORM_START,
                max_uniforms: RuntimeShader::MAX_UNIFORMS,
            }
        );
        assert!(shader.uniforms().is_empty());

        let err = shader
            .try_set_float4(RuntimeShader::MAX_USER_UNIFORMS - 3, 1.0, 2.0, 3.0, 4.0)
            .unwrap_err();
        assert_eq!(
            err,
            RuntimeShaderUniformError::OutOfUserRange {
                index: RuntimeShader::MAX_USER_UNIFORMS - 3,
                width: 4,
                max_user_uniforms: RuntimeShader::MAX_USER_UNIFORMS,
                reserved_start: RuntimeShader::RESERVED_UNIFORM_START,
                max_uniforms: RuntimeShader::MAX_UNIFORMS,
            }
        );
    }

    #[test]
    fn runtime_shader_setters_ignore_invalid_uniform_slots_without_panicking() {
        let mut shader = RuntimeShader::new("// test");
        shader.set_float(0, 7.0);

        shader.set_float(RuntimeShader::RESERVED_UNIFORM_START, 1.0);
        shader.set_float4(RuntimeShader::MAX_USER_UNIFORMS - 3, 1.0, 2.0, 3.0, 4.0);

        assert_eq!(shader.uniforms(), &[7.0]);
    }

    #[test]
    fn render_effect_chaining() {
        let blur = RenderEffect::blur(10.0);
        let offset = RenderEffect::offset(5.0, 5.0);
        let chained = blur.then(offset);
        match chained {
            RenderEffect::Chain { first, second } => {
                assert!(matches!(*first, RenderEffect::Blur { .. }));
                assert!(matches!(*second, RenderEffect::Offset { .. }));
            }
            _ => panic!("expected Chain"),
        }
    }

    #[test]
    fn blur_convenience() {
        let effect = RenderEffect::blur(15.0);
        match effect {
            RenderEffect::Blur {
                radius_x,
                radius_y,
                edge_treatment,
            } => {
                assert_eq!(radius_x, 15.0);
                assert_eq!(radius_y, 15.0);
                assert_eq!(edge_treatment, TileMode::Clamp);
            }
            _ => panic!("expected Blur"),
        }
    }

    #[test]
    fn blur_with_edge_treatment_uses_explicit_mode() {
        let effect = RenderEffect::blur_with_edge_treatment(6.0, TileMode::Decal);
        match effect {
            RenderEffect::Blur {
                radius_x,
                radius_y,
                edge_treatment,
            } => {
                assert_eq!(radius_x, 6.0);
                assert_eq!(radius_y, 6.0);
                assert_eq!(edge_treatment, TileMode::Decal);
            }
            _ => panic!("expected Blur"),
        }
    }

    #[test]
    fn source_hash_consistent() {
        let s1 = RuntimeShader::new("fn main() {}");
        let s2 = RuntimeShader::new("fn main() {}");
        assert_eq!(s1.source_hash(), s2.source_hash());
    }

    #[test]
    fn runtime_shader_from_shared_source_reuses_shared_source() {
        let source = Arc::<str>::from("fn fragment() -> vec4<f32> { return vec4<f32>(1.0); }");
        let s1 = RuntimeShader::from_shared_source(source.clone());
        let s2 = RuntimeShader::from_shared_source(source);

        assert!(Arc::ptr_eq(&s1.source, &s2.source));
        assert_eq!(s1.source_hash(), s2.source_hash());
    }

    fn runtime_shader_from_reuse_callsite(source: &str) -> RuntimeShader {
        RuntimeShader::new(source)
    }

    fn runtime_shader_from_replacement_callsite(source: &str) -> RuntimeShader {
        RuntimeShader::new(source)
    }

    #[test]
    fn runtime_shader_new_reuses_same_callsite_source() {
        let source = "fn fragment() -> vec4<f32> { return vec4<f32>(1.0); }";
        let s1 = runtime_shader_from_reuse_callsite(source);
        let s2 = runtime_shader_from_reuse_callsite(source);

        assert!(Arc::ptr_eq(&s1.source, &s2.source));
        assert_eq!(s1.source_hash(), s2.source_hash());
    }

    #[test]
    fn runtime_shader_new_replaces_changed_callsite_source() {
        let s1 = runtime_shader_from_replacement_callsite("fn a() {}");
        let s2 = runtime_shader_from_replacement_callsite("fn b() {}");

        assert!(!Arc::ptr_eq(&s1.source, &s2.source));
        assert_ne!(s1.source_hash(), s2.source_hash());
        assert_eq!(s2.source(), "fn b() {}");
    }

    #[test]
    fn runtime_shader_source_storage_has_no_process_global_interner() {
        let source = include_str!("render_effect.rs");
        let blocked_static = ["static ", "INTERNER"].concat();
        let blocked_type = ["ShaderSource", "Interner"].concat();

        assert!(
            !source.contains(&blocked_static) && !source.contains(&blocked_type),
            "RuntimeShader source sharing must be explicit via from_shared_source, not a process-global interner"
        );
    }

    #[test]
    fn blur_xy_preserves_tile_mode() {
        let effect = RenderEffect::blur_xy(3.0, 7.0, TileMode::Clamp);
        match effect {
            RenderEffect::Blur {
                radius_x,
                radius_y,
                edge_treatment,
            } => {
                assert_eq!(radius_x, 3.0);
                assert_eq!(radius_y, 7.0);
                assert_eq!(edge_treatment, TileMode::Clamp);
            }
            _ => panic!("expected Blur"),
        }
    }

    #[test]
    fn offset_constructor_sets_components() {
        let effect = RenderEffect::offset(11.0, -5.0);
        match effect {
            RenderEffect::Offset { offset_x, offset_y } => {
                assert_eq!(offset_x, 11.0);
                assert_eq!(offset_y, -5.0);
            }
            _ => panic!("expected Offset"),
        }
    }

    #[test]
    fn runtime_shader_equality_is_source_value_based() {
        let mut s1 = RuntimeShader::new("fn main() {}");
        let mut s2 = RuntimeShader::new("fn main() {}");
        s1.set_float(0, 1.0);
        s2.set_float(0, 1.0);
        assert_eq!(s1, s2);
    }

    #[test]
    fn blurred_edge_treatment_defaults_to_bounded_rectangle() {
        let treatment = BlurredEdgeTreatment::default();
        assert_eq!(treatment.shape(), Some(LayerShape::Rectangle));
        assert!(treatment.clip());
        assert_eq!(treatment.tile_mode(), TileMode::Clamp);
    }

    #[test]
    fn blurred_edge_treatment_unbounded_uses_decal_and_no_clip() {
        let treatment = BlurredEdgeTreatment::UNBOUNDED;
        assert_eq!(treatment.shape(), None);
        assert!(!treatment.clip());
        assert_eq!(treatment.tile_mode(), TileMode::Decal);
    }

    #[test]
    fn blurred_edge_treatment_with_shape_uses_bounded_mode() {
        let rounded = LayerShape::Rounded(RoundedCornerShape::uniform(8.0));
        let treatment = BlurredEdgeTreatment::with_shape(rounded);
        assert_eq!(treatment.shape(), Some(rounded));
        assert!(treatment.clip());
        assert_eq!(treatment.tile_mode(), TileMode::Clamp);
    }

    #[test]
    fn an_effect_chains_output_support_is_the_support_of_the_stage_that_writes_its_output() {
        let mut shader = RuntimeShader::new("fn glass_fs() {}");
        assert_eq!(shader.output_support(), None);
        let support = Rect {
            x: 4.0,
            y: 6.0,
            width: 30.0,
            height: 12.0,
        };
        shader.set_output_support(Some(support));
        assert_eq!(shader.output_support(), Some(support));
        let effect = RenderEffect::blur(3.0).then(RenderEffect::Shader {
            shader: shader.clone(),
        });
        assert_eq!(effect.output_support(), Some(support));
        let effect = RenderEffect::Shader {
            shader: shader.clone(),
        }
        .then(RenderEffect::blur(3.0));
        assert_eq!(effect.output_support(), None);
        assert_eq!(RenderEffect::blur(3.0).output_support(), None);
    }

    #[test]
    fn a_sample_domain_is_the_writers_and_a_blur_declares_none() {
        let mut shader = RuntimeShader::new("fn glass_fs() {}");
        let domain = Rect {
            x: -2.0,
            y: -2.0,
            width: 20.0,
            height: 12.0,
        };
        let plain = shader.clone();
        shader.set_sample_domain(Some(domain));
        assert_ne!(shader, plain);
        assert_eq!(shader.sample_domain(), Some(domain));
        let effect = RenderEffect::blur(3.0).then(RenderEffect::Shader {
            shader: shader.clone(),
        });
        assert_eq!(effect.sample_domain(), Some(domain));
        assert_eq!(RenderEffect::blur(3.0).output_support(), None);
        assert_eq!(RenderEffect::blur(3.0).sample_domain(), None);
        shader.set_sample_domain(Some(Rect {
            x: f32::INFINITY,
            ..domain
        }));
        assert_eq!(shader.sample_domain(), None);
    }

    #[test]
    fn a_non_finite_output_support_clears_the_declaration_and_a_support_tells_shaders_apart() {
        let mut shader = RuntimeShader::new("fn glass_fs() {}");
        let plain = shader.clone();
        shader.set_output_support(Some(Rect {
            x: 0.0,
            y: 0.0,
            width: 10.0,
            height: 10.0,
        }));
        assert_ne!(shader, plain);
        shader.set_output_support(Some(Rect {
            x: 0.0,
            y: 0.0,
            width: f32::NAN,
            height: 10.0,
        }));
        assert_eq!(shader.output_support(), None);
        assert_eq!(shader, plain);
    }
}