From e75fe80966e1e30541e8190f45f32ae92b84e606 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?S=C3=A9bastien=20Crozet?= Date: Wed, 24 Jul 2013 16:50:40 +0200 Subject: [PATCH] Add documentation. --- src/adaptors/rotmat.rs | 26 ++++++++++++++++++++++++++ src/adaptors/transform.rs | 32 ++++++++++++++++++++++++++++++-- src/dmat.rs | 28 +++++++++++++++++++++++++--- src/dvec.rs | 13 ++++++++++++- src/mat.rs | 12 +++++++++++- src/nalgebra.rc | 6 +++++- src/traits/basis.rs | 28 ++++++++++++++++++++++++++-- src/traits/column.rs | 7 +++++-- src/traits/dim.rs | 36 ++++++++++++++---------------------- src/traits/homogeneous.rs | 6 ++++++ src/traits/indexable.rs | 14 +++++++++++--- src/traits/iterable.rs | 4 ++++ src/traits/mat_cast.rs | 7 ++++++- src/traits/rotation.rs | 26 +++++++++++++++++++++----- src/traits/sample.rs | 14 ++++++++++++++ src/traits/sub_dot.rs | 3 ++- src/traits/transformation.rs | 15 +++++++++++++++ src/traits/translation.rs | 10 +++++++++- src/traits/vec_cast.rs | 7 ++++++- src/vec.rs | 36 ++++++++++++++++++++++++++++++++++-- src/vec0_spec.rs | 2 ++ src/vec_macros.rs | 2 ++ 22 files changed, 286 insertions(+), 48 deletions(-) diff --git a/src/adaptors/rotmat.rs b/src/adaptors/rotmat.rs index 86a51438..2c29b8fa 100644 --- a/src/adaptors/rotmat.rs +++ b/src/adaptors/rotmat.rs @@ -16,18 +16,23 @@ use vec::Vec1; use mat::{Mat2, Mat3}; use vec::Vec3; +/// Matrix wrapper representing rotation matrix. It is built uppon another matrix and ensures (at +/// the type-level) that it will always represent a rotation. Rotation matrices have some +/// properties useful for performances, like the fact that the inversion is simply a transposition. #[deriving(Eq, ToStr, Clone)] pub struct Rotmat { priv submat: M } impl Rotmat { + /// Gets a copy of the internal representation of the rotation. pub fn submat(&self) -> M { self.submat.clone() } } impl> Rotmat> { + /// Builds a 2 dimensional rotation matrix from an angle in radian. pub fn from_angle(angle: N) -> Rotmat> { let (sia, coa) = angle.sin_cos(); @@ -38,6 +43,11 @@ impl> Rotmat> impl Rotmat> { + /// Builds a 3 dimensional rotation matrix from an axis and an angle. + /// + /// # Arguments + /// * `axisangle` - A vector representing the rotation. Its magnitude is the amount of rotation + /// in radian. Its direction is the axis of rotation. pub fn from_axis_angle(axisangle: Vec3) -> Rotmat> { if axisangle.sqnorm().is_zero() @@ -76,6 +86,15 @@ impl Rotmat> impl Rotmat> { + /// Reorient this matrix such that its local `x` axis points to a given point. Note that the + /// usually known `look_at` function does the same thing but with the `z` axis. See `look_at_z` + /// for that. + /// + /// # Arguments + /// * at - The point to look at. It is also the direction the matrix `x` axis will be aligned + /// with + /// * up - Vector pointing `up`. The only requirement of this parameter is to not be colinear + /// with `at`. Non-colinearity is not checked. pub fn look_at(&mut self, at: &Vec3, up: &Vec3) { let xaxis = at.normalized(); @@ -87,6 +106,13 @@ impl Rotmat> xaxis.z , yaxis.z , zaxis.z) } + /// Reorient this matrix such that its local `z` axis points to a given point. + /// + /// # Arguments + /// * at - The point to look at. It is also the direction the matrix `y` axis will be aligned + /// with + /// * up - Vector pointing `up`. The only requirement of this parameter is to not be colinear + /// with `at`. Non-colinearity is not checked. pub fn look_at_z(&mut self, at: &Vec3, up: &Vec3) { let zaxis = at.normalized(); diff --git a/src/adaptors/transform.rs b/src/adaptors/transform.rs index 073f2728..7780578b 100644 --- a/src/adaptors/transform.rs +++ b/src/adaptors/transform.rs @@ -15,6 +15,13 @@ use adaptors::rotmat::Rotmat; use vec::Vec3; use mat::Mat3; +/// Matrix-Vector wrapper used to represent a matrix multiplication followed by a translation. +/// Usually, a matrix in homogeneous coordinate is used to be able to apply an affine transform with +/// a translation to a vector. This is weird because it makes a `n`-dimentional transformation be +/// an `n + 1`-matrix. Using the `Transform` wrapper avoid homogeneous coordinates by having the +/// translation separate from the other transformations. This is particularity useful when the +/// underlying transform is a rotation (see `Rotmat`): this makes inversion much faster than +/// inverting the homogeneous matrix itself. #[deriving(Eq, ToStr, Clone)] pub struct Transform { @@ -24,6 +31,7 @@ pub struct Transform impl Transform { + /// Builds a new transform from a matrix and a vector. #[inline] pub fn new(mat: M, trans: V) -> Transform { Transform { submat: mat, subtrans: trans } } @@ -31,10 +39,12 @@ impl Transform impl Transform { + /// Gets a copy of the internal matrix. #[inline] pub fn submat(&self) -> M { self.submat.clone() } + /// Gets a copy of the internal translation. #[inline] pub fn subtrans(&self) -> V { self.subtrans.clone() } @@ -42,12 +52,31 @@ impl Transform impl Transform>, Vec3> { + /// Reorient and translate this transformation such that its local `x` axis points to a given + /// direction. Note that the usually known `look_at` function does the same thing but with the + /// `z` axis. See `look_at_z` for that. + /// + /// # Arguments + /// * eye - The new translation of the transformation. + /// * at - The point to look at. `at - eye` is the direction the matrix `x` axis will be + /// aligned with + /// * up - Vector pointing `up`. The only requirement of this parameter is to not be colinear + /// with `at`. Non-colinearity is not checked. pub fn look_at(&mut self, eye: &Vec3, at: &Vec3, up: &Vec3) { self.submat.look_at(&(*at - *eye), up); self.subtrans = eye.clone(); } + /// Reorient and translate this transformation such that its local `z` axis points to a given + /// direction. + /// + /// # Arguments + /// * eye - The new translation of the transformation. + /// * at - The point to look at. `at - eye` is the direction the matrix `x` axis will be + /// aligned with + /// * up - Vector pointing `up`. The only requirement of this parameter is to not be colinear + /// with `at`. Non-colinearity is not checked. pub fn look_at_z(&mut self, eye: &Vec3, at: &Vec3, up: &Vec3) { self.submat.look_at_z(&(*at - *eye), up); @@ -281,8 +310,7 @@ FromHomogeneous for Transform { fn from(m: &M) -> Transform { - Transform::new(FromHomogeneous::from(m), - m.column(Dim::dim::() - 1)) + Transform::new(FromHomogeneous::from(m), m.column(Dim::dim::() - 1)) } } diff --git a/src/dmat.rs b/src/dmat.rs index 2572f316..7a7f69d5 100644 --- a/src/dmat.rs +++ b/src/dmat.rs @@ -9,21 +9,33 @@ use traits::transpose::Transpose; use traits::rlmul::{RMul, LMul}; use dvec::{DVec, zero_vec_with_dim}; +/// Square matrix with a dimension unknown at compile-time. #[deriving(Eq, ToStr, Clone)] pub struct DMat { - dim: uint, // FIXME: handle more than just square matrices - mij: ~[N] + priv dim: uint, // FIXME: handle more than just square matrices + priv mij: ~[N] } +/// Builds a matrix filled with zeros. +/// +/// # Arguments +/// * `dim` - The dimension of the matrix. A `dim`-dimensional matrix contains `dim * dim` +/// components. #[inline] pub fn zero_mat_with_dim(dim: uint) -> DMat { DMat { dim: dim, mij: from_elem(dim * dim, Zero::zero()) } } +/// Tests if all components of the matrix are zeroes. #[inline] pub fn is_zero_mat(mat: &DMat) -> bool { mat.mij.iter().all(|e| e.is_zero()) } +/// Builds an identity matrix. +/// +/// # Arguments +/// * `dim` - The dimension of the matrix. A `dim`-dimensional matrix contains `dim * dim` +/// components. #[inline] pub fn one_mat_with_dim(dim: uint) -> DMat { @@ -39,9 +51,14 @@ pub fn one_mat_with_dim(dim: uint) -> DMat impl DMat { #[inline] - pub fn offset(&self, i: uint, j: uint) -> uint + fn offset(&self, i: uint, j: uint) -> uint { i * self.dim + j } + /// Changes the value of a component of the matrix. + /// + /// # Arguments + /// * `i` - 0-based index of the line to be changed + /// * `j` - 0-based index of the column to be changed #[inline] pub fn set(&mut self, i: uint, j: uint, t: &N) { @@ -50,6 +67,11 @@ impl DMat self.mij[self.offset(i, j)] = t.clone() } + /// Reads the value of a component of the matrix. + /// + /// # Arguments + /// * `i` - 0-based index of the line to be read + /// * `j` - 0-based index of the column to be read #[inline] pub fn at(&self, i: uint, j: uint) -> N { diff --git a/src/dvec.rs b/src/dvec.rs index 74fde06b..e751c5ac 100644 --- a/src/dvec.rs +++ b/src/dvec.rs @@ -13,16 +13,23 @@ use traits::norm::Norm; use traits::translation::{Translation, Translatable}; use traits::scalar_op::{ScalarMul, ScalarDiv, ScalarAdd, ScalarSub}; +/// Vector with a dimension unknown at compile-time. #[deriving(Eq, Ord, ToStr, Clone)] pub struct DVec { + /// Components of the vector. Contains as much elements as the vector dimension. at: ~[N] } +/// Builds a vector filled with zeros. +/// +/// # Arguments +/// * `dim` - The dimension of the vector. #[inline] pub fn zero_vec_with_dim(dim: uint) -> DVec { DVec { at: from_elem(dim, Zero::zero::()) } } +/// Tests if all components of the vector are zeroes. #[inline] pub fn is_zero_vec(vec: &DVec) -> bool { vec.at.iter().all(|e| e.is_zero()) } @@ -52,9 +59,11 @@ impl> FromIterator for DVec } } -// FIXME: is Clone needed? impl> DVec { + /// Computes the canonical basis for the given dimension. A canonical basis is a set of + /// vectors, mutually orthogonal, with all its component equal to 0.0 exept one which is equal to + /// 1.0. pub fn canonical_basis_with_dim(dim: uint) -> ~[DVec] { let mut res : ~[DVec] = ~[]; @@ -71,6 +80,8 @@ impl> DVec res } + /// Computes a basis of the space orthogonal to the vector. If the input vector is of dimension + /// `n`, this will return `n - 1` vectors. pub fn orthogonal_subspace_basis(&self) -> ~[DVec] { // compute the basis of the orthogonal subspace using Gram-Schmidt diff --git a/src/mat.rs b/src/mat.rs index fbced08d..99cafd53 100644 --- a/src/mat.rs +++ b/src/mat.rs @@ -1,3 +1,5 @@ +#[allow(missing_doc)]; // we allow missing to avoid having to document the mij components. + use std::cast; use std::uint::iterate; use std::num::{One, Zero}; @@ -28,9 +30,12 @@ pub use traits::transpose::*; mod mat_macros; +/// Square matrix of dimension 1. #[deriving(Eq, Ord, Encodable, Decodable, Clone, DeepClone, IterBytes, Rand, Zero, ToStr)] pub struct Mat1 -{ m11: N } +{ + m11: N +} mat_impl!(Mat1, m11) mat_cast_impl!(Mat1, m11) @@ -50,6 +55,7 @@ column_impl!(Mat1, 1) to_homogeneous_impl!(Mat1, Mat2, 1, 2) from_homogeneous_impl!(Mat1, Mat2, 1, 2) +/// Square matrix of dimension 2. #[deriving(Eq, Ord, Encodable, Decodable, Clone, DeepClone, IterBytes, Rand, Zero, ToStr)] pub struct Mat2 { @@ -78,6 +84,7 @@ column_impl!(Mat2, 2) to_homogeneous_impl!(Mat2, Mat3, 2, 3) from_homogeneous_impl!(Mat2, Mat3, 2, 3) +/// Square matrix of dimension 3. #[deriving(Eq, Ord, Encodable, Decodable, Clone, DeepClone, IterBytes, Rand, Zero, ToStr)] pub struct Mat3 { @@ -110,6 +117,7 @@ column_impl!(Mat3, 3) to_homogeneous_impl!(Mat3, Mat4, 3, 4) from_homogeneous_impl!(Mat3, Mat4, 3, 4) +/// Square matrix of dimension 4. #[deriving(Eq, Ord, Encodable, Decodable, Clone, DeepClone, IterBytes, Rand, Zero, ToStr)] pub struct Mat4 { @@ -150,6 +158,7 @@ column_impl!(Mat4, 4) to_homogeneous_impl!(Mat4, Mat5, 4, 5) from_homogeneous_impl!(Mat4, Mat5, 4, 5) +/// Square matrix of dimension 5. #[deriving(Eq, Ord, Encodable, Decodable, Clone, DeepClone, IterBytes, Rand, Zero, ToStr)] pub struct Mat5 { @@ -196,6 +205,7 @@ column_impl!(Mat5, 5) to_homogeneous_impl!(Mat5, Mat6, 5, 6) from_homogeneous_impl!(Mat5, Mat6, 5, 6) +/// Square matrix of dimension 6. #[deriving(Eq, Ord, Encodable, Decodable, Clone, DeepClone, IterBytes, Rand, Zero, ToStr)] pub struct Mat6 { diff --git a/src/nalgebra.rc b/src/nalgebra.rc index 5e27fadb..814c9a52 100644 --- a/src/nalgebra.rc +++ b/src/nalgebra.rc @@ -8,7 +8,11 @@ , author = "Sébastien Crozet" , uuid = "1E96070F-4778-4EC1-B080-BF69F7048216")]; #[crate_type = "lib"]; -#[warn(non_camel_case_types)] +#[deny(non_camel_case_types)]; +#[deny(non_uppercase_statics)]; +#[deny(unnecessary_qualification)]; +#[deny(missing_doc)]; +#[deny(warnings)]; extern mod std; extern mod extra; diff --git a/src/traits/basis.rs b/src/traits/basis.rs index 88a75909..65073d99 100644 --- a/src/traits/basis.rs +++ b/src/traits/basis.rs @@ -1,7 +1,31 @@ +/// Traits of objecs which can form a basis. pub trait Basis { - /// Computes the canonical basis of the space in which this object lives. - // FIXME: implement the for loop protocol? + /// Iterate through the canonical basis of the space in which this object lives. fn canonical_basis(&fn(Self)); + + /// Iterate through a basis of the subspace orthogonal to `self`. fn orthonormal_subspace_basis(&self, &fn(Self)); + + /// Creates the canonical basis of the space in which this object lives. + fn canonical_basis_list() -> ~[Self] + { + let mut res = ~[]; + + do Basis::canonical_basis:: |elem| + { res.push(elem) } + + res + } + + /// Creates a basis of the subspace orthogonal to `self`. + fn orthonormal_subspace_basis_list(&self) -> ~[Self] + { + let mut res = ~[]; + + do self.orthonormal_subspace_basis |elem| + { res.push(elem) } + + res + } } diff --git a/src/traits/column.rs b/src/traits/column.rs index 25b69e1f..af278e89 100644 --- a/src/traits/column.rs +++ b/src/traits/column.rs @@ -1,5 +1,8 @@ +/// Traits to access columns of a matrix. pub trait Column { - fn set_column(&mut self, uint, C); - fn column(&self, uint) -> C; + /// Reads the `i`-th column of `self`. + fn column(&self, i: uint) -> C; + /// Writes the `i`-th column of `self`. + fn set_column(&mut self, i: uint, C); } diff --git a/src/traits/dim.rs b/src/traits/dim.rs index 49f007ea..a77596b4 100644 --- a/src/traits/dim.rs +++ b/src/traits/dim.rs @@ -12,63 +12,55 @@ pub trait Dim { /// Dimensional token for 0-dimensions. Dimensional tokens are the preferred /// way to specify at the type level the dimension of n-dimensional objects. #[deriving(Eq, Ord, ToStr)] -pub struct d0; +pub struct D0; /// Dimensional token for 1-dimension. Dimensional tokens are the preferred /// way to specify at the type level the dimension of n-dimensional objects. #[deriving(Eq, Ord, ToStr)] -pub struct d1; +pub struct D1; /// Dimensional token for 2-dimensions. Dimensional tokens are the preferred /// way to specify at the type level the dimension of n-dimensional objects. #[deriving(Eq, Ord, ToStr)] -pub struct d2; +pub struct D2; /// Dimensional token for 3-dimensions. Dimensional tokens are the preferred /// way to specify at the type level the dimension of n-dimensional objects. #[deriving(Eq, Ord, ToStr)] -pub struct d3; +pub struct D3; /// Dimensional token for 4-dimensions. Dimensional tokens are the preferred /// way to specify at the type level the dimension of n-dimensional objects. #[deriving(Eq, Ord, ToStr)] -pub struct d4; +pub struct D4; /// Dimensional token for 5-dimensions. Dimensional tokens are the preferred /// way to specify at the type level the dimension of n-dimensional objects. #[deriving(Eq, Ord, ToStr)] -pub struct d5; +pub struct D5; /// Dimensional token for 6-dimensions. Dimensional tokens are the preferred /// way to specify at the type level the dimension of n-dimensional objects. #[deriving(Eq, Ord, ToStr)] -pub struct d6; +pub struct D6; -/// Dimensional token for 7-dimensions. Dimensional tokens are the preferred -/// way to specify at the type level the dimension of n-dimensional objects. -#[deriving(Eq, Ord, ToStr)] -pub struct d7; - -impl Dim for d0 +impl Dim for D0 { fn dim() -> uint { 0 } } -impl Dim for d1 +impl Dim for D1 { fn dim() -> uint { 1 } } -impl Dim for d2 +impl Dim for D2 { fn dim() -> uint { 2 } } -impl Dim for d3 +impl Dim for D3 { fn dim() -> uint { 3 } } -impl Dim for d4 +impl Dim for D4 { fn dim() -> uint { 4 } } -impl Dim for d5 +impl Dim for D5 { fn dim() -> uint { 5 } } -impl Dim for d6 +impl Dim for D6 { fn dim() -> uint { 6 } } - -impl Dim for d7 -{ fn dim() -> uint { 7 } } diff --git a/src/traits/homogeneous.rs b/src/traits/homogeneous.rs index 75cbdbec..08e2b907 100644 --- a/src/traits/homogeneous.rs +++ b/src/traits/homogeneous.rs @@ -1,9 +1,15 @@ +/// Traits of objects which can be put in homogeneous coordinates. pub trait ToHomogeneous { + /// Gets the homogeneous coordinates version of this object. fn to_homogeneous(&self) -> U; } +/// Traits of objects which can be build from an homogeneous coordinate representation. pub trait FromHomogeneous { + /// Builds an object with its homogeneous coordinate version. Note this it is not required for + /// `from` to be the iverse of `to_homogeneous`. Typically, `from` will remove some informations + /// unrecoverable by `to_homogeneous`. fn from(&U) -> Self; } diff --git a/src/traits/indexable.rs b/src/traits/indexable.rs index a2f7a29b..bd4a886d 100644 --- a/src/traits/indexable.rs +++ b/src/traits/indexable.rs @@ -2,9 +2,17 @@ // however, it is needed because std::ops::Index is (strangely) to poor: it // does not have a function to set values. // Also, using Index with tuples crashes. +/// This is a workaround trait. +/// +/// It exists because the `Index` trait cannot be used to express write access. +/// Thus, this is the same as the `Index` trait but without the syntactic sugar and with a method +/// to write to a specific index. pub trait Indexable { - fn at(&self, Index) -> Res; - fn set(&mut self, Index, Res); - fn swap(&mut self, Index, Index); + /// Reads the `i`-th element of `self`. + fn at(&self, i: Index) -> Res; + /// Writes to the `i`-th element of `self`. + fn set(&mut self, i: Index, Res); + /// Swaps the `i`-th element of `self` with its `j`-th element. + fn swap(&mut self, i: Index, j: Index); } diff --git a/src/traits/iterable.rs b/src/traits/iterable.rs index 2ac6eceb..45a53a59 100644 --- a/src/traits/iterable.rs +++ b/src/traits/iterable.rs @@ -1,12 +1,16 @@ use std::vec; +/// Traits of objects which can be iterated through like a vector. pub trait Iterable { + /// Gets a vector-like read-only iterator. fn iter<'l>(&'l self) -> vec::VecIterator<'l, N>; } +/// Traits of mutable objects which can be iterated through like a vector. pub trait IterableMut { + /// Gets a vector-like read-write iterator. fn mut_iter<'l>(&'l mut self) -> vec::VecMutIterator<'l, N>; } diff --git a/src/traits/mat_cast.rs b/src/traits/mat_cast.rs index dfa9e21a..3d002892 100644 --- a/src/traits/mat_cast.rs +++ b/src/traits/mat_cast.rs @@ -1,2 +1,7 @@ +/// Trait of matrices which can be converted to another matrix. Used to change the type of a matrix +/// components. pub trait MatCast -{ fn from(Self) -> M; } +{ + /// Converts `m` to have the type `M`. + fn from(m: Self) -> M; +} diff --git a/src/traits/rotation.rs b/src/traits/rotation.rs index a83ff469..f17e7d0c 100644 --- a/src/traits/rotation.rs +++ b/src/traits/rotation.rs @@ -8,12 +8,16 @@ pub trait Rotation /// Gets the rotation associated with this object. fn rotation(&self) -> V; + /// Gets the inverse rotation associated with this object. fn inv_rotation(&self) -> V; - /// In-place version of `rotated`. + /// In-place version of `rotated` (see the `Rotatable` trait). fn rotate_by(&mut self, &V); } +/// Trait of objects which can be put on an alternate form which represent a rotation. This is +/// typically implemented by structures requiring an internal restructuration to be able to +/// represent a rotation. pub trait Rotatable> { /// Appends a rotation from an alternative representation. Such @@ -21,9 +25,13 @@ pub trait Rotatable> fn rotated(&self, &V) -> Res; } +/// Trait of objects able to rotate other objects. This is typically implemented by matrices which +/// rotate vectors. pub trait Rotate { + /// Apply a rotation to an object. fn rotate(&self, &V) -> V; + /// Apply an inverse rotation to an object. fn inv_rotate(&self, &V) -> V; } @@ -49,6 +57,12 @@ pub fn rotated_wrt_point, res } +/// Rotates an object using a specific center of rotation. +/// +/// # Arguments +/// * `m` - the object to be rotated +/// * `ammount` - the rotation to be applied +/// * `center` - the new center of rotation #[inline] pub fn rotate_wrt_point + Translation, LV: Neg, @@ -63,8 +77,9 @@ pub fn rotate_wrt_point + Translation, /** * Applies a rotation centered on the input translation. * - * - `m`: the object to be rotated. - * - `ammount`: the rotation to apply. + * # Arguments + * * `m` - the object to be rotated. + * * `ammount` - the rotation to apply. */ #[inline] pub fn rotated_wrt_center + Translation, @@ -77,8 +92,9 @@ pub fn rotated_wrt_center + Translation, /** * Applies a rotation centered on the input translation. * - * - `m`: the object to be rotated. - * - `ammount`: the rotation to apply. + * # Arguments + * * `m` - the object to be rotated. + * * `ammount` - the rotation to apply. */ #[inline] pub fn rotate_wrt_center + Translation + Rotation, diff --git a/src/traits/sample.rs b/src/traits/sample.rs index a0ee726d..7a47508b 100644 --- a/src/traits/sample.rs +++ b/src/traits/sample.rs @@ -1,4 +1,18 @@ +/// Traits of vectors able to sample a sphere. The number of sample must be sufficient to +/// approximate a sphere using support mapping functions. pub trait UniformSphereSample { + /// Iterate throught the samples. pub fn sample(&fn(&'static Self)); + + /// Gets the list of all samples. + pub fn sample_list() -> ~[&'static Self] + { + let mut res = ~[]; + + do UniformSphereSample::sample:: |s| + { res.push(s) } + + res + } } diff --git a/src/traits/sub_dot.rs b/src/traits/sub_dot.rs index 89fba981..97f85642 100644 --- a/src/traits/sub_dot.rs +++ b/src/traits/sub_dot.rs @@ -1,9 +1,10 @@ use traits::dot::Dot; +/// Traits of objects with a subtract and a dot product. Exists only for optimization purpose. pub trait SubDot : Sub + Dot { /** - * Short-cut to compute the projecton of a point on a vector, but without + * Short-cut to compute the projection of a point on a vector, but without * computing intermediate vectors. * This must be equivalent to: * diff --git a/src/traits/transformation.rs b/src/traits/transformation.rs index 2925b557..36c8e5ad 100644 --- a/src/traits/transformation.rs +++ b/src/traits/transformation.rs @@ -1,21 +1,36 @@ +/// Trait of object which represent a transformation, and to wich new transformations can +/// be appended. A transformation is assumed to be an isomitry without translation +/// and without reflexion. pub trait Transformation { + /// Gets the transformation associated with this object. fn transformation(&self) -> M; + /// Gets the inverse transformation associated with this object. fn inv_transformation(&self) -> M; + /// In-place version of `transformed` (see the `Transformable` trait). fn transform_by(&mut self, &M); } +/// Trait of objects able to transform other objects. This is typically implemented by matrices which +/// transform vectors. pub trait Transform { // XXX: sadly we cannot call this `transform` as it conflicts with the // iterators' `transform` function (which seems always exist). + /// Apply a transformation to an object. fn transform_vec(&self, &V) -> V; + /// Apply an inverse transformation to an object. fn inv_transform(&self, &V) -> V; } +/// Trait of objects which can be put on an alternate form which represent a transformation. This is +/// typically implemented by structures requiring an internal restructuration to be able to +/// represent a transformation. pub trait Transformable> { + /// Appends a transformation from an alternative representation. Such + /// representation has the same format as the one returned by `transformation`. fn transformed(&self, &M) -> Res; } diff --git a/src/traits/translation.rs b/src/traits/translation.rs index 5564a2b3..7228ed3f 100644 --- a/src/traits/translation.rs +++ b/src/traits/translation.rs @@ -6,18 +6,26 @@ pub trait Translation /// Gets the translation associated with this object. fn translation(&self) -> V; + /// Gets the inverse translation associated with this object. fn inv_translation(&self) -> V; - /// In-place version of `translate`. + /// In-place version of `translated` (see the `Translatable` trait). fn translate_by(&mut self, &V); } +/// Trait of objects able to rotate other objects. This is typically implemented by matrices which +/// rotate vectors. pub trait Translate { + /// Apply a translation to an object. fn translate(&self, &V) -> V; + /// Apply an inverse translation to an object. fn inv_translate(&self, &V) -> V; } +/// Trait of objects which can be put on an alternate form which represent a translation. This is +/// typically implemented by structures requiring an internal restructuration to be able to +/// represent a translation. pub trait Translatable> { /// Appends a translation from an alternative representation. Such diff --git a/src/traits/vec_cast.rs b/src/traits/vec_cast.rs index e16ed03a..44089c5b 100644 --- a/src/traits/vec_cast.rs +++ b/src/traits/vec_cast.rs @@ -1,2 +1,7 @@ +/// Trait of vectors which can be converted to another matrix. Used to change the type of a vector +/// components. pub trait VecCast -{ fn from(Self) -> V; } +{ + /// Converts `v` to have the type `V`. + fn from(v: Self) -> V; +} diff --git a/src/vec.rs b/src/vec.rs index 3f1da03c..52946527 100644 --- a/src/vec.rs +++ b/src/vec.rs @@ -27,12 +27,17 @@ pub use traits::scalar_op::*; mod vec_macros; +/// Vector of dimension 0. #[deriving(Eq, Ord, Encodable, Decodable, Clone, DeepClone, Rand, Zero, ToStr)] pub struct Vec0; +/// Vector of dimension 1. #[deriving(Eq, Ord, Encodable, Decodable, Clone, DeepClone, IterBytes, Rand, Zero, ToStr)] pub struct Vec1 -{ x: N } +{ + /// First component of the vector. + x: N +} new_impl!(Vec1, x) vec_cast_impl!(Vec1, x) @@ -61,10 +66,13 @@ iterable_mut_impl!(Vec1, 1) to_homogeneous_impl!(Vec1, Vec2, y, x) from_homogeneous_impl!(Vec1, Vec2, y, x) +/// Vector of dimension 2. #[deriving(Eq, Ord, Encodable, Decodable, Clone, DeepClone, IterBytes, Rand, Zero, ToStr)] pub struct Vec2 { + /// First component of the vector. x: N, + /// Second component of the vector. y: N } @@ -95,14 +103,20 @@ iterable_mut_impl!(Vec2, 2) to_homogeneous_impl!(Vec2, Vec3, z, x, y) from_homogeneous_impl!(Vec2, Vec3, z, x, y) +/// Vector of dimension 3. #[deriving(Eq, Ord, Encodable, Decodable, Clone, DeepClone, IterBytes, Rand, Zero, ToStr)] pub struct Vec3 + { + /// First component of the vector. x: N, + /// Second component of the vector. y: N, + /// Third component of the vector. z: N } + new_impl!(Vec3, x, y, z) vec_cast_impl!(Vec3, x, y, z) indexable_impl!(Vec3, 3) @@ -130,12 +144,17 @@ iterable_mut_impl!(Vec3, 3) to_homogeneous_impl!(Vec3, Vec4, w, x, y, z) from_homogeneous_impl!(Vec3, Vec4, w, x, y, z) +/// Vector of dimension 4. #[deriving(Eq, Ord, Encodable, Decodable, Clone, DeepClone, IterBytes, Rand, Zero, ToStr)] pub struct Vec4 { + /// First component of the vector. x: N, + /// Second component of the vector. y: N, + /// Third component of the vector. z: N, + /// Fourth component of the vector. w: N } @@ -166,14 +185,20 @@ iterable_mut_impl!(Vec4, 4) to_homogeneous_impl!(Vec4, Vec5, a, x, y, z, w) from_homogeneous_impl!(Vec4, Vec5, a, x, y, z, w) +/// Vector of dimension 5. #[deriving(Eq, Ord, Encodable, Decodable, Clone, DeepClone, IterBytes, Rand, Zero, ToStr)] pub struct Vec5 { + /// First component of the vector. x: N, + /// Second component of the vector. y: N, + /// Third component of the vector. z: N, + /// Fourth component of the vector. w: N, - a: N, + /// Fifth of the vector. + a: N } new_impl!(Vec5, x, y, z, w, a) @@ -203,14 +228,21 @@ iterable_mut_impl!(Vec5, 5) to_homogeneous_impl!(Vec5, Vec6, b, x, y, z, w, a) from_homogeneous_impl!(Vec5, Vec6, b, x, y, z, w, a) +/// Vector of dimension 6. #[deriving(Eq, Ord, Encodable, Decodable, Clone, DeepClone, IterBytes, Rand, Zero, ToStr)] pub struct Vec6 { + /// First component of the vector. x: N, + /// Second component of the vector. y: N, + /// Third component of the vector. z: N, + /// Fourth component of the vector. w: N, + /// Fifth of the vector. a: N, + /// Sixth component of the vector. b: N } diff --git a/src/vec0_spec.rs b/src/vec0_spec.rs index 37e28644..b576b729 100644 --- a/src/vec0_spec.rs +++ b/src/vec0_spec.rs @@ -19,6 +19,7 @@ use vec; impl vec::Vec0 { + /// Creates a new vector. #[inline] pub fn new() -> vec::Vec0 { vec::Vec0 } @@ -41,6 +42,7 @@ impl Indexable for vec::Vec0 impl vec::Vec0 { + /// Creates a new vector. The parameter is not taken in account. #[inline] pub fn new_repeat(_: N) -> vec::Vec0 { vec::Vec0 } diff --git a/src/vec_macros.rs b/src/vec_macros.rs index ad099cb4..754c07e8 100644 --- a/src/vec_macros.rs +++ b/src/vec_macros.rs @@ -4,6 +4,7 @@ macro_rules! new_impl( ($t: ident, $comp0: ident $(,$compN: ident)*) => ( impl $t { + /// Creates a new vector. #[inline] pub fn new($comp0: N $( , $compN: N )*) -> $t { @@ -49,6 +50,7 @@ macro_rules! new_repeat_impl( ($t: ident, $param: ident, $comp0: ident $(,$compN: ident)*) => ( impl $t { + /// Creates a new vector with all its components equal to a given value. #[inline] pub fn new_repeat($param: N) -> $t {