[Cogl] [PATCH 1/2] Add cogl_framebuffer_read_pixels()

[Neil Roberts]

This adds a public convenience wrapper around
cogl_framebuffer_read_pixels_into_bitmap which allocates a temporary
CoglBitmap to read into the application's own buffer. This can only be
used for the 99% common case where the rowstride is exactly the
bpp*width and the source is the color buffer.
---
 cogl/cogl-framebuffer.c                            |   27 +++++++++++
 cogl/cogl-framebuffer.h                            |   48 ++++++++++++++++++++
 .../cogl-2.0-experimental-sections.txt             |    1 +
 3 files changed, 76 insertions(+), 0 deletions(-)

diff --git a/cogl/cogl-framebuffer.c b/cogl/cogl-framebuffer.c
index ab7f0aa..8cbee1d 100644
--- a/cogl/cogl-framebuffer.c
+++ b/cogl/cogl-framebuffer.c
@@ -2179,6 +2179,33 @@ cogl_framebuffer_read_pixels_into_bitmap (CoglFramebuffer *framebuffer,
   return TRUE;
 }
 
+gboolean
+cogl_framebuffer_read_pixels (CoglFramebuffer *framebuffer,
+                              int x,
+                              int y,
+                              int width,
+                              int height,
+                              CoglPixelFormat format,
+                              guint8 *pixels)
+{
+  int bpp = _cogl_pixel_format_get_bytes_per_pixel (format);
+  CoglBitmap *bitmap;
+  gboolean ret;
+
+  bitmap = cogl_bitmap_new_for_data (framebuffer->context,
+                                     width, height,
+                                     format,
+                                     bpp * width, /* rowstride */
+                                     pixels);
+  ret = cogl_framebuffer_read_pixels_into_bitmap (framebuffer,
+                                                  x, y,
+                                                  COGL_READ_PIXELS_COLOR_BUFFER,
+                                                  bitmap);
+  cogl_object_unref (bitmap);
+
+  return ret;
+}
+
 void
 _cogl_blit_framebuffer (unsigned int src_x,
                         unsigned int src_y,
diff --git a/cogl/cogl-framebuffer.h b/cogl/cogl-framebuffer.h
index b314426..896a3c1 100644
--- a/cogl/cogl-framebuffer.h
+++ b/cogl/cogl-framebuffer.h
@@ -1280,6 +1280,54 @@ cogl_framebuffer_read_pixels_into_bitmap (CoglFramebuffer *framebuffer,
                                           CoglBitmap *bitmap);
 
 /**
+ * cogl_framebuffer_read_pixels:
+ * @framebuffer: A #CoglFramebuffer
+ * @x: The x position to read from
+ * @y: The y position to read from
+ * @width: The width of the region of rectangles to read
+ * @height: The height of the region of rectangles to read
+ * @format: The pixel format to store the data in
+ * @pixels: The address of the buffer to store the data in
+ *
+ * This is a convenience wrapper around
+ * cogl_framebuffer_read_pixels_into_bitmap() which allocates a
+ * temporary #CoglBitmap to read pixel data directly into the given
+ * buffer. The rowstride of the buffer is assumed to be the width of
+ * the region times the bytes per pixel of the format. The source for
+ * the data is always taken from the color buffer. If you want to use
+ * any other rowstride or source, please use the
+ * cogl_framebuffer_read_pixels_into_bitmap() function directly.
+ *
+ * The implementation of the function looks like this:
+ *
+ * |[
+ * bitmap = cogl_bitmap_new_for_data (context,
+ *                                    width, height,
+ *                                    format,
+ *                                    /<!-- -->* rowstride *<!-- -->/
+ *                                    bpp * width,
+ *                                    pixels);
+ * cogl_framebuffer_read_pixels_into_bitmap (framebuffer,
+ *                                           x, y,
+ *                                           COGL_READ_PIXELS_COLOR_BUFFER,
+ *                                           bitmap);
+ * cogl_object_unref (bitmap);
+ * ]|
+ *
+ * Return value: %TRUE if the read succeeded or %FALSE otherwise.
+ * Since: 1.10
+ * Stability: unstable
+ */
+gboolean
+cogl_framebuffer_read_pixels (CoglFramebuffer *framebuffer,
+                              int x,
+                              int y,
+                              int width,
+                              int height,
+                              CoglPixelFormat format,
+                              guint8 *pixels);
+
+/**
  * cogl_get_draw_framebuffer:
  *
  * Gets the current #CoglFramebuffer as set using
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 1907687..ad3e067 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
@@ -396,6 +396,7 @@ cogl_framebuffer_get_context
 cogl_framebuffer_clear
 cogl_framebuffer_clear4f
 cogl_framebuffer_read_pixels_into_bitmap
+cogl_framebuffer_read_pixels
 
 <SUBSECTION>
 cogl_framebuffer_draw_primitive
-- 
1.7.3.16.g9464b