Camera-driven UI

[bardt]

Objective

Add support for presenting each UI tree on a specific window and viewport, while making as few breaking changes as possible.

This PR is meant to resolve the following issues at once, since they're all related.

• Fixes Support multiple UI roots #5622
• Fixes Viewport Specific UI #5570
• Fixes Support window independent UI scaling #5621

Adopted #5892 , but started over since the current codebase diverged significantly from the original PR branch. Also, I made a decision to propagate component to children instead of recursively iterating over nodes in search for the root.

Solution

Add a new optional component that can be inserted to UI root nodes and propagate to children to specify which camera it should render onto. This is then used to get the render target and the viewport for that UI tree. Since this component is optional, the default behavior should be to render onto the single camera (if only one exist) and warn of ambiguity if multiple cameras exist. This reduces the complexity for users with just one camera, while giving control in contexts where it matters.

Changelog

• Adds TargetCamera(Entity) component to specify which camera should a node tree be rendered into. If only one camera exists, this component is optional.
• Adds an example of rendering UI to a texture and using it as a material in a 3D world.
• Fixes recalculation of physical viewport size when target scale factor changes. This can happen when the window is moved between displays with different DPI.
• Changes examples to demonstrate assigning UI to different viewports and windows and make interactions in an offset viewport testable.
• Removes UiCameraConfig. UI visibility now can be controlled via combination of explicit TargetCamera and Visibility on the root nodes.

Migration Guide

If the world contains more than one camera, insert TargetCamera(Entity) component to each UI root node, where Entity is the ID of the camera you want this specific UI tree to be rendered to. Test for any required adjustments of UI positioning and scaling.

// before
commands.spawn(Camera3dBundle { ... });
commands.spawn(NodeBundle { ... });

// after
let camera = commands.spawn(Camera3dBundle { ... }).id();
commands.spawn((TargetCamera(camera), NodeBundle { ... }));

Remove UiCameraConfig component from all cameras. If it was used to control UI visibility, insert Visibility component on UI root nodes instead.

[github-actions]

Welcome, new contributor!

Please make sure you've read our contributing guide and we look forward to reviewing your pull request shortly ✨

[IceSentry]

I believe this PR could also close #5476. Since you could now render it to a texture and render that texture to a world space quad

[IceSentry]

CI is failing because you need to run rustfmt

[bardt]

I will clean up the examples and figure out why tests are failing in the upcoming few days.

[bardt]

I've discovered that the tests are failing due to nodes not being added to the UiSurface if there is no camera set (which is the case in most tests). Arguably, camera-driven UI can require a camera to be rendered. But this would make the changes less backward compatible, which I would prefer to avoid. I will look into a better way to default rendering target, which would allow for a camera-less rendering.

[ickshonpe]

I have something I'm working on I need to finish urgently but once that's done (hopefully finished today), I'll do an in-depth review. These are changes I've really wanted for a long time.

[alice-i-cecile]

this is great and seems to work well.

i suspect this pr makes UiCameraConfig pretty much obsolete? the only remaining use is if you want to disable ui on your only camera (which you can always do with Visibility anyway) ... is it worth keeping around just for that?

IMO we remove this in this PR too.

[bardt]

Done removing UiCameraConfig. Added a comment about it to the PR description.

[robtfm]

LGTM. i backported this to bevy 0.12 and have been using it in my work project.

i haven't thoroughly tested the scale factor changes, but the basic functionality works as intended and is super useful.

[github-actions]

It looks like your PR is a breaking change, but you didn't provide a migration guide.

Could you add some context on what users should update when this change get released in a new version of Bevy?
It will be used to help writing the migration guide for the version. Putting it after a ## Migration Guide will help it get automatically picked up by our tooling.