hodasemi/cgmath
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity

Use /// style doc comments

Browse source
This commit is contained in:
Brendan Zabarauskas 2013-06-01 12:57:29 +10:00
parent f443203d4a
commit d352577356
3 changed files with 588 additions and 977 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

928
src/mat.rs
View file

File diff suppressed because it is too large Load diff

218
src/quat.rs
View file

@ -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<T> { s: T, v: Vec3<T> }
pub impl<T:Copy + Float + NumAssign> Quat<T> {
/**
* 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<T> {
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<T>) -> Quat<T> {
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<T> {
Quat::new(One::one(),
@ -80,11 +70,7 @@ pub impl<T:Copy + Float + NumAssign> Quat<T> {
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<T> {
Quat::new(Zero::zero(),
@ -163,11 +149,7 @@ pub impl<T:Copy + Float + NumAssign> Quat<T> {
let m: Mat3<T> = 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<T> {
Quat::new(*self.index(0) * value,
@ -176,11 +158,7 @@ pub impl<T:Copy + Float + NumAssign> Quat<T> {
*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<T> {
Quat::new(*self.index(0) / value,
@ -189,22 +167,14 @@ pub impl<T:Copy + Float + NumAssign> Quat<T> {
*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<T>) -> Vec3<T> {
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<T>) -> Quat<T> {
Quat::new(*self.index(0) + *other.index(0),
@ -213,11 +183,7 @@ pub impl<T:Copy + Float + NumAssign> Quat<T> {
*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<T>) -> Quat<T> {
Quat::new(*self.index(0) - *other.index(0),
@ -226,11 +192,7 @@ pub impl<T:Copy + Float + NumAssign> Quat<T> {
*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<T>) -> Quat<T> {
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<T:Copy + Float + NumAssign> Quat<T> {
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>) -> 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<T> {
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<T> {
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<T> {
self.mul_t(One::one::<T>()/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<T>, amount: T) -> Quat<T> {
self.mul_t(One::one::<T>() - 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<T>, amount: T) -> Quat<T> {
let dot = self.dot(other);
@ -363,19 +297,13 @@ pub impl<T:Copy + Float + NumAssign> Quat<T> {
}
}
/**
* # 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<T> {
let x2 = self.v.x + self.v.x;

419
src/vec.rs
View file

@ -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<T>: 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<T>: BaseVec<T> {
fn new(x: T, y: T) -> Self;
}
/**
* A generic 3-dimensional vector
*/
/// A generic 3-dimensional vector
pub trait BaseVec3<T>: BaseVec<T> {
fn new(x: T, y: T, z: T) -> Self;
}
/**
* A generic 4-dimensional vector
*/
/// A generic 4-dimensional vector
pub trait BaseVec4<T>: BaseVec<T> {
fn new(x: T, y: T, z: T, w: T) -> Self;
}
/**
* A vector with numeric components
*/
/// A vector with numeric components
pub trait NumVec<T>: BaseVec<T> + Neg<Self> {
/**
* 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<T>: NumVec<T> {
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<T>: NumVec<T> {
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<T>: NumVec<T> {
fn unit_x() -> Self;
fn unit_y() -> Self;
@ -227,174 +150,106 @@ pub trait NumVec4<T>: NumVec<T> {
}
pub trait ToHomogeneous<H> {
/**
* 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<T>: NumVec<T> {
/**
* # 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<T, BoolVec>: BaseVec<T> {
/**
* 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<T, BoolVec>: BaseVec<T> {
/**
* 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<bool> {
/**
* # 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<T> { x: T, y: T }
@ -904,20 +757,18 @@ vec2_type!(Vec2u32<u32>)
vec2_type!(Vec2u64<u64>)
vec2_type!(Vec2b<bool>)
/**
* 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<T> { x: T, y: T, z: T }
@ -1309,21 +1160,19 @@ vec3_type!(Vec3u32<u32>)
vec3_type!(Vec3u64<u64>)
vec3_type!(Vec3b<bool>)
/**
* 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<T> { x: T, y: T, z: T, w: T }