[cogl-matrix] Documents that CoglMatrix members should be considered read only

In the future if we want to annotate matrices with internal flags, and add
caching of the inverse matrix then we need to ensure that all matrix
modifications are done by cogl_matrix API so we'd know when to dirty the
cache or update the flags.

This just adds documentation to that effect, and assuming the most likley
case where someone would try and directly write to matrix members would
probably be to load a constant matrix other than the identity matrix; I
renamed cogl_matrix_init_from_gl_matrix to cogl_matrix_init_from_array to
make it seem more general purpose.

clutter/cogl/cogl-matrix.h

@@ -35,8 +35,15 @@ G_BEGIN_DECLS
  * w_new = wx * x + wy * y + wz * z + ww * w
  * </programlisting>
  * Where w is normally 1
+ *
+ * Note: You must consider the members of the CoglMatrix structure read only,
+ * and all matrix modifications must be done via the cogl_matrix API. This
+ * allows Cogl to annotate the matrices internally. Violation of this will give
+ * undefined results. If you need to initialize a matrix with a constant other
+ * than the identity matrix you can use cogl_matrix_init_from_array().
  */
 typedef struct _CoglMatrix {
+
     /* column 0 */
     float xx;
     float yx;
@@ -92,7 +99,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,
@@ -163,22 +170,22 @@ cogl_matrix_transform_point (const CoglMatrix *matrix,
                              float *w);
 
 /**
- * cogl_matrix_init_from_gl_matrix:
+ * cogl_matrix_init_from_array:
  * @matrix: A 4x4 transformation matrix
- * @gl_matrix: A linear array of 16 Glfloats (column-major)
+ * @array: A linear array of 16 floats (column-major order)
  *
- * This initialises @matrix with the contents of @gl_matrix
+ * This initialises @matrix with the contents of @array
  */
-void cogl_matrix_init_from_gl_matrix (CoglMatrix *matrix, const float *gl_matrix);
+void cogl_matrix_init_from_array (CoglMatrix *matrix, const float *array);
 
 /**
- * cogl_matrix_get_gl_matrix:
+ * cogl_matrix_get_array:
  * @matrix: A 4x4 transformation matrix
  *
- * This casts a CoglMatrix to a GLfloat array which can be directly passed to
+ * This casts a CoglMatrix to a float array which can be directly passed to
  * OpenGL.
  */
-const float *cogl_matrix_get_gl_matrix (const CoglMatrix *matrix);
+const float *cogl_matrix_get_array (const CoglMatrix *matrix);
 
 G_END_DECLS
 

clutter/cogl/common/cogl-matrix.c

@@ -141,13 +141,13 @@ cogl_matrix_transform_point (const CoglMatrix *matrix,
 }
 
 void
-cogl_matrix_init_from_gl_matrix (CoglMatrix *matrix, const float *gl_matrix)
+cogl_matrix_init_from_array (CoglMatrix *matrix, const float *array)
 {
-  memcpy (matrix, gl_matrix, sizeof (float) * 16);
+  memcpy (matrix, array, sizeof (float) * 16);
 }
 
 const float *
-cogl_matrix_get_gl_matrix (const CoglMatrix *matrix)
+cogl_matrix_get_array (const CoglMatrix *matrix)
 {
   return (float *)matrix;
 }

clutter/cogl/gl/cogl.c

@@ -532,7 +532,7 @@ _cogl_add_stencil_clip (float x_offset,
 void
 _cogl_set_matrix (const CoglMatrix *matrix)
 {
-  const GLfloat *gl_matrix = cogl_matrix_get_gl_matrix (matrix);
+  const GLfloat *gl_matrix = cogl_matrix_get_array (matrix);
 
   GE (glLoadMatrixf (gl_matrix));
 }
@@ -1130,7 +1130,7 @@ cogl_get_modelview_matrix (CoglMatrix *matrix)
   /* Since it's internal to Cogl and CoglMatrix doesn't currently have
    * any flag members, we could avoid this extra copy if it really
    * bothers anyone */
-  cogl_matrix_init_from_gl_matrix (matrix, m);
+  cogl_matrix_init_from_array (matrix, m);
 }
 
 void
@@ -1141,7 +1141,7 @@ cogl_get_projection_matrix (CoglMatrix *matrix)
   /* Since it's internal to Cogl and CoglMatrix doesn't currently have
    * any flag members, we could avoid this extra copy if it really
    * bothers anyone */
-  cogl_matrix_init_from_gl_matrix (matrix, m);
+  cogl_matrix_init_from_array (matrix, m);
 }
 
 void

clutter/cogl/gles/cogl.c

@@ -455,7 +455,7 @@ _cogl_add_stencil_clip (float x_offset,
 void
 _cogl_set_matrix (const CoglMatrix *matrix)
 {
-  const GLfloat *gl_matrix = cogl_matrix_get_gl_matrix (matrix);
+  const GLfloat *gl_matrix = cogl_matrix_get_array (matrix);
 
   GE (glLoadMatrixf (gl_matrix));
 }
@@ -687,7 +687,7 @@ cogl_get_modelview_matrix (CoglMatrix *matrix)
   /* Since it's internal to Cogl and CoglMatrix doesn't currently have
    * any flag members, we could avoid this extra copy if it really
    * bothers anyone */
-  cogl_matrix_init_from_gl_matrix (matrix, m);
+  cogl_matrix_init_from_array (matrix, m);
 }
 
 void
@@ -698,7 +698,7 @@ cogl_get_projection_matrix (CoglMatrix *matrix)
   /* Since it's internal to Cogl and CoglMatrix doesn't currently have
    * any flag members, we could avoid this extra copy if it really
    * bothers anyone */
-  cogl_matrix_init_from_gl_matrix (matrix, m);
+  cogl_matrix_init_from_array (matrix, m);
 }
 
 void

doc/reference/cogl/cogl-sections.txt

@@ -322,6 +322,8 @@ cogl_matrix_multiply
 cogl_matrix_rotate
 cogl_matrix_translate
 cogl_matrix_scale
+cogl_matrix_init_from_array
+cogl_matrix_get_array
 </SECTION>
 
 <SECTION>