Various documentation improvements.

nalgebra-glm/README

@@ -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

nalgebra-glm/src/common.rs

@@ -19,18 +19,18 @@ pub fn ceil<N: Real, D: Dimension>(x: &Vec<N, D>) -> Vec<N, D>
 
 
 /// Returns `min(max(x, min_val), max_val)`.
-pub fn clamp<N: Number>(x: N, min_val: N, max_val: N) -> N {
+pub fn clamp_scalar<N: Number>(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<N: Number, D: Dimension>(x: &Vec<N, D>, min_val: N, max_val: N) -> Vec<N, D>
+/// 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<N: Number, D: Dimension>(x: &Vec<N, D>, min_val: N, max_val: N) -> Vec<N, D>
     where DefaultAllocator: Alloc<N, D> {
     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<N: Number, D: Dimension>(x: &Vec<N, D>, min_val: &Vec<N, D>, max_val: &Vec<N, D>) -> Vec<N, D>
+/// 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<N: Number, D: Dimension>(x: &Vec<N, D>, min_val: &Vec<N, D>, max_val: &Vec<N, D>) -> Vec<N, D>
     where DefaultAllocator: Alloc<N, D> {
     na::clamp(x.clone(), min_val.clone(), max_val.clone())
 }

nalgebra-glm/src/ext/matrix_relationnal.rs

@@ -25,7 +25,7 @@ pub fn equal_columns_eps<N: Number, R: Dimension, C: Dimension>(x: &Mat<N, R, C>
     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<N: Number, R: Dimension, C: Dimension>(x: &Mat<N, R, C>, y: &Mat<N, R, C>, epsilon: &Vec<N, C>) -> Vec<bool, C>

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};