Unofficial OpenGL Software Development Kit
0.5.0

#include <MatrixStack.h>
Implements a stack for glm::mat4 transformations.
A matrix stack is a sequence of transforms which you can preserve and restore as needed. The stack has the concept of a "current matrix", which can be retrieved with the Top() function. The top matrix can even be obtained as a float array. The pointer returned will remain valid until this object is destroyed (though its values will change when you modify the current matrix). This is useful for uploading matrices to OpenGL via `glUniformMatrix4fv`.
The other functions will rightmultiply a transformation matrix with the current matrix, thus changing the current matrix.
The main power of the matrix stack is the ability to preserve and restore matrices in a stack fashion. The current matrix can be preserved on the stack with Push() and the most recently preserved matrix can be restored with Pop(). You must ensure that you do not Pop() more times than you Push(). Also, while this matrix stack does not have an explicit size limit, if you Push() more times than you Pop(), then you can eventually run out of memory (unless you create and destroy the MatrixStack every frame).
The best way to manage the stack is to never use the Push() and Pop() methods directly. Instead, use the PushStack object to do all pushing and popping. That will ensure that overflows and underflows cannot not happen.
Public Member Functions  
MatrixStack ()  
Initializes the matrix stack with the identity matrix.  
MatrixStack (const glm::mat4 &initialMatrix)  
Initializes the matrix stack with the given matrix.  
Stack Maintanence Functions  
These functions maintain the matrix stack. You must take care not to underflow or overflow the stack.  
void  Push () 
Preserves the current matrix on the stack.  
void  Pop () 
Restores the most recently preserved matrix.  
void  Reset () 
Restores the current matrix to the value of the most recently preserved matrix. More...  
const glm::mat4 &  Top () const 
Retrieve the current matrix.  
Rotation Matrix Functions  
These functions rightmultiply the current matrix with a rotation matrix of some form. All rotation angles are counterclockwise for an observer looking down the axis direction. If an observer is facing so that the axis of rotation is pointing directly towards the user, then positive angles will rotate counterclockwise.  
void  Rotate (const glm::vec3 axis, float angDegCCW) 
Applies a rotation matrix about the given axis, with the given angle in degrees.  
void  RotateRadians (const glm::vec3 axis, float angRadCCW) 
Applies a rotation matrix about the given axis, with the given angle in radians.  
void  RotateX (float angDegCCW) 
Applies a rotation matrix about the +X axis, with the given angle in degrees.  
void  RotateY (float angDegCCW) 
Applies a rotation matrix about the +Y axis, with the given angle in degrees.  
void  RotateZ (float angDegCCW) 
Applies a rotation matrix about the +Z axis, with the given angle in degrees.  
Scale Matrix Functions  
These functions rightmultiply the current matrix with a scaling matrix of some form.  
void  Scale (const glm::vec3 &scaleVec) 
Applies a scale matrix, with the given glm::vec3 as the axis scales.  
void  Scale (float scaleX, float scaleY, float scaleZ) 
Applies a scale matrix, with the given values as the axis scales.  
void  Scale (float uniformScale) 
Applies a uniform scale matrix.  
Translation Matrix Functions  
These functions rightmultiply the current matrix with a translation matrix of some form.  
void  Translate (const glm::vec3 &offsetVec) 
Applies a translation matrix, with the given glm::vec3 as the offset.  
void  Translate (float transX, float transY, float transZ) 
Applies a translation matrix, with the given X, Y and Z values as the offset.  
Camera Matrix Functions  
These functions rightmultiply the current matrix with a matrix that transforms from a world space to the camera space expected by the Perspective() or Orthographic() functions.  
void  LookAt (const glm::vec3 &cameraPos, const glm::vec3 &lookatPos, const glm::vec3 &upDir) 
Applies a matrix that transforms to a cameraspace defined by a position, a target in the world, and an up direction. More...  
Projection Matrix Functions  
These functions rightmultiply the current matrix with a projection matrix of some form. These functions all transform positions into the 4D homogeneous space expected by the output of OpenGL vertex shaders. As such, these can be used directly with GLSL shaders. The space that these matrices transform from is defined as follows. The preprojection space, called camera space or eye space, has the camera/eye position at the origin. The camera faces down the Z axis, so objects with larger negative Z values are farther away. +Y is up and +X is to the right.  
void  Perspective (float degFOV, float aspectRatio, float zNear, float zFar) 
Applies a standard, OpenGLstyle perspective projection matrix. More...  
void  Orthographic (float left, float right, float bottom, float top, float zNear=1.0f, float zFar=1.0f) 
Applies a standard, OpenGLstyle orthographic projection matrix. More...  
void  PixelPerfectOrtho (glm::ivec2 size, glm::vec2 depthRange, bool isTopLeft=true) 
Applies an ortho matrix for pixelaccurate reproduction. More...  
Matrix Application  
These functions rightmultiply a userprovided matrix by the current matrix; the result becomes the new current matrix.  
void  ApplyMatrix (const glm::mat4 &theMatrix) 
Rightmultiplies the current matrix with the given one, making the result new current matrix.  
MatrixStack &  operator*= (const glm::mat4 &theMatrix) 
Rightmultiplies the current matrix with the given one, making the result new current matrix.  
Matrix Setting  
These functions directly set the value of the current matrix, replacing the old value. Previously preserved matrices on the stack are unaffected.  
void  SetMatrix (const glm::mat4 &theMatrix) 
The given matrix becomes the current matrix.  
void  SetIdentity () 
Sets the current matrix to the identity matrix.  
void glutil::MatrixStack::LookAt  (  const glm::vec3 &  cameraPos, 
const glm::vec3 &  lookatPos,  
const glm::vec3 &  upDir  
) 
Applies a matrix that transforms to a cameraspace defined by a position, a target in the world, and an up direction.
cameraPos  The worldspace position of the camera. 
lookatPos  The worldspace position the camera should be facing. It should not be equal to cameraPos. 
upDir  The worldspace direction vector that should be considered up. The generated matrix will be bad if the up direction is along the same direction as the direction the camera faces (the direction between cameraPos and lookatPos). 
void glutil::MatrixStack::Orthographic  (  float  left, 
float  right,  
float  bottom,  
float  top,  
float  zNear = 1.0f , 

float  zFar = 1.0f 

) 
Applies a standard, OpenGLstyle orthographic projection matrix.
left  The left cameraspace position in the X axis that will be captured within the projection. 
right  The right cameraspace position in the X axis that will be captured within the projection. 
bottom  The bottom cameraspace position in the Y axis that will be captured within the projection. 
top  The top cameraspace position in the Y axis that will be captured within the projection. 
zNear  The front cameraspace position in the Z axis that will be captured within the projection. 
zFar  The rear cameraspace position in the Z axis that will be captured within the projection. 
void glutil::MatrixStack::Perspective  (  float  degFOV, 
float  aspectRatio,  
float  zNear,  
float  zFar  
) 
Applies a standard, OpenGLstyle perspective projection matrix.
degFOV  The field of view. This is the angle in degrees between directly forward and the farthest visible point horizontally. 
aspectRatio  The ratio of the width of the view area to the height. 
zNear  The closest cameraspace distance to the camera that can be seen. The projection will be clipped against this value. It cannot be negative or 0.0. 
zFar  The farthest cameraspace distance from the camera that can be seen. The projection will be clipped against this value. It must be larger than zNear. 
void glutil::MatrixStack::PixelPerfectOrtho  (  glm::ivec2  size, 
glm::vec2  depthRange,  
bool  isTopLeft = true 

) 
Applies an ortho matrix for pixelaccurate reproduction.
A common use for orthographic projections is to create an ortho matrix that allows for pixelaccurate reproduction of textures. It allows you to provide vertices directly in window space.
The camera space that this function creates can have the origin at the topleft (with +y going down) or bottomleft (with +y going up). Note that a topleft orientation will have to flip the Y coordinate, which means that the winding order of any triangles are reversed.
The depth range is arbitrary and up to the user.
size  The size of the window space. 
depthRange  The near and far depth range. The x coord is zNear, and the y coord is zFar. 
isTopLeft  True if this should be topleft orientation, false if it should be bottomleft. 

inline 
Restores the current matrix to the value of the most recently preserved matrix.
This function does not affect the depth of the matrix stack.