bevyengine / bevyengine/bevy

Docs for `transform_point` on `Transform` and `GlobalTransform` contain mistakes

Open
#11,078 4 comments 0 reactions 0 assignees View on GitHub
A-Transform C-Docs D-Trivial
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

Open the contributing 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.