[clutter] offscreen-effect: Add a method to get the target area

[Emmanuele Bassi <ebassi src gnome org>]

commit 37e3ef23035aafe1cba5a1113a3d6ce19ed51998
Author: Emmanuele Bassi <ebassi gnome org>
Date:   Thu Feb 21 13:01:58 2013 +0000

    offscreen-effect: Add a method to get the target area
    
    The target size is not always enough, there are cases where the offset
    used to paint the target must also be available for developers
    implementing an OffscreenEffect.
    
    The get_target_rect() method returns the rectangle used to paint the
    target, with the offsets in the ClutterRect:origin and the texture size
    in the ClutterRect:size fields, respectively.
    
    The get_target_size() method should be deprecated, given that its
    replacement is generally more useful.
    
    https://bugzilla.gnome.org/show_bug.cgi?id=670004

 clutter/clutter-offscreen-effect.c         |   42 ++++++++++++++++++++++++++++
 clutter/clutter-offscreen-effect.h         |    6 ++++
 clutter/clutter.symbols                    |    1 +
 doc/reference/clutter/clutter-sections.txt |    1 +
 4 files changed, 50 insertions(+), 0 deletions(-)
---
diff --git a/clutter/clutter-offscreen-effect.c b/clutter/clutter-offscreen-effect.c
index d58227f..8d8c852 100644
--- a/clutter/clutter-offscreen-effect.c
+++ b/clutter/clutter-offscreen-effect.c
@@ -598,6 +598,8 @@ clutter_offscreen_effect_create_texture (ClutterOffscreenEffect *effect,
  *   and %FALSE otherwise
  *
  * Since: 1.8
+ *
+ * Deprecated: 1.14: Use clutter_offscreen_effect_get_target_rect() instead
  */
 gboolean
 clutter_offscreen_effect_get_target_size (ClutterOffscreenEffect *effect,
@@ -621,3 +623,43 @@ clutter_offscreen_effect_get_target_size (ClutterOffscreenEffect *effect,
 
   return TRUE;
 }
+
+/**
+ * clutter_offscreen_effect_get_target_rect:
+ * @effect: a #ClutterOffscreenEffect
+ * @rect: (out caller-allocates): return location for the target area
+ *
+ * Retrieves the origin and size of the offscreen buffer used by @effect to
+ * paint the actor to which it has been applied.
+ *
+ * This function should only be called by #ClutterOffscreenEffect
+ * implementations, from within the <function>paint_target()</function>
+ * virtual function.
+ *
+ * Return value: %TRUE if the offscreen buffer has a valid rectangle,
+ *   and %FALSE otherwise
+ *
+ * Since: 1.14
+ */
+gboolean
+clutter_offscreen_effect_get_target_rect (ClutterOffscreenEffect *effect,
+                                          ClutterRect            *rect)
+{
+  ClutterOffscreenEffectPrivate *priv;
+
+  g_return_val_if_fail (CLUTTER_IS_OFFSCREEN_EFFECT (effect), FALSE);
+  g_return_val_if_fail (rect != NULL, FALSE);
+
+  priv = effect->priv;
+
+  if (priv->texture == NULL)
+    return FALSE;
+
+  clutter_rect_init (rect,
+                     priv->x_offset,
+                     priv->y_offset,
+                     cogl_texture_get_width (priv->texture),
+                     cogl_texture_get_height (priv->texture));
+
+  return TRUE;
+}
diff --git a/clutter/clutter-offscreen-effect.h b/clutter/clutter-offscreen-effect.h
index a5987d7..6e70cbe 100644
--- a/clutter/clutter-offscreen-effect.h
+++ b/clutter/clutter-offscreen-effect.h
@@ -103,10 +103,16 @@ void            clutter_offscreen_effect_paint_target           (ClutterOffscree
 CoglHandle      clutter_offscreen_effect_create_texture         (ClutterOffscreenEffect *effect,
                                                                  gfloat                  width,
                                                                  gfloat                  height);
+
+CLUTTER_DEPRECATED_IN_1_14_FOR (clutter_offscreen_effect_get_target_rect)
 gboolean        clutter_offscreen_effect_get_target_size        (ClutterOffscreenEffect *effect,
                                                                  gfloat                 *width,
                                                                  gfloat                 *height);
 
+CLUTTER_AVAILABLE_IN_1_14
+gboolean        clutter_offscreen_effect_get_target_rect        (ClutterOffscreenEffect *effect,
+                                                                 ClutterRect            *rect);
+
 G_END_DECLS
 
 #endif /* __CLUTTER_OFFSCREEN_EFFECT_H__ */
diff --git a/clutter/clutter.symbols b/clutter/clutter.symbols
index 37b0ce3..ecb8ff5 100644
--- a/clutter/clutter.symbols
+++ b/clutter/clutter.symbols
@@ -981,6 +981,7 @@ clutter_model_set_types
 clutter_modifier_type_get_type
 clutter_offscreen_effect_create_texture
 clutter_offscreen_effect_get_target
+clutter_offscreen_effect_get_target_rect
 clutter_offscreen_effect_get_target_size
 clutter_offscreen_effect_get_texture
 clutter_offscreen_effect_get_type
diff --git a/doc/reference/clutter/clutter-sections.txt b/doc/reference/clutter/clutter-sections.txt
index 1e4471a..3c5473f 100644
--- a/doc/reference/clutter/clutter-sections.txt
+++ b/doc/reference/clutter/clutter-sections.txt
@@ -2746,6 +2746,7 @@ clutter_offscreen_effect_get_texture
 clutter_offscreen_effect_create_texture
 clutter_offscreen_effect_paint_target
 clutter_offscreen_effect_get_target_size
+clutter_offscreen_effect_get_target_rect
 <SUBSECTION Standard>
 CLUTTER_TYPE_OFFSCREEN_EFFECT
 CLUTTER_OFFSCREEN_EFFECT