Math Lib Specification
| Prev: In Action | Next: In Action |
Enumeration for matrix types:
enum MatrixTypes {
MODEL,
VIEW,
PROJECTION,
AUX0, AUX1, AUX2, AUX3, AUX4, AIX5, AUX6, AUX7
};
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) void multPointMatrix(float *point, MatrixTypes aType, 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 * MODEL vsml->multPointMatrix(a, VSMathLib::MODEL, 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: In Action |