From d25534610d69014d8b339ea90167db7b93328c37 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?S=C3=A9bastien=20Crozet?= Date: Tue, 8 Oct 2013 01:59:15 +0200 Subject: [PATCH] Add a one-line description to each free-function. This is better than nothing. --- README.md | 7 +- src/lib.rs | 6 +- src/na.rs | 210 +++++++++++++++++++++++++++++++++++++++-------------- 3 files changed, 163 insertions(+), 60 deletions(-) diff --git a/README.md b/README.md index 51bd2192..967700b6 100644 --- a/README.md +++ b/README.md @@ -1,3 +1,4 @@ +/*! # nalgebra **nalgebra** is a linear algebra library written for Rust targeting: @@ -50,12 +51,12 @@ and keeps an optimized set of tools for computational graphics and physics. Thos ```rust extern mod nalgebra; -use std::num::{Zero, One}; use nalgebra::na::{Vec3, Mat3}; +use nalgebra::na; fn main() { - let v: Vec3 = Zero::zero(); - let m: Mat3 = One::one(); + let v: Vec3 = na::zero(); + let m: Mat3 = na::one(); let _ = m * v; // matrix-vector multiplication. let _ = v * m; // vector-matrix multiplication. diff --git a/src/lib.rs b/src/lib.rs index d1c301b0..897d058f 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -51,12 +51,12 @@ and keeps an optimized set of tools for computational graphics and physics. Thos ```rust extern mod nalgebra; -use std::num::{Zero, One}; use nalgebra::na::{Vec3, Mat3}; +use nalgebra::na; fn main() { - let v: Vec3 = Zero::zero(); - let m: Mat3 = One::one(); + let v: Vec3 = na::zero(); + let m: Mat3 = na::one(); let _ = m * v; // matrix-vector multiplication. let _ = v * m; // vector-matrix multiplication. diff --git a/src/na.rs b/src/na.rs index d4c2604b..81d16a35 100644 --- a/src/na.rs +++ b/src/na.rs @@ -217,13 +217,40 @@ pub fn set_translation>(m: &mut M, v: V) { * Translate */ -/// FIXME +/// Applies a translation to a vector. +/// +/// ```rust +/// extern mod nalgebra; +/// use nalgebra::na; +/// +/// pub main() { +/// let t = na::translation3d(1.0, 1.0, 1.0); +/// let v = na::vec3(2.0, 2.0, 2.0); +/// +/// let tv = na::translate(&t, &v); +/// +/// assert!(tv == na::vec3(3.0, 3.0, 3.0)) +/// } +/// ``` #[inline(always)] pub fn translate>(m: &M, v: &V) -> V { m.translate(v) } -/// FIXME +/// Applies an inverse translation to a vector. +/// +/// ```rust +/// extern mod nalgebra; +/// use nalgebra::na; +/// +/// pub main() { +/// let t = na::translation3d(1.0, 1.0, 1.0); +/// let v = na::vec3(2.0, 2.0, 2.0); +/// +/// let tv = na::translate(&t, &v); +/// +/// assert!(tv == na::vec3(1.0, 1.0, 1.0)) +/// } #[inline(always)] pub fn inv_translate>(m: &M, v: &V) -> V { m.inv_translate(v) @@ -240,7 +267,7 @@ pub fn inv_translate>(m: &M, v: &V) -> V { /// use nalgebra::na; /// /// pub main() { -/// let t = na::rotation3d(1.0, 1.0, 1.0); +/// let t = na::rot3(1.0, 1.0, 1.0); /// /// assert!(na::rotation(t) == na::vec3(1.0, 1.0, 1.0)); /// } @@ -258,7 +285,7 @@ pub fn rotation>(m: &M) -> V { /// use nalgebra::na; /// /// pub main() { -/// let t = na::rotation3d(1.0, 1.0, 1.0); +/// let t = na::rot3(1.0, 1.0, 1.0); /// /// assert!(na::inv_rotation(t) == na::vec3(-1.0, -1.0, -1.0)); /// } @@ -268,19 +295,60 @@ pub fn inv_rotation>(m: &M) -> V { m.inv_rotation() } -/// FIXME +/// Rotates an object in-place. +/// +/// ```rust +/// extern mod nalgebra; +/// use nalgebra::na; +/// +/// pub main() { +/// let mut t = na::rot3(0.0, 0.0, 0.0); +/// let v = na::vec3(1.0, 1.0, 1.0); +/// +/// na::rotate_by(&mut t, &v); +/// +/// assert!(na::rotation(&t) == na::vec3(1.0, 1.0, 1.0)) +/// } +/// ``` #[inline(always)] pub fn rotate_by>(m: &mut M, v: &V) { m.rotate_by(v) } -/// FIXME +/// Creates a rotated copy of an object. +/// +/// ```rust +/// extern mod nalgebra; +/// use nalgebra::na; +/// +/// pub main() { +/// let t = na::rot3(0.0, 0.0, 0.0); +/// let v = na::vec3(1.0, 1.0, 1.0); +/// let rt = na::rotated(&mut t, &v); +/// +/// assert!(na::rotation(&rt) == na::vec3(1.0, 1.0, 1.0)) +/// } +/// ``` #[inline(always)] pub fn rotated>(m: &M, v: &V) -> M { m.rotated(v) } -/// FIXME +/// Sets the rotation of an object. +/// +/// ```rust +/// extern mod nalgebra; +/// use nalgebra::na; +/// +/// pub main() { +/// let mut t = na::rot3(1.0, 0.5, 0.2); +/// let v = na::vec3(1.0, 1.0, 1.0); +/// +/// na::set_rotation(&mut t, &v); +/// +/// assert!(na::rotation(&t) == na::vec3(1.0, 1.0, 1.0)) +/// } +/// ``` #[inline(always)] pub fn set_rotation>(m: &mut M, v: V) { m.set_rotation(v) @@ -290,13 +358,42 @@ pub fn set_rotation>(m: &mut M, v: V) { * Rotate */ -/// FIXME +/// Applies a rotation to a vector. +/// +/// ```rust +/// extern mod nalgebra; +/// use nalgebra::na; +/// +/// pub main() { +/// let t = na::rot3(1.0, 0.0, 0.0); +/// let v = na::vec3(0.0, 0.0, na::pi() / 2.0); +/// +/// let tv = na::rotate(&t, &v); +/// +/// assert!(tv == na::vec3(0.0, 1.0, 0.0)) +/// } +/// ``` #[inline(always)] pub fn rotate>(m: &M, v: &V) -> V { m.rotate(v) } -/// FIXME + +/// Applies an inverse rotation to a vector. +/// +/// ```rust +/// extern mod nalgebra; +/// use nalgebra::na; +/// +/// pub main() { +/// let t = na::rot3(1.0, 0.0, 0.0); +/// let v = na::vec3(0.0, 0.0, na::pi() / 2.0); +/// +/// let tv = na::rotate(&t, &v); +/// +/// assert!(tv == na::vec3(0.0, -1.0, 0.0)) +/// } +/// ``` #[inline(always)] pub fn inv_rotate>(m: &M, v: &V) -> V { m.inv_rotate(v) @@ -306,7 +403,7 @@ pub fn inv_rotate>(m: &M, v: &V) -> V { * RotationWithTranslation */ -/// FIXME +/// Creates a rotated copy of an object using a specific center of rotation. #[inline(always)] pub fn rotated_wrt_point, AV, @@ -317,7 +414,7 @@ pub fn rotated_wrt_point, m.rotated_wrt_point(amount, center) } -/// FIXME +/// In-place version of `rotated_wrt_point`. #[inline(always)] pub fn rotate_wrt_point, AV, @@ -328,7 +425,7 @@ pub fn rotate_wrt_point, m.rotate_wrt_point(amount, center) } -/// FIXME +/// Creates a rotated copy of an object using its own translation as the center of rotation. #[inline(always)] pub fn rotated_wrt_center, AV, @@ -338,7 +435,7 @@ pub fn rotated_wrt_center, m.rotated_wrt_center(amount) } -/// FIXME +/// In-place version of `rotate_wrt_center`. #[inline(always)] pub fn rotate_wrt_center, AV, @@ -352,7 +449,7 @@ pub fn rotate_wrt_center, * RotationMatrix */ -/// FIXME +/// Builds a rotation matrix from a rotation-capable object. #[inline(always)] pub fn to_rot_mat + Rotation, R: RotationMatrix>(r: &R) -> M { r.to_rot_mat() @@ -362,57 +459,57 @@ pub fn to_rot_mat + Rotation, R: RotationMatrix */ -/// FIXME +/// Applies a rotation using the absolute values of its components. #[inline(always)] pub fn absolute_rotate>(m: &M, v: &V) -> V { m.absolute_rotate(v) } /* - * Transformation + * Transformation */ -/// FIXME +/// Gets the transformation applicable by the given object. #[inline(always)] -pub fn transformation>(m: &M) -> V { +pub fn transformation>(m: &M) -> T { m.transformation() } -/// FIXME +/// Gets the inverse transformation applicable by the given object. #[inline(always)] -pub fn inv_transformation>(m: &M) -> V { +pub fn inv_transformation>(m: &M) -> T { m.inv_transformation() } -/// FIXME +/// In-place version of `transformed`. #[inline(always)] -pub fn transform_by>(m: &mut M, v: &V) { - m.transform_by(v) +pub fn transform_by>(m: &mut M, t: &T) { + m.transform_by(t) } -/// FIXME +/// Gets a transformed copy of an object. #[inline(always)] -pub fn transformed>(m: &M, v: &V) -> M { - m.transformed(v) +pub fn transformed>(m: &M, t: &T) -> M { + m.transformed(t) } -/// FIXME +/// Sets the transformation of an object. #[inline(always)] -pub fn set_transformation>(m: &mut M, v: V) { - m.set_transformation(v) +pub fn set_transformation>(m: &mut M, t: T) { + m.set_transformation(t) } /* * Transform */ -/// FIXME +/// Applies a transformation to a vector. #[inline(always)] pub fn transform>(m: &M, v: &V) -> V { m.transform(v) } -/// FIXME +/// Applies an inverse transformation to a vector. #[inline(always)] pub fn inv_transform>(m: &M, v: &V) -> V { m.inv_transform(v) @@ -422,13 +519,13 @@ pub fn inv_transform>(m: &M, v: &V) -> V { * Dot */ -/// FIXME +/// Computes the dot product of two vectors. #[inline(always)] pub fn dot, N>(a: &V, b: &V) -> N { a.dot(b) } -/// FIXME +/// Computes a subtraction followed by a dot product. #[inline(always)] pub fn sub_dot, N>(a: &V, b: &V, c: &V) -> N { a.sub_dot(b, c) @@ -438,25 +535,25 @@ pub fn sub_dot, N>(a: &V, b: &V, c: &V) -> N { * Norm */ -/// FIXME +/// Computes the L2 norm of a vector. #[inline(always)] pub fn norm, N: Algebraic>(v: &V) -> N { v.norm() } -/// FIXME +/// Computes the squared L2 norm of a vector. #[inline(always)] pub fn sqnorm, N: Algebraic>(v: &V) -> N { v.sqnorm() } -/// FIXME +/// Gets the normalized version of a vector. #[inline(always)] pub fn normalized, N: Algebraic>(v: &V) -> V { v.normalized() } -/// FIXME +/// In-place version of `normalized`. #[inline(always)] pub fn normalize, N: Algebraic>(v: &mut V) -> N { v.normalize() @@ -466,7 +563,7 @@ pub fn normalize, N: Algebraic>(v: &mut V) -> N { * Cross */ -/// FIXME +/// Computes the cross product of two vectors. #[inline(always)] pub fn cross, AV>(a: &LV, b: &LV) -> AV { a.cross(b) @@ -476,7 +573,8 @@ pub fn cross, AV>(a: &LV, b: &LV) -> AV { * CrossMatrix */ -/// FIXME +/// Given a vector, computes the matrix which, when multiplied by another vector, computes a cross +/// product. #[inline(always)] pub fn cross_matrix, M>(v: &V) -> M { v.cross_matrix() @@ -486,7 +584,7 @@ pub fn cross_matrix, M>(v: &V) -> M { * ToHomogeneous */ -/// FIXME +/// Converts a matrix or vector to homogoneous coordinates. #[inline(always)] pub fn to_homogeneous, Res>(m: &M) -> Res { m.to_homogeneous() @@ -496,7 +594,9 @@ pub fn to_homogeneous, Res>(m: &M) -> Res { * FromHomogeneous */ -/// FIXME +/// Converts a matrix or vector from homogoneous coordinates. +/// +/// w-normalization is appied. #[inline(always)] pub fn from_homogeneous>(m: &M) -> Res { FromHomogeneous::from(m) @@ -506,7 +606,9 @@ pub fn from_homogeneous>(m: &M) -> Res { * UniformSphereSample */ -/// FIXME +/// Samples the unit sphere living on the dimension as the samples types. +/// +/// The number of sampling point is implementation-specific. It is always uniform. #[inline(always)] pub fn sample_sphere(f: &fn(V)) { UniformSphereSample::sample(f) @@ -523,7 +625,7 @@ pub fn sample_sphere(f: &fn(V)) { * Absolute */ -/// FIXME +/// Computes a component-wise absolute value. #[inline(always)] pub fn absolute, Res>(m: &M) -> Res { m.absolute() @@ -533,13 +635,13 @@ pub fn absolute, Res>(m: &M) -> Res { * Inv */ -/// FIXME +/// Gets an inverted copy of a matrix. #[inline(always)] pub fn inverted(m: &M) -> Option { m.inverted() } -/// FIXME +/// In-place version of `inverted`. #[inline(always)] pub fn invert(m: &mut M) -> bool { m.invert() @@ -549,13 +651,13 @@ pub fn invert(m: &mut M) -> bool { * Transpose */ -/// FIXME +/// Gets a transposed copy of a matrix. #[inline(always)] pub fn transposed(m: &M) -> M { m.transposed() } -/// FIXME +/// In-place version of `transposed`. #[inline(always)] pub fn transpose(m: &mut M) { m.transpose() @@ -565,7 +667,7 @@ pub fn transpose(m: &mut M) { * Outer */ -/// FIXME +/// Computes the outer product of two vectors. #[inline(always)] pub fn outer, M>(a: &V, b: &V) -> M { a.outer(b) @@ -575,7 +677,7 @@ pub fn outer, M>(a: &V, b: &V) -> M { * Cov */ -/// FIXME +/// Computes the covariance of a set of observations. #[inline(always)] pub fn cov, Res>(observations: &M) -> Res { observations.cov() @@ -585,7 +687,7 @@ pub fn cov, Res>(observations: &M) -> Res { * Mean */ -/// FIXME +/// Computes the mean of a set of observations. #[inline(always)] pub fn mean>(observations: &M) -> N { observations.mean() @@ -601,7 +703,7 @@ pub fn mean>(observations: &M) -> N { * MatCast */ -/// FIXME +/// Converts a matrix to a matrix with different value type. #[inline(always)] pub fn cast_mat, Res>(m: M) -> Res { MatCast::from(m) @@ -611,7 +713,7 @@ pub fn cast_mat, Res>(m: M) -> Res { * VecCast */ -/// FIXME +/// Converts a matrix to a matrix with different value type. #[inline(always)] pub fn cast_vec, Res>(v: V) -> Res { VecCast::from(v) @@ -621,13 +723,13 @@ pub fn cast_vec, Res>(v: V) -> Res { * Basis */ -/// FIXME +/// Computes the canonical basis for a given dimension. #[inline(always)] pub fn canonical_basis(f: &fn(V) -> bool) { Basis::canonical_basis(f) } -/// FIXME +/// Computes the basis of the orthonormal subspace of a given vector. #[inline(always)] pub fn orthonormal_subspace_basis(v: &V, f: &fn(V) -> bool) { v.orthonormal_subspace_basis(f)