AuroraMiddleware/glm
1
0
Fork 0
Code Issues Pull Requests Releases Wiki Activity
c4c558098f
glm/doc/pages.doxy
Christophe Riccio c4c558098f Added NewDocs patch
2011-02-07 12:31:35 +00:00

715 lines
21 KiB
Plaintext
Raw Blame History

/*!
\mainpage OpenGL Mathematics
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.
\li \subpage pg_started
\li \subpage pg_advanced
\li \subpage pg_differences
\li \subpage pg_deprecated
\li \subpage pg_issues
\li \subpage pg_faq
\li \subpage pg_samples
\li \subpage pg_reference
**/
/*!
\page pg_started Getting Started
\section started_compiler Compiler Setup
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.
\section started_sample Use Sample of GLM Core
\code
#include <glm/glm.hpp>
int foo()
{
glm::vec4 Position = glm::vec4(glm::vec3(0.0), 1.0);
glm::mat4 Model = glm::mat4(1.0);
Model[4] = glm::vec4(1.0, 1.0, 0.0, 1.0);
glm::vec4 Transformed = Model * Position;
return 0;
}
\endcode
\section started_dependencies Dependencies
When <glm/glm.hpp> is included, GLM provides all the GLSL features it implements in C++.
When an extension is included, all the dependent extensions will be included as well. All the extensions depend on GLM core. (<glm/glm.hpp>)
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_extensions GLM Extensions
GLM extends the core GLSL feature set with extensions. These extensions include: \ref gtc_quaternion "quaternion", \ref gtc_matrix_transform "transformation", \ref gtx_spline "spline", \ref gtc_matrix_inverse "matrix inverse", \ref gtx_color_space "color spaces", etc.
Note that some extensions are incompatible with other extensions; this may result in C++ name collisions when used together.
GLM provides two methods to use these extensions.
This method simply requires the inclusion of the extension implementation filename. The extension features are added to the GLM namespace.
\code
#include <glm/glm.hpp>
#include <glm/gtc/matrix_transform.hpp>
int foo()
{
glm::vec4 Position = glm::vec4(glm::vec3(0.0f), 1.0f);
glm::mat4 Model = glm::translate(
glm::mat4(1.0f), glm::vec3(1.0f));
glm::vec4 Transformed = Model * Position;
return 0;
}
\endcode
\section started_interop OpenGL Interoperability
It could be possible to implement <tt>glVertex3fv(glm::vec3(0))</tt> in C++ with the appropriate cast operator. It would result as a transparent cast in this example; however, cast operator may result in programs running with unexpected behaviors without build errors or any notification.
The \ref gtc_type_ptr extension provides a safe solution:
\code
#include <glm/glm.hpp>
#include <glm/gtc/type_ptr.hpp>
void foo()
{
glm::vec4 v(0.0f);
glm::mat4 m(1.0f);
...
glVertex3fv(glm::value_ptr(v))
glLoadMatrixfv(glm::value_ptr(m));
}
\endcode
Another solution inspired by STL:
\code
#include <glm/glm.hpp>
void foo()
{
glm::vec4 v(0.0f);
glm::mat4 m(1.0f);
...
glVertex3fv(&v[0]);
glLoadMatrixfv(&m[0][0]);
}
\endcode
**/
/*!
\page pg_advanced Advaned Usage
\section advanced_swizzle Swizzle Operators
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, <20>variable.x<>, <20>variable.xxy<78>, <20>variable.zxyy<79> are examples of swizzling.
\code
vec4 A;
vec2 B;
...
B.yx = A.wy;
B = A.xx;
\endcode
This functionally turns out to be really complicated, not to say impossible, to implement in C++ using the exact GLSL conventions. GLM provides 2 implementions this feature.
\subsection advanced_swizzle_macro Macro implementation
The first implementation follows the GLSL convensions accurately however it uses macros which might generates name conflicts with system headers or third party libraries so that it is disabled by default. To enable this implementation, GLM_SWIZZLE has to be defined before any inclusion of <glm/glm.hpp>.
\code
#define GLM_SWIZZLE
#include <glm/glm.hpp>
\endcode
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:
\code
#define GLM_SWIZZLE_XYZW
#define GLM_SWIZZLE_STQP
#include <glm/glm.hpp>
\endcode
\subsection advanced_swizzle_ext Extension implementation
A safer way to do swizzling is to use the extension GLM_GTC_swizzle. In term of functionalities, this extension is at the same level than GLSL expect that GLM support both static and dynamic swizzling where GLSL only support static swizzling.
Static swizzling is an operation which is resolved at build time but dynamic swizzling is revolved at runtime which is more flexible but slower especially when SSE instructions are used.
\code
#include <glm/glm.hpp>
#include <glm/gtc/swizzle.hpp>
void foo()
{
glm::vec4 ColorRGBA(1.0f, 0.5f, 0.0f, 1.0f);
<09>
// Dynamic swizzling (at run time, more flexible)
// l-value:
glm::vec4 ColorBGRA1 =
glm::swizzle(ColorRGBA, glm::B, glm::G, glm::R, glm::A);
// r-value:
glm::swizzle(ColorRGBA, glm::B, glm::G, glm::R, glm::A) = ColorRGBA;
// Static swizzling (at build time, faster)
// l-value:
glm::vec4 ColorBGRA2 =
glm::swizzle<glm::B, glm::G, glm::R, glm::A>(ColorRGBA);
// r-value:
glm::swizzle<glm::B, glm::G, glm::R, glm::A>(ColorRGBA) = ColorRGBA;
}
\endcode
\section advanced_notify Notification System
GLM includes a notification system which can display some information at build time:
\li Compiler
\li Build model: 32bits or 64 bits
\li C++ version
\li Architecture: x86, SSE, AVX, etc.
\li Included extensions
\li etc.
This system is disable by default. To enable this system, define GLM_MESSAGES before any inclusion of <glm/glm.hpp>.
\code
#define GLM_MESSAGES
#include <glm/glm.hpp>
\endcode
\section advanced_inline Force Inline
To push further the software performance, a programmer can define GLM_FORCE_INLINE before any inclusion of <glm/glm.hpp> to force the compiler to inline GLM code.
\code
#define GLM_FORCE_INLINE
#include <glm/glm.hpp>
\endcode
\section advanced_simd SIMD Support
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 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.
\code
#define GLM_FORCE_PURE
#include <glm/glm.hpp>
\endcode
\section advanced_compatibility Compatibility
Compilers have some language extensions that GLM will automatically take advantage of them when they are enabled. To increase cross platform compatibility and to avoid compiler extensions, a programmer can define GLM_FORCE_CXX98 before any inclusion of <glm/glm.hpp>.
\code
#define GLM_FORCE_CXX98
#include <glm/glm.hpp>
\endcode
**/
/*!
\page pg_deprecated Deprecated Function Replacements
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.
\section deprecated_opengl OpenGL Function Replacements
<b>glRotate{f,d}:</b>
From \ref gtc_matrix_transform.
\code
glm::mat4 glm::rotate(
glm::mat4 const & m,
float angle, glm::vec3 const & axis);
glm::dmat4 glm::rotate(
glm::dmat4 const & m,
double angle, glm::dvec3 const & axis);
\endcode
<b>glScale{f, d}:</b>
From \ref gtc_matrix_transform.
\code
glm::mat4 glm::scale(
glm::mat4 const & m,
glm::vec3 const & factors);
glm::dmat4 glm::scale(
glm::dmat4 const & m,
glm::dvec3 const & factors);
\endcode
<b>glTranslate{f, d}:</b>
From \ref gtc_matrix_transform.
\code
glm::mat4 glm::translate(
glm::mat4 const & m,
glm::vec3 const & translation);
glm::dmat4 glm::translate(
glm::dmat4 const & m,
glm::dvec3 const & translation);
\endcode
<b>glLoadIdentity:</b>
From \ref core.
\code
glm::mat4(1.0) or glm::mat4();
glm::dmat4(1.0) or glm::dmat4();
\endcode
<b>glMultMatrix{f, d}:</b>
From \ref core.
\code
glm::mat4() * glm::mat4();
glm::dmat4() * glm::dmat4();
\endcode
<b>glLoadTransposeMatrix{f, d}:</b>
From \ref core.
\code
glm::transpose(glm::mat4());
glm::transpose(glm::dmat4());
\endcode
<b>glMultTransposeMatrix{f, d}:</b>
From \ref core.
\code
glm::mat4() * glm::transpose(glm::mat4());
glm::dmat4() * glm::transpose(glm::dmat4());
\endcode
<b>glFrustum:</b>
From \ref gtc_matrix_transform.
\code
glm::mat4 glm::frustum(
float left, float right,
float bottom, float top,
float zNear, float zFar);
glm::dmat4 glm::frustum(
double left, double right,
double bottom, double top,
double zNear, double zFar);
\endcode
<b>glOrtho:</b>
From \ref gtc_matrix_transform.
\code
glm::mat4 glm::ortho(
float left, float right,
float bottom, float top,
float zNear, float zFar);
glm::dmat4 glm::ortho(
double left, double right,
double bottom, double top,
double zNear, double zFar);
\endcode
\section deprecated_glu GLU Function Replacements
<b>gluLookAt:</b>
From \ref gtc_matrix_transform.
\code
glm::mat4 glm::lookAt(
glm::vec3 const & eye,
glm::vec3 const & center,
glm::vec3 const & up);
glm::dmat4 glm::lookAt(
glm::dvec3 const & eye,
glm::dvec3 const & center,
glm::dvec3 const & up);
\endcode
<b>gluOrtho2D:</b>
From \ref gtc_matrix_transform.
\code
glm::mat4 glm::ortho(
float left, float right, float bottom, float top);
glm::dmat4 glm::ortho(
double left, double right, double bottom, double top);
\endcode
<b>gluPerspective:</b>
From \ref gtc_matrix_transform.
\code
glm::mat4 perspective(
float fovy, float aspect, float zNear, float zFar);
glm::dmat4 perspective(
double fovy, double aspect, double zNear, double zFar);
\endcode
<b>gluProject:</b>
From \ref gtc_matrix_transform.
\code
glm::vec3 project(
glm::vec3 const & obj,
glm::mat4 const & model,
glm::mat4 const & proj,
glm::{i, ' ', d}vec4 const & viewport);
glm::dvec3 project(
glm::dvec3 const & obj,
glm::dmat4 const & model,
glm::dmat4 const & proj,
glm::{i, ' ', d}vec4 const & viewport);
\endcode
<b>gluUnProject:</b>
From \ref gtc_matrix_transform.
\code
glm::vec3 unProject(
glm::vec3 const & win,
glm::mat4 const & model,
glm::mat4 const & proj,
glm::{i, ' '}vec4 const & viewport);
glm::dvec3 unProject(
glm::dvec3 const & win,
glm::dmat4 const & model,
glm::dmat4 const & proj,
glm::{i, ' ', d}vec4 const & viewport);
\endcode
**/
/*!
\page pg_differences Differences between GLSL and GLM core
GLM comes very close to replicating GLSL, but it is not exact. Here is a list of
differences between GLM and GLSL:
<ul>
<li>
Precision qualifiers. In GLSL numeric types can have qualifiers that define
the precision of that type. While OpenGL's GLSL ignores these qualifiers, OpenGL
ES's version of GLSL uses them.
C++ has no language equivalent to precision qualifiers. Instead, GLM provides
a set of typedefs for each kind of precision qualifier and type. These types can
be found in \ref core_precision "their own section".
Functions that take types tend to be templated on those types, so they can
take these qualified types just as well as the regular ones.
</li>
</ul>
**/
/*!
\page pg_faq FAQ
\section faq1 Why does GLM follow GLSL specification and conventions?
Following GLSL conventions is a really strict policy of GLM. GLM has been designed according to
the idea that everyone writes their own math library with their own conventions. The idea is that
brilliant developers (the OpenGL ARB) worked together and agreed to make GLSL. Following
GLSL conventions is a way to find consensus. Moreover, basically when a developer knows
GLSL, he knows GLM.
\section faq2 Does GLM run GLSL program?
No, GLM is a C++ implementation of a subset of GLSL.
\section faq3 Does a GLSL compiler build GLM codes?
No, this is not what GLM intends to do!
\section faq4 Should I use GTX extensions?
\ref gtx are qualified to be experimental extensions. 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
fairly the way OpenGL features are developed through extensions.
\section faq5 Where can I ask my questions?
A good place is the OpenGL Toolkits forum on OpenGL.org:
http://www.opengl.org/discussion_boards/ubbthreads.php?ubb=postlist&Board=10&page=1
\section faq6 Where can I find the documentation of extensions?
The Doxygen generated documentation includes a complete list of all extensions available.
Explore this documentation to get a complete view of all GLM capabilities!
http://glm.g-truc.net/html/index.html
\section faq7 Should I use 'using namespace glm;'?
NO! Chances are that if 'using namespace glm;' is called, name collisions will happen
because GLM is based on GLSL and GLSL is also a consensus on tokens so these tokens are
probably used quite often.
If you need frequent use of certain types, you can bring them into the global
namespace with a using declaration like this:
/code
using glm::mat4;
mat4 someVariable(3.0f);
/endcode
\section faq8 Is GLM fast?
First, GLM is mainly designed to be convenient and that's why it is written against GLSL specification. Following the 20-80 rules where 20% of the code grad 80% of the performances, GLM perfectly operates on the 80% of the code that consumes 20% of the performances. This said, on performance critical code section, the developers will probably have to write to specific code based on a specific design to reach peak performances but GLM can provides some descent performances alternatives based on approximations or SIMD instructions.
**/
/*!
\page pg_samples Code Samples
This series of samples only shows various GLM functionalities without consideration of any sort.
\section sample1 Compute a Triangle's Normal
\code
#include <glm/glm.hpp> // vec3 normalize cross
glm::vec3 computeNormal(
glm::vec3 const & a,
glm::vec3 const & b,
glm::vec3 const & c)
{
return glm::normalize(glm::cross(c - a, b - a));
}
\endcode
A potentially faster, but less accurate alternative:
\code
#include <glm/glm.hpp> // vec3 cross
#include <glm/gtx/fast_square_root.hpp> // fastNormalize
glm::vec3 computeNormal(
glm::vec3 const & a,
glm::vec3 const & b,
glm::vec3 const & c)
{
return glm::fastNormalize(glm::cross(c - a, b - a));
}
\endcode
\section sample2 Matrix Transform
\code
#include <glm/glm.hpp> //vec3, vec4, ivec4, mat4
#include <glm/gtc/matrix_transform.hpp> //translate, rotate, scale, perspective
#include <glm/gtc/type_ptr.hpp> //value_ptr
void setUniformMVP(
GLuint Location,
glm::vec3 const & Translate,
glm::vec3 const & Rotate)
{
glm::mat4 Projection =
glm::perspective(45.0f, 4.0f / 3.0f, 0.1f, 100.f);
glm::mat4 ViewTranslate = glm::translate(
glm::mat4(1.0f),
Translate);
glm::mat4 ViewRotateX = glm::rotate(
ViewTranslate,
Rotate.y, glm::vec3(-1.0f, 0.0f, 0.0f));
glm::mat4 View = glm::rotate(
ViewRotateX,
Rotate.x, glm::vec3(0.0f, 1.0f, 0.0f));
glm::mat4 Model = glm::scale(
glm::mat4(1.0f),
glm::vec3(0.5f));
glm::mat4 MVP = Projection * View * Model;
glUniformMatrix4fv(
Location, 1, GL_FALSE, glm::value_ptr(MVP));
}
\endcode
\section sample3 Vector Types
\code
#include <glm/glm.hpp> //vec2
#include <glm/gtc/type_precision.hpp> //hvec2, i8vec2, i32vec2
std::size_t const VertexCount = 4;
// Float quad geometry
std::size_t const PositionSizeF32 = VertexCount * sizeof(glm::vec2);
glm::vec2 const PositionDataF32[VertexCount] =
{
glm::vec2(-1.0f,-1.0f),
glm::vec2( 1.0f,-1.0f),
glm::vec2( 1.0f, 1.0f),
glm::vec2(-1.0f, 1.0f)
};
// Half-float quad geometry
std::size_t const PositionSizeF16 = VertexCount * sizeof(glm::hvec2);
glm::hvec2 const PositionDataF16[VertexCount] =
{
glm::hvec2(-1.0f, -1.0f),
glm::hvec2( 1.0f, -1.0f),
glm::hvec2( 1.0f, 1.0f),
glm::hvec2(-1.0f, 1.0f)
};
// 8 bits signed integer quad geometry
std::size_t const PositionSizeI8 = VertexCount * sizeof(glm::i8vec2);
glm::i8vec2 const PositionDataI8[VertexCount] =
{
glm::i8vec2(-1,-1),
glm::i8vec2( 1,-1),
glm::i8vec2( 1, 1),
glm::i8vec2(-1, 1)
};
// 32 bits signed integer quad geometry
std::size_t const PositionSizeI32 = VertexCount * sizeof(glm::i32vec2);
glm::i32vec2 const PositionDataI32[VertexCount] =
{
glm::i32vec2 (-1,-1),
glm::i32vec2 ( 1,-1),
glm::i32vec2 ( 1, 1),
glm::i32vec2 (-1, 1)
};
\endcode
\section sample4 Lighting
\code
#include <glm/glm.hpp> // vec3 normalize reflect dot pow
#include <glm/gtx/random.hpp> // vecRand3
// vecRand3, generate a random and equiprobable normalized vec3
glm::vec3 lighting(
intersection const & Intersection,
material const & Material,
light const & Light,
glm::vec3 const & View)
{
glm::vec3 Color = glm::vec3(0.0f);
glm::vec3 LightVertor = glm::normalize(
Light.position() - Intersection.globalPosition() +
glm::vecRand3(0.0f, Light.inaccuracy());
if(!shadow(
Intersection.globalPosition(),
Light.position(),
LightVertor))
{
float Diffuse = glm::dot(Intersection.normal(), LightVector);
if(Diffuse <= 0.0f)
return Color;
if(Material.isDiffuse())
Color += Light.color() * Material.diffuse() * Diffuse;
if(Material.isSpecular())
{
glm::vec3 Reflect = glm::reflect(
-LightVector,
Intersection.normal());
float Dot = glm::dot(Reflect, View);
float Base = Dot > 0.0f ? Dot : 0.0f;
float Specular = glm::pow(Base, Material.exponent());
Color += Material.specular() * Specular;
}
return Color;
}
\endcode
**/
/*!
\page pg_issues Known Issues
\section issue1 not Function
The GLSL keyword not is also a keyword in C++. To prevent name collisions, the GLSL not
function has been implemented with the name not_.
\section issue2 Half Based Types
GLM supports half float number types through the extension GLM_GTC_half_float. This extension provides the types half, hvec*, hmat*x* and hquat*.
Unfortunately, C++ 98 specification doesn<73>t support anonymous unions which limit hvec* vector components access to x, y, z and w.
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.
\code
#define GLM_FORCE_ONLY_XYZW
#include <glm/glm.hpp>
\endcode
**/
/*!
\page pg_reference References
OpenGL 4.1 core specification:
http://www.opengl.org/registry/doc/glspec41.core.20100725.pdf
GLSL 4.10 specification:
http://www.opengl.org/registry/doc/GLSLangSpec.4.10.6.clean.pdf
GLU 1.3 specification:
http://www.opengl.org/documentation/specs/glu/glu1_3.pdf
GLM HEAD snapshot:
http://ogl-math.git.sourceforge.net/git/gitweb.cgi?p=ogl-math/ogl-math;a=snapshot;h=HEAD;sf=tgz
GLM Trac, for bug report and feature request:
https://sourceforge.net/apps/trac/ogl-math
GLM website:
http://glm.g-truc.net
G-Truc Creation page:
http://www.g-truc.net/project-0016.html
The OpenGL Toolkits forum to ask questions about GLM:
http://www.opengl.org/discussion_boards/ubbthreads.php?ubb=postlist&Board=10&page=1
**/
Reference in New Issue View Git Blame Copy Permalink