Skip to main content

three_rs/textures/
cube_depth_texture.rs

1//! Port of `three.js/src/textures/CubeDepthTexture.js` — the six-face depth
2//! texture a `PointShadowNode` renders into and then samples with
3//! `textureSampleCompare` through a comparison sampler.
4//!
5//! Like [`DepthTexture`](super::DepthTexture) the handle is an `Rc`: the node
6//! graph names the texture while the renderer owns its GPU side, exactly as
7//! `light.shadow.map` is shared between the shadow node and the renderer.
8
9use std::cell::RefCell;
10use std::rc::Rc;
11
12use super::TextureFilter;
13use super::TextureId;
14
15/// The state behind a [`CubeDepthTexture`] handle.
16#[derive(Debug)]
17pub struct CubeDepthTextureInner {
18    /// `shadow.mapSize.width` — a cube face is square.
19    pub size: u32,
20    /// `depthTexture.minFilter` / `.magFilter`. `PCFShadowMap` with
21    /// `textureSampleCompare` available means `LinearFilter`.
22    pub mag_filter: TextureFilter,
23    /// `depthTexture.minFilter`.
24    pub min_filter: TextureFilter,
25    /// The GPU texture: a `depth24plus` 2D texture with six array layers,
26    /// created by the renderer the first time the shadow is rendered.
27    pub(crate) gpu: Option<wgpu::Texture>,
28}
29
30/// three.js' `CubeDepthTexture` — the six-face depth texture a point light's
31/// shadow renders into.
32#[derive(Clone)]
33pub struct CubeDepthTexture(Rc<RefCell<CubeDepthTextureInner>>, TextureId);
34
35/// The id is identity, not content: leaving it out keeps the `Debug` of a
36/// binding description — what `examples/dump_wgsl.rs` prints beside the WGSL —
37/// a function of the texture itself.
38impl std::fmt::Debug for CubeDepthTexture {
39    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
40        f.debug_tuple("CubeDepthTexture").field(&self.0).finish()
41    }
42}
43
44impl CubeDepthTexture {
45    /// `cubeDepthTexture.dispose()` — drops this handle, and nothing more: a texture
46    /// handle is an `Rc`, so the renderer frees the GPU side once every handle
47    /// is gone, at the top of the next render (`docs/scene-graph.md`,
48    /// "Identity and eviction"). Dropping the handle does the same; this
49    /// exists so three.js code ports line for line.
50    pub fn dispose(self) {}
51
52    /// `new CubeDepthTexture( size )`.
53    pub fn new(size: u32) -> Self {
54        Self(
55            Rc::new(RefCell::new(CubeDepthTextureInner {
56                size,
57                mag_filter: TextureFilter::Linear,
58                min_filter: TextureFilter::Linear,
59                gpu: None,
60            })),
61            TextureId::next(),
62        )
63    }
64
65    /// `depthTexture.minFilter` / `.magFilter` — `ShadowNode.setupShadow()`
66    /// picks `LinearFilter` for `PCFShadowMap` and `NearestFilter` for every
67    /// other type.
68    pub fn set_filters(&self, min_filter: TextureFilter, mag_filter: TextureFilter) {
69        let mut inner = self.0.borrow_mut();
70        inner.min_filter = min_filter;
71        inner.mag_filter = mag_filter;
72    }
73
74    /// `shadow.mapSize.width` — the size of a (square) face.
75    pub fn size(&self) -> u32 {
76        self.0.borrow().size
77    }
78
79    /// `WebGPUTextureUtils.getFormat()` for a `DepthTexture` of
80    /// `UnsignedIntType`, which is what the dumped shadow pipeline uses.
81    pub(crate) fn gpu_format(&self) -> wgpu::TextureFormat {
82        wgpu::TextureFormat::Depth24Plus
83    }
84
85    /// `texture.id` — unique per texture, stable for its lifetime.
86    pub fn id(&self) -> usize {
87        self.1.get()
88    }
89
90    /// The handle's liveness, without the handle; see [`TextureOwner`].
91    ///
92    /// [`TextureOwner`]: super::TextureOwner
93    pub(crate) fn owner(&self) -> super::TextureOwner {
94        Rc::downgrade(&self.0) as super::TextureOwner
95    }
96
97    pub(crate) fn inner(&self) -> &RefCell<CubeDepthTextureInner> {
98        &self.0
99    }
100}