From b31b1eb1f47d396a259d9749abeaa817ebcfdc25 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Fran=C3=A7ois=20Mockers?= Date: Thu, 18 Mar 2021 22:51:24 +0100 Subject: [PATCH 1/4] documentation on Transform and GlobalTransform --- .../src/components/global_transform.rs | 55 +++++++++++++-- .../src/components/transform.rs | 68 +++++++++++++++++-- .../src/transform_propagate_system.rs | 2 + 3 files changed, 111 insertions(+), 14 deletions(-) diff --git a/crates/bevy_transform/src/components/global_transform.rs b/crates/bevy_transform/src/components/global_transform.rs index 8496408c12682..71e8d5bc2d8e8 100644 --- a/crates/bevy_transform/src/components/global_transform.rs +++ b/crates/bevy_transform/src/components/global_transform.rs @@ -4,6 +4,35 @@ use bevy_math::{Mat3, Mat4, Quat, Vec3}; use bevy_reflect::Reflect; use std::ops::Mul; +/// Describe the position of an entity relative to the reference frame. +/// +/// * To place or move an entity, you should set its [`Transform`]. +/// * To be displayed, an entity must have both a [`Transform`] and a [`GlobalTransform`]. +/// * To get the global position of an entity, you should get its [`GlobalTransform`]. +/// +/// ## [`Transform`] and [`GlobalTransform`] +/// +/// [`Transform`] is the position of an entity relative to its parent position, or the reference +/// frame if it doesn't have a [`Parent`](super::Parent). +/// +/// [`GlobalTransform`] is the position of an entity relative to the reference frame. +/// +/// [`GlobalTransform`] is updated from [`Transform`] in the system +/// [`transform_propagate_system`](crate::transform_propagate_system::transform_propagate_system). +/// +/// In pseudo code: +/// ``` +/// for entity in entities_without_parent: +/// set entity.global_transform to entity.transform +/// recursively: +/// set parent to current entity +/// for child in parent.children: +/// set child.global_transform to parent.global_transform * child.transform +/// ``` +/// +/// This system runs in stage [`CoreStage::PostUpdate`](crate::CoreStage::PostUpdate). If you +/// update the[`Transform`] of an entity in this stage or after, you will notice a 1 frame lag +/// before the [`GlobalTransform`] is updated. #[derive(Debug, PartialEq, Clone, Copy, Reflect)] #[reflect(Component, PartialEq)] pub struct GlobalTransform { @@ -13,12 +42,14 @@ pub struct GlobalTransform { } impl GlobalTransform { - /// Create a new [`GlobalTransform`] at the position `(x, y, z)` + #[doc(hidden)] #[inline] pub fn from_xyz(x: f32, y: f32, z: f32) -> Self { Self::from_translation(Vec3::new(x, y, z)) } + /// Crate a new identity [`GlobalTransform`], with no translation, rotation, and a scale of 1 + /// on all axis. #[inline] pub const fn identity() -> Self { GlobalTransform { @@ -28,6 +59,7 @@ impl GlobalTransform { } } + #[doc(hidden)] #[inline] pub fn from_matrix(matrix: Mat4) -> Self { let (scale, rotation, translation) = matrix.to_scale_rotation_translation(); @@ -39,6 +71,7 @@ impl GlobalTransform { } } + #[doc(hidden)] #[inline] pub fn from_translation(translation: Vec3) -> Self { GlobalTransform { @@ -47,6 +80,7 @@ impl GlobalTransform { } } + #[doc(hidden)] #[inline] pub fn from_rotation(rotation: Quat) -> Self { GlobalTransform { @@ -55,6 +89,7 @@ impl GlobalTransform { } } + #[doc(hidden)] #[inline] pub fn from_scale(scale: Vec3) -> Self { GlobalTransform { @@ -63,43 +98,46 @@ impl GlobalTransform { } } - /// Returns transform with the same translation and scale, but rotation so that - /// transform.forward() points at target + #[doc(hidden)] #[inline] pub fn looking_at(mut self, target: Vec3, up: Vec3) -> Self { self.look_at(target, up); self } + /// Returns the 3d affine transformation matrix from this transform translation, + /// rotation and scale. #[inline] pub fn compute_matrix(&self) -> Mat4 { Mat4::from_scale_rotation_translation(self.scale, self.rotation, self.translation) } - #[inline] /// Get the unit vector in the local x direction + #[inline] pub fn local_x(&self) -> Vec3 { self.rotation * Vec3::X } - #[inline] /// Get the unit vector in the local y direction + #[inline] pub fn local_y(&self) -> Vec3 { self.rotation * Vec3::Y } - #[inline] /// Get the unit vector in the local z direction + #[inline] pub fn local_z(&self) -> Vec3 { self.rotation * Vec3::Z } + #[doc(hidden)] #[inline] - /// Rotate the transform by the given rotation pub fn rotate(&mut self, rotation: Quat) { self.rotation *= rotation; } + /// Multiply `self` with `transform` component by component, returning the + /// resulting [`GlobalTransform`] #[inline] pub fn mul_transform(&self, transform: Transform) -> GlobalTransform { let translation = self.mul_vec3(transform.translation); @@ -112,6 +150,7 @@ impl GlobalTransform { } } + /// Returns a [`Vec3`] of this [`Transform`] applied to `value`. #[inline] pub fn mul_vec3(&self, mut value: Vec3) -> Vec3 { value = self.rotation * value; @@ -120,11 +159,13 @@ impl GlobalTransform { value } + #[doc(hidden)] #[inline] pub fn apply_non_uniform_scale(&mut self, scale: Vec3) { self.scale *= scale; } + #[doc(hidden)] #[inline] pub fn look_at(&mut self, target: Vec3, up: Vec3) { let forward = Vec3::normalize(self.translation - target); diff --git a/crates/bevy_transform/src/components/transform.rs b/crates/bevy_transform/src/components/transform.rs index 49b20fe95f148..805a3995b4df9 100644 --- a/crates/bevy_transform/src/components/transform.rs +++ b/crates/bevy_transform/src/components/transform.rs @@ -4,21 +4,58 @@ use bevy_math::{Mat3, Mat4, Quat, Vec3}; use bevy_reflect::Reflect; use std::ops::Mul; +/// Describe the position of an entity. If the entity has a parent, the position is relative +/// to its parent position. +/// +/// * To place or move an entity, you should set its [`Transform`]. +/// * To be displayed, an entity must have both a [`Transform`] and a [`GlobalTransform`]. +/// * To get the global position of an entity, you should get its [`GlobalTransform`]. +/// +/// ## [`Transform`] and [`GlobalTransform`] +/// +/// [`Transform`] is the position of an entity relative to its parent position, or the reference +/// frame if it doesn't have a [`Parent`](super::Parent). +/// +/// [`GlobalTransform`] is the position of an entity relative to the reference frame. +/// +/// [`GlobalTransform`] is updated from [`Transform`] in the system +/// [`transform_propagate_system`](crate::transform_propagate_system::transform_propagate_system). +/// +/// In pseudo code: +/// ``` +/// for entity in entities_without_parent: +/// set entity.global_transform to entity.transform +/// recursively: +/// set parent to current entity +/// for child in parent.children: +/// set child.global_transform to parent.global_transform * child.transform +/// ``` +/// +/// This system runs in stage [`CoreStage::PostUpdate`](crate::CoreStage::PostUpdate). If you +/// update the[`Transform`] of an entity in this stage or after, you will notice a 1 frame lag +/// before the [`GlobalTransform`] is updated. #[derive(Debug, PartialEq, Clone, Copy, Reflect)] #[reflect(Component, PartialEq)] pub struct Transform { + /// Position of the entity. In 2d, the last value of the `Vec3` is used for z-ordering. pub translation: Vec3, + /// Rotation of the entity. pub rotation: Quat, + /// Scale of the entity. pub scale: Vec3, } impl Transform { - /// Create a new [`Transform`] at the position `(x, y, z)` + /// Create a new [`Transform`] at the position `(x, y, z)`. In 2d, the `z` component + /// is used for z-ordering elements: higher `z`-value will be in front of lower + /// `z`-value. #[inline] pub fn from_xyz(x: f32, y: f32, z: f32) -> Self { Self::from_translation(Vec3::new(x, y, z)) } + /// Crate a new identity [`Transform`], with no translation, rotation, and a scale of 1 on + /// all axis. #[inline] pub const fn identity() -> Self { Transform { @@ -28,6 +65,8 @@ impl Transform { } } + /// Extracts the translation, rotation and scale from `matrix`. It must be a 3d affine + /// transformation matrix. #[inline] pub fn from_matrix(matrix: Mat4) -> Self { let (scale, rotation, translation) = matrix.to_scale_rotation_translation(); @@ -39,6 +78,8 @@ impl Transform { } } + /// Create a new [`Transform`], with `translation`. Rotation will be 0 and scale 1 on + /// all axis. #[inline] pub fn from_translation(translation: Vec3) -> Self { Transform { @@ -47,6 +88,8 @@ impl Transform { } } + /// Create a new [`Transform`], with `rotation`. Translation will be 0 and scale 1 on + /// all axis. #[inline] pub fn from_rotation(rotation: Quat) -> Self { Transform { @@ -55,6 +98,8 @@ impl Transform { } } + /// Create a new [`Transform`], with `scale`. Translation will be 0 and rotation 0 on + /// all axis. #[inline] pub fn from_scale(scale: Vec3) -> Self { Transform { @@ -63,43 +108,48 @@ impl Transform { } } - /// Returns transform with the same translation and scale, but rotation so that - /// transform.forward() points at target + /// Update and return this [`Transform`] by rotating it so that its unit vector in the + /// local x direction is toward `target` and its unit vector in the local y direction + /// is toward `up`. #[inline] pub fn looking_at(mut self, target: Vec3, up: Vec3) -> Self { self.look_at(target, up); self } + /// Returns the 3d affine transformation matrix from this transform translation, + /// rotation and scale. #[inline] pub fn compute_matrix(&self) -> Mat4 { Mat4::from_scale_rotation_translation(self.scale, self.rotation, self.translation) } + /// Get the unit vector in the local x direction. #[inline] - /// Get the unit vector in the local x direction pub fn local_x(&self) -> Vec3 { self.rotation * Vec3::X } + /// Get the unit vector in the local y direction. #[inline] - /// Get the unit vector in the local y direction pub fn local_y(&self) -> Vec3 { self.rotation * Vec3::Y } + /// Get the unit vector in the local z direction. #[inline] - /// Get the unit vector in the local z direction pub fn local_z(&self) -> Vec3 { self.rotation * Vec3::Z } + /// Rotate the transform by the given rotation. #[inline] - /// Rotate the transform by the given rotation pub fn rotate(&mut self, rotation: Quat) { self.rotation *= rotation; } + /// Multiply `self` with `transform` component by component, returning the + /// resulting [`Transform`] #[inline] pub fn mul_transform(&self, transform: Transform) -> Self { let translation = self.mul_vec3(transform.translation); @@ -112,6 +162,7 @@ impl Transform { } } + /// Returns a [`Vec3`] of this [`Transform`] applied to `value`. #[inline] pub fn mul_vec3(&self, mut value: Vec3) -> Vec3 { value = self.rotation * value; @@ -120,11 +171,14 @@ impl Transform { value } + /// Change the `scale` of this [`Transform`]. #[inline] pub fn apply_non_uniform_scale(&mut self, scale: Vec3) { self.scale *= scale; } + /// Rotate this [`Transform`] so that its unit vector in the local x direction is toward + /// `target` and its unit vector in the local y direction is toward `up`. #[inline] pub fn look_at(&mut self, target: Vec3, up: Vec3) { let forward = Vec3::normalize(self.translation - target); diff --git a/crates/bevy_transform/src/transform_propagate_system.rs b/crates/bevy_transform/src/transform_propagate_system.rs index a3fbebd27df39..feb59d5012ef8 100644 --- a/crates/bevy_transform/src/transform_propagate_system.rs +++ b/crates/bevy_transform/src/transform_propagate_system.rs @@ -5,6 +5,8 @@ use bevy_ecs::{ system::Query, }; +/// Update [`GlobalTransform`] component of entities based on entity hierarchy and +/// [`Transform`] component. pub fn transform_propagate_system( mut root_query: Query< (Entity, Option<&Children>, &Transform, &mut GlobalTransform), From fff5be80bd63c5853f2eb643592cb1e7b8d8bec1 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Fran=C3=A7ois=20Mockers?= Date: Thu, 18 Mar 2021 23:08:51 +0100 Subject: [PATCH 2/4] do not try to compile pseudo code blocs --- crates/bevy_transform/src/components/global_transform.rs | 2 +- crates/bevy_transform/src/components/transform.rs | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/crates/bevy_transform/src/components/global_transform.rs b/crates/bevy_transform/src/components/global_transform.rs index 71e8d5bc2d8e8..c265450ccfbf4 100644 --- a/crates/bevy_transform/src/components/global_transform.rs +++ b/crates/bevy_transform/src/components/global_transform.rs @@ -21,7 +21,7 @@ use std::ops::Mul; /// [`transform_propagate_system`](crate::transform_propagate_system::transform_propagate_system). /// /// In pseudo code: -/// ``` +/// ```ignore /// for entity in entities_without_parent: /// set entity.global_transform to entity.transform /// recursively: diff --git a/crates/bevy_transform/src/components/transform.rs b/crates/bevy_transform/src/components/transform.rs index 805a3995b4df9..4ee7b91bc0ef7 100644 --- a/crates/bevy_transform/src/components/transform.rs +++ b/crates/bevy_transform/src/components/transform.rs @@ -22,7 +22,7 @@ use std::ops::Mul; /// [`transform_propagate_system`](crate::transform_propagate_system::transform_propagate_system). /// /// In pseudo code: -/// ``` +/// ```ignore /// for entity in entities_without_parent: /// set entity.global_transform to entity.transform /// recursively: From 7688a1cfa84b83dfc179026b117eba0d3e63aabf Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Fran=C3=A7ois=20Mockers?= Date: Fri, 19 Mar 2021 03:28:21 +0100 Subject: [PATCH 3/4] review --- .../src/components/global_transform.rs | 8 +++--- .../src/components/transform.rs | 27 ++++++++++--------- 2 files changed, 18 insertions(+), 17 deletions(-) diff --git a/crates/bevy_transform/src/components/global_transform.rs b/crates/bevy_transform/src/components/global_transform.rs index c265450ccfbf4..e3a353a773f0a 100644 --- a/crates/bevy_transform/src/components/global_transform.rs +++ b/crates/bevy_transform/src/components/global_transform.rs @@ -48,8 +48,8 @@ impl GlobalTransform { Self::from_translation(Vec3::new(x, y, z)) } - /// Crate a new identity [`GlobalTransform`], with no translation, rotation, and a scale of 1 - /// on all axis. + /// Create a new identity [`GlobalTransform`], with no translation, rotation, and a scale of 1 + /// on all axes. #[inline] pub const fn identity() -> Self { GlobalTransform { @@ -105,8 +105,8 @@ impl GlobalTransform { self } - /// Returns the 3d affine transformation matrix from this transform translation, - /// rotation and scale. + /// Returns the 3d affine transformation matrix from this transforms translation, + /// rotation, and scale. #[inline] pub fn compute_matrix(&self) -> Mat4 { Mat4::from_scale_rotation_translation(self.scale, self.rotation, self.translation) diff --git a/crates/bevy_transform/src/components/transform.rs b/crates/bevy_transform/src/components/transform.rs index 4ee7b91bc0ef7..d7a21cd607664 100644 --- a/crates/bevy_transform/src/components/transform.rs +++ b/crates/bevy_transform/src/components/transform.rs @@ -54,8 +54,8 @@ impl Transform { Self::from_translation(Vec3::new(x, y, z)) } - /// Crate a new identity [`Transform`], with no translation, rotation, and a scale of 1 on - /// all axis. + /// Create a new identity [`Transform`], with no translation, rotation, and a scale of 1 on + /// all axes. #[inline] pub const fn identity() -> Self { Transform { @@ -65,7 +65,7 @@ impl Transform { } } - /// Extracts the translation, rotation and scale from `matrix`. It must be a 3d affine + /// Extracts the translation, rotation, and scale from `matrix`. It must be a 3d affine /// transformation matrix. #[inline] pub fn from_matrix(matrix: Mat4) -> Self { @@ -79,7 +79,7 @@ impl Transform { } /// Create a new [`Transform`], with `translation`. Rotation will be 0 and scale 1 on - /// all axis. + /// all axes. #[inline] pub fn from_translation(translation: Vec3) -> Self { Transform { @@ -89,7 +89,7 @@ impl Transform { } /// Create a new [`Transform`], with `rotation`. Translation will be 0 and scale 1 on - /// all axis. + /// all axes. #[inline] pub fn from_rotation(rotation: Quat) -> Self { Transform { @@ -99,7 +99,7 @@ impl Transform { } /// Create a new [`Transform`], with `scale`. Translation will be 0 and rotation 0 on - /// all axis. + /// all axes. #[inline] pub fn from_scale(scale: Vec3) -> Self { Transform { @@ -109,7 +109,7 @@ impl Transform { } /// Update and return this [`Transform`] by rotating it so that its unit vector in the - /// local x direction is toward `target` and its unit vector in the local y direction + /// local z direction is toward `target` and its unit vector in the local y direction /// is toward `up`. #[inline] pub fn looking_at(mut self, target: Vec3, up: Vec3) -> Self { @@ -117,8 +117,8 @@ impl Transform { self } - /// Returns the 3d affine transformation matrix from this transform translation, - /// rotation and scale. + /// Returns the 3d affine transformation matrix from this transforms translation, + /// rotation, and scale. #[inline] pub fn compute_matrix(&self) -> Mat4 { Mat4::from_scale_rotation_translation(self.scale, self.rotation, self.translation) @@ -171,13 +171,14 @@ impl Transform { value } - /// Change the `scale` of this [`Transform`]. + /// Change the `scale` of this [`Transform`], multiplying the current `scale` by + /// `scale_factor`. #[inline] - pub fn apply_non_uniform_scale(&mut self, scale: Vec3) { - self.scale *= scale; + pub fn apply_non_uniform_scale(&mut self, scale_factor: Vec3) { + self.scale *= scale_factor; } - /// Rotate this [`Transform`] so that its unit vector in the local x direction is toward + /// Rotate this [`Transform`] so that its unit vector in the local z direction is toward /// `target` and its unit vector in the local y direction is toward `up`. #[inline] pub fn look_at(&mut self, target: Vec3, up: Vec3) { From 4c781a8e37eb494d366eb0d9bbe9217318e60c93 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Fran=C3=A7ois=20Mockers?= Date: Fri, 19 Mar 2021 04:33:54 +0100 Subject: [PATCH 4/4] still missing some 's' --- .../src/components/global_transform.rs | 4 ++-- .../src/components/transform.rs | 20 +++++++++---------- 2 files changed, 12 insertions(+), 12 deletions(-) diff --git a/crates/bevy_transform/src/components/global_transform.rs b/crates/bevy_transform/src/components/global_transform.rs index e3a353a773f0a..96e050b2afab2 100644 --- a/crates/bevy_transform/src/components/global_transform.rs +++ b/crates/bevy_transform/src/components/global_transform.rs @@ -48,7 +48,7 @@ impl GlobalTransform { Self::from_translation(Vec3::new(x, y, z)) } - /// Create a new identity [`GlobalTransform`], with no translation, rotation, and a scale of 1 + /// Creates a new identity [`GlobalTransform`], with no translation, rotation, and a scale of 1 /// on all axes. #[inline] pub const fn identity() -> Self { @@ -136,7 +136,7 @@ impl GlobalTransform { self.rotation *= rotation; } - /// Multiply `self` with `transform` component by component, returning the + /// Multiplies `self` with `transform` component by component, returning the /// resulting [`GlobalTransform`] #[inline] pub fn mul_transform(&self, transform: Transform) -> GlobalTransform { diff --git a/crates/bevy_transform/src/components/transform.rs b/crates/bevy_transform/src/components/transform.rs index d7a21cd607664..878ef33ca8f30 100644 --- a/crates/bevy_transform/src/components/transform.rs +++ b/crates/bevy_transform/src/components/transform.rs @@ -46,7 +46,7 @@ pub struct Transform { } impl Transform { - /// Create a new [`Transform`] at the position `(x, y, z)`. In 2d, the `z` component + /// Creates a new [`Transform`] at the position `(x, y, z)`. In 2d, the `z` component /// is used for z-ordering elements: higher `z`-value will be in front of lower /// `z`-value. #[inline] @@ -54,7 +54,7 @@ impl Transform { Self::from_translation(Vec3::new(x, y, z)) } - /// Create a new identity [`Transform`], with no translation, rotation, and a scale of 1 on + /// Creates a new identity [`Transform`], with no translation, rotation, and a scale of 1 on /// all axes. #[inline] pub const fn identity() -> Self { @@ -78,7 +78,7 @@ impl Transform { } } - /// Create a new [`Transform`], with `translation`. Rotation will be 0 and scale 1 on + /// Creates a new [`Transform`], with `translation`. Rotation will be 0 and scale 1 on /// all axes. #[inline] pub fn from_translation(translation: Vec3) -> Self { @@ -88,7 +88,7 @@ impl Transform { } } - /// Create a new [`Transform`], with `rotation`. Translation will be 0 and scale 1 on + /// Creates a new [`Transform`], with `rotation`. Translation will be 0 and scale 1 on /// all axes. #[inline] pub fn from_rotation(rotation: Quat) -> Self { @@ -98,7 +98,7 @@ impl Transform { } } - /// Create a new [`Transform`], with `scale`. Translation will be 0 and rotation 0 on + /// Creates a new [`Transform`], with `scale`. Translation will be 0 and rotation 0 on /// all axes. #[inline] pub fn from_scale(scale: Vec3) -> Self { @@ -108,7 +108,7 @@ impl Transform { } } - /// Update and return this [`Transform`] by rotating it so that its unit vector in the + /// Updates and returns this [`Transform`] by rotating it so that its unit vector in the /// local z direction is toward `target` and its unit vector in the local y direction /// is toward `up`. #[inline] @@ -142,13 +142,13 @@ impl Transform { self.rotation * Vec3::Z } - /// Rotate the transform by the given rotation. + /// Rotates the transform by the given rotation. #[inline] pub fn rotate(&mut self, rotation: Quat) { self.rotation *= rotation; } - /// Multiply `self` with `transform` component by component, returning the + /// Multiplies `self` with `transform` component by component, returning the /// resulting [`Transform`] #[inline] pub fn mul_transform(&self, transform: Transform) -> Self { @@ -171,14 +171,14 @@ impl Transform { value } - /// Change the `scale` of this [`Transform`], multiplying the current `scale` by + /// Changes the `scale` of this [`Transform`], multiplying the current `scale` by /// `scale_factor`. #[inline] pub fn apply_non_uniform_scale(&mut self, scale_factor: Vec3) { self.scale *= scale_factor; } - /// Rotate this [`Transform`] so that its unit vector in the local z direction is toward + /// Rotates this [`Transform`] so that its unit vector in the local z direction is toward /// `target` and its unit vector in the local y direction is toward `up`. #[inline] pub fn look_at(&mut self, target: Vec3, up: Vec3) {