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