diff --git a/src/mat.rs b/src/mat.rs index 2976f41..18b6764 100644 --- a/src/mat.rs +++ b/src/mat.rs @@ -22,256 +22,150 @@ use quat::Quat; use num::NumAssign; -/** - * The base square matrix trait - * - * # Type parameters - * - * * `T` - The type of the elements of the matrix. Should be a floating point type. - * * `V` - The type of the row and column vectors. Should have components of a - * floating point type and have the same number of dimensions as the - * number of rows and columns in the matrix. - */ +/// The base square matrix trait +/// +/// # Type parameters +/// +/// - `T`: The type of the elements of the matrix. Should be a floating point type. +/// - `V`: The type of the row and column vectors. Should have components of a +/// floating point type and have the same number of dimensions as the +/// number of rows and columns in the matrix. pub trait BaseMat: Eq + Neg { - /** - * # Return value - * - * The column vector at `i` - */ + /// The column vector at `i` fn col<'a>(&'a self, i: uint) -> &'a V; - /** - * # Return value - * - * The row vector at `i` - */ + /// The row vector at `i` fn row(&self, i: uint) -> V; - /** - * # Return value - * - * The matrix element at `i`, `j` - */ + /// The matrix element at `i`, `j` fn elem<'a>(&'a self, i: uint, j: uint) -> &'a T; - /** - * Construct a diagonal matrix with the major diagonal set to `value` - */ + /// Construct a diagonal matrix with the major diagonal set to `value` fn from_value(value: T) -> Self; - /** - * # Return value - * - * The identity matrix - */ + /// The identity matrix fn identity() -> Self; - /** - * # Return value - * - * A matrix with all elements set to zero - */ + /// A matrix with all elements set to zero fn zero() -> Self; - /** - * # Return value - * - * The scalar multiplication of this matrix and `value` - */ + /// The scalar multiplication of this matrix and `value` fn mul_t(&self, value: T) -> Self; - /** - * # Return value - * - * The matrix vector product of the matrix and `vec` - */ + /// The matrix vector product of the matrix and `vec` fn mul_v(&self, vec: &V) -> V; - /** - * # Return value - * - * The matrix addition of the matrix and `other` - */ + /// The matrix addition of the matrix and `other` fn add_m(&self, other: &Self) -> Self; - /** - * # Return value - * - * The difference between the matrix and `other` - */ + /// The difference between the matrix and `other` fn sub_m(&self, other: &Self) -> Self; - /** - * # Return value - * - * The matrix product of the matrix and `other` - */ + /// The matrix product of the matrix and `other` fn mul_m(&self, other: &Self) -> Self; - /** - * # Return value - * - * The matrix dot product of the matrix and `other` - */ + /// The matrix dot product of the matrix and `other` fn dot(&self, other: &Self) -> T; - /** - * # Return value - * - * The determinant of the matrix - */ + /// The determinant of the matrix fn determinant(&self) -> T; - /** - * # Return value - * - * The sum of the main diagonal of the matrix - */ + /// The sum of the main diagonal of the matrix fn trace(&self) -> T; - /** - * Returns the inverse of the matrix - * - * # Return value - * - * * `Some(m)` - if the inversion was successful, where `m` is the inverted matrix - * * `None` - if the inversion was unsuccessful (because the matrix was not invertable) - */ + /// Returns the inverse of the matrix + /// + /// # Return value + /// + /// - `Some(m)`: if the inversion was successful, where `m` is the inverted matrix + /// - `None`: if the inversion was unsuccessful (because the matrix was not invertable) fn inverse(&self) -> Option; - /** - * # Return value - * - * The transposed matrix - */ + /// The transposed matrix fn transpose(&self) -> Self; - /** - * # Return value - * - * A mutable reference to the column at `i` - */ + /// A mutable reference to the column at `i` fn col_mut<'a>(&'a mut self, i: uint) -> &'a mut V; - /** - * # Return value - * - * A mutable reference to the matrix element at `i`, `j` - */ + /// A mutable reference to the matrix element at `i`, `j` fn elem_mut<'a>(&'a mut self, i: uint, j: uint) -> &'a mut T; - /** - * Swap two columns of the matrix in place - */ + /// Swap two columns of the matrix in place fn swap_cols(&mut self, a: uint, b: uint); - /** - * Swap two rows of the matrix in place - */ + /// Swap two rows of the matrix in place fn swap_rows(&mut self, a: uint, b: uint); - /** - * Sets the matrix to `other` - */ + /// Sets the matrix to `other` fn set(&mut self, other: &Self); - /** - * Sets the matrix to the identity matrix - */ + /// Sets the matrix to the identity matrix fn to_identity(&mut self); - /** - * Sets each element of the matrix to zero - */ + /// Sets each element of the matrix to zero fn to_zero(&mut self); - /** - * Multiplies the matrix by a scalar - */ + /// Multiplies the matrix by a scalar fn mul_self_t(&mut self, value: T); - /** - * Add the matrix `other` to `self` - */ + /// Add the matrix `other` to `self` fn add_self_m(&mut self, other: &Self); - /** - * Subtract the matrix `other` from `self` - */ + /// Subtract the matrix `other` from `self` fn sub_self_m(&mut self, other: &Self); - /** - * Sets the matrix to its inverse - * - * # Failure - * - * Fails if the matrix is not invertable. Make sure you check with the - * `is_invertible` method before you attempt this! - */ + /// Sets the matrix to its inverse + /// + /// # Failure + /// + /// Fails if the matrix is not invertable. Make sure you check with the + /// `is_invertible` method before you attempt this! fn invert_self(&mut self); - /** - * Sets the matrix to its transpose - */ + /// Sets the matrix to its transpose fn transpose_self(&mut self); - /** - * Check to see if the matrix is an identity matrix - * - * # Return value - * - * `true` if the matrix is approximately equal to the identity matrix - */ + /// Check to see if the matrix is an identity matrix + /// + /// # Return value + /// + /// `true` if the matrix is approximately equal to the identity matrix fn is_identity(&self) -> bool; - /** - * Check to see if the matrix is diagonal - * - * # Return value - * - * `true` all the elements outside the main diagonal are approximately - * equal to zero. - */ + /// Check to see if the matrix is diagonal + /// + /// # Return value + /// + /// `true` all the elements outside the main diagonal are approximately + /// equal to zero. fn is_diagonal(&self) -> bool; - /** - * Check to see if the matrix is rotated - * - * # Return value - * - * `true` if the matrix is not approximately equal to the identity matrix. - */ + /// Check to see if the matrix is rotated + /// + /// # Return value + /// + /// `true` if the matrix is not approximately equal to the identity matrix. fn is_rotated(&self) -> bool; - /** - * Check to see if the matrix is symmetric - * - * # Return value - * - * `true` if the matrix is approximately equal to its transpose). - */ + /// Check to see if the matrix is symmetric + /// + /// # Return value + /// + /// `true` if the matrix is approximately equal to its transpose). fn is_symmetric(&self) -> bool; - /** - * Check to see if the matrix is invertable - * - * # Return value - * - * `true` if the matrix is invertable - */ + /// Check to see if the matrix is invertable + /// + /// # Return value + /// + /// `true` if the matrix is invertable fn is_invertible(&self) -> bool; - /** - * # Return value - * - * A pointer to the first element of the matrix - */ + /// A pointer to the first element of the matrix fn to_ptr(&self) -> *T; } -/** - * A 2 x 2 matrix - */ +/// A 2 x 2 matrix pub trait BaseMat2: BaseMat { fn new(c0r0: T, c0r1: T, c1r0: T, c1r1: T) -> Self; @@ -285,9 +179,7 @@ pub trait BaseMat2: BaseMat { fn to_mat4(&self) -> Mat4; } -/** - * A 3 x 3 matrix - */ +/// A 3 x 3 matrix pub trait BaseMat3: BaseMat { fn new(c0r0:T, c0r1:T, c0r2:T, c1r0:T, c1r1:T, c1r2:T, @@ -314,9 +206,7 @@ pub trait BaseMat3: BaseMat { fn to_quat(&self) -> Quat; } -/** - * A 4 x 4 matrix - */ +/// A 4 x 4 matrix pub trait BaseMat4: BaseMat { fn new(c0r0: T, c0r1: T, c0r2: T, c0r3: T, c1r0: T, c1r1: T, c1r2: T, c1r3: T, @@ -326,19 +216,17 @@ pub trait BaseMat4: BaseMat { fn from_cols(c0: V, c1: V, c2: V, c3: V) -> Self; } -/** - * A 2 x 2 column major matrix - * - * # Type parameters - * - * * `T` - The type of the elements of the matrix. Should be a floating point type. - * - * # Fields - * - * * `x` - the first column vector of the matrix - * * `y` - the second column vector of the matrix - * * `z` - the third column vector of the matrix - */ +/// A 2 x 2 column major matrix +/// +/// # Type parameters +/// +/// - `T`: The type of the elements of the matrix. Should be a floating point type. +/// +/// # Fields +/// +/// - `x`: the first column vector of the matrix +/// - `y`: the second column vector of the matrix +/// - `z`: the third column vector of the matrix #[deriving(Eq)] pub struct Mat2 { x: Vec2, y: Vec2 } @@ -359,56 +247,50 @@ impl BaseMat> for Mat2 { self.col(i).index(j) } - /** - * Construct a 2 x 2 diagonal matrix with the major diagonal set to `value` - * - * # Arguments - * - * * `value` - the value to set the major diagonal to - * - * ~~~ - * c0 c1 - * +-----+-----+ - * r0 | val | 0 | - * +-----+-----+ - * r1 | 0 | val | - * +-----+-----+ - * ~~~ - */ + /// Construct a 2 x 2 diagonal matrix with the major diagonal set to `value` + /// + /// # Arguments + /// + /// - `value`: the value to set the major diagonal to + /// + /// ~~~ + /// c0 c1 + /// +-----+-----+ + /// r0 | val | 0 | + /// +-----+-----+ + /// r1 | 0 | val | + /// +-----+-----+ + /// ~~~ #[inline(always)] fn from_value(value: T) -> Mat2 { BaseMat2::new(value, Zero::zero(), Zero::zero(), value) } - /** - * Returns the multiplicative identity matrix - * ~~~ - * c0 c1 - * +----+----+ - * r0 | 1 | 0 | - * +----+----+ - * r1 | 0 | 1 | - * +----+----+ - * ~~~ - */ + /// Returns the multiplicative identity matrix + /// ~~~ + /// c0 c1 + /// +----+----+ + /// r0 | 1 | 0 | + /// +----+----+ + /// r1 | 0 | 1 | + /// +----+----+ + /// ~~~ #[inline(always)] fn identity() -> Mat2 { BaseMat2::new( One::one::(), Zero::zero::(), Zero::zero::(), One::one::()) } - /** - * Returns the additive identity matrix - * ~~~ - * c0 c1 - * +----+----+ - * r0 | 0 | 0 | - * +----+----+ - * r1 | 0 | 0 | - * +----+----+ - * ~~~ - */ + /// Returns the additive identity matrix + /// ~~~ + /// c0 c1 + /// +----+----+ + /// r0 | 0 | 0 | + /// +----+----+ + /// r1 | 0 | 0 | + /// +----+----+ + /// ~~~ #[inline(always)] fn zero() -> Mat2 { BaseMat2::new(Zero::zero::(), Zero::zero::(), @@ -588,23 +470,21 @@ impl BaseMat> for Mat2 { } impl BaseMat2> for Mat2 { - /** - * Construct a 2 x 2 matrix - * - * # Arguments - * - * * `c0r0`, `c0r1` - the first column of the matrix - * * `c1r0`, `c1r1` - the second column of the matrix - * - * ~~~ - * c0 c1 - * +------+------+ - * r0 | c0r0 | c1r0 | - * +------+------+ - * r1 | c0r1 | c1r1 | - * +------+------+ - * ~~~ - */ + /// Construct a 2 x 2 matrix + /// + /// # Arguments + /// + /// - `c0r0`, `c0r1`: the first column of the matrix + /// - `c1r0`, `c1r1`: the second column of the matrix + /// + /// ~~~ + /// c0 c1 + /// +------+------+ + /// r0 | c0r0 | c1r0 | + /// +------+------+ + /// r1 | c0r1 | c1r1 | + /// +------+------+ + /// ~~~ #[inline(always)] fn new(c0r0: T, c0r1: T, c1r0: T, c1r1: T) -> Mat2 { @@ -612,23 +492,21 @@ impl BaseMat2> for Mat2 { BaseVec2::new::>(c1r0, c1r1)) } - /** - * Construct a 2 x 2 matrix from column vectors - * - * # Arguments - * - * * `c0` - the first column vector of the matrix - * * `c1` - the second column vector of the matrix - * - * ~~~ - * c0 c1 - * +------+------+ - * r0 | c0.x | c1.x | - * +------+------+ - * r1 | c0.y | c1.y | - * +------+------+ - * ~~~ - */ + /// Construct a 2 x 2 matrix from column vectors + /// + /// # Arguments + /// + /// - `c0`: the first column vector of the matrix + /// - `c1`: the second column vector of the matrix + /// + /// ~~~ + /// c0 c1 + /// +------+------+ + /// r0 | c0.x | c1.x | + /// +------+------+ + /// r1 | c0.y | c1.y | + /// +------+------+ + /// ~~~ #[inline(always)] fn from_cols(c0: Vec2, c1: Vec2) -> Mat2 { Mat2 { x: c0, y: c1 } @@ -643,19 +521,17 @@ impl BaseMat2> for Mat2 { sin_theta, cos_theta) } - /** - * Returns the the matrix with an extra row and column added - * ~~~ - * c0 c1 c0 c1 c2 - * +----+----+ +----+----+----+ - * r0 | a | b | r0 | a | b | 0 | - * +----+----+ +----+----+----+ - * r1 | c | d | => r1 | c | d | 0 | - * +----+----+ +----+----+----+ - * r2 | 0 | 0 | 1 | - * +----+----+----+ - * ~~~ - */ + /// Returns the the matrix with an extra row and column added + /// ~~~ + /// c0 c1 c0 c1 c2 + /// +----+----+ +----+----+----+ + /// r0 | a | b | r0 | a | b | 0 | + /// +----+----+ +----+----+----+ + /// r1 | c | d | => r1 | c | d | 0 | + /// +----+----+ +----+----+----+ + /// r2 | 0 | 0 | 1 | + /// +----+----+----+ + /// ~~~ #[inline(always)] fn to_mat3(&self) -> Mat3 { BaseMat3::new(*self.elem(0, 0), *self.elem(0, 1), Zero::zero(), @@ -663,21 +539,19 @@ impl BaseMat2> for Mat2 { Zero::zero(), Zero::zero(), One::one()) } - /** - * Returns the the matrix with an extra two rows and columns added - * ~~~ - * c0 c1 c0 c1 c2 c3 - * +----+----+ +----+----+----+----+ - * r0 | a | b | r0 | a | b | 0 | 0 | - * +----+----+ +----+----+----+----+ - * r1 | c | d | => r1 | c | d | 0 | 0 | - * +----+----+ +----+----+----+----+ - * r2 | 0 | 0 | 1 | 0 | - * +----+----+----+----+ - * r3 | 0 | 0 | 0 | 1 | - * +----+----+----+----+ - * ~~~ - */ + /// Returns the the matrix with an extra two rows and columns added + /// ~~~ + /// c0 c1 c0 c1 c2 c3 + /// +----+----+ +----+----+----+----+ + /// r0 | a | b | r0 | a | b | 0 | 0 | + /// +----+----+ +----+----+----+----+ + /// r1 | c | d | => r1 | c | d | 0 | 0 | + /// +----+----+ +----+----+----+----+ + /// r2 | 0 | 0 | 1 | 0 | + /// +----+----+----+----+ + /// r3 | 0 | 0 | 0 | 1 | + /// +----+----+----+----+ + /// ~~~ #[inline(always)] fn to_mat4(&self) -> Mat4 { BaseMat4::new(*self.elem(0, 0), *self.elem(0, 1), Zero::zero(), Zero::zero(), @@ -753,19 +627,17 @@ mat2_type!(Mat2f) mat2_type!(Mat2f32) mat2_type!(Mat2f64) -/** - * A 3 x 3 column major matrix - * - * # Type parameters - * - * * `T` - The type of the elements of the matrix. Should be a floating point type. - * - * # Fields - * - * * `x` - the first column vector of the matrix - * * `y` - the second column vector of the matrix - * * `z` - the third column vector of the matrix - */ +/// A 3 x 3 column major matrix +/// +/// # Type parameters +/// +/// - `T`: The type of the elements of the matrix. Should be a floating point type. +/// +/// # Fields +/// +/// - `x`: the first column vector of the matrix +/// - `y`: the second column vector of the matrix +/// - `z`: the third column vector of the matrix #[deriving(Eq)] pub struct Mat3 { x: Vec3, y: Vec3, z: Vec3 } @@ -787,24 +659,22 @@ impl BaseMat> for Mat3 { self.col(i).index(j) } - /** - * Construct a 3 x 3 diagonal matrix with the major diagonal set to `value` - * - * # Arguments - * - * * `value` - the value to set the major diagonal to - * - * ~~~ - * c0 c1 c2 - * +-----+-----+-----+ - * r0 | val | 0 | 0 | - * +-----+-----+-----+ - * r1 | 0 | val | 0 | - * +-----+-----+-----+ - * r2 | 0 | 0 | val | - * +-----+-----+-----+ - * ~~~ - */ + /// Construct a 3 x 3 diagonal matrix with the major diagonal set to `value` + /// + /// # Arguments + /// + /// - `value`: the value to set the major diagonal to + /// + /// ~~~ + /// c0 c1 c2 + /// +-----+-----+-----+ + /// r0 | val | 0 | 0 | + /// +-----+-----+-----+ + /// r1 | 0 | val | 0 | + /// +-----+-----+-----+ + /// r2 | 0 | 0 | val | + /// +-----+-----+-----+ + /// ~~~ #[inline(always)] fn from_value(value: T) -> Mat3 { BaseMat3::new(value, Zero::zero(), Zero::zero(), @@ -812,19 +682,17 @@ impl BaseMat> for Mat3 { Zero::zero(), Zero::zero(), value) } - /** - * Returns the multiplicative identity matrix - * ~~~ - * c0 c1 c2 - * +----+----+----+ - * r0 | 1 | 0 | 0 | - * +----+----+----+ - * r1 | 0 | 1 | 0 | - * +----+----+----+ - * r2 | 0 | 0 | 1 | - * +----+----+----+ - * ~~~ - */ + /// Returns the multiplicative identity matrix + /// ~~~ + /// c0 c1 c2 + /// +----+----+----+ + /// r0 | 1 | 0 | 0 | + /// +----+----+----+ + /// r1 | 0 | 1 | 0 | + /// +----+----+----+ + /// r2 | 0 | 0 | 1 | + /// +----+----+----+ + /// ~~~ #[inline(always)] fn identity() -> Mat3 { BaseMat3::new(One::one::(), Zero::zero::(), Zero::zero::(), @@ -832,19 +700,17 @@ impl BaseMat> for Mat3 { Zero::zero::(), Zero::zero::(), One::one::()) } - /** - * Returns the additive identity matrix - * ~~~ - * c0 c1 c2 - * +----+----+----+ - * r0 | 0 | 0 | 0 | - * +----+----+----+ - * r1 | 0 | 0 | 0 | - * +----+----+----+ - * r2 | 0 | 0 | 0 | - * +----+----+----+ - * ~~~ - */ + /// Returns the additive identity matrix + /// ~~~ + /// c0 c1 c2 + /// +----+----+----+ + /// r0 | 0 | 0 | 0 | + /// +----+----+----+ + /// r1 | 0 | 0 | 0 | + /// +----+----+----+ + /// r2 | 0 | 0 | 0 | + /// +----+----+----+ + /// ~~~ #[inline(always)] fn zero() -> Mat3 { BaseMat3::new(Zero::zero::(), Zero::zero::(), Zero::zero::(), @@ -909,7 +775,6 @@ impl BaseMat> for Mat3 { *self.elem(2, 2) } - // #[inline(always)] fn inverse(&self) -> Option> { let d = self.determinant(); if d.approx_eq(&Zero::zero()) { @@ -1067,26 +932,24 @@ impl BaseMat> for Mat3 { } impl BaseMat3> for Mat3 { - /** - * Construct a 3 x 3 matrix - * - * # Arguments - * - * * `c0r0`, `c0r1`, `c0r2` - the first column of the matrix - * * `c1r0`, `c1r1`, `c1r2` - the second column of the matrix - * * `c2r0`, `c2r1`, `c2r2` - the third column of the matrix - * - * ~~~ - * c0 c1 c2 - * +------+------+------+ - * r0 | c0r0 | c1r0 | c2r0 | - * +------+------+------+ - * r1 | c0r1 | c1r1 | c2r1 | - * +------+------+------+ - * r2 | c0r2 | c1r2 | c2r2 | - * +------+------+------+ - * ~~~ - */ + /// Construct a 3 x 3 matrix + /// + /// # Arguments + /// + /// - `c0r0`, `c0r1`, `c0r2`: the first column of the matrix + /// - `c1r0`, `c1r1`, `c1r2`: the second column of the matrix + /// - `c2r0`, `c2r1`, `c2r2`: the third column of the matrix + /// + /// ~~~ + /// c0 c1 c2 + /// +------+------+------+ + /// r0 | c0r0 | c1r0 | c2r0 | + /// +------+------+------+ + /// r1 | c0r1 | c1r1 | c2r1 | + /// +------+------+------+ + /// r2 | c0r2 | c1r2 | c2r2 | + /// +------+------+------+ + /// ~~~ #[inline(always)] fn new(c0r0:T, c0r1:T, c0r2:T, c1r0:T, c1r1:T, c1r2:T, @@ -1096,34 +959,30 @@ impl BaseMat3> for Mat3 { BaseVec3::new::>(c2r0, c2r1, c2r2)) } - /** - * Construct a 3 x 3 matrix from column vectors - * - * # Arguments - * - * * `c0` - the first column vector of the matrix - * * `c1` - the second column vector of the matrix - * * `c2` - the third column vector of the matrix - * - * ~~~ - * c0 c1 c2 - * +------+------+------+ - * r0 | c0.x | c1.x | c2.x | - * +------+------+------+ - * r1 | c0.y | c1.y | c2.y | - * +------+------+------+ - * r2 | c0.z | c1.z | c2.z | - * +------+------+------+ - * ~~~ - */ + /// Construct a 3 x 3 matrix from column vectors + /// + /// # Arguments + /// + /// - `c0`: the first column vector of the matrix + /// - `c1`: the second column vector of the matrix + /// - `c2`: the third column vector of the matrix + /// + /// ~~~ + /// c0 c1 c2 + /// +------+------+------+ + /// r0 | c0.x | c1.x | c2.x | + /// +------+------+------+ + /// r1 | c0.y | c1.y | c2.y | + /// +------+------+------+ + /// r2 | c0.z | c1.z | c2.z | + /// +------+------+------+ + /// ~~~ #[inline(always)] fn from_cols(c0: Vec3, c1: Vec3, c2: Vec3) -> Mat3 { Mat3 { x: c0, y: c1, z: c2 } } - /** - * Construct a matrix from an angular rotation around the `x` axis - */ + /// Construct a matrix from an angular rotation around the `x` axis #[inline(always)] fn from_angle_x(radians: T) -> Mat3 { // http://en.wikipedia.org/wiki/Rotation_matrix#Basic_rotations @@ -1135,9 +994,7 @@ impl BaseMat3> for Mat3 { Zero::zero(), -sin_theta, cos_theta) } - /** - * Construct a matrix from an angular rotation around the `y` axis - */ + /// Construct a matrix from an angular rotation around the `y` axis #[inline(always)] fn from_angle_y(radians: T) -> Mat3 { // http://en.wikipedia.org/wiki/Rotation_matrix#Basic_rotations @@ -1149,9 +1006,7 @@ impl BaseMat3> for Mat3 { sin_theta, Zero::zero(), cos_theta) } - /** - * Construct a matrix from an angular rotation around the `z` axis - */ + /// Construct a matrix from an angular rotation around the `z` axis #[inline(always)] fn from_angle_z(radians: T) -> Mat3 { // http://en.wikipedia.org/wiki/Rotation_matrix#Basic_rotations @@ -1163,15 +1018,13 @@ impl BaseMat3> for Mat3 { Zero::zero(), Zero::zero(), One::one()) } - /** - * Construct a matrix from Euler angles - * - * # Arguments - * - * * `theta_x` - the angular rotation around the `x` axis (pitch) - * * `theta_y` - the angular rotation around the `y` axis (yaw) - * * `theta_z` - the angular rotation around the `z` axis (roll) - */ + /// Construct a matrix from Euler angles + /// + /// # Arguments + /// + /// - `theta_x`: the angular rotation around the `x` axis (pitch) + /// - `theta_y`: the angular rotation around the `y` axis (yaw) + /// - `theta_z`: the angular rotation around the `z` axis (roll) #[inline(always)] fn from_angle_xyz(radians_x: T, radians_y: T, radians_z: T) -> Mat3 { // http://en.wikipedia.org/wiki/Rotation_matrix#General_rotations @@ -1187,9 +1040,7 @@ impl BaseMat3> for Mat3 { sx*sz + cx*sy*cz, -sx*cz + cx*sy*sz, cx*cy) } - /** - * Construct a matrix from an axis and an angular rotation - */ + /// Construct a matrix from an axis and an angular rotation #[inline(always)] fn from_angle_axis(radians: T, axis: &Vec3) -> Mat3 { let c = radians.cos(); @@ -1219,21 +1070,19 @@ impl BaseMat3> for Mat3 { BaseMat3::from_axes(up_, side, dir_) } - /** - * Returns the the matrix with an extra row and column added - * ~~~ - * c0 c1 c2 c0 c1 c2 c3 - * +----+----+----+ +----+----+----+----+ - * r0 | a | b | c | r0 | a | b | c | 0 | - * +----+----+----+ +----+----+----+----+ - * r1 | d | e | f | => r1 | d | e | f | 0 | - * +----+----+----+ +----+----+----+----+ - * r2 | g | h | i | r2 | g | h | i | 0 | - * +----+----+----+ +----+----+----+----+ - * r3 | 0 | 0 | 0 | 1 | - * +----+----+----+----+ - * ~~~ - */ + /// Returns the the matrix with an extra row and column added + /// ~~~ + /// c0 c1 c2 c0 c1 c2 c3 + /// +----+----+----+ +----+----+----+----+ + /// r0 | a | b | c | r0 | a | b | c | 0 | + /// +----+----+----+ +----+----+----+----+ + /// r1 | d | e | f | => r1 | d | e | f | 0 | + /// +----+----+----+ +----+----+----+----+ + /// r2 | g | h | i | r2 | g | h | i | 0 | + /// +----+----+----+ +----+----+----+----+ + /// r3 | 0 | 0 | 0 | 1 | + /// +----+----+----+----+ + /// ~~~ #[inline(always)] fn to_mat4(&self) -> Mat4 { BaseMat4::new(*self.elem(0, 0), *self.elem(0, 1), *self.elem(0, 2), Zero::zero(), @@ -1242,9 +1091,7 @@ impl BaseMat3> for Mat3 { Zero::zero(), Zero::zero(), Zero::zero(), One::one()) } - /** - * Convert the matrix to a quaternion - */ + /// Convert the matrix to a quaternion #[inline(always)] fn to_quat(&self) -> Quat { // Implemented using a mix of ideas from jMonkeyEngine and Ken Shoemake's @@ -1372,20 +1219,18 @@ mat3_type!(Mat3f) mat3_type!(Mat3f32) mat3_type!(Mat3f64) -/** - * A 4 x 4 column major matrix - * - * # Type parameters - * - * * `T` - The type of the elements of the matrix. Should be a floating point type. - * - * # Fields - * - * * `x` - the first column vector of the matrix - * * `y` - the second column vector of the matrix - * * `z` - the third column vector of the matrix - * * `w` - the fourth column vector of the matrix - */ +/// A 4 x 4 column major matrix +/// +/// # Type parameters +/// +/// - `T` - The type of the elements of the matrix. Should be a floating point type. +/// +/// # Fields +/// +/// - `x`: the first column vector of the matrix +/// - `y`: the second column vector of the matrix +/// - `z`: the third column vector of the matrix +/// - `w`: the fourth column vector of the matrix #[deriving(Eq)] pub struct Mat4 { x: Vec4, y: Vec4, z: Vec4, w: Vec4 } @@ -1408,26 +1253,24 @@ impl BaseMat> for Mat4 { self.col(i).index(j) } - /** - * Construct a 4 x 4 diagonal matrix with the major diagonal set to `value` - * - * # Arguments - * - * * `value` - the value to set the major diagonal to - * - * ~~~ - * c0 c1 c2 c3 - * +-----+-----+-----+-----+ - * r0 | val | 0 | 0 | 0 | - * +-----+-----+-----+-----+ - * r1 | 0 | val | 0 | 0 | - * +-----+-----+-----+-----+ - * r2 | 0 | 0 | val | 0 | - * +-----+-----+-----+-----+ - * r3 | 0 | 0 | 0 | val | - * +-----+-----+-----+-----+ - * ~~~ - */ + /// Construct a 4 x 4 diagonal matrix with the major diagonal set to `value` + /// + /// # Arguments + /// + /// - `value`: the value to set the major diagonal to + /// + /// ~~~ + /// c0 c1 c2 c3 + /// +-----+-----+-----+-----+ + /// r0 | val | 0 | 0 | 0 | + /// +-----+-----+-----+-----+ + /// r1 | 0 | val | 0 | 0 | + /// +-----+-----+-----+-----+ + /// r2 | 0 | 0 | val | 0 | + /// +-----+-----+-----+-----+ + /// r3 | 0 | 0 | 0 | val | + /// +-----+-----+-----+-----+ + /// ~~~ #[inline(always)] fn from_value(value: T) -> Mat4 { BaseMat4::new(value, Zero::zero(), Zero::zero(), Zero::zero(), @@ -1436,21 +1279,19 @@ impl BaseMat> for Mat4 { Zero::zero(), Zero::zero(), Zero::zero(), value) } - /** - * Returns the multiplicative identity matrix - * ~~~ - * c0 c1 c2 c3 - * +----+----+----+----+ - * r0 | 1 | 0 | 0 | 0 | - * +----+----+----+----+ - * r1 | 0 | 1 | 0 | 0 | - * +----+----+----+----+ - * r2 | 0 | 0 | 1 | 0 | - * +----+----+----+----+ - * r3 | 0 | 0 | 0 | 1 | - * +----+----+----+----+ - * ~~~ - */ + /// Returns the multiplicative identity matrix + /// ~~~ + /// c0 c1 c2 c3 + /// +----+----+----+----+ + /// r0 | 1 | 0 | 0 | 0 | + /// +----+----+----+----+ + /// r1 | 0 | 1 | 0 | 0 | + /// +----+----+----+----+ + /// r2 | 0 | 0 | 1 | 0 | + /// +----+----+----+----+ + /// r3 | 0 | 0 | 0 | 1 | + /// +----+----+----+----+ + /// ~~~ #[inline(always)] fn identity() -> Mat4 { BaseMat4::new(One::one::(), Zero::zero::(), Zero::zero::(), Zero::zero::(), @@ -1459,21 +1300,19 @@ impl BaseMat> for Mat4 { Zero::zero::(), Zero::zero::(), Zero::zero::(), One::one::()) } - /** - * Returns the additive identity matrix - * ~~~ - * c0 c1 c2 c3 - * +----+----+----+----+ - * r0 | 0 | 0 | 0 | 0 | - * +----+----+----+----+ - * r1 | 0 | 0 | 0 | 0 | - * +----+----+----+----+ - * r2 | 0 | 0 | 0 | 0 | - * +----+----+----+----+ - * r3 | 0 | 0 | 0 | 0 | - * +----+----+----+----+ - * ~~~ - */ + /// Returns the additive identity matrix + /// ~~~ + /// c0 c1 c2 c3 + /// +----+----+----+----+ + /// r0 | 0 | 0 | 0 | 0 | + /// +----+----+----+----+ + /// r1 | 0 | 0 | 0 | 0 | + /// +----+----+----+----+ + /// r2 | 0 | 0 | 0 | 0 | + /// +----+----+----+----+ + /// r3 | 0 | 0 | 0 | 0 | + /// +----+----+----+----+ + /// ~~~ #[inline(always)] fn zero() -> Mat4 { BaseMat4::new(Zero::zero::(), Zero::zero::(), Zero::zero::(), Zero::zero::(), @@ -1574,7 +1413,6 @@ impl BaseMat> for Mat4 { if d.approx_eq(&Zero::zero()) { None } else { - // Gauss Jordan Elimination with partial pivoting // So take this matrix, A, augmented with the identity // and essentially reduce [A|I] @@ -1798,29 +1636,27 @@ impl BaseMat> for Mat4 { } impl BaseMat4> for Mat4 { - /** - * Construct a 4 x 4 matrix - * - * # Arguments - * - * * `c0r0`, `c0r1`, `c0r2`, `c0r3` - the first column of the matrix - * * `c1r0`, `c1r1`, `c1r2`, `c1r3` - the second column of the matrix - * * `c2r0`, `c2r1`, `c2r2`, `c2r3` - the third column of the matrix - * * `c3r0`, `c3r1`, `c3r2`, `c3r3` - the fourth column of the matrix - * - * ~~~ - * c0 c1 c2 c3 - * +------+------+------+------+ - * r0 | c0r0 | c1r0 | c2r0 | c3r0 | - * +------+------+------+------+ - * r1 | c0r1 | c1r1 | c2r1 | c3r1 | - * +------+------+------+------+ - * r2 | c0r2 | c1r2 | c2r2 | c3r2 | - * +------+------+------+------+ - * r3 | c0r3 | c1r3 | c2r3 | c3r3 | - * +------+------+------+------+ - * ~~~ - */ + /// Construct a 4 x 4 matrix + /// + /// # Arguments + /// + /// - `c0r0`, `c0r1`, `c0r2`, `c0r3`: the first column of the matrix + /// - `c1r0`, `c1r1`, `c1r2`, `c1r3`: the second column of the matrix + /// - `c2r0`, `c2r1`, `c2r2`, `c2r3`: the third column of the matrix + /// - `c3r0`, `c3r1`, `c3r2`, `c3r3`: the fourth column of the matrix + /// + /// ~~~ + /// c0 c1 c2 c3 + /// +------+------+------+------+ + /// r0 | c0r0 | c1r0 | c2r0 | c3r0 | + /// +------+------+------+------+ + /// r1 | c0r1 | c1r1 | c2r1 | c3r1 | + /// +------+------+------+------+ + /// r2 | c0r2 | c1r2 | c2r2 | c3r2 | + /// +------+------+------+------+ + /// r3 | c0r3 | c1r3 | c2r3 | c3r3 | + /// +------+------+------+------+ + /// ~~~ #[inline(always)] fn new(c0r0: T, c0r1: T, c0r2: T, c0r3: T, c1r0: T, c1r1: T, c1r2: T, c1r3: T, @@ -1832,29 +1668,27 @@ impl BaseMat4> for Mat4 { BaseVec4::new::>(c3r0, c3r1, c3r2, c3r3)) } - /** - * Construct a 4 x 4 matrix from column vectors - * - * # Arguments - * - * * `c0` - the first column vector of the matrix - * * `c1` - the second column vector of the matrix - * * `c2` - the third column vector of the matrix - * * `c3` - the fourth column vector of the matrix - * - * ~~~ - * c0 c1 c2 c3 - * +------+------+------+------+ - * r0 | c0.x | c1.x | c2.x | c3.x | - * +------+------+------+------+ - * r1 | c0.y | c1.y | c2.y | c3.y | - * +------+------+------+------+ - * r2 | c0.z | c1.z | c2.z | c3.z | - * +------+------+------+------+ - * r3 | c0.w | c1.w | c2.w | c3.w | - * +------+------+------+------+ - * ~~~ - */ + /// Construct a 4 x 4 matrix from column vectors + /// + /// # Arguments + /// + /// - `c0`: the first column vector of the matrix + /// - `c1`: the second column vector of the matrix + /// - `c2`: the third column vector of the matrix + /// - `c3`: the fourth column vector of the matrix + /// + /// ~~~ + /// c0 c1 c2 c3 + /// +------+------+------+------+ + /// r0 | c0.x | c1.x | c2.x | c3.x | + /// +------+------+------+------+ + /// r1 | c0.y | c1.y | c2.y | c3.y | + /// +------+------+------+------+ + /// r2 | c0.z | c1.z | c2.z | c3.z | + /// +------+------+------+------+ + /// r3 | c0.w | c1.w | c2.w | c3.w | + /// +------+------+------+------+ + /// ~~~ #[inline(always)] fn from_cols(c0: Vec4, c1: Vec4, c2: Vec4, c3: Vec4) -> Mat4 { Mat4 { x: c0, y: c1, z: c2, w: c3 } diff --git a/src/quat.rs b/src/quat.rs index c6ddf21..3d87a06 100644 --- a/src/quat.rs +++ b/src/quat.rs @@ -22,56 +22,46 @@ use vec::{Vec3, BaseVec3, AffineVec, NumVec, NumVec3}; use num::NumAssign; -/** - * A quaternion in scalar/vector form - * - * # Type parameters - * - * * `T` - The type of the components. Should be a floating point type. - * - * # Fields - * - * * `s` - the scalar component - * * `v` - a vector containing the three imaginary components - */ +/// A quaternion in scalar/vector form +/// +/// # Type parameters +/// +/// - `T`: The type of the components. Should be a floating point type. +/// +/// # Fields +/// +/// - `s`: the scalar component +/// - `v`: a vector containing the three imaginary components #[deriving(Eq)] pub struct Quat { s: T, v: Vec3 } pub impl Quat { - /** - * Construct the quaternion from one scalar component and three - * imaginary components - * - * # Arguments - * - * * `w` - the scalar component - * * `xi` - the fist imaginary component - * * `yj` - the second imaginary component - * * `zk` - the third imaginary component - */ + /// Construct the quaternion from one scalar component and three + /// imaginary components + /// + /// # Arguments + /// + /// - `w`: the scalar component + /// - `xi`: the fist imaginary component + /// - `yj`: the second imaginary component + /// - `zk`: the third imaginary component #[inline(always)] fn new(w: T, xi: T, yj: T, zk: T) -> Quat { Quat::from_sv(w, BaseVec3::new(xi, yj, zk)) } - /** - * Construct the quaternion from a scalar and a vector - * - * # Arguments - * - * * `s` - the scalar component - * * `v` - a vector containing the three imaginary components - */ + /// Construct the quaternion from a scalar and a vector + /// + /// # Arguments + /// + /// - `s`: the scalar component + /// - `v`: a vector containing the three imaginary components #[inline(always)] fn from_sv(s: T, v: Vec3) -> Quat { Quat { s: s, v: v } } - /** - * # Return value - * - * The multiplicative identity, ie: `q = 1 + 0i + 0j + 0i` - */ + /// The multiplicative identity, ie: `q = 1 + 0i + 0j + 0i` #[inline(always)] fn identity() -> Quat { Quat::new(One::one(), @@ -80,11 +70,7 @@ pub impl Quat { Zero::zero()) } - /** - * # Return value - * - * The additive identity, ie: `q = 0 + 0i + 0j + 0i` - */ + /// The additive identity, ie: `q = 0 + 0i + 0j + 0i` #[inline(always)] fn zero() -> Quat { Quat::new(Zero::zero(), @@ -163,11 +149,7 @@ pub impl Quat { let m: Mat3 = BaseMat3::look_at(dir, up); m.to_quat() } - /** - * # Return value - * - * The result of multiplying the quaternion a scalar - */ + /// The result of multiplying the quaternion a scalar #[inline(always)] fn mul_t(&self, value: T) -> Quat { Quat::new(*self.index(0) * value, @@ -176,11 +158,7 @@ pub impl Quat { *self.index(3) * value) } - /** - * # Return value - * - * The result of dividing the quaternion a scalar - */ + /// The result of dividing the quaternion a scalar #[inline(always)] fn div_t(&self, value: T) -> Quat { Quat::new(*self.index(0) / value, @@ -189,22 +167,14 @@ pub impl Quat { *self.index(3) / value) } - /** - * # Return value - * - * The result of multiplying the quaternion by a vector - */ + /// The result of multiplying the quaternion by a vector #[inline(always)] fn mul_v(&self, vec: &Vec3) -> Vec3 { let tmp = self.v.cross(vec).add_v(&vec.mul_t(self.s)); self.v.cross(&tmp).mul_t(num::cast(2)).add_v(vec) } - /** - * # Return value - * - * The sum of this quaternion and `other` - */ + /// The sum of this quaternion and `other` #[inline(always)] fn add_q(&self, other: &Quat) -> Quat { Quat::new(*self.index(0) + *other.index(0), @@ -213,11 +183,7 @@ pub impl Quat { *self.index(3) + *other.index(3)) } - /** - * # Return value - * - * The sum of this quaternion and `other` - */ + /// The sum of this quaternion and `other` #[inline(always)] fn sub_q(&self, other: &Quat) -> Quat { Quat::new(*self.index(0) - *other.index(0), @@ -226,11 +192,7 @@ pub impl Quat { *self.index(3) - *other.index(3)) } - /** - * # Return value - * - * The the result of multipliplying the quaternion by `other` - */ + /// The the result of multipliplying the quaternion by `other` #[inline(always)] fn mul_q(&self, other: &Quat) -> Quat { Quat::new(self.s * other.s - self.v.x * other.v.x - self.v.y * other.v.y - self.v.z * other.v.z, @@ -239,107 +201,79 @@ pub impl Quat { self.s * other.v.z + self.v.z * other.s + self.v.x * other.v.y - self.v.y * other.v.x) } - /** - * # Return value - * - * The dot product of the quaternion and `other` - */ + /// The dot product of the quaternion and `other` #[inline(always)] fn dot(&self, other: &Quat) -> T { self.s * other.s + self.v.dot(&other.v) } - /** - * # Return value - * - * The conjugate of the quaternion - */ + /// The conjugate of the quaternion #[inline(always)] fn conjugate(&self) -> Quat { Quat::from_sv(self.s, -self.v) } - /** - * # Return value - * - * The multiplicative inverse of the quaternion - */ + /// The multiplicative inverse of the quaternion #[inline(always)] fn inverse(&self) -> Quat { self.conjugate().div_t(self.magnitude2()) } - /** - * # Return value - * - * The squared magnitude of the quaternion. This is useful for - * magnitude comparisons where the exact magnitude does not need to be - * calculated. - */ + /// The squared magnitude of the quaternion. This is useful for + /// magnitude comparisons where the exact magnitude does not need to be + /// calculated. #[inline(always)] fn magnitude2(&self) -> T { self.s * self.s + self.v.length2() } - /** - * # Return value - * - * The magnitude of the quaternion - * - * # Performance notes - * - * For instances where the exact magnitude of the quaternion does not need - * to be known, for example for quaternion-quaternion magnitude comparisons, - * it is advisable to use the `magnitude2` method instead. - */ + /// The magnitude of the quaternion + /// + /// # Performance notes + /// + /// For instances where the exact magnitude of the quaternion does not need + /// to be known, for example for quaternion-quaternion magnitude comparisons, + /// it is advisable to use the `magnitude2` method instead. #[inline(always)] fn magnitude(&self) -> T { self.magnitude2().sqrt() } - /** - * # Return value - * - * The normalized quaternion - */ + /// The normalized quaternion #[inline(always)] fn normalize(&self) -> Quat { self.mul_t(One::one::()/self.magnitude()) } - /** - * Normalised linear interpolation - * - * # Return value - * - * The intoperlated quaternion - */ + /// Normalised linear interpolation + /// + /// # Return value + /// + /// The intoperlated quaternion #[inline(always)] fn nlerp(&self, other: &Quat, amount: T) -> Quat { self.mul_t(One::one::() - amount).add_q(&other.mul_t(amount)).normalize() } - /** - * Spherical Linear Intoperlation - * - * Perform a spherical linear interpolation between the quaternion and - * `other`. Both quaternions should be normalized first. - * - * # Return value - * - * The intoperlated quaternion - * - * # Performance notes - * - * The `acos` operation used in `slerp` is an expensive operation, so unless - * your quarternions a far away from each other it's generally more advisable - * to use `nlerp` when you know your rotations are going to be small. - * - * - [Understanding Slerp, Then Not Using It] - * (http://number-none.com/product/Understanding%20Slerp,%20Then%20Not%20Using%20It/) - * - [Arcsynthesis OpenGL tutorial] - * (http://www.arcsynthesis.org/gltut/Positioning/Tut08%20Interpolation.html) - */ + /// Spherical Linear Intoperlation + /// + /// Perform a spherical linear interpolation between the quaternion and + /// `other`. Both quaternions should be normalized first. + /// + /// # Return value + /// + /// The intoperlated quaternion + /// + /// # Performance notes + /// + /// The `acos` operation used in `slerp` is an expensive operation, so unless + /// your quarternions a far away from each other it's generally more advisable + /// to use `nlerp` when you know your rotations are going to be small. + /// + /// - [Understanding Slerp, Then Not Using It] + /// (http://number-none.com/product/Understanding%20Slerp,%20Then%20Not%20Using%20It/) + /// - [Arcsynthesis OpenGL tutorial] + /// (http://www.arcsynthesis.org/gltut/Positioning/Tut08%20Interpolation.html) #[inline(always)] fn slerp(&self, other: &Quat, amount: T) -> Quat { let dot = self.dot(other); @@ -363,19 +297,13 @@ pub impl Quat { } } - /** - * # Return value - * - * A pointer to the first component of the quaternion - */ + /// A pointer to the first component of the quaternion #[inline(always)] fn to_ptr(&self) -> *T { unsafe { cast::transmute(self) } } - /** - * Convert the quaternion to a 3 x 3 rotation matrix - */ + /// Convert the quaternion to a 3 x 3 rotation matrix #[inline(always)] fn to_mat3(&self) -> Mat3 { let x2 = self.v.x + self.v.x; diff --git a/src/vec.rs b/src/vec.rs index d82a101..12952ba 100644 --- a/src/vec.rs +++ b/src/vec.rs @@ -19,206 +19,129 @@ use std::num::{Zero, One}; use num::NumAssign; -/** - * The base generic vector trait. - * - * # Type parameters - * - * * `T` - The type of the components. This is intended to support boolean, - * integer, unsigned integer, and floating point types. - */ +/// The base generic vector trait. +/// +/// # Type parameters +/// +/// - `T`: The type of the components. This is intended to support boolean, +/// integer, unsigned integer, and floating point types. pub trait BaseVec: Eq { + /// The component of the vector at the index `i` fn index<'a>(&'a self, i: uint) -> &'a T; - /** - * Construct the vector from a single value, copying it to each component - */ + /// Construct the vector from a single value, copying it to each component fn from_value(value: T) -> Self; - /** - * # Return value - * - * A pointer to the first component of the vector - */ + /// A pointer to the first component of the vector fn to_ptr(&self) -> *T; - /** - * Get a mutable reference to the component at `i` - */ + /// Get a mutable reference to the component at `i` fn index_mut<'a>(&'a mut self, i: uint) -> &'a mut T; - /** - * Swap two components of the vector in place - */ + /// Swap two components of the vector in place fn swap(&mut self, a: uint, b: uint); } -/** - * A generic 2-dimensional vector - */ +/// A generic 2-dimensional vector pub trait BaseVec2: BaseVec { fn new(x: T, y: T) -> Self; } -/** - * A generic 3-dimensional vector - */ +/// A generic 3-dimensional vector pub trait BaseVec3: BaseVec { fn new(x: T, y: T, z: T) -> Self; } -/** - * A generic 4-dimensional vector - */ +/// A generic 4-dimensional vector pub trait BaseVec4: BaseVec { fn new(x: T, y: T, z: T, w: T) -> Self; } -/** - * A vector with numeric components - */ +/// A vector with numeric components pub trait NumVec: BaseVec + Neg { - /** - * The standard basis vector - * - * # Return value - * - * A vector with each component set to one - */ + /// The standard basis vector + /// + /// # Return value + /// + /// A vector with each component set to one fn identity() -> Self; - /** - * The null vector - * - * # Return value - * - * A vector with each component set to zero - */ + /// The null vector + /// + /// # Return value + /// + /// A vector with each component set to zero fn zero() -> Self; - /** - * # Return value - * - * True if the vector is equal to zero - */ + /// True if the vector is equal to zero fn is_zero(&self) -> bool; - /** - * # Return value - * - * The scalar multiplication of the vector and `value` - */ + /// The scalar multiplication of the vector and `value` fn mul_t(&self, value: T) -> Self; - /** - * # Return value - * - * The scalar division of the vector and `value` - */ + /// The scalar division of the vector and `value` fn div_t(&self, value: T) -> Self; - /** - * Component-wise vector addition - */ + /// Component-wise vector addition fn add_v(&self, other: &Self) -> Self; - /** - * Component-wise vector subtraction - */ + /// Component-wise vector subtraction fn sub_v(&self, other: &Self) -> Self; - /** - * Component-wise vector multiplication - */ + /// Component-wise vector multiplication fn mul_v(&self, other: &Self) -> Self; - /** - * Component-wise vector division - */ + /// Component-wise vector division fn div_v(&self, other: &Self) -> Self; - /** - * # Return value - * - * The dot product of the vector and `other` - */ + /// The dot product of the vector and `other` fn dot(&self, other: &Self) -> T; - /** - * Negate the vector - */ + /// Negate the vector fn neg_self(&mut self); - /** - * Multiply the vector by a scalar - */ + /// Multiply the vector by a scalar fn mul_self_t(&mut self, value: T); - /** - * Divide the vector by a scalar - */ + /// Divide the vector by a scalar fn div_self_t(&mut self, value: T); - /** - * Set the vector to the component-wise vector sum - */ + /// Set the vector to the component-wise vector sum fn add_self_v(&mut self, other: &Self); - /** - * Set the vector to the component-wise vector difference - */ + /// Set the vector to the component-wise vector difference fn sub_self_v(&mut self, other: &Self); - /** - * Set the vector to the component-wise vector product - */ + /// Set the vector to the component-wise vector product fn mul_self_v(&mut self, other: &Self); - /** - * Set the vector to the component-wise vector quotient - */ + /// Set the vector to the component-wise vector quotient fn div_self_v(&mut self, other: &Self); } -/** - * A 2-dimensional vector with numeric components - */ +/// A 2-dimensional vector with numeric components pub trait NumVec2: NumVec { fn unit_x() -> Self; fn unit_y() -> Self; - /** - * # Return value - * - * The perp dot product of the vector and `other` - */ + /// The perp dot product of the vector and `other` fn perp_dot(&self, other: &Self) -> T; } -/** - * A 3-dimensional vector with numeric components - */ +/// A 3-dimensional vector with numeric components pub trait NumVec3: NumVec { fn unit_x() -> Self; fn unit_y() -> Self; fn unit_z() -> Self; - /** - * # Return value - * - * The cross product of the vector and `other` - */ + /// The cross product of the vector and `other` fn cross(&self, other: &Self) -> Self; - /** - * Set to the cross product of the vector and `other` - */ + /// Set to the cross product of the vector and `other` fn cross_self(&mut self, other: &Self); } -/** - * A 4-dimensional vector with numeric components - */ +/// A 4-dimensional vector with numeric components pub trait NumVec4: NumVec { fn unit_x() -> Self; fn unit_y() -> Self; @@ -227,174 +150,106 @@ pub trait NumVec4: NumVec { } pub trait ToHomogeneous { - /** - * Convert to a homogenous coordinate - */ + /// Convert to a homogenous coordinate fn to_homogeneous(&self) -> H; } -/** - * A Euclidean (or Affine) vector - * - * # Type parameters - * - * * `T` - The type of the components. This should be a floating point type. - */ +/// A Euclidean (or Affine) vector +/// +/// # Type parameters +/// +/// - `T`: The type of the components. This should be a floating point type. pub trait AffineVec: NumVec { - /** - * # Return value - * - * The squared length of the vector. This is useful for comparisons where - * the exact length does not need to be calculated. - */ + /// The squared length of the vector. This is useful for comparisons where + /// the exact length does not need to be calculated. fn length2(&self) -> T; - /** - * # Return value - * - * The length of the vector - * - * # Performance notes - * - * For instances where the exact length of the vector does not need to be - * known, for example for quaternion-quaternion length comparisons, - * it is advisable to use the `length2` method instead. - */ + /// The length of the vector + /// + /// # Performance notes + /// + /// For instances where the exact length of the vector does not need to be + /// known, for example for quaternion-quaternion length comparisons, + /// it is advisable to use the `length2` method instead. fn length(&self) -> T; - /** - * # Return value - * - * The squared distance between the vector and `other`. - */ + /// The squared distance between the vector and `other`. fn distance2(&self, other: &Self) -> T; - /** - * # Return value - * - * The distance between the vector and `other` - */ + /// The distance between the vector and `other` fn distance(&self, other: &Self) -> T; - /** - * # Return value - * - * The angle between the vector and `other` in radians - */ + /// The angle between the vector and `other` in radians fn angle(&self, other: &Self) -> T; - /** - * # Return value - * - * The normalized vector - */ + /// The normalized vector fn normalize(&self) -> Self; - /** - * Set the length of the vector whilst preserving the direction - */ + /// Set the length of the vector whilst preserving the direction fn normalize_to(&self, length: T) -> Self; - /** - * Linearly intoperlate between the vector and `other` - * - * # Return value - * - * The intoperlated vector - */ + /// Linearly intoperlate between the vector and `other` + /// + /// # Return value + /// + /// The intoperlated vector fn lerp(&self, other: &Self, amount: T) -> Self; - /** - * Normalize the vector - */ + /// Normalize the vector fn normalize_self(&mut self); - /** - * Set the vector to a specified length whilst preserving the direction - */ + /// Set the vector to a specified length whilst preserving the direction fn normalize_self_to(&mut self, length: T); - /** - * Linearly intoperlate the vector towards `other` - */ + /// Linearly intoperlate the vector towards `other` fn lerp_self(&mut self, other: &Self, amount: T); } -/** - * Component-wise vector comparison methods - * - * The methods contained in this trait correspond to the relational functions - * mentioned in Section 8.7 of the [GLSL 4.30.6 specification] - * (http://www.opengl.org/registry/doc/GLSLangSpec.4.30.6.pdf). - */ +/// Component-wise vector comparison methods +/// +/// The methods contained in this trait correspond to the relational functions +/// mentioned in Section 8.7 of the [GLSL 4.30.6 specification] +/// (http://www.opengl.org/registry/doc/GLSLangSpec.4.30.6.pdf). pub trait OrdVec: BaseVec { - /** - * Component-wise compare of `self < other` - */ + /// Component-wise compare of `self < other` fn less_than(&self, other: &Self) -> BoolVec; - /** - * Component-wise compare of `self <= other` - */ + /// Component-wise compare of `self <= other` fn less_than_equal(&self, other: &Self) -> BoolVec; - /** - * Component-wise compare of `self > other` - */ + /// Component-wise compare of `self > other` fn greater_than(&self, other: &Self) -> BoolVec; - /** - * Component-wise compare of `self >= other` - */ + /// Component-wise compare of `self >= other` fn greater_than_equal(&self, other: &Self) -> BoolVec; } -/** - * Component-wise equality comparison methods - * - * The methods contained in this trait correspond to the relational functions - * mentioned in Section 8.7 of the [GLSL 4.30.6 specification] - * (http://www.opengl.org/registry/doc/GLSLangSpec.4.30.6.pdf). - */ +/// Component-wise equality comparison methods +/// +/// The methods contained in this trait correspond to the relational functions +/// mentioned in Section 8.7 of the [GLSL 4.30.6 specification] +/// (http://www.opengl.org/registry/doc/GLSLangSpec.4.30.6.pdf). pub trait EqVec: BaseVec { - /** - * Component-wise compare of `self == other` - */ + /// Component-wise compare of `self == other` fn equal(&self, other: &Self) -> BoolVec; - /** - * Component-wise compare of `self != other` - */ + /// Component-wise compare of `self != other` fn not_equal(&self, other: &Self) -> BoolVec; } -/** - * A vector with boolean components - * - * The methods contained in this trait correspond to the relational functions - * mentioned in Section 8.7 of the [GLSL 4.30.6 specification] - * (http://www.opengl.org/registry/doc/GLSLangSpec.4.30.6.pdf). - */ +/// A vector with boolean components +/// +/// The methods contained in this trait correspond to the relational functions +/// mentioned in Section 8.7 of the [GLSL 4.30.6 specification] +/// (http://www.opengl.org/registry/doc/GLSLangSpec.4.30.6.pdf). pub trait BoolVec: BaseVec { - /** - * # Return value - * - * `true` if of any component is `true` - */ + /// `true` if of any component is `true` fn any(&self) -> bool; - /** - * # Return value - * - * `true` only if all components are `true` - */ + /// `true` only if all components are `true` fn all(&self) -> bool; - /** - * # Return value - * - * the component-wise logical complement - */ + /// the component-wise logical complement fn not(&self) -> Self; } @@ -523,19 +378,17 @@ macro_rules! zip_assign( ($a:ident[] $method:ident $b:ident ..4) => ({ zip_assign!($a[] $method $b ..3); $a.index_mut(3).$method(&$b); }); ) -/** - * A 2-dimensional vector - * - * # Type parameters - * - * * `T` - The type of the components. This is intended to support boolean, - * integer, unsigned integer, and floating point types. - * - * # Fields - * - * * `x` - the first component of the vector - * * `y` - the second component of the vector - */ +/// A 2-dimensional vector +/// +/// # Type parameters +/// +/// - `T`: The type of the components. This is intended to support boolean, +/// integer, unsigned integer, and floating point types. +/// +/// # Fields +/// +/// - `x`: the first component of the vector +/// - `y`: the second component of the vector #[deriving(Eq)] pub struct Vec2 { x: T, y: T } @@ -904,20 +757,18 @@ vec2_type!(Vec2u32) vec2_type!(Vec2u64) vec2_type!(Vec2b) -/** - * A 3-dimensional vector - * - * # Type parameters - * - * * `T` - The type of the components. This is intended to support boolean, - * integer, unsigned integer, and floating point types. - * - * # Fields - * - * * `x` - the first component of the vector - * * `y` - the second component of the vector - * * `z` - the third component of the vector - */ +/// A 3-dimensional vector +/// +/// # Type parameters +/// +/// - `T`: The type of the components. This is intended to support boolean, +/// integer, unsigned integer, and floating point types. +/// +/// # Fields +/// +/// - `x`: the first component of the vector +/// - `y`: the second component of the vector +/// - `z`: the third component of the vector #[deriving(Eq)] pub struct Vec3 { x: T, y: T, z: T } @@ -1309,21 +1160,19 @@ vec3_type!(Vec3u32) vec3_type!(Vec3u64) vec3_type!(Vec3b) -/** - * A 4-dimensional vector - * - * # Type parameters - * - * * `T` - The type of the components. This is intended to support boolean, - * integer, unsigned integer, and floating point types. - * - * # Fields - * - * * `x` - the first component of the vector - * * `y` - the second component of the vector - * * `z` - the third component of the vector - * * `w` - the fourth component of the vector - */ +/// A 4-dimensional vector +/// +/// # Type parameters +/// +/// - `T`: The type of the components. This is intended to support boolean, +/// integer, unsigned integer, and floating point types. +/// +/// # Fields +/// +/// - `x`: the first component of the vector +/// - `y`: the second component of the vector +/// - `z`: the third component of the vector +/// - `w`: the fourth component of the vector #[deriving(Eq)] pub struct Vec4 { x: T, y: T, z: T, w: T }