wgsl-rs 0.1.0-beta.4

//! Texture builtin functions for WGSL.
//!
//! This module provides CPU-side implementations of WGSL texture builtin
//! functions. These functions allow textures to be sampled, loaded, and queried
//! on the CPU, enabling shader code written with `wgsl-rs` to produce
//! equivalent results in both "Rust world" (CPU) and "WGSL world" (GPU).
//!
//! See <https://gpuweb.github.io/gpuweb/wgsl/#texture-builtin-functions>.

// Note: Use `std::vec::Vec` explicitly throughout this module to avoid
// name collision with our `Vec<N, T>` vector type from vectors.rs.

use crate::std::{
    texture::{Sampler, SamplerComparison},
    vector::Vec4f,
};

/// CPU-side texture data for 1D textures.
///
/// Stores mip levels as a vector of 1D image strips.
#[derive(Clone)]
pub struct TextureData1D<T> {
    /// Mip levels, each containing width pixels.
    pub mips: std::vec::Vec<std::vec::Vec<[T; 4]>>,
}

impl<T: Default + Copy> TextureData1D<T> {
    /// Create a new 1D texture with the given width.
    pub fn new(width: u32) -> Self {
        let pixels: std::vec::Vec<[T; 4]> = (0..width)
            .map(|_| std::array::from_fn(|_| T::default()))
            .collect();
        Self { mips: vec![pixels] }
    }
}

impl<T> TextureData1D<T> {
    /// Get the width at the given mip level.
    pub fn width(&self, level: u32) -> u32 {
        self.mips
            .get(level as usize)
            .map(|m| m.len() as u32)
            .unwrap_or(0)
    }

    /// Get the number of mip levels.
    pub fn num_levels(&self) -> u32 {
        self.mips.len() as u32
    }

    /// Get a pixel at the given coordinate and mip level.
    pub fn get_pixel(&self, x: u32, level: u32) -> Option<&[T; 4]> {
        self.mips.get(level as usize)?.get(x as usize)
    }

    /// Set a pixel at the given coordinate and mip level.
    pub fn set_pixel(&mut self, x: u32, level: u32, value: [T; 4]) {
        if let Some(mip) = self.mips.get_mut(level as usize)
            && let Some(pixel) = mip.get_mut(x as usize)
        {
            *pixel = value;
        }
    }
}

/// CPU-side texture data for 2D textures.
#[derive(Clone)]
pub struct TextureData2D<T> {
    /// Mip levels, each containing a 2D image
    pub mips: std::vec::Vec<std::vec::Vec<std::vec::Vec<[T; 4]>>>,
}

impl<T: Default + Clone> TextureData2D<T> {
    /// Create a new 2D texture with the given dimensions.
    pub fn new(width: u32, height: u32) -> Self {
        let pixels: std::vec::Vec<std::vec::Vec<[T; 4]>> = (0..height)
            .map(|_| {
                (0..width)
                    .map(|_| std::array::from_fn(|_| T::default()))
                    .collect()
            })
            .collect();
        Self { mips: vec![pixels] }
    }
}

impl<T> TextureData2D<T> {
    /// Get the dimensions at the given mip level.
    pub fn dimensions(&self, level: u32) -> (u32, u32) {
        self.mips
            .get(level as usize)
            .map(|m| {
                let height = m.len() as u32;
                let width = m.first().map(|r| r.len() as u32).unwrap_or(0);
                (width, height)
            })
            .unwrap_or((0, 0))
    }

    /// Get the number of mip levels.
    pub fn num_levels(&self) -> u32 {
        self.mips.len() as u32
    }

    /// Get a pixel at the given coordinate and mip level.
    pub fn get_pixel(&self, x: u32, y: u32, level: u32) -> Option<&[T; 4]> {
        self.mips
            .get(level as usize)?
            .get(y as usize)?
            .get(x as usize)
    }

    /// Set a pixel at the given coordinate and mip level.
    pub fn set_pixel(&mut self, x: u32, y: u32, level: u32, value: [T; 4]) {
        if let Some(mip) = self.mips.get_mut(level as usize)
            && let Some(row) = mip.get_mut(y as usize)
            && let Some(pixel) = row.get_mut(x as usize)
        {
            *pixel = value;
        }
    }
}

impl<T: Default + Clone> TextureData2D<T> {
    /// Generate mip levels for the texture.
    pub fn generate_mips(&mut self)
    where
        T: Copy + Into<f32> + From<f32>,
    {
        // Start with base level dimensions
        let (mut w, mut h) = self.dimensions(0);

        while w > 1 || h > 1 {
            let new_w = Ord::max(w / 2, 1);
            let new_h = Ord::max(h / 2, 1);

            let prev_level = self.mips.len() - 1;
            let mut new_mip: std::vec::Vec<std::vec::Vec<[T; 4]>> = (0..new_h)
                .map(|_| {
                    (0..new_w)
                        .map(|_| std::array::from_fn(|_| T::default()))
                        .collect()
                })
                .collect();

            for y in 0..new_h {
                for x in 0..new_w {
                    // Sample 2x2 block from previous level
                    let mut sum = [0.0f32; 4];
                    let mut count = 0;

                    for dy in 0..2 {
                        for dx in 0..2 {
                            let sx = Ord::min(x * 2 + dx, w - 1);
                            let sy = Ord::min(y * 2 + dy, h - 1);
                            if let Some(pixel) = self.mips[prev_level]
                                .get(sy as usize)
                                .and_then(|row| row.get(sx as usize))
                            {
                                for c in 0..4 {
                                    sum[c] += pixel[c].into();
                                }
                                count += 1;
                            }
                        }
                    }

                    if count > 0 {
                        let avg = [
                            T::from(sum[0] / count as f32),
                            T::from(sum[1] / count as f32),
                            T::from(sum[2] / count as f32),
                            T::from(sum[3] / count as f32),
                        ];
                        new_mip[y as usize][x as usize] = avg;
                    }
                }
            }

            self.mips.push(new_mip);
            w = new_w;
            h = new_h;
        }
    }
}

/// CPU-side texture data for 2D array textures.
#[derive(Clone)]
pub struct TextureData2DArray<T> {
    /// Array of 2D textures
    pub layers: std::vec::Vec<TextureData2D<T>>,
}

impl<T: Default + Copy> TextureData2DArray<T> {
    /// Create a new 2D array texture.
    pub fn new(width: u32, height: u32, layers: u32) -> Self {
        Self {
            layers: (0..layers)
                .map(|_| TextureData2D::new(width, height))
                .collect(),
        }
    }
}

impl<T> TextureData2DArray<T> {
    /// Get the number of array layers.
    pub fn num_layers(&self) -> u32 {
        self.layers.len() as u32
    }

    /// Get the dimensions at the given mip level.
    pub fn dimensions(&self, level: u32) -> (u32, u32) {
        self.layers
            .first()
            .map(|l| l.dimensions(level))
            .unwrap_or((0, 0))
    }

    /// Get the number of mip levels.
    pub fn num_levels(&self) -> u32 {
        self.layers.first().map(|l| l.num_levels()).unwrap_or(0)
    }
}

/// CPU-side texture data for 3D textures.
#[derive(Clone)]
pub struct TextureData3D<T> {
    /// Mip levels, each containing a 3D volume
    pub mips: std::vec::Vec<std::vec::Vec<std::vec::Vec<std::vec::Vec<[T; 4]>>>>,
}

impl<T: Default + Copy> TextureData3D<T> {
    /// Create a new 3D texture with the given dimensions.
    pub fn new(width: u32, height: u32, depth: u32) -> Self {
        let volume: std::vec::Vec<std::vec::Vec<std::vec::Vec<[T; 4]>>> = (0..depth)
            .map(|_| {
                (0..height)
                    .map(|_| {
                        (0..width)
                            .map(|_| std::array::from_fn(|_| T::default()))
                            .collect()
                    })
                    .collect()
            })
            .collect();
        Self { mips: vec![volume] }
    }
}

impl<T> TextureData3D<T> {
    /// Get the dimensions at the given mip level.
    pub fn dimensions(&self, level: u32) -> (u32, u32, u32) {
        self.mips
            .get(level as usize)
            .map(|m| {
                let depth = m.len() as u32;
                let height = m.first().map(|s| s.len() as u32).unwrap_or(0);
                let width = m
                    .first()
                    .and_then(|s| s.first())
                    .map(|r| r.len() as u32)
                    .unwrap_or(0);
                (width, height, depth)
            })
            .unwrap_or((0, 0, 0))
    }

    /// Get the number of mip levels.
    pub fn num_levels(&self) -> u32 {
        self.mips.len() as u32
    }

    /// Get a pixel at the given coordinate and mip level.
    pub fn get_pixel(&self, x: u32, y: u32, z: u32, level: u32) -> Option<&[T; 4]> {
        self.mips
            .get(level as usize)?
            .get(z as usize)?
            .get(y as usize)?
            .get(x as usize)
    }

    /// Set a pixel at the given coordinate and mip level.
    pub fn set_pixel(&mut self, x: u32, y: u32, z: u32, level: u32, value: [T; 4]) {
        if let Some(mip) = self.mips.get_mut(level as usize)
            && let Some(slice) = mip.get_mut(z as usize)
            && let Some(row) = slice.get_mut(y as usize)
            && let Some(pixel) = row.get_mut(x as usize)
        {
            *pixel = value;
        }
    }
}

/// CPU-side texture data for cube textures.
///
/// A cube texture has 6 faces: +X, -X, +Y, -Y, +Z, -Z
#[derive(Clone)]
pub struct TextureDataCube<T> {
    /// The 6 faces of the cube, each is a 2D texture
    pub faces: [TextureData2D<T>; 6],
}

impl<T: Default + Copy> TextureDataCube<T> {
    /// Create a new cube texture with the given face size.
    pub fn new(size: u32) -> Self {
        Self {
            faces: std::array::from_fn(|_| TextureData2D::new(size, size)),
        }
    }
}

impl<T> TextureDataCube<T> {
    /// Get the dimensions (face width/height) at the given mip level.
    pub fn dimensions(&self, level: u32) -> (u32, u32) {
        self.faces[0].dimensions(level)
    }

    /// Get the number of mip levels.
    pub fn num_levels(&self) -> u32 {
        self.faces[0].num_levels()
    }
}

/// CPU-side texture data for cube array textures.
#[derive(Clone)]
pub struct TextureDataCubeArray<T> {
    /// Array of cube textures
    pub cubes: std::vec::Vec<TextureDataCube<T>>,
}

impl<T: Default + Copy> TextureDataCubeArray<T> {
    /// Create a new cube array texture.
    pub fn new(size: u32, layers: u32) -> Self {
        Self {
            cubes: (0..layers).map(|_| TextureDataCube::new(size)).collect(),
        }
    }
}

impl<T> TextureDataCubeArray<T> {
    /// Get the number of array layers.
    pub fn num_layers(&self) -> u32 {
        self.cubes.len() as u32
    }

    /// Get the dimensions at the given mip level.
    pub fn dimensions(&self, level: u32) -> (u32, u32) {
        self.cubes
            .first()
            .map(|c| c.dimensions(level))
            .unwrap_or((0, 0))
    }

    /// Get the number of mip levels.
    pub fn num_levels(&self) -> u32 {
        self.cubes.first().map(|c| c.num_levels()).unwrap_or(0)
    }
}

/// CPU-side texture data for multisampled 2D textures.
#[derive(Clone)]
pub struct TextureDataMultisampled2D<T> {
    /// Width of the texture
    pub width: u32,
    /// Height of the texture
    pub height: u32,
    /// Number of samples per pixel
    pub sample_count: u32,
    /// Pixel data: `[y][x][sample]`
    pub samples: std::vec::Vec<std::vec::Vec<std::vec::Vec<[T; 4]>>>,
}

impl<T: Default + Clone> TextureDataMultisampled2D<T> {
    /// Create a new multisampled 2D texture.
    pub fn new(width: u32, height: u32, sample_count: u32) -> Self {
        let samples: std::vec::Vec<std::vec::Vec<std::vec::Vec<[T; 4]>>> = (0..height)
            .map(|_| {
                (0..width)
                    .map(|_| {
                        (0..sample_count)
                            .map(|_| std::array::from_fn(|_| T::default()))
                            .collect()
                    })
                    .collect()
            })
            .collect();
        Self {
            width,
            height,
            sample_count,
            samples,
        }
    }
}

impl<T> TextureDataMultisampled2D<T> {
    /// Get the dimensions.
    pub fn dimensions(&self) -> (u32, u32) {
        (self.width, self.height)
    }

    /// Get the number of samples.
    pub fn num_samples(&self) -> u32 {
        self.sample_count
    }

    /// Get a sample at the given coordinate.
    pub fn get_sample(&self, x: u32, y: u32, sample: u32) -> Option<&[T; 4]> {
        self.samples
            .get(y as usize)?
            .get(x as usize)?
            .get(sample as usize)
    }
}

/// CPU-side depth texture data for 2D depth textures.
#[derive(Clone)]
pub struct TextureDataDepth2D {
    /// Mip levels
    pub mips: std::vec::Vec<std::vec::Vec<std::vec::Vec<f32>>>,
}

impl TextureDataDepth2D {
    /// Create a new 2D depth texture.
    pub fn new(width: u32, height: u32) -> Self {
        let row = vec![0.0f32; width as usize];
        let pixels = vec![row; height as usize];
        Self { mips: vec![pixels] }
    }

    /// Get the dimensions at the given mip level.
    pub fn dimensions(&self, level: u32) -> (u32, u32) {
        self.mips
            .get(level as usize)
            .map(|m| {
                let height = m.len() as u32;
                let width = m.first().map(|r| r.len() as u32).unwrap_or(0);
                (width, height)
            })
            .unwrap_or((0, 0))
    }

    /// Get the number of mip levels.
    pub fn num_levels(&self) -> u32 {
        self.mips.len() as u32
    }

    /// Get a depth value at the given coordinate and mip level.
    pub fn get_depth(&self, x: u32, y: u32, level: u32) -> Option<f32> {
        self.mips
            .get(level as usize)?
            .get(y as usize)?
            .get(x as usize)
            .copied()
    }
}

/// CPU-side depth texture data for 2D depth array textures.
#[derive(Clone)]
pub struct TextureDataDepth2DArray {
    /// Array of depth textures
    pub layers: std::vec::Vec<TextureDataDepth2D>,
}

impl TextureDataDepth2DArray {
    /// Create a new 2D depth array texture.
    pub fn new(width: u32, height: u32, layers: u32) -> Self {
        Self {
            layers: (0..layers)
                .map(|_| TextureDataDepth2D::new(width, height))
                .collect(),
        }
    }

    /// Get the number of array layers.
    pub fn num_layers(&self) -> u32 {
        self.layers.len() as u32
    }

    /// Get the dimensions at the given mip level.
    pub fn dimensions(&self, level: u32) -> (u32, u32) {
        self.layers
            .first()
            .map(|l| l.dimensions(level))
            .unwrap_or((0, 0))
    }

    /// Get the number of mip levels.
    pub fn num_levels(&self) -> u32 {
        self.layers.first().map(|l| l.num_levels()).unwrap_or(0)
    }
}

/// CPU-side depth texture data for cube depth textures.
#[derive(Clone)]
pub struct TextureDataDepthCube {
    /// The 6 faces of the cube
    pub faces: [TextureDataDepth2D; 6],
}

impl TextureDataDepthCube {
    /// Create a new cube depth texture.
    pub fn new(size: u32) -> Self {
        Self {
            faces: std::array::from_fn(|_| TextureDataDepth2D::new(size, size)),
        }
    }

    /// Get the dimensions at the given mip level.
    pub fn dimensions(&self, level: u32) -> (u32, u32) {
        self.faces[0].dimensions(level)
    }

    /// Get the number of mip levels.
    pub fn num_levels(&self) -> u32 {
        self.faces[0].num_levels()
    }
}

/// CPU-side depth texture data for cube array depth textures.
#[derive(Clone)]
pub struct TextureDataDepthCubeArray {
    /// Array of cube depth textures
    pub cubes: std::vec::Vec<TextureDataDepthCube>,
}

impl TextureDataDepthCubeArray {
    /// Create a new cube array depth texture.
    pub fn new(size: u32, layers: u32) -> Self {
        Self {
            cubes: (0..layers)
                .map(|_| TextureDataDepthCube::new(size))
                .collect(),
        }
    }

    /// Get the number of array layers.
    pub fn num_layers(&self) -> u32 {
        self.cubes.len() as u32
    }

    /// Get the dimensions at the given mip level.
    pub fn dimensions(&self, level: u32) -> (u32, u32) {
        self.cubes
            .first()
            .map(|c| c.dimensions(level))
            .unwrap_or((0, 0))
    }

    /// Get the number of mip levels.
    pub fn num_levels(&self) -> u32 {
        self.cubes.first().map(|c| c.num_levels()).unwrap_or(0)
    }
}

/// CPU-side multisampled depth texture data.
#[derive(Clone)]
pub struct TextureDataDepthMultisampled2D {
    /// Width of the texture
    pub width: u32,
    /// Height of the texture
    pub height: u32,
    /// Number of samples per pixel
    pub sample_count: u32,
    /// Depth samples: `[y][x][sample]`
    pub samples: std::vec::Vec<std::vec::Vec<std::vec::Vec<f32>>>,
}

impl TextureDataDepthMultisampled2D {
    /// Create a new multisampled 2D depth texture.
    pub fn new(width: u32, height: u32, sample_count: u32) -> Self {
        let samples_per_pixel = vec![0.0f32; sample_count as usize];
        let row = vec![samples_per_pixel; width as usize];
        let pixels = vec![row; height as usize];
        Self {
            width,
            height,
            sample_count,
            samples: pixels,
        }
    }

    /// Get the dimensions.
    pub fn dimensions(&self) -> (u32, u32) {
        (self.width, self.height)
    }

    /// Get the number of samples.
    pub fn num_samples(&self) -> u32 {
        self.sample_count
    }
}

/// Filter mode for texture sampling.
#[derive(Clone, Copy, Debug, Default, PartialEq, Eq)]
pub enum FilterMode {
    /// Nearest-neighbor filtering (point sampling)
    #[default]
    Nearest,
    /// Linear filtering (bilinear/trilinear interpolation)
    Linear,
}

/// Address mode for texture coordinate wrapping.
#[derive(Clone, Copy, Debug, Default, PartialEq, Eq)]
pub enum AddressMode {
    /// Clamp to edge - coordinates outside [0, 1] are clamped
    #[default]
    ClampToEdge,
    /// Repeat - coordinates wrap around
    Repeat,
    /// Mirror repeat - coordinates mirror at boundaries
    MirrorRepeat,
}

/// CPU-side sampler state.
#[derive(Clone, Debug)]
pub struct SamplerState {
    /// Magnification filter
    pub mag_filter: FilterMode,
    /// Minification filter
    pub min_filter: FilterMode,
    /// Mipmap filter
    pub mipmap_filter: FilterMode,
    /// Address mode for U coordinate
    pub address_mode_u: AddressMode,
    /// Address mode for V coordinate
    pub address_mode_v: AddressMode,
    /// Address mode for W coordinate
    pub address_mode_w: AddressMode,
    /// LOD min clamp
    pub lod_min_clamp: f32,
    /// LOD max clamp
    pub lod_max_clamp: f32,
}

impl Default for SamplerState {
    fn default() -> Self {
        Self {
            mag_filter: FilterMode::Nearest,
            min_filter: FilterMode::Nearest,
            mipmap_filter: FilterMode::Nearest,
            address_mode_u: AddressMode::ClampToEdge,
            address_mode_v: AddressMode::ClampToEdge,
            address_mode_w: AddressMode::ClampToEdge,
            lod_min_clamp: 0.0,
            lod_max_clamp: 1000.0,
        }
    }
}

impl SamplerState {
    /// Create a new sampler state with default values.
    pub fn new() -> Self {
        Self::default()
    }

    /// Create a sampler state with linear filtering.
    pub fn linear() -> Self {
        Self {
            mag_filter: FilterMode::Linear,
            min_filter: FilterMode::Linear,
            mipmap_filter: FilterMode::Linear,
            ..Default::default()
        }
    }

    /// Apply address mode to a coordinate.
    pub fn apply_address_mode(mode: AddressMode, coord: f32) -> f32 {
        match mode {
            AddressMode::ClampToEdge => coord.clamp(0.0, 1.0),
            AddressMode::Repeat => coord.rem_euclid(1.0),
            AddressMode::MirrorRepeat => {
                let t = coord.rem_euclid(2.0);
                if t > 1.0 { 2.0 - t } else { t }
            }
        }
    }
}

/// Comparison sampler state.
#[derive(Clone, Debug)]
pub struct SamplerComparisonState {
    /// Base sampler state
    pub sampler: SamplerState,
    /// Comparison function
    pub compare: CompareFunction,
}

/// Comparison function for depth testing.
#[derive(Clone, Copy, Debug, Default, PartialEq, Eq)]
pub enum CompareFunction {
    /// Never pass
    Never,
    /// Pass if less than
    Less,
    /// Pass if equal
    Equal,
    /// Pass if less than or equal
    #[default]
    LessEqual,
    /// Pass if greater than
    Greater,
    /// Pass if not equal
    NotEqual,
    /// Pass if greater than or equal
    GreaterEqual,
    /// Always pass
    Always,
}

impl CompareFunction {
    /// Evaluate the comparison function per WebGPU spec semantics.
    ///
    /// The `reference` (depth_ref, the "provided value") is compared against
    /// the `sample` (fetched texel, the "sampled value"). Per the WebGPU spec,
    /// `Less` passes when `reference < sample`, etc.
    ///
    /// See <https://www.w3.org/TR/webgpu/#enumdef-gpucomparefunction>.
    pub fn compare(self, sample: f32, reference: f32) -> f32 {
        let result = match self {
            CompareFunction::Never => false,
            CompareFunction::Less => reference < sample,
            CompareFunction::Equal => (sample - reference).abs() < f32::EPSILON,
            CompareFunction::LessEqual => reference <= sample,
            CompareFunction::Greater => reference > sample,
            CompareFunction::NotEqual => (sample - reference).abs() >= f32::EPSILON,
            CompareFunction::GreaterEqual => reference >= sample,
            CompareFunction::Always => true,
        };
        if result { 1.0 } else { 0.0 }
    }
}

impl Default for SamplerComparisonState {
    fn default() -> Self {
        Self {
            sampler: SamplerState::default(),
            compare: CompareFunction::LessEqual,
        }
    }
}

/// Trait for textures that support `textureDimensions`.
pub trait TextureDimensionsQuery {
    /// The output type for dimensions (u32, Vec2u, or Vec3u)
    type Output;

    /// Get the dimensions at the given mip level.
    fn query_dimensions(&self, level: u32) -> Self::Output;
}

/// Trait for textures that support `textureNumLayers`.
pub trait TextureNumLayersQuery {
    /// Get the number of array layers.
    fn query_num_layers(&self) -> u32;
}

/// Trait for textures that support `textureNumLevels`.
pub trait TextureNumLevelsQuery {
    /// Get the number of mip levels.
    fn query_num_levels(&self) -> u32;
}

/// Trait for textures that support `textureNumSamples`.
pub trait TextureNumSamplesQuery {
    /// Get the number of samples.
    fn query_num_samples(&self) -> u32;
}

/// Trait for textures that support `textureLoad`.
pub trait TextureLoad<Coords, Level> {
    /// The output type (`Vec4<T>` for sampled textures, f32 for depth)
    type Output;

    /// Load a texel at the given coordinates and mip level.
    fn load(&self, coords: Coords, level: Level) -> Self::Output;
}

/// Trait for multisampled textures that support `textureLoad` with sample
/// index.
pub trait TextureLoadMultisampled<Coords, SampleIndex> {
    /// The output type
    type Output;

    /// Load a sample at the given coordinates and sample index.
    fn load_multisampled(&self, coords: Coords, sample_index: SampleIndex) -> Self::Output;
}

/// Trait for array textures that support `textureLoad` with array index.
pub trait TextureLoadArray<Coords, ArrayIndex, Level> {
    /// The output type
    type Output;

    /// Load a texel at the given coordinates, array index, and mip level.
    fn load_array(&self, coords: Coords, array_index: ArrayIndex, level: Level) -> Self::Output;
}

/// Trait for textures that support `textureSample`.
pub trait TextureSample<Coords> {
    /// The output type
    type Output;

    /// Sample the texture at the given coordinates.
    fn sample(&self, sampler: &Sampler, coords: Coords) -> Self::Output;
}

/// Trait for textures that support `textureSample` with offset.
pub trait TextureSampleOffset<Coords, Offset> {
    /// The output type
    type Output;

    /// Sample the texture at the given coordinates with offset.
    fn sample_offset(&self, sampler: &Sampler, coords: Coords, offset: Offset) -> Self::Output;
}

/// Trait for array textures that support `textureSample` with array index.
pub trait TextureSampleArray<Coords, ArrayIndex> {
    /// The output type
    type Output;

    /// Sample the texture at the given coordinates and array index.
    fn sample_array(
        &self,
        sampler: &Sampler,
        coords: Coords,
        array_index: ArrayIndex,
    ) -> Self::Output;
}

/// Trait for textures that support `textureSampleLevel`.
///
/// Per the WGSL spec, the `level` parameter must be `f32` for non-depth
/// sampled textures; only depth textures accept `i32`/`u32` levels.
pub trait TextureSampleLevel<Coords, Level> {
    /// The output type
    type Output;

    /// Sample the texture at the given coordinates and explicit LOD.
    fn sample_level(&self, sampler: &Sampler, coords: Coords, level: Level) -> Self::Output;
}

/// Trait for textures that support `textureSampleBias`.
pub trait TextureSampleBias<Coords, Bias> {
    /// The output type
    type Output;

    /// Sample the texture at the given coordinates with LOD bias.
    fn sample_bias(&self, sampler: &Sampler, coords: Coords, bias: Bias) -> Self::Output;
}

/// Trait for textures that support `textureSampleGrad`.
pub trait TextureSampleGrad<Coords, Ddx, Ddy> {
    /// The output type
    type Output;

    /// Sample the texture with explicit gradients.
    fn sample_grad(&self, sampler: &Sampler, coords: Coords, ddx: Ddx, ddy: Ddy) -> Self::Output;
}

/// Trait for textures that support `textureSampleCompare`.
pub trait TextureSampleCompare<Coords, DepthRef> {
    /// Sample the depth texture with comparison.
    fn sample_compare(
        &self,
        sampler: &SamplerComparison,
        coords: Coords,
        depth_ref: DepthRef,
    ) -> f32;
}

/// Trait for textures that support `textureSampleCompareLevel`.
///
/// Per the WGSL spec, `textureSampleCompareLevel` always samples at mip level
/// 0. There is no level parameter.
pub trait TextureSampleCompareLevel<Coords, DepthRef> {
    /// Sample the depth texture with comparison at mip level 0.
    fn sample_compare_level(
        &self,
        sampler: &SamplerComparison,
        coords: Coords,
        depth_ref: DepthRef,
    ) -> f32;
}

/// Trait for textures that support `textureSampleBaseClampToEdge`.
///
/// Samples a texture at mip level 0 with coordinates clamped to
/// `[0.5/dim, 1.0 - 0.5/dim]` to prevent edge wrapping artifacts.
pub trait TextureSampleBaseClampToEdge<Coords> {
    /// The output type
    type Output;

    /// Sample the texture at base level with coordinates clamped to the edge.
    fn sample_base_clamp_to_edge(&self, sampler: &Sampler, coords: Coords) -> Self::Output;
}

/// Trait for textures that support `textureGather`.
pub trait TextureGather<Coords> {
    /// The output type
    type Output;

    /// Gather one component from 4 texels.
    fn gather(&self, component: u32, sampler: &Sampler, coords: Coords) -> Self::Output;
}

/// Trait for depth textures that support `textureGather` (no component
/// parameter).
pub trait TextureGatherDepth<Coords> {
    /// Gather depth values from 4 texels.
    fn gather_depth(&self, sampler: &Sampler, coords: Coords) -> Vec4f;
}

/// Trait for textures that support `textureGatherCompare`.
pub trait TextureGatherCompare<Coords, DepthRef> {
    /// Gather depth values with comparison from 4 texels.
    fn gather_compare(
        &self,
        sampler: &SamplerComparison,
        coords: Coords,
        depth_ref: DepthRef,
    ) -> Vec4f;
}

/// Trait for array textures that support `textureSample` with array index and
/// offset.
pub trait TextureSampleArrayOffset<Coords, ArrayIndex, Offset> {
    /// The output type
    type Output;

    /// Sample the texture at the given coordinates, array index, and offset.
    fn sample_array_offset(
        &self,
        sampler: &Sampler,
        coords: Coords,
        array_index: ArrayIndex,
        offset: Offset,
    ) -> Self::Output;
}

/// Trait for textures that support `textureSampleLevel` with offset.
pub trait TextureSampleLevelOffset<Coords, Level, Offset> {
    /// The output type
    type Output;

    /// Sample the texture at the given coordinates and explicit LOD with
    /// offset.
    fn sample_level_offset(
        &self,
        sampler: &Sampler,
        coords: Coords,
        level: Level,
        offset: Offset,
    ) -> Self::Output;
}

/// Trait for array textures that support `textureSampleLevel` with array index.
pub trait TextureSampleLevelArray<Coords, ArrayIndex, Level> {
    /// The output type
    type Output;

    /// Sample the texture at the given coordinates, array index, and explicit
    /// LOD.
    fn sample_level_array(
        &self,
        sampler: &Sampler,
        coords: Coords,
        array_index: ArrayIndex,
        level: Level,
    ) -> Self::Output;
}

/// Trait for array textures that support `textureSampleLevel` with array index
/// and offset.
pub trait TextureSampleLevelArrayOffset<Coords, ArrayIndex, Level, Offset> {
    /// The output type
    type Output;

    /// Sample the texture at the given coordinates, array index, explicit LOD,
    /// and offset.
    fn sample_level_array_offset(
        &self,
        sampler: &Sampler,
        coords: Coords,
        array_index: ArrayIndex,
        level: Level,
        offset: Offset,
    ) -> Self::Output;
}

/// Trait for textures that support `textureSampleBias` with offset.
pub trait TextureSampleBiasOffset<Coords, Bias, Offset> {
    /// The output type
    type Output;

    /// Sample the texture at the given coordinates with LOD bias and offset.
    fn sample_bias_offset(
        &self,
        sampler: &Sampler,
        coords: Coords,
        bias: Bias,
        offset: Offset,
    ) -> Self::Output;
}

/// Trait for array textures that support `textureSampleBias` with array index.
pub trait TextureSampleBiasArray<Coords, ArrayIndex, Bias> {
    /// The output type
    type Output;

    /// Sample the texture at the given coordinates, array index, with LOD bias.
    fn sample_bias_array(
        &self,
        sampler: &Sampler,
        coords: Coords,
        array_index: ArrayIndex,
        bias: Bias,
    ) -> Self::Output;
}

/// Trait for array textures that support `textureSampleBias` with array index
/// and offset.
pub trait TextureSampleBiasArrayOffset<Coords, ArrayIndex, Bias, Offset> {
    /// The output type
    type Output;

    /// Sample the texture at the given coordinates, array index, LOD bias, and
    /// offset.
    fn sample_bias_array_offset(
        &self,
        sampler: &Sampler,
        coords: Coords,
        array_index: ArrayIndex,
        bias: Bias,
        offset: Offset,
    ) -> Self::Output;
}

/// Trait for textures that support `textureSampleGrad` with offset.
pub trait TextureSampleGradOffset<Coords, Ddx, Ddy, Offset> {
    /// The output type
    type Output;

    /// Sample the texture with explicit gradients and offset.
    fn sample_grad_offset(
        &self,
        sampler: &Sampler,
        coords: Coords,
        ddx: Ddx,
        ddy: Ddy,
        offset: Offset,
    ) -> Self::Output;
}

/// Trait for array textures that support `textureSampleGrad` with array index.
pub trait TextureSampleGradArray<Coords, ArrayIndex, Ddx, Ddy> {
    /// The output type
    type Output;

    /// Sample the texture with explicit gradients and array index.
    fn sample_grad_array(
        &self,
        sampler: &Sampler,
        coords: Coords,
        array_index: ArrayIndex,
        ddx: Ddx,
        ddy: Ddy,
    ) -> Self::Output;
}

/// Trait for array textures that support `textureSampleGrad` with array index
/// and offset.
pub trait TextureSampleGradArrayOffset<Coords, ArrayIndex, Ddx, Ddy, Offset> {
    /// The output type
    type Output;

    /// Sample the texture with explicit gradients, array index, and offset.
    fn sample_grad_array_offset(
        &self,
        sampler: &Sampler,
        coords: Coords,
        array_index: ArrayIndex,
        ddx: Ddx,
        ddy: Ddy,
        offset: Offset,
    ) -> Self::Output;
}

/// Trait for depth textures that support `textureSampleCompare` with offset.
pub trait TextureSampleCompareOffset<Coords, DepthRef, Offset> {
    /// Sample the depth texture with comparison and offset.
    fn sample_compare_offset(
        &self,
        sampler: &SamplerComparison,
        coords: Coords,
        depth_ref: DepthRef,
        offset: Offset,
    ) -> f32;
}

/// Trait for depth array textures that support `textureSampleCompare` with
/// array index.
pub trait TextureSampleCompareArray<Coords, ArrayIndex, DepthRef> {
    /// Sample the depth array texture with comparison.
    fn sample_compare_array(
        &self,
        sampler: &SamplerComparison,
        coords: Coords,
        array_index: ArrayIndex,
        depth_ref: DepthRef,
    ) -> f32;
}

/// Trait for depth array textures that support `textureSampleCompare` with
/// array index and offset.
pub trait TextureSampleCompareArrayOffset<Coords, ArrayIndex, DepthRef, Offset> {
    /// Sample the depth array texture with comparison and offset.
    fn sample_compare_array_offset(
        &self,
        sampler: &SamplerComparison,
        coords: Coords,
        array_index: ArrayIndex,
        depth_ref: DepthRef,
        offset: Offset,
    ) -> f32;
}

/// Trait for depth textures that support `textureSampleCompareLevel` with
/// offset.
pub trait TextureSampleCompareLevelOffset<Coords, DepthRef, Offset> {
    /// Sample the depth texture with comparison at mip level 0, with offset.
    fn sample_compare_level_offset(
        &self,
        sampler: &SamplerComparison,
        coords: Coords,
        depth_ref: DepthRef,
        offset: Offset,
    ) -> f32;
}

/// Trait for depth array textures that support `textureSampleCompareLevel` with
/// array index.
pub trait TextureSampleCompareLevelArray<Coords, ArrayIndex, DepthRef> {
    /// Sample the depth array texture with comparison at mip level 0.
    fn sample_compare_level_array(
        &self,
        sampler: &SamplerComparison,
        coords: Coords,
        array_index: ArrayIndex,
        depth_ref: DepthRef,
    ) -> f32;
}

/// Trait for depth array textures that support `textureSampleCompareLevel` with
/// array index and offset.
pub trait TextureSampleCompareLevelArrayOffset<Coords, ArrayIndex, DepthRef, Offset> {
    /// Sample the depth array texture with comparison at mip level 0, with
    /// offset.
    fn sample_compare_level_array_offset(
        &self,
        sampler: &SamplerComparison,
        coords: Coords,
        array_index: ArrayIndex,
        depth_ref: DepthRef,
        offset: Offset,
    ) -> f32;
}

/// Trait for textures that support `textureGather` with offset.
pub trait TextureGatherOffset<Coords, Offset> {
    /// The output type
    type Output;

    /// Gather one component from 4 texels with offset.
    fn gather_offset(
        &self,
        component: u32,
        sampler: &Sampler,
        coords: Coords,
        offset: Offset,
    ) -> Self::Output;
}

/// Trait for array textures that support `textureGather` with array index.
pub trait TextureGatherArray<Coords, ArrayIndex> {
    /// The output type
    type Output;

    /// Gather one component from 4 texels with array index.
    fn gather_array(
        &self,
        component: u32,
        sampler: &Sampler,
        coords: Coords,
        array_index: ArrayIndex,
    ) -> Self::Output;
}

/// Trait for array textures that support `textureGather` with array index and
/// offset.
pub trait TextureGatherArrayOffset<Coords, ArrayIndex, Offset> {
    /// The output type
    type Output;

    /// Gather one component from 4 texels with array index and offset.
    fn gather_array_offset(
        &self,
        component: u32,
        sampler: &Sampler,
        coords: Coords,
        array_index: ArrayIndex,
        offset: Offset,
    ) -> Self::Output;
}

/// Trait for depth textures that support `textureGather` with offset (no
/// component).
pub trait TextureGatherDepthOffset<Coords, Offset> {
    /// Gather depth values from 4 texels with offset.
    fn gather_depth_offset(&self, sampler: &Sampler, coords: Coords, offset: Offset) -> Vec4f;
}

/// Trait for depth array textures that support `textureGather` with array index
/// (no component).
pub trait TextureGatherDepthArray<Coords, ArrayIndex> {
    /// Gather depth values from 4 texels with array index.
    fn gather_depth_array(
        &self,
        sampler: &Sampler,
        coords: Coords,
        array_index: ArrayIndex,
    ) -> Vec4f;
}

/// Trait for depth array textures that support `textureGather` with array index
/// and offset.
pub trait TextureGatherDepthArrayOffset<Coords, ArrayIndex, Offset> {
    /// Gather depth values from 4 texels with array index and offset.
    fn gather_depth_array_offset(
        &self,
        sampler: &Sampler,
        coords: Coords,
        array_index: ArrayIndex,
        offset: Offset,
    ) -> Vec4f;
}

/// Trait for depth textures that support `textureGatherCompare` with offset.
pub trait TextureGatherCompareOffset<Coords, DepthRef, Offset> {
    /// Gather depth values with comparison from 4 texels, with offset.
    fn gather_compare_offset(
        &self,
        sampler: &SamplerComparison,
        coords: Coords,
        depth_ref: DepthRef,
        offset: Offset,
    ) -> Vec4f;
}

/// Trait for depth array textures that support `textureGatherCompare` with
/// array index.
pub trait TextureGatherCompareArray<Coords, ArrayIndex, DepthRef> {
    /// Gather depth values with comparison from 4 texels, with array index.
    fn gather_compare_array(
        &self,
        sampler: &SamplerComparison,
        coords: Coords,
        array_index: ArrayIndex,
        depth_ref: DepthRef,
    ) -> Vec4f;
}

/// Trait for depth array textures that support `textureGatherCompare` with
/// array index and offset.
pub trait TextureGatherCompareArrayOffset<Coords, ArrayIndex, DepthRef, Offset> {
    /// Gather depth values with comparison from 4 texels, with array index and
    /// offset.
    fn gather_compare_array_offset(
        &self,
        sampler: &SamplerComparison,
        coords: Coords,
        array_index: ArrayIndex,
        depth_ref: DepthRef,
        offset: Offset,
    ) -> Vec4f;
}

/// Trait for storage textures that support `textureStore`.
pub trait TextureStore<Coords, Value> {
    /// Store a value to the storage texture at the given coordinates.
    fn store(&self, coords: Coords, value: Value);
}

/// Trait for storage array textures that support `textureStore` with array
/// index.
pub trait TextureStoreArray<Coords, ArrayIndex, Value> {
    /// Store a value to the storage array texture at the given coordinates and
    /// array index.
    fn store_array(&self, coords: Coords, array_index: ArrayIndex, value: Value);
}

/// Trait for storage textures that support `textureLoad` (no mip level
/// parameter, unlike [`TextureLoad`]). WGSL §17.7.4 storage overloads.
pub trait TextureLoadStorage<Coords> {
    /// The output type (`vec4<f32>`, `vec4<u32>`, or `vec4<i32>` depending on
    /// the texel format).
    type Output;

    /// Load a texel at the given coordinates.
    fn load_storage(&self, coords: Coords) -> Self::Output;
}

/// Trait for storage array textures that support `textureLoad` with array
/// index (no mip level). WGSL §17.7.4 storage overloads.
pub trait TextureLoadStorageArray<Coords, ArrayIndex> {
    /// The output type.
    type Output;

    /// Load a texel at the given coordinates and array index.
    fn load_storage_array(&self, coords: Coords, array_index: ArrayIndex) -> Self::Output;
}

/// Trait for types that can be used as texture coordinates.
pub trait IntoCoord {
    fn into_i32(self) -> i32;
    fn into_u32(self) -> u32;
}

impl IntoCoord for i32 {
    fn into_i32(self) -> i32 {
        self
    }
    fn into_u32(self) -> u32 {
        self.max(0) as u32
    }
}

impl IntoCoord for u32 {
    fn into_i32(self) -> i32 {
        self as i32
    }
    fn into_u32(self) -> u32 {
        self
    }
}

/// Trait for types that can be used as mip levels.
pub trait IntoLevel {
    fn into_level(self) -> u32;
}

impl IntoLevel for i32 {
    fn into_level(self) -> u32 {
        self.max(0) as u32
    }
}

impl IntoLevel for u32 {
    fn into_level(self) -> u32 {
        self
    }
}

/// Returns the dimensions of a texture.
///
/// For 1D textures, returns `u32`.
/// For 2D textures, returns `Vec2u`.
/// For 3D textures, returns `Vec3u`.
///
/// To specify a mipmap level use [`texture_dimensions_level`].
///
/// # WGSL Equivalent
///
/// ```wgsl
/// let dims = textureDimensions(my_texture);
/// ```
pub fn texture_dimensions<T: TextureDimensionsQuery>(t: &T) -> T::Output {
    t.query_dimensions(0)
}

/// Returns the dimensions of a texture at a given mipmap level.
///
/// For 1D textures, returns `u32`.
/// For 2D textures, returns `Vec2u`.
/// For 3D textures, returns `Vec3u`.
///
/// # WGSL Equivalent
///
/// ```wgsl
/// let dims_at_level = textureDimensions(my_texture, 2);
/// ```
pub fn texture_dimensions_level<T: TextureDimensionsQuery>(
    t: &T,
    level: impl IntoLevel,
) -> T::Output {
    t.query_dimensions(level.into_level())
}

/// Returns the number of array layers in an array texture.
///
/// # WGSL Equivalent
///
/// ```wgsl
/// let layers = textureNumLayers(my_texture_array);
/// ```
pub fn texture_num_layers<T: TextureNumLayersQuery>(t: &T) -> u32 {
    t.query_num_layers()
}

/// Returns the number of mip levels in a texture.
///
/// # WGSL Equivalent
///
/// ```wgsl
/// let levels = textureNumLevels(my_texture);
/// ```
pub fn texture_num_levels<T: TextureNumLevelsQuery>(t: &T) -> u32 {
    t.query_num_levels()
}

/// Returns the number of samples in a multisampled texture.
///
/// # WGSL Equivalent
///
/// ```wgsl
/// let samples = textureNumSamples(my_multisampled_texture);
/// ```
pub fn texture_num_samples<T: TextureNumSamplesQuery>(t: &T) -> u32 {
    t.query_num_samples()
}

/// Reads a single texel from a texture without sampling or filtering.
///
/// # WGSL Equivalent
///
/// ```wgsl
/// let texel = textureLoad(my_texture, coords, level);
/// ```
pub fn texture_load<T, C, L>(t: &T, coords: C, level: L) -> T::Output
where
    T: TextureLoad<C, L>,
{
    t.load(coords, level)
}

/// Reads a single texel from a multisampled texture.
///
/// # WGSL Equivalent
///
/// ```wgsl
/// let texel = textureLoad(my_multisampled_texture, coords, sample_index);
/// ```
pub fn texture_load_multisampled<T, C, S>(t: &T, coords: C, sample_index: S) -> T::Output
where
    T: TextureLoadMultisampled<C, S>,
{
    t.load_multisampled(coords, sample_index)
}

/// Reads a single texel from an array texture.
///
/// # WGSL Equivalent
///
/// ```wgsl
/// let texel = textureLoad(my_array_texture, coords, array_index, level);
/// ```
pub fn texture_load_array<T, C, A, L>(t: &T, coords: C, array_index: A, level: L) -> T::Output
where
    T: TextureLoadArray<C, A, L>,
{
    t.load_array(coords, array_index, level)
}

/// Samples a texture.
///
/// Must only be used in a fragment shader stage (enforced by WGSL, not by
/// Rust). On CPU, this samples at mip level 0 since screen-space derivatives
/// are not available.
///
/// # WGSL Equivalent
///
/// ```wgsl
/// let color = textureSample(my_texture, my_sampler, uv);
/// ```
pub fn texture_sample<T, C>(t: &T, s: &Sampler, coords: C) -> T::Output
where
    T: TextureSample<C>,
{
    t.sample(s, coords)
}

/// Samples a texture with an offset applied to the texture coordinates.
///
/// # WGSL Equivalent
///
/// ```wgsl
/// let color = textureSample(my_texture, my_sampler, uv, vec2<i32>(1, 0));
/// ```
pub fn texture_sample_offset<T, C, O>(t: &T, s: &Sampler, coords: C, offset: O) -> T::Output
where
    T: TextureSampleOffset<C, O>,
{
    t.sample_offset(s, coords, offset)
}

/// Samples a texture array.
///
/// # WGSL Equivalent
///
/// ```wgsl
/// let color = textureSample(my_texture_array, my_sampler, uv, array_index);
/// ```
pub fn texture_sample_array<T, C, A>(t: &T, s: &Sampler, coords: C, array_index: A) -> T::Output
where
    T: TextureSampleArray<C, A>,
{
    t.sample_array(s, coords, array_index)
}

/// Samples a texture at an explicit mip level.
///
/// # WGSL Equivalent
///
/// ```wgsl
/// let color = textureSampleLevel(my_texture, my_sampler, uv, 2.0);
/// ```
pub fn texture_sample_level<T, C, L>(t: &T, s: &Sampler, coords: C, level: L) -> T::Output
where
    T: TextureSampleLevel<C, L>,
{
    t.sample_level(s, coords, level)
}

/// Samples a texture with a bias added to the mip level.
///
/// # WGSL Equivalent
///
/// ```wgsl
/// let color = textureSampleBias(my_texture, my_sampler, uv, 1.0);
/// ```
pub fn texture_sample_bias<T, C, B>(t: &T, s: &Sampler, coords: C, bias: B) -> T::Output
where
    T: TextureSampleBias<C, B>,
{
    t.sample_bias(s, coords, bias)
}

/// Samples a texture with explicit gradients for LOD calculation.
///
/// # WGSL Equivalent
///
/// ```wgsl
/// let color = textureSampleGrad(my_texture, my_sampler, uv, ddx, ddy);
/// ```
pub fn texture_sample_grad<T, C, D>(t: &T, s: &Sampler, coords: C, ddx: D, ddy: D) -> T::Output
where
    T: TextureSampleGrad<C, D, D>,
{
    t.sample_grad(s, coords, ddx, ddy)
}

/// Samples a depth texture and compares the result against a reference value.
///
/// # WGSL Equivalent
///
/// ```wgsl
/// let shadow = textureSampleCompare(shadow_map, shadow_sampler, uv, depth_ref);
/// ```
pub fn texture_sample_compare<T, C, R>(t: &T, s: &SamplerComparison, coords: C, depth_ref: R) -> f32
where
    T: TextureSampleCompare<C, R>,
{
    t.sample_compare(s, coords, depth_ref)
}

/// Samples a depth texture at mip level 0 and compares the result.
///
/// Per the WGSL spec, `textureSampleCompareLevel` always samples at mip level
/// 0. Unlike `textureSampleCompare`, this function may be invoked in any shader
/// stage.
///
/// # WGSL Equivalent
///
/// ```wgsl
/// let shadow = textureSampleCompareLevel(shadow_map, shadow_sampler, uv, depth_ref);
/// ```
pub fn texture_sample_compare_level<T, C, R>(
    t: &T,
    s: &SamplerComparison,
    coords: C,
    depth_ref: R,
) -> f32
where
    T: TextureSampleCompareLevel<C, R>,
{
    t.sample_compare_level(s, coords, depth_ref)
}

/// Samples a texture at its base mip level with coordinates clamped to the
/// edge.
///
/// The coordinates are clamped to `[0.5/dim, 1.0 - 0.5/dim]` before sampling,
/// which prevents wrapping artifacts regardless of the sampler's address mode.
///
/// # WGSL Equivalent
///
/// ```wgsl
/// let color = textureSampleBaseClampToEdge(my_texture, my_sampler, uv);
/// ```
pub fn texture_sample_base_clamp_to_edge<T, C>(t: &T, s: &Sampler, coords: C) -> T::Output
where
    T: TextureSampleBaseClampToEdge<C>,
{
    t.sample_base_clamp_to_edge(s, coords)
}

/// Gathers one component from 4 texels that would be used in bilinear
/// filtering.
///
/// # WGSL Equivalent
///
/// ```wgsl
/// let gathered = textureGather(0, my_texture, my_sampler, uv);
/// ```
pub fn texture_gather<T, C>(component: impl IntoCoord, t: &T, s: &Sampler, coords: C) -> T::Output
where
    T: TextureGather<C>,
{
    t.gather(component.into_u32(), s, coords)
}

/// Gathers depth values from 4 texels (for depth textures).
///
/// # WGSL Equivalent
///
/// ```wgsl
/// let gathered = textureGather(depth_texture, my_sampler, uv);
/// ```
pub fn texture_gather_depth<T, C>(t: &T, s: &Sampler, coords: C) -> Vec4f
where
    T: TextureGatherDepth<C>,
{
    t.gather_depth(s, coords)
}

/// Gathers depth values with comparison from 4 texels.
///
/// # WGSL Equivalent
///
/// ```wgsl
/// let gathered = textureGatherCompare(depth_texture, shadow_sampler, uv, depth_ref);
/// ```
pub fn texture_gather_compare<T, C, R>(
    t: &T,
    s: &SamplerComparison,
    coords: C,
    depth_ref: R,
) -> Vec4f
where
    T: TextureGatherCompare<C, R>,
{
    t.gather_compare(s, coords, depth_ref)
}

/// Samples a texture array with an offset applied.
///
/// # WGSL Equivalent
///
/// ```wgsl
/// let color = textureSample(my_array_tex, my_sampler, uv, array_index, vec2<i32>(1, 0));
/// ```
pub fn texture_sample_array_offset<T, C, A, O>(
    t: &T,
    s: &Sampler,
    coords: C,
    array_index: A,
    offset: O,
) -> T::Output
where
    T: TextureSampleArrayOffset<C, A, O>,
{
    t.sample_array_offset(s, coords, array_index, offset)
}

/// Samples a texture at an explicit mip level with an offset.
///
/// # WGSL Equivalent
///
/// ```wgsl
/// let color = textureSampleLevel(my_texture, my_sampler, uv, 2.0, vec2<i32>(1, 0));
/// ```
pub fn texture_sample_level_offset<T, C, L, O>(
    t: &T,
    s: &Sampler,
    coords: C,
    level: L,
    offset: O,
) -> T::Output
where
    T: TextureSampleLevelOffset<C, L, O>,
{
    t.sample_level_offset(s, coords, level, offset)
}

/// Samples a texture array at an explicit mip level.
///
/// # WGSL Equivalent
///
/// ```wgsl
/// let color = textureSampleLevel(my_array_tex, my_sampler, uv, array_index, 2.0);
/// ```
pub fn texture_sample_level_array<T, C, A, L>(
    t: &T,
    s: &Sampler,
    coords: C,
    array_index: A,
    level: L,
) -> T::Output
where
    T: TextureSampleLevelArray<C, A, L>,
{
    t.sample_level_array(s, coords, array_index, level)
}

/// Samples a texture array at an explicit mip level with an offset.
///
/// # WGSL Equivalent
///
/// ```wgsl
/// let color = textureSampleLevel(my_array_tex, my_sampler, uv, idx, 2.0, vec2<i32>(1, 0));
/// ```
pub fn texture_sample_level_array_offset<T, C, A, L, O>(
    t: &T,
    s: &Sampler,
    coords: C,
    array_index: A,
    level: L,
    offset: O,
) -> T::Output
where
    T: TextureSampleLevelArrayOffset<C, A, L, O>,
{
    t.sample_level_array_offset(s, coords, array_index, level, offset)
}

/// Samples a texture with a bias and an offset.
///
/// # WGSL Equivalent
///
/// ```wgsl
/// let color = textureSampleBias(my_texture, my_sampler, uv, 1.0, vec2<i32>(1, 0));
/// ```
pub fn texture_sample_bias_offset<T, C, B, O>(
    t: &T,
    s: &Sampler,
    coords: C,
    bias: B,
    offset: O,
) -> T::Output
where
    T: TextureSampleBiasOffset<C, B, O>,
{
    t.sample_bias_offset(s, coords, bias, offset)
}

/// Samples a texture array with a bias.
///
/// # WGSL Equivalent
///
/// ```wgsl
/// let color = textureSampleBias(my_array_tex, my_sampler, uv, array_index, 1.0);
/// ```
pub fn texture_sample_bias_array<T, C, A, B>(
    t: &T,
    s: &Sampler,
    coords: C,
    array_index: A,
    bias: B,
) -> T::Output
where
    T: TextureSampleBiasArray<C, A, B>,
{
    t.sample_bias_array(s, coords, array_index, bias)
}

/// Samples a texture array with a bias and an offset.
///
/// # WGSL Equivalent
///
/// ```wgsl
/// let color = textureSampleBias(my_array_tex, my_sampler, uv, idx, 1.0, vec2<i32>(1, 0));
/// ```
pub fn texture_sample_bias_array_offset<T, C, A, B, O>(
    t: &T,
    s: &Sampler,
    coords: C,
    array_index: A,
    bias: B,
    offset: O,
) -> T::Output
where
    T: TextureSampleBiasArrayOffset<C, A, B, O>,
{
    t.sample_bias_array_offset(s, coords, array_index, bias, offset)
}

/// Samples a texture with explicit gradients and an offset.
///
/// # WGSL Equivalent
///
/// ```wgsl
/// let color = textureSampleGrad(my_texture, my_sampler, uv, ddx, ddy, vec2<i32>(1, 0));
/// ```
pub fn texture_sample_grad_offset<T, C, D, O>(
    t: &T,
    s: &Sampler,
    coords: C,
    ddx: D,
    ddy: D,
    offset: O,
) -> T::Output
where
    T: TextureSampleGradOffset<C, D, D, O>,
{
    t.sample_grad_offset(s, coords, ddx, ddy, offset)
}

/// Samples a texture array with explicit gradients.
///
/// # WGSL Equivalent
///
/// ```wgsl
/// let color = textureSampleGrad(my_array_tex, my_sampler, uv, array_index, ddx, ddy);
/// ```
pub fn texture_sample_grad_array<T, C, A, D>(
    t: &T,
    s: &Sampler,
    coords: C,
    array_index: A,
    ddx: D,
    ddy: D,
) -> T::Output
where
    T: TextureSampleGradArray<C, A, D, D>,
{
    t.sample_grad_array(s, coords, array_index, ddx, ddy)
}

/// Samples a texture array with explicit gradients and an offset.
///
/// # WGSL Equivalent
///
/// ```wgsl
/// let color = textureSampleGrad(my_arr, my_sampler, uv, idx, ddx, ddy, vec2<i32>(1, 0));
/// ```
pub fn texture_sample_grad_array_offset<T, C, A, D, O>(
    t: &T,
    s: &Sampler,
    coords: C,
    array_index: A,
    ddx: D,
    ddy: D,
    offset: O,
) -> T::Output
where
    T: TextureSampleGradArrayOffset<C, A, D, D, O>,
{
    t.sample_grad_array_offset(s, coords, array_index, ddx, ddy, offset)
}

/// Samples a depth texture with comparison and an offset.
///
/// # WGSL Equivalent
///
/// ```wgsl
/// let shadow = textureSampleCompare(shadow_map, sampler, uv, depth_ref, vec2<i32>(1, 0));
/// ```
pub fn texture_sample_compare_offset<T, C, R, O>(
    t: &T,
    s: &SamplerComparison,
    coords: C,
    depth_ref: R,
    offset: O,
) -> f32
where
    T: TextureSampleCompareOffset<C, R, O>,
{
    t.sample_compare_offset(s, coords, depth_ref, offset)
}

/// Samples a depth array texture with comparison.
///
/// # WGSL Equivalent
///
/// ```wgsl
/// let shadow = textureSampleCompare(shadow_map, sampler, uv, array_index, depth_ref);
/// ```
pub fn texture_sample_compare_array<T, C, A, R>(
    t: &T,
    s: &SamplerComparison,
    coords: C,
    array_index: A,
    depth_ref: R,
) -> f32
where
    T: TextureSampleCompareArray<C, A, R>,
{
    t.sample_compare_array(s, coords, array_index, depth_ref)
}

/// Samples a depth array texture with comparison and an offset.
///
/// # WGSL Equivalent
///
/// ```wgsl
/// let shadow = textureSampleCompare(map, s, uv, idx, depth_ref, vec2<i32>(1, 0));
/// ```
pub fn texture_sample_compare_array_offset<T, C, A, R, O>(
    t: &T,
    s: &SamplerComparison,
    coords: C,
    array_index: A,
    depth_ref: R,
    offset: O,
) -> f32
where
    T: TextureSampleCompareArrayOffset<C, A, R, O>,
{
    t.sample_compare_array_offset(s, coords, array_index, depth_ref, offset)
}

/// Samples a depth texture at mip level 0 with comparison and an offset.
///
/// # WGSL Equivalent
///
/// ```wgsl
/// let shadow = textureSampleCompareLevel(map, sampler, uv, depth_ref, vec2<i32>(1, 0));
/// ```
pub fn texture_sample_compare_level_offset<T, C, R, O>(
    t: &T,
    s: &SamplerComparison,
    coords: C,
    depth_ref: R,
    offset: O,
) -> f32
where
    T: TextureSampleCompareLevelOffset<C, R, O>,
{
    t.sample_compare_level_offset(s, coords, depth_ref, offset)
}

/// Samples a depth array texture at mip level 0 with comparison.
///
/// # WGSL Equivalent
///
/// ```wgsl
/// let shadow = textureSampleCompareLevel(map, sampler, uv, array_index, depth_ref);
/// ```
pub fn texture_sample_compare_level_array<T, C, A, R>(
    t: &T,
    s: &SamplerComparison,
    coords: C,
    array_index: A,
    depth_ref: R,
) -> f32
where
    T: TextureSampleCompareLevelArray<C, A, R>,
{
    t.sample_compare_level_array(s, coords, array_index, depth_ref)
}

/// Samples a depth array texture at mip level 0 with comparison and an offset.
///
/// # WGSL Equivalent
///
/// ```wgsl
/// let shadow = textureSampleCompareLevel(map, s, uv, idx, depth_ref, vec2<i32>(1, 0));
/// ```
pub fn texture_sample_compare_level_array_offset<T, C, A, R, O>(
    t: &T,
    s: &SamplerComparison,
    coords: C,
    array_index: A,
    depth_ref: R,
    offset: O,
) -> f32
where
    T: TextureSampleCompareLevelArrayOffset<C, A, R, O>,
{
    t.sample_compare_level_array_offset(s, coords, array_index, depth_ref, offset)
}

/// Gathers one component from 4 texels with an offset.
///
/// # WGSL Equivalent
///
/// ```wgsl
/// let gathered = textureGather(0, my_texture, my_sampler, uv, vec2<i32>(1, 0));
/// ```
pub fn texture_gather_offset<T, C, O>(
    component: impl IntoCoord,
    t: &T,
    s: &Sampler,
    coords: C,
    offset: O,
) -> T::Output
where
    T: TextureGatherOffset<C, O>,
{
    t.gather_offset(component.into_u32(), s, coords, offset)
}

/// Gathers one component from 4 texels of an array texture.
///
/// # WGSL Equivalent
///
/// ```wgsl
/// let gathered = textureGather(0, my_array_tex, my_sampler, uv, array_index);
/// ```
pub fn texture_gather_array<T, C, A>(
    component: impl IntoCoord,
    t: &T,
    s: &Sampler,
    coords: C,
    array_index: A,
) -> T::Output
where
    T: TextureGatherArray<C, A>,
{
    t.gather_array(component.into_u32(), s, coords, array_index)
}

/// Gathers one component from 4 texels of an array texture with an offset.
///
/// # WGSL Equivalent
///
/// ```wgsl
/// let gathered = textureGather(0, my_arr, my_sampler, uv, idx, vec2<i32>(1, 0));
/// ```
pub fn texture_gather_array_offset<T, C, A, O>(
    component: impl IntoCoord,
    t: &T,
    s: &Sampler,
    coords: C,
    array_index: A,
    offset: O,
) -> T::Output
where
    T: TextureGatherArrayOffset<C, A, O>,
{
    t.gather_array_offset(component.into_u32(), s, coords, array_index, offset)
}

/// Gathers depth values from 4 texels with an offset (no component).
///
/// # WGSL Equivalent
///
/// ```wgsl
/// let gathered = textureGather(depth_texture, my_sampler, uv, vec2<i32>(1, 0));
/// ```
pub fn texture_gather_depth_offset<T, C, O>(t: &T, s: &Sampler, coords: C, offset: O) -> Vec4f
where
    T: TextureGatherDepthOffset<C, O>,
{
    t.gather_depth_offset(s, coords, offset)
}

/// Gathers depth values from 4 texels of an array texture (no component).
///
/// # WGSL Equivalent
///
/// ```wgsl
/// let gathered = textureGather(depth_array_texture, my_sampler, uv, array_index);
/// ```
pub fn texture_gather_depth_array<T, C, A>(t: &T, s: &Sampler, coords: C, array_index: A) -> Vec4f
where
    T: TextureGatherDepthArray<C, A>,
{
    t.gather_depth_array(s, coords, array_index)
}

/// Gathers depth values from 4 texels of an array texture with an offset.
///
/// # WGSL Equivalent
///
/// ```wgsl
/// let gathered = textureGather(depth_arr, my_sampler, uv, idx, vec2<i32>(1, 0));
/// ```
pub fn texture_gather_depth_array_offset<T, C, A, O>(
    t: &T,
    s: &Sampler,
    coords: C,
    array_index: A,
    offset: O,
) -> Vec4f
where
    T: TextureGatherDepthArrayOffset<C, A, O>,
{
    t.gather_depth_array_offset(s, coords, array_index, offset)
}

/// Gathers depth values with comparison from 4 texels, with an offset.
///
/// # WGSL Equivalent
///
/// ```wgsl
/// let gathered = textureGatherCompare(depth_tex, sampler, uv, depth_ref, vec2<i32>(1, 0));
/// ```
pub fn texture_gather_compare_offset<T, C, R, O>(
    t: &T,
    s: &SamplerComparison,
    coords: C,
    depth_ref: R,
    offset: O,
) -> Vec4f
where
    T: TextureGatherCompareOffset<C, R, O>,
{
    t.gather_compare_offset(s, coords, depth_ref, offset)
}

/// Gathers depth values with comparison from 4 texels of an array texture.
///
/// # WGSL Equivalent
///
/// ```wgsl
/// let gathered = textureGatherCompare(depth_arr, sampler, uv, array_index, depth_ref);
/// ```
pub fn texture_gather_compare_array<T, C, A, R>(
    t: &T,
    s: &SamplerComparison,
    coords: C,
    array_index: A,
    depth_ref: R,
) -> Vec4f
where
    T: TextureGatherCompareArray<C, A, R>,
{
    t.gather_compare_array(s, coords, array_index, depth_ref)
}

/// Gathers depth values with comparison from 4 texels of an array texture, with
/// an offset.
///
/// # WGSL Equivalent
///
/// ```wgsl
/// let gathered = textureGatherCompare(arr, sampler, uv, idx, depth_ref, vec2<i32>(1, 0));
/// ```
pub fn texture_gather_compare_array_offset<T, C, A, R, O>(
    t: &T,
    s: &SamplerComparison,
    coords: C,
    array_index: A,
    depth_ref: R,
    offset: O,
) -> Vec4f
where
    T: TextureGatherCompareArrayOffset<C, A, R, O>,
{
    t.gather_compare_array_offset(s, coords, array_index, depth_ref, offset)
}

/// Stores a value to a storage texture.
///
/// # WGSL Equivalent
///
/// ```wgsl
/// textureStore(my_storage_texture, coords, value);
/// ```
pub fn texture_store<T, C, V>(t: &T, coords: C, value: V)
where
    T: TextureStore<C, V>,
{
    t.store(coords, value)
}

/// Stores a value to a storage array texture.
///
/// # WGSL Equivalent
///
/// ```wgsl
/// textureStore(my_storage_array_texture, coords, array_index, value);
/// ```
pub fn texture_store_array<T, C, A, V>(t: &T, coords: C, array_index: A, value: V)
where
    T: TextureStoreArray<C, A, V>,
{
    t.store_array(coords, array_index, value)
}

/// Reads a single texel from a storage texture without a mip level.
///
/// Unlike [`texture_load`], this overload takes no `level` parameter —
/// storage textures have no mip levels (WGSL §17.7.4).
///
/// # WGSL Equivalent
///
/// ```wgsl
/// let texel = textureLoad(my_storage_texture, coords);
/// ```
pub fn texture_load_storage<T, C>(t: &T, coords: C) -> T::Output
where
    T: TextureLoadStorage<C>,
{
    t.load_storage(coords)
}

/// Reads a single texel from a storage array texture without a mip level.
///
/// # WGSL Equivalent
///
/// ```wgsl
/// let texel = textureLoad(my_storage_array_texture, coords, array_index);
/// ```
pub fn texture_load_storage_array<T, C, A>(t: &T, coords: C, array_index: A) -> T::Output
where
    T: TextureLoadStorageArray<C, A>,
{
    t.load_storage_array(coords, array_index)
}

/// Helper function for bilinear interpolation.
fn bilinear_interpolate<T: Copy + Default + Into<f32> + From<f32>>(
    tl: [T; 4],
    tr: [T; 4],
    bl: [T; 4],
    br: [T; 4],
    fx: f32,
    fy: f32,
) -> [T; 4] {
    std::array::from_fn(|i| {
        let top = tl[i].into() * (1.0 - fx) + tr[i].into() * fx;
        let bottom = bl[i].into() * (1.0 - fx) + br[i].into() * fx;
        T::from(top * (1.0 - fy) + bottom * fy)
    })
}

/// Helper function to convert normalized coordinates to texel coordinates.
fn normalized_to_texel(coord: f32, size: u32) -> (u32, f32) {
    let scaled = coord * size as f32;
    let texel = (scaled.floor() as i32).clamp(0, (size as i32) - 1) as u32;
    // Use `scaled.fract().abs()` instead of `scaled.fract()` because
    // `f32::fract` returns a negative value for negative inputs (e.g.
    // `(-0.5).fract() == -0.5`), which would produce negative interpolation
    // weights and nonsensical results when sampling below texel 0.
    let frac = scaled.fract().abs();
    (texel, frac)
}

/// Sample a 2D texture at the given normalized coordinates.
pub(crate) fn sample_texture_2d<T: Copy + Default + Into<f32> + From<f32>>(
    data: &TextureData2D<T>,
    sampler_state: &SamplerState,
    u: f32,
    v: f32,
    level: u32,
) -> [T; 4] {
    let u = SamplerState::apply_address_mode(sampler_state.address_mode_u, u);
    let v = SamplerState::apply_address_mode(sampler_state.address_mode_v, v);

    let (width, height) = data.dimensions(level);
    if width == 0 || height == 0 {
        return std::array::from_fn(|_| T::default());
    }

    match sampler_state.min_filter {
        FilterMode::Nearest => {
            let x = Ord::min((u * width as f32).floor() as u32, width - 1);
            let y = Ord::min((v * height as f32).floor() as u32, height - 1);
            data.get_pixel(x, y, level)
                .copied()
                .unwrap_or_else(|| std::array::from_fn(|_| T::default()))
        }
        FilterMode::Linear => {
            let (x0, fx) = normalized_to_texel(u - 0.5 / width as f32, width);
            let (y0, fy) = normalized_to_texel(v - 0.5 / height as f32, height);
            let x1 = Ord::min(x0 + 1, width - 1);
            let y1 = Ord::min(y0 + 1, height - 1);

            let default_pixel = || std::array::from_fn(|_| T::default());
            let tl = data
                .get_pixel(x0, y0, level)
                .copied()
                .unwrap_or_else(default_pixel);
            let tr = data
                .get_pixel(x1, y0, level)
                .copied()
                .unwrap_or_else(default_pixel);
            let bl = data
                .get_pixel(x0, y1, level)
                .copied()
                .unwrap_or_else(default_pixel);
            let br = data
                .get_pixel(x1, y1, level)
                .copied()
                .unwrap_or_else(default_pixel);

            bilinear_interpolate(tl, tr, bl, br, fx, fy)
        }
    }
}

/// Sample a depth 2D texture at the given normalized coordinates.
pub(crate) fn sample_depth_texture_2d(
    data: &TextureDataDepth2D,
    sampler_state: &SamplerState,
    u: f32,
    v: f32,
    level: u32,
) -> f32 {
    let u = SamplerState::apply_address_mode(sampler_state.address_mode_u, u);
    let v = SamplerState::apply_address_mode(sampler_state.address_mode_v, v);

    let (width, height) = data.dimensions(level);
    if width == 0 || height == 0 {
        return 0.0;
    }

    match sampler_state.min_filter {
        FilterMode::Nearest => {
            let x = Ord::min((u * width as f32).floor() as u32, width - 1);
            let y = Ord::min((v * height as f32).floor() as u32, height - 1);
            data.get_depth(x, y, level).unwrap_or(0.0)
        }
        FilterMode::Linear => {
            let (x0, fx) = normalized_to_texel(u - 0.5 / width as f32, width);
            let (y0, fy) = normalized_to_texel(v - 0.5 / height as f32, height);
            let x1 = Ord::min(x0 + 1, width - 1);
            let y1 = Ord::min(y0 + 1, height - 1);

            let tl = data.get_depth(x0, y0, level).unwrap_or(0.0);
            let tr = data.get_depth(x1, y0, level).unwrap_or(0.0);
            let bl = data.get_depth(x0, y1, level).unwrap_or(0.0);
            let br = data.get_depth(x1, y1, level).unwrap_or(0.0);

            let top = tl * (1.0 - fx) + tr * fx;
            let bottom = bl * (1.0 - fx) + br * fx;
            top * (1.0 - fy) + bottom * fy
        }
    }
}

/// Gather the 4 depth texels that would be used in bilinear filtering at mip
/// level 0, returning them in the WGSL-specified gather component order:
///   x = (u_min, v_max), y = (u_max, v_max),
///   z = (u_max, v_min), w = (u_min, v_min).
pub(crate) fn gather_4_depth_texels(
    data: &TextureDataDepth2D,
    sampler_state: &SamplerState,
    u: f32,
    v: f32,
) -> [f32; 4] {
    let u = SamplerState::apply_address_mode(sampler_state.address_mode_u, u);
    let v = SamplerState::apply_address_mode(sampler_state.address_mode_v, v);

    let (width, height) = data.dimensions(0);
    if width == 0 || height == 0 {
        return [0.0; 4];
    }

    // Find the 4 texels that bilinear filtering would use.
    // The texel grid center is offset by half a texel from the normalized
    // coordinate origin, so we subtract 0.5/dim before computing the floor.
    let (x0, _fx) = normalized_to_texel(u - 0.5 / width as f32, width);
    let (y0, _fy) = normalized_to_texel(v - 0.5 / height as f32, height);
    let x1 = Ord::min(x0 + 1, width - 1);
    let y1 = Ord::min(y0 + 1, height - 1);

    let tl = data.get_depth(x0, y0, 0).unwrap_or(0.0); // (u_min, v_min)
    let tr = data.get_depth(x1, y0, 0).unwrap_or(0.0); // (u_max, v_min)
    let bl = data.get_depth(x0, y1, 0).unwrap_or(0.0); // (u_min, v_max)
    let br = data.get_depth(x1, y1, 0).unwrap_or(0.0); // (u_max, v_max)

    // WGSL gather order: x=(u_min,v_max), y=(u_max,v_max), z=(u_max,v_min),
    // w=(u_min,v_min)
    [bl, br, tr, tl]
}

/// Helper for trilinear interpolation across the 8 corners of a 3D cell.
///
/// `fx`, `fy`, `fz` are the fractional weights in `[0, 1)` for the +1
/// direction along each axis. The 8 corners are named `(x0|y0|z0)` style:
/// `c000`, `c100`, `c010`, `c110`, `c001`, `c101`, `c011`, `c111`, where
/// a `1` in position `x/y/z` means the +1 texel along that axis.
#[allow(clippy::too_many_arguments)]
fn trilinear_interpolate<T: Copy + Default + Into<f32> + From<f32>>(
    c000: [T; 4],
    c100: [T; 4],
    c010: [T; 4],
    c110: [T; 4],
    c001: [T; 4],
    c101: [T; 4],
    c011: [T; 4],
    c111: [T; 4],
    fx: f32,
    fy: f32,
    fz: f32,
) -> [T; 4] {
    let lerp = |a: f32, b: f32, t: f32| a * (1.0 - t) + b * t;
    std::array::from_fn(|i| {
        let top = lerp(
            lerp(c000[i].into(), c100[i].into(), fx),
            lerp(c010[i].into(), c110[i].into(), fx),
            fy,
        );
        let bottom = lerp(
            lerp(c001[i].into(), c101[i].into(), fx),
            lerp(c011[i].into(), c111[i].into(), fx),
            fy,
        );
        T::from(lerp(top, bottom, fz))
    })
}

/// Sample a 1D texture at the given normalized coordinate.
pub(crate) fn sample_texture_1d<T: Copy + Default + Into<f32> + From<f32>>(
    data: &TextureData1D<T>,
    sampler_state: &SamplerState,
    u: f32,
    level: u32,
) -> [T; 4] {
    let u = SamplerState::apply_address_mode(sampler_state.address_mode_u, u);

    let width = data.width(level);
    if width == 0 {
        return std::array::from_fn(|_| T::default());
    }

    match sampler_state.min_filter {
        FilterMode::Nearest => {
            let x = Ord::min((u * width as f32).floor() as u32, width - 1);
            data.get_pixel(x, level)
                .copied()
                .unwrap_or_else(|| std::array::from_fn(|_| T::default()))
        }
        FilterMode::Linear => {
            let (x0, fx) = normalized_to_texel(u - 0.5 / width as f32, width);
            let x1 = Ord::min(x0 + 1, width - 1);
            let left = data
                .get_pixel(x0, level)
                .copied()
                .unwrap_or_else(|| std::array::from_fn(|_| T::default()));
            let right = data
                .get_pixel(x1, level)
                .copied()
                .unwrap_or_else(|| std::array::from_fn(|_| T::default()));
            std::array::from_fn(|i| T::from(left[i].into() * (1.0 - fx) + right[i].into() * fx))
        }
    }
}

/// Sample a 3D texture at the given normalized coordinates.
///
/// `u`, `v`, `w` are normalized coordinates in `[0, 1]`. The W coordinate
/// uses `address_mode_w` for wrapping. Nearest filtering picks the nearest
/// texel in 3D; linear filtering does trilinear interpolation across the 8
/// surrounding texels.
pub(crate) fn sample_texture_3d<T: Copy + Default + Into<f32> + From<f32>>(
    data: &TextureData3D<T>,
    sampler_state: &SamplerState,
    u: f32,
    v: f32,
    w: f32,
    level: u32,
) -> [T; 4] {
    let u = SamplerState::apply_address_mode(sampler_state.address_mode_u, u);
    let v = SamplerState::apply_address_mode(sampler_state.address_mode_v, v);
    let w = SamplerState::apply_address_mode(sampler_state.address_mode_w, w);

    let (width, height, depth) = data.dimensions(level);
    if width == 0 || height == 0 || depth == 0 {
        return std::array::from_fn(|_| T::default());
    }

    match sampler_state.min_filter {
        FilterMode::Nearest => {
            let x = Ord::min((u * width as f32).floor() as u32, width - 1);
            let y = Ord::min((v * height as f32).floor() as u32, height - 1);
            let z = Ord::min((w * depth as f32).floor() as u32, depth - 1);
            data.get_pixel(x, y, z, level)
                .copied()
                .unwrap_or_else(|| std::array::from_fn(|_| T::default()))
        }
        FilterMode::Linear => {
            let (x0, fx) = normalized_to_texel(u - 0.5 / width as f32, width);
            let (y0, fy) = normalized_to_texel(v - 0.5 / height as f32, height);
            let (z0, fz) = normalized_to_texel(w - 0.5 / depth as f32, depth);
            let x1 = Ord::min(x0 + 1, width - 1);
            let y1 = Ord::min(y0 + 1, height - 1);
            let z1 = Ord::min(z0 + 1, depth - 1);

            let default_pixel = || std::array::from_fn(|_| T::default());
            let c000 = data
                .get_pixel(x0, y0, z0, level)
                .copied()
                .unwrap_or_else(default_pixel);
            let c100 = data
                .get_pixel(x1, y0, z0, level)
                .copied()
                .unwrap_or_else(default_pixel);
            let c010 = data
                .get_pixel(x0, y1, z0, level)
                .copied()
                .unwrap_or_else(default_pixel);
            let c110 = data
                .get_pixel(x1, y1, z0, level)
                .copied()
                .unwrap_or_else(default_pixel);
            let c001 = data
                .get_pixel(x0, y0, z1, level)
                .copied()
                .unwrap_or_else(default_pixel);
            let c101 = data
                .get_pixel(x1, y0, z1, level)
                .copied()
                .unwrap_or_else(default_pixel);
            let c011 = data
                .get_pixel(x0, y1, z1, level)
                .copied()
                .unwrap_or_else(default_pixel);
            let c111 = data
                .get_pixel(x1, y1, z1, level)
                .copied()
                .unwrap_or_else(default_pixel);

            trilinear_interpolate(c000, c100, c010, c110, c001, c101, c011, c111, fx, fy, fz)
        }
    }
}

/// Selects the cube face and projected `(u, v)` coordinates for a given
/// direction vector, using the standard WebGPU cube-map major-axis
/// selection convention.
///
/// Returns `(face_index, u, v)` where `face_index` is in `0..6` following
/// the WebGPU face order: 0=+X, 1=-X, 2=+Y, 3=-Y, 4=+Z, 5=-Z. The returned
/// `u`, `v` are in `[0, 1]` within the selected face, suitable for passing
/// to [`sample_texture_2d`].
///
/// A zero-length direction is degenerate (GPU behavior is undefined);
/// this function returns face 0 at its center as a deterministic
/// fallback rather than producing NaN from division by zero.
///
/// See <https://www.w3.org/TR/webgpu/#texture-view-format-cube>.
fn select_cube_face(dx: f32, dy: f32, dz: f32) -> (usize, f32, f32) {
    let ax = dx.abs();
    let ay = dy.abs();
    let az = dz.abs();
    let ma = ax.max(ay).max(az);

    // A zero-length direction is degenerate. Return a deterministic
    // fallback to avoid division by zero.
    if ma == 0.0 {
        return (0, 0.5, 0.5);
    }

    // Major-axis selection. For each face the projection follows the
    // standard cube-map convention: the two non-major axes are mapped to
    // face (u, v), with sign flips depending on face orientation so that
    // the texture is oriented correctly when viewed from outside the cube.
    // The major axis is `ma`, so we divide by `2.0 * ma` to map the
    // non-major components into [-0.5, 0.5] before centering at 0.5.
    if ax == ma {
        // X major
        if dx >= 0.0 {
            // +X face: u = -dz, v = -dy
            (0, 0.5 - dz / (2.0 * ma), 0.5 - dy / (2.0 * ma))
        } else {
            // -X face: u = +dz, v = -dy
            (1, 0.5 + dz / (2.0 * ma), 0.5 - dy / (2.0 * ma))
        }
    } else if ay == ma {
        // Y major
        if dy >= 0.0 {
            // +Y face: u = +dx, v = +dz
            (2, 0.5 + dx / (2.0 * ma), 0.5 + dz / (2.0 * ma))
        } else {
            // -Y face: u = +dx, v = -dz
            (3, 0.5 + dx / (2.0 * ma), 0.5 - dz / (2.0 * ma))
        }
    } else {
        // Z major
        if dz >= 0.0 {
            // +Z face: u = +dx, v = -dy
            (4, 0.5 + dx / (2.0 * ma), 0.5 - dy / (2.0 * ma))
        } else {
            // -Z face: u = -dx, v = -dy
            (5, 0.5 - dx / (2.0 * ma), 0.5 - dy / (2.0 * ma))
        }
    }
}

/// Sample a cube texture at the given direction.
///
/// The direction `(dx, dy, dz)` is first mapped to a face via
/// [`select_cube_face`], then the face's 2D texture is sampled using
/// [`sample_texture_2d`]. The W component of the sampler's address modes
/// is not applied (cube textures have no W coordinate).
pub(crate) fn sample_texture_cube<T: Copy + Default + Into<f32> + From<f32>>(
    data: &TextureDataCube<T>,
    sampler_state: &SamplerState,
    dx: f32,
    dy: f32,
    dz: f32,
    level: u32,
) -> [T; 4] {
    let (face, u, v) = select_cube_face(dx, dy, dz);
    sample_texture_2d(&data.faces[face], sampler_state, u, v, level)
}

/// Sample a cube array texture at the given direction and array layer.
///
/// The `array_index` is clamped to `[0, num_layers - 1]` before sampling
/// the selected cube via [`sample_texture_cube`].
pub(crate) fn sample_texture_cube_array<T: Copy + Default + Into<f32> + From<f32>>(
    data: &TextureDataCubeArray<T>,
    sampler_state: &SamplerState,
    dx: f32,
    dy: f32,
    dz: f32,
    array_index: u32,
    level: u32,
) -> [T; 4] {
    let layer = (array_index as usize).min(data.cubes.len().saturating_sub(1));
    data.cubes
        .get(layer)
        .map(|cube| sample_texture_cube(cube, sampler_state, dx, dy, dz, level))
        .unwrap_or_else(|| std::array::from_fn(|_| T::default()))
}

/// Gathers one component from the 4 texels that would be used in bilinear
/// filtering of a 2D texture.
///
/// `u` and `v` are normalized coordinates; the sampler's address modes are
/// applied before texel selection. The returned values follow the WGSL
/// `textureGather` component order: `x` = (u_min, v_max), `y` = (u_max,
/// v_max), `z` = (u_max, v_min), `w` = (u_min, v_min). Per the spec, the
/// gather always reads mip level 0.
pub(crate) fn gather_texture_2d<T: Copy + Default>(
    data: &TextureData2D<T>,
    sampler_state: &SamplerState,
    u: f32,
    v: f32,
    component: u32,
) -> [T; 4] {
    let (w, h) = data.dimensions(0);
    if w == 0 || h == 0 {
        return std::array::from_fn(|_| T::default());
    }
    let u = SamplerState::apply_address_mode(sampler_state.address_mode_u, u);
    let v = SamplerState::apply_address_mode(sampler_state.address_mode_v, v);
    let texel_x = (u * w as f32 - 0.5).floor();
    let texel_y = (v * h as f32 - 0.5).floor();
    let c = component.min(3) as usize;
    let get = |x: f32, y: f32| -> T {
        let xi = (x as i32).clamp(0, w as i32 - 1) as u32;
        let yi = (y as i32).clamp(0, h as i32 - 1) as u32;
        data.get_pixel(xi, yi, 0).map(|p| p[c]).unwrap_or_default()
    };
    // WGSL gather component order:
    // x = (u_min, v_max), y = (u_max, v_max), z = (u_max, v_min), w = (u_min,
    // v_min)
    [
        get(texel_x, texel_y + 1.0),
        get(texel_x + 1.0, texel_y + 1.0),
        get(texel_x + 1.0, texel_y),
        get(texel_x, texel_y),
    ]
}

/// Gathers one component from the 4 texels of the cube face selected by the
/// direction `(dx, dy, dz)`.
///
/// Face selection and `(u, v)` projection follow [`select_cube_face`]; the
/// gather itself is performed on the selected face via [`gather_texture_2d`].
pub(crate) fn gather_texture_cube<T: Copy + Default>(
    data: &TextureDataCube<T>,
    sampler_state: &SamplerState,
    dx: f32,
    dy: f32,
    dz: f32,
    component: u32,
) -> [T; 4] {
    let (face, u, v) = select_cube_face(dx, dy, dz);
    gather_texture_2d(&data.faces[face], sampler_state, u, v, component)
}

/// Gathers one component from the 4 texels of the cube layer selected by
/// `array_index`.
///
/// The `array_index` is clamped to `[0, num_layers - 1]` before gathering
/// from the selected cube via [`gather_texture_cube`].
pub(crate) fn gather_texture_cube_array<T: Copy + Default>(
    data: &TextureDataCubeArray<T>,
    sampler_state: &SamplerState,
    dx: f32,
    dy: f32,
    dz: f32,
    array_index: u32,
    component: u32,
) -> [T; 4] {
    let layer = (array_index as usize).min(data.cubes.len().saturating_sub(1));
    data.cubes
        .get(layer)
        .map(|cube| gather_texture_cube(cube, sampler_state, dx, dy, dz, component))
        .unwrap_or_else(|| std::array::from_fn(|_| T::default()))
}

/// Gathers one component from the 4 texels of the 2D array layer selected by
/// `array_index`.
///
/// The `array_index` is clamped to `[0, num_layers - 1]` before gathering
/// from the selected layer via [`gather_texture_2d`].
pub(crate) fn gather_texture_2d_array<T: Copy + Default>(
    data: &TextureData2DArray<T>,
    sampler_state: &SamplerState,
    u: f32,
    v: f32,
    array_index: u32,
    component: u32,
) -> [T; 4] {
    let layer = (array_index as usize).min(data.layers.len().saturating_sub(1));
    data.layers
        .get(layer)
        .map(|layer_data| gather_texture_2d(layer_data, sampler_state, u, v, component))
        .unwrap_or_else(|| std::array::from_fn(|_| T::default()))
}

/// Gathers the depth values of the 4 texels of the cube face selected by
/// the direction `(dx, dy, dz)`.
///
/// Face selection and `(u, v)` projection follow [`select_cube_face`]; the
/// gather itself is performed on the selected face via
/// [`gather_4_depth_texels`].
pub(crate) fn gather_depth_texture_cube(
    data: &TextureDataDepthCube,
    sampler_state: &SamplerState,
    dx: f32,
    dy: f32,
    dz: f32,
) -> [f32; 4] {
    let (face, u, v) = select_cube_face(dx, dy, dz);
    gather_4_depth_texels(&data.faces[face], sampler_state, u, v)
}

/// Gathers the depth values of the 4 texels of the cube layer selected by
/// `array_index`.
///
/// The `array_index` is clamped to `[0, num_layers - 1]` before gathering
/// from the selected cube via [`gather_depth_texture_cube`].
pub(crate) fn gather_depth_texture_cube_array(
    data: &TextureDataDepthCubeArray,
    sampler_state: &SamplerState,
    dx: f32,
    dy: f32,
    dz: f32,
    array_index: u32,
) -> [f32; 4] {
    let layer = (array_index as usize).min(data.cubes.len().saturating_sub(1));
    data.cubes
        .get(layer)
        .map(|cube| gather_depth_texture_cube(cube, sampler_state, dx, dy, dz))
        .unwrap_or([0.0, 0.0, 0.0, 0.0])
}