-
-
Notifications
You must be signed in to change notification settings - Fork 3.9k
Clarify Transform
and GlobalTransform
documentation
#9182
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
Clarify Transform
and GlobalTransform
documentation
#9182
Conversation
@@ -5,7 +5,8 @@ use bevy_ecs::{component::Component, reflect::ReflectComponent}; | |||
use bevy_math::{Affine3A, Mat4, Quat, Vec3, Vec3A}; | |||
use bevy_reflect::{std_traits::ReflectDefault, Reflect}; | |||
|
|||
/// Describe the position of an entity relative to the reference frame. | |||
/// Describe the absolute position of an entity in space, |
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.
While we're at it, I don't particularly like the use of "position" here. Unity uses Position, rotation and scale of an object
in their docs. I'm pretty partial to https://en.wikipedia.org/wiki/Pose_(computer_vision), but that might not common enough jargon to use here.
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.
I agree, I've thought about it too, and it's used on the first line of the doc too, actually translation/rotation/scale are never really explained.
But I don't have a good enough replacement except enumerating the three (with translation) which is a bit annoying to put every time.
"positioning" might be a bit better as it implies rotation too (in my mind at least)?
I could use "pose" by defining it at the beginning (which I think I should do anyway)? Also "The term “pose” is largely synonymous with the term “transform”, but a transform may often include scale, whereas pose does not.".
Maybe just use the enumeration at first then just "transform" but it might be confusing?
Edit: I used "transform" here : 9c91876 but I detailed what a transform is. I used "position" to talk about the translation
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.
I added some suggestions for the GlobalTransform
docs.
Some of those suggestions are applicable to bits of text that are repeated in the Transform
docs as well, but I haven't repeated the suggestions there.
I am a bit worried about drift in these docs. I think it's worth discussing whether most of them should be moved to either GlobalTransform
or Transform
so they don't need to be kept in sync.
Side Note: The links to GlobalTransform
in the GlobalTransform
section and Transform
in the Transform
section seem a bit distracting / useless.
I am having a hard time reviewing because the docs are so similar.
@@ -5,34 +5,62 @@ use bevy_ecs::{component::Component, reflect::ReflectComponent}; | |||
use bevy_math::{Affine3A, Mat4, Quat, Vec3, Vec3A}; | |||
use bevy_reflect::{std_traits::ReflectDefault, Reflect}; | |||
|
|||
/// Describe the position of an entity relative to the reference frame. | |||
/// Describe the absolute transform (translation, rotation, scale) of an entity in space, |
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.
/// Describe the absolute transform (translation, rotation, scale) of an entity in space, | |
/// Describes the absolute transform (translation, rotation, scale) of an entity in space, |
/// [`GlobalTransform`] represents: | ||
/// - The position of an entity in space, defined as a `translation` from the origin, | ||
/// [`Vec3::ZERO`]. The unit doesn't have a predefined meaning, but the convention | ||
/// is usually to use `1.0` is equivalent to 1 meter. |
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.
/// is usually to use `1.0` is equivalent to 1 meter. | |
/// is usually to consider `1.0` equivalent to 1 meter. |
This is the language used later in this PR in the Transform
docs and sounds better to me.
/// 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 vertices position attribute |
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.
/// For example if the scale is `1.0` for a `Mesh`, its vertices position attribute | |
/// For example if the scale is `1.0` for a `Mesh`, its vertex position attributes |
/// [`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`]. |
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.
I think it's a bit confusing to say "transform is ... the global transform."
I'd suggest something like
relative to its parent transform or if it doesn't have a parent, the main reference frame
Or some language like "which is equivalent to the global transform if it doesn't have a parent" if you are trying to push that angle.
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.
There's actually a very similar sentence at the top of the Transform
docs that seems a bit better.
/// [`TransformPropagate`]: crate::TransformSystem::TransformPropagate | ||
/// [`PostUpdate`]: bevy_app::PostUpdate | ||
/// [`Parent`]: bevy_hierarchy::Parent | ||
/// [`transform example`]: https://github.com/bevyengine/bevy/blob/latest/examples/transforms/transform.rs |
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.
I'm not sure which link is preferred, but we should be consistent about linking to either the example showcase or the git repository.
/// [`Parent`]: bevy_hierarchy::Parent | ||
/// [`transform example`]: https://github.com/bevyengine/bevy/blob/latest/examples/transforms/transform.rs | ||
/// [`transforms folder`]: https://github.com/bevyengine/bevy/tree/latest/examples/transforms | ||
/// [`parenting example`]: https://bevyengine.org/examples/3d/parenting/ |
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.
This link is broken
@@ -5,36 +5,73 @@ use bevy_reflect::prelude::*; | |||
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. | |||
/// Describe the local transform (translation, rotation, scale) of an entity in space. |
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.
/// Describe the local transform (translation, rotation, scale) of an entity in space. | |
/// Describes the local transform (translation, rotation, scale) of an entity in space. |
Looks like this got lost in limbo. @Selene-Amanita is this still an active PR for you? I can adopt if not. |
@NthTensor I'm not active on Bevy lately, sorry, you can adopt it if you want, no problem! Edit: btw thank you @rparrett for your review, sorry to not have reacted sooner |
@alice-i-cecile adopted at #15358. |
Objective
The doc about
Transform
andGlobalTransform
mention "the reference frame", which can be confusing for two reasons:Transform
is in the reference frame of the parent,Also:
translation
,rotation
andscale
This PR tries to fix that.
Solution
translation
,rotation
andscale