From 37e3ef23035aafe1cba5a1113a3d6ce19ed51998 Mon Sep 17 00:00:00 2001
From: Emmanuele Bassi <ebassi@gnome.org>
Date: Thu, 21 Feb 2013 13:01:58 +0000
Subject: [PATCH] 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(+)

diff --git a/clutter/clutter-offscreen-effect.c b/clutter/clutter-offscreen-effect.c
index d58227fdd..8d8c8522b 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 a5987d754..6e70cbe45 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 37b0ce35d..ecb8ff567 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 1e4471a9c..3c5473fa7 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