Skip to main content

three_rs/objects/
skinned_mesh.rs

1//! Port of `three.js/src/objects/SkinnedMesh.js`.
2
3use std::cell::RefCell;
4use std::rc::Rc;
5
6use crate::core::{BufferGeometry, Object3D, ObjectRef};
7use crate::materials::MeshBasicNodeMaterial;
8use crate::math::{Box3, Matrix4, Sphere, Vector3, Vector4};
9use crate::objects::{Mesh, Payload, Skeleton};
10
11/// `AttachedBindMode` / `DetachedBindMode` from `src/constants.js`.
12#[derive(Clone, Copy, Debug, PartialEq, Eq, Default)]
13pub enum BindMode {
14    /// `'attached'` — the bind matrix inverse tracks `matrixWorld`.
15    #[default]
16    Attached,
17    /// `'detached'` — it tracks `bindMatrix`.
18    Detached,
19}
20
21/// `class SkinnedMesh extends Mesh`.
22///
23/// The `Mesh` half is held rather than inherited, exactly as
24/// [`InstancedMesh`](crate::objects::InstancedMesh) holds it, and the whole
25/// struct is one node's [`Payload`] — so the renderer's tree walk finds a
26/// skinned mesh wherever it hangs, and the bones (which are ordinary nodes in
27/// the same tree) reach it through their shared [`Skeleton`].
28#[derive(Clone)]
29pub struct SkinnedMesh {
30    /// The `Mesh` it extends: `geometry` and `material`.
31    pub mesh: Mesh,
32    /// `SkinnedMesh.skeleton`.
33    pub skeleton: Option<Rc<RefCell<Skeleton>>>,
34    /// `SkinnedMesh.bindMode`.
35    pub bind_mode: BindMode,
36    /// `SkinnedMesh.bindMatrix`.
37    pub bind_matrix: Matrix4,
38    /// `SkinnedMesh.bindMatrixInverse`.
39    ///
40    /// In the default [`BindMode::Attached`] this is `matrixWorld⁻¹`, recomputed
41    /// **every frame** by `Object3D.updateMatrixWorld()` — see
42    /// `SkinnedMesh::update_bind_matrix_inverse`, which the tree walk calls
43    /// for this payload the way three.js' `SkinnedMesh.updateMatrixWorld()`
44    /// override does. A stale or identity value here scales the skin by the
45    /// node's own scale and is silent.
46    pub bind_matrix_inverse: Matrix4,
47    /// `Mesh.boundingBox` (`SkinnedMesh.computeBoundingBox`).
48    pub bounding_box: Option<Box3>,
49    /// `Mesh.boundingSphere` (`SkinnedMesh.computeBoundingSphere`).
50    pub bounding_sphere: Option<Sphere>,
51    /// `Mesh.morphTargetInfluences`, which glTF morph animation writes into.
52    /// Shared, because `SceneResolver` binds a `.morphTargetInfluences` track to
53    /// it while the mesh is owned elsewhere.
54    pub morph_target_influences: Rc<RefCell<Vec<f64>>>,
55    /// `Mesh.morphTargetDictionary`.
56    pub morph_target_dictionary: Vec<(String, usize)>,
57}
58
59impl SkinnedMesh {
60    /// `new SkinnedMesh( geometry, material )`, as a scene-graph [`ObjectRef`].
61    #[allow(clippy::new_ret_no_self)] // `new` mirrors three.js's constructor and returns a scene-graph `ObjectRef`, not `Self`; public API, not changing.
62    pub fn new(
63        geometry: Rc<BufferGeometry>,
64        material: impl Into<Option<MeshBasicNodeMaterial>>,
65    ) -> ObjectRef {
66        let mut object = Object3D {
67            object_type: "SkinnedMesh",
68            ..Default::default()
69        };
70        object.payload = Payload::SkinnedMesh(Box::new(Self::of(geometry, material.into())));
71        object.into_node()
72    }
73
74    /// The payload on its own, for a caller that already has the node —
75    /// `GLTFLoader`, which builds the node from the glTF node definition first.
76    pub fn of(geometry: Rc<BufferGeometry>, material: Option<MeshBasicNodeMaterial>) -> Self {
77        Self {
78            mesh: Mesh {
79                geometry,
80                material,
81                materials: Vec::new(),
82                morph_target_influences: Vec::new(),
83                line_segments: None,
84                count: None,
85            },
86            skeleton: None,
87            bind_mode: BindMode::Attached,
88            bind_matrix: Matrix4::identity(),
89            bind_matrix_inverse: Matrix4::identity(),
90            bounding_box: None,
91            bounding_sphere: None,
92            morph_target_influences: Rc::new(RefCell::new(Vec::new())),
93            morph_target_dictionary: Vec::new(),
94        }
95    }
96
97    /// `SkinnedMesh.geometry`.
98    pub fn geometry(&self) -> &Rc<BufferGeometry> {
99        &self.mesh.geometry
100    }
101
102    /// `SkinnedMesh.bind( skeleton, bindMatrix )` for a mesh that is already a
103    /// node — the node is needed for three.js' `bindMatrix === undefined`
104    /// branch, which updates the world matrix and takes it.
105    pub fn bind(node: &ObjectRef, skeleton: Rc<RefCell<Skeleton>>, bind_matrix: Option<Matrix4>) {
106        let bind_matrix = match bind_matrix {
107            Some(matrix) => matrix,
108            None => {
109                node.update_matrix_world(true);
110                skeleton.borrow_mut().calculate_inverses();
111                node.borrow().matrix_world
112            }
113        };
114
115        let mut object = node.borrow_mut();
116        let skin = object
117            .payload
118            .skinned_mesh_mut()
119            .expect("three-rs: SkinnedMesh::bind needs a SkinnedMesh node");
120        skin.skeleton = Some(skeleton);
121        skin.bind_matrix.copy(&bind_matrix);
122        skin.bind_matrix_inverse.copy(&bind_matrix);
123        skin.bind_matrix_inverse.invert();
124    }
125
126    /// The tail of `SkinnedMesh.updateMatrixWorld( force )`: everything after
127    /// `super.updateMatrixWorld( force )`. The tree walk
128    /// (`Object3D.updateMatrixWorld`) runs it for every `SkinnedMesh` payload it
129    /// passes, which is what keeps `bindMatrixInverse` in step with a moving or
130    /// scaled parent without the caller having to remember.
131    pub(crate) fn update_bind_matrix_inverse(&mut self, matrix_world: &Matrix4) {
132        match self.bind_mode {
133            BindMode::Attached => {
134                self.bind_matrix_inverse.copy(matrix_world);
135                self.bind_matrix_inverse.invert();
136            }
137            BindMode::Detached => {
138                self.bind_matrix_inverse.copy(&self.bind_matrix);
139                self.bind_matrix_inverse.invert();
140            }
141        }
142    }
143
144    /// `SkinnedMesh.pose()`.
145    pub fn pose(&mut self) {
146        if let Some(skeleton) = &self.skeleton {
147            skeleton.borrow_mut().pose();
148        }
149    }
150
151    /// `SkinnedMesh.normalizeSkinWeights()`. Mutates the geometry, so it takes
152    /// the geometry out of the `Rc` (three.js mutates in place; an `Rc` shared
153    /// with the renderer cannot be).
154    pub fn normalize_skin_weights(&mut self) {
155        let mut geometry = (*self.mesh.geometry).clone();
156
157        let Some(skin_weight) = geometry.get_attribute_mut("skinWeight") else {
158            return;
159        };
160
161        let mut vector = Vector4::default();
162
163        for i in 0..skin_weight.count() {
164            vector.set(
165                skin_weight.get_x(i),
166                skin_weight.get_y(i),
167                skin_weight.get_z(i),
168                skin_weight.get_w(i),
169            );
170
171            let scale = 1.0 / vector.manhattan_length();
172
173            if scale.is_finite() {
174                vector.multiply_scalar(scale);
175            } else {
176                // fix gltf files with all zero weights
177                vector.set(1.0, 0.0, 0.0, 0.0);
178            }
179
180            skin_weight.set_x(i, vector.x);
181            skin_weight.set_y(i, vector.y);
182            skin_weight.set_z(i, vector.z);
183            skin_weight.set_w(i, vector.w);
184        }
185
186        self.mesh.geometry = Rc::new(geometry);
187    }
188
189    /// `SkinnedMesh.applyBoneTransform( index, vector )`.
190    pub fn apply_bone_transform(&self, index: usize, vector: &mut Vector3) {
191        let Some(skeleton) = &self.skeleton else {
192            return;
193        };
194        let skeleton = skeleton.borrow();
195
196        let (Some(skin_index), Some(skin_weight)) = (
197            self.mesh.geometry.get_attribute("skinIndex"),
198            self.mesh.geometry.get_attribute("skinWeight"),
199        ) else {
200            return;
201        };
202
203        let mut base_position = *vector;
204        base_position.apply_matrix4(&self.bind_matrix);
205
206        vector.set(0.0, 0.0, 0.0);
207
208        for i in 0..4 {
209            let weight = match i {
210                0 => skin_weight.get_x(index),
211                1 => skin_weight.get_y(index),
212                2 => skin_weight.get_z(index),
213                _ => skin_weight.get_w(index),
214            };
215
216            if weight == 0.0 {
217                continue;
218            }
219
220            let bone_index = match i {
221                0 => skin_index.get_x(index),
222                1 => skin_index.get_y(index),
223                2 => skin_index.get_z(index),
224                _ => skin_index.get_w(index),
225            } as usize;
226
227            let mut offset_matrix = Matrix4::identity();
228            offset_matrix.multiply_matrices(
229                &skeleton.bones[bone_index].borrow().matrix_world,
230                &skeleton.bone_inverses[bone_index],
231            );
232
233            let mut temp = base_position;
234            temp.apply_matrix4(&offset_matrix);
235            vector.add_scaled_vector(&temp, weight);
236        }
237
238        vector.apply_matrix4(&self.bind_matrix_inverse);
239    }
240
241    /// `SkinnedMesh.computeBoundingBox()`.
242    pub fn compute_bounding_box(&mut self) {
243        let Some(position) = self.mesh.geometry.position() else {
244            return;
245        };
246        let count = position.count();
247
248        let mut bounding_box = Box3::default();
249        bounding_box.make_empty();
250
251        for i in 0..count {
252            let mut vertex = Vector3::new(position.get_x(i), position.get_y(i), position.get_z(i));
253            self.apply_bone_transform(i, &mut vertex);
254            bounding_box.expand_by_point(&vertex);
255        }
256
257        self.bounding_box = Some(bounding_box);
258    }
259
260    /// `SkinnedMesh.computeBoundingSphere()`.
261    pub fn compute_bounding_sphere(&mut self) {
262        let Some(position) = self.mesh.geometry.position() else {
263            return;
264        };
265        let count = position.count();
266
267        let mut bounding_sphere = Sphere::default();
268        bounding_sphere.make_empty();
269
270        for i in 0..count {
271            let mut vertex = Vector3::new(position.get_x(i), position.get_y(i), position.get_z(i));
272            self.apply_bone_transform(i, &mut vertex);
273            bounding_sphere.expand_by_point(&vertex);
274        }
275
276        self.bounding_sphere = Some(bounding_sphere);
277    }
278
279    /// `SkinnedMesh.getVertexPosition( index, target )` — `Mesh`'s morphed
280    /// position, then `applyBoneTransform()`.
281    pub fn get_vertex_position(&self, index: usize) -> Vector3 {
282        let mut target = crate::objects::mesh::vertex_position(
283            &self.mesh.geometry,
284            &self.morph_target_influences.borrow(),
285            index,
286        );
287        self.apply_bone_transform(index, &mut target);
288        target
289    }
290
291    /// `SkinnedMesh.raycast( raycaster, intersects )` — `Mesh.raycast()` over
292    /// the skinned mesh's *own* bounds, which follow the bones, with a plain
293    /// `ray.intersectsSphere()` test where `Mesh` checks `near` / `far`.
294    ///
295    /// A missing material is three's default `MeshBasicMaterial`, as for
296    /// [`Mesh::raycast`](crate::objects::Mesh::raycast).
297    pub fn raycast(
298        &mut self,
299        matrix_world: &Matrix4,
300        object: &crate::core::ObjectRef,
301        raycaster: &crate::core::Raycaster,
302        intersects: &mut Vec<crate::core::Intersection>,
303    ) {
304        // Test with the bounding sphere in world space.
305        if self.bounding_sphere.is_none() {
306            self.compute_bounding_sphere();
307        }
308        let Some(mut sphere) = self.bounding_sphere else {
309            return;
310        };
311        sphere.apply_matrix4(matrix_world);
312        if !raycaster.ray.intersects_sphere(&sphere) {
313            return;
314        }
315
316        // Convert the ray to the local space of the skinned mesh.
317        let mut inverse_matrix = *matrix_world;
318        inverse_matrix.invert();
319        let mut ray = raycaster.ray;
320        ray.apply_matrix4(&inverse_matrix);
321
322        // Test with the bounding box in local space.
323        if let Some(bounding_box) = &self.bounding_box {
324            if !ray.intersects_box(bounding_box) {
325                return;
326            }
327        }
328
329        let this = &*self;
330        let target = crate::objects::mesh::MeshRaycast {
331            geometry: &this.mesh.geometry,
332            side: this
333                .mesh
334                .material
335                .as_ref()
336                .map_or(crate::materials::Side::Front, |m| m.side),
337            matrix_world: *matrix_world,
338            draw_start: this.mesh.geometry.draw_range.start,
339            draw_count: this.mesh.geometry.draw_range.count,
340            vertex_position: &|index| this.get_vertex_position(index),
341        };
342        target.compute_intersections(raycaster, &ray, object, intersects);
343    }
344}