From ec9af1b8b17bc7f0defed65b6481e9088a8d5783 Mon Sep 17 00:00:00 2001 From: Josh Holtrop Date: Mon, 23 May 2011 15:53:16 -0400 Subject: [PATCH] added doxygen documentation --- glslUtil.h | 193 ++++++++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 191 insertions(+), 2 deletions(-) diff --git a/glslUtil.h b/glslUtil.h index ff652aa..8062ca5 100644 --- a/glslUtil.h +++ b/glslUtil.h @@ -1,4 +1,8 @@ +/** + * @file glslUtil.h + */ + #ifndef GLSLUTIL_H #define GLSLUTIL_H @@ -8,14 +12,34 @@ #include #endif +/** + * A 3x3 matrix of GLfloat elements + * + * Matrices are stored in column-major order + */ typedef GLfloat guMatrix3x3[3][3]; +/** + * A 4x4 matrix of GLfloat elements + * + * Matrices are stored in column-major order + */ typedef GLfloat guMatrix4x4[4][4]; +/** + * Structure used to define an attribute binding + */ typedef struct { + /** GL vertex attribute index */ GLuint index; + /** GL vertex attribute name */ const char *name; } guAttribBinding; +/** + * Structure used to obtain a uniform location + */ typedef struct { + /** where to store the uniform location */ GLint *loc; + /** name of the uniform variable */ const char *name; } guUniformLocation; @@ -23,38 +47,203 @@ typedef struct { extern "C" { #endif +/** + * Load a matrix with the identity matrix. + * The matrix will be initialized to all zeros except for ones + * along the main diagonal. + * @param m the matrix to initialize + */ void guMatrixLoadIdentity(guMatrix4x4 *m); +/** + * Multiply two matrices. + * m and a can point to the same matrix. + * m should be different from b. + * @param m the output matrix + * @param a the first matrix + * @param b the second matrix + */ void guMatrixMult(guMatrix4x4 *m, guMatrix4x4 *a, guMatrix4x4 *b); +/** + * Multiply a matrix by a translation transformation matrix. + * @param m the matrix to update + * @param x the translation distance along the X axis + * @param y the translation distance along the Y axis + * @param z the translation distance along the Z axis + */ void guMatrixTranslate(guMatrix4x4 *m, GLfloat x, GLfloat y, GLfloat z); +/** + * Multiply a matrix by a scaling transformation matrix. + * @param m the matrix to update + * @param x the scale factor along the X axis + * @param y the scale factor along the Y axis + * @param z the scale factor along the Z axis + */ void guMatrixScale(guMatrix4x4 *m, GLfloat x, GLfloat y, GLfloat z); +/** + * Multiply a matrix by a rotation transformation matrix. + * @param m the matrix to update + * @param angle the rotation angle, in degrees + * @param specifies the vector of rotation + */ void guMatrixRotate(guMatrix4x4 *m, GLfloat angle, GLfloat x, GLfloat y, GLfloat z); +/** + * Multiply a matrix by a perspective projection matrix. + * @param m the matrix to update + * @param left the X coordinate of the left edge of the viewing pane + * @param right the X coordinate of the right edge of the viewing pane + * @param bottom the Y coordinate of the bottom edge of the viewing pane + * @param top the Y coordinate of the top edge of the viewing pane + * @param near the Z coordinate of the viewing pane / near clipping plane + * @param far the Z coordinate of the far clipping plane + * + * near and far should both be positive. + * It must be true that right > left and bottom > top and far > near. + */ void guMatrixFrustum(guMatrix4x4 *m, GLfloat left, GLfloat right, GLfloat bottom, GLfloat top, GLfloat near, GLfloat far); +/** + * Multiply a matrix by a perspective projection matrix. + * @param m the matrix to update + * @param fovy the vertical field-of-view angle in degrees + * @param aspect the aspect ratio (width/height) + * @param near the distance to the near clipping plane + * @param far the distance to the far clipping plane + * + * near and far should both be positive. + * It must be true that far > near. + */ void guMatrixPerspective(guMatrix4x4 *m, GLfloat fovy, GLfloat aspect, GLfloat near, GLfloat far); +/** + * Multiply a matrix by an orthogonal projection matrix. + * @param m the matrix to update + * @param left the X coordinate of the left edge of the viewing pane + * @param right the X coordinate of the right edge of the viewing pane + * @param bottom the Y coordinate of the bottom edge of the viewing pane + * @param top the Y coordinate of the top edge of the viewing pane + * @param near the Z coordinate of the near clipping plane + * @param far the Z coordinate of the far clipping plane + */ void guMatrixOrtho(guMatrix4x4 *m, GLfloat left, GLfloat right, GLfloat bottom, GLfloat top, GLfloat near, GLfloat far); +/** + * Extract the upper-left portion of a 4x4 matrix into a 3x3 matrix. + * @param out the 3x3 matrix to store the upper-left corner in + * @param in the 4x4 matrix to extract the upper-left corner from + */ void guMatrix4x4To3x3(guMatrix3x3 *out, const guMatrix4x4 *in); +/** + * Get log messages from an OpenGL shader object. + * @return the log messages, or NULL if none is available. + * + * The caller is responsible for freeing the log message returned with free(). + */ char *guGetShaderLog(GLuint id); +/** + * Get log messages from an OpenGL program object. + * @return the log messages, or NULL of none is available + * + * The caller is responsible for freeing the log message returned with free(). + */ char *guGetProgramLog(GLuint id); +/** + * Create an OpenGL shader object from a file. + * @param shaderType the OpenGL shader type (vertex or fragment) + * @param fname the file name containing the OpenGL Shading Language + * shader source code. + * + * The caller is responsible for deleting the shader object. + */ GLuint guMakeShaderFromFile(GLenum shaderType, const char *fname); +/** + * Create an OpenGL shader object from in-memory source. + * @param shaderType the OpenGL shader type (vertex or fragment) + * @param source pointer to the OpenGL Shading Language shader source code. + * + * The caller is responsible for deleting the shader object. + */ GLuint guMakeShader(GLenum shaderType, const char *source); -GLuint guMakeProgramFromSource(const char *v_shader, const char *f_shader, - const guAttribBinding *bindings); +/** + * Create an OpenGL program object from shader source files. + * @param v_shader the file name of the file containing the vertex + * shader source code. + * @param f_shader the file name of the file containing the fragment + * shader source code. + * @param bindings array of vertex attribute binding structures for + * instructing OpenGL where to link vertex attributes + * @return the program object ID or 0 on error + * + * On error any log messages are printed to standard error. + * If bindings is not NULL, it should point to an array of + * guAttribBinding structures. The array should be terminated + * by a NULL entry. + * The caller is reponsible for deleting the program object. + */ GLuint guMakeProgramFromFiles(const char *v_shader, const char *f_shader, const guAttribBinding *bindings); +/** + * Create an OpenGL program object from in-memory shader sources. + * @param v_shader pointer to the vertex shader source code. + * @param f_shader pointer to the fragment shader source code. + * @param bindings array of vertex attribute binding structures for + * instructing OpenGL where to link vertex attributes + * @return the program object ID or 0 on error + * + * On error any log messages are printed to standard error. + * If bindings is not NULL, it should point to an array of + * guAttribBinding structures. The array should be terminated + * by a NULL entry. + * The caller is reponsible for deleting the program object. + */ +GLuint guMakeProgramFromSource(const char *v_shader, const char *f_shader, + const guAttribBinding *bindings); +/** + * Create an OpenGL program object from previously created shader objects. + * @param v_shader_id the vertex shader object. + * @param f_shader_id the fragment shader object. + * @param bindings array of vertex attribute binding structures for + * instructing OpenGL where to link vertex attributes + * @return the program object ID or 0 on error + * + * On error any log messages are printed to standard error. + * If bindings is not NULL, it should point to an array of + * guAttribBinding structures. The array should be terminated + * by a NULL entry. + * The caller is reponsible for deleting the program and shader objects. + */ GLuint guMakeProgram(GLuint v_shader_id, GLuint f_shader_id, const guAttribBinding *bindings); +/** + * Get the locations of uniform variables in an OpenGL program object. + * @param program the OpenGL program object + * @param locs a pointer to uniform location structures + * + * locs should point to an array of guUniformLocation structures. + * The identifier pointed to by the loc element of each structure will + * be populated by the location of the uniform variable with name given + * by the name element of the structure. + * The array should be terminated by a NULL entry. + */ void guGetUniformLocations(GLuint program, guUniformLocation *locs); +/** + * Create an OpenGL buffer object containing contents from memory. + * @param target the OpenGL buffer target (ex: GL_ARRAY_BUFFER). + * @param usage the usage hint for the buffer (ex: GL_STATIC_DRAW). + * @param ptr a pointer to the memory block to be used to initialize + * the buffer contents. + * @param sz the number of bytes to put into the buffer. + * + * The caller is responsible for deleting the buffer object. + */ GLuint guMakeBuffer(GLenum target, GLenum usage, const void *ptr, size_t sz); #ifdef __cplusplus