bevyengine / bevyengine/bevy

Add tests, examples and benchmarks for RenderLayers and TargetCamera rework

Open
#12,588 1 comment 0 reactions 0 assignees View on GitHub
A-Rendering C-Code-Quality C-Examples D-Trivial
Dominant language
Rust
Stars
48.2k
Forks
4.8k
Avg merge
3d 16h
Merged PRs (30d)
171

Description

## What problem does this solve or what need does it fill?

PR #12502 is an important rework of how cameras are matched with entities for rendering. Currently `RenderLayers` are fixed to 32 possible layers, `RenderLayers` don't propagate down hierarchies so you need to manually propagate them (e.g. when spawning scenes), and `TargetCamera` only works for UI entities. It's also confusing to have a split in behavior between normal entities/cameras and UI, and it 'special cases' the codebase.

The PR linked above combines the concepts of `RenderLayers` and `TargetCamera` into a new design that works for all cameras and entities. It introduces `RenderGroups`, `CameraView`, `PropagateRenderGroups`, and `InheritedRenderGroups`.

This design allows a flexible number of `RenderLayers` (up to 1million before it panics), adds the idea of 'camera affiliation' so any entity can be affiliated with a specific camera, and enables `RenderGroups` (which contain a `RenderLayers` and an optional camera affiliation) to propagate down hierarchies in an intuitive manner. UI cameras will automatically propagate themselves down their hierarchies (using a `PropagateRenderGroups` component added to the UI camera bundles), providing a clean transition away from `TargetCamera`.

The PR is functionally complete, but is in need of tests and examples. At this point I have over-committed time to this PR and can't bring it across the finish-line on my own. It would be excellent to see this land in v0.14, so I am looking for people to join me in the credits for this feature :).

P.S. The PR is only **part 1** of a 2-part rework. **Part 2** will remove `TargetCamera` and finish the integration (mostly deleting code and testing that UI still works as expected).

## What solution would you like?

There are a number of tasks that need attention. Changes and additions can be submitted as PRs to [my branch](https://github.com/UkoeHB/bevy/tree/vis_rework) for PR #12502.
- [ ] Tests for `RenderLayers` bit fiddling.
- [ ] Tests for adding/subtracting bits past the max amount that can be stored on the stack (64). This should be an easy one.
- [ ] Tests for `RenderGroups` propagation.
- [ ] Unit tests of basic functionality, to exercise the API.
- [ ] Permutation tests. There are a large number of permutations of test cases in this code. One option would be to write a 'fuzz test' that randomly constructs and mutates hierarchies with randomly changing/adding/removing components. To validate a fuzz state, you traverse the entity hierarchy (e.g. in a system added to `Last`, with a system in `Update` that modifies the fuzz state) to check if `InheritedRenderGroups` values are correct on all entities (basically manually recompute the expected values using the brute-force approach that is too inefficient to actually use in Bevy). If someone does the heavy lifting of writing that framework, I will check it to see if it's missing anything! The framework can be validated by checking if it hits all lines in the propagation algorithm using a code coverage tool.
- [ ] Perf tests. This requires a little research into available perf test options, and may require writing a new benchtest and/or stress test.
- [ ] The system `check_light_mesh_visibility` needs to be perf tested for entities with camera affiliations, since I introduced a hashset lookup for that case.
- [ ] Add example with character-cam that only displays the character.
- [x] Add example demonstrating `RenderGroup` propagation for spawned scenes (completed by @viridia).
- [ ] Add example with minimap. This one can be fairly simple, as it will be expanded to include UI elements in **part 2** of the rework. You just need a second camera with a viewport adjusted to one corner of the screen (also adjust the camera order so it writes on top of the main camera), and some entities to display there and on the main camera.

Contributor guide

Open the contributing guide

Research direction

Start with PR #12502 on the vis_rework branch and inspect the RenderLayers, RenderGroups, InheritedRenderGroups, and PropagateRenderGroups implementation. Prioritize the listed propagation and bit-manipulation tests, then investigate performance coverage for check_light_mesh_visibility and the requested character-camera and minimap examples. Done means the remaining unchecked tests, benchmarks, and examples cover the stated behavior and run successfully.

Written by the indexing model from the issue text.

Assessment

Tech stack
rust
Domain
computer-graphics, game-dev, testing
Issue type
Feature
Difficulty
4/5
Estimated time
3-5 days
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
25/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.