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

glam/camera/rh/
proj.rs
