image: Add set_area() method

This method allows replacing an area inside the texture data used by a
ClutterImage.

clutter/clutter-image.c

@@ -233,12 +233,104 @@ clutter_image_set_data (ClutterImage     *image,
   return TRUE;
 }
 
+/**
+ * clutter_image_set_area:
+ * @image: a #ClutterImage
+ * @data: (array): the image data, as an array of bytes
+ * @pixel_format: the Cogl pixel format of the image data
+ * @rect: a rectangle indicating the area that should be set
+ * @row_stride: the length of each row inside @data
+ * @error: return location for a #GError, or %NULL
+ *
+ * Sets the image data to be display by @image, using @rect to indicate
+ * the position and size of the image data to be set.
+ *
+ * If the @image does not have any image data set when this function is
+ * called, a new texture will be created with the size of the width and
+ * height of the rectangle, i.e. calling this function on a newly created
+ * #ClutterImage will be the equivalent of calling clutter_image_set_data().
+ *
+ * If the image data was successfully loaded, the @image will be invalidated.
+ *
+ * In case of error, the @error value will be set, and this function will
+ * return %FALSE.
+ *
+ * The image data is copied in texture memory.
+ *
+ * Return value: %TRUE if the image data was successfully loaded,
+ *   and %FALSE otherwise.
+ *
+ * Since: 1.10
+ */
+gboolean
+clutter_image_set_area (ClutterImage                 *image,
+                        const guint8                 *data,
+                        CoglPixelFormat               pixel_format,
+                        const cairo_rectangle_int_t  *area,
+                        guint                         row_stride,
+                        GError                      **error)
+{
+  ClutterImagePrivate *priv;
+
+  g_return_val_if_fail (CLUTTER_IS_IMAGE (image), FALSE);
+  g_return_val_if_fail (data != NULL, FALSE);
+  g_return_val_if_fail (area != NULL, FALSE);
+
+  priv = image->priv;
+
+  if (priv->texture == NULL)
+    {
+      priv->texture = cogl_texture_new_from_data (area->width,
+                                                  area->height,
+                                                  COGL_TEXTURE_NONE,
+                                                  pixel_format,
+                                                  COGL_PIXEL_FORMAT_ANY,
+                                                  row_stride,
+                                                  data);
+    }
+  else
+    {
+      gboolean res;
+
+      res = cogl_texture_set_region (priv->texture,
+                                     0, 0,
+                                     area->x, area->y,
+                                     area->width, area->height,
+                                     area->width, area->height,
+                                     pixel_format,
+                                     row_stride,
+                                     data);
+
+      if (!res)
+        {
+          cogl_object_unref (priv->texture);
+          priv->texture = NULL;
+        }
+    }
+
+  if (priv->texture == NULL)
+    {
+      g_set_error_literal (error, CLUTTER_IMAGE_ERROR,
+                           CLUTTER_IMAGE_ERROR_INVALID_DATA,
+                           _("Unable to load image data"));
+      return FALSE;
+    }
+
+  clutter_content_invalidate (CLUTTER_CONTENT (image));
+
+  return TRUE;
+}
+
 /**
  * clutter_image_get_texture:
  * @image: a #ClutterImage
  *
  * Retrieves a pointer to the Cogl texture used by @image.
  *
+ * If you change the contents of the returned Cogl texture you will need
+ * to manually invalidate the @image with clutter_content_invalidate()
+ * in order to update the actors using @image as their content.
+ *
  * Return value: (transfer none): a pointer to the Cogl texture, or %NULL
  *
  * Since: 1.10

clutter/clutter-image.h

@@ -95,6 +95,12 @@ gboolean                clutter_image_set_data          (ClutterImage     *image
                                                          guint                         height,
                                                          guint                         row_stride,
                                                          GError                      **error);
+gboolean                clutter_image_set_area          (ClutterImage                 *image,
+                                                         const guint8                 *data,
+                                                         CoglPixelFormat               pixel_format,
+                                                         const cairo_rectangle_int_t  *rect,
+                                                         guint                         row_stride,
+                                                         GError                      **error);
 
 #if defined(COGL_ENABLE_EXPERIMENTAL_API) && defined(CLUTTER_ENABLE_EXPERIMENTAL_API)
 CoglTexture *           clutter_image_get_texture       (ClutterImage                 *image);

clutter/clutter.symbols

@@ -734,6 +734,7 @@ clutter_image_error_quark
 clutter_image_get_texture
 clutter_image_get_type
 clutter_image_new
+clutter_image_set_area
 clutter_image_set_data
 clutter_init
 clutter_init_error_get_type

doc/reference/clutter/clutter-sections.txt

@@ -3157,6 +3157,7 @@ ClutterImageClass
 ClutterImageError
 clutter_image_new
 clutter_image_set_data
+clutter_image_set_area
 clutter_image_get_texture
 <SUBSECTION Standard>
 CLUTTER_TYPE_IMAGE