bevyengine / bevyengine/bevy

Document new renderer

Open
#3,999 3 comments 10 reactions 0 assignees View on GitHub
A-Rendering C-Docs
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

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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.