bevy_camera/

camera.rs

use crate::primitives::Frustum;

use super::{
    visibility::{Visibility, VisibleEntities},
    ClearColorConfig, MsaaWriteback,
};
use bevy_asset::Handle;
use bevy_derive::Deref;
use bevy_ecs::{
    component::Component, entity::Entity, reflect::ReflectComponent, template::FromTemplate,
};
use bevy_image::Image;
use bevy_math::{ops, Dir3, FloatOrd, Mat4, Ray3d, Rect, URect, UVec2, Vec2, Vec3, Vec3A};
use bevy_reflect::prelude::*;
use bevy_transform::components::{GlobalTransform, Transform};
use bevy_window::{NormalizedWindowRef, WindowRef};
use core::ops::Range;
use derive_more::derive::From;
use thiserror::Error;
use wgpu_types::{BlendState, TextureUsages};

/// Render viewport configuration for the [`Camera`] component.
///
/// The viewport defines the area on the render target to which the camera renders its image.
/// You can overlay multiple cameras in a single window using viewports to create effects like
/// split screen, minimaps, and character viewers.
///
/// <div class="warning">
///
/// Note that the physical position is in actual screen coordinates and not virtual pixels for window targets.  
/// You should use the scaling factor reported by the window, which on some OS's defaults to a value other than 1.
/// Please see the example code (which assumes a single camera and window)
///
/// ```no_run
/// # use bevy_camera::{Camera, Projection, Viewport};
/// # use bevy_transform::prelude::Transform;
/// # use bevy_ecs::prelude::*;
/// # use bevy_math::UVec2;
/// # use bevy_window::Window;
/// # use bevy_utils::default;
///
/// fn update_viewport(
///    mut camera_query: Query<(&mut Camera, &mut Transform, &mut Projection)>,
///    windows: Query<&Window>
/// ) {
///     let Ok((mut camera, _, _)) = camera_query.single_mut() else { return; };
///
///     let window = windows.single().expect("Window not found");
///     let scale = window.resolution.scale_factor();
///
///     camera.viewport = Some(Viewport {
///         physical_position: (UVec2::new(10, 10).as_vec2() * scale).as_uvec2(),
///         physical_size: (UVec2::new(100, 100).as_vec2() * scale).as_uvec2(),
///         ..default()
///     });
/// }
/// ```
///
/// </div>
#[derive(Reflect, Debug, Clone)]
#[reflect(Default, Clone)]
pub struct Viewport {
    /// The physical position to render this viewport to within the [`RenderTarget`] of this [`Camera`].
    /// (0,0) corresponds to the top-left corner
    pub physical_position: UVec2,
    /// The physical size of the viewport rectangle to render to within the [`RenderTarget`] of this [`Camera`].
    /// The origin of the rectangle is in the top-left corner.
    pub physical_size: UVec2,
    /// The minimum and maximum depth to render (on a scale from 0.0 to 1.0).
    pub depth: Range<f32>,
}

impl Default for Viewport {
    fn default() -> Self {
        Self {
            physical_position: Default::default(),
            physical_size: UVec2::new(1, 1),
            depth: 0.0..1.0,
        }
    }
}

impl Viewport {
    /// Cut the viewport rectangle so that it lies inside a rectangle of the
    /// given size.
    ///
    /// If either of the viewport's position coordinates lies outside the given
    /// dimensions, it will be moved just inside first. If either of the given
    /// dimensions is zero, the position and size of the viewport rectangle will
    /// both be set to zero in that dimension.
    pub fn clamp_to_size(&mut self, size: UVec2) {
        // If the origin of the viewport rect is outside, then adjust so that
        // it's just barely inside. Then, cut off the part that is outside.
        if self.physical_size.x + self.physical_position.x > size.x {
            if self.physical_position.x < size.x {
                self.physical_size.x = size.x - self.physical_position.x;
            } else if size.x > 0 {
                self.physical_position.x = size.x - 1;
                self.physical_size.x = 1;
            } else {
                self.physical_position.x = 0;
                self.physical_size.x = 0;
            }
        }
        if self.physical_size.y + self.physical_position.y > size.y {
            if self.physical_position.y < size.y {
                self.physical_size.y = size.y - self.physical_position.y;
            } else if size.y > 0 {
                self.physical_position.y = size.y - 1;
                self.physical_size.y = 1;
            } else {
                self.physical_position.y = 0;
                self.physical_size.y = 0;
            }
        }
    }

    pub fn from_viewport_and_override(
        viewport: Option<&Self>,
        main_pass_resolution_override: Option<&MainPassResolutionOverride>,
    ) -> Option<Self> {
        if let Some(override_size) = main_pass_resolution_override {
            let mut vp = viewport.map_or_else(Self::default, Self::clone);
            vp.physical_size = **override_size;
            Some(vp)
        } else {
            viewport.cloned()
        }
    }
}

/// Override the resolution a 3d camera's main pass is rendered at.
///
/// Does not affect post processing.
///
/// ## Usage
///
/// * Insert this component on a 3d camera entity in the render world.
/// * The resolution override must be smaller than the camera's viewport size.
/// * The resolution override is specified in physical pixels.
/// * In shaders, use `View::main_pass_viewport` instead of `View::viewport`.
#[derive(Component, Reflect, Deref, Debug)]
#[reflect(Component)]
pub struct MainPassResolutionOverride(pub UVec2);

/// 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)]
#[reflect(Clone, PartialEq, Default)]
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(Debug, Reflect, Clone)]
pub struct RenderTargetInfo {
    /// The physical size of this render target (in physical pixels, ignoring scale factor).
    pub physical_size: UVec2,
    /// The scale factor of this render target.
    ///
    /// When rendering to a window, typically it is a value greater or equal than 1.0,
    /// representing the ratio between the size of the window in physical pixels and the logical size of the window.
    pub scale_factor: f32,
}

impl Default for RenderTargetInfo {
    fn default() -> Self {
        Self {
            physical_size: Default::default(),
            scale_factor: 1.,
        }
    }
}

/// Holds internally computed [`Camera`] values.
#[derive(Default, Debug, Reflect, Clone)]
pub struct ComputedCameraValues {
    pub clip_from_view: Mat4,
    pub target_info: Option<RenderTargetInfo>,
    // size of the `Viewport`
    pub old_viewport_size: Option<UVec2>,
    pub old_sub_camera_view: Option<SubCameraView>,
}

/// How much energy a [`Camera3d`](crate::Camera3d) absorbs from incoming light.
///
/// <https://en.wikipedia.org/wiki/Exposure_(photography)>
#[derive(Component, Clone, Copy, Reflect)]
#[reflect(opaque)]
#[reflect(Component, Default, Clone)]
pub struct Exposure {
    /// <https://en.wikipedia.org/wiki/Exposure_value#Tabulated_exposure_values>
    pub ev100: f32,
}

impl Exposure {
    pub const SUNLIGHT: Self = Self {
        ev100: Self::EV100_SUNLIGHT,
    };
    pub const OVERCAST: Self = Self {
        ev100: Self::EV100_OVERCAST,
    };
    pub const INDOOR: Self = Self {
        ev100: Self::EV100_INDOOR,
    };
    /// This value was calibrated to match Blender's implicit/default exposure as closely as possible.
    /// It also happens to be a reasonable default.
    ///
    /// See <https://github.com/bevyengine/bevy/issues/11577> for details.
    pub const BLENDER: Self = Self {
        ev100: Self::EV100_BLENDER,
    };

    pub const EV100_SUNLIGHT: f32 = 15.0;
    pub const EV100_OVERCAST: f32 = 12.0;
    pub const EV100_INDOOR: f32 = 7.0;

    /// This value was calibrated to match Blender's implicit/default exposure as closely as possible.
    /// It also happens to be a reasonable default.
    ///
    /// See <https://github.com/bevyengine/bevy/issues/11577> for details.
    pub const EV100_BLENDER: f32 = 9.7;

    pub fn from_physical_camera(physical_camera_parameters: PhysicalCameraParameters) -> Self {
        Self {
            ev100: physical_camera_parameters.ev100(),
        }
    }

    /// Converts EV100 values to exposure values.
    /// <https://google.github.io/filament/Filament.md.html#imagingpipeline/physicallybasedcamera/exposure>
    #[inline]
    pub fn exposure(&self) -> f32 {
        ops::exp2(-self.ev100) / 1.2
    }
}

impl Default for Exposure {
    fn default() -> Self {
        Self::BLENDER
    }
}

/// Parameters based on physical camera characteristics for calculating EV100
/// values for use with [`Exposure`]. This is also used for depth of field.
#[derive(Clone, Copy)]
pub struct PhysicalCameraParameters {
    /// <https://en.wikipedia.org/wiki/F-number>
    pub aperture_f_stops: f32,
    /// <https://en.wikipedia.org/wiki/Shutter_speed>
    pub shutter_speed_s: f32,
    /// <https://en.wikipedia.org/wiki/Film_speed>
    pub sensitivity_iso: f32,
    /// The height of the [image sensor format] in meters.
    ///
    /// Focal length is derived from the FOV and this value. The default is
    /// 18.66mm, matching the [Super 35] format, which is popular in cinema.
    ///
    /// [image sensor format]: https://en.wikipedia.org/wiki/Image_sensor_format
    ///
    /// [Super 35]: https://en.wikipedia.org/wiki/Super_35
    pub sensor_height: f32,
}

impl PhysicalCameraParameters {
    /// Calculate the [EV100](https://en.wikipedia.org/wiki/Exposure_value).
    pub fn ev100(&self) -> f32 {
        ops::log2(
            self.aperture_f_stops * self.aperture_f_stops * 100.0
                / (self.shutter_speed_s * self.sensitivity_iso),
        )
    }
}

impl Default for PhysicalCameraParameters {
    fn default() -> Self {
        Self {
            aperture_f_stops: 1.0,
            shutter_speed_s: 1.0 / 125.0,
            sensitivity_iso: 100.0,
            sensor_height: 0.01866,
        }
    }
}

/// Error returned when a conversion between world-space and viewport-space coordinates fails.
///
/// See [`world_to_viewport`][Camera::world_to_viewport] and [`viewport_to_world`][Camera::viewport_to_world].
#[derive(Debug, Eq, PartialEq, Copy, Clone, Error)]
pub enum ViewportConversionError {
    /// The pre-computed size of the viewport was not available.
    ///
    /// This may be because the `Camera` was just created and `camera_system` has not been executed
    /// yet, or because the [`RenderTarget`] is misconfigured in one of the following ways:
    ///   - it references the [`PrimaryWindow`](RenderTarget::Window) when there is none,
    ///   - it references a [`Window`](RenderTarget::Window) entity that doesn't exist or doesn't actually have a `Window` component,
    ///   - it references an [`Image`](RenderTarget::Image) that doesn't exist (invalid handle),
    ///   - it references a [`TextureView`](RenderTarget::TextureView) that doesn't exist (invalid handle).
    #[error("pre-computed size of viewport not available")]
    NoViewportSize,
    /// The computed coordinate was beyond the `Camera`'s near plane.
    ///
    /// Only applicable when converting from world-space to viewport-space.
    #[error("computed coordinate beyond `Camera`'s near plane")]
    PastNearPlane,
    /// The computed coordinate was beyond the `Camera`'s far plane.
    ///
    /// Only applicable when converting from world-space to viewport-space.
    #[error("computed coordinate beyond `Camera`'s far plane")]
    PastFarPlane,
    /// The Normalized Device Coordinates could not be computed because the `camera_transform`, the
    /// `world_position`, or the projection matrix defined by [`Projection`](super::projection::Projection)
    /// contained `NAN` (see [`world_to_ndc`][Camera::world_to_ndc] and [`ndc_to_world`][Camera::ndc_to_world]).
    #[error("found NaN while computing NDC")]
    InvalidData,
}

/// The defining [`Component`] for camera entities,
/// storing information about how and what to render through this camera.
///
/// The [`Camera`] component is added to an entity to define the properties of the viewpoint from
/// which rendering occurs. It defines the position of the view to render, the projection method
/// to transform the 3D objects into a 2D image, as well as the render target into which that image
/// is produced.
///
/// Note that a [`Camera`] needs a `CameraRenderGraph` to render anything.
/// This is typically provided by adding a [`Camera2d`] or [`Camera3d`] component,
/// but custom render graphs can also be defined. Inserting a [`Camera`] with no render
/// graph will emit an error at runtime.
///
/// [`Camera2d`]: crate::Camera2d
/// [`Camera3d`]: crate::Camera3d
#[derive(Component, Debug, Reflect, Clone)]
#[reflect(Component, Default, Debug, Clone)]
#[require(
    Frustum,
    CameraMainTextureUsages,
    VisibleEntities,
    Transform,
    Visibility,
    RenderTarget
)]
pub struct Camera {
    /// If set, this camera will render to the given [`Viewport`] rectangle within the configured [`RenderTarget`].
    pub viewport: Option<Viewport>,
    /// Cameras with a higher order are rendered later, and thus on top of lower order cameras.
    pub order: isize,
    /// If this is set to `true`, this camera will be rendered to its specified [`RenderTarget`]. If `false`, this
    /// camera will not be rendered.
    pub is_active: bool,
    /// Computed values for this camera, such as the projection matrix and the render target size.
    pub computed: ComputedCameraValues,
    // todo: reflect this when #6042 lands
    /// The [`CameraOutputMode`] for this camera.
    pub output_mode: CameraOutputMode,
    /// Controls when MSAA writeback occurs for this camera.
    /// See [`MsaaWriteback`] for available options.
    pub msaa_writeback: MsaaWriteback,
    /// The clear color operation to perform on the render target.
    pub clear_color: ClearColorConfig,
    /// Whether to switch culling mode so that materials that request backface
    /// culling cull front faces, and vice versa.
    ///
    /// This is typically used for cameras that mirror the world that they
    /// render across a plane, because doing that flips the winding of each
    /// polygon.
    ///
    /// This setting doesn't affect materials that disable backface culling.
    pub invert_culling: bool,
    /// 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 {
    fn default() -> Self {
        Self {
            is_active: true,
            order: 0,
            viewport: None,
            computed: Default::default(),
            output_mode: Default::default(),
            msaa_writeback: MsaaWriteback::default(),
            clear_color: Default::default(),
            invert_culling: false,
            sub_camera_view: None,
        }
    }
}

impl Camera {
    /// Converts a physical size in this `Camera` to a logical size.
    #[inline]
    pub fn to_logical(&self, physical_size: UVec2) -> Option<Vec2> {
        let scale = self.computed.target_info.as_ref()?.scale_factor;
        Some(physical_size.as_vec2() / scale)
    }

    /// The rendered physical bounds [`URect`] of the camera. If the `viewport` field is
    /// set to [`Some`], this will be the rect of that custom viewport. Otherwise it will default to
    /// the full physical rect of the current [`RenderTarget`].
    #[inline]
    pub fn physical_viewport_rect(&self) -> Option<URect> {
        let min = self
            .viewport
            .as_ref()
            .map(|v| v.physical_position)
            .unwrap_or(UVec2::ZERO);
        let max = min + self.physical_viewport_size()?;
        Some(URect { min, max })
    }

    /// The rendered logical bounds [`Rect`] of the camera. If the `viewport` field is set to
    /// [`Some`], this will be the rect of that custom viewport. Otherwise it will default to the
    /// full logical rect of the current [`RenderTarget`].
    #[inline]
    pub fn logical_viewport_rect(&self) -> Option<Rect> {
        let URect { min, max } = self.physical_viewport_rect()?;
        Some(Rect {
            min: self.to_logical(min)?,
            max: self.to_logical(max)?,
        })
    }

    /// The logical size of this camera's viewport. If the `viewport` field is set to [`Some`], this
    /// will be the size of that custom viewport. Otherwise it will default to the full logical size
    /// of the current [`RenderTarget`].
    ///  For logic that requires the full logical size of the
    /// [`RenderTarget`], prefer [`Camera::logical_target_size`].
    ///
    /// Returns `None` if either:
    /// - the function is called just after the `Camera` is created, before `camera_system` is executed,
    /// - the [`RenderTarget`] isn't correctly set:
    ///   - it references the [`PrimaryWindow`](RenderTarget::Window) when there is none,
    ///   - it references a [`Window`](RenderTarget::Window) entity that doesn't exist or doesn't actually have a `Window` component,
    ///   - it references an [`Image`](RenderTarget::Image) that doesn't exist (invalid handle),
    ///   - it references a [`TextureView`](RenderTarget::TextureView) that doesn't exist (invalid handle).
    #[inline]
    pub fn logical_viewport_size(&self) -> Option<Vec2> {
        self.viewport
            .as_ref()
            .and_then(|v| self.to_logical(v.physical_size))
            .or_else(|| self.logical_target_size())
    }

    /// The physical size of this camera's viewport (in physical pixels).
    /// If the `viewport` field is set to [`Some`], this
    /// will be the size of that custom viewport. Otherwise it will default to the full physical size of
    /// the current [`RenderTarget`].
    /// For logic that requires the full physical size of the [`RenderTarget`], prefer [`Camera::physical_target_size`].
    #[inline]
    pub fn physical_viewport_size(&self) -> Option<UVec2> {
        self.viewport
            .as_ref()
            .map(|v| v.physical_size)
            .or_else(|| self.physical_target_size())
    }

    /// The full logical size of this camera's [`RenderTarget`], ignoring custom `viewport` configuration.
    /// Note that if the `viewport` field is [`Some`], this will not represent the size of the rendered area.
    /// For logic that requires the size of the actually rendered area, prefer [`Camera::logical_viewport_size`].
    #[inline]
    pub fn logical_target_size(&self) -> Option<Vec2> {
        self.computed
            .target_info
            .as_ref()
            .and_then(|t| self.to_logical(t.physical_size))
    }

    /// The full physical size of this camera's [`RenderTarget`] (in physical pixels),
    /// ignoring custom `viewport` configuration.
    /// Note that if the `viewport` field is [`Some`], this will not represent the size of the rendered area.
    /// For logic that requires the size of the actually rendered area, prefer [`Camera::physical_viewport_size`].
    #[inline]
    pub fn physical_target_size(&self) -> Option<UVec2> {
        self.computed.target_info.as_ref().map(|t| t.physical_size)
    }

    #[inline]
    pub fn target_scaling_factor(&self) -> Option<f32> {
        self.computed
            .target_info
            .as_ref()
            .map(|t: &RenderTargetInfo| t.scale_factor)
    }

    /// The projection matrix computed using this camera's [`Projection`](super::projection::Projection).
    #[inline]
    pub fn clip_from_view(&self) -> Mat4 {
        self.computed.clip_from_view
    }

    /// Core conversion logic to compute viewport coordinates
    ///
    /// This function is shared by `world_to_viewport` and `world_to_viewport_with_depth`
    /// to avoid code duplication.
    ///
    /// Returns a tuple `(viewport_position, depth)`.
    fn world_to_viewport_core(
        &self,
        camera_transform: &GlobalTransform,
        world_position: Vec3,
    ) -> Result<(Vec2, f32), ViewportConversionError> {
        let target_rect = self
            .logical_viewport_rect()
            .ok_or(ViewportConversionError::NoViewportSize)?;
        let mut ndc_space_coords = self
            .world_to_ndc(camera_transform, world_position)
            .ok_or(ViewportConversionError::InvalidData)?;
        // NDC z-values outside of 0 < z < 1 are outside the (implicit) camera frustum and are thus not in viewport-space
        if ndc_space_coords.z < 0.0 {
            return Err(ViewportConversionError::PastFarPlane);
        }
        if ndc_space_coords.z > 1.0 {
            return Err(ViewportConversionError::PastNearPlane);
        }

        let depth = ndc_space_coords.z;

        // Flip the Y co-ordinate origin from the bottom to the top.
        ndc_space_coords.y = -ndc_space_coords.y;

        // Once in NDC space, we can discard the z element and map x/y to the viewport rect
        let viewport_position =
            (ndc_space_coords.truncate() + Vec2::ONE) / 2.0 * target_rect.size() + target_rect.min;
        Ok((viewport_position, depth))
    }

    /// Given a position in world space, use the camera to compute the viewport-space coordinates.
    ///
    /// To get the coordinates in Normalized Device Coordinates, you should use
    /// [`world_to_ndc`](Self::world_to_ndc).
    ///
    /// # Panics
    ///
    /// Will panic if `glam_assert` is enabled and the `camera_transform` contains `NAN`
    /// (see [`world_to_ndc`][Self::world_to_ndc]).
    #[doc(alias = "world_to_screen")]
    pub fn world_to_viewport(
        &self,
        camera_transform: &GlobalTransform,
        world_position: Vec3,
    ) -> Result<Vec2, ViewportConversionError> {
        Ok(self
            .world_to_viewport_core(camera_transform, world_position)?
            .0)
    }

    /// Given a position in world space, use the camera to compute the viewport-space coordinates and depth.
    ///
    /// To get the coordinates in Normalized Device Coordinates, you should use
    /// [`world_to_ndc`](Self::world_to_ndc).
    ///
    /// # Panics
    ///
    /// Will panic if `glam_assert` is enabled and the `camera_transform` contains `NAN`
    /// (see [`world_to_ndc`][Self::world_to_ndc]).
    #[doc(alias = "world_to_screen_with_depth")]
    pub fn world_to_viewport_with_depth(
        &self,
        camera_transform: &GlobalTransform,
        world_position: Vec3,
    ) -> Result<Vec3, ViewportConversionError> {
        let result = self.world_to_viewport_core(camera_transform, world_position)?;
        // Stretching ndc depth to value via near plane and negating result to be in positive room again.
        let depth = -self.depth_ndc_to_view_z(result.1);
        Ok(result.0.extend(depth))
    }

    /// Returns a ray originating from the camera, that passes through everything beyond `viewport_position`.
    ///
    /// The resulting ray starts on the near plane of the camera.
    ///
    /// If the camera's projection is orthographic the direction of the ray is always equal to `camera_transform.forward()`.
    ///
    /// To get the world space coordinates with Normalized Device Coordinates, you should use
    /// [`ndc_to_world`](Self::ndc_to_world).
    ///
    /// # Example
    /// ```no_run
    /// # use bevy_window::Window;
    /// # use bevy_ecs::prelude::{Single, IntoScheduleConfigs};
    /// # use bevy_transform::prelude::{GlobalTransform, TransformSystems};
    /// # use bevy_camera::Camera;
    /// # use bevy_app::{App, PostUpdate};
    /// #
    /// fn system(camera_query: Single<(&Camera, &GlobalTransform)>, window: Single<&Window>) {
    ///     let (camera, camera_transform) = *camera_query;
    ///
    ///     if let Some(cursor_position) = window.cursor_position()
    ///         // Calculate a ray pointing from the camera into the world based on the cursor's position.
    ///         && let Ok(ray) = camera.viewport_to_world(camera_transform, cursor_position)
    ///     {
    ///         println!("{ray:?}");
    ///     }
    /// }
    ///
    /// # let mut app = App::new();
    /// // Run the system after transform propagation so the camera's global transform is up-to-date.
    /// app.add_systems(PostUpdate, system.after(TransformSystems::Propagate));
    /// ```
    ///
    /// # Panics
    ///
    /// Will panic if the camera's projection matrix is invalid (has a determinant of 0) and
    /// `glam_assert` is enabled (see [`ndc_to_world`](Self::ndc_to_world).
    pub fn viewport_to_world(
        &self,
        camera_transform: &GlobalTransform,
        viewport_position: Vec2,
    ) -> Result<Ray3d, ViewportConversionError> {
        let ndc_xy = self.viewport_to_ndc(viewport_position)?;

        let ndc_point_near = ndc_xy.extend(1.0).into();
        // Using EPSILON because an ndc with Z = 0 returns NaNs.
        let ndc_point_far = ndc_xy.extend(f32::EPSILON).into();
        let view_from_clip = self.computed.clip_from_view.inverse();
        let world_from_view = camera_transform.affine();
        // We multiply the point by `view_from_clip` and then `world_from_view` in sequence to avoid the precision loss
        // (and performance penalty) incurred by pre-composing an affine transform with a projective transform.
        // Additionally, we avoid adding and subtracting translation to the direction component to maintain precision.
        let view_point_near = view_from_clip.project_point3a(ndc_point_near);
        let view_point_far = view_from_clip.project_point3a(ndc_point_far);
        let view_dir = view_point_far - view_point_near;
        let origin = world_from_view.transform_point3a(view_point_near).into();
        let direction = world_from_view.transform_vector3a(view_dir).into();

        // The fallible direction constructor ensures that direction isn't NaN.
        Dir3::new(direction)
            .map_err(|_| ViewportConversionError::InvalidData)
            .map(|direction| Ray3d { origin, direction })
    }

    /// Returns a 2D world position computed from a position on this [`Camera`]'s viewport.
    ///
    /// Useful for 2D cameras and other cameras with an orthographic projection pointing along the Z axis.
    ///
    /// To get the world space coordinates with Normalized Device Coordinates, you should use
    /// [`ndc_to_world`](Self::ndc_to_world).
    ///
    /// # Example
    /// ```no_run
    /// # use bevy_window::Window;
    /// # use bevy_ecs::prelude::*;
    /// # use bevy_transform::prelude::{GlobalTransform, TransformSystems};
    /// # use bevy_camera::Camera;
    /// # use bevy_app::{App, PostUpdate};
    /// #
    /// fn system(camera_query: Single<(&Camera, &GlobalTransform)>, window: Single<&Window>) {
    ///     let (camera, camera_transform) = *camera_query;
    ///
    ///     if let Some(cursor_position) = window.cursor_position()
    ///         // Calculate a world position based on the cursor's position.
    ///         && let Ok(world_pos) = camera.viewport_to_world_2d(camera_transform, cursor_position)
    ///     {
    ///         println!("World position: {world_pos:.2}");
    ///     }
    /// }
    ///
    /// # let mut app = App::new();
    /// // Run the system after transform propagation so the camera's global transform is up-to-date.
    /// app.add_systems(PostUpdate, system.after(TransformSystems::Propagate));
    /// ```
    ///
    /// # Panics
    ///
    /// Will panic if the camera's projection matrix is invalid (has a determinant of 0) and
    /// `glam_assert` is enabled (see [`ndc_to_world`](Self::ndc_to_world).
    pub fn viewport_to_world_2d(
        &self,
        camera_transform: &GlobalTransform,
        viewport_position: Vec2,
    ) -> Result<Vec2, ViewportConversionError> {
        let ndc = self.viewport_to_ndc(viewport_position)?;

        let world_near_plane = self
            .ndc_to_world(camera_transform, ndc.extend(1.))
            .ok_or(ViewportConversionError::InvalidData)?;

        Ok(world_near_plane.truncate())
    }

    /// Given a point in world space, use the camera's viewport to compute the Normalized Device Coordinates of the point.
    ///
    /// When the point is within the viewport the values returned will be between -1.0 (bottom left) and 1.0 (top right)
    /// on the X and Y axes, and between 0.0 (far) and 1.0 (near) on the Z axis.
    /// To get the coordinates in the render target's viewport dimensions, you should use
    /// [`world_to_viewport`](Self::world_to_viewport).
    ///
    /// Returns `None` if the `camera_transform`, the `world_position`, or the projection matrix defined by
    /// [`Projection`](super::projection::Projection) contain `NAN`.
    ///
    /// # Panics
    ///
    /// Will panic if the `camera_transform` contains `NAN` and the `glam_assert` feature is enabled.
    pub fn world_to_ndc<V: Into<Vec3A> + From<Vec3A>>(
        &self,
        camera_transform: &GlobalTransform,
        world_point: V,
    ) -> Option<V> {
        let view_from_world = camera_transform.affine().inverse();
        let view_point = view_from_world.transform_point3a(world_point.into());
        let ndc_point = self.computed.clip_from_view.project_point3a(view_point);

        (!ndc_point.is_nan()).then_some(ndc_point.into())
    }

    /// Given a position in Normalized Device Coordinates,
    /// use the camera's viewport to compute the world space position.
    ///
    /// The input is expected to be in NDC: `x` and `y` in the range `[-1.0, 1.0]`, and `z` in `[0.0, 1.0]`
    /// (with `z = 0.0` at the far plane and `z = 1.0` at the near plane).
    /// The returned value is a position in world space (your game's world units) and is not limited to `[-1.0, 1.0]`.
    /// To convert from a viewport position to world space, you should use
    /// [`viewport_to_world`](Self::viewport_to_world).
    ///
    /// Returns `None` if the `camera_transform`, the `ndc_point`, or the projection matrix defined by
    /// [`Projection`](super::projection::Projection) contain `NAN`.
    ///
    /// # Panics
    ///
    /// Will panic if the projection matrix is invalid (has a determinant of 0) and `glam_assert` is enabled.
    pub fn ndc_to_world<V: Into<Vec3A> + From<Vec3A>>(
        &self,
        camera_transform: &GlobalTransform,
        ndc_point: V,
    ) -> Option<V> {
        // We multiply the point by `view_from_clip` and then `world_from_view` in sequence to avoid the precision loss
        // (and performance penalty) incurred by pre-composing an affine transform with a projective transform.
        let view_point = self
            .computed
            .clip_from_view
            .inverse()
            .project_point3a(ndc_point.into());
        let world_point = camera_transform.affine().transform_point3a(view_point);

        (!world_point.is_nan()).then_some(world_point.into())
    }

    /// Converts the depth in Normalized Device Coordinates
    /// to linear view z for perspective projections.
    ///
    /// Note: Depth values in front of the camera will be negative as -z is forward
    pub fn depth_ndc_to_view_z(&self, ndc_depth: f32) -> f32 {
        let near = self.clip_from_view().w_axis.z; // [3][2]
        -near / ndc_depth
    }

    /// Converts the depth in Normalized Device Coordinates
    /// to linear view z for orthographic projections.
    ///
    /// Note: Depth values in front of the camera will be negative as -z is forward
    pub fn depth_ndc_to_view_z_2d(&self, ndc_depth: f32) -> f32 {
        -(self.clip_from_view().w_axis.z - ndc_depth) / self.clip_from_view().z_axis.z
        //                       [3][2]                                         [2][2]
    }

    /// Converts a position in viewport coordinates to NDC.
    pub fn viewport_to_ndc(
        &self,
        viewport_position: Vec2,
    ) -> Result<Vec2, ViewportConversionError> {
        let target_rect = self
            .logical_viewport_rect()
            .ok_or(ViewportConversionError::NoViewportSize)?;
        let rect_relative = (viewport_position - target_rect.min) / target_rect.size();
        let mut ndc = rect_relative * 2. - Vec2::ONE;
        // Flip the Y co-ordinate from the top to the bottom to enter NDC.
        ndc.y = -ndc.y;
        Ok(ndc)
    }
}

/// The entity that Bevy uses to resolve visibility ranges when no specific
/// camera is applicable.
///
/// For efficiency, Bevy currently renders point and spot light shadow maps only
/// once per frame, regardless of the number of cameras in use, rather than
/// rendering the shadow maps anew for each camera each frame. Most of the time,
/// this optimization doesn't change the result relative to a rendering that
/// rendered such shadow maps separately for each camera. However, there's one
/// exception: visibility ranges. Visibility ranges cause meshes to be visible
/// or invisible depending on the distance from the mesh to the camera. When
/// rendering a shadow map for a point or spot light, Bevy must therefore select
/// an entity to use as the reference point for the purposes of visibility
/// ranges. This entity is called the *LOD origin*.
///
/// Placing this component on an entity makes that entity the origin from which
/// LOD distances are computed for the purposes of shadow mapping of point and
/// spot lights. Typically, you place this component on a camera, but you may
/// place it on another entity if you wish.
///
/// The exact algorithm that Bevy uses to determine the LOD origin is as
/// follows. Once the LOD origin is determined, all further steps are skipped.
///
/// 1. If an entity has this [`ShadowLodOrigin`] component, then it's the LOD
///    origin. If there's more than one entity with the [`ShadowLodOrigin`]
///    component, one is chosen arbitrarily in a manner that's stable from frame to
///    frame.
///
/// 2. If a camera renders to a window (that is, the camera's [`RenderTarget`]
///    is [`RenderTarget::Window`]), then that camera is the shadow LOD origin. If
///    there's more than one such camera that renders to a window, then one is
///    chosen arbitrarily in a manner that's stable from frame to frame.
///
/// 3. A camera is chosen to be the LOD origin arbitrarily from all cameras in
///    the scene in a manner that's stable from frame to frame.
///
/// This algorithm means that, in most cases, you don't need to add this
/// [`ShadowLodOrigin`] component explicitly to the scene; usually, Bevy chooses
/// the right origin automatically. You only need to use this component
/// explicitly if you have multiple cameras rendering to the window: e.g. in a
/// split-screen game.
#[derive(Clone, Copy, Default, Component, Debug, Reflect)]
#[reflect(Clone, Default, Component)]
#[require(Transform)]
pub struct ShadowLodOrigin;

/// Control how this [`Camera`] outputs once rendering is completed.
#[derive(Debug, Clone, Copy, Reflect)]
pub enum CameraOutputMode {
    /// Writes the camera output to configured render target.
    Write {
        /// The blend state that will be used by the pipeline that writes the intermediate render textures to the final render target texture.
        /// If not set, the output will be written as-is, ignoring `clear_color` and the existing data in the final render target texture.
        blend_state: Option<BlendState>,
        /// The clear color operation to perform on the final render target texture.
        clear_color: ClearColorConfig,
    },
    /// Skips writing the camera output to the configured render target. The output will remain in the
    /// Render Target's "intermediate" textures, which a camera with a higher order should write to the render target
    /// using [`CameraOutputMode::Write`]. The "skip" mode can easily prevent render results from being displayed, or cause
    /// them to be lost. Only use this if you know what you are doing!
    /// In camera setups with multiple active cameras rendering to the same [`RenderTarget`], the Skip mode can be used to remove
    /// unnecessary / redundant writes to the final output texture, removing unnecessary render passes.
    Skip,
}

impl Default for CameraOutputMode {
    fn default() -> Self {
        CameraOutputMode::Write {
            blend_state: None,
            clear_color: ClearColorConfig::Default,
        }
    }
}

/// The "target" that a [`Camera`] will render to. For example, this could be a `Window`
/// swapchain or an [`Image`].
#[derive(Component, Debug, Clone, Reflect, From)]
#[reflect(Clone, Component)]
pub enum RenderTarget {
    /// Window to which the camera's view is rendered.
    Window(WindowRef),
    /// Image to which the camera's view is rendered.
    Image(ImageRenderTarget),
    /// Texture View to which the camera's view is rendered.
    /// Useful when the texture view needs to be created outside of Bevy, for example OpenXR.
    TextureView(ManualTextureViewHandle),
    /// The camera won't render to any color target.
    ///
    /// This is useful when you want a camera that *only* renders prepasses, for
    /// example a depth prepass. See the `render_depth_to_texture` example.
    None {
        /// The physical size of the viewport.
        size: UVec2,
    },
}

impl RenderTarget {
    /// Get a handle to the render target's image,
    /// or `None` if the render target is another variant.
    pub fn as_image(&self) -> Option<&Handle<Image>> {
        if let Self::Image(image_target) = self {
            Some(&image_target.handle)
        } else {
            None
        }
    }

    /// Normalize the render target down to a more concrete value, mostly used for equality comparisons.
    pub fn normalize(&self, primary_window: Option<Entity>) -> Option<NormalizedRenderTarget> {
        match self {
            RenderTarget::Window(window_ref) => window_ref
                .normalize(primary_window)
                .map(NormalizedRenderTarget::Window),
            RenderTarget::Image(handle) => Some(NormalizedRenderTarget::Image(handle.clone())),
            RenderTarget::TextureView(id) => Some(NormalizedRenderTarget::TextureView(*id)),
            RenderTarget::None { size } => Some(NormalizedRenderTarget::None {
                width: size.x,
                height: size.y,
            }),
        }
    }
}

/// Normalized version of the render target.
///
/// Once we have this we shouldn't need to resolve it down anymore.
#[derive(Debug, Clone, Reflect, PartialEq, Eq, Hash, PartialOrd, Ord, From)]
#[reflect(Clone, PartialEq, Hash)]
pub enum NormalizedRenderTarget {
    /// Window to which the camera's view is rendered.
    Window(NormalizedWindowRef),
    /// Image to which the camera's view is rendered.
    Image(ImageRenderTarget),
    /// Texture View to which the camera's view is rendered.
    /// Useful when the texture view needs to be created outside of Bevy, for example OpenXR.
    TextureView(ManualTextureViewHandle),
    /// The camera won't render to any color target.
    ///
    /// This is useful when you want a camera that *only* renders prepasses, for
    /// example a depth prepass. See the `render_depth_to_texture` example.
    None {
        /// The physical width of the viewport.
        width: u32,
        /// The physical height of the viewport.
        height: u32,
    },
}

/// A unique id that corresponds to a specific `ManualTextureView` in the `ManualTextureViews` collection.
///
/// See `ManualTextureViews` in `bevy_camera` for more details.
#[derive(
    Default,
    Debug,
    Clone,
    Copy,
    PartialEq,
    Eq,
    Hash,
    PartialOrd,
    Ord,
    Component,
    Reflect,
    FromTemplate,
)]
#[reflect(Component, Default, Debug, PartialEq, Hash, Clone)]
pub struct ManualTextureViewHandle(pub u32);

/// A render target that renders to an [`Image`].
#[derive(Debug, Clone, Reflect)]
#[reflect(Clone, PartialEq, Hash)]
pub struct ImageRenderTarget {
    /// The image to render to.
    pub handle: Handle<Image>,
    /// The scale factor of the render target image, corresponding to the scale
    /// factor for a window target. This should almost always be 1.0.
    pub scale_factor: f32,
}

impl Eq for ImageRenderTarget {}

impl PartialEq for ImageRenderTarget {
    fn eq(&self, other: &Self) -> bool {
        self.handle == other.handle && FloatOrd(self.scale_factor) == FloatOrd(other.scale_factor)
    }
}

impl core::hash::Hash for ImageRenderTarget {
    fn hash<H: core::hash::Hasher>(&self, state: &mut H) {
        self.handle.hash(state);
        FloatOrd(self.scale_factor).hash(state);
    }
}

impl PartialOrd for ImageRenderTarget {
    fn partial_cmp(&self, other: &Self) -> Option<core::cmp::Ordering> {
        Some(self.cmp(other))
    }
}

impl Ord for ImageRenderTarget {
    fn cmp(&self, other: &Self) -> core::cmp::Ordering {
        self.handle
            .cmp(&other.handle)
            .then_with(|| FloatOrd(self.scale_factor).cmp(&FloatOrd(other.scale_factor)))
    }
}

impl From<Handle<Image>> for RenderTarget {
    fn from(handle: Handle<Image>) -> Self {
        Self::Image(handle.into())
    }
}

impl From<Handle<Image>> for ImageRenderTarget {
    fn from(handle: Handle<Image>) -> Self {
        Self {
            handle,
            scale_factor: 1.0,
        }
    }
}

impl Default for RenderTarget {
    fn default() -> Self {
        Self::Window(Default::default())
    }
}

/// This component lets you control the [`TextureUsages`] field of the main texture generated for the camera
#[derive(Component, Clone, Copy, Reflect)]
#[reflect(opaque)]
#[reflect(Component, Default, Clone)]
pub struct CameraMainTextureUsages(pub TextureUsages);

impl Default for CameraMainTextureUsages {
    fn default() -> Self {
        Self(
            TextureUsages::RENDER_ATTACHMENT
                | TextureUsages::TEXTURE_BINDING
                | TextureUsages::COPY_SRC,
        )
    }
}

impl CameraMainTextureUsages {
    pub fn with(mut self, usages: TextureUsages) -> Self {
        self.0 |= usages;
        self
    }
}

#[cfg(test)]
mod test {
    use bevy_math::{Vec2, Vec3};
    use bevy_transform::components::GlobalTransform;

    use crate::{
        Camera, OrthographicProjection, PerspectiveProjection, Projection, RenderTargetInfo,
        Viewport,
    };

    fn make_camera(mut projection: Projection, physical_size: Vec2) -> Camera {
        let viewport = Viewport {
            physical_size: physical_size.as_uvec2(),
            ..Default::default()
        };
        let mut camera = Camera {
            viewport: Some(viewport.clone()),
            ..Default::default()
        };
        camera.computed.target_info = Some(RenderTargetInfo {
            physical_size: viewport.physical_size,
            scale_factor: 1.0,
        });
        projection.update(
            viewport.physical_size.x as f32,
            viewport.physical_size.y as f32,
        );
        camera.computed.clip_from_view = projection.get_clip_from_view();
        camera
    }

    #[test]
    fn viewport_to_world_orthographic_3d_returns_forward() {
        let transform = GlobalTransform::default();
        let size = Vec2::new(1600.0, 900.0);
        let camera = make_camera(
            Projection::Orthographic(OrthographicProjection::default_3d()),
            size,
        );
        let ray = camera.viewport_to_world(&transform, Vec2::ZERO).unwrap();
        assert_eq!(ray.direction, transform.forward());
        assert!(ray
            .origin
            .abs_diff_eq(Vec3::new(-size.x * 0.5, size.y * 0.5, 0.0), 1e-4));
        let ray = camera.viewport_to_world(&transform, size).unwrap();
        assert_eq!(ray.direction, transform.forward());
        assert!(ray
            .origin
            .abs_diff_eq(Vec3::new(size.x * 0.5, -size.y * 0.5, 0.0), 1e-4));
    }

    #[test]
    fn viewport_to_world_orthographic_2d_returns_forward() {
        let transform = GlobalTransform::default();
        let size = Vec2::new(1600.0, 900.0);
        let camera = make_camera(
            Projection::Orthographic(OrthographicProjection::default_2d()),
            size,
        );
        let ray = camera.viewport_to_world(&transform, Vec2::ZERO).unwrap();
        assert_eq!(ray.direction, transform.forward());
        assert!(ray
            .origin
            .abs_diff_eq(Vec3::new(-size.x * 0.5, size.y * 0.5, 1000.0), 1e-4));
        let ray = camera.viewport_to_world(&transform, size).unwrap();
        assert_eq!(ray.direction, transform.forward());
        assert!(ray
            .origin
            .abs_diff_eq(Vec3::new(size.x * 0.5, -size.y * 0.5, 1000.0), 1e-4));
    }

    #[test]
    fn viewport_to_world_perspective_center_returns_forward() {
        let transform = GlobalTransform::default();
        let size = Vec2::new(1600.0, 900.0);
        let camera = make_camera(
            Projection::Perspective(PerspectiveProjection::default()),
            size,
        );
        let ray = camera.viewport_to_world(&transform, size * 0.5).unwrap();
        assert_eq!(ray.direction, transform.forward());
        assert_eq!(ray.origin, transform.forward() * 0.1);
    }
}