texture: Adds cogl_texture_set_data convenience api

This adds a cogl_texture_set_data function that is basically just a
convenience wrapper around cogl_texture_set_region. In the common case
where you want to upload the full contents of a mipmap level though this
api takes 4 less arguments (6 in total) so it's a bit simpler.

Reviewed-by: Neil Roberts <neil@linux.intel.com>

(cherry picked from commit e651dbdc4e4f03016a3dee513e3680270a4a9142)

3 files changed, 89 insertions, 0 deletions

diff --git a/cogl/cogl-texture.c b/cogl/cogl-texture.c
index 1b97648a..69895008 100644
--- a/cogl/cogl-texture.c
+++ b/cogl/cogl-texture.c
@@ -610,6 +610,34 @@ cogl_texture_set_region (CoglTexture *texture,
   return status;
 }
 
+CoglBool
+cogl_texture_set_data (CoglTexture *texture,
+                       CoglPixelFormat format,
+                       int rowstride,
+                       const uint8_t *data,
+                       int level,
+                       CoglError **error)
+{
+  int level_width;
+  int level_height;
+
+  _cogl_texture_get_level_size (texture,
+                                level,
+                                &level_width,
+                                &level_height,
+                                NULL);
+
+  return _cogl_texture_set_region (texture,
+                                   level_width,
+                                   level_height,
+                                   format,
+                                   rowstride,
+                                   data,
+                                   0, 0, /* dest x, y */
+                                   level,
+                                   error);
+}
+
 /* Reads back the contents of a texture by rendering it to the framebuffer
  * and reading back the resulting pixels.
  *
diff --git a/cogl/cogl-texture.h b/cogl/cogl-texture.h
index b744babe..a0261da5 100644
--- a/cogl/cogl-texture.h
+++ b/cogl/cogl-texture.h
@@ -431,6 +431,66 @@ cogl_texture_set_region (CoglTexture *texture,
 #if defined (COGL_ENABLE_EXPERIMENTAL_API)
 
 /**
+ * cogl_texture_set_data:
+ * @texture a #CoglTexture.
+ * @format: the #CoglPixelFormat used in the source @data buffer.
+ * @rowstride: rowstride of the source @data buffer (computed from
+ *             the texture width and @format if it equals 0)
+ * @data: the source data, pointing to the first top-left pixel to set
+ * @level: The mipmap level to update (Normally 0 for the largest,
+ *         base texture)
+ * @error: A #CoglError to return exceptional errors
+ *
+ * Sets all the pixels for a given mipmap @level by copying the pixel
+ * data pointed to by the @data argument into the given @texture.
+ *
+ * @data should point to the first pixel to copy corresponding
+ * to the top left of the mipmap @level being set.
+ *
+ * If @rowstride equals 0 then it will be automatically calculated
+ * from the width of the mipmap level and the bytes-per-pixel for the
+ * given @format.
+ *
+ * A mipmap @level of 0 corresponds to the largest, base image of a
+ * texture and @level 1 is half the width and height of level 0. If
+ * dividing any dimension of the previous level by two results in a
+ * fraction then round the number down (floor()), but clamp to 1
+ * something like this:
+ *
+ * |[
+ *  next_width = MAX (1, floor (prev_width));
+ * ]|
+ *
+ * You can determine the number of mipmap levels for a given texture
+ * like this:
+ *
+ * |[
+ *  n_levels = 1 + floor (log2 (max_dimension));
+ * ]|
+ *
+ * Where %max_dimension is the larger of cogl_texture_get_width() and
+ * cogl_texture_get_height().
+ *
+ * It is an error to pass a @level number >= the number of levels that
+ * @texture can have according to the above calculation.
+ *
+ * <note>Since the storage for a #CoglTexture is allocated lazily then
+ * if the given @texture has not previously been allocated then this
+ * api can return %FALSE and throw an exceptional @error if there is
+ * not enough memory to allocate storage for @texture.</note>
+ *
+ * Return value: %TRUE if the data upload was successful, and
+ *               %FALSE otherwise
+ */
+CoglBool
+cogl_texture_set_data (CoglTexture *texture,
+                       CoglPixelFormat format,
+                       int rowstride,
+                       const uint8_t *data,
+                       int level,
+                       CoglError **error);
+
+/**
  * cogl_texture_set_region_from_bitmap:
  * @texture: a #CoglTexture pointer
  * @src_x: upper left coordinate to use from the source bitmap.
diff --git a/doc/reference/cogl-2.0-experimental/cogl-2.0-experimental-sections.txt b/doc/reference/cogl-2.0-experimental/cogl-2.0-experimental-sections.txt
index b0796e09..e6a4e93e 100644
--- a/doc/reference/cogl-2.0-experimental/cogl-2.0-experimental-sections.txt
+++ b/doc/reference/cogl-2.0-experimental/cogl-2.0-experimental-sections.txt
@@ -405,6 +405,7 @@ cogl_texture_get_height
 cogl_texture_get_format
 cogl_texture_is_sliced
 cogl_texture_get_data
+cogl_texture_set_data
 cogl_texture_set_region
 CoglTextureType