diff --git a/nalgebra-glm/src/geometric.rs b/nalgebra-glm/src/geometric.rs index a5d8ff10..57355bbc 100644 --- a/nalgebra-glm/src/geometric.rs +++ b/nalgebra-glm/src/geometric.rs @@ -9,6 +9,10 @@ pub fn cross(x: &TVec3, y: &TVec3) -> TVec3 { } /// The distance between two points. +/// +/// # See also: +/// +/// * [`distance2`](fn.distance2.html) pub fn distance(p0: &TVec, p1: &TVec) -> N where DefaultAllocator: Alloc { (p1 - p0).norm() @@ -31,12 +35,28 @@ pub fn faceforward(n: &TVec, i: &TVec, 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(x: &TVec) -> N where DefaultAllocator: Alloc { 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(x: &TVec) -> N where DefaultAllocator: Alloc { x.norm() @@ -68,4 +88,4 @@ pub fn refract_vec(i: &TVec, n: &TVec, eta: N else { i * eta - n * (eta * dot(n, i) + k.sqrt()) } -} \ No newline at end of file +} diff --git a/nalgebra-glm/src/gtx/norm.rs b/nalgebra-glm/src/gtx/norm.rs index a59b50cf..cde4d5c7 100644 --- a/nalgebra-glm/src/gtx/norm.rs +++ b/nalgebra-glm/src/gtx/norm.rs @@ -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(p0: &TVec, p1: &TVec) -> N where DefaultAllocator: Alloc { (p1 - p0).norm_squared() @@ -34,12 +38,32 @@ pub fn l2_norm(x: &TVec) -> 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(x: &TVec) -> N where DefaultAllocator: Alloc { 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(x: &TVec) -> N where DefaultAllocator: Alloc { x.norm_squared() diff --git a/nalgebra-glm/src/lib.rs b/nalgebra-glm/src/lib.rs index 60dbdd14..905fe264 100644 --- a/nalgebra-glm/src/lib.rs +++ b/nalgebra-glm/src/lib.rs @@ -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 diff --git a/src/base/dimension.rs b/src/base/dimension.rs index 7a47d28c..c660c5a4 100644 --- a/src/base/dimension.rs +++ b/src/base/dimension.rs @@ -209,6 +209,7 @@ pub trait NamedDim: Sized + Any + Unsigned { type Name: DimName; } +/// 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; diff --git a/src/lib.rs b/src/lib.rs index 71636369..668636ef 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -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 { T::identity() } /// Gets the additive identity element. +/// +/// # See also: +/// +/// * [`one`](fn.one.html) +/// * [`origin`](../nalgebra/fn.origin.html) #[inline] pub fn zero>() -> 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 { 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: &M) -> Option { 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: &M) -> M { m.inverse() @@ -407,24 +430,49 @@ pub fn angle(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: &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: &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: &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: &V) -> V::Field { v.norm_squared() @@ -448,18 +496,33 @@ pub fn try_normalize(v: &V, min_norm: V::Field) -> Option { * */ /// The center of two points. +/// +/// # See also: +/// +/// * [distance](fn.distance.html) +/// * [distance_squared](fn.distance_squared.html) #[inline] pub fn center(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(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(p1: &P, p2: &P) -> P::Real { (p2.coordinates() - p1.coordinates()).norm_squared() @@ -470,7 +533,15 @@ pub fn distance_squared(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>(t: From) -> To { To::from_subset(&t) @@ -478,37 +549,89 @@ pub fn convert>(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, To>(t: From) -> Option { 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, 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, 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>(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, To>(t: &From) -> Option { 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, To>(t: &From) -> To { t.to_subset_unchecked()