Allow lazy texture storage allocation

Consistent with how we lazily allocate framebuffers this patch allows us
to instantiate textures but still specify constraints and requirements
before allocating storage so that we can be sure to allocate the most
appropriate/efficient storage.

This adds a cogl_texture_allocate() function that is analogous to
cogl_framebuffer_allocate() which can optionally be called to explicitly
allocate storage and catch any errors. If this function isn't used
explicitly then Cogl will implicitly ensure textures are allocated
before the storage is needed.

It is generally recommended to rely on lazy storage allocation or at
least perform explicit allocation as late as possible so Cogl can be
fully informed about the best way to allocate storage.

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

(cherry picked from commit 1fa7c0f10a8a03043e3c75cb079a49625df098b7)

Note: This reverts the cogl_texture_rectangle_new_with_size API change
that dropped the CoglError argument and keeps the semantics of
allocating the texture immediately. This is because Mutter currently
uses this API so we will probably look at updating this later once
we have a corresponding Mutter patch prepared. The other API changes
were kept since they only affected experimental api.

cogl/cogl-texture.c

@@ -139,6 +139,7 @@ _cogl_texture_init (CoglTexture *texture,
   texture->max_level = 0;
   texture->width = width;
   texture->height = height;
+  texture->allocated = FALSE;
   texture->vtable = vtable;
   texture->framebuffers = NULL;
 }
@@ -440,6 +441,20 @@ _cogl_texture_get_type (CoglTexture *texture)
 void
 _cogl_texture_pre_paint (CoglTexture *texture, CoglTexturePrePaintFlags flags)
 {
+  /* Assert that the storage for the texture exists already if we're
+   * about to reference it for painting.
+   *
+   * Note: we abort on error here since it's a bit late to do anything
+   * about it if we fail to allocate the texture and the app could
+   * have explicitly allocated the texture earlier to handle problems
+   * gracefully.
+   *
+   * XXX: Maybe it could even be considered a programmer error if the
+   * texture hasn't been allocated by this point since it implies we
+   * are abount to paint with undefined texture contents?
+   */
+  cogl_texture_allocate (texture, NULL);
+
   texture->vtable->pre_paint (texture, flags);
 }
 
@@ -465,10 +480,12 @@ _cogl_texture_set_region_from_bitmap (CoglTexture *texture,
                             >= width, FALSE);
   _COGL_RETURN_VAL_IF_FAIL ((cogl_bitmap_get_height (bmp) - src_y)
                             >= height, FALSE);
+  _COGL_RETURN_VAL_IF_FAIL (width > 0, FALSE);
+  _COGL_RETURN_VAL_IF_FAIL (height > 0, FALSE);
 
-  /* Shortcut out early if the image is empty */
-  if (width == 0 || height == 0)
-    return TRUE;
+  /* Assert that the storage for this texture has been allocated */
+  if (!cogl_texture_allocate (texture, error))
+    return FALSE;
 
   /* Note that we don't prepare the bitmap for upload here because
      some backends may be internally using a different format for the
@@ -897,10 +914,12 @@ get_texture_bits_via_offscreen (CoglTexture    *texture,
                                        COGL_OFFSCREEN_DISABLE_DEPTH_AND_STENCIL,
                                        0);
 
-  if (offscreen == NULL)
-    return FALSE;
-
   framebuffer = COGL_FRAMEBUFFER (offscreen);
+  if (!cogl_framebuffer_allocate (framebuffer, &ignore_error))
+    {
+      cogl_error_free (ignore_error);
+      return FALSE;
+    }
 
   bitmap = cogl_bitmap_new_for_data (ctx,
                                      width, height,
@@ -1390,3 +1409,22 @@ _cogl_texture_spans_foreach_in_region (CoglSpan *x_spans,
 	}
     }
 }
+
+void
+_cogl_texture_set_allocated (CoglTexture *texture,
+                             CoglBool allocated)
+{
+  texture->allocated = allocated;
+}
+
+CoglBool
+cogl_texture_allocate (CoglTexture *texture,
+                       CoglError **error)
+{
+  if (texture->allocated)
+    return TRUE;
+
+  texture->allocated = texture->vtable->allocate (texture, error);
+
+  return texture->allocated;
+}