three_rs/textures/data_array_texture.rs
1//! Port of `three.js/src/textures/DataArrayTexture.js` — the morph-target data
2//! texture (`Morph.js`' `getEntry()`), the one 2-D-array texture on the ladder.
3
4use super::TextureId;
5use std::cell::{Ref, RefCell};
6use std::rc::Rc;
7
8/// The state behind a [`DataArrayTexture`] handle.
9pub struct DataArrayTextureInner {
10 /// `new Float32Array( width * height * 4 * depth )` — one RGBA texel per
11 /// vertex datum, layer-major.
12 pub data: Vec<f32>,
13 /// `image.width`.
14 pub width: u32,
15 /// `image.height`.
16 pub height: u32,
17 /// `image.depth` — the array layer count, i.e. the morph-target count.
18 pub depth: u32,
19 pub(crate) gpu: Option<wgpu::Texture>,
20}
21
22/// Cloning is a handle copy, as in JS.
23#[derive(Clone)]
24pub struct DataArrayTexture(Rc<RefCell<DataArrayTextureInner>>, TextureId);
25
26/// The id is identity, not content: leaving it out keeps the `Debug` of a
27/// binding description — what `examples/dump_wgsl.rs` prints beside the WGSL —
28/// a function of the texture itself.
29impl std::fmt::Debug for DataArrayTexture {
30 fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
31 f.debug_tuple("DataArrayTexture").field(&self.0).finish()
32 }
33}
34
35impl DataArrayTexture {
36 /// `dataArrayTexture.dispose()` — drops this handle, and nothing more: a texture
37 /// handle is an `Rc`, so the renderer frees the GPU side once every handle
38 /// is gone, at the top of the next render (`docs/scene-graph.md`,
39 /// "Identity and eviction"). Dropping the handle does the same; this
40 /// exists so three.js code ports line for line.
41 pub fn dispose(self) {}
42
43 /// `new DataArrayTexture( data, width, height, depth )` with
44 /// `texture.type = FloatType` — `rgba32float` on the GPU. `NearestFilter`
45 /// and no mipmaps, and the shader only ever `textureLoad`s it, so there is
46 /// no sampler binding at all.
47 pub fn new(data: Vec<f32>, width: u32, height: u32, depth: u32) -> Self {
48 Self(
49 Rc::new(RefCell::new(DataArrayTextureInner {
50 data,
51 width,
52 height,
53 depth,
54 gpu: None,
55 })),
56 TextureId::next(),
57 )
58 }
59
60 /// `texture.id` — unique per texture, stable for its lifetime.
61 pub fn id(&self) -> usize {
62 self.1.get()
63 }
64
65 /// The handle's liveness, without the handle; see [`TextureOwner`].
66 ///
67 /// [`TextureOwner`]: super::TextureOwner
68 pub(crate) fn owner(&self) -> super::TextureOwner {
69 Rc::downgrade(&self.0) as super::TextureOwner
70 }
71
72 /// Borrows the texture's data, width, height and depth.
73 pub fn borrow(&self) -> Ref<'_, DataArrayTextureInner> {
74 self.0.borrow()
75 }
76
77 /// `( image.width, image.height, image.depth )`.
78 pub fn size(&self) -> (u32, u32, u32) {
79 let inner = self.0.borrow();
80 (inner.width, inner.height, inner.depth)
81 }
82
83 pub(crate) fn set_gpu(&self, gpu: wgpu::Texture) {
84 self.0.borrow_mut().gpu = Some(gpu);
85 }
86
87 pub(crate) fn has_gpu(&self) -> bool {
88 self.0.borrow().gpu.is_some()
89 }
90
91 /// Runs `f` with the uploaded GPU texture. Panics if the texture has not
92 /// been uploaded yet.
93 pub fn with_gpu<R>(&self, f: impl FnOnce(&wgpu::Texture) -> R) -> R {
94 let inner = self.0.borrow();
95 f(inner
96 .gpu
97 .as_ref()
98 .expect("three-rs: data array texture not uploaded"))
99 }
100}
101
102/// As `TextureInner`: the morph data is one `f32` per vertex datum and has no
103/// place in a debug dump.
104impl std::fmt::Debug for DataArrayTextureInner {
105 fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
106 f.debug_struct("DataArrayTextureInner")
107 .field("data", &super::texture::DataLen(self.data.len()))
108 .field("width", &self.width)
109 .field("height", &self.height)
110 .field("depth", &self.depth)
111 .field("gpu", &self.gpu)
112 .finish()
113 }
114}