OpenGL Mathematics (GLM) is a C++ mathematics library for graphics software based on the OpenGL Shading Language (GLSL) specification.
GLM provides classes and functions designed and implemented with the same naming conventions and functionalities than GLSL so that when a programmer knows GLSL, he knows GLM as well which makes it really easy to use.
This project isn't limited by GLSL features. An extension system, based on the GLSL extension conventions, provides extended capabilities: matrix transformations, quaternions, half-based types, random numbers, etc...
This library works perfectly with OpenGL but it also ensures interoperability with other third party libraries and SDK. It is a good candidate for software rendering (Raytracing / Rasterisation), image processing, physic simulations and any context that requires a simple and convenient mathematics library.
GLM is written as a platform independent library with no dependence and officially supports the following compilers:
1. GCC 3.4 and higher
2. LLVM 2.3 and higher
3. Visual Studio 2005 and higher
The source code is licenced under the <a href="http://www.opensource.org/licenses/mit-license.php">MIT licence</a>.
Thanks for contributing to the project by submitting tickets for bug reports and feature requests. (SF.net account required). Any feedback is welcome at glm@g-truc.net.
GLM is a header only library, there is nothing to build to use it which increases its cross platform capabilities.
To use GLM, a programmer only has to include <glm/glm.hpp>. This provides all the GLSL features implemented by GLM.
GLM makes heavy usages of C++ templates. This design may significantly increase the compile time for files that use GLM. Precompiled headers are recommended to avoid this issue.
\ref gtc "Core extensions" are sets of functions and types that add onto the core.
These are considered reasonably stable, with their APIs not changing much between
versions. Each core extension is included with a separated header file include. All
of the core extensions are in the "glm/glc" directory.
\ref gtx "Experimental extensions" are sets of functions and types that add onto the
core. Unlike core extensions, their APIs are not considered particularly stable, which
is why they are "experimental". All of the experimental extensions are in the
"glm/gtx" directory. Like core extensions, each experimental extension is included
with a separate header file.
If you want to use all extensions by default, you may <tt>#include <glm/ext.hpp></tt>.
This includes all extensions, core and experimental.
All of GLM is defined as direct children of the glm namespace, including extensions. Note that some extensions are incompatible with other extensions; this may result in C++ name collisions when used together.
There is no dependence with external libraries or external headers like gl.h, gl3.h, glu.h or windows.h. However, if <boost/static_assert.hpp> is included, Boost static assert will be used throughout GLM code to provide compiled time errors.
\section started_interop OpenGL Interoperability
It is often useful to get a vector type as an array of its base type. For example, the
OpenGL function <tt>glUniform3fv()</tt> takes an array instead of 3 individual values.
If the vector and matrix types were simple arrays, then one could pass them to the function
like so: <tt>glUniform3fv(loc, 1, glm::vec3(0))</tt>. However, this is not the case;
the vector and matrix types are C++ classes, not arrays.
As you can see, this requires dereferencing the very first basic type of the object, not merely the first element. The [] operator on the matrix type returns a column vector; one must then access the first element of that column vector to get a pointer to the basic type.
\note This operation could have been built into the base vector and matrix types and performed with a cast operator. However, this has some downsides. Implicit casts
A common feature of shader languages like GLSL is components swizzling. This involves being able to select which components of a vector are used and in what order. For example, "variable.x", "variable.xxy", "variable.zxyy" are examples of swizzling.
The first implementation follows the GLSL convensions accurately. It uses macros to achieve this, which might generates name conflicts with system headers or third party libraries. Therefore, it is disabled by default. To enable this implementation, GLM_SWIZZLE must be defined before any inclusion of <glm/glm.hpp>.
This implementation can be partially enabled by defining GLM_SWIZZLE_XYZW, GLM_SWIZZLE_RGBA or GLM_SWIZZLE_STQP. Each macro only enable a set of swizzling operators. For example we can only enable x,y,z,w and s,t,q,p operators using:
A safer way to do swizzling is to use the <glm/gtc/swizzle.hpp> extension. This extension provides the GLSL functionality, but uses a different syntax for it. However, the swizzle extension also provides dynamic swizzling.
Static swizzling is resovled at compile-time. The swizzle mask ".xzyy" is as fixed as the type of a particular variable. Dynamic swizzling is resolved at runtime via function calls. Dynamic swizzling is more flexible, since one can choose the swizzle mask at runtime, but it runs slower. This performance issue is enhanced when \ref advanced_simd "SIMD instructions" are used.
GLM's functions are defined in headers, so they are defined with C++'s "inline" delcaration. This does not require the compiler to inline them, however. If you want to force the compiler to inline the function, using whatever capabilities that the compiler provides to do so, you can define GLM_FORCE_INLINE before any inclusion of <glm/glm.hpp>.
GLM provides some SIMD optimizations based on compiler intrinsics. These optimizations will be automatically utilized based on the build environment. These optimizations are mainly available through the extensions \ref gtx_simd_vec4 and \ref gtx_simd_mat4.
A programmer can restrict or force instruction sets used for these optimizations using GLM_FORCE_SSE2 or GLM_FORCE_AVX.
A programmer can discard the use of intrinsics by defining GLM_FORCE_PURE before any inclusion of <glm/glm.hpp>. If GLM_FORCE_PURE is defined, then including a SIMD extension will generate a build error.
Compilers have some language extensions that GLM will automatically take advantage of them when they are enabled. The #define GLM_FORCE_CXX98 can switch off these extensions, forcing GLM to operate on pure C++98.
The OpenGL 3.0 specification deprecated some features, and most of these have been removed from the OpenGL 3.1 specfication and beyond. GLM provides some replacement functions. Many of these functions come from the \ref gtc_matrix_transform extension.
<dd>The default constructor of all matrix types creates an identity matrix.</dd>
<dt>glMultMatrix[fd]</dt>
<dd>Per the GLSL specification, the multiplication operator is overloaded for all matrix types. Multiplying two matrices together will perform matrix multiplication.</dd>
\ref gtx are experimental. In GLM this means that these extensions might change from version to version without restriction. In practice, it doesn't really change except time to time. GTC extensions are stabled, tested and perfectly reliable in time. Many GTX extensions extend GTC extensions and provide a way to explore features and implementations before becoming stable by a promotion as GTC extensions. This is similar to how OpenGL extensions can be EXT or ARB extensions before becoming core functionality.
In short, if you use a GTX extension, the API is much more likely to change from version to version than if you don't. But you should not feel too uncomfortable about using them.
This is unwise. There is every chance that are that if 'using namespace glm;' is called, name collisions will happen. GLSL names for functions are fairly generic, so it is entirely likely that there is another function called, for example, \link glm::sqrt sqrt \endlink.
GLM is mainly designed to be convenient; that's why it is written against GLSL specification.
The <a href="http://en.wikipedia.org/wiki/Pareto_principle">80-20</a> rule suggests that 80% of a program's performance comes from 20% of its code. Therefore, one must first identify which 20% of the code is impacting the performance.
In general, if one identifies certain math code to be a performance bottleneck, the only way to solve this is to write specialized code for those particular math needs. So no canned library solution would be suitable.
That being said, GLM can provides some descent performances alternatives based on approximations or SIMD instructions.
However, Visual C++ does support anonymous unions if the language extensions are enabled (/Za to disable them). In this case GLM will automatically enables the support of all component names (x,y,z,w ; r,g,b,a ; s,t,p,q).
To uniformalize the component access across types, GLM provides the define GLM_FORCE_ONLY_XYZW which will generates errors if component accesses are done using r,g,b,a or s,t,p,q.
