From ea668dea903d4050718f51cb686a2eb973648889 Mon Sep 17 00:00:00 2001 From: sebcrozet Date: Sun, 23 Sep 2018 06:50:39 +0200 Subject: [PATCH] Various documentation improvements. --- nalgebra-glm/README | 14 ------- nalgebra-glm/src/common.rs | 10 ++--- nalgebra-glm/src/ext/matrix_relationnal.rs | 2 +- nalgebra-glm/src/lib.rs | 44 ++++++++++++++++++---- 4 files changed, 43 insertions(+), 27 deletions(-) delete mode 100644 nalgebra-glm/README diff --git a/nalgebra-glm/README b/nalgebra-glm/README deleted file mode 100644 index 5b5a8619..00000000 --- a/nalgebra-glm/README +++ /dev/null @@ -1,14 +0,0 @@ - - -* not_ -> not -* equal overload with epsilon -> equal_epsilon -* ortho(l, r, b, t) -> infinite_ortho -* tweaked_infinite_perspective(fovy, aspect, near, ep) -> tweaked_infinite_perspective_ep -* Function overload: the vec version is suffixed by _vec -* Function overload: the methods taking an epsilon as suffixed by _eps -* L1Norm and L2Norm between two vectors have been renamed: l1_distance, l2_distance -* Matrix columnwise comparisons suffixed by _columns, e.g., `equal` -> `equal_columns` -* All quaternion functions are prefixed by quat_ -* min(Vec, Vec) -> min_vec -* 2D cross is namepd perp -* quat_cross(vec, quat) -> quat_inv_cross \ No newline at end of file diff --git a/nalgebra-glm/src/common.rs b/nalgebra-glm/src/common.rs index e24e873f..7dc0e9e7 100644 --- a/nalgebra-glm/src/common.rs +++ b/nalgebra-glm/src/common.rs @@ -19,18 +19,18 @@ pub fn ceil(x: &Vec) -> Vec /// Returns `min(max(x, min_val), max_val)`. -pub fn clamp(x: N, min_val: N, max_val: N) -> N { +pub fn clamp_scalar(x: N, min_val: N, max_val: N) -> N { na::clamp(x, min_val, max_val) } -/// Returns `min(max(x, min_val), max_val)` for each component in `x` using the floating-point values `min_val and `max_val`. -pub fn clamp2(x: &Vec, min_val: N, max_val: N) -> Vec +/// Returns `min(max(x[i], min_val), max_val)` for each component in `x` using the floating-point values `min_val and `max_val`. +pub fn clamp(x: &Vec, min_val: N, max_val: N) -> Vec where DefaultAllocator: Alloc { x.map(|x| na::clamp(x, min_val, max_val)) } -/// Returns `min(max(x, min_val), max_val)` for each component in `x` using the components of `min_val` and `max_val` as bounds. -pub fn clamp3(x: &Vec, min_val: &Vec, max_val: &Vec) -> Vec +/// Returns `min(max(x[i], min_val[i]), max_val[i])` for each component in `x` using the components of `min_val` and `max_val` as bounds. +pub fn clamp_vec(x: &Vec, min_val: &Vec, max_val: &Vec) -> Vec where DefaultAllocator: Alloc { na::clamp(x.clone(), min_val.clone(), max_val.clone()) } diff --git a/nalgebra-glm/src/ext/matrix_relationnal.rs b/nalgebra-glm/src/ext/matrix_relationnal.rs index 41da0612..0cb05ddb 100644 --- a/nalgebra-glm/src/ext/matrix_relationnal.rs +++ b/nalgebra-glm/src/ext/matrix_relationnal.rs @@ -25,7 +25,7 @@ pub fn equal_columns_eps(x: &Mat equal_columns_eps_vec(x, y, &Vec::<_, C>::repeat(epsilon)) } -/// Returns the component-wise comparison of `|x - y| < epsilon`. +/// Returns the component-wise comparison on each matrix column `|x - y| < epsilon`. /// /// True if this expression is satisfied. pub fn equal_columns_eps_vec(x: &Mat, y: &Mat, epsilon: &Vec) -> Vec diff --git a/nalgebra-glm/src/lib.rs b/nalgebra-glm/src/lib.rs index d8663045..bc5da272 100644 --- a/nalgebra-glm/src/lib.rs +++ b/nalgebra-glm/src/lib.rs @@ -3,6 +3,9 @@ [GLM](https://glm.g-truc.net) itself is a popular C++ linear algebra library essentially targeting computer graphics. Therefore **nalgebra-glm** draws inspiration from GLM to define a nice and easy-to-use API for simple graphics application. + All the types of **nalgebra-glm** are aliases of types from **nalgebra**. Therefore there is a complete and + seamless inter-operability between both. + ## Getting started First of all, you should start by taking a look at the official [GLM API documentation](http://glm.g-truc.net/0.9.9/api/index.html) since **nalgebra-glm** implements a large subset of it. To use **nalgebra-glm** to your project, you @@ -23,10 +26,17 @@ ``` ## Features overview + **nalgebra-glm** supports most linear-algebra related features of the C++ GLM library. Mathematically + speaking, it supports all the common transformations like rotations, translations, scaling, shearing, + and projections but operating in homogeneous coordinates. This means all the 2D transformations are + expressed as 3x3 matrices, and all the 3D transformations as 4x4 matrices. This is less computationally-efficient + and memory-efficient than nalgebra's [transformation types](https://www.nalgebra.org/points_and_transformations/#transformations), + but this has the benefit of being simpler to use. ### Main differences compared to GLM While **nalgebra-glm** follows the feature line of the C++ GLM library, quite a few differences remain and they are mostly syntactic. The main ones are: - * All function names use `snake_case` while the C++ GLM library uses `camelCase`. + * All function names use `snake_case`, which is the Rust convention. + * All type names use `CamelCase`, which is the Rust convention. * All function arguments, except for scalars, are all passed by-reference. * Some feature are not yet implemented and should be added in the future. In particular, no packing functions are available. @@ -54,10 +64,11 @@ dimension 3, i.e., you can only refer to the components `x`, `y` and `z` and can only create a 2D or 3D vector using this technique. Here is some examples, assuming `v` is a vector with float components here: - * `v.xx()` is equivalent to `glm::vec2(v.x, v.x)` as well as `Vec2::new(v.x, v.x)`. - * `v.zx()` is equivalent to `glm::vec2(v.z, v.x)` as well as `Vec2::new(v.z, v.x)`. - * `v.yxz()` is equivalent to `glm::vec3(v.y, v.x, v.z)` as well as `Vec3::new(v.y, v.x, v.z)`. - * `v.zzy()` is equivalent to `glm::vec3(v.z, v.z, v.y)` as well as `Vec3::new(v.z, v.z, v.y)`. + * `v.xx()` is equivalent to `glm::vec2(v.x, v.x)` and to `Vec2::new(v.x, v.x)`. + * `v.zx()` is equivalent to `glm::vec2(v.z, v.x)` and to `Vec2::new(v.z, v.x)`. + * `v.yxz()` is equivalent to `glm::vec3(v.y, v.x, v.z)` and to `Vec3::new(v.y, v.x, v.z)`. + * `v.zzy()` is equivalent to `glm::vec3(v.z, v.z, v.y)` and to `Vec3::new(v.z, v.z, v.y)`. + Any combination of two or three components picked among `x`, `y`, and `z` will work. ### Conversions It is often useful to convert one algebraic type to another. There are two main approaches for converting @@ -76,7 +87,26 @@ 2. If you need this kind of conversions anyway, you can use `try_convert` which will test if the object being converted complies with the algebraic requirements of the target type. This will return `None` if the requirements are not satisfied. 3. The `convert_unchecked` will ignore those tests and always perform the conversion, even if that breaks the invariants of the target type. - This must be used with care! + 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. + + ### 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 + those not used to the abstract mathematical concepts for transformations. **nalgebra-glm** however + have more straightforward functions and benefit from the various tutorials existing on the internet + for the original C++ GLM library. + + Overall, if you are already used to the C++ GLM library, or to working with homogeneous coordinates (like 4D + matrices for 3D transformations), then you will have more success with **nalgebra-glm**. If on the other + hand you prefer more rigorous treatments of transformations, with type-level restrictions, then go for **nalgebra**. + If you need dynamically-sized matrices, you should go for **nalgebra** as well. + + Keep in mind that **nalgebra-glm** is just a different API for **nalgebra**. So you can very well use both + and benefit from both their advantages: use **nalgebra-glm** when mathematical rigor is not that important, + and **nalgebra** itself when you need more expressive types, and more powerful linear algebra operations like + matrix factorizations and slicing. Just remember that all the **nalgebra-glm** types are just aliases to **nalgebra** types, + and keep in mind it is possible to convert, e.g., an `Isometry3` to a `Mat4` and vice-versa (see the [conversions section](#conversions)). */ extern crate num_traits as num; @@ -87,7 +117,7 @@ extern crate nalgebra as na; pub use aliases::*; pub use constructors::*; -pub use common::{abs, ceil, clamp, clamp2, clamp3, float_bits_to_int, float_bits_to_int_vec, float_bits_to_uint, float_bits_to_uint_vec, floor, fract, int_bits_to_float, int_bits_to_float_vec, mix, modf, modf_vec, round, sign, smoothstep, step, step_scalar, step_vec, trunc, uint_bits_to_float, uint_bits_to_float_scalar}; +pub use common::{abs, ceil, clamp, clamp_scalar, clamp_vec, float_bits_to_int, float_bits_to_int_vec, float_bits_to_uint, float_bits_to_uint_vec, floor, fract, int_bits_to_float, int_bits_to_float_vec, mix, modf, modf_vec, round, sign, smoothstep, step, step_scalar, step_vec, trunc, uint_bits_to_float, uint_bits_to_float_scalar}; pub use geometric::{reflect_vec, cross, distance, dot, faceforward, length, magnitude, normalize, refract_vec}; pub use matrix::{transpose, determinant, inverse, matrix_comp_mult, outer_product}; pub use traits::{Dimension, Number, Alloc};