Docs for `transform_point` on `Transform` and `GlobalTransform` contain mistakes
- Dominant language
- Rust
- Stars
- 48.2k
- Forks
- 4.8k
- Avg merge
- 3d 16h
- Merged PRs (30d)
- 171
Description
The docs for `transform_point` on `Transform` and `GlobalTransform` contain mistakes.
The latter has the line:
> This moves `point` into the local space of this [`GlobalTransform`].
https://github.com/bevyengine/bevy/blob/eca7924bb44fdf28664f5ae82dea7ea4e44f08b6/crates/bevy_transform/src/components/global_transform.rs#L188
similarly Transform states that:
> If this [`Transform`] has a parent, this will transform a `point` that is
> relative to the parent's [`Transform`] into one relative to this [`Transform`].
> If this [`Transform`] does not have a parent, this will transform a `point`
> that is in global space into one relative to this [`Transform`].
https://github.com/bevyengine/bevy/blob/eca7924bb44fdf28664f5ae82dea7ea4e44f08b6/crates/bevy_transform/src/components/transform.rs#L383
**All of these statements get the conversion the wrong way round.**
`transform_point` transforms the point FROM the local space of the transform TO the space of the parent/ the reference frame. It is a `localToParent/World` operation.
If you wanted to go from global to local, you need to call
`global_xform.affine().inverse().transform_point(point)`
outside of the scope of a docs issue, but I'd argue that the world to local transform is a common enough scenario that it'd be handy to have it as method directly on `GlobalTransform` and `Transform`, maybe another method for vectors too, eg:
`fn transform_point_to_local()`
`fn transform_vector_to_local()`
You could also extend the name of `transform_point` to further clear up the confusion in the docs (and add a method for vectors too)
`fn transform_point_from_local()`
`fn transform_vector_from_local()`
Contributor guide
Research direction
Read the transform_point documentation in crates/bevy_transform/src/components/transform.rs around line 383 and crates/bevy_transform/src/components/global_transform.rs around line 188. Compare both descriptions with the stated local-to-parent or reference-frame behavior, then update the wording so the documentation consistently describes the actual conversion direction; the docs should no longer reverse local and global spaces.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- rust
- Domain
- documentation
- Issue type
- Documentation
- Difficulty
- 2/5
- Estimated time
- 1-3 hours
- Activity status
- Stale
- Clarity
- Clearly specified
- Newbie friendliness
- 48/100