1 | /** @mainpage Generic Math Template Library |
---|
2 | * @section Using Using This Reference Guide |
---|
3 | * Welcome to GMTL. To use this reference guide effectively, we suggest |
---|
4 | * you see the <a href="modules.html">Modules</a> section first. |
---|
5 | * The <a href="modules.html">Modules</a> section provides the most |
---|
6 | * intuitive navigation of the reference guide because this |
---|
7 | * section is structured very similar GMTL. Be sure |
---|
8 | * to read the GMTL Programmer's Guide (available on the |
---|
9 | * <a href="http://ggt.sf.net">GMTL web site</a>) to |
---|
10 | * understand the philosophy behind GMTL. Understanding abstractly what |
---|
11 | * GMTL is and why it is designed this way will make |
---|
12 | * your life with GMTL very easy. Lastly, you should subscribe to the mailing |
---|
13 | * lists so that you can ask questions, or propose extensions to the library. |
---|
14 | * |
---|
15 | * Please see the @ref gmtlfaq "GMTL FAQ" for more information. |
---|
16 | * |
---|
17 | * @section API Quickly Understanding The GMTL API |
---|
18 | * The GMTL API has two aspects you should keep in mind. The <i>data</i> |
---|
19 | * types, and the <i>operations</i> on the data. |
---|
20 | * <p> |
---|
21 | * All data types and operations are defined in the <tt>gmtl</tt> |
---|
22 | * namespace. |
---|
23 | * Thus all types must be prefixed with the <tt>gmtl::</tt> |
---|
24 | * scope or a <tt>using gmtl;</tt> command can be used to bring all |
---|
25 | * of the GMTL functionality into the local scope. |
---|
26 | * |
---|
27 | * @subsection Types Supplied GMTL Math Types |
---|
28 | * GMTL comes with many math data types: Vec, Point, Matrix, Quat, Coord, |
---|
29 | * Sphere. |
---|
30 | * Please read the programmer's guide for more detailed information. |
---|
31 | * Or read on for a light overview on what GMTL is. |
---|
32 | * |
---|
33 | * @section Overview A Light Overview Of GMTL |
---|
34 | * GMTL stands for (<b>G</b>)eneric (<b>M</b>)ath |
---|
35 | * (<b>T</b>)emplate (<b>L</b>)ibrary. |
---|
36 | * It is a math library designed to be high-performance, |
---|
37 | * extensible, and generic. The design is based upon discussion with many |
---|
38 | * experts in the field of computer graphics and virtual reality and is the |
---|
39 | * culmination of many previous graphics math library efforts. GMTL gives |
---|
40 | * the graphics programmer several core math types and a rich library of |
---|
41 | * graphics/math operations on those types. |
---|
42 | * |
---|
43 | * @subsection Design Design |
---|
44 | * The design of GMTL allows extensibility while mantaining a stable core. |
---|
45 | * Core data types are separated from operations. This allows anyone to write |
---|
46 | * their own math routines to extend or replace parts of the GMTL. This |
---|
47 | * feature |
---|
48 | * allows a very stable core set of math primitives that seldom change due to |
---|
49 | * extensions, maintainance, or programmer error. |
---|
50 | * <p> |
---|
51 | * All math primitives in GMTL use generic programming techniques |
---|
52 | * to give the programmer many options to define their data. For example, |
---|
53 | * matrices |
---|
54 | * and vectors can be any dimension and any type. GMTL suffers no loss of |
---|
55 | * performance |
---|
56 | * due to these generalities because the parameter choices made are bound |
---|
57 | * at <i>compile time</i>. |
---|
58 | * |
---|
59 | * @subsection Implementation Implementation |
---|
60 | * GMTL is implemented using generic programming and template metaprogramming. |
---|
61 | * Generic |
---|
62 | * programming allows selection by the user of size and type information for |
---|
63 | * all |
---|
64 | * data types in GMTL. For example, the generic Matrix type allows a |
---|
65 | * programmer |
---|
66 | * to select between any size (N x M) and any datatype (float, double, |
---|
67 | * int...). |
---|
68 | * The selection of these parameters is done through <i>template |
---|
69 | * parameters</i>. To ease the use of these parameters, the system declares |
---|
70 | * several typedefs that capture commonly used options. |
---|
71 | * <p> |
---|
72 | * Requested data types are statically bound and optimized by the compiler. |
---|
73 | * The operations supplied with GMTL are implemented generically using a |
---|
74 | * technique |
---|
75 | * called <i>template metaprogramming</i>. Template metaprogramming |
---|
76 | * allows things such as loops to be unrolled and conditionals to be |
---|
77 | * evaluated |
---|
78 | * <i>by the compiler</i>. Things such as loops and conditionals are |
---|
79 | * evaluated statically, rather than at runtime. In addition, advanced |
---|
80 | * optimizations |
---|
81 | * can be performed that do this such as eliminate temporary variables and |
---|
82 | * other |
---|
83 | * intermediate computations. The result is compiled code that can behave as |
---|
84 | * fast |
---|
85 | * (or faster) then using traditional hand-coding methods such as loop |
---|
86 | * unrolling, etc... |
---|
87 | * |
---|
88 | * @subsection Testing Testing |
---|
89 | * GMTL has an integrated test suite included in the source code distribution. |
---|
90 | * The suite tests GMTL for correctness as well as performance degradation. |
---|
91 | * The GMTL developers have put much time and effort into the test suite |
---|
92 | * because |
---|
93 | * we think that it will ensure that the code stays stable when changes are |
---|
94 | * made, |
---|
95 | * and that changes don't introduce performance hits. The bottom line is, |
---|
96 | * if any |
---|
97 | * behaviour changes in GMTL we want to know about it before it bites us. |
---|
98 | * As a result |
---|
99 | * of this philosophy, any contributions to GMTL also need to be well |
---|
100 | * tested. |
---|
101 | * Submissions will not be accepted without tests for correctness and |
---|
102 | * performance. |
---|
103 | * |
---|
104 | * |
---|
105 | */ |
---|
106 | |
---|
107 | /** @defgroup Defines Global Flags: Xelt, XYZ, etc... |
---|
108 | * Constant Static Global Flags |
---|
109 | */ |
---|
110 | |
---|
111 | /** @defgroup Math C Math Abstraction: sin, cos, tan, Min, Max, PI |
---|
112 | * We've abstracted C math to be cross platform and typesafe. |
---|
113 | */ |
---|
114 | |
---|
115 | /** @defgroup Types Abstract Data Types: Matrix, Vec, Quat, Coord, Sphere, Plane |
---|
116 | * GMTL comes with many math data types: Vec, Point, Matrix, Quat, Coord, Sphere. |
---|
117 | */ |
---|
118 | |
---|
119 | |
---|
120 | |
---|
121 | /** @defgroup Ops Mathematical Operations: add(...), sub(...), mul(...), div(...), invert(...), dot(...), cross(...) |
---|
122 | * Implements fundamental mathematical operations such as +, -, *, invert, dot product. |
---|
123 | */ |
---|
124 | |
---|
125 | /** @defgroup Transforms Spacial Transformers: xform( ... ), operator*( ... ). |
---|
126 | * Transform points and vectors by Matrices and Quaternions. Note that xform |
---|
127 | * is defined differently for Point and Vec. By Point is a full xform, by Vec |
---|
128 | * is only a rotation. |
---|
129 | */ |
---|
130 | |
---|
131 | /** @defgroup Compare Comparison: isEqual(...), isEquiv(...), ==, != |
---|
132 | * Tests for equality between GMTL data types. |
---|
133 | */ |
---|
134 | |
---|
135 | /** @defgroup Generate Generators: make( ... ), set( ... ). |
---|
136 | * Make get and set functions for all math types in gmtl. |
---|
137 | */ |
---|
138 | |
---|
139 | /** @defgroup Interp Interpolation: lerp(...), slerp(...) |
---|
140 | * Functions to interpolate between two values. |
---|
141 | */ |
---|
142 | |
---|
143 | |
---|
144 | /** @defgroup Output Output Stream Methods: operator<<( ... ). |
---|
145 | * Output GMTL data types to an ostream. std::ostream& operator<< methods... |
---|
146 | */ |
---|
147 | |
---|
148 | |
---|
149 | /** @defgroup Meta Template Metaprogramming Utilities */ |
---|
150 | /** @defgroup HelperMeta Template Metaprogramming Utilities (Helpers) */ |
---|