-
-
Notifications
You must be signed in to change notification settings - Fork 3.9k
Clarify Transform
and GlobalTransform
documentation (adopted)
#15358
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
base: main
Are you sure you want to change the base?
Changes from all commits
15b6aab
7937244
a3a2c8b
9c91876
1094728
d5159a2
494e9fa
1b7b939
6e08f16
f112da9
a7448b1
6280762
0a3bfb4
bb18c4f
c8d2998
ccf1071
File filter
Filter by extension
Conversations
Jump to
Diff view
Diff view
There are no files selected for viewing
Original file line number | Diff line number | Diff line change | ||||||||
---|---|---|---|---|---|---|---|---|---|---|
|
@@ -9,33 +9,46 @@ use bevy_reflect::{std_traits::ReflectDefault, Reflect}; | |||||||||
#[cfg(all(feature = "bevy-support", feature = "serialize"))] | ||||||||||
use bevy_reflect::{ReflectDeserialize, ReflectSerialize}; | ||||||||||
|
||||||||||
/// [`GlobalTransform`] is an affine transformation from entity-local coordinates to worldspace coordinates. | ||||||||||
/// [`GlobalTransform`] is an affine transformation from entity-local coordinates to worldspace | ||||||||||
/// coordinates. | ||||||||||
/// | ||||||||||
/// You cannot directly mutate [`GlobalTransform`]; instead, you change an entity's transform by manipulating | ||||||||||
/// its [`Transform`], which indirectly causes Bevy to update its [`GlobalTransform`]. | ||||||||||
/// ## Usage | ||||||||||
/// | ||||||||||
/// * To get the global transform of an entity, you should get its [`GlobalTransform`]. | ||||||||||
/// * For transform hierarchies to work correctly, you must have both a [`Transform`] and a [`GlobalTransform`]. | ||||||||||
/// * You may use the [`TransformBundle`](crate::bundles::TransformBundle) to guarantee this. | ||||||||||
/// * To place or move an entity, you should set its [`Transform`]. | ||||||||||
/// * To get the absolute transform of an entity, you should get its [`GlobalTransform`] | ||||||||||
/// after [`TransformPropagate`] or [`PostUpdate`] to avoid being 1 frame out of date. | ||||||||||
/// * You can use [`compute_transform`] to get the global `translation`, `rotation` and `scale`. | ||||||||||
/// * [`GlobalTransform`] is fully managed by bevy and should not be mutated directly. | ||||||||||
/// Instead, use [`Transform`]. Then, the [`GlobalTransform`] will be automatically updated by [`TransformPropagate`]. | ||||||||||
/// * You may use the [`TransformBundle`](crate::bundles::TransformBundle) to guarantee | ||||||||||
/// an entity has both components. | ||||||||||
/// | ||||||||||
/// ## [`Transform`] and [`GlobalTransform`] | ||||||||||
/// | ||||||||||
/// [`Transform`] transforms an entity relative to its parent's reference frame, or relative to world space coordinates, | ||||||||||
/// if it doesn't have a [`Parent`](bevy_hierarchy::Parent). | ||||||||||
/// [`Transform`] is the local transform of an entity in space relative to its parent transform, | ||||||||||
/// or the global transform relative to the main reference frame if it doesn't have a [`Parent`]. | ||||||||||
Comment on lines
+28
to
+29
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more.
Suggested change
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. I think I'd go with a separate sentence here. |
||||||||||
/// | ||||||||||
/// [`GlobalTransform`] is managed by Bevy; it is computed by successively applying the [`Transform`] of each ancestor | ||||||||||
/// entity which has a Transform. This is done automatically by Bevy-internal systems in the system set | ||||||||||
/// [`TransformPropagate`](crate::TransformSystem::TransformPropagate). | ||||||||||
/// [`GlobalTransform`] is the absolute transform of an entity in space, relative to the main reference frame. | ||||||||||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more.
Suggested change
|
||||||||||
/// | ||||||||||
/// This system runs during [`PostUpdate`](bevy_app::PostUpdate). If you | ||||||||||
/// update the [`Transform`] of an entity in this schedule or after, you will notice a 1 frame lag | ||||||||||
/// before the [`GlobalTransform`] is updated. | ||||||||||
/// [`GlobalTransform`] is updated from [`Transform`] by systems in the system set | ||||||||||
/// [`TransformPropagate`]. | ||||||||||
/// Those systems run during [`PostUpdate`]. | ||||||||||
/// If you update the [`Transform`] of an entity in this schedule or after, | ||||||||||
/// you may notice a 1 frame lag before the [`GlobalTransform`] is updated. | ||||||||||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more.
Suggested change
|
||||||||||
/// | ||||||||||
/// # Examples | ||||||||||
/// | ||||||||||
/// - [`transform`][transform_example] | ||||||||||
/// - The [`transform example`], or the other examples in the [`transforms folder`], | ||||||||||
/// to learn how to use the [`Transform`] of an entity. | ||||||||||
/// - The [`parenting example`], to learn how [`Transform`] behaves in a hierarchy. | ||||||||||
/// | ||||||||||
/// [transform_example]: https://github.com/bevyengine/bevy/blob/latest/examples/transforms/transform.rs | ||||||||||
/// [`compute_transform`]: GlobalTransform::compute_transform | ||||||||||
/// [`TransformBundle`]: crate::TransformBundle | ||||||||||
/// [`TransformPropagate`]: crate::TransformSystem::TransformPropagate | ||||||||||
/// [`PostUpdate`]: bevy_app::PostUpdate | ||||||||||
/// [`Parent`]: bevy_hierarchy::Parent | ||||||||||
/// [`transform example`]: https://bevyengine.org/examples/transforms/transform | ||||||||||
/// [`parenting example`]: https://bevyengine.org/examples/3d-rendering/parenting | ||||||||||
#[derive(Debug, PartialEq, Clone, Copy)] | ||||||||||
#[cfg_attr(feature = "serialize", derive(serde::Serialize, serde::Deserialize))] | ||||||||||
#[cfg_attr( | ||||||||||
|
Original file line number | Diff line number | Diff line change | ||||||||
---|---|---|---|---|---|---|---|---|---|---|
|
@@ -6,33 +6,72 @@ use bevy_math::{Affine3A, Dir3, Isometry3d, Mat3, Mat4, Quat, Vec3}; | |||||||||
use bevy_reflect::prelude::*; | ||||||||||
use std::ops::Mul; | ||||||||||
|
||||||||||
/// Describe the position of an entity. If the entity has a parent, the position is relative | ||||||||||
/// to its parent position. | ||||||||||
/// Describes the local transform (translation, rotation, scale) of an entity in space. | ||||||||||
/// If the entity has a parent, the local transform is relative to its parent's | ||||||||||
/// [`GlobalTransform`], otherwise, it's relative to the main reference frame. | ||||||||||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more.
Suggested change
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Separate sentence is better here, I think. |
||||||||||
/// | ||||||||||
/// ## Usage | ||||||||||
/// | ||||||||||
/// * To place or move an entity, you should set its [`Transform`]. | ||||||||||
/// * To get the global transform of an entity, you should get its [`GlobalTransform`]. | ||||||||||
/// * To get the absolute transform of an entity, you should get its [`GlobalTransform`] | ||||||||||
/// after [`TransformPropagate`] or [`PostUpdate`] to avoid being a frame out of date. | ||||||||||
/// * To be displayed, an entity must have both a [`Transform`] and a [`GlobalTransform`]. | ||||||||||
/// * You may use the [`TransformBundle`](crate::bundles::TransformBundle) to guarantee this. | ||||||||||
/// * You may use the [`TransformBundle`] to guarantee this. | ||||||||||
/// | ||||||||||
/// ## `translation`, `rotation` and `scale` | ||||||||||
/// | ||||||||||
/// If the entity has no parent, [`Transform`] is relative to the main reference frame: | ||||||||||
/// - The position of an entity in space, defined as a `translation` from the origin, | ||||||||||
/// [`Vec3::ZERO`]. The length unit doesn't have a predefined meaning, but the convention | ||||||||||
/// is usually to consider `1.0` equivalent to 1 meter. | ||||||||||
/// - The `rotation` of an entity in space, [`Quat::IDENTITY`] representing the rotation | ||||||||||
/// where [`Vec3::Z`] is forward and [`Vec3::Y`] is up. | ||||||||||
/// - The `scale` of an entity, `1.0` representing the "size values" of the entity | ||||||||||
/// matching the main reference frame coordinates. | ||||||||||
/// It can be seen as a ratio of the main reference frame length unit to | ||||||||||
/// the entity's length unit. | ||||||||||
/// For example, if the scale is `1.0` for a `Mesh`, its vertex position attributes | ||||||||||
/// have the same unit than the values used inside `translation`. | ||||||||||
/// | ||||||||||
/// If the entity has a parent: | ||||||||||
/// - The `translation` is relative to the parent's [`GlobalTransform`], it is | ||||||||||
/// added to it. | ||||||||||
/// Another way of seeing it is that the `translation`'s origin is the | ||||||||||
/// parent global position. | ||||||||||
/// - The `rotation` is relative to the parent's [`GlobalTransform`], it is multiplied | ||||||||||
/// by it. | ||||||||||
/// Another way of seeing it is that [`Quat::IDENTITY`] represents the rotation | ||||||||||
/// where the parent's global forward axis is forward and the parent's global up axis is up. | ||||||||||
/// - The `scale` is relative to the parent's [`GlobalTransform`], it is multiplied | ||||||||||
/// by it. | ||||||||||
Comment on lines
+45
to
+46
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more.
Suggested change
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Hrm, I'm not particularly convinced by either one. Maybe simply,
? |
||||||||||
/// Another way of seeing it is to consider the parent has its own length unit | ||||||||||
/// used by the child. | ||||||||||
/// | ||||||||||
/// ## [`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`](bevy_hierarchy::Parent). | ||||||||||
/// [`Transform`] is the local transform of an entity in space relative to its parent transform, | ||||||||||
/// or the global transform relative to the main reference frame if it doesn't have a [`Parent`]. | ||||||||||
Comment on lines
+52
to
+53
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more.
Suggested change
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Think I'll add a sentence here too. |
||||||||||
/// | ||||||||||
/// [`GlobalTransform`] is the position of an entity relative to the reference frame. | ||||||||||
/// [`GlobalTransform`] is the absolute transform of an entity in space relative to the main reference frame. | ||||||||||
/// | ||||||||||
/// [`GlobalTransform`] is updated from [`Transform`] by systems in the system set | ||||||||||
/// [`TransformPropagate`](crate::TransformSystem::TransformPropagate). | ||||||||||
/// | ||||||||||
/// This system runs during [`PostUpdate`](bevy_app::PostUpdate). If you | ||||||||||
/// update the [`Transform`] of an entity during this set or after, you will notice a 1 frame lag | ||||||||||
/// before the [`GlobalTransform`] is updated. | ||||||||||
/// [`TransformPropagate`]. | ||||||||||
/// Those systems run during [`PostUpdate`]. | ||||||||||
/// If you update the [`Transform`] of an entity in this schedule or after, | ||||||||||
/// you may notice a 1 frame lag before the [`GlobalTransform`] is updated. | ||||||||||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more.
Suggested change
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. I should update to use "one" 🤔 |
||||||||||
/// | ||||||||||
/// # Examples | ||||||||||
/// | ||||||||||
/// - [`transform`][transform_example] | ||||||||||
/// - The [`transform example`], or the other examples in the [`transforms folder`], | ||||||||||
/// to learn how to use the [`Transform`] of an entity. | ||||||||||
/// - The [`parenting example`], to learn how [`Transform`] behaves in a hierarchy. | ||||||||||
/// | ||||||||||
/// [transform_example]: https://github.com/bevyengine/bevy/blob/latest/examples/transforms/transform.rs | ||||||||||
/// [`TransformBundle`]: crate::bundles::TransformBundle | ||||||||||
/// [`TransformPropagate`]: crate::TransformSystem::TransformPropagate | ||||||||||
/// [`PostUpdate`]: bevy_app::PostUpdate | ||||||||||
/// [`Parent`]: bevy_hierarchy::Parent | ||||||||||
/// [`transform example`]: https://bevyengine.org/examples/transforms/transform | ||||||||||
/// [`parenting example`]: https://bevyengine.org/examples/3d-rendering/parenting | ||||||||||
#[derive(Debug, PartialEq, Clone, Copy)] | ||||||||||
#[cfg_attr(feature = "serialize", derive(serde::Serialize, serde::Deserialize))] | ||||||||||
#[cfg_attr( | ||||||||||
|
@@ -61,7 +100,7 @@ pub struct Transform { | |||||||||
/// | ||||||||||
/// See the [`scale`] example for usage. | ||||||||||
/// | ||||||||||
/// [`scale`]: https://github.com/bevyengine/bevy/blob/latest/examples/transforms/scale.rs | ||||||||||
/// [`scale`]: https://bevyengine.org/examples/transforms/scale | ||||||||||
pub scale: Vec3, | ||||||||||
} | ||||||||||
|
||||||||||
|
@@ -298,9 +337,9 @@ impl Transform { | |||||||||
/// | ||||||||||
/// # Examples | ||||||||||
/// | ||||||||||
/// - [`3d_rotation`] | ||||||||||
/// - [`3d-rotation`] | ||||||||||
/// | ||||||||||
/// [`3d_rotation`]: https://github.com/bevyengine/bevy/blob/latest/examples/transforms/3d_rotation.rs | ||||||||||
/// [`3d-rotation`]: https://bevyengine.org/examples/transforms/3d-rotation | ||||||||||
#[inline] | ||||||||||
pub fn rotate(&mut self, rotation: Quat) { | ||||||||||
self.rotation = rotation * self.rotation; | ||||||||||
|
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.