three-rs 0.3.0

A port of three.js core and its WebGPURenderer to Rust on wgpu, graded against three.js's own end-to-end pixel comparison.
Documentation
//! Port of `three.js/src/textures/CubeDepthTexture.js` — the six-face depth
//! texture a `PointShadowNode` renders into and then samples with
//! `textureSampleCompare` through a comparison sampler.
//!
//! Like [`DepthTexture`](super::DepthTexture) the handle is an `Rc`: the node
//! graph names the texture while the renderer owns its GPU side, exactly as
//! `light.shadow.map` is shared between the shadow node and the renderer.

use std::cell::RefCell;
use std::rc::Rc;

use super::TextureFilter;
use super::TextureId;

/// The state behind a [`CubeDepthTexture`] handle.
#[derive(Debug)]
pub struct CubeDepthTextureInner {
    /// `shadow.mapSize.width` — a cube face is square.
    pub size: u32,
    /// `depthTexture.minFilter` / `.magFilter`. `PCFShadowMap` with
    /// `textureSampleCompare` available means `LinearFilter`.
    pub mag_filter: TextureFilter,
    /// `depthTexture.minFilter`.
    pub min_filter: TextureFilter,
    /// The GPU texture: a `depth24plus` 2D texture with six array layers,
    /// created by the renderer the first time the shadow is rendered.
    pub(crate) gpu: Option<wgpu::Texture>,
}

/// three.js' `CubeDepthTexture` — the six-face depth texture a point light's
/// shadow renders into.
#[derive(Clone)]
pub struct CubeDepthTexture(Rc<RefCell<CubeDepthTextureInner>>, TextureId);

/// The id is identity, not content: leaving it out keeps the `Debug` of a
/// binding description — what `examples/dump_wgsl.rs` prints beside the WGSL —
/// a function of the texture itself.
impl std::fmt::Debug for CubeDepthTexture {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        f.debug_tuple("CubeDepthTexture").field(&self.0).finish()
    }
}

impl CubeDepthTexture {
    /// `cubeDepthTexture.dispose()` — drops this handle, and nothing more: a texture
    /// handle is an `Rc`, so the renderer frees the GPU side once every handle
    /// is gone, at the top of the next render (`docs/scene-graph.md`,
    /// "Identity and eviction"). Dropping the handle does the same; this
    /// exists so three.js code ports line for line.
    pub fn dispose(self) {}

    /// `new CubeDepthTexture( size )`.
    pub fn new(size: u32) -> Self {
        Self(
            Rc::new(RefCell::new(CubeDepthTextureInner {
                size,
                mag_filter: TextureFilter::Linear,
                min_filter: TextureFilter::Linear,
                gpu: None,
            })),
            TextureId::next(),
        )
    }

    /// `depthTexture.minFilter` / `.magFilter` — `ShadowNode.setupShadow()`
    /// picks `LinearFilter` for `PCFShadowMap` and `NearestFilter` for every
    /// other type.
    pub fn set_filters(&self, min_filter: TextureFilter, mag_filter: TextureFilter) {
        let mut inner = self.0.borrow_mut();
        inner.min_filter = min_filter;
        inner.mag_filter = mag_filter;
    }

    /// `shadow.mapSize.width` — the size of a (square) face.
    pub fn size(&self) -> u32 {
        self.0.borrow().size
    }

    /// `WebGPUTextureUtils.getFormat()` for a `DepthTexture` of
    /// `UnsignedIntType`, which is what the dumped shadow pipeline uses.
    pub(crate) fn gpu_format(&self) -> wgpu::TextureFormat {
        wgpu::TextureFormat::Depth24Plus
    }

    /// `texture.id` — unique per texture, stable for its lifetime.
    pub fn id(&self) -> usize {
        self.1.get()
    }

    /// The handle's liveness, without the handle; see [`TextureOwner`].
    ///
    /// [`TextureOwner`]: super::TextureOwner
    pub(crate) fn owner(&self) -> super::TextureOwner {
        Rc::downgrade(&self.0) as super::TextureOwner
    }

    pub(crate) fn inner(&self) -> &RefCell<CubeDepthTextureInner> {
        &self.0
    }
}