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

@@ -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;
+}

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__ */

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

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