added doxygen documentation

glslUtil.h

@@ -1,4 +1,8 @@
 
+/**
+ * @file glslUtil.h
+ */
+
 #ifndef GLSLUTIL_H
 #define GLSLUTIL_H
 
@@ -8,14 +12,34 @@
 #include <GL/gl.h>
 #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 <x, y, z> 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