[clutter] Add a note on the paint volume origin

[Emmanuele Bassi <ebassi src gnome org>]

commit bbb7da03ac56a600b72dd81708db3f2af2113887
Author: Emmanuele Bassi <ebassi linux intel com>
Date:   Mon Feb 13 18:19:48 2012 +0000

    Add a note on the paint volume origin
    
    This should avoid trying to fix the origin of a paint volume set from
    the allocation's origin, and thus breaking everything.
    
    A PaintVolume for an actor is defined to be relative to the actor's
    modelview unless specifically modified by internal functions; the origin
    of an actor's allocation is, on the other hand, parent-relative.

 clutter/clutter-actor.c        |    5 ++++-
 clutter/clutter-paint-volume.c |    8 ++++++--
 clutter/clutter-types.h        |    5 ++++-
 3 files changed, 14 insertions(+), 4 deletions(-)
---
diff --git a/clutter/clutter-actor.c b/clutter/clutter-actor.c
index 61ec219..3bb8b96 100644
--- a/clutter/clutter-actor.c
+++ b/clutter/clutter-actor.c
@@ -4692,7 +4692,10 @@ clutter_actor_real_get_paint_volume (ClutterActor       *self,
   res = FALSE;
 
   /* we start from the allocation */
-  clutter_paint_volume_set_from_allocation (volume, self);
+  clutter_paint_volume_set_width (volume,
+                                  priv->allocation.x2 - priv->allocation.x1);
+  clutter_paint_volume_set_height (volume,
+                                   priv->allocation.y2 - priv->allocation.y1);
 
   /* if the actor has a clip set then we have a pretty definite
    * size for the paint volume: the actor cannot possibly paint
diff --git a/clutter/clutter-paint-volume.c b/clutter/clutter-paint-volume.c
index 5b54274..419b281 100644
--- a/clutter/clutter-paint-volume.c
+++ b/clutter/clutter-paint-volume.c
@@ -970,6 +970,10 @@ _clutter_actor_set_default_paint_volume (ClutterActor       *self,
 
   clutter_actor_get_allocation_box (self, &box);
 
+  /* we only set the width and height, as the paint volume is defined
+   * to be relative to the actor's modelview, which means that the
+   * allocation's origin has already been applied
+   */
   clutter_paint_volume_set_width (volume, box.x2 - box.x1);
   clutter_paint_volume_set_height (volume, box.y2 - box.y1);
 
@@ -984,8 +988,8 @@ _clutter_actor_set_default_paint_volume (ClutterActor       *self,
  * Sets the #ClutterPaintVolume from the allocation of @actor.
  *
  * This function should be used when overriding the
- * <function>get_paint_volume()</function> by #ClutterActor sub-classes that do
- * not paint outside their allocation.
+ * #ClutterActorClass.get_paint_volume() by #ClutterActor sub-classes
+ * that do not paint outside their allocation.
  *
  * A typical example is:
  *
diff --git a/clutter/clutter-types.h b/clutter/clutter-types.h
index 2136874..ecd0d16 100644
--- a/clutter/clutter-types.h
+++ b/clutter/clutter-types.h
@@ -112,9 +112,12 @@ typedef union _ClutterEvent             ClutterEvent;
  * whose members cannot be directly accessed.
  *
  * A <structname>ClutterPaintVolume</structname> represents an
- * a bounding volume whos internal representation isn't defined but
+ * a bounding volume whose internal representation isn't defined but
  * can be set and queried in terms of an axis aligned bounding box.
  *
+ * A <structname>ClutterPaintVolume</structname> for a #ClutterActor
+ * is defined to be relative from the current actor modelview matrix.
+ *
  * Other internal representation and methods for describing the
  * bounding volume may be added in the future.
  *