Document new renderer
- Dominant language
- Rust
- Stars
- 48.2k
- Forks
- 4.8k
- Avg merge
- 3d 16h
- Merged PRs (30d)
- 171
Description
I'm opening this issue to collate all the new renderer (from v0.6) questions I have, which I don't think are currently documented.
I started adding a custom render node by copying some code from the sprite renderer, but I've reached a point where that code is too simple and doesn't cover things I want to do. It was also recently [refactored to use render commands](https://github.com/bevyengine/bevy/blob/544b6dfb8662f589658445ac4c9387918e3e6c1a/crates/bevy_sprite/src/render/mod.rs#L564) and is now even more difficult to understand for a novice.
Hopefully someone with more insight can comment on some of those. I'm happy to make PRs if I can get to a point where I understand myself those things. Thanks! 🙏
# Views
Several aspects of the render graph refer to _views_, but this concept is not documented as far as I know.
1. **How are views produced?**
I assume there should be one view per "point of view to render", that is typically one of main camera, additional effect cameras (mirror and water reflection, portal effect, ...), shadow-casting lights, etc. However, now adding a second `PerspectiveCameraBundle` (for example) doesn't do what one would expect because there's a single _active camera_ in an app world and only that one renders, effectively "shadowing" all other ones (see https://github.com/bevyengine/bevy/pull/3528). There's also no way to specify which camera(s) an entity/mesh/... renders to. I believe there should be a single _primary camera_ (the one that eventually blits to the window/screen) but multiple _active_ ones (all the ones actively rendering _something_).
2. **What is the _view entity_ passed to [`Draw::draw()`](https://docs.rs/bevy/latest/bevy/render/render_phase/trait.Draw.html#tymethod.draw)**
Using a single camera I always get entity 0v0 (id:0, gen:0). Adding a second camera I always get 1v0, and never 0v0 anymore.
3. **Is [`RenderStage::Queue`](https://docs.rs/bevy/latest/bevy/render/enum.RenderStage.html) view-dependent? Are previous ones (`Extract` and `Prepare`) view-independent?**
I thought I read something about this but the doc for `RenderStage` doesn't mention it.
4. **How to handle multiple views?**
I believe in the "queue" stage a custom render node should iterate over the `RenderPhase` (for example) to get all views? I know I can get the current camera's parameters [via `ViewUniformOffset` and that _view entity_ mentioned above](https://github.com/bevyengine/bevy/blob/544b6dfb8662f589658445ac4c9387918e3e6c1a/crates/bevy_sprite/src/render/mod.rs#L581), but whatever I do I seem to have only a single view, so I cannot confidently test any view-dependent code.
# Render graph
5. **What is [`Transparent3d::distance`](https://docs.rs/bevy/latest/bevy/core_pipeline/struct.Transparent3d.html#structfield.distance) (and same on others)?**
How can my custom render node provide a relevant value for this? For now I always set it to `distance: 0.0` and everything seems to work fine.
6. **What is [`Transparent3d::entity`](https://docs.rs/bevy/latest/bevy/core_pipeline/struct.Transparent3d.html#structfield.entity)?**
I have no idea what I'm supposed to store there nor why.
7. **What is the `VIEW_ENTITY` input of the 2D/3D graphs?**
The 2D and 3D render graphs [declare a `VIEW_ENTITY` input](https://github.com/bevyengine/bevy/blob/544b6dfb8662f589658445ac4c9387918e3e6c1a/crates/bevy_core_pipeline/src/lib.rs#L152) that doesn't seem to be connected/used anywhere. What's the point? Is that related to the _views_ section above in any way?
# Concepts explanations / tutorials
8. **Explain main app vs. sub-app / render app?**
9. **How to extend the renderer with a new `Node`?**
10. **What's [`Draw`](https://docs.rs/bevy/latest/bevy/render/render_phase/trait.Draw.html) and draw functions? Why should they be used?**
The docs only mention the difference with `RenderCommands`, which makes things even more confusing (what is a render command in the first place? why are there 2 concepts for the same thing?).
Contributor guide
Research direction
Start with the linked renderer code in crates/bevy_sprite/src/render/mod.rs and the VIEW_ENTITY declaration in crates/bevy_core_pipeline/src/lib.rs, then compare the RenderStage and Draw documentation. Organize the answers around views, render phases, render graphs, app/sub-app concepts, Nodes, Draw, and render commands. Done means these renderer questions are explained in accessible documentation or tutorials.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- rust
- Domain
- computer-graphics, documentation
- Issue type
- Documentation
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Stale
- Clarity
- Needs clarification
- Newbie friendliness
- 25/100