glam/dcamera/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::{dcamera::camera_impl, DMat4};
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: f64, aspect_ratio: f64, near: f64, far: f64) -> DMat4 {
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(
51 left: f64,
52 right: f64,
53 bottom: f64,
54 top: f64,
55 near: f64,
56 far: f64,
57 ) -> DMat4 {
58 camera_impl::orthographic::<false, false, false>(left, right, bottom, top, near, far)
59 }
60
61 /// Creates a perspective projection matrix from a frustum for use with OpenGL.
62 ///
63 /// Expects a left-handed Y-up view space input.
64 /// Outputs NDC with Z in [-1, 1] and Y-up.
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: f64, right: f64, bottom: f64, top: f64, near: f64, far: f64) -> DMat4 {
75 camera_impl::frustum::<false, 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 left-handed Y-up view space input.
83 //!
84 //! Includes standard, infinite-far, and reverse-depth variants.
85
86 use crate::{dcamera::camera_impl, DMat4};
87
88 /// Creates a perspective projection matrix for use with Vulkan.
89 ///
90 /// Expects a left-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: f64, aspect_ratio: f64, near: f64, far: f64) -> DMat4 {
102 camera_impl::perspective::<false, 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 left-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: f64, aspect_ratio: f64, near: f64) -> DMat4 {
121 camera_impl::perspective_infinite::<false, 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 left-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: f64, aspect_ratio: f64, near: f64) -> DMat4 {
142 camera_impl::perspective_infinite_reverse::<false, true>(vertical_fov, aspect_ratio, near)
143 }
144
145 /// Creates an orthographic projection matrix for use with Vulkan.
146 ///
147 /// Expects a left-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(
158 left: f64,
159 right: f64,
160 bottom: f64,
161 top: f64,
162 near: f64,
163 far: f64,
164 ) -> DMat4 {
165 camera_impl::orthographic::<false, true, true>(left, right, bottom, top, near, far)
166 }
167
168 /// Creates a perspective projection from a frustum for use with Vulkan.
169 ///
170 /// Expects a left-handed Y-up view space input.
171 /// Outputs NDC with Z in [0, 1] and Y-down.
172 ///
173 /// # Panics
174 ///
175 /// Will panic if `left` is equal to `right`, if `bottom` is equal to
176 /// `top`, or if `near` or `far` are less than or equal to zero, or if `near` is
177 /// equal to `far`, when `glam_assert` is enabled.
178 #[inline]
179 #[must_use]
180 #[cfg_attr(any(debug_assertions, feature = "glam-assert"), track_caller)]
181 pub fn frustum(left: f64, right: f64, bottom: f64, top: f64, near: f64, far: f64) -> DMat4 {
182 camera_impl::frustum::<false, true, true>(left, right, bottom, top, near, far)
183 }
184}
185
186#[doc(alias = "webgpu")]
187pub mod directx {
188 //! DirectX and WebGPU NDC convention: Z range **[0, 1]**, Y-up.
189 //!
190 //! Expects a left-handed Y-up view space input.
191 //!
192 //! Includes standard, infinite-far, and reverse-depth variants.
193
194 use crate::{dcamera::camera_impl, DMat4};
195
196 /// Creates a perspective projection matrix for use with DirectX and WebGPU.
197 ///
198 /// Expects a left-handed Y-up view space input.
199 /// Outputs NDC with Z in [0, 1] and Y-up.
200 ///
201 /// # Panics
202 ///
203 /// Will panic if `vertical_fov` is not in the range `(0, π)`, if `aspect_ratio` is
204 /// zero, or if `near` or `far` are less than or equal to zero, or if `near` is equal to
205 /// `far`, when `glam_assert` is enabled.
206 #[inline]
207 #[must_use]
208 #[cfg_attr(any(debug_assertions, feature = "glam-assert"), track_caller)]
209 pub fn perspective(vertical_fov: f64, aspect_ratio: f64, near: f64, far: f64) -> DMat4 {
210 camera_impl::perspective::<false, true, false>(vertical_fov, aspect_ratio, near, far)
211 }
212
213 /// Creates an infinite perspective projection matrix for use with DirectX and WebGPU.
214 ///
215 /// Like `perspective`, but with an infinite value for `far`. Points at distance
216 /// `near` map to depth `0`; as distance approaches infinity, depth approaches `1`.
217 ///
218 /// Expects a left-handed Y-up view space input.
219 /// Outputs NDC with Z in [0, 1] and Y-up.
220 ///
221 /// # Panics
222 ///
223 /// Will panic if `vertical_fov` is not in the range `(0, π)`, if `aspect_ratio` is
224 /// zero, or if `near` is less than or equal to zero when `glam_assert` is enabled.
225 #[inline]
226 #[must_use]
227 #[cfg_attr(any(debug_assertions, feature = "glam-assert"), track_caller)]
228 pub fn perspective_infinite(vertical_fov: f64, aspect_ratio: f64, near: f64) -> DMat4 {
229 camera_impl::perspective_infinite::<false, true, false>(vertical_fov, aspect_ratio, near)
230 }
231
232 /// Creates an infinite perspective projection matrix with reversed depth for use with
233 /// DirectX and WebGPU.
234 ///
235 /// Maps `near` to depth `1` and infinity to depth `0`.
236 ///
237 /// Reversed Z improves depth precision when used with a floating-point depth buffer.
238 ///
239 /// Expects a left-handed Y-up view space input.
240 /// Outputs NDC with Z in [0, 1] and Y-up.
241 ///
242 /// # Panics
243 ///
244 /// Will panic if `vertical_fov` is not in the range `(0, π)`, if `aspect_ratio` is
245 /// zero, or if `near` is less than or equal to zero when `glam_assert` is enabled.
246 #[inline]
247 #[must_use]
248 #[cfg_attr(any(debug_assertions, feature = "glam-assert"), track_caller)]
249 pub fn perspective_infinite_reverse(vertical_fov: f64, aspect_ratio: f64, near: f64) -> DMat4 {
250 camera_impl::perspective_infinite_reverse::<false, false>(vertical_fov, aspect_ratio, near)
251 }
252
253 /// Creates an orthographic projection matrix for use with DirectX and WebGPU.
254 ///
255 /// Expects a left-handed Y-up view space input.
256 /// Outputs NDC with Z in [0, 1] and Y-up.
257 ///
258 /// # Panics
259 ///
260 /// Will panic if `left` is equal to `right`, if `bottom` is equal to
261 /// `top`, or if `near` is equal to `far` when `glam_assert` is enabled.
262 #[inline]
263 #[must_use]
264 #[cfg_attr(any(debug_assertions, feature = "glam-assert"), track_caller)]
265 pub fn orthographic(
266 left: f64,
267 right: f64,
268 bottom: f64,
269 top: f64,
270 near: f64,
271 far: f64,
272 ) -> DMat4 {
273 camera_impl::orthographic::<false, true, false>(left, right, bottom, top, near, far)
274 }
275
276 /// Creates a perspective projection from a frustum for use with DirectX and WebGPU.
277 ///
278 /// Expects a left-handed Y-up view space input.
279 /// Outputs NDC with Z in [0, 1] and Y-up.
280 ///
281 /// # Panics
282 ///
283 /// Will panic if `left` is equal to `right`, if `bottom` is equal to
284 /// `top`, or if `near` or `far` are less than or equal to zero, or if `near` is
285 /// equal to `far`, when `glam_assert` is enabled.
286 #[inline]
287 #[must_use]
288 #[cfg_attr(any(debug_assertions, feature = "glam-assert"), track_caller)]
289 pub fn frustum(left: f64, right: f64, bottom: f64, top: f64, near: f64, far: f64) -> DMat4 {
290 camera_impl::frustum::<false, true, false>(left, right, bottom, top, near, far)
291 }
292}