From af0726480c29ac8c327ce302a55ef4eaed757594 Mon Sep 17 00:00:00 2001 From: Robert Bragg Date: Wed, 25 Feb 2009 16:23:09 +0000 Subject: [PATCH] [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 | 23 +++++++++++++++-------- clutter/cogl/common/cogl-matrix.c | 6 +++--- clutter/cogl/gl/cogl.c | 6 +++--- clutter/cogl/gles/cogl.c | 6 +++--- doc/reference/cogl/cogl-sections.txt | 2 ++ 5 files changed, 26 insertions(+), 17 deletions(-) diff --git a/clutter/cogl/cogl-matrix.h b/clutter/cogl/cogl-matrix.h index 2c8003b50..c8396cf44 100644 --- a/clutter/cogl/cogl-matrix.h +++ b/clutter/cogl/cogl-matrix.h @@ -35,8 +35,15 @@ G_BEGIN_DECLS * w_new = wx * x + wy * y + wz * z + ww * w * * 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 diff --git a/clutter/cogl/common/cogl-matrix.c b/clutter/cogl/common/cogl-matrix.c index 26b6b926d..a99473da9 100644 --- a/clutter/cogl/common/cogl-matrix.c +++ b/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; } diff --git a/clutter/cogl/gl/cogl.c b/clutter/cogl/gl/cogl.c index 8073ad10f..3443f7121 100644 --- a/clutter/cogl/gl/cogl.c +++ b/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 diff --git a/clutter/cogl/gles/cogl.c b/clutter/cogl/gles/cogl.c index f096a3775..49f6335f5 100644 --- a/clutter/cogl/gles/cogl.c +++ b/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 diff --git a/doc/reference/cogl/cogl-sections.txt b/doc/reference/cogl/cogl-sections.txt index 432ef75bf..78b3eb2e9 100644 --- a/doc/reference/cogl/cogl-sections.txt +++ b/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