Skip to content

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

Open
wants to merge 16 commits into
base: main
Choose a base branch
from
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 4 additions & 2 deletions crates/bevy_transform/src/bundles.rs
Original file line number Diff line number Diff line change
Expand Up @@ -12,8 +12,10 @@ use crate::prelude::{GlobalTransform, Transform};
///
/// ## [`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.
///
/// [`Transform`] is 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.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
/// [`GlobalTransform`], otherwise, it's relative to the main reference frame.
/// [`GlobalTransform`]; otherwise, it's relative to the main reference frame.

///
/// [`GlobalTransform`] is the position of an entity relative to the reference frame.
///
Expand Down
45 changes: 29 additions & 16 deletions crates/bevy_transform/src/components/global_transform.rs
Original file line number Diff line number Diff line change
Expand Up @@ -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
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
/// [`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`].
/// [`Transform`] is the local transform of an entity in space relative to its parent transform;
/// if it doesn't have a [`Parent`], then it is equivalent to the global transform relative to the main reference frame.

Copy link
Contributor Author

Choose a reason for hiding this comment

The 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.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
/// [`GlobalTransform`] is the absolute transform of an entity in space, relative to the main reference frame.
/// [`GlobalTransform`] is the absolute transform of an entity in space relative to the main reference frame.

///
/// 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.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
/// you may notice a 1 frame lag before the [`GlobalTransform`] is updated.
/// you may notice 1 frame of lag before the [`GlobalTransform`] is updated.

///
/// # 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(
Expand Down
73 changes: 56 additions & 17 deletions crates/bevy_transform/src/components/transform.rs
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
/// [`GlobalTransform`], otherwise, it's relative to the main reference frame.
/// [`GlobalTransform`]; otherwise, it's relative to the main reference frame.

Copy link
Contributor Author

Choose a reason for hiding this comment

The 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
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
/// - The `scale` is relative to the parent's [`GlobalTransform`], it is multiplied
/// by it.
/// - The `scale` is relative to the parent's [`GlobalTransform`] (it is multiplied in)

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Hrm, I'm not particularly convinced by either one. Maybe simply,

The scale is multiplied by the parent entity's [GlobalTransform].

?

/// 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
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
/// [`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`].
/// [`Transform`] is the local transform of an entity in space relative to its parent transform;
/// if it doesn't have a [`Parent`], then it is the global transform relative to the main reference frame.

Copy link
Contributor Author

Choose a reason for hiding this comment

The 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.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
/// you may notice a 1 frame lag before the [`GlobalTransform`] is updated.
/// you may notice 1 frame of lag before the [`GlobalTransform`] is updated.

Copy link
Contributor Author

Choose a reason for hiding this comment

The 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(
Expand Down Expand Up @@ -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,
}

Expand Down Expand Up @@ -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;
Expand Down