M-Labs
/
nalgebra
3
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Improve cross-linking and cross-referencing in docs.

This commit is contained in:
Bruce Mitchener 2018-09-26 16:39:30 +07:00 committed by Sébastien Crozet
parent a3a2ed81a8
commit a8ae62ea52
5 changed files with 189 additions and 20 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

22
nalgebra-glm/src/geometric.rs
View File

@ -9,6 +9,10 @@ pub fn cross<N: Number, D: Dimension>(x: &TVec3<N>, y: &TVec3<N>) -> TVec3<N> {
}
/// The distance between two points.
///
/// # See also:
///
/// * [`distance2`](fn.distance2.html)
pub fn distance<N: Real, D: Dimension>(p0: &TVec<N, D>, p1: &TVec<N, D>) -> N
where DefaultAllocator: Alloc<N, D> {
(p1 - p0).norm()
@ -31,12 +35,28 @@ pub fn faceforward<N: Number, D: Dimension>(n: &TVec<N, D>, i: &TVec<N, D>, nref
}
/// The magnitude of a vector.
///
/// A synonym for [`magnitude`](fn.magnitude.html).
///
/// # See also:
///
/// * [`length2`](fn.length2.html)
/// * [`magnitude`](fn.magnitude.html)
/// * [`magnitude2`](fn.magnitude2.html)
pub fn length<N: Real, D: Dimension>(x: &TVec<N, D>) -> N
where DefaultAllocator: Alloc<N, D> {
x.norm()
}
/// The magnitude of a vector.
///
/// A wrapper around [`nalgebra::norm`](../nalgebra/fn.norm.html).
///
/// # See also:
///
/// * [`length`](fn.length.html)
/// * [`magnitude2`](fn.magnitude2.html)
/// * [`nalgebra::norm`](../nalgebra/fn.norm.html)
pub fn magnitude<N: Real, D: Dimension>(x: &TVec<N, D>) -> N
where DefaultAllocator: Alloc<N, D> {
x.norm()
@ -68,4 +88,4 @@ pub fn refract_vec<N: Real, D: Dimension>(i: &TVec<N, D>, n: &TVec<N, D>, eta: N
else {
i * eta - n * (eta * dot(n, i) + k.sqrt())
}
}
}

24
nalgebra-glm/src/gtx/norm.rs
View File

@ -4,6 +4,10 @@ use traits::{Alloc, Dimension};
use aliases::TVec;
/// The squared distance between two points.
///
/// # See also:
///
/// * [`distance`](fn.distance.html)
pub fn distance2<N: Real, D: Dimension>(p0: &TVec<N, D>, p1: &TVec<N, D>) -> N
where DefaultAllocator: Alloc<N, D> {
(p1 - p0).norm_squared()
@ -34,12 +38,32 @@ pub fn l2_norm<N: Real, D: Dimension>(x: &TVec<N, D>) -> N
}
/// The squared magnitude of `x`.
///
/// A synonym for [`magnitude2`](fn.magnitude2.html).
///
/// # See also:
///
/// * [`distance`](fn.distance.html)
/// * [`distance2`](fn.distance2.html)
/// * [`length`](fn.length.html)
/// * [`magnitude`](fn.magnitude.html)
/// * [`magnitude2`](fn.magnitude2.html)
pub fn length2<N: Real, D: Dimension>(x: &TVec<N, D>) -> N
where DefaultAllocator: Alloc<N, D> {
x.norm_squared()
}
/// The squared magnitude of `x`.
///
/// A wrapper around [`nalgebra::norm_squared`](../nalgebra/fn.norm_squared.html).
///
/// # See also:
///
/// * [`distance`](fn.distance.html)
/// * [`distance2`](fn.distance2.html)
/// * [`length2`](fn.length2.html)
/// * [`magnitude`](fn.magnitude.html)
/// * [`nalgebra::norm_squared`](../nalgebra/fn.norm_squared.html)
pub fn magnitude2<N: Real, D: Dimension>(x: &TVec<N, D>) -> N
where DefaultAllocator: Alloc<N, D> {
x.norm_squared()

24
nalgebra-glm/src/lib.rs
View File

@ -38,7 +38,7 @@
* 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.
* The most generic vector and matrix types are `TMat` and `TVec` instead of `mat` and `vec`.
* The most generic vector and matrix types are [`TMat`](type.TMat.html) and [`TVec`](type.TVec.html) instead of `mat` and `vec`.
* Some feature are not yet implemented and should be added in the future. In particular, no packing
functions are available.
* A few features are not implemented and will never be. This includes functions related to color
@ -47,17 +47,17 @@
In addition, because Rust does not allows function overloading, all functions must be given a unique name.
Here are a few rules chosen arbitrarily for **nalgebra-glm**:
* Functions operating in 2d will usually end with the `2d` suffix, e.g., `glm::rotade2d` is for 2D while `glm::rotate` is for 3D.
* Functions operating on vector will often end with the `_vec` suffix, possibly followed by the dimension of vector, e.g., `glm::rotate_vec2`.
* Every function related to quaternions start with the `quat_` prefix, e.g., `glm::quat_dot(q1, q2)`.
* Functions operating in 2d will usually end with the `2d` suffix, e.g., [`glm::rotate2d`](fn.rotate2d.html) is for 2D while [`glm::rotate`](fn.rotate.html) is for 3D.
* Functions operating on vectors will often end with the `_vec` suffix, possibly followed by the dimension of vector, e.g., [`glm::rotate_vec2`](fn.rotate_vec2.html).
* Every function related to quaternions start with the `quat_` prefix, e.g., [`glm::quat_dot(q1, q2)`](fn.quat_dot.html).
* All the conversion functions have unique names as described [below](#conversions).
### Vector and matrix construction
Vectors, matrices, and quaternions can be constructed using several approaches:
* Using functions with the same name as their type in lower-case. For example `glm::vec3(x, y, z)` will create a 3D vector.
* Using the `::new` constructor. For example `Vec3::new(x, y, z)` will create a 3D vector.
* Using the functions prefixed by `make_` to build a vector a matrix from a slice. For example `glm::make_vec3(&[x, y, z])` will create a 3D vector.
Keep in mind that constructing a matrix using this type of functions require its components to be arrange in column-major order on the slice.
* Using a geometric construction function. For example `glm::rotation(angle, axis)` will build a 4x4 homogeneous rotation matrix from an angle (in radians) and an axis.
* Using functions with the same name as their type in lower-case. For example [`glm::vec3(x, y, z)`](fn.vec3.html) will create a 3D vector.
* Using the `::new` constructor. For example [`Vec3::new(x, y, z)`](../nalgebra/base/type.MatrixMN.html#method.new-27) will create a 3D vector.
* Using the functions prefixed by `make_` to build a vector a matrix from a slice. For example [`glm::make_vec3(&[x, y, z])`](fn.make_vec3.html) will create a 3D vector.
Keep in mind that constructing a matrix using this type of functions require its components to be arranged in column-major order on the slice.
* Using a geometric construction function. For example [`glm::rotation(angle, axis)`](fn.rotation.html) will build a 4x4 homogeneous rotation matrix from an angle (in radians) and an axis.
* Using swizzling and conversions as described in the next sections.
### Swizzling
Vector swizzling is a native feature of **nalgebra** itself. Therefore, you can use it with all
@ -75,11 +75,11 @@
It is often useful to convert one algebraic type to another. There are two main approaches for converting
between types in `nalgebra-glm`:
* Using function with the form `type1_to_type2` in order to convert an instance of `type1` into an instance of `type2`.
For example `glm::mat3_to_mat4(m)` will convert the 3x3 matrix `m` to a 4x4 matrix by appending one column on the right
For example [`glm::mat3_to_mat4(m)`](fn.mat3_to_mat4.html) will convert the 3x3 matrix `m` to a 4x4 matrix by appending one column on the right
and one row on the left. Those now row and columns are filled with 0 except for the diagonal element which is set to 1.
* Using one of the `convert`, `try_convert`, or `convert_unchecked` functions.
* Using one of the [`convert`](fn.convert.html), [`try_convert`](fn.try_convert.html), or [`convert_unchecked`](fn.convert_unchecked.html) functions.
These functions are directly re-exported from nalgebra and are extremely versatile:
1. The `convert` function can convert any type (especially geometric types from nalgebra like `Isometry3`) into another algebraic type which equivalent but more general. For example,
1. The `convert` function can convert any type (especially geometric types from nalgebra like `Isometry3`) into another algebraic type which is equivalent but more general. For example,
`let sim: Similarity3<_> = na::convert(isometry)` will convert an `Isometry3` into a `Similarity3`.
In addition, `let mat: Mat4 = glm::convert(isometry)` will convert an `Isometry3` to a 4x4 matrix. This will also convert the scalar types,
therefore: `let mat: DMat4 = glm::convert(m)` where `m: Mat4` will work. However, conversion will not work the other way round: you

2
src/base/dimension.rs
View File

@ -209,6 +209,7 @@ pub trait NamedDim: Sized + Any + Unsigned {
type Name: DimName<Value = Self>;
}
/// A type level dimension with a value of `1`.
#[derive(Debug, Copy, Clone, Hash, PartialEq, Eq)]
#[cfg_attr(feature = "serde-serialize", derive(Serialize, Deserialize))]
pub struct U1;
@ -246,6 +247,7 @@ impl NamedDim for typenum::U1 {
macro_rules! named_dimension(
($($D: ident),* $(,)*) => {$(
/// A type level dimension.
#[derive(Debug, Copy, Clone, Hash, PartialEq, Eq)]
#[cfg_attr(feature = "serde-serialize", derive(Serialize, Deserialize))]
pub struct $D;

137
src/lib.rs
View File

@ -161,18 +161,33 @@ pub fn id() -> Id {
}
/// Gets the multiplicative identity element.
///
/// # See also:
///
/// * [`origin`](../nalgebra/fn.origin.html)
/// * [`zero`](fn.zero.html)
#[inline]
pub fn one<T: Identity<Multiplicative>>() -> T {
T::identity()
}
/// Gets the additive identity element.
///
/// # See also:
///
/// * [`one`](fn.one.html)
/// * [`origin`](../nalgebra/fn.origin.html)
#[inline]
pub fn zero<T: Identity<Additive>>() -> T {
T::identity()
}
/// Gets the origin of the given point.
///
/// # See also:
///
/// * [`one`](fn.one.html)
/// * [`zero`](fn.zero.html)
#[inline]
pub fn origin<P: EuclideanSpace>() -> P {
P::origin()
@ -375,12 +390,20 @@ pub fn partial_sort2<'a, T: PartialOrd>(a: &'a T, b: &'a T) -> Option<(&'a T, &'
*/
/// Tries to gets an inverted copy of a square matrix.
///
/// # See also:
///
/// * [`inverse`](fn.inverse.html)
#[inline]
pub fn try_inverse<M: AlgaSquareMatrix>(m: &M) -> Option<M> {
m.try_inverse()
}
/// Computes the multiplicative inverse of an (always invertible) algebraic entity.
///
/// # See also:
///
/// * [`try_inverse`](fn.try_inverse.html)
#[inline]
pub fn inverse<M: Inverse<Multiplicative>>(m: &M) -> M {
m.inverse()
@ -407,24 +430,49 @@ pub fn angle<V: InnerSpace>(a: &V, b: &V) -> V::Real {
*/
/// Computes the L2 (euclidean) norm of a vector.
///
/// # See also:
///
/// * [`magnitude`](fn.magnitude.html)
/// * [`magnitude_squared`](fn.magnitude_squared.html)
/// * [`norm_squared`](fn.norm_squared.html)
#[inline]
pub fn norm<V: NormedSpace>(v: &V) -> V::Field {
v.norm()
}
/// Computes the squared L2 (euclidean) norm of the vector `v`.
///
/// # See also:
///
/// * [`magnitude`](fn.magnitude.html)
/// * [`magnitude_squared`](fn.magnitude_squared.html)
/// * [`norm`](fn.norm.html)
#[inline]
pub fn norm_squared<V: NormedSpace>(v: &V) -> V::Field {
v.norm_squared()
}
/// A synonym function for `norm()` aka length.
/// A synonym for [`norm`](fn.norm.html), aka length.
///
/// # See also:
///
/// * [`magnitude_squared`](fn.magnitude_squared.html)
/// * [`norm`](fn.norm.html)
/// * [`norm_squared`](fn.norm_squared.html)
#[inline]
pub fn magnitude<V: NormedSpace>(v: &V) -> V::Field {
v.norm()
}
/// A synonym function for `norm_squared()` aka length squared.
/// A synonym for [`norm_squared`](fn.norm_squared.html),
/// aka length squared.
///
/// # See also:
///
/// * [`magnitude`](fn.magnitude.html)
/// * [`norm`](fn.norm.html)
/// * [`norm_squared`](fn.norm_squared.html)
#[inline]
pub fn magnitude_squared<V: NormedSpace>(v: &V) -> V::Field {
v.norm_squared()
@ -448,18 +496,33 @@ pub fn try_normalize<V: NormedSpace>(v: &V, min_norm: V::Field) -> Option<V> {
*
*/
/// The center of two points.
///
/// # See also:
///
/// * [distance](fn.distance.html)
/// * [distance_squared](fn.distance_squared.html)
#[inline]
pub fn center<P: EuclideanSpace>(p1: &P, p2: &P) -> P {
P::from_coordinates((p1.coordinates() + p2.coordinates()) * convert(0.5))
}
/// The distance between two points.
///
/// # See also:
///
/// * [center](fn.center.html)
/// * [distance_squared](fn.distance_squared.html)
#[inline]
pub fn distance<P: EuclideanSpace>(p1: &P, p2: &P) -> P::Real {
(p2.coordinates() - p1.coordinates()).norm()
}
/// The squared distance between two points.
///
/// # See also:
///
/// * [center](fn.center.html)
/// * [distance](fn.distance.html)
#[inline]
pub fn distance_squared<P: EuclideanSpace>(p1: &P, p2: &P) -> P::Real {
(p2.coordinates() - p1.coordinates()).norm_squared()
@ -470,7 +533,15 @@ pub fn distance_squared<P: EuclideanSpace>(p1: &P, p2: &P) -> P::Real {
*/
/// Converts an object from one type to an equivalent or more general one.
///
/// See also `::try_convert` for conversion to more specific types.
/// See also [`try_convert`](fn.try_convert.html) for conversion to more specific types.
///
/// # See also:
///
/// * [convert_ref](fn.convert_ref.html)
/// * [convert_ref_unchecked](fn.convert_ref_unchecked.html)
/// * [is_convertible](../nalgebra/fn.is_convertible.html)
/// * [try_convert](fn.try_convert.html)
/// * [try_convert_ref](fn.try_convert_ref.html)
#[inline]
pub fn convert<From, To: SupersetOf<From>>(t: From) -> To {
To::from_subset(&t)
@ -478,37 +549,89 @@ pub fn convert<From, To: SupersetOf<From>>(t: From) -> To {
/// Attempts to convert an object to a more specific one.
///
/// See also `::convert` for conversion to more general types.
/// See also [`convert`](fn.convert.html) for conversion to more general types.
///
/// # See also:
///
/// * [convert](fn.convert.html)
/// * [convert_ref](fn.convert_ref.html)
/// * [convert_ref_unchecked](fn.convert_ref_unchecked.html)
/// * [is_convertible](../nalgebra/fn.is_convertible.html)
/// * [try_convert_ref](fn.try_convert_ref.html)
#[inline]
pub fn try_convert<From: SupersetOf<To>, To>(t: From) -> Option<To> {
t.to_subset()
}
/// Indicates if `::try_convert` will succeed without actually performing the conversion.
/// Indicates if [`try_convert`](fn.try_convert.html) will succeed without
/// actually performing the conversion.
///
/// # See also:
///
/// * [convert](fn.convert.html)
/// * [convert_ref](fn.convert_ref.html)
/// * [convert_ref_unchecked](fn.convert_ref_unchecked.html)
/// * [try_convert](fn.try_convert.html)
/// * [try_convert_ref](fn.try_convert_ref.html)
#[inline]
pub fn is_convertible<From: SupersetOf<To>, To>(t: &From) -> bool {
t.is_in_subset()
}
/// Use with care! Same as `try_convert` but without any property checks.
/// Use with care! Same as [`try_convert`](fn.try_convert.html) but
/// without any property checks.
///
/// # See also:
///
/// * [convert](fn.convert.html)
/// * [convert_ref](fn.convert_ref.html)
/// * [convert_ref_unchecked](fn.convert_ref_unchecked.html)
/// * [is_convertible](../nalgebra/fn.is_convertible.html)
/// * [try_convert](fn.try_convert.html)
/// * [try_convert_ref](fn.try_convert_ref.html)
#[inline]
pub unsafe fn convert_unchecked<From: SupersetOf<To>, To>(t: From) -> To {
t.to_subset_unchecked()
}
/// Converts an object from one type to an equivalent or more general one.
///
/// # See also:
///
/// * [convert](fn.convert.html)
/// * [convert_ref_unchecked](fn.convert_ref_unchecked.html)
/// * [is_convertible](../nalgebra/fn.is_convertible.html)
/// * [try_convert](fn.try_convert.html)
/// * [try_convert_ref](fn.try_convert_ref.html)
#[inline]
pub fn convert_ref<From, To: SupersetOf<From>>(t: &From) -> To {
To::from_subset(t)
}
/// Attempts to convert an object to a more specific one.
///
/// # See also:
///
/// * [convert](fn.convert.html)
/// * [convert_ref](fn.convert_ref.html)
/// * [convert_ref_unchecked](fn.convert_ref_unchecked.html)
/// * [is_convertible](../nalgebra/fn.is_convertible.html)
/// * [try_convert](fn.try_convert.html)
#[inline]
pub fn try_convert_ref<From: SupersetOf<To>, To>(t: &From) -> Option<To> {
t.to_subset()
}
/// Use with care! Same as `try_convert` but without any property checks.
/// Use with care! Same as [`try_convert`](fn.try_convert.html) but
/// without any property checks.
///
/// # See also:
///
/// * [convert](fn.convert.html)
/// * [convert_ref](fn.convert_ref.html)
/// * [is_convertible](../nalgebra/fn.is_convertible.html)
/// * [try_convert](fn.try_convert.html)
/// * [try_convert_ref](fn.try_convert_ref.html)
#[inline]
pub unsafe fn convert_ref_unchecked<From: SupersetOf<To>, To>(t: &From) -> To {
t.to_subset_unchecked()