Add user control of UI cameras

Add fields to UiCameraConfig to control the UI camera scale and
position.

Fixes #5242. It is again possible to manipulate the ui camera.

An alternative design was considered, where instead of having a
component that controls all of the UI camera settings, the component
would only hold an Entity referencing another camera.

That design was abandoned in favor of the current one because the
viewport is tightly bound to the "actual" camera the UI camera is
attached to. So it would be awkward to maintain independently two
different cameras.

Author: nicopap

crates/bevy_ui/src/entity.rs

@@ -2,14 +2,14 @@
 
 use crate::{
     widget::{Button, ImageMode},
-    CalculatedSize, FocusPolicy, Interaction, Node, Style, UiColor, UiImage,
+    CalculatedSize, FocusPolicy, Interaction, Node, Style, UiColor, UiImage, UI_CAMERA_FAR,
 };
-use bevy_ecs::{
-    bundle::Bundle,
-    prelude::{Component, With},
-    query::QueryItem,
+use bevy_ecs::{bundle::Bundle, prelude::Component};
+use bevy_math::Vec2;
+use bevy_render::{
+    camera::{DepthCalculation, OrthographicProjection, WindowOrigin},
+    view::Visibility,
 };
-use bevy_render::{camera::Camera, extract_component::ExtractComponent, view::Visibility};
 use bevy_text::Text;
 use bevy_transform::prelude::{GlobalTransform, Transform};
 
@@ -96,7 +96,7 @@ impl Default for TextBundle {
 }
 
 /// A UI node that is a button
-#[derive(Bundle, Clone, Debug)]
+#[derive(Bundle, Clone, Debug, Default)]
 pub struct ButtonBundle {
     /// Describes the size of the node
     pub node: Node,
@@ -120,22 +120,6 @@ pub struct ButtonBundle {
     pub visibility: Visibility,
 }
 
-impl Default for ButtonBundle {
-    fn default() -> Self {
-        ButtonBundle {
-            button: Button,
-            interaction: Default::default(),
-            focus_policy: Default::default(),
-            node: Default::default(),
-            style: Default::default(),
-            color: Default::default(),
-            image: Default::default(),
-            transform: Default::default(),
-            global_transform: Default::default(),
-            visibility: Default::default(),
-        }
-    }
-}
 /// Configuration for cameras related to UI.
 ///
 /// When a [`Camera`] doesn't have the [`UiCameraConfig`] component,
@@ -149,19 +133,41 @@ pub struct UiCameraConfig {
     /// When a `Camera` doesn't have the [`UiCameraConfig`] component,
     /// it will display the UI by default.
     pub show_ui: bool,
+    /// The position of the UI camera in UI space.
+    pub position: Vec2,
+    /// The projection data for the UI camera.
+    ///
+    /// The code relies on this not being set,
+    /// please use [`UiCameraConfig::scale_mut`] and [`UiCameraConfig::projection`]
+    /// instead.
+    /// This is only public so it is possible to use the struct update syntax.
+    #[doc(hidden)]
+    pub projection: OrthographicProjection,
 }
 
-impl Default for UiCameraConfig {
-    fn default() -> Self {
-        Self { show_ui: true }
+impl UiCameraConfig {
+    /// Get mutably the scale of the UI camera, useful for zoom effects.
+    pub fn scale_mut(&mut self) -> &mut f32 {
+        &mut self.projection.scale
     }
-}
 
-impl ExtractComponent for UiCameraConfig {
-    type Query = &'static Self;
-    type Filter = With<Camera>;
+    /// The projection data for the UI camera.
+    pub fn projection(&self) -> &OrthographicProjection {
+        &self.projection
+    }
+}
 
-    fn extract_component(item: QueryItem<Self::Query>) -> Self {
-        item.clone()
+impl Default for UiCameraConfig {
+    fn default() -> Self {
+        Self {
+            show_ui: true,
+            position: Vec2::ZERO,
+            projection: OrthographicProjection {
+                far: UI_CAMERA_FAR,
+                window_origin: WindowOrigin::BottomLeft,
+                depth_calculation: DepthCalculation::ZDifference,
+                ..Default::default()
+            },
+        }
     }
 }

crates/bevy_ui/src/lib.rs

@@ -12,7 +12,6 @@ pub mod entity;
 pub mod update;
 pub mod widget;
 
-use bevy_render::extract_component::ExtractComponentPlugin;
 pub use flex::*;
 pub use focus::*;
 pub use geometry::*;
@@ -33,8 +32,6 @@ use bevy_transform::TransformSystem;
 use bevy_window::ModifiesWindows;
 use update::{ui_z_system, update_clipping_system};
 
-use crate::prelude::UiCameraConfig;
-
 /// The basic plugin for Bevy UI
 #[derive(Default)]
 pub struct UiPlugin;
@@ -50,8 +47,7 @@ pub enum UiSystem {
 
 impl Plugin for UiPlugin {
     fn build(&self, app: &mut App) {
-        app.add_plugin(ExtractComponentPlugin::<UiCameraConfig>::default())
-            .init_resource::<FlexSurface>()
+        app.init_resource::<FlexSurface>()
             .register_type::<AlignContent>()
             .register_type::<AlignItems>()
             .register_type::<AlignSelf>()

crates/bevy_ui/src/render/mod.rs

@@ -12,7 +12,7 @@ use bevy_ecs::prelude::*;
 use bevy_math::{Mat4, Vec2, Vec3, Vec4Swizzles};
 use bevy_reflect::TypeUuid;
 use bevy_render::{
-    camera::{Camera, CameraProjection, DepthCalculation, OrthographicProjection, WindowOrigin},
+    camera::{Camera, CameraProjection},
     color::Color,
     render_asset::RenderAssets,
     render_graph::{RenderGraph, RunGraphOnViewNode, SlotInfo, SlotType},
@@ -215,52 +215,52 @@ pub fn extract_uinodes(
 /// as ui elements are "stacked on top of each other", they are within the camera's view
 /// and have room to grow.
 // TODO: Consider computing this value at runtime based on the maximum z-value.
-const UI_CAMERA_FAR: f32 = 1000.0;
+pub(crate) const UI_CAMERA_FAR: f32 = 1000.0;
 
 // This value is subtracted from the far distance for the camera's z-position to ensure nodes at z == 0.0 are rendered
 // TODO: Evaluate if we still need this.
 const UI_CAMERA_TRANSFORM_OFFSET: f32 = -0.1;
 
-#[derive(Component)]
-pub struct DefaultCameraView(pub Entity);
+#[derive(Component, Debug)]
+pub struct UiCamera {
+    pub entity: Entity,
+}
 
 pub fn extract_default_ui_camera_view<T: Component>(
     mut commands: Commands,
     render_world: Res<RenderWorld>,
-    query: Query<(Entity, &Camera, Option<&UiCameraConfig>), With<T>>,
+    mut query: Query<(Entity, &Camera, Option<&mut UiCameraConfig>), With<T>>,
 ) {
-    for (entity, camera, camera_ui) in query.iter() {
+    for (camera_entity, camera, opt_ui_config) in query.iter_mut() {
+        let ui_config = opt_ui_config.as_deref().cloned().unwrap_or_default();
         // ignore cameras with disabled ui
-        if matches!(camera_ui, Some(&UiCameraConfig { show_ui: false, .. })) {
+        if !ui_config.show_ui {
             continue;
         }
         if let (Some(logical_size), Some(physical_size)) = (
             camera.logical_viewport_size(),
             camera.physical_viewport_size(),
         ) {
-            let mut projection = OrthographicProjection {
-                far: UI_CAMERA_FAR,
-                window_origin: WindowOrigin::BottomLeft,
-                depth_calculation: DepthCalculation::ZDifference,
-                ..Default::default()
-            };
+            let mut projection = ui_config.projection.clone();
             projection.update(logical_size.x, logical_size.y);
+            let projection_matrix = projection.get_projection_matrix();
+            if let Some(mut config_to_update) = opt_ui_config {
+                config_to_update.projection = projection;
+            }
             // This roundabout approach is required because spawn().id() won't work in this context
-            let default_camera_view = render_world.entities().reserve_entity();
-            commands
-                .get_or_spawn(default_camera_view)
-                .insert(ExtractedView {
-                    projection: projection.get_projection_matrix(),
-                    transform: GlobalTransform::from_xyz(
-                        0.0,
-                        0.0,
-                        UI_CAMERA_FAR + UI_CAMERA_TRANSFORM_OFFSET,
-                    ),
-                    width: physical_size.x,
-                    height: physical_size.y,
-                });
-            commands.get_or_spawn(entity).insert_bundle((
-                DefaultCameraView(default_camera_view),
+            let ui_camera = render_world.entities().reserve_entity();
+            commands.get_or_spawn(ui_camera).insert(ExtractedView {
+                projection: projection_matrix,
+                transform: GlobalTransform::from_xyz(
+                    ui_config.position.x,
+                    ui_config.position.y,
+                    UI_CAMERA_FAR + UI_CAMERA_TRANSFORM_OFFSET,
+                ),
+                width: physical_size.x,
+                height: physical_size.y,
+            });
+            commands.get_or_spawn(camera_entity).insert_bundle((
+                UiCamera { entity: ui_camera },
                 RenderPhase::<TransparentUi>::default(),
             ));
         }

crates/bevy_ui/src/render/render_pass.rs

@@ -1,5 +1,6 @@
+use crate::UiCamera;
+
 use super::{UiBatch, UiImageBindGroups, UiMeta};
-use crate::{prelude::UiCameraConfig, DefaultCameraView};
 use bevy_ecs::{
     prelude::*,
     system::{lifetimeless::*, SystemParamItem},
@@ -16,15 +17,9 @@ use bevy_render::{
 use bevy_utils::FloatOrd;
 
 pub struct UiPassNode {
-    ui_view_query: QueryState<
-        (
-            &'static RenderPhase<TransparentUi>,
-            &'static ViewTarget,
-            Option<&'static UiCameraConfig>,
-        ),
-        With<ExtractedView>,
-    >,
-    default_camera_view_query: QueryState<&'static DefaultCameraView>,
+    ui_view_query:
+        QueryState<(&'static RenderPhase<TransparentUi>, &'static ViewTarget), With<ExtractedView>>,
+    default_camera_view_query: QueryState<&'static UiCamera>,
 }
 
 impl UiPassNode {
@@ -56,29 +51,25 @@ impl Node for UiPassNode {
     ) -> Result<(), NodeRunError> {
         let input_view_entity = graph.get_input_entity(Self::IN_VIEW)?;
 
-        let (transparent_phase, target, camera_ui) =
+        let (transparent_phase, target) =
             if let Ok(result) = self.ui_view_query.get_manual(world, input_view_entity) {
                 result
             } else {
                 return Ok(());
             };
+
         if transparent_phase.items.is_empty() {
             return Ok(());
         }
-        // Don't render UI for cameras where it is explicitly disabled
-        if matches!(camera_ui, Some(&UiCameraConfig { show_ui: false })) {
-            return Ok(());
-        }
-
-        // use the "default" view entity if it is defined
         let view_entity = if let Ok(default_view) = self
             .default_camera_view_query
             .get_manual(world, input_view_entity)
         {
-            default_view.0
+            default_view.entity
         } else {
             input_view_entity
         };
+
         let pass_descriptor = RenderPassDescriptor {
             label: Some("ui_pass"),
             color_attachments: &[RenderPassColorAttachment {

examples/ui/ui.rs

@@ -13,12 +13,19 @@ fn main() {
         .insert_resource(WinitSettings::desktop_app())
         .add_startup_system(setup)
         .add_system(mouse_scroll)
+        .add_system(change_ui_camera)
         .run();
 }
 
 fn setup(mut commands: Commands, asset_server: Res<AssetServer>) {
     // Camera
-    commands.spawn_bundle(Camera2dBundle::default());
+    commands
+        .spawn_bundle(Camera2dBundle::default())
+        // By default, the UI is already displayed, but here we want to be able to toggle it later
+        .insert(UiCameraConfig {
+            show_ui: true,
+            ..default()
+        });
 
     // root node
     commands
@@ -309,6 +316,31 @@ struct ScrollingList {
     position: f32,
 }
 
+fn change_ui_camera(
+    mouse: Res<Input<MouseButton>>,
+    keyboard: Res<Input<KeyCode>>,
+    mut ui_config: Query<&mut UiCameraConfig>,
+) {
+    for mut config in ui_config.iter_mut() {
+        if mouse.just_pressed(MouseButton::Left) {
+            config.show_ui = !config.show_ui;
+        }
+        if keyboard.pressed(KeyCode::Left) {
+            config.position.x -= 1.0;
+        }
+        if keyboard.pressed(KeyCode::Right) {
+            config.position.x += 1.0;
+        }
+        if keyboard.pressed(KeyCode::Up) {
+            let scale = config.scale_mut();
+            *scale *= 0.99;
+        }
+        if keyboard.pressed(KeyCode::Down) {
+            let scale = config.scale_mut();
+            *scale *= 1.01;
+        }
+    }
+}
 fn mouse_scroll(
     mut mouse_wheel_events: EventReader<MouseWheel>,
     mut query_list: Query<(&mut ScrollingList, &mut Style, &Children, &Node)>,