introduce texture loaders to make allocations lazy

This introduces the internal idea of texture loaders that track the
state for loading and allocating a texture. This defers a lot more work
until the texture is allocated.

There are several intentions to this change:

- provides a means for extending how textures are allocated without
  requiring all the parameters to be supplied in a single _texture_new()
  function call.

- allow us to remove the internal_format argument from all
  _texture_new() apis since using CoglPixelFormat is bad way of
  expressing the internal format constraints because it is too specific.

  For now the internal_format arguments haven't actually been removed
  but this patch does introduce replacement apis for controlling the
  internal format:

    cogl_texture_set_components() lets you specify what components your
    texture needs when it is allocated.
    cogl_texture_set_premultiplied() lets you specify whether a texture
    data should be interpreted as premultiplied or not.

- Enable us to support asynchronous texture loading + allocation in the
  future.

Of note, the _new_from_data() texture constructors all continue to
allocate textures immediately so that existing code doesn't need to be
adapted to manage the lifetime of the data being uploaded.

Reviewed-by: Neil Roberts <neil@linux.intel.com>
(cherry picked from commit 6a83de9ef4210f380a31f410797447b365a8d02c)

Note: Compared to the original patch, the ->premultipled state for
textures isn't forced to be %TRUE in _cogl_texture_init since that
effectively ignores the users explicitly given internal_format which was
a mistake and on master that change should have been made in the patch
that followed. The gtk-doc comments for cogl_texture_set_premultiplied()
and cogl_texture_set_components() have also been updated in-line with
this fix.

1 files changed, 90 insertions, 0 deletions

diff --git a/cogl/cogl-texture.h b/cogl/cogl-texture.h
index 2e3f25b7..55b3be94 100644
--- a/cogl/cogl-texture.h
+++ b/cogl/cogl-texture.h
@@ -256,6 +256,96 @@ cogl_texture_new_from_bitmap (CoglBitmap *bitmap,
 CoglBool
 cogl_is_texture (void *object);
 
+typedef enum _CoglTextureComponents
+{
+  COGL_TEXTURE_COMPONENTS_A = 1,
+  COGL_TEXTURE_COMPONENTS_RGB,
+  COGL_TEXTURE_COMPONENTS_RGBA,
+  COGL_TEXTURE_COMPONENTS_DEPTH
+} CoglTextureComponents;
+
+/**
+ * cogl_texture_set_components:
+ * @texture: a #CoglTexture pointer.
+ *
+ * Affects the internal storage format for this texture by
+ * determinging what components will be required for sampling later.
+ *
+ * This api affects how data is uploaded to the GPU since unused
+ * components can potentially be discarded from source data.
+ *
+ * By default the required components are automatically determined
+ * using the format of the source data that is first uploaded to
+ * the given @texture.
+ */
+void
+cogl_texture_set_components (CoglTexture *texture,
+                             CoglTextureComponents components);
+
+/**
+ * cogl_texture_get_components:
+ * @texture: a #CoglTexture pointer.
+ *
+ * Queries what components the given @texture stores internally as set
+ * via cogl_texture_set_components().
+ *
+ * By default the required components are automatically determined
+ * using the format of the source data that is first uploaded to
+ * the given @texture.
+ */
+CoglBool
+cogl_texture_get_components (CoglTexture *texture);
+
+/**
+ * cogl_texture_set_premultiplied:
+ * @texture: a #CoglTexture pointer.
+ * @premultiplied: Whether any internally stored red, green or blue
+ *                 components are pre-multiplied by an alpha
+ *                 component.
+ *
+ * Affects the internal storage format for this texture by determining
+ * whether red, green and blue color components should be stored as
+ * pre-multiplied alpha values.
+ *
+ * This api affects how data is uploaded to the GPU since Cogl will
+ * convert source data to have premultiplied or unpremultiplied
+ * components according to this state.
+ *
+ * For example if you create a texture via
+ * cogl_texture_2d_new_with_size() and then upload data via
+ * cogl_texture_set_data() passing a source format of
+ * %COGL_PIXEL_FORMAT_RGBA_8888 then Cogl will internally multiply the
+ * red, green and blue components of the source data by the alpha
+ * component, for each pixel so that the internally stored data has
+ * pre-multiplied alpha components. If you instead upload data that
+ * already has pre-multiplied components by passing
+ * %COGL_PIXEL_FORMAT_RGBA_8888_PRE as the source format to
+ * cogl_texture_set_data() then the data can be uploaded without being
+ * converted.
+ *
+ * By default the @premultipled state is @TRUE.
+ */
+void
+cogl_texture_set_premultiplied (CoglTexture *texture,
+                                CoglBool premultiplied);
+
+/**
+ * cogl_texture_get_premultiplied:
+ * @texture: a #CoglTexture pointer.
+ *
+ * Queries the pre-multiplied alpha status for internally stored red,
+ * green and blue components for the given @texture as set by
+ * cogl_texture_set_premultiplied().
+ *
+ * By default the pre-multipled state is @TRUE.
+ *
+ * Return value: %TRUE if red, green and blue components are
+ *               internally stored pre-multiplied by the alpha
+ *               value or %FALSE if not.
+ */
+CoglBool
+cogl_texture_get_premultiplied (CoglTexture *texture);
+
 /**
  * cogl_texture_get_width:
  * @texture: a #CoglTexture pointer.