Skip to main content

three_rs/core/
object3d.rs

1//! Port of `three.js/src/core/Object3D.js`. The parent/children tree and the
2//! methods that need it live in [`crate::core::node`]; this file is the object
3//! itself and its transform methods.
4
5use std::cell::Cell;
6use std::rc::Rc;
7
8use crate::core::object_ref::{ObjectRef, WeakObjectRef};
9use crate::core::{Layers, ObjectRenderHook, SceneEventListeners};
10use crate::math::{Euler, Matrix4, Quaternion, Vector3};
11use crate::objects::{InstancedBufferAttribute, Mesh, Payload};
12
13/// three.js' module-level `let _object3DId = 0`.
14fn next_id() -> u32 {
15    thread_local! {
16        static OBJECT3D_ID: Cell<u32> = const { Cell::new(0) };
17    }
18
19    OBJECT3D_ID.with(|id| {
20        let value = id.get();
21        id.set(value + 1);
22        value
23    })
24}
25
26/// three.js' `Object3D`: the transform and the drawable state every scene node
27/// carries. The parent/children tree lives on [`ObjectRef`], the handle that wraps
28/// this in an `Rc<RefCell<..>>` — see `docs/scene-graph.md`.
29///
30/// `Debug` is written out by hand because the render hooks are closures: it
31/// prints whether each is set.
32pub struct Object3D {
33    /// `Object3D.id` — a per-thread counter, three.js' `_object3DId ++`.
34    pub id: u32,
35    /// `Object3D.name`.
36    pub name: String,
37    /// `Object3D.type`. `'Object3D'` unless a subclass overrides it (`Group`
38    /// sets `'Group'`).
39    pub object_type: &'static str,
40    /// `Object3D.parent`, weak: see `docs/scene-graph.md`.
41    pub parent: Option<WeakObjectRef>,
42    /// `Object3D.children`.
43    pub children: Vec<ObjectRef>,
44    /// `Object3D.visible`.
45    pub visible: bool,
46    /// `Object3D.layers` — tested against the camera's in `_projectObject`.
47    pub layers: Layers,
48    /// `Object3D.renderOrder`. On a `Group` it becomes the `groupOrder` of
49    /// everything below it; on a drawable it is the second render-list sort key.
50    pub render_order: f64,
51    /// `Object3D.frustumCulled`.
52    pub frustum_culled: bool,
53    /// `Object3D.matrixAutoUpdate` (`Object3D.DEFAULT_MATRIX_AUTO_UPDATE`).
54    pub matrix_auto_update: bool,
55    /// `Object3D.matrixWorldAutoUpdate` (`DEFAULT_MATRIX_WORLD_AUTO_UPDATE`).
56    pub matrix_world_auto_update: bool,
57    /// `Object3D.matrixWorldNeedsUpdate`.
58    pub matrix_world_needs_update: bool,
59    /// `this.matrix = other.matrixWorld` — `CameraHelper`'s sharing of its
60    /// camera's world matrix *object*. JS aliases the two; the port copies the
61    /// other node's `matrix_world` into `matrix` at the moment
62    /// `updateMatrixWorld()` reads `matrix`, which is when the alias would be
63    /// observed. `None` for everything else, and for a clone (`copy()` copies
64    /// the matrix's values, not the object).
65    pub matrix_alias: Option<crate::core::WeakObjectRef>,
66    /// `Object3D.isCamera` — `lookAt()` points a camera the other way round.
67    pub is_camera: bool,
68    /// `Object3D.isLight` — as `is_camera`.
69    pub is_light: bool,
70    /// `Object3D.castShadow` — whether the shadow pass draws this object.
71    pub cast_shadow: bool,
72    /// `Object3D.receiveShadow` — whether the object's material samples the
73    /// shadow maps, which makes it a different program from the same material
74    /// on a non-receiving object.
75    pub receive_shadow: bool,
76    /// `object.occlusionTest` — not a declared `Object3D` property in three
77    /// but an ad-hoc one the renderer reads (`RenderList.push()`,
78    /// `WebGPUBackend.draw()`): when `true` the object's draws are wrapped in
79    /// an occlusion query, and `renderer.isOccluded( object )` answers from its
80    /// result. Being ad hoc, `Object3D.copy()` does not carry it, so neither
81    /// does [`Clone`].
82    pub occlusion_test: bool,
83    /// `Object3D.isGroup`.
84    pub is_group: bool,
85    /// `Object3D.isScene`.
86    pub is_scene: bool,
87    /// `Object3D.position`.
88    pub position: Vector3,
89    /// Kept in sync with `quaternion` by [`Object3D::set_rotation`], the same way
90    /// three.js' `Euler`/`Quaternion` `onChange` callbacks keep them in sync.
91    pub rotation: Euler,
92    /// `Object3D.quaternion`.
93    pub quaternion: Quaternion,
94    /// `Object3D.scale`.
95    pub scale: Vector3,
96    /// `Object3D.up`.
97    pub up: Vector3,
98    /// `Object3D.matrix`, composed from `position`/`quaternion`/`scale` by
99    /// [`update_matrix`](Self::update_matrix).
100    pub matrix: Matrix4,
101    /// `Object3D.matrixWorld`.
102    pub matrix_world: Matrix4,
103    /// `Object3D.userData` — the application's own data on the object, an
104    /// open JSON object as in three.js. The node system reads it through
105    /// [`user_data`](crate::nodes::tsl::user_data), once per draw, as
106    /// `UserDataNode` does.
107    pub user_data: serde_json::Map<String, serde_json::Value>,
108    /// What three.js would get from subclassing: the `Mesh`/`InstancedMesh`
109    /// state that makes this node drawable. See [`Payload`].
110    pub payload: Payload,
111    /// `object._listeners` — the [`SceneEvent`](crate::core::SceneEvent)
112    /// listeners, added and dispatched through
113    /// [`ObjectRef::add_event_listener`] and its siblings.
114    pub listeners: SceneEventListeners,
115    /// `object.onBeforeRender( renderer, scene, camera, geometry, material,
116    /// group )` — called by the renderer once per draw of this object in a
117    /// scene render, after the scene's matrices are updated and before
118    /// anything of the pass is drawn. `None` is three's empty default. See
119    /// [`ObjectRenderHook`] for the arguments and `docs/api.md` decision 12
120    /// for where the port calls it.
121    pub on_before_render: Option<ObjectRenderHook>,
122    /// `object.onAfterRender( renderer, scene, camera, geometry, material,
123    /// group )` — called once per draw of this object after the scene's pass
124    /// (and its output pass, if any) has been recorded.
125    pub on_after_render: Option<ObjectRenderHook>,
126}
127
128impl std::fmt::Debug for Object3D {
129    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
130        f.debug_struct("Object3D")
131            .field("id", &self.id)
132            .field("name", &self.name)
133            .field("object_type", &self.object_type)
134            .field("parent", &self.parent)
135            .field("children", &self.children)
136            .field("visible", &self.visible)
137            .field("layers", &self.layers)
138            .field("render_order", &self.render_order)
139            .field("frustum_culled", &self.frustum_culled)
140            .field("matrix_auto_update", &self.matrix_auto_update)
141            .field("matrix_world_auto_update", &self.matrix_world_auto_update)
142            .field("matrix_world_needs_update", &self.matrix_world_needs_update)
143            .field("matrix_alias", &self.matrix_alias)
144            .field("is_camera", &self.is_camera)
145            .field("is_light", &self.is_light)
146            .field("cast_shadow", &self.cast_shadow)
147            .field("receive_shadow", &self.receive_shadow)
148            .field("occlusion_test", &self.occlusion_test)
149            .field("is_group", &self.is_group)
150            .field("is_scene", &self.is_scene)
151            .field("position", &self.position)
152            .field("rotation", &self.rotation)
153            .field("quaternion", &self.quaternion)
154            .field("scale", &self.scale)
155            .field("up", &self.up)
156            .field("matrix", &self.matrix)
157            .field("matrix_world", &self.matrix_world)
158            .field("user_data", &self.user_data)
159            .field("payload", &self.payload)
160            .field("listeners", &self.listeners)
161            .field("on_before_render", &self.on_before_render.is_some())
162            .field("on_after_render", &self.on_after_render.is_some())
163            .finish()
164    }
165}
166
167impl Default for Object3D {
168    fn default() -> Self {
169        Self {
170            id: next_id(),
171            name: String::new(),
172            object_type: "Object3D",
173            parent: None,
174            children: Vec::new(),
175            visible: true,
176            layers: Layers::default(),
177            render_order: 0.0,
178            frustum_culled: true,
179            matrix_auto_update: true,
180            matrix_world_auto_update: true,
181            matrix_world_needs_update: false,
182            matrix_alias: None,
183            is_camera: false,
184            is_light: false,
185            cast_shadow: false,
186            receive_shadow: false,
187            occlusion_test: false,
188            is_group: false,
189            is_scene: false,
190            position: Vector3::ZERO,
191            rotation: Euler::default(),
192            quaternion: Quaternion::default(),
193            scale: Vector3::new(1.0, 1.0, 1.0),
194            // `Object3D.DEFAULT_UP`
195            up: Vector3::new(0.0, 1.0, 0.0),
196            matrix: Matrix4::identity(),
197            matrix_world: Matrix4::identity(),
198            user_data: serde_json::Map::new(),
199            payload: Payload::None,
200            listeners: SceneEventListeners::default(),
201            on_before_render: None,
202            on_after_render: None,
203        }
204    }
205}
206
207/// `Object3D.copy( source, recursive = false )`, minus the tree: a clone gets a
208/// fresh `id` and no parent or children, because a `Clone` that shared the
209/// `Rc`s would give two objects the same child list. Nor does it get the
210/// listeners or the render hooks: `copy()` does not copy `_listeners`, and a
211/// boxed closure cannot be cloned.
212impl Clone for Object3D {
213    fn clone(&self) -> Self {
214        Self {
215            id: next_id(),
216            name: self.name.clone(),
217            object_type: self.object_type,
218            parent: None,
219            children: Vec::new(),
220            visible: self.visible,
221            layers: self.layers,
222            render_order: self.render_order,
223            frustum_culled: self.frustum_culled,
224            matrix_auto_update: self.matrix_auto_update,
225            matrix_world_auto_update: self.matrix_world_auto_update,
226            matrix_world_needs_update: self.matrix_world_needs_update,
227            matrix_alias: None,
228            is_camera: self.is_camera,
229            is_light: self.is_light,
230            cast_shadow: self.cast_shadow,
231            receive_shadow: self.receive_shadow,
232            occlusion_test: false,
233            is_group: self.is_group,
234            is_scene: self.is_scene,
235            position: self.position,
236            rotation: self.rotation,
237            quaternion: self.quaternion,
238            scale: self.scale,
239            up: self.up,
240            matrix: self.matrix,
241            matrix_world: self.matrix_world,
242            // `JSON.parse( JSON.stringify( source.userData ) )`: a deep copy.
243            user_data: self.user_data.clone(),
244            payload: self.payload.clone(),
245            listeners: SceneEventListeners::default(),
246            on_before_render: None,
247            on_after_render: None,
248        }
249    }
250}
251
252impl Object3D {
253    /// A fresh `Object3D` as a scene-graph [`ObjectRef`].
254    pub fn new_node() -> ObjectRef {
255        ObjectRef::new(Self::default())
256    }
257
258    /// This object, moved into a scene-graph [`ObjectRef`].
259    pub fn into_node(self) -> ObjectRef {
260        ObjectRef::new(self)
261    }
262
263    /// `object.onBeforeRender = function ( renderer, scene, camera, geometry,
264    /// material, group ) { ... }` — sets
265    /// [`on_before_render`](Self::on_before_render). Assigning the field
266    /// works too; this spares spelling out the closure's argument types.
267    pub fn set_on_before_render(
268        &mut self,
269        hook: impl FnMut(
270                &ObjectRef,
271                &crate::renderer::Renderer,
272                &crate::objects::Scene,
273                &dyn crate::cameras::RenderCamera,
274                Option<&crate::core::Group>,
275            ) + 'static,
276    ) {
277        self.on_before_render = Some(Box::new(hook));
278    }
279
280    /// `object.onAfterRender = function ( ... ) { ... }` — sets
281    /// [`on_after_render`](Self::on_after_render), as
282    /// [`set_on_before_render`](Self::set_on_before_render) does.
283    pub fn set_on_after_render(
284        &mut self,
285        hook: impl FnMut(
286                &ObjectRef,
287                &crate::renderer::Renderer,
288                &crate::objects::Scene,
289                &dyn crate::cameras::RenderCamera,
290                Option<&crate::core::Group>,
291            ) + 'static,
292    ) {
293        self.on_after_render = Some(Box::new(hook));
294    }
295
296    /// `object.isMesh` — see [`Payload::is_mesh`].
297    pub fn is_mesh(&self) -> bool {
298        self.payload.is_mesh()
299    }
300
301    /// `object.isSkinnedMesh`.
302    pub fn is_skinned_mesh(&self) -> bool {
303        self.payload.is_skinned_mesh()
304    }
305
306    /// The `SkinnedMesh` this object is, if it is one.
307    pub fn skinned_mesh(&self) -> Option<&crate::objects::SkinnedMesh> {
308        self.payload.skinned_mesh()
309    }
310
311    /// `object.isSkinnedMesh`'s `SkinnedMesh` state, mutably.
312    pub fn skinned_mesh_mut(&mut self) -> Option<&mut crate::objects::SkinnedMesh> {
313        self.payload.skinned_mesh_mut()
314    }
315
316    /// `object.isInstancedMesh`.
317    pub fn is_instanced_mesh(&self) -> bool {
318        self.payload.is_instanced_mesh()
319    }
320
321    /// `object.isLine` — see [`Payload::is_line`].
322    pub fn is_line(&self) -> bool {
323        self.payload.is_line()
324    }
325
326    /// `object.isPoints` — see [`Payload::is_points`].
327    pub fn is_points(&self) -> bool {
328        self.payload.is_points()
329    }
330
331    /// `object.isLineSegments`.
332    pub fn is_line_segments(&self) -> bool {
333        self.payload.is_line_segments()
334    }
335
336    /// `Line.geometry` / `Line.material` when this node is a line.
337    pub fn line(&self) -> Option<&crate::objects::Line> {
338        self.payload.line()
339    }
340
341    /// `Line.geometry` / `Line.material`, mutably, when this node is a line.
342    pub fn line_mut(&mut self) -> Option<&mut crate::objects::Line> {
343        self.payload.line_mut()
344    }
345
346    /// `object.geometry` for a mesh or a line.
347    pub fn geometry(&self) -> Option<&Rc<crate::core::BufferGeometry>> {
348        self.payload.geometry()
349    }
350
351    /// `object.material` for a mesh or a line.
352    pub fn material(&self) -> Option<&crate::materials::MeshBasicNodeMaterial> {
353        self.payload.material()
354    }
355
356    /// `Mesh.geometry` / `Mesh.material` when this node is a mesh.
357    pub fn mesh(&self) -> Option<&Mesh> {
358        self.payload.mesh()
359    }
360
361    /// `Mesh.geometry` / `Mesh.material`, mutably, when this node is a mesh.
362    pub fn mesh_mut(&mut self) -> Option<&mut Mesh> {
363        self.payload.mesh_mut()
364    }
365
366    /// The light state when `is_light` is true — `Light.color`,
367    /// `Light.intensity`, `PointLight.distance`, `PointLight.decay`.
368    pub fn light(&self) -> Option<&crate::lights::LightObject> {
369        self.payload.light()
370    }
371
372    /// The light state, mutably; see [`light`](Self::light).
373    pub fn light_mut(&mut self) -> Option<&mut crate::lights::LightObject> {
374        self.payload.light_mut()
375    }
376
377    /// `InstancedMesh.count`, else 1.
378    pub(crate) fn instance_count(&self) -> u32 {
379        self.payload.count()
380    }
381
382    /// `InstancedMesh.instanceMatrix`.
383    pub fn instance_matrix(&self) -> Option<&InstancedBufferAttribute> {
384        self.payload.instance_matrix()
385    }
386
387    /// `InstancedMesh.instanceColor`, `None` until `setColorAt()` is called.
388    pub fn instance_color(&self) -> Option<&InstancedBufferAttribute> {
389        self.payload.instance_color()
390    }
391
392    /// `InstancedMesh.setMatrixAt( index, matrix )`, reached through the payload.
393    ///
394    /// Panics if this node is not an `InstancedMesh`, the way the JS would throw.
395    pub fn set_matrix_at(&mut self, index: usize, matrix: &Matrix4) {
396        self.payload
397            .instanced_mesh_mut()
398            .expect("three-rs: setMatrixAt on an object that is not an InstancedMesh")
399            .set_matrix_at(index, matrix);
400    }
401
402    /// `InstancedMesh.setColorAt( index, color )`, reached through the payload.
403    ///
404    /// Panics if this node is not an `InstancedMesh`, the way the JS would throw.
405    pub fn set_color_at(&mut self, index: usize, color: &crate::math::Color) {
406        self.payload
407            .instanced_mesh_mut()
408            .expect("three-rs: setColorAt on an object that is not an InstancedMesh")
409            .set_color_at(index, color);
410    }
411
412    /// `object.rotation.set( x, y, z )` — the Euler `onChange` callback then
413    /// refreshes the quaternion, which is what `updateMatrix()` composes from.
414    pub fn set_rotation(&mut self, x: f64, y: f64, z: f64) {
415        self.rotation.set(x, y, z);
416        self.quaternion.set_from_euler(&self.rotation);
417    }
418
419    /// three.js' `Quaternion.onChange` callback: keeps `rotation` in step with
420    /// `quaternion` (`rotation.setFromQuaternion( quaternion, rotation.order,
421    /// false )`). Every method below that writes the quaternion calls this, the
422    /// way three.js' property setters do.
423    pub(crate) fn sync_rotation_from_quaternion(&mut self) {
424        let (q, order) = (self.quaternion, self.rotation.order);
425        self.rotation.set_from_quaternion(&q, order);
426    }
427
428    /// `Object3D.applyMatrix4()`.
429    pub fn apply_matrix4(&mut self, m: &Matrix4) {
430        if self.matrix_auto_update {
431            self.update_matrix();
432        }
433
434        self.matrix.premultiply(m);
435
436        let matrix = self.matrix;
437        let (mut position, mut quaternion, mut scale) =
438            (self.position, self.quaternion, self.scale);
439        matrix.decompose(&mut position, &mut quaternion, &mut scale);
440        self.position = position;
441        self.quaternion = quaternion;
442        self.scale = scale;
443
444        self.sync_rotation_from_quaternion();
445    }
446
447    /// `Object3D.applyQuaternion()`.
448    pub fn apply_quaternion(&mut self, q: &Quaternion) {
449        self.quaternion.premultiply(q);
450        self.sync_rotation_from_quaternion();
451    }
452
453    /// `Object3D.setRotationFromAxisAngle()`.
454    pub fn set_rotation_from_axis_angle(&mut self, axis: &Vector3, angle: f64) {
455        // assumes axis is normalized
456        self.quaternion.set_from_axis_angle(axis, angle);
457        self.sync_rotation_from_quaternion();
458    }
459
460    /// `Object3D.setRotationFromEuler()`.
461    pub fn set_rotation_from_euler(&mut self, euler: &Euler) {
462        self.quaternion.set_from_euler(euler);
463        self.sync_rotation_from_quaternion();
464    }
465
466    /// `Object3D.setRotationFromMatrix()` — the upper 3x3 of `m` must be a pure
467    /// rotation (unscaled).
468    pub fn set_rotation_from_matrix(&mut self, m: &Matrix4) {
469        self.quaternion.set_from_rotation_matrix(m);
470        self.sync_rotation_from_quaternion();
471    }
472
473    /// `Object3D.setRotationFromQuaternion()` — `q` is assumed normalized.
474    pub fn set_rotation_from_quaternion(&mut self, q: &Quaternion) {
475        self.quaternion.copy(q);
476        self.sync_rotation_from_quaternion();
477    }
478
479    /// `Object3D.rotateOnAxis()` — rotates about an axis in object space.
480    pub fn rotate_on_axis(&mut self, axis: &Vector3, angle: f64) {
481        let mut q1 = Quaternion::default();
482        q1.set_from_axis_angle(axis, angle);
483
484        self.quaternion.multiply(&q1);
485        self.sync_rotation_from_quaternion();
486    }
487
488    /// `Object3D.rotateOnWorldAxis()` — rotates about an axis in world space.
489    /// Assumes the object has no rotated parent.
490    pub fn rotate_on_world_axis(&mut self, axis: &Vector3, angle: f64) {
491        let mut q1 = Quaternion::default();
492        q1.set_from_axis_angle(axis, angle);
493
494        self.quaternion.premultiply(&q1);
495        self.sync_rotation_from_quaternion();
496    }
497
498    /// `Object3D.rotateX()`.
499    pub fn rotate_x(&mut self, angle: f64) {
500        self.rotate_on_axis(&Vector3::new(1.0, 0.0, 0.0), angle);
501    }
502
503    /// `Object3D.rotateY()`.
504    pub fn rotate_y(&mut self, angle: f64) {
505        self.rotate_on_axis(&Vector3::new(0.0, 1.0, 0.0), angle);
506    }
507
508    /// `Object3D.rotateZ()`.
509    pub fn rotate_z(&mut self, angle: f64) {
510        self.rotate_on_axis(&Vector3::new(0.0, 0.0, 1.0), angle);
511    }
512
513    /// `Object3D.translateOnAxis()` — translates along an axis in object space.
514    pub fn translate_on_axis(&mut self, axis: &Vector3, distance: f64) {
515        let mut v1 = *axis;
516        v1.apply_quaternion(&self.quaternion);
517        v1.multiply_scalar(distance);
518
519        self.position.add(&v1);
520    }
521
522    /// `Object3D.translateX()`.
523    pub fn translate_x(&mut self, distance: f64) {
524        self.translate_on_axis(&Vector3::new(1.0, 0.0, 0.0), distance);
525    }
526
527    /// `Object3D.translateY()`.
528    pub fn translate_y(&mut self, distance: f64) {
529        self.translate_on_axis(&Vector3::new(0.0, 1.0, 0.0), distance);
530    }
531
532    /// `Object3D.translateZ()`.
533    pub fn translate_z(&mut self, distance: f64) {
534        self.translate_on_axis(&Vector3::new(0.0, 0.0, 1.0), distance);
535    }
536
537    /// `Object3D.localToWorld()`.
538    pub fn local_to_world(&mut self, vector: &mut Vector3) {
539        self.update_matrix_world(None);
540        vector.apply_matrix4(&self.matrix_world);
541    }
542
543    /// `Object3D.worldToLocal()`.
544    pub fn world_to_local(&mut self, vector: &mut Vector3) {
545        self.update_matrix_world(None);
546
547        let mut inverse = self.matrix_world;
548        inverse.invert();
549        vector.apply_matrix4(&inverse);
550    }
551
552    /// `Object3D.lookAt()` for a plain object: the object's +Z is pointed away
553    /// from `target` (a camera or light points *at* it instead — see
554    /// `PerspectiveCamera::look_at`).
555    pub fn look_at(&mut self, target: &Vector3) {
556        self.update_matrix_world(None);
557
558        let mut position = Vector3::ZERO;
559        position.set_from_matrix_position(&self.matrix_world);
560
561        let mut m1 = Matrix4::identity();
562        m1.look_at(target, &position, &self.up);
563
564        self.quaternion.set_from_rotation_matrix(&m1);
565        self.sync_rotation_from_quaternion();
566    }
567
568    /// `Object3D.getWorldPosition()`.
569    pub fn get_world_position(&mut self) -> Vector3 {
570        self.update_matrix_world(None);
571
572        let mut target = Vector3::ZERO;
573        target.set_from_matrix_position(&self.matrix_world);
574        target
575    }
576
577    /// `Object3D.getWorldQuaternion()`.
578    pub fn get_world_quaternion(&mut self) -> Quaternion {
579        self.update_matrix_world(None);
580
581        let mut position = Vector3::ZERO;
582        let mut target = Quaternion::default();
583        let mut scale = Vector3::ZERO;
584        self.matrix_world
585            .decompose(&mut position, &mut target, &mut scale);
586        target
587    }
588
589    /// `Object3D.getWorldScale()`.
590    pub fn get_world_scale(&mut self) -> Vector3 {
591        self.update_matrix_world(None);
592
593        let mut position = Vector3::ZERO;
594        let mut quaternion = Quaternion::default();
595        let mut target = Vector3::ZERO;
596        self.matrix_world
597            .decompose(&mut position, &mut quaternion, &mut target);
598        target
599    }
600
601    /// `Object3D.getWorldDirection()` — the object's +Z axis in world space.
602    pub fn get_world_direction(&mut self) -> Vector3 {
603        self.update_matrix_world(None);
604
605        let e = &self.matrix_world.elements;
606        let mut target = Vector3::new(e[8], e[9], e[10]);
607        target.normalize();
608        target
609    }
610
611    /// `Object3D.updateMatrix()`.
612    pub fn update_matrix(&mut self) {
613        let (position, quaternion, scale) = (self.position, self.quaternion, self.scale);
614        self.matrix.compose(&position, &quaternion, &scale);
615
616        self.matrix_world_needs_update = true;
617    }
618
619    /// `Object3D.updateMatrixWorld()` for an object whose parent's world matrix
620    /// is `parent_matrix_world` (`None` for a root).
621    pub fn update_matrix_world(&mut self, parent_matrix_world: Option<&Matrix4>) {
622        self.update_matrix_world_forced(parent_matrix_world, false);
623    }
624
625    /// `Object3D.updateMatrixWorld( force )` for one object, returning the
626    /// `force` its children should be updated with (three.js recurses here; an
627    /// `Object3D` held by value has no children to recurse into, so the caller
628    /// — `Scene::update_matrix_world`, or `ObjectRef`'s tree methods — does
629    /// that part).
630    pub(crate) fn update_matrix_world_forced(
631        &mut self,
632        parent_matrix_world: Option<&Matrix4>,
633        force: bool,
634    ) -> bool {
635        if self.matrix_auto_update {
636            self.update_matrix();
637        }
638
639        if self.matrix_world_needs_update || force {
640            if self.matrix_world_auto_update {
641                match parent_matrix_world {
642                    None => self.matrix_world = self.matrix,
643                    Some(parent) => {
644                        let matrix = self.matrix;
645                        self.matrix_world.multiply_matrices(parent, &matrix);
646                    }
647                }
648            }
649
650            self.matrix_world_needs_update = false;
651
652            return true;
653        }
654
655        force
656    }
657}