Add sub_camera_view, enabling sheared projection (#15537)

# Objective

- This PR fixes #12488

## Solution

- This PR adds a new property to `Camera` that emulates the
functionality of the
[setViewOffset()](https://threejs.org/docs/#api/en/cameras/PerspectiveCamera.setViewOffset)
API in three.js.
- When set, the perspective and orthographic projections will restrict
the visible area of the camera to a part of the view frustum defined by
`offset` and `size`.

## Testing

- In the new `camera_sub_view` example, a fixed, moving and control sub
view is created for both perspective and orthographic projection
- Run the example with `cargo run --example camera_sub_view`
- The code can be tested by adding a `SubCameraView` to a camera

---

## Showcase


![image](https://github.com/user-attachments/assets/75ac45fc-d75d-4664-8ef6-ff7865297c25)

- Left Half: Perspective Projection
- Right Half: Orthographic Projection
- Small boxes in order:
  - Sub view of the left half of the full image
- Sub view moving from the top left to the bottom right of the full
image
  - Sub view of the full image (acting as a control)
- Large box: No sub view

<details>
  <summary>Shortened camera setup of `camera_sub_view` example</summary>

```rust
    // Main perspective Camera
    commands.spawn(Camera3dBundle {
        transform,
        ..default()
    });

    // Perspective camera left half
    commands.spawn(Camera3dBundle {
        camera: Camera {
            sub_camera_view: Some(SubCameraView {
                // Set the sub view camera to the left half of the full image
                full_size: uvec2(500, 500),
                offset: ivec2(0, 0),
                size: uvec2(250, 500),
            }),
            order: 1,
            ..default()
        },
        transform,
        ..default()
    });

    // Perspective camera moving
    commands.spawn((
        Camera3dBundle {
            camera: Camera {
                sub_camera_view: Some(SubCameraView {
                    // Set the sub view camera to a fifth of the full view and
                    // move it in another system
                    full_size: uvec2(500, 500),
                    offset: ivec2(0, 0),
                    size: uvec2(100, 100),
                }),
                order: 2,
                ..default()
            },
            transform,
            ..default()
        },
        MovingCameraMarker,
    ));

    // Perspective camera control
    commands.spawn(Camera3dBundle {
        camera: Camera {
            sub_camera_view: Some(SubCameraView {
                // Set the sub view to the full image, to ensure that it matches
                // the projection without sub view
                full_size: uvec2(450, 450),
                offset: ivec2(0, 0),
                size: uvec2(450, 450),
            }),
            order: 3,
            ..default()
        },
        transform,
        ..default()
    });

    // Main orthographic camera
    commands.spawn(Camera3dBundle {
        projection: OrthographicProjection {
          ...
        }
        .into(),
        camera: Camera {
            order: 4,
            ..default()
        },
        transform,
        ..default()
    });

    // Orthographic camera left half
    commands.spawn(Camera3dBundle {
        projection: OrthographicProjection {
          ...
        }
        .into(),
        camera: Camera {
            sub_camera_view: Some(SubCameraView {
                // Set the sub view camera to the left half of the full image
                full_size: uvec2(500, 500),
                offset: ivec2(0, 0),
                size: uvec2(250, 500),
            }),
            order: 5,
            ..default()
        },
        transform,
        ..default()
    });

    // Orthographic camera moving
    commands.spawn((
        Camera3dBundle {
            projection: OrthographicProjection {
              ...
            }
            .into(),
            camera: Camera {
                sub_camera_view: Some(SubCameraView {
                    // Set the sub view camera to a fifth of the full view and
                    // move it in another system
                    full_size: uvec2(500, 500),
                    offset: ivec2(0, 0),
                    size: uvec2(100, 100),
                }),
                order: 6,
                ..default()
            },
            transform,
            ..default()
        },
        MovingCameraMarker,
    ));

    // Orthographic camera control
    commands.spawn(Camera3dBundle {
        projection: OrthographicProjection {
          ...
        }
        .into(),
        camera: Camera {
            sub_camera_view: Some(SubCameraView {
                // Set the sub view to the full image, to ensure that it matches
                // the projection without sub view
                full_size: uvec2(450, 450),
                offset: ivec2(0, 0),
                size: uvec2(450, 450),
            }),
            order: 7,
            ..default()
        },
        transform,
        ..default()
    });
```

</details>

Cargo.toml

@@ -3430,6 +3430,17 @@ description = "Demonstrates screen space reflections with water ripples"
 category = "3D Rendering"
 wasm = false
 
+[[example]]
+name = "camera_sub_view"
+path = "examples/3d/camera_sub_view.rs"
+doc-scrape-examples = true
+
+[package.metadata.example.camera_sub_view]
+name = "Camera sub view"
+description = "Demonstrates using different sub view effects on a camera"
+category = "3D Rendering"
+wasm = true
+
 [[example]]
 name = "color_grading"
 path = "examples/3d/color_grading.rs"

crates/bevy_render/src/camera/camera.rs

@@ -67,6 +67,54 @@ impl Default for Viewport {
     }
 }
 
+/// Settings to define a camera sub view.
+///
+/// When [`Camera::sub_camera_view`] is `Some`, only the sub-section of the
+/// image defined by `size` and `offset` (relative to the `full_size` of the
+/// whole image) is projected to the cameras viewport.
+///
+/// Take the example of the following multi-monitor setup:
+/// ```css
+/// ┌───┬───┐
+/// │ A │ B │
+/// ├───┼───┤
+/// │ C │ D │
+/// └───┴───┘
+/// ```
+/// If each monitor is 1920x1080, the whole image will have a resolution of
+/// 3840x2160. For each monitor we can use a single camera with a viewport of
+/// the same size as the monitor it corresponds to. To ensure that the image is
+/// cohesive, we can use a different sub view on each camera:
+/// - Camera A: `full_size` = 3840x2160, `size` = 1920x1080, `offset` = 0,0
+/// - Camera B: `full_size` = 3840x2160, `size` = 1920x1080, `offset` = 1920,0
+/// - Camera C: `full_size` = 3840x2160, `size` = 1920x1080, `offset` = 0,1080
+/// - Camera D: `full_size` = 3840x2160, `size` = 1920x1080, `offset` =
+///   1920,1080
+///
+/// However since only the ratio between the values is important, they could all
+/// be divided by 120 and still produce the same image. Camera D would for
+/// example have the following values:
+/// `full_size` = 32x18, `size` = 16x9, `offset` = 16,9
+#[derive(Debug, Clone, Copy, Reflect, PartialEq)]
+pub struct SubCameraView {
+    /// Size of the entire camera view
+    pub full_size: UVec2,
+    /// Offset of the sub camera
+    pub offset: Vec2,
+    /// Size of the sub camera
+    pub size: UVec2,
+}
+
+impl Default for SubCameraView {
+    fn default() -> Self {
+        Self {
+            full_size: UVec2::new(1, 1),
+            offset: Vec2::new(0., 0.),
+            size: UVec2::new(1, 1),
+        }
+    }
+}
+
 /// Information about the current [`RenderTarget`].
 #[derive(Default, Debug, Clone)]
 pub struct RenderTargetInfo {
@@ -86,6 +134,7 @@ pub struct ComputedCameraValues {
     target_info: Option<RenderTargetInfo>,
     // size of the `Viewport`
     old_viewport_size: Option<UVec2>,
+    old_sub_camera_view: Option<SubCameraView>,
 }
 
 /// How much energy a `Camera3d` absorbs from incoming light.
@@ -256,6 +305,8 @@ pub struct Camera {
     pub msaa_writeback: bool,
     /// The clear color operation to perform on the render target.
     pub clear_color: ClearColorConfig,
+    /// If set, this camera will be a sub camera of a large view, defined by a [`SubCameraView`].
+    pub sub_camera_view: Option<SubCameraView>,
 }
 
 impl Default for Camera {
@@ -270,6 +321,7 @@ impl Default for Camera {
             hdr: false,
             msaa_writeback: true,
             clear_color: Default::default(),
+            sub_camera_view: None,
         }
     }
 }
@@ -843,6 +895,7 @@ pub fn camera_system<T: CameraProjection + Component>(
                 || camera.is_added()
                 || camera_projection.is_changed()
                 || camera.computed.old_viewport_size != viewport_size
+                || camera.computed.old_sub_camera_view != camera.sub_camera_view
             {
                 let new_computed_target_info = normalized_target.get_render_target_info(
                     &windows,
@@ -890,14 +943,21 @@ pub fn camera_system<T: CameraProjection + Component>(
                 camera.computed.target_info = new_computed_target_info;
                 if let Some(size) = camera.logical_viewport_size() {
                     camera_projection.update(size.x, size.y);
-                    camera.computed.clip_from_view = camera_projection.get_clip_from_view();
+                    camera.computed.clip_from_view = match &camera.sub_camera_view {
+                        Some(sub_view) => camera_projection.get_clip_from_view_for_sub(sub_view),
+                        None => camera_projection.get_clip_from_view(),
+                    }
                 }
             }
         }
 
         if camera.computed.old_viewport_size != viewport_size {
             camera.computed.old_viewport_size = viewport_size;
         }
+
+        if camera.computed.old_sub_camera_view != camera.sub_camera_view {
+            camera.computed.old_sub_camera_view = camera.sub_camera_view;
+        }
     }
 }
 

crates/bevy_render/src/camera/projection.rs

@@ -6,7 +6,7 @@ use core::{
 use crate::{primitives::Frustum, view::VisibilitySystems};
 use bevy_app::{App, Plugin, PostStartup, PostUpdate};
 use bevy_ecs::prelude::*;
-use bevy_math::{ops, AspectRatio, Mat4, Rect, Vec2, Vec3A};
+use bevy_math::{ops, AspectRatio, Mat4, Rect, Vec2, Vec3A, Vec4};
 use bevy_reflect::{
     std_traits::ReflectDefault, GetTypeRegistration, Reflect, ReflectDeserialize, ReflectSerialize,
 };
@@ -76,6 +76,7 @@ pub struct CameraUpdateSystem;
 /// [`Camera`]: crate::camera::Camera
 pub trait CameraProjection {
     fn get_clip_from_view(&self) -> Mat4;
+    fn get_clip_from_view_for_sub(&self, sub_view: &super::SubCameraView) -> Mat4;
     fn update(&mut self, width: f32, height: f32);
     fn far(&self) -> f32;
     fn get_frustum_corners(&self, z_near: f32, z_far: f32) -> [Vec3A; 8];
@@ -124,6 +125,13 @@ impl CameraProjection for Projection {
         }
     }
 
+    fn get_clip_from_view_for_sub(&self, sub_view: &super::SubCameraView) -> Mat4 {
+        match self {
+            Projection::Perspective(projection) => projection.get_clip_from_view_for_sub(sub_view),
+            Projection::Orthographic(projection) => projection.get_clip_from_view_for_sub(sub_view),
+        }
+    }
+
     fn update(&mut self, width: f32, height: f32) {
         match self {
             Projection::Perspective(projection) => projection.update(width, height),
@@ -189,6 +197,45 @@ impl CameraProjection for PerspectiveProjection {
         Mat4::perspective_infinite_reverse_rh(self.fov, self.aspect_ratio, self.near)
     }
 
+    fn get_clip_from_view_for_sub(&self, sub_view: &super::SubCameraView) -> Mat4 {
+        let full_width = sub_view.full_size.x as f32;
+        let full_height = sub_view.full_size.y as f32;
+        let sub_width = sub_view.size.x as f32;
+        let sub_height = sub_view.size.y as f32;
+        let offset_x = sub_view.offset.x;
+        // Y-axis increases from top to bottom
+        let offset_y = full_height - (sub_view.offset.y + sub_height);
+
+        // Original frustum parameters
+        let top = self.near * ops::tan(0.5 * self.fov);
+        let bottom = -top;
+        let right = top * self.aspect_ratio;
+        let left = -right;
+
+        // Calculate scaling factors
+        let width = right - left;
+        let height = top - bottom;
+
+        // Calculate the new frustum parameters
+        let left_prime = left + (width * offset_x) / full_width;
+        let right_prime = left + (width * (offset_x + sub_width)) / full_width;
+        let bottom_prime = bottom + (height * offset_y) / full_height;
+        let top_prime = bottom + (height * (offset_y + sub_height)) / full_height;
+
+        // Compute the new projection matrix
+        let x = (2.0 * self.near) / (right_prime - left_prime);
+        let y = (2.0 * self.near) / (top_prime - bottom_prime);
+        let a = (right_prime + left_prime) / (right_prime - left_prime);
+        let b = (top_prime + bottom_prime) / (top_prime - bottom_prime);
+
+        Mat4::from_cols(
+            Vec4::new(x, 0.0, 0.0, 0.0),
+            Vec4::new(0.0, y, 0.0, 0.0),
+            Vec4::new(a, b, 0.0, -1.0),
+            Vec4::new(0.0, 0.0, self.near, 0.0),
+        )
+    }
+
     fn update(&mut self, width: f32, height: f32) {
         self.aspect_ratio = AspectRatio::try_new(width, height)
             .expect("Failed to update PerspectiveProjection: width and height must be positive, non-zero values")
@@ -395,6 +442,42 @@ impl CameraProjection for OrthographicProjection {
         )
     }
 
+    fn get_clip_from_view_for_sub(&self, sub_view: &super::SubCameraView) -> Mat4 {
+        let full_width = sub_view.full_size.x as f32;
+        let full_height = sub_view.full_size.y as f32;
+        let offset_x = sub_view.offset.x;
+        let offset_y = sub_view.offset.y;
+        let sub_width = sub_view.size.x as f32;
+        let sub_height = sub_view.size.y as f32;
+
+        // Orthographic projection parameters
+        let top = self.area.max.y;
+        let bottom = self.area.min.y;
+        let right = self.area.max.x;
+        let left = self.area.min.x;
+
+        // Calculate scaling factors
+        let scale_w = (right - left) / full_width;
+        let scale_h = (top - bottom) / full_height;
+
+        // Calculate the new orthographic bounds
+        let left_prime = left + scale_w * offset_x;
+        let right_prime = left_prime + scale_w * sub_width;
+        let top_prime = top - scale_h * offset_y;
+        let bottom_prime = top_prime - scale_h * sub_height;
+
+        Mat4::orthographic_rh(
+            left_prime,
+            right_prime,
+            bottom_prime,
+            top_prime,
+            // NOTE: near and far are swapped to invert the depth range from [0,1] to [1,0]
+            // This is for interoperability with pipelines using infinite reverse perspective projections.
+            self.far,
+            self.near,
+        )
+    }
+
     fn update(&mut self, width: f32, height: f32) {
         let (projection_width, projection_height) = match self.scaling_mode {
             ScalingMode::WindowSize(pixel_scale) => (width / pixel_scale, height / pixel_scale),