bevyengine / bevyengine/bevy

Document methods relative to projection

Open
#13,731 2 comments 0 reactions 0 assignees View on GitHub
A-Rendering C-Docs D-Modest
Dominant language
Rust
Stars
48.2k
Forks
4.8k
Avg merge
3d 16h
Merged PRs (30d)
171

Description

Following https://github.com/bevyengine/bevy/issues/8492, a bunch of methods were renamed, it basically erased a lot of references to "projection" and replaced them with "clip". I didn't see this PR until after it happened, but I find the documentation (not the migration guide) surrounding it a bit lacking (not saying it's the fault/responsibility of the PR/its author, some of it was also the case before):

- I'm not sure it's clarified anywhere what is a "clip". I assume it's the space/box where stuff end up after the projection just before being rendered, but having next to no knowledge about rendering but knowledge in mathematics, "projection" is a much more understandable term for me and I don't think I'm the only one, it would be nice to have references to it in the comments of methods with "clip" in their name, like https://github.com/bevyengine/bevy/issues/8492 suggested, and/or have a definition of "clip" somewhere
- None of the methods of the trait `CameraProjection` have comments
- The documentation of the methods of the struct `Frustum` talk about `clip_from_world`. I assume it is referring to the method that comes from `ExtractedView`, but it is not clear (I know rustdoc doesn't help with not being able to reference stuff not from dependencies :( but still it could help to say it comes from ExtractedView and/or explain a bit what that method gives
- `ExtractedView` and `ViewUniform` aren't documented. We don't know where they're from (I assume `ExtractedView` is added as a component to the camera but not from `Camera3dBundle`?) or their purpose. Even if it's an internal thing, a brief description might help, especially since the Frustum's doc references it.
- Other types referenced in this PR are not documented like `MeshTransform`

Even if those things wouldn't matter much for someone that just codes a simple game, it might matter to plugin writers and people who want to understand how the rendering side of Bevy works.

Contributor guide

Open the contributing guide

Research direction

Start by reviewing the documentation changes discussed in issue #8492 and the APIs named here: CameraProjection, Frustum, ExtractedView, ViewUniform, and MeshTransform. Clarify what “clip” means relative to projection, document the CameraProjection methods and referenced types, and explain the purpose or source of the rendering types. Done means plugin authors can understand these APIs from their documentation.

Written by the indexing model from the issue text.

Assessment

Tech stack
rust
Domain
documentation
Issue type
Documentation
Difficulty
4/5
Estimated time
3-5 days
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.