perspective and orthographic functions and options

nalgebra-glm/Cargo.toml

@@ -12,6 +12,22 @@ categories = [ "science" ]
 keywords = [ "linear", "algebra", "matrix", "vector", "math" ]
 license = "BSD-3-Clause"
 
+[features]
+
+default = ["opengl_projection"]
+
+opengl_projection = ["right_hand_default", "negone_to_one_clip_default"]
+vulkan_projection = ["right_hand_default", "zero_to_one_clip_default", "projection_y_flip"]
+directx_projection = ["left_hand_default", "zero_to_one_clip_default"]
+
+projection_y_flip = [] 
+
+left_hand_default = []
+right_hand_default = []
+
+zero_to_one_clip_default = []
+negone_to_one_clip_default = []
+
 [dependencies]
 num-traits = { version = "0.2", default-features = false }
 approx = { version = "0.3", default-features = false }

nalgebra-glm/src/ext/matrix_projection.rs

@@ -24,7 +24,8 @@ pub fn pick_matrix<N: Real>(center: &TVec2<N>, delta: &TVec2<N>, viewport: &TVec
     ))
 }
 
-/// Map the specified object coordinates `(obj.x, obj.y, obj.z)` into window coordinates using OpenGL near and far clip planes definition.
+/// Map the specified object coordinates `(obj.x, obj.y, obj.z)` into window coordinates using
+/// the default configured depth range
 ///
 /// # Parameters:
 ///
@@ -33,6 +34,15 @@ pub fn pick_matrix<N: Real>(center: &TVec2<N>, delta: &TVec2<N>, viewport: &TVec
 /// * `proj` - Specifies the current projection matrix.
 /// * `viewport` - Specifies the current viewport.
 ///
+/// # Compile Options
+///
+/// There are 2 compile options that change the behaviour of the function:
+/// 1. zero_to_one_clip_default/negone_to_one_clip_default
+///
+/// ##### zero_to_one_clip_default/negone_to_one_clip_default
+/// Depending on which option is set the function will return a point un-projected with the depth
+/// range of either 0 to 1 or -1 to 1
+///
 /// # See also:
 ///
 /// * [`project_no`](fn.project_no.html)
@@ -47,7 +57,13 @@ pub fn project<N: Real>(
     viewport: TVec4<N>,
 ) -> TVec3<N>
 {
-    project_no(obj, model, proj, viewport)
+    if cfg!(feature="negone_to_one_clip_default") {
+        project_no(obj, model, proj, viewport)
+    } else if cfg!(feature="zero_to_one_clip_default") {
+        project_zo(obj, model, proj, viewport)
+    } else {
+        unimplemented!()
+    }
 }
 
 /// Map the specified object coordinates (obj.x, obj.y, obj.z) into window coordinates.
@@ -114,7 +130,8 @@ pub fn project_zo<N: Real>(
     )
 }
 
-/// Map the specified window coordinates (win.x, win.y, win.z) into object coordinates using OpenGL near and far clip planes definition.
+/// Map the specified window coordinates (win.x, win.y, win.z) into object coordinates using the
+/// default configured depth range
 ///
 /// # Parameters:
 ///
@@ -123,6 +140,15 @@ pub fn project_zo<N: Real>(
 /// * `proj` - Specifies the current projection matrix.
 /// * `viewport` - Specifies the current viewport.
 ///
+/// # Compile Options
+///
+/// There are 2 compile options that change the behaviour of the function:
+/// 1. zero_to_one_clip_default/negone_to_one_clip_default
+///
+/// ##### zero_to_one_clip_default/negone_to_one_clip_default
+/// Depending on which option is set the function will return a point un-projected with the depth
+/// range of either 0 to 1 or -1 to 1
+///
 /// # See also:
 ///
 /// * [`project`](fn.project.html)
@@ -137,7 +163,13 @@ pub fn unproject<N: Real>(
     viewport: TVec4<N>,
 ) -> TVec3<N>
 {
-    unproject_no(win, model, proj, viewport)
+    if cfg!(feature="negone_to_one_clip_default") {
+        unproject_no(win, model, proj, viewport)
+    } else if cfg!(feature="zero_to_one_clip_default") {
+        unproject_zo(win, model, proj, viewport)
+    } else {
+        unimplemented!()
+    }
 }
 
 /// Map the specified window coordinates (win.x, win.y, win.z) into object coordinates.

nalgebra-glm/src/ext/matrix_transform.rs

@@ -9,6 +9,8 @@ where DefaultAllocator: Alloc<N, D, D> {
     TMat::<N, D, D>::identity()
 }
 
+/// Build a look at view matrix with a handedness based on the defaults configured for the library
+/// at compile time.
 /// Build a look at view matrix based on the right handedness.
 ///
 /// # Parameters:
@@ -17,12 +19,27 @@ where DefaultAllocator: Alloc<N, D, D> {
 /// * `center` − Position where the camera is looking at.
 /// * `u` − Normalized up vector, how the camera is oriented. Typically `(0, 1, 0)`.
 ///
+/// # Compile Options
+///
+/// There is 1 compile option that changes the behaviour of the function:
+/// 1. left_hand_default/right_hand_default
+///
+/// #### left_hand_default/right_hand_default
+/// Depending on which option is set the function will return either a left hand or a right
+/// hand matrix. It switches between using look_at_lh and look_at_rh.
+///
 /// # See also:
 ///
 /// * [`look_at_lh`](fn.look_at_lh.html)
 /// * [`look_at_rh`](fn.look_at_rh.html)
 pub fn look_at<N: Real>(eye: &TVec3<N>, center: &TVec3<N>, up: &TVec3<N>) -> TMat4<N> {
-    look_at_rh(eye, center, up)
+    if cfg!(feature="right_hand_default") {
+        look_at_rh(eye, center, up)
+    } else if cfg!(feature="left_hand_default") {
+        look_at_lh(eye, center, up)
+    } else {
+        unimplemented!()
+    }
 }
 
 /// Build a left handed look at view matrix.

nalgebra-glm/src/ext/mod.rs

@@ -1,6 +1,16 @@
 //! (Reexported) Additional features not specified by GLSL specification
 
-pub use self::matrix_clip_space::{ortho, perspective};
+pub use self::matrix_clip_space::{
+    ortho, ortho_lh, ortho_lh_no, ortho_lh_zo, ortho_no, ortho_rh, ortho_rh_no, ortho_rh_zo,
+    ortho_zo,
+
+    perspective, perspective_lh, perspective_lh_no, perspective_lh_zo, perspective_no,
+    perspective_rh, perspective_rh_no, perspective_rh_zo, perspective_zo,
+
+    perspective_fov, perspective_fov_lh,perspective_fov_lh_no, perspective_fov_lh_zo,
+    perspective_fov_no, perspective_fov_rh, perspective_fov_rh_no, perspective_fov_rh_zo,
+    perspective_fov_zo,
+};
 pub use self::matrix_projection::{
     pick_matrix, project, project_no, project_zo, unproject, unproject_no, unproject_zo,
 };

nalgebra-glm/src/gtc/quaternion.rs

@@ -5,7 +5,7 @@ use aliases::{Qua, TMat4, TVec, TVec3};
 /// Euler angles of the quaternion `q` as (pitch, yaw, roll).
 pub fn quat_euler_angles<N: Real>(x: &Qua<N>) -> TVec3<N> {
     let q = UnitQuaternion::new_unchecked(*x);
-    let a = q.to_euler_angles();
+    let a = q.euler_angles();
     TVec3::new(a.2, a.1, a.0)
 }
 
@@ -34,9 +34,30 @@ pub fn quat_cast<N: Real>(x: &Qua<N>) -> TMat4<N> {
     ::quat_to_mat4(x)
 }
 
-/// Computes a right-handed look-at quaternion (equivalent to a right-handed look-at matrix).
+/// Computes a look-at quaternion based on the defaults configured for the library at build time
+///
+/// # Parameters
+///
+/// * `direction` - Direction vector point at where to look
+/// * `up` - Object up vector
+///
+/// # Compile Options
+///
+/// There is 1 compile option that changes the behaviour of the function:
+/// 1. left_hand_default/right_hand_default
+///
+/// ##### left_hand_default/right_hand_default
+/// Depending on which option is set the function will return either a left hand or a right
+/// hand look at quaternion.
+///
 pub fn quat_look_at<N: Real>(direction: &TVec3<N>, up: &TVec3<N>) -> Qua<N> {
-    quat_look_at_rh(direction, up)
+    if cfg!(feature="right_hand_default") {
+        quat_look_at_rh(direction, up)
+    } else if cfg!(feature="left_hand_default") {
+        quat_look_at_lh(direction, up)
+    } else {
+        unimplemented!()
+    }
 }
 
 /// Computes a left-handed look-at quaternion (equivalent to a left-handed look-at matrix).

nalgebra-glm/src/lib.rs

@@ -142,12 +142,17 @@ pub use ext::{
     epsilon, equal_columns, equal_columns_eps, equal_columns_eps_vec, equal_eps, equal_eps_vec,
     identity, look_at, look_at_lh, look_at_rh, max, max2, max3, max3_scalar, max4, max4_scalar,
     min, min2, min3, min3_scalar, min4, min4_scalar, not_equal_columns, not_equal_columns_eps,
-    not_equal_columns_eps_vec, not_equal_eps, not_equal_eps_vec, ortho, perspective, pi,
+    not_equal_columns_eps_vec, not_equal_eps, not_equal_eps_vec, ortho, perspective, perspective_fov,
-    pick_matrix, project, project_no, project_zo, quat_angle, quat_angle_axis, quat_axis,
+    perspective_fov_lh,perspective_fov_lh_no, perspective_fov_lh_zo, perspective_fov_no,
-    quat_conjugate, quat_cross, quat_dot, quat_equal, quat_equal_eps, quat_exp, quat_inverse,
+    perspective_fov_rh, perspective_fov_rh_no, perspective_fov_rh_zo, perspective_fov_zo,
-    quat_length, quat_lerp, quat_log, quat_magnitude, quat_normalize, quat_not_equal,
+    perspective_lh, perspective_lh_no, perspective_lh_zo, perspective_no, perspective_rh,
-    quat_not_equal_eps, quat_pow, quat_rotate, quat_slerp, rotate, rotate_x, rotate_y, rotate_z,
+    perspective_rh_no, perspective_rh_zo, perspective_zo, ortho_lh, ortho_lh_no, ortho_lh_zo,
-    scale, translate, unproject, unproject_no, unproject_zo,
+    ortho_no, ortho_rh, ortho_rh_no, ortho_rh_zo, ortho_zo, pi, pick_matrix, project, project_no,
+    project_zo, quat_angle, quat_angle_axis, quat_axis, quat_conjugate, quat_cross, quat_dot,
+    quat_equal, quat_equal_eps, quat_exp, quat_inverse, quat_length, quat_lerp, quat_log,
+    quat_magnitude, quat_normalize, quat_not_equal, quat_not_equal_eps, quat_pow, quat_rotate,
+    quat_slerp, rotate, rotate_x, rotate_y, rotate_z, scale, translate, unproject, unproject_no,
+    unproject_zo,
 };
 pub use gtc::{
     affine_inverse, column, e, euler, four_over_pi, golden_ratio, half_pi, inverse_transpose,