[4] | 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) */ |
---|