Expose CoglAtlasTexture api

This exposes the CoglAtlasTexture api, making the following public:
cogl_atlas_texture_new_with_size
cogl_atlas_texture_new_from_file
cogl_atlas_texture_new_from_data
cogl_atlas_texture_new_from_bitmap

The plan is to remove auto-texture apis like cogl_texture_new_from_file
since they are a bit too magic, but that means we need an explicit way
for users to allocate texture that will go in the atlas.

Although the _new_from_file() api is arguably redundant since you can
use _bitmap_new_from_file() followed by _atlas_texture_new_from_bitmap()
we don't want to loose any of the convenience that
cogl_texture_new_from_file() had.

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

8 files changed, 327 insertions, 71 deletions

diff --git a/cogl-pango/cogl-pango-glyph-cache.c b/cogl-pango/cogl-pango-glyph-cache.c
index 27cdcbe8..d7da0bc1 100644
--- a/cogl-pango/cogl-pango-glyph-cache.c
+++ b/cogl-pango/cogl-pango-glyph-cache.c
@@ -224,12 +224,11 @@ cogl_pango_glyph_cache_add_to_global_atlas (CoglPangoGlyphCache *cache,
   if (cache->use_mipmapping)
     return FALSE;
 
-  texture = _cogl_atlas_texture_new_with_size (cache->ctx,
-                                               value->draw_width,
-                                               value->draw_height,
-                                               COGL_TEXTURE_NONE,
-                                               COGL_PIXEL_FORMAT_RGBA_8888_PRE,
-                                               &ignore_error);
+  texture = cogl_atlas_texture_new_with_size (cache->ctx,
+                                              value->draw_width,
+                                              value->draw_height,
+                                              COGL_PIXEL_FORMAT_RGBA_8888_PRE,
+                                              &ignore_error);
 
   if (texture == NULL)
     {
diff --git a/cogl/Makefile.am b/cogl/Makefile.am
index 45383011..3c8149ff 100644
--- a/cogl/Makefile.am
+++ b/cogl/Makefile.am
@@ -96,6 +96,7 @@ cogl_public_h = \
 	$(srcdir)/cogl-renderer.h 		\
 	$(srcdir)/cogl-snippet.h		\
 	$(srcdir)/cogl-sub-texture.h            \
+	$(srcdir)/cogl-atlas-texture.h          \
 	$(srcdir)/cogl-texture-2d-gl.h 		\
 	$(srcdir)/cogl-texture-2d-sliced.h      \
 	$(srcdir)/cogl-texture-2d.h             \
@@ -506,7 +507,7 @@ libcogl2_la_LDFLAGS = \
 	-no-undefined \
 	-version-info @COGL_LT_CURRENT@:@COGL_LT_REVISION@:@COGL_LT_AGE@ \
 	-export-dynamic \
-	-export-symbols-regex "^(cogl|_cogl_debug_flags|_cogl_atlas_new|_cogl_atlas_add_reorganize_callback|_cogl_atlas_reserve_space|_cogl_callback|_cogl_util_get_eye_planes_for_screen_poly|_cogl_atlas_texture_remove_reorganize_callback|_cogl_atlas_texture_add_reorganize_callback|_cogl_texture_foreach_sub_texture_in_region|_cogl_atlas_texture_new_with_size|_cogl_profile_trace_message|_cogl_context_get_default|_cogl_framebuffer_get_stencil_bits|_cogl_clip_stack_push_rectangle|_cogl_framebuffer_get_modelview_stack|_cogl_object_default_unref|_cogl_pipeline_foreach_layer_internal|_cogl_clip_stack_push_primitive|_cogl_buffer_unmap_for_fill_or_fallback|_cogl_framebuffer_draw_primitive|_cogl_debug_instances|_cogl_framebuffer_get_projection_stack|_cogl_pipeline_layer_get_texture|_cogl_buffer_map_for_fill_or_fallback|_cogl_framebuffer_get_clip_state|_cogl_texture_can_hardware_repeat|_cogl_pipeline_prune_to_n_layers|test_|unit_test_).*"
+	-export-symbols-regex "^(cogl|_cogl_debug_flags|_cogl_atlas_new|_cogl_atlas_add_reorganize_callback|_cogl_atlas_reserve_space|_cogl_callback|_cogl_util_get_eye_planes_for_screen_poly|_cogl_atlas_texture_remove_reorganize_callback|_cogl_atlas_texture_add_reorganize_callback|_cogl_texture_foreach_sub_texture_in_region|_cogl_profile_trace_message|_cogl_context_get_default|_cogl_framebuffer_get_stencil_bits|_cogl_clip_stack_push_rectangle|_cogl_framebuffer_get_modelview_stack|_cogl_object_default_unref|_cogl_pipeline_foreach_layer_internal|_cogl_clip_stack_push_primitive|_cogl_buffer_unmap_for_fill_or_fallback|_cogl_framebuffer_draw_primitive|_cogl_debug_instances|_cogl_framebuffer_get_projection_stack|_cogl_pipeline_layer_get_texture|_cogl_buffer_map_for_fill_or_fallback|_cogl_framebuffer_get_clip_state|_cogl_texture_can_hardware_repeat|_cogl_pipeline_prune_to_n_layers|test_|unit_test_).*"
 
 libcogl2_la_SOURCES = $(cogl_sources_c)
 nodist_libcogl2_la_SOURCES = $(BUILT_SOURCES)
diff --git a/cogl/cogl-atlas-texture-private.h b/cogl/cogl-atlas-texture-private.h
index 75c740e0..ae5799da 100644
--- a/cogl/cogl-atlas-texture-private.h
+++ b/cogl/cogl-atlas-texture-private.h
@@ -21,17 +21,14 @@
  *
  */
 
-#ifndef __COGL_ATLAS_TEXTURE_H
-#define __COGL_ATLAS_TEXTURE_H
+#ifndef _COGL_ATLAS_TEXTURE_PRIVATE_H_
+#define _COGL_ATLAS_TEXTURE_PRIVATE_H_
 
 #include "cogl-object-private.h"
 #include "cogl-texture-private.h"
 #include "cogl-rectangle-map.h"
 #include "cogl-atlas.h"
-
-#define COGL_ATLAS_TEXTURE(tex) ((CoglAtlasTexture *) tex)
-
-typedef struct _CoglAtlasTexture CoglAtlasTexture;
+#include "cogl-atlas-texture.h"
 
 struct _CoglAtlasTexture
 {
@@ -59,19 +56,10 @@ struct _CoglAtlasTexture
 
 CoglAtlasTexture *
 _cogl_atlas_texture_new_from_bitmap (CoglBitmap *bmp,
-                                     CoglTextureFlags flags,
                                      CoglPixelFormat internal_format,
                                      CoglBool can_convert_in_place,
                                      CoglError **error);
 
-CoglAtlasTexture *
-_cogl_atlas_texture_new_with_size (CoglContext *ctx,
-                                   int width,
-                                   int height,
-                                   CoglTextureFlags flags,
-                                   CoglPixelFormat internal_format,
-                                   CoglError **error);
-
 void
 _cogl_atlas_texture_add_reorganize_callback (CoglContext *ctx,
                                              GHookFunc callback,
@@ -85,4 +73,4 @@ _cogl_atlas_texture_remove_reorganize_callback (CoglContext *ctx,
 CoglBool
 _cogl_is_atlas_texture (void *object);
 
-#endif /* __COGL_ATLAS_TEXTURE_H */
+#endif /* _COGL_ATLAS_TEXTURE_PRIVATE_H_ */
diff --git a/cogl/cogl-atlas-texture.c b/cogl/cogl-atlas-texture.c
index b390cc2c..728cbaa7 100644
--- a/cogl/cogl-atlas-texture.c
+++ b/cogl/cogl-atlas-texture.c
@@ -643,42 +643,14 @@ _cogl_atlas_texture_can_use_format (CoglPixelFormat format)
 }
 
 CoglAtlasTexture *
-_cogl_atlas_texture_new_with_size (CoglContext *ctx,
-                                   int width,
-                                   int height,
-                                   CoglTextureFlags flags,
-                                   CoglPixelFormat internal_format,
-                                   CoglError **error)
+cogl_atlas_texture_new_with_size (CoglContext *ctx,
+                                  int width,
+                                  int height,
+                                  CoglPixelFormat internal_format,
+                                  CoglError **error)
 {
   CoglAtlasTexture *atlas_tex;
 
-  /* Don't put textures in the atlas if the user has explicitly
-     requested to disable it */
-  if (G_UNLIKELY (COGL_DEBUG_ENABLED (COGL_DEBUG_DISABLE_ATLAS)))
-    {
-      _cogl_set_error (error,
-                       COGL_SYSTEM_ERROR,
-                       COGL_SYSTEM_ERROR_UNSUPPORTED,
-                       "Atlasing disabled");
-      return NULL;
-    }
-
-  /* We can't put the texture in the atlas if there are any special
-     flags. This precludes textures with COGL_TEXTURE_NO_ATLAS and
-     COGL_TEXTURE_NO_SLICING from being atlased */
-  if (flags)
-    {
-      /* XXX: This is a bit of an odd error; if we make this api
-       * public then this should probably be dealt with at a higher
-       * level, in cogl-auto-texture.c:cogl_texture_new_with_size().
-       */
-      _cogl_set_error (error,
-                       COGL_SYSTEM_ERROR,
-                       COGL_SYSTEM_ERROR_UNSUPPORTED,
-                       "Usage constraints preclude atlasing texture");
-      return NULL;
-    }
-
   /* We can't atlas zero-sized textures because it breaks the atlas
      data structure */
   if (width < 1 || height < 1)
@@ -785,7 +757,6 @@ _cogl_atlas_texture_allocate (CoglTexture *tex,
 
 CoglAtlasTexture *
 _cogl_atlas_texture_new_from_bitmap (CoglBitmap *bmp,
-                                     CoglTextureFlags flags,
                                      CoglPixelFormat internal_format,
                                      CoglBool can_convert_in_place,
                                      CoglError **error)
@@ -806,10 +777,10 @@ _cogl_atlas_texture_new_from_bitmap (CoglBitmap *bmp,
   internal_format = _cogl_texture_determine_internal_format (bmp_format,
                                                              internal_format);
 
-  atlas_tex = _cogl_atlas_texture_new_with_size (ctx,
-                                                 bmp_width, bmp_height,
-                                                 flags, internal_format,
-                                                 error);
+  atlas_tex = cogl_atlas_texture_new_with_size (ctx,
+                                                bmp_width, bmp_height,
+                                                internal_format,
+                                                error);
   if (!atlas_tex)
     return NULL;
 
@@ -852,6 +823,74 @@ _cogl_atlas_texture_new_from_bitmap (CoglBitmap *bmp,
   return atlas_tex;
 }
 
+CoglAtlasTexture *
+cogl_atlas_texture_new_from_bitmap (CoglBitmap *bmp,
+                                    CoglPixelFormat internal_format,
+                                    CoglError **error)
+{
+  return _cogl_atlas_texture_new_from_bitmap (bmp, internal_format,
+                                              FALSE, error);
+}
+
+CoglAtlasTexture *
+cogl_atlas_texture_new_from_data (CoglContext *ctx,
+                                  int width,
+                                  int height,
+                                  CoglPixelFormat format,
+                                  CoglPixelFormat internal_format,
+                                  int rowstride,
+                                  const uint8_t *data,
+                                  CoglError **error)
+{
+  CoglBitmap *bmp;
+  CoglAtlasTexture *atlas_tex;
+
+  _COGL_RETURN_VAL_IF_FAIL (format != COGL_PIXEL_FORMAT_ANY, NULL);
+  _COGL_RETURN_VAL_IF_FAIL (data != NULL, NULL);
+
+  /* Rowstride from width if not given */
+  if (rowstride == 0)
+    rowstride = width * _cogl_pixel_format_get_bytes_per_pixel (format);
+
+  /* Wrap the data into a bitmap */
+  bmp = cogl_bitmap_new_for_data (ctx,
+                                  width, height,
+                                  format,
+                                  rowstride,
+                                  (uint8_t *) data);
+
+  atlas_tex = cogl_atlas_texture_new_from_bitmap (bmp, internal_format, error);
+
+  cogl_object_unref (bmp);
+
+  return atlas_tex;
+}
+
+CoglAtlasTexture *
+cogl_atlas_texture_new_from_file (CoglContext *ctx,
+                                  const char *filename,
+                                  CoglPixelFormat internal_format,
+                                  CoglError **error)
+{
+  CoglBitmap *bmp;
+  CoglAtlasTexture *atlas_tex = NULL;
+
+  _COGL_RETURN_VAL_IF_FAIL (error == NULL || *error == NULL, NULL);
+
+  bmp = cogl_bitmap_new_from_file (ctx, filename, error);
+  if (bmp == NULL)
+    return NULL;
+
+  atlas_tex = _cogl_atlas_texture_new_from_bitmap (bmp,
+                                                   internal_format,
+                                                   TRUE, /* convert in-place */
+                                                   error);
+
+  cogl_object_unref (bmp);
+
+  return atlas_tex;
+}
+
 void
 _cogl_atlas_texture_add_reorganize_callback (CoglContext *ctx,
                                              GHookFunc callback,
diff --git a/cogl/cogl-atlas-texture.h b/cogl/cogl-atlas-texture.h
new file mode 100644
index 00000000..5745ccae
--- /dev/null
+++ b/cogl/cogl-atlas-texture.h
@@ -0,0 +1,214 @@
+/*
+ * Cogl
+ *
+ * An object oriented GL/GLES Abstraction/Utility Layer
+ *
+ * Copyright (C) 2013 Intel Corporation.
+ *
+ * This library is free software; you can redistribute it and/or
+ * modify it under the terms of the GNU Lesser General Public
+ * License as published by the Free Software Foundation; either
+ * version 2 of the License, or (at your option) any later version.
+ *
+ * This library is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+ * Lesser General Public License for more details.
+ *
+ * You should have received a copy of the GNU Lesser General Public
+ * License along with this library. If not, see
+ * <http://www.gnu.org/licenses/>.
+ *
+ *
+ */
+
+#if !defined(__COGL_H_INSIDE__) && !defined(COGL_COMPILATION)
+#error "Only <cogl/cogl.h> can be included directly."
+#endif
+
+#ifndef _COGL_ATLAS_TEXTURE_H_
+#define _COGL_ATLAS_TEXTURE_H_
+
+#include <cogl/cogl-context.h>
+
+COGL_BEGIN_DECLS
+
+/**
+ * SECTION:cogl-atlas-texture
+ * @short_description: Functions for managing textures in Cogl's global
+ *                     set of texture atlases
+ *
+ * A texture atlas is a texture that contains many smaller images that
+ * an application is interested in. These are packed together as a way
+ * of optimizing drawing with those images by avoiding the costs of
+ * repeatedly telling the hardware to change what texture it should
+ * sample from.  This can enable more geometry to be batched together
+ * into few draw calls.
+ *
+ * Each #CoglContext has an shared, pool of texture atlases that are
+ * are managed by Cogl.
+ *
+ * This api lets applications upload texture data into one of Cogl's
+ * shared texture atlases using a high-level #CoglAtlasTexture which
+ * represents a sub-region of one of these atlases.
+ *
+ * <note>A #CoglAtlasTexture is a high-level meta texture which has
+ * some limitations to be aware of. Please see the documentation for
+ * #CoglMetaTexture for more details.</note>
+ */
+
+
+typedef struct _CoglAtlasTexture CoglAtlasTexture;
+#define COGL_ATLAS_TEXTURE(tex) ((CoglAtlasTexture *) tex)
+
+
+/**
+ * cogl_atlas_texture_new_with_size:
+ * @ctx: A #CoglContext
+ * @width: The width of your atlased texture.
+ * @height: The height of your atlased texture.
+ * @internal_format: The format of the texture
+ *
+ * Creates a #CoglAtlasTexture with a given @width and @height. A
+ * #CoglAtlasTexture represents a sub-region within one of Cogl's
+ * shared texture atlases.
+ *
+ * The storage for the texture is not allocated before this function
+ * returns. You can call cogl_texture_allocate() to explicitly
+ * allocate the underlying storage or let Cogl automatically allocate
+ * storage lazily.
+ *
+ * <note>This call can fail if Cogl considers the given
+ * @internal_format incompatible with the format of its internal
+ * atlases.</note>
+ *
+ * <note>The returned #CoglAtlasTexture is a high-level meta-texture
+ * with some limitations. See the documentation for #CoglMetaTexture
+ * for more details.</note>
+ *
+ * Returns: A new #CoglAtlasTexture object with no storage allocated
+ *          yet or %NULL on failure and @error will be updated.
+ * Since: 1.16
+ * Stability: unstable
+ */
+CoglAtlasTexture *
+cogl_atlas_texture_new_with_size (CoglContext *ctx,
+                                  int width,
+                                  int height,
+                                  CoglPixelFormat internal_format,
+                                  CoglError **error);
+
+/**
+ * cogl_atlas_texture_new_from_file:
+ * @ctx: A #CoglContext
+ * @filename: the file to load
+ * @internal_format: The format of the texture
+ *
+ * Creates a #CoglAtlasTexture from an image file. A #CoglAtlasTexture
+ * represents a sub-region within one of Cogl's shared texture
+ * atlases.
+ *
+ * <note>This call can fail if Cogl considers the given
+ * @internal_format incompatible with the format of its internal
+ * atlases.</note>
+ *
+ * <note>The returned #CoglAtlasTexture is a high-level meta-texture
+ * with some limitations. See the documentation for #CoglMetaTexture
+ * for more details.</note>
+ *
+ * Returns: A new #CoglAtlasTexture object or %NULL on failure and
+ *          @error will be updated.
+ * Since: 1.16
+ * Stability: unstable
+ */
+CoglAtlasTexture *
+cogl_atlas_texture_new_from_file (CoglContext *ctx,
+                                  const char *filename,
+                                  CoglPixelFormat internal_format,
+                                  CoglError **error);
+
+/**
+ * cogl_atlas_texture_new_from_data:
+ * @ctx: A #CoglContext
+ * @width: width of texture in pixels
+ * @height: height of texture in pixels
+ * @format: the #CoglPixelFormat the buffer is stored in in RAM
+ * @internal_format: the #CoglPixelFormat to use for the GPU storage of the
+ *    texture. If %COGL_PIXEL_FORMAT_ANY is given then a premultiplied
+ *    format similar to the format of the source data will be used. The
+ *    default blending equations of Cogl expect premultiplied color data;
+ *    the main use of passing a non-premultiplied format here is if you
+ *    have non-premultiplied source data and are going to adjust the blend
+ *    mode (see cogl_material_set_blend()) or use the data for something
+ *    other than straight blending.
+ * @rowstride: the memory offset in bytes between the start of each
+ *    row in @data. A value of 0 will make Cogl automatically
+ *    calculate @rowstride from @width and @format.
+ * @data: pointer to the memory region where the source buffer resides
+ * @error: A #CoglError to catch exceptional errors or %NULL
+ *
+ * Creates a new #CoglAtlasTexture texture based on data residing in
+ * memory. A #CoglAtlasTexture represents a sub-region within one of
+ * Cogl's shared texture atlases.
+ *
+ * <note>This call can fail if Cogl considers the given
+ * @internal_format incompatible with the format of its internal
+ * atlases.</note>
+ *
+ * <note>The returned #CoglAtlasTexture is a high-level
+ * meta-texture with some limitations. See the documentation for
+ * #CoglMetaTexture for more details.</note>
+ *
+ * Returns: A new #CoglAtlasTexture object or %NULL on failure and
+ *          @error will be updated.
+ * Since: 1.16
+ * Stability: unstable
+ */
+CoglAtlasTexture *
+cogl_atlas_texture_new_from_data (CoglContext *ctx,
+                                  int width,
+                                  int height,
+                                  CoglPixelFormat format,
+                                  CoglPixelFormat internal_format,
+                                  int rowstride,
+                                  const uint8_t *data,
+                                  CoglError **error);
+
+/**
+ * cogl_atlas_texture_new_from_bitmap:
+ * @bitmap: A #CoglBitmap
+ * @internal_format: the #CoglPixelFormat to use for the GPU storage of the
+ *    texture. If %COGL_PIXEL_FORMAT_ANY is given then a premultiplied
+ *    format similar to the format of the source data will be used. The
+ *    default blending equations of Cogl expect premultiplied color data;
+ *    the main use of passing a non-premultiplied format here is if you
+ *    have non-premultiplied source data and are going to adjust the blend
+ *    mode (see cogl_material_set_blend()) or use the data for something
+ *    other than straight blending.
+ * @error: A #CoglError to catch exceptional errors or %NULL
+ *
+ * Creates a new #CoglAtlasTexture texture based on data residing in a
+ * @bitmap. A #CoglAtlasTexture represents a sub-region within one of
+ * Cogl's shared texture atlases.
+ *
+ * <note>This call can fail if Cogl considers the given
+ * @internal_format incompatible with the format of its internal
+ * atlases.</note>
+ *
+ * <note>The returned #CoglAtlasTexture is a high-level meta-texture
+ * with some limitations. See the documentation for #CoglMetaTexture
+ * for more details.</note>
+ *
+ * Returns: A new #CoglAtlasTexture object or %NULL on failure and
+ *          @error will be updated.
+ * Since: 1.16
+ * Stability: unstable
+ */
+CoglAtlasTexture *
+cogl_atlas_texture_new_from_bitmap (CoglBitmap *bmp,
+                                    CoglPixelFormat internal_format,
+                                    CoglError **error);
+
+COGL_END_DECLS
+
+#endif /* _COGL_ATLAS_TEXTURE_H_ */
diff --git a/cogl/cogl-auto-texture.c b/cogl/cogl-auto-texture.c
index 166e6a5c..6ee5e5f2 100644
--- a/cogl/cogl-auto-texture.c
+++ b/cogl/cogl-auto-texture.c
@@ -147,16 +147,19 @@ _cogl_texture_new_from_bitmap (CoglBitmap *bitmap,
   CoglTexture *tex;
   CoglError *internal_error = NULL;
 
-  /* First try putting the texture in the atlas */
-  if ((atlas_tex = _cogl_atlas_texture_new_from_bitmap (bitmap,
-                                                        flags,
-                                                        internal_format,
-                                                        can_convert_in_place,
-                                                        &internal_error)))
-    return COGL_TEXTURE (atlas_tex);
-
-  cogl_error_free (internal_error);
-  internal_error = NULL;
+  if (!flags &&
+      !COGL_DEBUG_ENABLED (COGL_DEBUG_DISABLE_ATLAS))
+    {
+      /* First try putting the texture in the atlas */
+      if ((atlas_tex = _cogl_atlas_texture_new_from_bitmap (bitmap,
+                                                            internal_format,
+                                                            can_convert_in_place,
+                                                            &internal_error)))
+        return COGL_TEXTURE (atlas_tex);
+
+      cogl_error_free (internal_error);
+      internal_error = NULL;
+    }
 
   /* If that doesn't work try a fast path 2D texture */
   if ((_cogl_util_is_pot (bitmap->width) &&
diff --git a/cogl/cogl.h b/cogl/cogl.h
index 304beeda..c5ad6619 100644
--- a/cogl/cogl.h
+++ b/cogl/cogl.h
@@ -60,6 +60,7 @@
 #include <cogl/cogl-texture-3d.h>
 #include <cogl/cogl-texture-2d-sliced.h>
 #include <cogl/cogl-sub-texture.h>
+#include <cogl/cogl-atlas-texture.h>
 #include <cogl/cogl-meta-texture.h>
 #include <cogl/cogl-primitive-texture.h>
 #include <cogl/cogl-index-buffer.h>
diff --git a/doc/reference/cogl2/cogl2-sections.txt b/doc/reference/cogl2/cogl2-sections.txt
index 1a6e343b..be00e2d2 100644
--- a/doc/reference/cogl2/cogl2-sections.txt
+++ b/doc/reference/cogl2/cogl2-sections.txt
@@ -407,6 +407,17 @@ cogl_is_sub_texture
 </SECTION>
 
 <SECTION>
+<FILE>cogl-atlas-texture</FILE>
+<TITLE>Atlas Textures</TITLE>
+CoglAtlasTexture
+cogl_atlas_texture_new_with_size
+cogl_atlas_texture_new_from_file
+cogl_atlas_texture_new_from_data
+cogl_atlas_texture_new_from_bitmap
+cogl_is_atlas_texture
+</SECTION>
+
+<SECTION>
 <FILE>cogl-texture-2d-sliced</FILE>
 <TITLE>Sliced Textures</TITLE>
 CoglTexture2DSliced