updating changes for response to pull request

Removed the compile configs based on cargo features and updated docs
This commit is contained in:
MindSpunk 2018-12-19 14:01:09 +11:00 committed by Sébastien Crozet
parent ffd3dd5b68
commit 55b599e52c
7 changed files with 105 additions and 825 deletions

View File

@ -12,32 +12,6 @@ categories = [ "science" ]
keywords = [ "linear", "algebra", "matrix", "vector", "math" ]
license = "BSD-3-Clause"
[features]
## Default to produce opengl compatible matrices and conventions
default = ["opengl_projection"]
## Produce projection matrices and default to coordinate space behaviour that is compatible with OpenGL's NDC space
opengl_projection = ["right_hand_default", "negone_to_one_clip_default"]
## Produce projection matrices and default to coordinate space behaviour that is compatible with Vulkan's NDC space
vulkan_projection = ["right_hand_default", "zero_to_one_clip_default", "projection_y_flip"]
## Produce projection matrices and default to coordinate space behaviour that is compatible with DirectX's NDC space
directx_projection = ["left_hand_default", "zero_to_one_clip_default"]
## Applies an implicit `mat[(1,1)] *= -1` to all projection matrices. Essentially flips the output of using the matrix
## about the x axis (vertical flip)
projection_y_flip = []
## Whether to default to left hand (DirectX) or right hand (OpenGL/Vulkan) coordinate system behaviour
left_hand_default = []
right_hand_default = []
## Whether to default to 0 to 1 depth range (DirectX, Vulkan, Metal) or -1 to 1 (OpenGL) behaviour
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 }

File diff suppressed because it is too large Load Diff

View File

@ -24,8 +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
/// the default configured depth range
/// Map the specified object coordinates `(obj.x, obj.y, obj.z)` into window coordinates with a
/// depth range of -1 to 1
///
/// # Parameters:
///
@ -34,15 +34,6 @@ 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)
@ -57,13 +48,7 @@ pub fn project<N: Real>(
viewport: TVec4<N>,
) -> TVec3<N>
{
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!()
}
project_no(obj, model, proj, viewport)
}
/// Map the specified object coordinates (obj.x, obj.y, obj.z) into window coordinates.
@ -130,8 +115,8 @@ pub fn project_zo<N: Real>(
)
}
/// Map the specified window coordinates (win.x, win.y, win.z) into object coordinates using the
/// default configured depth range
/// Map the specified window coordinates (win.x, win.y, win.z) into object coordinates using a
/// depth range of -1 to 1
///
/// # Parameters:
///
@ -140,15 +125,6 @@ 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)
@ -163,13 +139,7 @@ pub fn unproject<N: Real>(
viewport: TVec4<N>,
) -> TVec3<N>
{
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!()
}
unproject_no(win, model, proj, viewport)
}
/// Map the specified window coordinates (win.x, win.y, win.z) into object coordinates.

View File

@ -9,9 +9,7 @@ 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.
/// Build a right hand look at view matrix
///
/// # Parameters:
///
@ -19,27 +17,12 @@ 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> {
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!()
}
look_at_rh(eye, center, up)
}
/// Build a left handed look at view matrix.

View File

@ -34,30 +34,15 @@ pub fn quat_cast<N: Real>(x: &Qua<N>) -> TMat4<N> {
::quat_to_mat4(x)
}
/// Computes a look-at quaternion based on the defaults configured for the library at build time
/// Computes a right hand look-at quaternion
///
/// # 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> {
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!()
}
quat_look_at_rh(direction, up)
}
/// Computes a left-handed look-at quaternion (equivalent to a left-handed look-at matrix).

View File

@ -91,74 +91,6 @@
This must be used with care! This is actually the recommended method to convert between homogeneous transformations generated by `nalgebra-glm` and
specific transformation types from **nalgebra** like `Isometry3`. Just be careful you know your conversions make sense.
### Compile Features/Options
There are a few compile features that alters the default behaviour of some functions. The current set of compile options includes:
* opengl_projection
* vulkan_projection
* directx_projection
* projection_y_flip
* left_hand_default
* right_hand_default
* zero_to_one_clip_default
* negone_to_one_clip_default
The default is to compile with the `opengl_projection` feature enabled
#### opengl_projection
This is a "macro" feature that exists as an alias to `right_hand_default` and
`negone_to_one_clip_default`
#### vulkan_projection
This is a "macro" feature that exists as an alias to `right_hand_default`,
`zero_to_one_clip_default` and `projection_y_flip`
#### directx_projection
This is a "macro" feature that exists as an alias to `left_hand_default` and
`zero_to_one_clip_default`
#### projection_y_flip
Applies an implicit `mat[(1,1)] *= -1` to all projection matrices created through the
nalgebra-glm interface. This feature should be enabled when using Vulkan so the generated
matrices conform to Vulkan's NDC (normalized device coordinates).
#### left_hand_default / right_hand_default
These two options are used to change the default handedness of the coordinate system the library
will use. Depending on which option is set it would cause a function like `ortho` to switch
between using `ortho_rh` and `ortho_lh`.
DO NOT set both of these options at the same time. There is no guarantee that all functions will
follow the same convention if you were to do so
#### zero_to_one_clip_default / negone_to_one_clip_default
These options are used to change the default depth range for projection matrices generated by
the nalgebra-glm interface. Depending on which option is set functions like `ortho` will
statically switch between calling `ortho_zo` and `ortho_no`.
DO NOT set both of these options at the same time. There is no guarantee that all functions will
follow the same convention if you were to do so
#### Functions Affected
* [`perspective`](fn.perspective.html)
* [`perspective_no`](fn.perspective_no.html)
* [`perspective_zo`](fn.perspective_zo.html)
* [`perspective_rh`](fn.perspective_rh.html)
* [`perspective_lh`](fn.perspective_lh.html)
* [`perspective_fov`](fn.perspective_fov.html)
* [`perspective_fov_no`](fn.perspective_fov_no.html)
* [`perspective_fov_zo`](fn.perspective_fov_zo.html)
* [`perspective_fov_rh`](fn.perspective_fov_rh.html)
* [`perspective_fov_lh`](fn.perspective_fov_lh.html)
* [`ortho`](fn.ortho.html)
* [`ortho_no`](fn.ortho_no.html)
* [`ortho_zo`](fn.ortho_zo.html)
* [`ortho_rh`](fn.ortho_rh.html)
* [`ortho_lh`](fn.ortho_lh.html)
* [`project`](fn.project.html)
* [`unproject`](fn.unproject.html)
* [`look_at`](fn.look_at.html)
* [`quat_look_at`](fn.quat_look_at.html)
### Should I use nalgebra or nalgebra-glm?
Well that depends on your tastes and your background. **nalgebra** is more powerful overall since it allows stronger typing,
and goes much further than simple computer graphics math. However, has a bit of a learning curve for

View File

@ -6,47 +6,31 @@ use na::Orthographic3;
use glm::Mat4;
use glm::Vec4;
// Ensure that under default conditions the library doesn't break interface with old convention
#[test]
pub fn orthographic_glm_nalgebra_same()
{
let na_mat : Mat4 = Orthographic3::new(-100.0f32,100.0f32, -50.0f32, 50.0f32, 0.1f32, 100.0f32).unwrap();
let gl_mat : Mat4 = glm::ortho_rh_no(-100.0f32,100.0f32, -50.0f32, 50.0f32, 0.1f32, 100.0f32);
// ortho_rh_no is the same as the standard nalgebra orthographic matrix
//
// we cant use plain ortho here as the library could be configured to produce different values
let gl_mat : Mat4 = glm::ortho(-100.0f32,100.0f32, -50.0f32, 50.0f32, 0.1f32, 100.0f32);
assert_eq!(na_mat, gl_mat);
}
// Ensure that under default conditions the library doesn't break interface with old convention
#[test]
pub fn perspective_glm_nalgebra_same()
{
let na_mat : Mat4 = Perspective3::new(16.0f32/9.0f32, 3.14f32/2.0f32, 0.1f32, 100.0f32).unwrap();
let gl_mat : Mat4 = glm::perspective_rh_no(16.0f32/9.0f32, 3.14f32/2.0f32, 0.1f32, 100.0f32);
// perspective_rh_no is the same as the standard nalgebra perspective matrix
//
// we cant use plain perspective here as the library could be configured to produce different
// values
let gl_mat : Mat4 = glm::perspective(16.0f32/9.0f32, 3.14f32/2.0f32, 0.1f32, 100.0f32);
assert_eq!(na_mat, gl_mat);
}
// Ensure that under default conditions the library doesn't break interface with old convention
#[test]
pub fn orthographic_glm_nalgebra_project_same()
{
let point = Vec4::new(1.0,0.0,-20.0,1.0);
let na_mat : Mat4 = Orthographic3::new(-100.0f32,100.0f32, -50.0f32, 50.0f32, 0.1f32, 100.0f32).unwrap();
let gl_mat : Mat4 = glm::ortho_rh_no(-100.0f32,100.0f32, -50.0f32, 50.0f32, 0.1f32, 100.0f32);
// ortho_rh_no is the same as the standard nalgebra orthographic matrix
//
// we cant use plain ortho here as the library could be configured to produce different values
let gl_mat : Mat4 = glm::ortho(-100.0f32,100.0f32, -50.0f32, 50.0f32, 0.1f32, 100.0f32);
let na_pt = na_mat * point;
let gl_pt = gl_mat * point;
@ -55,19 +39,13 @@ pub fn orthographic_glm_nalgebra_project_same()
assert_eq!(na_pt, gl_pt);
}
// Ensure that under default conditions the library doesn't break interface with old convention
#[test]
pub fn perspective_glm_nalgebra_project_same()
{
let point = Vec4::new(1.0,0.0,-20.0,1.0);
let na_mat : Mat4 = Perspective3::new(16.0f32/9.0f32, 3.14f32/2.0f32, 0.1f32, 100.0f32).unwrap();
let gl_mat : Mat4 = glm::perspective_rh_no(16.0f32/9.0f32, 3.14f32/2.0f32, 0.1f32, 100.0f32);
// perspective_rh_no is the same as the standard nalgebra perspective matrix
//
// we cant use plain perspective here as the library could be configured to produce different
// values
let gl_mat : Mat4 = glm::perspective(16.0f32/9.0f32, 3.14f32/2.0f32, 0.1f32, 100.0f32);
let na_pt = na_mat * point;
let gl_pt = gl_mat * point;