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

glam/camera/rh/
proj.rs
