From e2f4be94bd100b24811b3563433f806be33688b3 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Mart=C3=ADn=20Andrighetti?= Date: Sun, 27 Oct 2024 19:41:06 -0300 Subject: [PATCH] Improve documentation for the `Mat4` projection functions (#570) * Add detailed docs to the Mat4 projection utility functions --- codegen/templates/mat.rs.tera | 45 +++++++++++++++++++++++++++++------ src/f32/coresimd/mat4.rs | 45 +++++++++++++++++++++++++++++------ src/f32/neon/mat4.rs | 45 +++++++++++++++++++++++++++++------ src/f32/scalar/mat4.rs | 45 +++++++++++++++++++++++++++++------ src/f32/sse2/mat4.rs | 45 +++++++++++++++++++++++++++++------ src/f32/wasm32/mat4.rs | 45 +++++++++++++++++++++++++++++------ src/f64/dmat4.rs | 45 +++++++++++++++++++++++++++++------ 7 files changed, 266 insertions(+), 49 deletions(-) diff --git a/codegen/templates/mat.rs.tera b/codegen/templates/mat.rs.tera index 345353b5..1ad3658a 100644 --- a/codegen/templates/mat.rs.tera +++ b/codegen/templates/mat.rs.tera @@ -1716,7 +1716,10 @@ impl {{ self_t }} { Self::look_to_rh(eye, center.sub(eye), up) } - /// Creates a right-handed perspective projection matrix with [-1,1] depth range. + /// Creates a right-handed perspective projection matrix with `[-1,1]` depth range. + /// + /// Useful to map the standard right-handed coordinate system into what OpenGL expects. + /// /// This is the same as the OpenGL `gluPerspective` function. /// See #[inline] @@ -1742,6 +1745,8 @@ impl {{ self_t }} { /// Creates a left-handed perspective projection matrix with `[0,1]` depth range. /// + /// Useful to map the standard left-handed coordinate system into what WebGPU/Metal/Direct3D expect. + /// /// # Panics /// /// Will panic if `z_near` or `z_far` are less than or equal to zero when `glam_assert` is @@ -1764,6 +1769,8 @@ impl {{ self_t }} { /// Creates a right-handed perspective projection matrix with `[0,1]` depth range. /// + /// Useful to map the standard right-handed coordinate system into what WebGPU/Metal/Direct3D expect. + /// /// # Panics /// /// Will panic if `z_near` or `z_far` are less than or equal to zero when `glam_assert` is @@ -1786,9 +1793,13 @@ impl {{ self_t }} { /// Creates an infinite left-handed perspective projection matrix with `[0,1]` depth range. /// + /// Like `perspective_lh`, but with an infinite value for `z_far`. + /// The result is that points near `z_near` are mapped to depth `0`, and as they move towards infinity the depth approaches `1`. + /// /// # Panics /// - /// Will panic if `z_near` is less than or equal to zero when `glam_assert` is enabled. + /// Will panic if `z_near` or `z_far` are less than or equal to zero when `glam_assert` is + /// enabled. #[inline] #[must_use] pub fn perspective_infinite_lh(fov_y_radians: {{ scalar_t }}, aspect_ratio: {{ scalar_t }}, z_near: {{ scalar_t }}) -> Self { @@ -1804,7 +1815,9 @@ impl {{ self_t }} { ) } - /// Creates an infinite left-handed perspective projection matrix with `[0,1]` depth range. + /// Creates an infinite reverse left-handed perspective projection matrix with `[0,1]` depth range. + /// + /// Similar to `perspective_infinite_lh`, but maps `Z = z_near` to a depth of `1` and `Z = infinity` to a depth of `0`. /// /// # Panics /// @@ -1828,8 +1841,15 @@ impl {{ self_t }} { ) } - /// Creates an infinite right-handed perspective projection matrix with - /// `[0,1]` depth range. + /// Creates an infinite right-handed perspective projection matrix with `[0,1]` depth range. + /// + /// Like `perspective_rh`, but with an infinite value for `z_far`. + /// The result is that points near `z_near` are mapped to depth `0`, and as they move towards infinity the depth approaches `1`. + /// + /// # Panics + /// + /// Will panic if `z_near` or `z_far` are less than or equal to zero when `glam_assert` is + /// enabled. #[inline] #[must_use] pub fn perspective_infinite_rh(fov_y_radians: {{ scalar_t }}, aspect_ratio: {{ scalar_t }}, z_near: {{ scalar_t }}) -> Self { @@ -1843,8 +1863,13 @@ impl {{ self_t }} { ) } - /// Creates an infinite reverse right-handed perspective projection matrix - /// with `[0,1]` depth range. + /// Creates an infinite reverse right-handed perspective projection matrix with `[0,1]` depth range. + /// + /// Similar to `perspective_infinite_rh`, but maps `Z = z_near` to a depth of `1` and `Z = infinity` to a depth of `0`. + /// + /// # Panics + /// + /// Will panic if `z_near` is less than or equal to zero when `glam_assert` is enabled. #[inline] #[must_use] pub fn perspective_infinite_reverse_rh( @@ -1866,6 +1891,8 @@ impl {{ self_t }} { /// range. This is the same as the OpenGL `glOrtho` function in OpenGL. /// See /// + /// + /// Useful to map a right-handed coordinate system to the normalized device coordinates that OpenGL expects. #[inline] #[must_use] pub fn orthographic_rh_gl( @@ -1892,6 +1919,8 @@ impl {{ self_t }} { } /// Creates a left-handed orthographic projection matrix with `[0,1]` depth range. + /// + /// Useful to map a left-handed coordinate system to the normalized device coordinates that WebGPU/Direct3D/Metal expect. #[inline] #[must_use] pub fn orthographic_lh( @@ -1919,6 +1948,8 @@ impl {{ self_t }} { } /// Creates a right-handed orthographic projection matrix with `[0,1]` depth range. + /// + /// Useful to map a right-handed coordinate system to the normalized device coordinates that WebGPU/Direct3D/Metal expect. #[inline] #[must_use] pub fn orthographic_rh( diff --git a/src/f32/coresimd/mat4.rs b/src/f32/coresimd/mat4.rs index 66d212b1..f39c7d81 100644 --- a/src/f32/coresimd/mat4.rs +++ b/src/f32/coresimd/mat4.rs @@ -848,7 +848,10 @@ impl Mat4 { Self::look_to_rh(eye, center.sub(eye), up) } - /// Creates a right-handed perspective projection matrix with [-1,1] depth range. + /// Creates a right-handed perspective projection matrix with `[-1,1]` depth range. + /// + /// Useful to map the standard right-handed coordinate system into what OpenGL expects. + /// /// This is the same as the OpenGL `gluPerspective` function. /// See #[inline] @@ -874,6 +877,8 @@ impl Mat4 { /// Creates a left-handed perspective projection matrix with `[0,1]` depth range. /// + /// Useful to map the standard left-handed coordinate system into what WebGPU/Metal/Direct3D expect. + /// /// # Panics /// /// Will panic if `z_near` or `z_far` are less than or equal to zero when `glam_assert` is @@ -896,6 +901,8 @@ impl Mat4 { /// Creates a right-handed perspective projection matrix with `[0,1]` depth range. /// + /// Useful to map the standard right-handed coordinate system into what WebGPU/Metal/Direct3D expect. + /// /// # Panics /// /// Will panic if `z_near` or `z_far` are less than or equal to zero when `glam_assert` is @@ -918,9 +925,13 @@ impl Mat4 { /// Creates an infinite left-handed perspective projection matrix with `[0,1]` depth range. /// + /// Like `perspective_lh`, but with an infinite value for `z_far`. + /// The result is that points near `z_near` are mapped to depth `0`, and as they move towards infinity the depth approaches `1`. + /// /// # Panics /// - /// Will panic if `z_near` is less than or equal to zero when `glam_assert` is enabled. + /// Will panic if `z_near` or `z_far` are less than or equal to zero when `glam_assert` is + /// enabled. #[inline] #[must_use] pub fn perspective_infinite_lh(fov_y_radians: f32, aspect_ratio: f32, z_near: f32) -> Self { @@ -936,7 +947,9 @@ impl Mat4 { ) } - /// Creates an infinite left-handed perspective projection matrix with `[0,1]` depth range. + /// Creates an infinite reverse left-handed perspective projection matrix with `[0,1]` depth range. + /// + /// Similar to `perspective_infinite_lh`, but maps `Z = z_near` to a depth of `1` and `Z = infinity` to a depth of `0`. /// /// # Panics /// @@ -960,8 +973,15 @@ impl Mat4 { ) } - /// Creates an infinite right-handed perspective projection matrix with - /// `[0,1]` depth range. + /// Creates an infinite right-handed perspective projection matrix with `[0,1]` depth range. + /// + /// Like `perspective_rh`, but with an infinite value for `z_far`. + /// The result is that points near `z_near` are mapped to depth `0`, and as they move towards infinity the depth approaches `1`. + /// + /// # Panics + /// + /// Will panic if `z_near` or `z_far` are less than or equal to zero when `glam_assert` is + /// enabled. #[inline] #[must_use] pub fn perspective_infinite_rh(fov_y_radians: f32, aspect_ratio: f32, z_near: f32) -> Self { @@ -975,8 +995,13 @@ impl Mat4 { ) } - /// Creates an infinite reverse right-handed perspective projection matrix - /// with `[0,1]` depth range. + /// Creates an infinite reverse right-handed perspective projection matrix with `[0,1]` depth range. + /// + /// Similar to `perspective_infinite_rh`, but maps `Z = z_near` to a depth of `1` and `Z = infinity` to a depth of `0`. + /// + /// # Panics + /// + /// Will panic if `z_near` is less than or equal to zero when `glam_assert` is enabled. #[inline] #[must_use] pub fn perspective_infinite_reverse_rh( @@ -998,6 +1023,8 @@ impl Mat4 { /// range. This is the same as the OpenGL `glOrtho` function in OpenGL. /// See /// + /// + /// Useful to map a right-handed coordinate system to the normalized device coordinates that OpenGL expects. #[inline] #[must_use] pub fn orthographic_rh_gl( @@ -1024,6 +1051,8 @@ impl Mat4 { } /// Creates a left-handed orthographic projection matrix with `[0,1]` depth range. + /// + /// Useful to map a left-handed coordinate system to the normalized device coordinates that WebGPU/Direct3D/Metal expect. #[inline] #[must_use] pub fn orthographic_lh( @@ -1051,6 +1080,8 @@ impl Mat4 { } /// Creates a right-handed orthographic projection matrix with `[0,1]` depth range. + /// + /// Useful to map a right-handed coordinate system to the normalized device coordinates that WebGPU/Direct3D/Metal expect. #[inline] #[must_use] pub fn orthographic_rh( diff --git a/src/f32/neon/mat4.rs b/src/f32/neon/mat4.rs index a56526c1..d8a16ecb 100644 --- a/src/f32/neon/mat4.rs +++ b/src/f32/neon/mat4.rs @@ -853,7 +853,10 @@ impl Mat4 { Self::look_to_rh(eye, center.sub(eye), up) } - /// Creates a right-handed perspective projection matrix with [-1,1] depth range. + /// Creates a right-handed perspective projection matrix with `[-1,1]` depth range. + /// + /// Useful to map the standard right-handed coordinate system into what OpenGL expects. + /// /// This is the same as the OpenGL `gluPerspective` function. /// See #[inline] @@ -879,6 +882,8 @@ impl Mat4 { /// Creates a left-handed perspective projection matrix with `[0,1]` depth range. /// + /// Useful to map the standard left-handed coordinate system into what WebGPU/Metal/Direct3D expect. + /// /// # Panics /// /// Will panic if `z_near` or `z_far` are less than or equal to zero when `glam_assert` is @@ -901,6 +906,8 @@ impl Mat4 { /// Creates a right-handed perspective projection matrix with `[0,1]` depth range. /// + /// Useful to map the standard right-handed coordinate system into what WebGPU/Metal/Direct3D expect. + /// /// # Panics /// /// Will panic if `z_near` or `z_far` are less than or equal to zero when `glam_assert` is @@ -923,9 +930,13 @@ impl Mat4 { /// Creates an infinite left-handed perspective projection matrix with `[0,1]` depth range. /// + /// Like `perspective_lh`, but with an infinite value for `z_far`. + /// The result is that points near `z_near` are mapped to depth `0`, and as they move towards infinity the depth approaches `1`. + /// /// # Panics /// - /// Will panic if `z_near` is less than or equal to zero when `glam_assert` is enabled. + /// Will panic if `z_near` or `z_far` are less than or equal to zero when `glam_assert` is + /// enabled. #[inline] #[must_use] pub fn perspective_infinite_lh(fov_y_radians: f32, aspect_ratio: f32, z_near: f32) -> Self { @@ -941,7 +952,9 @@ impl Mat4 { ) } - /// Creates an infinite left-handed perspective projection matrix with `[0,1]` depth range. + /// Creates an infinite reverse left-handed perspective projection matrix with `[0,1]` depth range. + /// + /// Similar to `perspective_infinite_lh`, but maps `Z = z_near` to a depth of `1` and `Z = infinity` to a depth of `0`. /// /// # Panics /// @@ -965,8 +978,15 @@ impl Mat4 { ) } - /// Creates an infinite right-handed perspective projection matrix with - /// `[0,1]` depth range. + /// Creates an infinite right-handed perspective projection matrix with `[0,1]` depth range. + /// + /// Like `perspective_rh`, but with an infinite value for `z_far`. + /// The result is that points near `z_near` are mapped to depth `0`, and as they move towards infinity the depth approaches `1`. + /// + /// # Panics + /// + /// Will panic if `z_near` or `z_far` are less than or equal to zero when `glam_assert` is + /// enabled. #[inline] #[must_use] pub fn perspective_infinite_rh(fov_y_radians: f32, aspect_ratio: f32, z_near: f32) -> Self { @@ -980,8 +1000,13 @@ impl Mat4 { ) } - /// Creates an infinite reverse right-handed perspective projection matrix - /// with `[0,1]` depth range. + /// Creates an infinite reverse right-handed perspective projection matrix with `[0,1]` depth range. + /// + /// Similar to `perspective_infinite_rh`, but maps `Z = z_near` to a depth of `1` and `Z = infinity` to a depth of `0`. + /// + /// # Panics + /// + /// Will panic if `z_near` is less than or equal to zero when `glam_assert` is enabled. #[inline] #[must_use] pub fn perspective_infinite_reverse_rh( @@ -1003,6 +1028,8 @@ impl Mat4 { /// range. This is the same as the OpenGL `glOrtho` function in OpenGL. /// See /// + /// + /// Useful to map a right-handed coordinate system to the normalized device coordinates that OpenGL expects. #[inline] #[must_use] pub fn orthographic_rh_gl( @@ -1029,6 +1056,8 @@ impl Mat4 { } /// Creates a left-handed orthographic projection matrix with `[0,1]` depth range. + /// + /// Useful to map a left-handed coordinate system to the normalized device coordinates that WebGPU/Direct3D/Metal expect. #[inline] #[must_use] pub fn orthographic_lh( @@ -1056,6 +1085,8 @@ impl Mat4 { } /// Creates a right-handed orthographic projection matrix with `[0,1]` depth range. + /// + /// Useful to map a right-handed coordinate system to the normalized device coordinates that WebGPU/Direct3D/Metal expect. #[inline] #[must_use] pub fn orthographic_rh( diff --git a/src/f32/scalar/mat4.rs b/src/f32/scalar/mat4.rs index ccbc96d8..490de463 100644 --- a/src/f32/scalar/mat4.rs +++ b/src/f32/scalar/mat4.rs @@ -770,7 +770,10 @@ impl Mat4 { Self::look_to_rh(eye, center.sub(eye), up) } - /// Creates a right-handed perspective projection matrix with [-1,1] depth range. + /// Creates a right-handed perspective projection matrix with `[-1,1]` depth range. + /// + /// Useful to map the standard right-handed coordinate system into what OpenGL expects. + /// /// This is the same as the OpenGL `gluPerspective` function. /// See #[inline] @@ -796,6 +799,8 @@ impl Mat4 { /// Creates a left-handed perspective projection matrix with `[0,1]` depth range. /// + /// Useful to map the standard left-handed coordinate system into what WebGPU/Metal/Direct3D expect. + /// /// # Panics /// /// Will panic if `z_near` or `z_far` are less than or equal to zero when `glam_assert` is @@ -818,6 +823,8 @@ impl Mat4 { /// Creates a right-handed perspective projection matrix with `[0,1]` depth range. /// + /// Useful to map the standard right-handed coordinate system into what WebGPU/Metal/Direct3D expect. + /// /// # Panics /// /// Will panic if `z_near` or `z_far` are less than or equal to zero when `glam_assert` is @@ -840,9 +847,13 @@ impl Mat4 { /// Creates an infinite left-handed perspective projection matrix with `[0,1]` depth range. /// + /// Like `perspective_lh`, but with an infinite value for `z_far`. + /// The result is that points near `z_near` are mapped to depth `0`, and as they move towards infinity the depth approaches `1`. + /// /// # Panics /// - /// Will panic if `z_near` is less than or equal to zero when `glam_assert` is enabled. + /// Will panic if `z_near` or `z_far` are less than or equal to zero when `glam_assert` is + /// enabled. #[inline] #[must_use] pub fn perspective_infinite_lh(fov_y_radians: f32, aspect_ratio: f32, z_near: f32) -> Self { @@ -858,7 +869,9 @@ impl Mat4 { ) } - /// Creates an infinite left-handed perspective projection matrix with `[0,1]` depth range. + /// Creates an infinite reverse left-handed perspective projection matrix with `[0,1]` depth range. + /// + /// Similar to `perspective_infinite_lh`, but maps `Z = z_near` to a depth of `1` and `Z = infinity` to a depth of `0`. /// /// # Panics /// @@ -882,8 +895,15 @@ impl Mat4 { ) } - /// Creates an infinite right-handed perspective projection matrix with - /// `[0,1]` depth range. + /// Creates an infinite right-handed perspective projection matrix with `[0,1]` depth range. + /// + /// Like `perspective_rh`, but with an infinite value for `z_far`. + /// The result is that points near `z_near` are mapped to depth `0`, and as they move towards infinity the depth approaches `1`. + /// + /// # Panics + /// + /// Will panic if `z_near` or `z_far` are less than or equal to zero when `glam_assert` is + /// enabled. #[inline] #[must_use] pub fn perspective_infinite_rh(fov_y_radians: f32, aspect_ratio: f32, z_near: f32) -> Self { @@ -897,8 +917,13 @@ impl Mat4 { ) } - /// Creates an infinite reverse right-handed perspective projection matrix - /// with `[0,1]` depth range. + /// Creates an infinite reverse right-handed perspective projection matrix with `[0,1]` depth range. + /// + /// Similar to `perspective_infinite_rh`, but maps `Z = z_near` to a depth of `1` and `Z = infinity` to a depth of `0`. + /// + /// # Panics + /// + /// Will panic if `z_near` is less than or equal to zero when `glam_assert` is enabled. #[inline] #[must_use] pub fn perspective_infinite_reverse_rh( @@ -920,6 +945,8 @@ impl Mat4 { /// range. This is the same as the OpenGL `glOrtho` function in OpenGL. /// See /// + /// + /// Useful to map a right-handed coordinate system to the normalized device coordinates that OpenGL expects. #[inline] #[must_use] pub fn orthographic_rh_gl( @@ -946,6 +973,8 @@ impl Mat4 { } /// Creates a left-handed orthographic projection matrix with `[0,1]` depth range. + /// + /// Useful to map a left-handed coordinate system to the normalized device coordinates that WebGPU/Direct3D/Metal expect. #[inline] #[must_use] pub fn orthographic_lh( @@ -973,6 +1002,8 @@ impl Mat4 { } /// Creates a right-handed orthographic projection matrix with `[0,1]` depth range. + /// + /// Useful to map a right-handed coordinate system to the normalized device coordinates that WebGPU/Direct3D/Metal expect. #[inline] #[must_use] pub fn orthographic_rh( diff --git a/src/f32/sse2/mat4.rs b/src/f32/sse2/mat4.rs index cef52bc0..88db90f6 100644 --- a/src/f32/sse2/mat4.rs +++ b/src/f32/sse2/mat4.rs @@ -857,7 +857,10 @@ impl Mat4 { Self::look_to_rh(eye, center.sub(eye), up) } - /// Creates a right-handed perspective projection matrix with [-1,1] depth range. + /// Creates a right-handed perspective projection matrix with `[-1,1]` depth range. + /// + /// Useful to map the standard right-handed coordinate system into what OpenGL expects. + /// /// This is the same as the OpenGL `gluPerspective` function. /// See #[inline] @@ -883,6 +886,8 @@ impl Mat4 { /// Creates a left-handed perspective projection matrix with `[0,1]` depth range. /// + /// Useful to map the standard left-handed coordinate system into what WebGPU/Metal/Direct3D expect. + /// /// # Panics /// /// Will panic if `z_near` or `z_far` are less than or equal to zero when `glam_assert` is @@ -905,6 +910,8 @@ impl Mat4 { /// Creates a right-handed perspective projection matrix with `[0,1]` depth range. /// + /// Useful to map the standard right-handed coordinate system into what WebGPU/Metal/Direct3D expect. + /// /// # Panics /// /// Will panic if `z_near` or `z_far` are less than or equal to zero when `glam_assert` is @@ -927,9 +934,13 @@ impl Mat4 { /// Creates an infinite left-handed perspective projection matrix with `[0,1]` depth range. /// + /// Like `perspective_lh`, but with an infinite value for `z_far`. + /// The result is that points near `z_near` are mapped to depth `0`, and as they move towards infinity the depth approaches `1`. + /// /// # Panics /// - /// Will panic if `z_near` is less than or equal to zero when `glam_assert` is enabled. + /// Will panic if `z_near` or `z_far` are less than or equal to zero when `glam_assert` is + /// enabled. #[inline] #[must_use] pub fn perspective_infinite_lh(fov_y_radians: f32, aspect_ratio: f32, z_near: f32) -> Self { @@ -945,7 +956,9 @@ impl Mat4 { ) } - /// Creates an infinite left-handed perspective projection matrix with `[0,1]` depth range. + /// Creates an infinite reverse left-handed perspective projection matrix with `[0,1]` depth range. + /// + /// Similar to `perspective_infinite_lh`, but maps `Z = z_near` to a depth of `1` and `Z = infinity` to a depth of `0`. /// /// # Panics /// @@ -969,8 +982,15 @@ impl Mat4 { ) } - /// Creates an infinite right-handed perspective projection matrix with - /// `[0,1]` depth range. + /// Creates an infinite right-handed perspective projection matrix with `[0,1]` depth range. + /// + /// Like `perspective_rh`, but with an infinite value for `z_far`. + /// The result is that points near `z_near` are mapped to depth `0`, and as they move towards infinity the depth approaches `1`. + /// + /// # Panics + /// + /// Will panic if `z_near` or `z_far` are less than or equal to zero when `glam_assert` is + /// enabled. #[inline] #[must_use] pub fn perspective_infinite_rh(fov_y_radians: f32, aspect_ratio: f32, z_near: f32) -> Self { @@ -984,8 +1004,13 @@ impl Mat4 { ) } - /// Creates an infinite reverse right-handed perspective projection matrix - /// with `[0,1]` depth range. + /// Creates an infinite reverse right-handed perspective projection matrix with `[0,1]` depth range. + /// + /// Similar to `perspective_infinite_rh`, but maps `Z = z_near` to a depth of `1` and `Z = infinity` to a depth of `0`. + /// + /// # Panics + /// + /// Will panic if `z_near` is less than or equal to zero when `glam_assert` is enabled. #[inline] #[must_use] pub fn perspective_infinite_reverse_rh( @@ -1007,6 +1032,8 @@ impl Mat4 { /// range. This is the same as the OpenGL `glOrtho` function in OpenGL. /// See /// + /// + /// Useful to map a right-handed coordinate system to the normalized device coordinates that OpenGL expects. #[inline] #[must_use] pub fn orthographic_rh_gl( @@ -1033,6 +1060,8 @@ impl Mat4 { } /// Creates a left-handed orthographic projection matrix with `[0,1]` depth range. + /// + /// Useful to map a left-handed coordinate system to the normalized device coordinates that WebGPU/Direct3D/Metal expect. #[inline] #[must_use] pub fn orthographic_lh( @@ -1060,6 +1089,8 @@ impl Mat4 { } /// Creates a right-handed orthographic projection matrix with `[0,1]` depth range. + /// + /// Useful to map a right-handed coordinate system to the normalized device coordinates that WebGPU/Direct3D/Metal expect. #[inline] #[must_use] pub fn orthographic_rh( diff --git a/src/f32/wasm32/mat4.rs b/src/f32/wasm32/mat4.rs index be87ac95..43df8165 100644 --- a/src/f32/wasm32/mat4.rs +++ b/src/f32/wasm32/mat4.rs @@ -848,7 +848,10 @@ impl Mat4 { Self::look_to_rh(eye, center.sub(eye), up) } - /// Creates a right-handed perspective projection matrix with [-1,1] depth range. + /// Creates a right-handed perspective projection matrix with `[-1,1]` depth range. + /// + /// Useful to map the standard right-handed coordinate system into what OpenGL expects. + /// /// This is the same as the OpenGL `gluPerspective` function. /// See #[inline] @@ -874,6 +877,8 @@ impl Mat4 { /// Creates a left-handed perspective projection matrix with `[0,1]` depth range. /// + /// Useful to map the standard left-handed coordinate system into what WebGPU/Metal/Direct3D expect. + /// /// # Panics /// /// Will panic if `z_near` or `z_far` are less than or equal to zero when `glam_assert` is @@ -896,6 +901,8 @@ impl Mat4 { /// Creates a right-handed perspective projection matrix with `[0,1]` depth range. /// + /// Useful to map the standard right-handed coordinate system into what WebGPU/Metal/Direct3D expect. + /// /// # Panics /// /// Will panic if `z_near` or `z_far` are less than or equal to zero when `glam_assert` is @@ -918,9 +925,13 @@ impl Mat4 { /// Creates an infinite left-handed perspective projection matrix with `[0,1]` depth range. /// + /// Like `perspective_lh`, but with an infinite value for `z_far`. + /// The result is that points near `z_near` are mapped to depth `0`, and as they move towards infinity the depth approaches `1`. + /// /// # Panics /// - /// Will panic if `z_near` is less than or equal to zero when `glam_assert` is enabled. + /// Will panic if `z_near` or `z_far` are less than or equal to zero when `glam_assert` is + /// enabled. #[inline] #[must_use] pub fn perspective_infinite_lh(fov_y_radians: f32, aspect_ratio: f32, z_near: f32) -> Self { @@ -936,7 +947,9 @@ impl Mat4 { ) } - /// Creates an infinite left-handed perspective projection matrix with `[0,1]` depth range. + /// Creates an infinite reverse left-handed perspective projection matrix with `[0,1]` depth range. + /// + /// Similar to `perspective_infinite_lh`, but maps `Z = z_near` to a depth of `1` and `Z = infinity` to a depth of `0`. /// /// # Panics /// @@ -960,8 +973,15 @@ impl Mat4 { ) } - /// Creates an infinite right-handed perspective projection matrix with - /// `[0,1]` depth range. + /// Creates an infinite right-handed perspective projection matrix with `[0,1]` depth range. + /// + /// Like `perspective_rh`, but with an infinite value for `z_far`. + /// The result is that points near `z_near` are mapped to depth `0`, and as they move towards infinity the depth approaches `1`. + /// + /// # Panics + /// + /// Will panic if `z_near` or `z_far` are less than or equal to zero when `glam_assert` is + /// enabled. #[inline] #[must_use] pub fn perspective_infinite_rh(fov_y_radians: f32, aspect_ratio: f32, z_near: f32) -> Self { @@ -975,8 +995,13 @@ impl Mat4 { ) } - /// Creates an infinite reverse right-handed perspective projection matrix - /// with `[0,1]` depth range. + /// Creates an infinite reverse right-handed perspective projection matrix with `[0,1]` depth range. + /// + /// Similar to `perspective_infinite_rh`, but maps `Z = z_near` to a depth of `1` and `Z = infinity` to a depth of `0`. + /// + /// # Panics + /// + /// Will panic if `z_near` is less than or equal to zero when `glam_assert` is enabled. #[inline] #[must_use] pub fn perspective_infinite_reverse_rh( @@ -998,6 +1023,8 @@ impl Mat4 { /// range. This is the same as the OpenGL `glOrtho` function in OpenGL. /// See /// + /// + /// Useful to map a right-handed coordinate system to the normalized device coordinates that OpenGL expects. #[inline] #[must_use] pub fn orthographic_rh_gl( @@ -1024,6 +1051,8 @@ impl Mat4 { } /// Creates a left-handed orthographic projection matrix with `[0,1]` depth range. + /// + /// Useful to map a left-handed coordinate system to the normalized device coordinates that WebGPU/Direct3D/Metal expect. #[inline] #[must_use] pub fn orthographic_lh( @@ -1051,6 +1080,8 @@ impl Mat4 { } /// Creates a right-handed orthographic projection matrix with `[0,1]` depth range. + /// + /// Useful to map a right-handed coordinate system to the normalized device coordinates that WebGPU/Direct3D/Metal expect. #[inline] #[must_use] pub fn orthographic_rh( diff --git a/src/f64/dmat4.rs b/src/f64/dmat4.rs index e8cb013a..119b316e 100644 --- a/src/f64/dmat4.rs +++ b/src/f64/dmat4.rs @@ -752,7 +752,10 @@ impl DMat4 { Self::look_to_rh(eye, center.sub(eye), up) } - /// Creates a right-handed perspective projection matrix with [-1,1] depth range. + /// Creates a right-handed perspective projection matrix with `[-1,1]` depth range. + /// + /// Useful to map the standard right-handed coordinate system into what OpenGL expects. + /// /// This is the same as the OpenGL `gluPerspective` function. /// See #[inline] @@ -778,6 +781,8 @@ impl DMat4 { /// Creates a left-handed perspective projection matrix with `[0,1]` depth range. /// + /// Useful to map the standard left-handed coordinate system into what WebGPU/Metal/Direct3D expect. + /// /// # Panics /// /// Will panic if `z_near` or `z_far` are less than or equal to zero when `glam_assert` is @@ -800,6 +805,8 @@ impl DMat4 { /// Creates a right-handed perspective projection matrix with `[0,1]` depth range. /// + /// Useful to map the standard right-handed coordinate system into what WebGPU/Metal/Direct3D expect. + /// /// # Panics /// /// Will panic if `z_near` or `z_far` are less than or equal to zero when `glam_assert` is @@ -822,9 +829,13 @@ impl DMat4 { /// Creates an infinite left-handed perspective projection matrix with `[0,1]` depth range. /// + /// Like `perspective_lh`, but with an infinite value for `z_far`. + /// The result is that points near `z_near` are mapped to depth `0`, and as they move towards infinity the depth approaches `1`. + /// /// # Panics /// - /// Will panic if `z_near` is less than or equal to zero when `glam_assert` is enabled. + /// Will panic if `z_near` or `z_far` are less than or equal to zero when `glam_assert` is + /// enabled. #[inline] #[must_use] pub fn perspective_infinite_lh(fov_y_radians: f64, aspect_ratio: f64, z_near: f64) -> Self { @@ -840,7 +851,9 @@ impl DMat4 { ) } - /// Creates an infinite left-handed perspective projection matrix with `[0,1]` depth range. + /// Creates an infinite reverse left-handed perspective projection matrix with `[0,1]` depth range. + /// + /// Similar to `perspective_infinite_lh`, but maps `Z = z_near` to a depth of `1` and `Z = infinity` to a depth of `0`. /// /// # Panics /// @@ -864,8 +877,15 @@ impl DMat4 { ) } - /// Creates an infinite right-handed perspective projection matrix with - /// `[0,1]` depth range. + /// Creates an infinite right-handed perspective projection matrix with `[0,1]` depth range. + /// + /// Like `perspective_rh`, but with an infinite value for `z_far`. + /// The result is that points near `z_near` are mapped to depth `0`, and as they move towards infinity the depth approaches `1`. + /// + /// # Panics + /// + /// Will panic if `z_near` or `z_far` are less than or equal to zero when `glam_assert` is + /// enabled. #[inline] #[must_use] pub fn perspective_infinite_rh(fov_y_radians: f64, aspect_ratio: f64, z_near: f64) -> Self { @@ -879,8 +899,13 @@ impl DMat4 { ) } - /// Creates an infinite reverse right-handed perspective projection matrix - /// with `[0,1]` depth range. + /// Creates an infinite reverse right-handed perspective projection matrix with `[0,1]` depth range. + /// + /// Similar to `perspective_infinite_rh`, but maps `Z = z_near` to a depth of `1` and `Z = infinity` to a depth of `0`. + /// + /// # Panics + /// + /// Will panic if `z_near` is less than or equal to zero when `glam_assert` is enabled. #[inline] #[must_use] pub fn perspective_infinite_reverse_rh( @@ -902,6 +927,8 @@ impl DMat4 { /// range. This is the same as the OpenGL `glOrtho` function in OpenGL. /// See /// + /// + /// Useful to map a right-handed coordinate system to the normalized device coordinates that OpenGL expects. #[inline] #[must_use] pub fn orthographic_rh_gl( @@ -928,6 +955,8 @@ impl DMat4 { } /// Creates a left-handed orthographic projection matrix with `[0,1]` depth range. + /// + /// Useful to map a left-handed coordinate system to the normalized device coordinates that WebGPU/Direct3D/Metal expect. #[inline] #[must_use] pub fn orthographic_lh( @@ -955,6 +984,8 @@ impl DMat4 { } /// Creates a right-handed orthographic projection matrix with `[0,1]` depth range. + /// + /// Useful to map a right-handed coordinate system to the normalized device coordinates that WebGPU/Direct3D/Metal expect. #[inline] #[must_use] pub fn orthographic_rh(