gml 1.0.0

Graphics Math Library. Generic Vector and Matrix Math library targetting graphics applications. 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113

// Copyright 2015 Creekware Inc. See the COPYRIGHT
// file at the top-level directory of this distribution.
//
// Licensed under the Apache License, Version 2.0 <LICENSE-APACHE or
// http://www.apache.org/licenses/LICENSE-2.0> or the MIT license
// <LICENSE-MIT or http://opensource.org/licenses/MIT>, at your
// option. This file may not be copied, modified, or distributed
// except according to those terms.

//! Graphics Math Library.
//!
//! A vector and matrix library for Rust targeting low level graphics
//! operations.  Similar to C++ libraries glm, cml, MathGeoLib, Eigen,
//! CGGeometry from Cocoa, and others.  It may be useful to anyone
//! working with low level graphic primitives in Rust.
//! 
//! This library was created to determine if header-only generic template
//! C++ libraries such as you would find in Boost, glm.g-truc.net, and the
//! like could be implemented in a simpler fashion in Rust with less
//! boilerplate while maintaining performance.  After several iterations
//! we are fairly happy with the result.  Version 1.0 of this library
//! (gml) implements a complete and tested fully generic vector and matrix
//! library, modelled after the functionality found in the OpenGL shader
//! language, the C++ library GLM, and the math portion of the Unity game
//! engine.  With OpenGL or DirectX bindings (not included here) and this
//! library you can be coding up spinning 3D geometries in no time.
//! 
//! ## Versioning
//! 
//! Version 1.0.0 represents a stable and tested API.  The third digit (ie
//! from 1.0.0 to 1.0.1) represents minor revisions, bug fixes and the
//! like.  The second digit (ie from 1.0.23 to 1.1.0) represents backwards
//! compatible feature additions.  The first digit (ie from 1.3.43 to
//! 2.0.0) represents breaking API changes.  Development prior to 1.0.0 were
//! done on a private repository.
//! 
//! ## Contributing
//! 
//! Discussions on how to implement these features using Rust in a simpler
//! or perhaps more performant fashion are welcome.  Bug fixes or feature
//! additions within the scope of the library are also welcome.  A variety
//! of additional features cherry picked from the C++ reference libraries
//! will be added as time permits.
//!
//! ## Example: triangle normal
//!
//! ```
//! use gml::*;
//!
//! let a = Vector3::new( 1.0,  3.0, 2.0);
//! let b = Vector3::new( 5.0, 11.0, 3.0);
//! let c = Vector3::new(-4.0, -8.0,-1.0);
//! let triangle_normal = (c - a).cross(b - a).normalize();
//! let expected_answer = Vector3::new(0.849837, -0.457604, 0.261488);
//!
//! assert!(triangle_normal.eq_approx(expected_answer , 1e-5 ));
//! ```
//!
//! ## Example: matrix transform
//!
//! ```
//! use gml::*;
//!
//! let translate = 3.0f32;
//! let rotate    = Vector3f::new(4.0, 7.0, 5.0);
//!
//! let projection     = perspective(45.0f32, 4.0f32 / 3.0f32, 0.1f32, 100.0f32);
//! let view_translate = Matrix4x4f::unit().translate( Vector3::new(0.0f32, 0.0f32, -translate));
//! let view_rotate_x  = view_translate.rotate(rotate.y, Vector3f::new(-1.0, 0.0, 0.0));
//! let view           = view_rotate_x.rotate(rotate.x, Vector3f::new(0.0, 1.0, 0.0));
//! let model          = Matrix4x4f::unit().scale(Vector3f::new_s(0.5));
//! let mvp            = projection * view * model;
//!
//! let expect = Matrix4x4f::new(-0.439393,  0.445646, -0.285849, -0.285278,
//!                               0.0     ,  0.675719,  0.329151,  0.328493,
//!                              -0.508739, -0.384901,  0.246885,  0.246392,
//!                               0.0     ,  0.0     ,  3.006006,  3.0      );
//! assert!(mvp.eq_approx(expect, 1e-5) );
//! ```

extern crate num;

use num::traits::*;

pub use vector::*;
pub use matrix::*;
pub use matrix_transform::*;
pub use quaternion::*;

pub mod vector;
pub mod matrix;
pub mod matrix_transform;
pub mod quaternion;


/// Approximate equality comparison for floating point types.
/// Floating point calculation inaccuracies make direct equality
/// comparison problematic.  This function returns true if two
/// floating point types are equal within a error range defined
/// by the argument epsilon; and false otherwise.
///
/// ```
/// let a = 3.039348;
/// let b = 3.039589;
///
/// assert!(gml::eq_approx(a, b, 0.001) == true);
/// assert!(gml::eq_approx(a, b, 0.0001) == false);
/// ```
pub fn eq_approx<T:Float>(a:T, b:T, epsilon:T) -> bool {
    (a - b).abs() < epsilon
}