[cairo-texture] Document redrawing behavior

Document that repeated calls to clutter_cairo_texture_create()
continue drawing on the same cairo_surface_t. Add
clutter_cairo_texture_clear() for when you don't want that behavior.

http://bugzilla.openedhand.com/show_bug.cgi?id=1599

Signed-off-by: Emmanuele Bassi <ebassi@linux.intel.com>

clutter/clutter-cairo-texture.c

@@ -54,6 +54,12 @@
  *   cairo_destroy (cr);
  * ]|
  *
+ * Although a new #cairo_t is created each time you call
+ * clutter_cairo_texture_create() or
+ * clutter_cairo_texture_create_region(), it uses the same
+ * #cairo_surface_t each time. You can call
+ * clutter_cairo_texture_clear() to erase the contents between calls.
+ *
  * <warning><para>Note that you should never use the code above inside the
  * #ClutterActor::paint or #ClutterActor::pick virtual functions or
  * signal handlers because it will lead to performance
@@ -760,3 +766,28 @@ clutter_cairo_texture_get_surface_size (ClutterCairoTexture *self,
   if (height)
     *height = self->priv->height;
 }
+
+/**
+ * clutter_cairo_texture_clear:
+ * @self: a #ClutterCairoTexture
+ *
+ * Clears @self's internal drawing surface, so that the next upload
+ * will replace the previous contents of the #ClutterCairoTexture
+ * rather than adding to it.
+ *
+ * Since: 1.0
+ */
+void
+clutter_cairo_texture_clear (ClutterCairoTexture *self)
+{
+  ClutterCairoTexturePrivate *priv;
+
+  g_return_if_fail (CLUTTER_IS_CAIRO_TEXTURE (self));
+
+  priv = self->priv;
+
+  if (!priv->cr_surface_data)
+    return;
+
+  memset (priv->cr_surface_data, 0, priv->height * priv->rowstride);
+}

clutter/clutter-cairo-texture.h

@@ -98,8 +98,10 @@ void          clutter_cairo_texture_get_surface_size (ClutterCairoTexture *self,
                                                       guint               *width,
                                                       guint               *height);
 
-void clutter_cairo_set_source_color (cairo_t            *cr,
+void          clutter_cairo_texture_clear            (ClutterCairoTexture *self);
-                                     const ClutterColor *color);
+
+void          clutter_cairo_set_source_color         (cairo_t             *cr,
+						      const ClutterColor  *color);
 
 G_END_DECLS