glam/camera/lh/
proj.rs

1// Generated from camera_proj.rs.tera template. Edit the template, not the generated file.
2
3//! Projection matrix constructors.
4//!
5//! Expects left-handed Y-up view space input.
6//!
7//! Each sub-module targets a specific graphics API convention:
8//!
9//! * [`opengl`] - NDC Z range **[-1, 1]**, Y-up
10//! * [`directx`] - NDC Z range **[0, 1]**, Y-up
11//! * [`vulkan`] - NDC Z range **[0, 1]**, Y-down
12
13#[doc(alias = "webgl")]
14pub mod opengl {
15    //! OpenGL NDC convention: Z range **[-1, 1]**, Y-up.
16    //!
17    //! Expects a left-handed Y-up view space input.
18
19    use crate::{camera::camera_impl, Mat4};
20
21    /// Creates a perspective projection matrix for use with OpenGL.
22    ///
23    /// Expects a left-handed Y-up view space input.
24    /// Outputs NDC with Z in [-1, 1] and Y-up.
25    ///
26    /// # Panics
27    ///
28    /// Will panic if `vertical_fov` is not in the range `(0, π)`, if `aspect_ratio` is
29    /// zero, or if `near` or `far` are less than or equal to zero, or if `near` is equal to
30    /// `far`, when `glam_assert` is enabled.
31    #[inline]
32    #[must_use]
33    #[cfg_attr(any(debug_assertions, feature = "glam-assert"), track_caller)]
34    pub fn perspective(vertical_fov: f32, aspect_ratio: f32, near: f32, far: f32) -> Mat4 {
35        camera_impl::perspective::<false, false, false>(vertical_fov, aspect_ratio, near, far)
36    }
37
38    /// Creates an orthographic projection matrix for use with OpenGL.
39    ///
40    /// Expects a left-handed Y-up view space input.
41    /// Outputs NDC with Z in [-1, 1] and Y-up.
42    ///
43    /// # Panics
44    ///
45    /// Will panic if `left` is equal to `right`, if `bottom` is equal to
46    /// `top`, or if `near` is equal to `far` when `glam_assert` is enabled.
47    #[inline]
48    #[must_use]
49    #[cfg_attr(any(debug_assertions, feature = "glam-assert"), track_caller)]
50    pub fn orthographic(left: f32, right: f32, bottom: f32, top: f32, near: f32, far: f32) -> Mat4 {
51        camera_impl::orthographic::<false, false, false>(left, right, bottom, top, near, far)
52    }
53
54    /// Creates a perspective projection matrix from a frustum for use with OpenGL.
55    ///
56    /// Expects a left-handed Y-up view space input.
57    /// Outputs NDC with Z in [-1, 1] and Y-up.
58    ///
59    /// # Panics
60    ///
61    /// Will panic if `left` is equal to `right`, if `bottom` is equal to
62    /// `top`, or if `near` or `far` are less than or equal to zero, or if `near` is
63    /// equal to `far`, when `glam_assert` is enabled.
64    #[inline]
65    #[must_use]
66    #[cfg_attr(any(debug_assertions, feature = "glam-assert"), track_caller)]
67    pub fn frustum(left: f32, right: f32, bottom: f32, top: f32, near: f32, far: f32) -> Mat4 {
68        camera_impl::frustum::<false, false, false>(left, right, bottom, top, near, far)
69    }
70}
71
72pub mod vulkan {
73    //! Vulkan NDC convention: Z range **[0, 1]**, Y-down.
74    //!
75    //! Expects a left-handed Y-up view space input.
76    //!
77    //! Includes standard, infinite-far, and reverse-depth variants.
78
79    use crate::{camera::camera_impl, Mat4};
80
81    /// Creates a perspective projection matrix for use with Vulkan.
82    ///
83    /// Expects a left-handed Y-up view space input.
84    /// Outputs NDC with Z in [0, 1] and Y-down.
85    ///
86    /// # Panics
87    ///
88    /// Will panic if `vertical_fov` is not in the range `(0, π)`, if `aspect_ratio` is
89    /// zero, or if `near` or `far` are less than or equal to zero, or if `near` is equal to
90    /// `far`, when `glam_assert` is enabled.
91    #[inline]
92    #[must_use]
93    #[cfg_attr(any(debug_assertions, feature = "glam-assert"), track_caller)]
94    pub fn perspective(vertical_fov: f32, aspect_ratio: f32, near: f32, far: f32) -> Mat4 {
95        camera_impl::perspective::<false, true, true>(vertical_fov, aspect_ratio, near, far)
96    }
97
98    /// Creates an infinite perspective projection matrix for use with Vulkan.
99    ///
100    /// Like `perspective`, but with an infinite value for `far`. Points at distance
101    /// `near` map to depth `0`; as distance approaches infinity, depth approaches `1`.
102    ///
103    /// Expects a left-handed Y-up view space input.
104    /// Outputs NDC with Z in [0, 1] and Y-down.
105    ///
106    /// # Panics
107    ///
108    /// Will panic if `vertical_fov` is not in the range `(0, π)`, if `aspect_ratio` is
109    /// zero, or if `near` is less than or equal to zero when `glam_assert` is enabled.
110    #[inline]
111    #[must_use]
112    #[cfg_attr(any(debug_assertions, feature = "glam-assert"), track_caller)]
113    pub fn perspective_infinite(vertical_fov: f32, aspect_ratio: f32, near: f32) -> Mat4 {
114        camera_impl::perspective_infinite::<false, true, true>(vertical_fov, aspect_ratio, near)
115    }
116
117    /// Creates an infinite perspective projection matrix with reversed depth for use with
118    /// Vulkan.
119    ///
120    /// Maps `near` to depth `1` and infinity to depth `0`.
121    ///
122    /// Reversed Z improves depth precision when used with a floating-point depth buffer.
123    ///
124    /// Expects a left-handed Y-up view space input.
125    /// Outputs NDC with Z in [0, 1] and Y-down.
126    ///
127    /// # Panics
128    ///
129    /// Will panic if `vertical_fov` is not in the range `(0, π)`, if `aspect_ratio` is
130    /// zero, or if `near` is less than or equal to zero when `glam_assert` is enabled.
131    #[inline]
132    #[must_use]
133    #[cfg_attr(any(debug_assertions, feature = "glam-assert"), track_caller)]
134    pub fn perspective_infinite_reverse(vertical_fov: f32, aspect_ratio: f32, near: f32) -> Mat4 {
135        camera_impl::perspective_infinite_reverse::<false, true>(vertical_fov, aspect_ratio, near)
136    }
137
138    /// Creates an orthographic projection matrix for use with Vulkan.
139    ///
140    /// Expects a left-handed Y-up view space input.
141    /// Outputs NDC with Z in [0, 1] and Y-down.
142    ///
143    /// # Panics
144    ///
145    /// Will panic if `left` is equal to `right`, if `bottom` is equal to
146    /// `top`, or if `near` is equal to `far` when `glam_assert` is enabled.
147    #[inline]
148    #[must_use]
149    #[cfg_attr(any(debug_assertions, feature = "glam-assert"), track_caller)]
150    pub fn orthographic(left: f32, right: f32, bottom: f32, top: f32, near: f32, far: f32) -> Mat4 {
151        camera_impl::orthographic::<false, true, true>(left, right, bottom, top, near, far)
152    }
153
154    /// Creates a perspective projection from a frustum for use with Vulkan.
155    ///
156    /// Expects a left-handed Y-up view space input.
157    /// Outputs NDC with Z in [0, 1] and Y-down.
158    ///
159    /// # Panics
160    ///
161    /// Will panic if `left` is equal to `right`, if `bottom` is equal to
162    /// `top`, or if `near` or `far` are less than or equal to zero, or if `near` is
163    /// equal to `far`, when `glam_assert` is enabled.
164    #[inline]
165    #[must_use]
166    #[cfg_attr(any(debug_assertions, feature = "glam-assert"), track_caller)]
167    pub fn frustum(left: f32, right: f32, bottom: f32, top: f32, near: f32, far: f32) -> Mat4 {
168        camera_impl::frustum::<false, true, true>(left, right, bottom, top, near, far)
169    }
170}
171
172#[doc(alias = "webgpu")]
173pub mod directx {
174    //! DirectX and WebGPU NDC convention: Z range **[0, 1]**, Y-up.
175    //!
176    //! Expects a left-handed Y-up view space input.
177    //!
178    //! Includes standard, infinite-far, and reverse-depth variants.
179
180    use crate::{camera::camera_impl, Mat4};
181
182    /// Creates a perspective projection matrix for use with DirectX and WebGPU.
183    ///
184    /// Expects a left-handed Y-up view space input.
185    /// Outputs NDC with Z in [0, 1] and Y-up.
186    ///
187    /// # Panics
188    ///
189    /// Will panic if `vertical_fov` is not in the range `(0, π)`, if `aspect_ratio` is
190    /// zero, or if `near` or `far` are less than or equal to zero, or if `near` is equal to
191    /// `far`, when `glam_assert` is enabled.
192    #[inline]
193    #[must_use]
194    #[cfg_attr(any(debug_assertions, feature = "glam-assert"), track_caller)]
195    pub fn perspective(vertical_fov: f32, aspect_ratio: f32, near: f32, far: f32) -> Mat4 {
196        camera_impl::perspective::<false, true, false>(vertical_fov, aspect_ratio, near, far)
197    }
198
199    /// Creates an infinite perspective projection matrix for use with DirectX and WebGPU.
200    ///
201    /// Like `perspective`, but with an infinite value for `far`. Points at distance
202    /// `near` map to depth `0`; as distance approaches infinity, depth approaches `1`.
203    ///
204    /// Expects a left-handed Y-up view space input.
205    /// Outputs NDC with Z in [0, 1] and Y-up.
206    ///
207    /// # Panics
208    ///
209    /// Will panic if `vertical_fov` is not in the range `(0, π)`, if `aspect_ratio` is
210    /// zero, or if `near` is less than or equal to zero when `glam_assert` is enabled.
211    #[inline]
212    #[must_use]
213    #[cfg_attr(any(debug_assertions, feature = "glam-assert"), track_caller)]
214    pub fn perspective_infinite(vertical_fov: f32, aspect_ratio: f32, near: f32) -> Mat4 {
215        camera_impl::perspective_infinite::<false, true, false>(vertical_fov, aspect_ratio, near)
216    }
217
218    /// Creates an infinite perspective projection matrix with reversed depth for use with
219    /// DirectX and WebGPU.
220    ///
221    /// Maps `near` to depth `1` and infinity to depth `0`.
222    ///
223    /// Reversed Z improves depth precision when used with a floating-point depth buffer.
224    ///
225    /// Expects a left-handed Y-up view space input.
226    /// Outputs NDC with Z in [0, 1] and Y-up.
227    ///
228    /// # Panics
229    ///
230    /// Will panic if `vertical_fov` is not in the range `(0, π)`, if `aspect_ratio` is
231    /// zero, or if `near` is less than or equal to zero when `glam_assert` is enabled.
232    #[inline]
233    #[must_use]
234    #[cfg_attr(any(debug_assertions, feature = "glam-assert"), track_caller)]
235    pub fn perspective_infinite_reverse(vertical_fov: f32, aspect_ratio: f32, near: f32) -> Mat4 {
236        camera_impl::perspective_infinite_reverse::<false, false>(vertical_fov, aspect_ratio, near)
237    }
238
239    /// Creates an orthographic projection matrix for use with DirectX and WebGPU.
240    ///
241    /// Expects a left-handed Y-up view space input.
242    /// Outputs NDC with Z in [0, 1] and Y-up.
243    ///
244    /// # Panics
245    ///
246    /// Will panic if `left` is equal to `right`, if `bottom` is equal to
247    /// `top`, or if `near` is equal to `far` when `glam_assert` is enabled.
248    #[inline]
249    #[must_use]
250    #[cfg_attr(any(debug_assertions, feature = "glam-assert"), track_caller)]
251    pub fn orthographic(left: f32, right: f32, bottom: f32, top: f32, near: f32, far: f32) -> Mat4 {
252        camera_impl::orthographic::<false, true, false>(left, right, bottom, top, near, far)
253    }
254
255    /// Creates a perspective projection from a frustum for use with DirectX and WebGPU.
256    ///
257    /// Expects a left-handed Y-up view space input.
258    /// Outputs NDC with Z in [0, 1] and Y-up.
259    ///
260    /// # Panics
261    ///
262    /// Will panic if `left` is equal to `right`, if `bottom` is equal to
263    /// `top`, or if `near` or `far` are less than or equal to zero, or if `near` is
264    /// equal to `far`, when `glam_assert` is enabled.
265    #[inline]
266    #[must_use]
267    #[cfg_attr(any(debug_assertions, feature = "glam-assert"), track_caller)]
268    pub fn frustum(left: f32, right: f32, bottom: f32, top: f32, near: f32, far: f32) -> Mat4 {
269        camera_impl::frustum::<false, true, false>(left, right, bottom, top, near, far)
270    }
271}
glam/camera/lh/proj.rs

glam/camera/lh/
proj.rs
