Unofficial OpenGL Software Development Kit: glutil::MatrixStack Class Reference

Unofficial OpenGL Software Development Kit 0.5.0

- Main Page
- Related Pages
- Modules
- Namespaces
- Classes
- Files

- Class List
- Class Index
- Class Hierarchy
- Class Members

All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Groups Pages
List of all members | Public Member Functions
glutil::MatrixStack Class Reference
Matrix Stack

`#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 right-multiply 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 right-multiply the current matrix with a rotation matrix of some form. All rotation angles are counter-clockwise 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 counter-clockwise.
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 right-multiply 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 right-multiply 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 right-multiply 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 camera-space defined by a position, a target in the world, and an up direction. More...
Projection Matrix Functions

These functions right-multiply 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 pre-projection 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, OpenGL-style 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, OpenGL-style orthographic projection matrix. More...
void | PixelPerfectOrtho (glm::ivec2 size, glm::vec2 depthRange, bool isTopLeft=true)
| Applies an ortho matrix for pixel-accurate reproduction. More...
Matrix Application
These functions right-multiply a user-provided matrix by the current matrix; the result becomes the new current matrix.
void | ApplyMatrix (const glm::mat4 &theMatrix)
| Right-multiplies the current matrix with the given one, making the result new current matrix.
MatrixStack & | operator*= (const glm::mat4 &theMatrix)
| Right-multiplies 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.

## Member Function Documentation

void glutil::MatrixStack::LookAt | ( | const glm::vec3 & | cameraPos,
|  | const glm::vec3 & | lookatPos,
|  | const glm::vec3 & | upDir
| ) |  |

Applies a matrix that transforms to a camera-space defined by a position, a target in the world, and an up direction.

Parameters

  cameraPos | The world-space position of the camera.
  lookatPos | The world-space position the camera should be facing. It should not be equal to cameraPos.
  upDir | The world-space 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, OpenGL-style orthographic projection matrix.

Parameters

  left | The left camera-space position in the X axis that will be captured within the projection.
  right | The right camera-space position in the X axis that will be captured within the projection.
  bottom | The bottom camera-space position in the Y axis that will be captured within the projection.
  top | The top camera-space position in the Y axis that will be captured within the projection.
  zNear | The front camera-space position in the Z axis that will be captured within the projection.
  zFar | The rear camera-space 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, OpenGL-style perspective projection matrix.

Parameters

  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 camera-space 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 camera-space 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 pixel-accurate reproduction.

A common use for orthographic projections is to create an ortho matrix that allows for pixel-accurate 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 top-left (with +y going down) or bottom-left (with +y going up). Note that a top-left 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.

Parameters

  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 top-left orientation, false if it should be bottom-left.

void glutil::MatrixStack::Reset | ( |  | ) |

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.

The documentation for this class was generated from the following file:

- C:/Projects/distro/glsdk_0_5_1/glutil/include/glutil/MatrixStack.h