From cdf19f3281c92cb3cd46df165f8f15153ac1aa0f Mon Sep 17 00:00:00 2001
From: Robert Bragg <robert@linux.intel.com>
Date: Mon, 22 Dec 2008 16:16:07 +0000
Subject: [PATCH] [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
---
 cogl-matrix.h                        | 54 +++++++++++++++++++++++++---
 doc/reference/cogl/cogl-docs.sgml    |  1 +
 doc/reference/cogl/cogl-sections.txt | 11 ++++++
 3 files changed, 61 insertions(+), 5 deletions(-)

diff --git a/cogl-matrix.h b/cogl-matrix.h
index 44444691e..08c4a7009 100644
--- a/cogl-matrix.h
+++ b/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 */
-typedef struct {
+#include <glib.h>
+
+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 */
 
diff --git a/doc/reference/cogl/cogl-docs.sgml b/doc/reference/cogl/cogl-docs.sgml
index d1718437e..f872b0349 100644
--- a/doc/reference/cogl/cogl-docs.sgml
+++ b/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"/>
diff --git a/doc/reference/cogl/cogl-sections.txt b/doc/reference/cogl/cogl-sections.txt
index 03247ff3c..84c43dbf3 100644
--- a/doc/reference/cogl/cogl-sections.txt
+++ b/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>
+