[cogl] Make cogl_texture_draw_and_read_to_bitmap public

[Robert Bragg <rbragg src gnome org>]

commit 6d6a277b8e9a63a8268046e5258877ba94a1da5b
Author: Robert Bragg <robert linux intel com>
Date:   Thu Nov 8 22:38:05 2012 +0000

    Make cogl_texture_draw_and_read_to_bitmap public
    
    This makes the internal api  _cogl_texture_draw_and_read public as
    cogl_texture_draw_and_read_to_bitmap() so that applications can manually
    use this api to handle fallbacks when it's not possible to directly read
    a textures contents.
    
    The intention is to no longer automatically render and read-back
    textures as a fallback on drivers that don't support glGetTexImage2D
    since this fallback depends on the idea of a current framebuffer which
    we'd like to get rid of and there is no feedback that the contents of
    the framebuffer have been destroyed if the fallback is hit.
    
    Reviewed-by: Neil Roberts <neil linux intel com>

 cogl/cogl-framebuffer.h |    7 +++++--
 cogl/cogl-texture.c     |   40 ++++++++++------------------------------
 cogl/cogl-texture.h     |   36 ++++++++++++++++++++++++++++++++++++
 3 files changed, 51 insertions(+), 32 deletions(-)
---
diff --git a/cogl/cogl-framebuffer.h b/cogl/cogl-framebuffer.h
index efcf780..8a0f65b 100644
--- a/cogl/cogl-framebuffer.h
+++ b/cogl/cogl-framebuffer.h
@@ -32,6 +32,11 @@
 #include <windows.h>
 #endif /* COGL_HAS_WIN32_SUPPORT */
 
+/* We forward declare the CoglFramebuffer type here to avoid some circular
+ * dependency issues with the following headers.
+ */
+typedef struct _CoglFramebuffer CoglFramebuffer;
+
 #include <cogl/cogl-path.h>
 #include <cogl/cogl-pipeline.h>
 #include <cogl/cogl-indices.h>
@@ -80,8 +85,6 @@ COGL_BEGIN_DECLS
  * configuration.
  */
 
-typedef struct _CoglFramebuffer CoglFramebuffer;
-
 #define COGL_FRAMEBUFFER(X) ((CoglFramebuffer *)(X))
 
 /**
diff --git a/cogl/cogl-texture.c b/cogl/cogl-texture.c
index fc7f63e..caa8f87 100644
--- a/cogl/cogl-texture.c
+++ b/cogl/cogl-texture.c
@@ -587,20 +587,12 @@ do_texture_draw_and_read (CoglFramebuffer *fb,
   return TRUE;
 }
 
-/* Reads back the contents of a texture by rendering it to the framebuffer
- * and reading back the resulting pixels.
- *
- * NB: Normally this approach isn't normally used since we can just use
- * glGetTexImage, but may be used as a fallback in some circumstances.
- */
-static CoglBool
-_cogl_texture_draw_and_read (CoglTexture *texture,
-                             CoglBitmap *target_bmp,
-                             GLuint target_gl_format,
-                             GLuint target_gl_type,
-                             CoglError **error)
+CoglBool
+cogl_texture_draw_and_read_to_bitmap (CoglTexture *texture,
+                                      CoglFramebuffer *framebuffer,
+                                      CoglBitmap *target_bmp,
+                                      CoglError **error)
 {
-  CoglFramebuffer *framebuffer = cogl_get_draw_framebuffer ();
   CoglContext *ctx = framebuffer->context;
   float save_viewport[4];
   float viewport[4];
@@ -1060,25 +1052,13 @@ cogl_texture_get_data (CoglTexture *texture,
       tg_data.success = FALSE;
     }
 
-  /* XXX: In some cases _cogl_texture_2d_download_from_gl may fail
-   * to read back the texture data; such as for GLES which doesn't
-   * support glGetTexImage, so here we fallback to drawing the
-   * texture and reading the pixels from the framebuffer. */
+  /* XXX: In some cases this api may fail to read back the texture
+   * data; such as for GLES which doesn't support glGetTexImage
+   */
   if (!tg_data.success)
     {
-      if (!_cogl_texture_draw_and_read (texture, target_bmp,
-                                        closest_gl_format,
-                                        closest_gl_type,
-                                        &ignore_error))
-        {
-          /* We have no more fallbacks so we just give up and
-           * hope for the best */
-          g_warning ("Failed to read texture since draw-and-read "
-                     "fallback failed: %s", ignore_error->message);
-          cogl_error_free (ignore_error);
-          cogl_object_unref (target_bmp);
-          return 0;
-        }
+      cogl_object_unref (target_bmp);
+      return 0;
     }
 
   /* Was intermediate used? */
diff --git a/cogl/cogl-texture.h b/cogl/cogl-texture.h
index 27adf93..77a269b 100644
--- a/cogl/cogl-texture.h
+++ b/cogl/cogl-texture.h
@@ -37,6 +37,7 @@ typedef struct _CoglTexture CoglTexture;
 #include <cogl/cogl-defines.h>
 #include <cogl/cogl-pixel-buffer.h>
 #include <cogl/cogl-bitmap.h>
+#include <cogl/cogl-framebuffer.h>
 
 COGL_BEGIN_DECLS
 
@@ -363,6 +364,41 @@ cogl_texture_get_data (CoglTexture *texture,
                        uint8_t *data);
 
 /**
+ * cogl_texture_draw_and_read_to_bitmap:
+ * @texture: The #CoglTexture to read
+ * @framebuffer: The intermediate framebuffer needed to render the
+ *               texture
+ * @target_bmp: The destination bitmap
+ * @error: A #CoglError to catch any exceptional errors
+ *
+ * Only to be used in exceptional circumstances, this api reads back
+ * the contents of a @texture by rendering it to the given
+ * @framebuffer and reading back the resulting pixels to be stored in
+ * @bitmap. If the @texture is larger than the given @framebuffer then
+ * multiple renders will be done to read the texture back in chunks.
+ *
+ * Any viewport, projection or modelview matrix state associated with
+ * @framebuffer will be saved and restored, but other state such as
+ * the color mask state is ignored and may affect the result of
+ * reading back the texture.
+ *
+ * This API should only be used in exceptional circumstances when
+ * alternative apis such as cogl_texture_get_data() have failed. For
+ * example compressed textures can not be read back directly and so
+ * a render is required if you want read back the image data. Ideally
+ * applications should aim to avoid needing to read back textures in
+ * the first place and perhaps only use this api for debugging
+ * purposes.
+ *
+ * Stability: unstable
+ */
+CoglBool
+cogl_texture_draw_and_read_to_bitmap (CoglTexture *texture,
+                                      CoglFramebuffer *framebuffer,
+                                      CoglBitmap *target_bmp,
+                                      CoglError **error);
+
+/**
  * cogl_texture_set_region:
  * @texture a #CoglTexture.
  * @src_x: upper left coordinate to use from source data.