# Math Lib Specification

Prev: In Action | Next: Header |

**Enumeration for matrix types:**

enum MatrixTypes { MODEL, VIEW, PROJECTION, AUX0, AUX1, AUX2, AUX3 };

These enumeration values are meant to be used to select the matrix on which to perform an operation. Most functions require a matrix type as a parameter. For instance to load the identity matrix in the projection matrix do as follows:

vsml->loadIdentity(VSMathLib::PROJECTION);

where vsml is the instance created for the VSMathLib class.

a second set of matrices, the computed matrices, is defined in the following enumeration:

enum ComputedMatrixTypes { VIEW_MODEL, PROJ_VIEW_MODEL, NORMAL, NORMAL_VIEW, NORMAL_MODEL };

As the name implies, these matrices can not be set by the user, rather they are computed on demand. They can however be assigned to a uniform variable. These matrices are part of the library since they are commonly used in graphics.

**Functions**

static VSML* getInstance (void)

VSMathLib works as a singleton. This code returns the pointer to the single instance of VSMathLib. The pointer is required to work with all the other functions of the library.

Example:

VSMathLib *vsml; ... vsml = VSMathLib::getInstance();

void setUniformBlockName(std::string blockName)

Use this function to set the uniform block name where the matrices reside. To use all the facilities provide in this library, all matrices must reside either on the same named block, or in the default block, see function `matricesToGL`

. If matrices are scattered in different blocks then `glGet`

must be used to retrieve the matrices, and VSShaderLib functions must be used to set the uniforms.

Passing “” to this function, or not calling it at all, implies that the uniforms are not in a named block, or that `glGet`

, and VSShaderLib, will be used to set the uniforms.

Example assuming the named block is named “Matrices”:

vsml->setUniformBlockName("Matrices");

void setUniformName(MatrixTypes matType, std::string uniName) void setUniformName(ComputedMatrixTypes matType, std::string uniName)

This function sets the semantics of the uniform variables. If these uniforms are in a named block, then `setUniformBlockName`

must also be called.

Example assuming a uniform block declared on the shader as follows:

layout (std140) uniform Matrices { mat4 viewModelMatrix; mat4 projMatrix; mat3 normalMatrix };

The code for the application could be:

vsml->setUniformBlockName("Matrices"); vsml->setuniformName(VSMathLib::VIEW_MODEL, "viewModelMatrix"); vsml->setuniformName(VSMathLib::PROJECTION, "projMatrix"); vsml->setuniformName(VSMathLib::NORMAL, "normalMatrix");

void setUniformArrayIndexName(MatrixTypes matType, std::string uniformName, int index) setUniformArrayIndexName(ComputedMatrixTypes matType, std::string uniformName, int index)

This function sets the semantics of the uniform variables placed in arrays. If these uniforms are in a named block, then `setUniformBlockName`

must also be called.

Example assuming a uniform block declared on the shader as follows:

layout (std140) uniform Matrices { mat4 matrix[2]; };

The code for the application could be:

vsml->setUniformBlockName("Matrices"); vsml->setuniformName(VSMathLib::VIEW_MODEL, "matrix[0]"); vsml->setuniformName(VSMathLib::PROJECTION, "matrix[1]");

void translate(MatrixTypes aType, float x, float y, float z)

Similar to `glTranslate*`

, but following a direct state access pattern. It can be applied to any matrix in the `MatrixTypes`

enumeration.

Example to translate 2 units in the Y axis:

vsml->translate(VSMathLib::MODEL, 0.0f, 2.0f, 0.0f);

void translate(float x, float y, float z)

Short code for translation applied to the `MODEL`

matrix.

Example to translate 2 units in the Y axis:

vsml->translate(0.0f, 2.0f, 0.0f);

void scale(MatrixTypes aType, float x, float y, float z)

Similar to `glScale*`

. It can be applied to any matrix in the `MatrixTypes`

enumeration.

Example to perform a uniform scale by 2 units:

vsml->scale(VSMathLib::MODEL, 2.0f, 2.0f, 2.0f);

void scale(float x, float y, float z)

Short code for scale applied to the `MODEL`

matrix.

Example to perform a uniform scale by 2 units:

vsml->scale(2.0f, 2.0f, 2.0f);

void rotate(MatrixTypes aType, float angle, float x, float y, float z)

Similar to `glRotate*`

. It can be applied to any matrix in the `MatrixTypes`

enumeration.

Example to perform a 45 degree rotation around the Y axis:

vsml->scale(VSMathLib::MODEL, 45, 0,1,0);

void rotate(float angle, float x, float y, float z)

Short code for scale applied to the `MODEL`

matrix.

Example to perform a 45 degree rotation around the Y axis:

vsml->scale(45, 0,1,0);

void multMatrix(MatrixTypes aType, float *aMatrix)

Multiplies an arbitrary matrix `aMatrix`

into the specified matrix `aType`

. It is assumed that `aMatrix`

is an array with 16 floats. Similar to `glMultMatrix*`

.

Example multiplying an arbitrary matrix `aMat`

into the `MODEL`

matrix:

vsml->multMatrix(VSMathLib::MODEL, aMat);

void loadIdentity(MatrixTypes aType)

Loads the identity matrix, similar to `glLoadIdentity`

.

Example loading the identity matrix in to the `PROJECTION`

matrix:

vsml->loadIdentity(VSMathLib::PROJECTION);

void loadMatrix(MatrixTypes aType, float *aMatrix)

Loads an arbitrary matrix `aMatrix`

, similar to `glLoadMatrix`

.

Example loading a matrix in to the `MODEL`

matrix:

float mat[16]; ... vsml->loadMatrix(VSMathLib::MODEL, mat);

void pushMatrix(MatrixTypes aType)

Places the current matrix in the stack. Similar to `glPushMatrix`

. Notice that there are separate stacks for each matrix type.

Example adding the current `MODEL`

matrix to the stack:

vsml->pushMatrix(VSMathLib::MODEL);

void popMatrix(MatrixTypes aType)

Pops the matrix from the top of the stack and assigns it to the specified matrix type.

Example poping a matrix from the `MODEL`

stack. After this operation the `MODEL`

matrix will have the values of the popped matrix.

vsml->popMatrix(VSMathLib::MODEL);

void lookAt(float xPos, float yPos, float zPos, float xLook, float yLook, float zLook, float xUp, float yUp, float zUp)

This function behaves as `gluLookAt`

, it only works in the `VIEW`

matrix. For instance, setting the camera location at (10, 10, 10), looking at the origin (0,0,0), and having the Y axis as the up vector results in:

vsml->lookAt(10, 10, 10, 0, 0, 0, 0, 1, 0);

void perspective(float fov, float ratio, float nearp, float farp)

Similar to `gluPerspective`

, it only works in the `PROJECTION`

matrix. Setting the perspective with a field of view of 50 degrees, an aspect ratio of 1.0, a near plane at one unit, and the far plane at 100 units can be achieved as follows:

vsml->perspective(50, 1, 1, 100);

void ortho(float l, float r, float b, float t, float n, float f)

Similar to `glOrtho`

, it only works in the `PROJECTION`

matrix. It can also be used to replace `gluOrtho2D`

, just place `near`

= -1.0 and `far`

= 1.0.

Example considering `left`

= `bottom`

= `near`

= -1 and `right`

= `top`

= `far`

= 1 :

vsml->ortho(-1.0, 1.0, -1.0, 1.0, -1.0, 1.0);

void frustum(float l, float r, float b, float t, float n, float f)

Similar to `glFrustum`

, it only works in the `PROJECTION`

matrix.

Example:

vsml->frustum(-1.0, 1.0, -1.0, 1.0, -1.0, 1.0);

float *get(MatrixTypes aType) float *get(ComputedMatrixTypes aType)

Similar to `glGet*`

.

Example:

float *m1, *m2; m1 = vsml->get(VSMathLib::VIEW); m2 = vsml->get(VSMathLib::NORMAL);

void matrixToGL(MatrixTypes aType) void matrixToGL(ComputedMatrixTypes aType) void matricesToGL()

These three functions send the matrices to OpenGL so that they can be used inside a shader. The first two versions, `matrixToGL`

, send a specific matrix, whereas the last version sends all matrices to which semantics has been defined, see `setUniform*`

.

When using uniform variables, these functions should be called before the draw command.

Example setting all matrices at once:

vsml->matricesToGL(); glDrawElements(...);

Example setting individual matrices. For instance, the `PROJECTION`

matrix can be set after calling `perspective`

.

vsml->perspective(...); vsml->matrixToGL(VSMathLib::PROJECTION);

Then before calling the draw command you just need to set the `MODEL`

matrix

vsml->matrixToGL(VSMathLib::MODEL); glDrawElements(...);

void multMatrixPoint(MatrixTypes aType, float *point, float *res) static void crossProduct( float *a, float *b, float *res) static float dotProduct(float *a, float * b) static void normalize(float *a) static void add( float *a, float *b, float *res) static void subtract( float *a, float *b, float *res) static float length(float *a)

These are a set of functions that operate on vectors. When the result is a vector, it is placed as the last param of the function.

Examples:

float res[4], a[4], b[4]; ... // computing res = MODEL * a vsml->multMatrixPoint(VSMathLib::MODEL, a, res); // computing res = a + b VSMathLib::add(a, b, res); // computing the dot product of a and b float dot = VSMathLib(a, b);

Prev: In Action | Next: Header |