From e1d592f1ac2d29463a5a1474e7ae552ccb3cbaa2 Mon Sep 17 00:00:00 2001 From: "Tormod G. Hellen" Date: Wed, 14 Jun 2023 19:28:01 +0200 Subject: [PATCH] Document when Camera::viewport_to_world and related methods return None --- crates/bevy_render/src/camera/camera.rs | 41 +++++++++++++++++++++++++ 1 file changed, 41 insertions(+) diff --git a/crates/bevy_render/src/camera/camera.rs b/crates/bevy_render/src/camera/camera.rs index da0e4818ae216c..daa4d86f21795e 100644 --- a/crates/bevy_render/src/camera/camera.rs +++ b/crates/bevy_render/src/camera/camera.rs @@ -170,6 +170,10 @@ impl Camera { /// of the current [`RenderTarget`]. /// For logic that requires the full logical size of the /// [`RenderTarget`], prefer [`Camera::logical_target_size`]. + /// + /// Returns None if both: + /// - The viewport is not set + /// - The render target is not set #[inline] pub fn logical_viewport_size(&self) -> Option { self.viewport @@ -219,6 +223,15 @@ impl Camera { /// /// To get the coordinates in Normalized Device Coordinates, you should use /// [`world_to_ndc`](Self::world_to_ndc). + /// + /// Returns None if any of these conditions occur: + /// - The logical viewport size cannot be computed. This can happen if both: + /// - The viewport is not set + /// - The render target is not set + /// - The projection matrix is invalid + /// - The camera transform is invalid or cannot be inverted + /// - The world position is invalid + /// - The computed coordinates are beyond the near or far plane #[doc(alias = "world_to_screen")] pub fn world_to_viewport( &self, @@ -247,6 +260,15 @@ impl Camera { /// /// To get the world space coordinates with Normalized Device Coordinates, you should use /// [`ndc_to_world`](Self::ndc_to_world). + /// + /// Returns None if any of these conditions occur: + /// - The logical viewport size cannot be computed. This can happen if both: + /// - The viewport is not set + /// - The render target is not set + /// - The near or far plane cannot be computed. This can happen if: + /// - The projection matrix is invalid or cannot be inverted + /// - The camera transform is invalid + /// - The viewport position is invalid pub fn viewport_to_world( &self, camera_transform: &GlobalTransform, @@ -275,6 +297,15 @@ impl Camera { /// /// To get the world space coordinates with Normalized Device Coordinates, you should use /// [`ndc_to_world`](Self::ndc_to_world). + /// + /// Returns None if any of these conditions occur: + /// - The logical viewport size cannot be computed. This can happen if both: + /// - The viewport is not set + /// - The render target is not set + /// - The viewport position cannot be mapped to the world. This can happen if: + /// - The projection matrix is invalid or cannot be inverted + /// - The camera transform is invalid + /// - The viewport position is invalid pub fn viewport_to_world_2d( &self, camera_transform: &GlobalTransform, @@ -296,6 +327,11 @@ impl Camera { /// and between 0.0 and 1.0 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 any of these conditions occur: + /// - The projection matrix is invalid + /// - The camera transform is invalid or cannot be inverted + /// - The world position is invalid pub fn world_to_ndc( &self, camera_transform: &GlobalTransform, @@ -316,6 +352,11 @@ impl Camera { /// and between 0.0 and 1.0 on the Z axis. /// To get the world space coordinates with the viewport position, you should use /// [`world_to_viewport`](Self::world_to_viewport). + /// + /// Returns None if any of these conditions occur: + /// - The projection matrix is invalid or cannot be inverted + /// - The camera transform is invalid + /// - The ndc is invalid pub fn ndc_to_world(&self, camera_transform: &GlobalTransform, ndc: Vec3) -> Option { // Build a transformation matrix to convert from NDC to world space using camera data let ndc_to_world =