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}