[clutter] actor: documents _get/apply_relative_transform_matrix

[Robert Bragg <rbragg src gnome org>]

commit b66c22ac1c793a06492364399e6a948294a90465
Author: Robert Bragg <robert linux intel com>
Date:   Fri Jun 17 18:27:45 2011 +0100

    actor: documents _get/apply_relative_transform_matrix
    
    Although this patch doesn't make them public, it documents the
    _clutter_actor_get/apply_relative_transform_matrix functions so they
    could easily be made public if desired. I think these API could be
    useful to have publicly, and I originally documented them because I
    thought they would be needed in the MX toolkit.

 clutter/clutter-actor-private.h |    6 +-
 clutter/clutter-actor.c         |   92 +++++++++++++++++++++++++++++----------
 clutter/clutter-paint-volume.c  |    8 ++--
 clutter/clutter-texture.c       |    6 +-
 4 files changed, 79 insertions(+), 33 deletions(-)
---
diff --git a/clutter/clutter-actor-private.h b/clutter/clutter-actor-private.h
index d1cf0b2..3af853f 100644
--- a/clutter/clutter-actor-private.h
+++ b/clutter/clutter-actor-private.h
@@ -121,9 +121,9 @@ ClutterActor *_clutter_actor_get_stage_internal         (ClutterActor *actor);
 
 void _clutter_actor_apply_modelview_transform           (ClutterActor *self,
                                                          CoglMatrix *matrix);
-void _clutter_actor_apply_modelview_transform_recursive (ClutterActor *self,
-						         ClutterActor *ancestor,
-                                                         CoglMatrix *matrix);
+void _clutter_actor_apply_relative_transformation_matrix (ClutterActor *self,
+                                                          ClutterActor *ancestor,
+                                                          CoglMatrix *matrix);
 
 void _clutter_actor_rerealize (ClutterActor    *self,
                                ClutterCallback  callback,
diff --git a/clutter/clutter-actor.c b/clutter/clutter-actor.c
index 08c7f5e..df1f59e 100644
--- a/clutter/clutter-actor.c
+++ b/clutter/clutter-actor.c
@@ -683,9 +683,9 @@ static gboolean clutter_anchor_coord_is_zero (const AnchorCoord *coord);
 
 static void _clutter_actor_queue_only_relayout (ClutterActor *self);
 
-static void _clutter_actor_get_relative_modelview (ClutterActor *self,
-                                                   ClutterActor *ancestor,
-                                                   CoglMatrix *matrix);
+static void _clutter_actor_get_relative_transformation_matrix (ClutterActor *self,
+                                                               ClutterActor *ancestor,
+                                                               CoglMatrix *matrix);
 
 static ClutterPaintVolume *_clutter_actor_get_paint_volume_mutable (ClutterActor *self);
 
@@ -2029,7 +2029,7 @@ clutter_actor_apply_relative_transform_to_point (ClutterActor        *self,
       return;
     }
 
-  _clutter_actor_get_relative_modelview (self, ancestor, &matrix);
+  _clutter_actor_get_relative_transformation_matrix (self, ancestor, &matrix);
   cogl_matrix_transform_point (&matrix, &vertex->x, &vertex->y, &vertex->z, &w);
 }
 
@@ -2056,7 +2056,7 @@ _clutter_actor_fully_transform_vertices (ClutterActor *self,
   /* Note: we pass NULL as the ancestor because we don't just want the modelview
    * that gets us to stage coordinates, we want to go all the way to eye
    * coordinates */
-  _clutter_actor_apply_modelview_transform_recursive (self, NULL, &modelview);
+  _clutter_actor_apply_relative_transformation_matrix (self, NULL, &modelview);
 
   /* Fetch the projection and viewport */
   _clutter_stage_get_projection_matrix (CLUTTER_STAGE (stage), &projection);
@@ -2098,21 +2098,43 @@ clutter_actor_apply_transform_to_point (ClutterActor        *self,
   _clutter_actor_fully_transform_vertices (self, point, vertex, 1);
 }
 
-/* _clutter_actor_get_relative_modelview:
- *
- * Retrieves the modelview transformation relative to some ancestor
- * actor, or eye coordinates if NULL is given for the ancestor.
- */
-/* FIXME: We should be caching the stage relative modelview along with the
- * actor itself */
+/*
+ * _clutter_actor_get_relative_transformation_matrix:
+ * @self: The actor whose coordinate space you want to transform from.
+ * @ancestor: The ancestor actor whose coordinate space you want to transform too
+ *            or %NULL if you want to transform all the way to eye coordinates.
+ * @matrix: A #CoglMatrix to store the transformation
+ *
+ * This gets a transformation @matrix that will transform coordinates from the
+ * coordinate space of @self into the coordinate space of @ancestor.
+ *
+ * For example if you need a matrix that can transform the local actor
+ * coordinates of @self into stage coordinates you would pass the actor's stage
+ * pointer as the @ancestor.
+ *
+ * If you pass %NULL then the transformation will take you all the way through
+ * to eye coordinates. This can be useful if you want to extract the entire
+ * modelview transform that Clutter applies before applying the projection
+ * transformation. If you want to explicitly set a modelview on a CoglFramebuffer
+ * using cogl_set_modelview_matrix() for example then you would want a matrix
+ * that transforms into eye coordinates.
+ *
+ * <note>This function explicitly initializes the given @matrix. If you just
+ * want clutter to multiply a relative transformation with an existing matrix
+ * you can use clutter_actor_apply_relative_transformation_matrix() instead.
+ * </note>
+ *
+ */
+/* XXX: We should consider caching the stage relative modelview along with
+ * the actor itself */
 static void
-_clutter_actor_get_relative_modelview (ClutterActor *self,
-                                       ClutterActor *ancestor,
-                                       CoglMatrix *matrix)
+_clutter_actor_get_relative_transformation_matrix (ClutterActor *self,
+                                                   ClutterActor *ancestor,
+                                                   CoglMatrix *matrix)
 {
   cogl_matrix_init_identity (matrix);
 
-  _clutter_actor_apply_modelview_transform_recursive (self, ancestor, matrix);
+  _clutter_actor_apply_relative_transformation_matrix (self, ancestor, matrix);
 }
 
 /* Project the given @box into stage window coordinates, writing the
@@ -2220,7 +2242,8 @@ clutter_actor_get_allocation_vertices (ClutterActor  *self,
   vertices[3].y = box.y2;
   vertices[3].z = 0;
 
-  _clutter_actor_get_relative_modelview (self, ancestor, &modelview);
+  _clutter_actor_get_relative_transformation_matrix (self, ancestor,
+                                                     &modelview);
 
   cogl_matrix_transform_points (&modelview,
                                 3,
@@ -2366,14 +2389,37 @@ _clutter_actor_apply_modelview_transform (ClutterActor *self,
   CLUTTER_ACTOR_GET_CLASS (self)->apply_transform (self, matrix);
 }
 
-/* Recursively applies the transforms associated with this actor and
- * its ancestors to the given matrix. Use NULL if you want this
- * to go all the way down to the stage.
+/*
+ * clutter_actor_apply_relative_transformation_matrix:
+ * @self: The actor whose coordinate space you want to transform from.
+ * @ancestor: The ancestor actor whose coordinate space you want to transform too
+ *            or %NULL if you want to transform all the way to eye coordinates.
+ * @matrix: A #CoglMatrix to apply the transformation too.
+ *
+ * This multiplies a transform with @matrix that will transform coordinates
+ * from the coordinate space of @self into the coordinate space of @ancestor.
+ *
+ * For example if you need a matrix that can transform the local actor
+ * coordinates of @self into stage coordinates you would pass the actor's stage
+ * pointer as the @ancestor.
+ *
+ * If you pass %NULL then the transformation will take you all the way through
+ * to eye coordinates. This can be useful if you want to extract the entire
+ * modelview transform that Clutter applies before applying the projection
+ * transformation. If you want to explicitly set a modelview on a CoglFramebuffer
+ * using cogl_set_modelview_matrix() for example then you would want a matrix
+ * that transforms into eye coordinates.
+ *
+ * <note>This function doesn't initialize the given @matrix, it simply
+ * multiplies the requested transformation matrix with the existing contents of
+ * @matrix. You can use cogl_matrix_init_identity() to initialize the @matrix
+ * before calling this function, or you can use
+ * clutter_actor_get_relative_transformation_matrix() instead.</note>
  */
 void
-_clutter_actor_apply_modelview_transform_recursive (ClutterActor *self,
-						    ClutterActor *ancestor,
-                                                    CoglMatrix *matrix)
+_clutter_actor_apply_relative_transformation_matrix (ClutterActor *self,
+                                                     ClutterActor *ancestor,
+                                                     CoglMatrix *matrix)
 {
   ClutterActor *parent;
 
@@ -2387,8 +2433,8 @@ _clutter_actor_apply_modelview_transform_recursive (ClutterActor *self,
   parent = clutter_actor_get_parent (self);
 
   if (parent != NULL)
-    _clutter_actor_apply_modelview_transform_recursive (parent, ancestor,
-                                                        matrix);
+    _clutter_actor_apply_relative_transformation_matrix (parent, ancestor,
+                                                         matrix);
 
   _clutter_actor_apply_modelview_transform (self, matrix);
 }
diff --git a/clutter/clutter-paint-volume.c b/clutter/clutter-paint-volume.c
index 71dc8ee..ea2f6cf 100644
--- a/clutter/clutter-paint-volume.c
+++ b/clutter/clutter-paint-volume.c
@@ -1008,8 +1008,8 @@ _clutter_paint_volume_get_stage_paint_box (ClutterPaintVolume *pv,
 
   /* If the paint volume isn't already in eye coordinates... */
   if (pv->actor)
-    _clutter_actor_apply_modelview_transform_recursive (pv->actor, NULL,
-                                                        &modelview);
+    _clutter_actor_apply_relative_transformation_matrix (pv->actor, NULL,
+                                                         &modelview);
 
   _clutter_stage_get_projection_matrix (stage, &projection);
   _clutter_stage_get_viewport (stage,
@@ -1043,8 +1043,8 @@ _clutter_paint_volume_transform_relative (ClutterPaintVolume *pv,
   _clutter_paint_volume_set_reference_actor (pv, relative_to_ancestor);
 
   cogl_matrix_init_identity (&matrix);
-  _clutter_actor_apply_modelview_transform_recursive (actor,
-                                                      relative_to_ancestor,
+  _clutter_actor_apply_relative_transformation_matrix (actor,
+                                                       relative_to_ancestor,
                                                       &matrix);
 
   _clutter_paint_volume_transform (pv, &matrix);
diff --git a/clutter/clutter-texture.c b/clutter/clutter-texture.c
index de328f0..3ad53b9 100644
--- a/clutter/clutter-texture.c
+++ b/clutter/clutter-texture.c
@@ -531,9 +531,9 @@ update_fbo (ClutterActor *self)
         {
           CoglMatrix modelview;
           cogl_matrix_init_identity (&modelview);
-          _clutter_actor_apply_modelview_transform_recursive (source_parent,
-                                                              NULL,
-                                                              &modelview);
+          _clutter_actor_apply_relative_transformation_matrix (source_parent,
+                                                               NULL,
+                                                               &modelview);
           cogl_set_modelview_matrix (&modelview);
         }
     }