[doc] Hooks up cogl-matrix reference documentation

Adds a few more gtk-doc notes to cogl-matrix.h, and adds a new section to
cogl-sections.txt

clutter/cogl/cogl-matrix.h

@@ -1,8 +1,42 @@
 #ifndef __COGL_MATRIX_H
 #define __COGL_MATRIX_H
 
-/* Note: This is ordered according to how OpenGL expects to get 4x4 matrices */
+#include <glib.h>
-typedef struct {
+
+G_BEGIN_DECLS
+
+/**
+ * SECTION:cogl-matrix
+ * @short_description: Fuctions for initializing and manipulating 4x4
+ *                     matrices.
+ *
+ * Matrices are used in Cogl to describe affine model-view transforms and
+ * texture transforms, and projective transforms. This exposes a utility API
+ * that can be used for direct manipulation of these matrices.
+ */
+
+
+/**
+ * CoglMatrix:
+ *
+ * A CoglMatrix holds a 4x4 transform matrix. This is a single precision,
+ * column-major matrix which means it is compatible with what OpenGL expects.
+ *
+ * A CoglMatix can represent transforms such as, rotations, scaling,
+ * translation, sheering, and linear projections. You can combine these
+ * transforms by multiplying multiple matrices in the order you want them
+ * applied.
+ *
+ * The transformation of a vertex (x, y, z, w) by a CoglMatrix is given by:
+ * <programlisting>
+ * x_new = xx * x + xy * y + xz * z + xw * w
+ * y_new = yx * x + yy * y + yz * z + yw * w
+ * z_new = zx * x + zy * y + zz * z + zw * w
+ * w_new = wx * x + wy * y + wz * z + ww * w
+ * </programlisting>
+ * Where w is normally 1
+ */
+typedef struct _CoglMatrix {
     /* column 0 */
     float xx;
     float yx;
@@ -27,6 +61,8 @@ typedef struct {
     float zw;
     float ww;
 
+    /*< private >*/
+
     /* Note: we may want to extend this later with private flags
      * and a cache of the inverse transform matrix. */
 } CoglMatrix;
@@ -35,7 +71,13 @@ typedef struct {
  * cogl_matrix_init_identity:
  * @matrix: A 4x4 transformation matrix
  *
- * Resets matrix to the identity matrix
+ * Resets matrix to the identity matrix:
+ * <programlisting>
+ * .xx=1; .xy=0; .xz=0; .xw=0;
+ * .yx=0; .yy=1; .yz=0; .yw=0;
+ * .zx=0; .zy=0; .zz=1; .zw=0;
+ * .wx=0; .wy=0; .wz=0; .ww=1;
+ * </programlisting>
  */
 void cogl_matrix_init_identity (CoglMatrix *matrix);
 
@@ -46,7 +88,7 @@ void cogl_matrix_init_identity (CoglMatrix *matrix);
  * @b: A 4x4 transformation matrix
  *
  * This function multiples the two supplied matricies together and stores
- * the result in 'result'
+ * the result in #result
  */
 void cogl_matrix_multiply (CoglMatrix *result,
 			   const CoglMatrix *a,
@@ -61,7 +103,7 @@ void cogl_matrix_multiply (CoglMatrix *result,
  * @z: Z component of your rotation vector
  *
  * This function multiples your matrix with a rotation matrix that applies
- * a rotation of angle degrees around the specified 3D vector.
+ * a rotation of #angle degrees around the specified 3D vector.
  */
 void cogl_matrix_rotate (CoglMatrix *matrix,
 			 float angle,
@@ -98,5 +140,7 @@ void cogl_matrix_scale (CoglMatrix *matrix,
 			float sy,
 			float sz);
 
+G_END_DECLS
+
 #endif /* __COGL_MATRIX_H */
 

doc/reference/cogl/cogl-docs.sgml

@@ -55,6 +55,7 @@
     <xi:include href="xml/cogl.xml"/>
     <xi:include href="xml/cogl-primitives.xml"/>
     <xi:include href="xml/cogl-util.xml"/>
+    <xi:include href="xml/cogl-matrix.xml"/>
     <xi:include href="xml/cogl-texture.xml"/>
     <xi:include href="xml/cogl-shaders.xml"/>
     <xi:include href="xml/cogl-offscreen.xml"/>

doc/reference/cogl/cogl-sections.txt

@@ -293,3 +293,14 @@ cogl_mesh_draw_range_elements
 cogl_mesh_submit
 </SECTION>
 
+<SECTION>
+<FILE>cogl-matrix</FILE>
+<TITLE>Matrices</TITLE>
+CoglMatrix
+cogl_matrix_init_identity
+cogl_matrix_multiply
+cogl_matrix_rotate
+cogl_matrix_translate
+cogl_matrix_scale
+</SECTION>
+