diff --git a/src/funs/common.rs b/src/funs/common.rs index bc227c0..cd388ec 100644 --- a/src/funs/common.rs +++ b/src/funs/common.rs @@ -1,12 +1,15 @@ +/** + * Common Functions + * + * This module corresponds to Section 8.3 of the [GLSL 4.30.6 specification] + * (http://www.opengl.org/registry/doc/GLSLangSpec.4.30.6.pdf). + */ + use num::cast::cast; use vec::{Vec2, Vec3, Vec4}; -/// Should only be implemented on signed types. pub trait Sign { pure fn abs() -> self; - - /// returns `-1` if the number is negative, `0` if the number is equal to 0, - /// and `1` if the number is positive pure fn sign() -> self; } diff --git a/src/funs/exponential.rs b/src/funs/exponential.rs index 9587771..e1643ef 100644 --- a/src/funs/exponential.rs +++ b/src/funs/exponential.rs @@ -1,6 +1,10 @@ /** * Exponential Functions + * + * This module corresponds to Section 8.2 of the [GLSL 4.30.6 specification] + * (http://www.opengl.org/registry/doc/GLSLangSpec.4.30.6.pdf). */ + use num::cast::{NumCast, cast}; use vec::{Vec2, Vec3, Vec4}; diff --git a/src/funs/projection.rs b/src/funs/projection.rs index 6b45c0a..c9609ec 100644 --- a/src/funs/projection.rs +++ b/src/funs/projection.rs @@ -5,12 +5,12 @@ use num::cast::cast; use num::consts::pi; use num::ext::FloatExt; -// -// Create a perspective projection matrix -// -// fov is in degrees -// http://www.opengl.org/wiki/GluPerspective_code -// +/** + * Create a perspective projection matrix + * + * This is the equivalent of the gluPerspective function, the algorithm of which + * can be found [here](http://www.opengl.org/wiki/GluPerspective_code). + */ #[inline(always)] pure fn perspective(fovy: Radians, aspectRatio: T, near: T, far: T) -> Mat4 { let ymax = near * tan(&fovy); @@ -19,18 +19,16 @@ pure fn perspective(fovy: Radians, aspectRatio: T, near: T, frustum(-xmax, xmax, -ymax, ymax, near, far) } -// -// Define a view frustrum -// http://www.felixgers.de/teaching/jogl/perspectiveProjection.html -// http://www.opengl.org/wiki/GluPerspective_code -// -// TODO: double check algorithm -// +/** + * Define a view frustrum + * + * This is the equivalent of the now deprecated [glFrustrum] + * (http://www.opengl.org/sdk/docs/man2/xhtml/glFrustum.xml) function. + */ #[inline(always)] pure fn frustum(left: T, right: T, bottom: T, top: T, near: T, far: T) -> Mat4 { let _0: T = cast(0); let _2: T = cast(2); - let neg_1 = cast(-1); let c0r0 = (_2 * near) / (right - left); let c0r1 = _0; @@ -43,7 +41,7 @@ pure fn frustum(left: T, right: T, bottom: T, top: T, near: T, let c2r0 = (right + left) / (right - left); let c2r1 = (top + bottom) / (top - bottom); let c2r2 = -(far + near) / (far - near); - let c2r3 = neg_1; + let c2r3 = cast(-1); let c3r0 = _0; let c3r1 = _0; let c3r2 = -(_2 * far * near) / (far - near); diff --git a/src/funs/relational.rs b/src/funs/relational.rs index d6b0eb9..c43bc39 100644 --- a/src/funs/relational.rs +++ b/src/funs/relational.rs @@ -1,9 +1,11 @@ /** * Vector Relational Functions + * + * This module corresponds to Section 8.7 of the [GLSL 4.30.6 specification] + * (http://www.opengl.org/registry/doc/GLSLangSpec.4.30.6.pdf). */ use core::cmp::{Eq, Ord}; - use vec::{Vector, Vec2, Vec3, Vec4}; pub trait RelVector { diff --git a/src/funs/triganomic.rs b/src/funs/triganomic.rs index 5489b0c..3dd8a65 100644 --- a/src/funs/triganomic.rs +++ b/src/funs/triganomic.rs @@ -1,3 +1,9 @@ +/** + * Angle and Trigonometry Functions + * + * This module corresponds to Section 8.1 of the [GLSL 4.30.6 specification] + * (http://www.opengl.org/registry/doc/GLSLangSpec.4.30.6.pdf). + */ use num::cast::{NumCast, cast}; use angle::Radians; use vec::{Vec3, Vec2, Vec4}; diff --git a/src/gltypes.rs b/src/gltypes.rs index 2c28b3b..6a3b68b 100644 --- a/src/gltypes.rs +++ b/src/gltypes.rs @@ -1,24 +1,24 @@ -/// -/// This module contains various type aliases and method wrappers to make working -/// with OpenGL cleaner and safer than working with the lmath types directly. -/// This is especially important when working with type-sensitive OpenGL functions -/// such as `glVertexAttribPointer` and `glUniformMatrix4fv`) where a simple mistake -/// such writing `Vec3::new(1, 2, 3)` or `Vec3::new(1f, 2f, 3f)` as opposed to -/// `Vec3::new(1f32, 2f32, 3f32)` could cause you an afternoon of pain. -/// -/// To give you an example of how using the wrapper methods can clean up your -/// code and make debugging far easier, instead of writing: -/// -/// ~~~ -/// let v: Mat4 = NumericMatrixNxN::identity(); -/// ~~~ -/// -/// you can write: -/// -/// ~~~ -/// let v = dmat4::identity(); -/// ~~~ -/// +/*** + * This module contains various type aliases and method wrappers to make working + * with OpenGL cleaner and safer than working with the lmath types directly. + * This is especially important when working with type-sensitive OpenGL functions + * such as `glVertexAttribPointer` and `glUniformMatrix4fv`) where a simple mistake + * such writing `Vec3::new(1, 2, 3)` or `Vec3::new(1f, 2f, 3f)` as opposed to + * `Vec3::new(1f32, 2f32, 3f32)` could cause you an afternoon of pain. + * + * To give you an example of how using the wrapper methods can clean up your + * code and make debugging far easier, instead of writing: + * + * ~~~ + * let v: Mat4 = NumericMatrixNxN::identity(); + * ~~~ + * + * you can write: + * + * ~~~ + * let v = dmat4::identity(); + * ~~~ + */ use core::sys::size_of; @@ -27,7 +27,8 @@ use vec::{Vector, NumericVector, Vec2, Vec3, Vec4}; use quat::{/*Quaternion, */Quat}; -// Vector aliases +// Vector aliases, corresponding to Section 4.1.5 of the [GLSL 4.30.6 specification] +// (http://www.opengl.org/registry/doc/GLSLangSpec.4.30.6.pdf). pub type vec2 = Vec2; /// a two-component single-precision floating-point vector pub type vec3 = Vec3; /// a three-component single-precision floating-point vector @@ -207,7 +208,8 @@ pub impl uvec4 { } -// Matrix aliases +// Matrix aliases, corresponding to Section 4.1.6 of the [GLSL 4.30.6 specification] +// (http://www.opengl.org/registry/doc/GLSLangSpec.4.30.6.pdf). pub type mat2 = mat2x2; /// a 2×2 single-precision floating-point matrix pub type mat3 = mat3x3; /// a 3×3 single-precision floating-point matrix diff --git a/src/num/ext.rs b/src/num/ext.rs index 00192c2..0720166 100644 --- a/src/num/ext.rs +++ b/src/num/ext.rs @@ -1,11 +1,3 @@ -/** - * Various traits intended to be used with the built in numeric types. These - * allow one to be more specific with trait bounds when using generics. - * - * Note: These traits won't be able to be used to their full potential until - * trait inheritence is implemented. - */ - use core::cmp::{Eq, Ord}; use std::cmp::FuzzyEq; diff --git a/src/num/rhs.rs b/src/num/rhs.rs index 2a3490b..f741720 100644 --- a/src/num/rhs.rs +++ b/src/num/rhs.rs @@ -1,32 +1,33 @@ -/// These RHS operator traits would formalise the overloading of the RHS of the -/// Num operators (as described in [Refining Traits and Impls] -/// (http:///smallcultfollowing.com/babysteps/blog/2012/10/04/refining-traits-slash-impls/) -/// by nmatsakis). For example, if you wanted to achieve something like: -/// -/// ~~~ -/// enum Radians = T; -/// -/// let half_rotation = Radians(float::consts::pi); -/// let full_rotation = 2.0 * half_rotation; -/// let quarter_rotation = half_rotation * 0.5; -/// ~~~ -/// -/// All you'd have to implement is: -/// -/// ~~~ -/// pub impl Radians: float::MulRHS> { -/// pure fn int_add_rhs(lhs: &int) -> Radians { Radians(lhs * (*self)) } -/// } -/// -/// pub impl Radians: Mul> { -/// pure fn mul(rhs: &T) -> Radians { Radians((*self) * (*rhs)) } -/// } -/// ~~~ -/// -/// I may have got something wrong in my implementations, as I got some 'multiple -/// applicable methods in scope' errors due to Num automatically being imported -/// with core. If that's the case, apologies in advance! -/// +/** + * These RHS operator traits would formalise the overloading of the RHS of the + * Num operators (as described in [Refining Traits and Impls] + * (http://smallcultfollowing.com/babysteps/blog/2012/10/04/refining-traits-slash-impls/) + * by nmatsakis). For example, if you wanted to achieve something like: + * + * ~~~ + * enum Radians = T; + * + * let half_rotation = Radians(float::consts::pi); + * let full_rotation = 2.0 * half_rotation; + * let quarter_rotation = half_rotation * 0.5; + * ~~~ + * + * All you'd have to implement is: + * + * ~~~ + * pub impl Radians: float::MulRHS> { + * pure fn int_add_rhs(lhs: &int) -> Radians { Radians(lhs * (*self)) } + * } + * + * pub impl Radians: Mul> { + * pure fn mul(rhs: &T) -> Radians { Radians((*self) * (*rhs)) } + * } + * ~~~ + * + * I may have got something wrong in my implementations, as I got some 'multiple + * applicable methods in scope' errors due to Num automatically being imported + * with core. If that's the case, apologies in advance! + */ use core::Num;