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

glam/dcamera/rh/
proj.rs
