Add cogl_framebuffer_read_pixels()

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.

Reviewed-by: Robert Bragg <robert@linux.intel.com>

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,

cogl/cogl-framebuffer.h

@@ -1279,6 +1279,54 @@ cogl_framebuffer_read_pixels_into_bitmap (CoglFramebuffer *framebuffer,
                                           CoglReadPixelsFlags source,
                                           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:
  *

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