clutter 2.2.4-x64-mingw32

data/vendor/local/include/cogl/cogl/cogl-frame-info.h

@@ -0,0 +1,148 @@
+/*
+ * Cogl
+ *
+ * A Low Level GPU Graphics and Utilities API
+ *
+ * Copyright (C) 2012 Red Hat, Inc.
+ *
+ * Permission is hereby granted, free of charge, to any person
+ * obtaining a copy of this software and associated documentation
+ * files (the "Software"), to deal in the Software without
+ * restriction, including without limitation the rights to use, copy,
+ * modify, merge, publish, distribute, sublicense, and/or sell copies
+ * of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be
+ * included in all copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+ * EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+ * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+ * NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS
+ * BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN
+ * ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
+ * CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ * SOFTWARE.
+ *
+ *
+ *
+ * Authors:
+ *   Owen Taylor <otaylor@redhat.com>
+ */
+#if !defined(__COGL_H_INSIDE__) && !defined(COGL_COMPILATION)
+#error "Only <cogl/cogl.h> can be included directly."
+#endif
+
+#ifndef __COGL_FRAME_INFO_H
+#define __COGL_FRAME_INFO_H
+
+#include <cogl/cogl-types.h>
+#include <cogl/cogl-output.h>
+
+#ifdef COGL_HAS_GTYPE_SUPPORT
+#include <glib-object.h>
+#endif
+#include <glib.h>
+
+G_BEGIN_DECLS
+
+typedef struct _CoglFrameInfo CoglFrameInfo;
+#define COGL_FRAME_INFO(X) ((CoglFrameInfo *)(X))
+
+#ifdef COGL_HAS_GTYPE_SUPPORT
+/**
+ * cogl_frame_info_get_gtype:
+ *
+ * Returns: a #GType that can be used with the GLib type system.
+ */
+GType cogl_frame_info_get_gtype (void);
+#endif
+
+/**
+ * cogl_is_frame_info:
+ * @object: A #CoglObject pointer
+ *
+ * Gets whether the given object references a #CoglFrameInfo.
+ *
+ * Return value: %TRUE if the object references a #CoglFrameInfo
+ *   and %FALSE otherwise.
+ * Since: 2.0
+ * Stability: unstable
+ */
+CoglBool
+cogl_is_frame_info (void *object);
+
+/**
+ * cogl_frame_info_get_frame_counter:
+ * @info: a #CoglFrameInfo object
+ *
+ * Gets the frame counter for the #CoglOnscreen that corresponds
+ * to this frame.
+ *
+ * Return value: The frame counter value
+ * Since: 1.14
+ * Stability: unstable
+ */
+int64_t cogl_frame_info_get_frame_counter (CoglFrameInfo *info);
+
+/**
+ * cogl_frame_info_get_presentation_time:
+ * @info: a #CoglFrameInfo object
+ *
+ * Gets the presentation time for the frame. This is the time at which
+ * the frame became visible to the user.
+ *
+ * The presentation time measured in nanoseconds is based on a
+ * monotonic time source. The time source is not necessarily
+ * correlated with system/wall clock time and may represent the time
+ * elapsed since some undefined system event such as when the system
+ * last booted.
+ *
+ * <note>Linux kernel version less that 3.8 can result in
+ * non-monotonic timestamps being reported when using a drm based
+ * OpenGL driver. Also some buggy Mesa drivers up to 9.0.1 may also
+ * incorrectly report non-monotonic timestamps.</note>
+ *
+ * Return value: the presentation time for the frame
+ * Since: 1.14
+ * Stability: unstable
+ */
+int64_t cogl_frame_info_get_presentation_time (CoglFrameInfo *info);
+
+/**
+ * cogl_frame_info_get_refresh_rate:
+ * @info: a #CoglFrameInfo object
+ *
+ * Gets the refresh rate in Hertz for the output that the frame was on
+ * at the time the frame was presented.
+ *
+ * <note>Some platforms can't associate a #CoglOutput with a
+ * #CoglFrameInfo object but are able to report a refresh rate via
+ * this api. Therefore if you need this information then this api is
+ * more reliable than using cogl_frame_info_get_output() followed by
+ * cogl_output_get_refresh_rate().</note>
+ *
+ * Return value: the refresh rate in Hertz
+ * Since: 1.14
+ * Stability: unstable
+ */
+float cogl_frame_info_get_refresh_rate (CoglFrameInfo *info);
+
+/**
+ * cogl_frame_info_get_output:
+ * @info: a #CoglFrameInfo object
+ *
+ * Gets the #CoglOutput that the swapped frame was presented to.
+ *
+ * Return value: (transfer none): The #CoglOutput that the frame was
+ *        presented to, or %NULL if this could not be determined.
+ * Since: 1.14
+ * Stability: unstable
+ */
+CoglOutput *
+cogl_frame_info_get_output (CoglFrameInfo *info);
+
+G_END_DECLS
+
+#endif /* __COGL_FRAME_INFO_H */

data/vendor/local/include/cogl/cogl/cogl-framebuffer-deprecated.h

@@ -0,0 +1,264 @@
+/*
+ * Cogl
+ *
+ * A Low Level GPU Graphics and Utilities API
+ *
+ * Copyright (C) 2014 Intel Corporation.
+ *
+ * Permission is hereby granted, free of charge, to any person
+ * obtaining a copy of this software and associated documentation
+ * files (the "Software"), to deal in the Software without
+ * restriction, including without limitation the rights to use, copy,
+ * modify, merge, publish, distribute, sublicense, and/or sell copies
+ * of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be
+ * included in all copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+ * EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+ * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+ * NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS
+ * BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN
+ * ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
+ * CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ * SOFTWARE.
+ *
+ *
+ */
+
+#ifndef __COGL_FRAMEBUFFER_DEPRECATED_H__
+#define __COGL_FRAMEBUFFER_DEPRECATED_H__
+
+#include <cogl/cogl-macros.h>
+
+COGL_BEGIN_DECLS
+
+/**
+ * cogl_set_framebuffer:
+ * @buffer: A #CoglFramebuffer object, either onscreen or offscreen.
+ *
+ * This redirects all subsequent drawing to the specified framebuffer. This can
+ * either be an offscreen buffer created with cogl_offscreen_new_to_texture ()
+ * or in the future it may be an onscreen framebuffers too.
+ *
+ * Since: 1.2
+ * Deprecated: 1.16: The latest drawing apis take explicit
+ *                   #CoglFramebuffer arguments so this stack of
+ *                   framebuffers shouldn't be used anymore.
+ */
+COGL_DEPRECATED_IN_1_16
+void
+cogl_set_framebuffer (CoglFramebuffer *buffer);
+
+/**
+ * cogl_push_framebuffer:
+ * @buffer: A #CoglFramebuffer object, either onscreen or offscreen.
+ *
+ * Redirects all subsequent drawing to the specified framebuffer. This can
+ * either be an offscreen buffer created with cogl_offscreen_new_to_texture ()
+ * or in the future it may be an onscreen framebuffer too.
+ *
+ * You should understand that a framebuffer owns the following state:
+ * <itemizedlist>
+ *  <listitem><simpara>The projection matrix</simpara></listitem>
+ *  <listitem><simpara>The modelview matrix stack</simpara></listitem>
+ *  <listitem><simpara>The viewport</simpara></listitem>
+ *  <listitem><simpara>The clip stack</simpara></listitem>
+ * </itemizedlist>
+ * So these items will automatically be saved and restored when you
+ * push and pop between different framebuffers.
+ *
+ * Also remember a newly allocated framebuffer will have an identity matrix for
+ * the projection and modelview matrices which gives you a coordinate space
+ * like OpenGL with (-1, -1) corresponding to the top left of the viewport,
+ * (1, 1) corresponding to the bottom right and +z coming out towards the
+ * viewer.
+ *
+ * If you want to set up a coordinate space like Clutter does with (0, 0)
+ * corresponding to the top left and (framebuffer_width, framebuffer_height)
+ * corresponding to the bottom right you can do so like this:
+ *
+ * |[
+ * static void
+ * setup_viewport (unsigned int width,
+ *                 unsigned int height,
+ *                 float fovy,
+ *                 float aspect,
+ *                 float z_near,
+ *                 float z_far)
+ * {
+ *   float z_camera;
+ *   CoglMatrix projection_matrix;
+ *   CoglMatrix mv_matrix;
+ *
+ *   cogl_set_viewport (0, 0, width, height);
+ *   cogl_perspective (fovy, aspect, z_near, z_far);
+ *
+ *   cogl_get_projection_matrix (&amp;projection_matrix);
+ *   z_camera = 0.5 * projection_matrix.xx;
+ *
+ *   cogl_matrix_init_identity (&amp;mv_matrix);
+ *   cogl_matrix_translate (&amp;mv_matrix, -0.5f, -0.5f, -z_camera);
+ *   cogl_matrix_scale (&amp;mv_matrix, 1.0f / width, -1.0f / height, 1.0f / width);
+ *   cogl_matrix_translate (&amp;mv_matrix, 0.0f, -1.0 * height, 0.0f);
+ *   cogl_set_modelview_matrix (&amp;mv_matrix);
+ * }
+ *
+ * static void
+ * my_init_framebuffer (ClutterStage *stage,
+ *                      CoglFramebuffer *framebuffer,
+ *                      unsigned int framebuffer_width,
+ *                      unsigned int framebuffer_height)
+ * {
+ *   ClutterPerspective perspective;
+ *
+ *   clutter_stage_get_perspective (stage, &perspective);
+ *
+ *   cogl_push_framebuffer (framebuffer);
+ *   setup_viewport (framebuffer_width,
+ *                   framebuffer_height,
+ *                   perspective.fovy,
+ *                   perspective.aspect,
+ *                   perspective.z_near,
+ *                   perspective.z_far);
+ * }
+ * ]|
+ *
+ * The previous framebuffer can be restored by calling cogl_pop_framebuffer()
+ *
+ * Since: 1.2
+ * Deprecated: 1.16: The latest drawing apis take explicit
+ *                   #CoglFramebuffer arguments so this stack of
+ *                   framebuffers shouldn't be used anymore.
+ */
+COGL_DEPRECATED_IN_1_16
+void
+cogl_push_framebuffer (CoglFramebuffer *buffer);
+
+/**
+ * cogl_pop_framebuffer:
+ *
+ * Restores the framebuffer that was previously at the top of the stack.
+ * All subsequent drawing will be redirected to this framebuffer.
+ *
+ * Since: 1.2
+ * Deprecated: 1.16: The latest drawing apis take explicit
+ *                   #CoglFramebuffer arguments so this stack of
+ *                   framebuffers shouldn't be used anymore.
+ */
+COGL_DEPRECATED_IN_1_16
+void
+cogl_pop_framebuffer (void);
+
+/**
+ * cogl_set_draw_buffer:
+ * @target: A #CoglBufferTarget that specifies what kind of framebuffer you
+ *          are setting as the render target.
+ * @offscreen: If you are setting a framebuffer of type COGL_OFFSCREEN_BUFFER
+ *             then this is a CoglHandle for the offscreen buffer.
+ *
+ * Redirects all subsequent drawing to the specified framebuffer. This
+ * can either be an offscreen buffer created with
+ * cogl_offscreen_new_to_texture () or you can revert to your original
+ * on screen window buffer.
+ *
+ * Deprecated: 1.16: The latest drawing apis take explicit
+ *                   #CoglFramebuffer arguments so this stack of
+ *                   framebuffers shouldn't be used anymore.
+ */
+COGL_DEPRECATED_IN_1_16
+void
+cogl_set_draw_buffer (CoglBufferTarget target,
+                      CoglHandle offscreen);
+
+/**
+ * cogl_push_draw_buffer:
+ *
+ * Save cogl_set_draw_buffer() state.
+ *
+ * Deprecated: 1.16: The latest drawing apis take explicit
+ *                   #CoglFramebuffer arguments so this stack of
+ *                   framebuffers shouldn't be used anymore.
+ */
+COGL_DEPRECATED_IN_1_16
+void
+cogl_push_draw_buffer (void);
+
+/**
+ * cogl_pop_draw_buffer:
+ *
+ * Restore cogl_set_draw_buffer() state.
+ *
+ * Deprecated: 1.16: The latest drawing apis take explicit
+ *                   #CoglFramebuffer arguments so this stack of
+ *                   framebuffers shouldn't be used anymore.
+ */
+COGL_DEPRECATED_IN_1_16
+void
+cogl_pop_draw_buffer (void);
+
+/**
+ * cogl_read_pixels:
+ * @x: The window x position to start reading from
+ * @y: The window y position to start reading from
+ * @width: The width of the rectangle you want to read
+ * @height: The height of the rectangle you want to read
+ * @source: Identifies which auxillary buffer you want to read
+ *          (only COGL_READ_PIXELS_COLOR_BUFFER supported currently)
+ * @format: The pixel format you want the result in
+ *          (only COGL_PIXEL_FORMAT_RGBA_8888 supported currently)
+ * @pixels: The location to write the pixel data.
+ *
+ * This reads a rectangle of pixels from the current framebuffer where
+ * position (0, 0) is the top left. The pixel at (x, y) is the first
+ * read, and the data is returned with a rowstride of (width * 4).
+ *
+ * Currently Cogl assumes that the framebuffer is in a premultiplied
+ * format so if @format is non-premultiplied it will convert it. To
+ * read the pixel values without any conversion you should either
+ * specify a format that doesn't use an alpha channel or use one of
+ * the formats ending in PRE.
+ *
+ * Deprecated: 1.16: Use cogl_framebuffer_read_pixels() instead
+ */
+COGL_DEPRECATED_IN_1_16_FOR (cogl_framebuffer_read_pixels)
+void
+cogl_read_pixels (int x,
+                  int y,
+                  int width,
+                  int height,
+                  CoglReadPixelsFlags source,
+                  CoglPixelFormat format,
+                  uint8_t *pixels);
+
+
+/* XXX: Since this api was marked unstable, maybe we can just
+ * remove this api if we can't find anyone is using it. */
+/**
+ * cogl_framebuffer_get_color_format:
+ * @framebuffer: A #CoglFramebuffer framebuffer
+ *
+ * Queries the common #CoglPixelFormat of all color buffers attached
+ * to this framebuffer. For an offscreen framebuffer created with
+ * cogl_offscreen_new_with_texture() this will correspond to the format
+ * of the texture.
+ *
+ * This API is deprecated because it is missleading to report a
+ * #CoglPixelFormat for the internal format of the @framebuffer since
+ * #CoglPixelFormat is such a precise format description and it's
+ * only the set of components and the premultiplied alpha status
+ * that is really known.
+ *
+ * Since: 1.8
+ * Stability: unstable
+ * Deprecated 1.18: Removed since it is misleading
+ */
+COGL_DEPRECATED_IN_1_18
+CoglPixelFormat
+cogl_framebuffer_get_color_format (CoglFramebuffer *framebuffer);
+
+COGL_END_DECLS
+
+#endif /* __COGL_FRAMEBUFFER_DEPRECATED_H__ */

data/vendor/local/include/cogl/cogl/cogl-framebuffer.h

@@ -0,0 +1,1818 @@
+/*
+ * Cogl
+ *
+ * A Low Level GPU Graphics and Utilities API
+ *
+ * Copyright (C) 2011 Intel Corporation.
+ *
+ * Permission is hereby granted, free of charge, to any person
+ * obtaining a copy of this software and associated documentation
+ * files (the "Software"), to deal in the Software without
+ * restriction, including without limitation the rights to use, copy,
+ * modify, merge, publish, distribute, sublicense, and/or sell copies
+ * of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be
+ * included in all copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+ * EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+ * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+ * NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS
+ * BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN
+ * ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
+ * CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ * SOFTWARE.
+ *
+ *
+ *
+ * Authors:
+ *   Robert Bragg <robert@linux.intel.com>
+ */
+
+#ifndef __COGL_FRAMEBUFFER_H
+#define __COGL_FRAMEBUFFER_H
+
+#ifdef COGL_HAS_WIN32_SUPPORT
+#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.
+ */
+#ifdef __COGL_H_INSIDE__
+/* For the public C api we typedef interface types as void to avoid needing
+ * lots of casting in code and instead we will rely on runtime type checking
+ * for these objects. */
+typedef void CoglFramebuffer;
+#else
+typedef struct _CoglFramebuffer CoglFramebuffer;
+#define COGL_FRAMEBUFFER(X) ((CoglFramebuffer *)(X))
+#endif
+
+#include <cogl/cogl-pipeline.h>
+#include <cogl/cogl-indices.h>
+#include <cogl/cogl-bitmap.h>
+#ifdef COGL_ENABLE_EXPERIMENTAL_API
+#include <cogl/cogl-quaternion.h>
+#include <cogl/cogl-euler.h>
+#include <cogl/cogl-texture.h>
+#endif
+#ifdef COGL_HAS_GTYPE_SUPPORT
+#include <glib-object.h>
+#endif
+
+COGL_BEGIN_DECLS
+
+/**
+ * SECTION:cogl-framebuffer
+ * @short_description: A common interface for manipulating framebuffers
+ *
+ * Framebuffers are a collection of buffers that can be rendered too.
+ * A framebuffer may be comprised of one or more color buffers, an
+ * optional depth buffer and an optional stencil buffer. Other
+ * configuration parameters are associated with framebuffers too such
+ * as whether the framebuffer supports multi-sampling (an anti-aliasing
+ * technique) or dithering.
+ *
+ * There are two kinds of framebuffer in Cogl, #CoglOnscreen
+ * framebuffers and #CoglOffscreen framebuffers. As the names imply
+ * offscreen framebuffers are for rendering something offscreen
+ * (perhaps to a texture which is bound as one of the color buffers).
+ * The exact semantics of onscreen framebuffers depends on the window
+ * system backend that you are using, but typically you can expect
+ * rendering to a #CoglOnscreen framebuffer will be immediately
+ * visible to the user.
+ *
+ * If you want to create a new framebuffer then you should start by
+ * looking at the #CoglOnscreen and #CoglOffscreen constructor
+ * functions, such as cogl_offscreen_new_with_texture() or
+ * cogl_onscreen_new(). The #CoglFramebuffer interface deals with
+ * all aspects that are common between those two types of framebuffer.
+ *
+ * Setup of a new CoglFramebuffer happens in two stages. There is a
+ * configuration stage where you specify all the options and ancillary
+ * buffers you want associated with your framebuffer and then when you
+ * are happy with the configuration you can "allocate" the framebuffer
+ * using cogl_framebuffer_allocate(). Technically explicitly calling
+ * cogl_framebuffer_allocate() is optional for convenience and the
+ * framebuffer will automatically be allocated when you first try to
+ * draw to it, but if you do the allocation manually then you can
+ * also catch any possible errors that may arise from your
+ * configuration.
+ */
+
+#ifdef COGL_ENABLE_EXPERIMENTAL_API
+
+#ifdef COGL_HAS_GTYPE_SUPPORT
+/**
+ * cogl_framebuffer_get_gtype:
+ *
+ * Returns: a #GType that can be used with the GLib type system.
+ */
+GType cogl_framebuffer_get_gtype (void);
+#endif
+
+/**
+ * cogl_framebuffer_allocate:
+ * @framebuffer: A #CoglFramebuffer
+ * @error: A pointer to a #CoglError for returning exceptions.
+ *
+ * Explicitly allocates a configured #CoglFramebuffer allowing developers to
+ * check and handle any errors that might arise from an unsupported
+ * configuration so that fallback configurations may be tried.
+ *
+ * <note>Many applications don't support any fallback options at least when
+ * they are initially developed and in that case the don't need to use this API
+ * since Cogl will automatically allocate a framebuffer when it first gets
+ * used.  The disadvantage of relying on automatic allocation is that the
+ * program will abort with an error message if there is an error during
+ * automatic allocation.</note>
+ *
+ * Return value: %TRUE if there were no error allocating the framebuffer, else %FALSE.
+ * Since: 1.8
+ * Stability: unstable
+ */
+CoglBool
+cogl_framebuffer_allocate (CoglFramebuffer *framebuffer,
+                           CoglError **error);
+
+/**
+ * cogl_framebuffer_get_width:
+ * @framebuffer: A #CoglFramebuffer
+ *
+ * Queries the current width of the given @framebuffer.
+ *
+ * Return value: The width of @framebuffer.
+ * Since: 1.8
+ * Stability: unstable
+ */
+int
+cogl_framebuffer_get_width (CoglFramebuffer *framebuffer);
+
+/**
+ * cogl_framebuffer_get_height:
+ * @framebuffer: A #CoglFramebuffer
+ *
+ * Queries the current height of the given @framebuffer.
+ *
+ * Return value: The height of @framebuffer.
+ * Since: 1.8
+ * Stability: unstable
+ */
+int
+cogl_framebuffer_get_height (CoglFramebuffer *framebuffer);
+
+/**
+ * cogl_framebuffer_set_viewport:
+ * @framebuffer: A #CoglFramebuffer
+ * @x: The top-left x coordinate of the viewport origin (only integers
+ *     supported currently)
+ * @y: The top-left y coordinate of the viewport origin (only integers
+ *     supported currently)
+ * @width: The width of the viewport (only integers supported currently)
+ * @height: The height of the viewport (only integers supported currently)
+ *
+ * Defines a scale and offset for everything rendered relative to the
+ * top-left of the destination framebuffer.
+ *
+ * By default the viewport has an origin of (0,0) and width and height
+ * that match the framebuffer's size. Assuming a default projection and
+ * modelview matrix then you could translate the contents of a window
+ * down and right by leaving the viewport size unchanged by moving the
+ * offset to (10,10). The viewport coordinates are measured in pixels.
+ * If you left the x and y origin as (0,0) you could scale the windows
+ * contents down by specify and width and height that's half the real
+ * size of the framebuffer.
+ *
+ * <note>Although the function takes floating point arguments, existing
+ * drivers only allow the use of integer values. In the future floating
+ * point values will be exposed via a checkable feature.</note>
+ *
+ * Since: 1.8
+ * Stability: unstable
+ */
+void
+cogl_framebuffer_set_viewport (CoglFramebuffer *framebuffer,
+                               float x,
+                               float y,
+                               float width,
+                               float height);
+
+/**
+ * cogl_framebuffer_get_viewport_x:
+ * @framebuffer: A #CoglFramebuffer
+ *
+ * Queries the x coordinate of the viewport origin as set using cogl_framebuffer_set_viewport()
+ * or the default value which is 0.
+ *
+ * Return value: The x coordinate of the viewport origin.
+ * Since: 1.8
+ * Stability: unstable
+ */
+float
+cogl_framebuffer_get_viewport_x (CoglFramebuffer *framebuffer);
+
+/**
+ * cogl_framebuffer_get_viewport_y:
+ * @framebuffer: A #CoglFramebuffer
+ *
+ * Queries the y coordinate of the viewport origin as set using cogl_framebuffer_set_viewport()
+ * or the default value which is 0.
+ *
+ * Return value: The y coordinate of the viewport origin.
+ * Since: 1.8
+ * Stability: unstable
+ */
+float
+cogl_framebuffer_get_viewport_y (CoglFramebuffer *framebuffer);
+
+/**
+ * cogl_framebuffer_get_viewport_width:
+ * @framebuffer: A #CoglFramebuffer
+ *
+ * Queries the width of the viewport as set using cogl_framebuffer_set_viewport()
+ * or the default value which is the width of the framebuffer.
+ *
+ * Return value: The width of the viewport.
+ * Since: 1.8
+ * Stability: unstable
+ */
+float
+cogl_framebuffer_get_viewport_width (CoglFramebuffer *framebuffer);
+
+/**
+ * cogl_framebuffer_get_viewport_height:
+ * @framebuffer: A #CoglFramebuffer
+ *
+ * Queries the height of the viewport as set using cogl_framebuffer_set_viewport()
+ * or the default value which is the height of the framebuffer.
+ *
+ * Return value: The height of the viewport.
+ * Since: 1.8
+ * Stability: unstable
+ */
+float
+cogl_framebuffer_get_viewport_height (CoglFramebuffer *framebuffer);
+
+/**
+ * cogl_framebuffer_get_viewport4fv:
+ * @framebuffer: A #CoglFramebuffer
+ * @viewport: (out caller-allocates) (array fixed-size=4): A pointer to an
+ *            array of 4 floats to receive the (x, y, width, height)
+ *            components of the current viewport.
+ *
+ * Queries the x, y, width and height components of the current viewport as set
+ * using cogl_framebuffer_set_viewport() or the default values which are 0, 0,
+ * framebuffer_width and framebuffer_height.  The values are written into the
+ * given @viewport array.
+ *
+ * Since: 1.8
+ * Stability: unstable
+ */
+void
+cogl_framebuffer_get_viewport4fv (CoglFramebuffer *framebuffer,
+                                  float *viewport);
+
+/**
+ * cogl_framebuffer_push_matrix:
+ * @framebuffer: A #CoglFramebuffer pointer
+ *
+ * Copies the current model-view matrix onto the matrix stack. The matrix
+ * can later be restored with cogl_framebuffer_pop_matrix().
+ *
+ * Since: 1.10
+ */
+void
+cogl_framebuffer_push_matrix (CoglFramebuffer *framebuffer);
+
+/**
+ * cogl_framebuffer_pop_matrix:
+ * @framebuffer: A #CoglFramebuffer pointer
+ *
+ * Restores the model-view matrix on the top of the matrix stack.
+ *
+ * Since: 1.10
+ */
+void
+cogl_framebuffer_pop_matrix (CoglFramebuffer *framebuffer);
+
+/**
+ * cogl_framebuffer_identity_matrix:
+ * @framebuffer: A #CoglFramebuffer pointer
+ *
+ * Resets the current model-view matrix to the identity matrix.
+ *
+ * Since: 1.10
+ * Stability: unstable
+ */
+void
+cogl_framebuffer_identity_matrix (CoglFramebuffer *framebuffer);
+
+/**
+ * cogl_framebuffer_scale:
+ * @framebuffer: A #CoglFramebuffer pointer
+ * @x: Amount to scale along the x-axis
+ * @y: Amount to scale along the y-axis
+ * @z: Amount to scale along the z-axis
+ *
+ * Multiplies the current model-view matrix by one that scales the x,
+ * y and z axes by the given values.
+ *
+ * Since: 1.10
+ * Stability: unstable
+ */
+void
+cogl_framebuffer_scale (CoglFramebuffer *framebuffer,
+                        float x,
+                        float y,
+                        float z);
+
+/**
+ * cogl_framebuffer_translate:
+ * @framebuffer: A #CoglFramebuffer pointer
+ * @x: Distance to translate along the x-axis
+ * @y: Distance to translate along the y-axis
+ * @z: Distance to translate along the z-axis
+ *
+ * Multiplies the current model-view matrix by one that translates the
+ * model along all three axes according to the given values.
+ *
+ * Since: 1.10
+ * Stability: unstable
+ */
+void
+cogl_framebuffer_translate (CoglFramebuffer *framebuffer,
+                            float x,
+                            float y,
+                            float z);
+
+/**
+ * cogl_framebuffer_rotate:
+ * @framebuffer: A #CoglFramebuffer pointer
+ * @angle: Angle in degrees to rotate.
+ * @x: X-component of vertex to rotate around.
+ * @y: Y-component of vertex to rotate around.
+ * @z: Z-component of vertex to rotate around.
+ *
+ * Multiplies the current model-view matrix by one that rotates the
+ * model around the axis-vector specified by @x, @y and @z. The
+ * rotation follows the right-hand thumb rule so for example rotating
+ * by 10 degrees about the axis-vector (0, 0, 1) causes a small
+ * counter-clockwise rotation.
+ *
+ * Since: 1.10
+ * Stability: unstable
+ */
+void
+cogl_framebuffer_rotate (CoglFramebuffer *framebuffer,
+                         float angle,
+                         float x,
+                         float y,
+                         float z);
+
+#ifdef COGL_ENABLE_EXPERIMENTAL_API
+
+/**
+ * cogl_framebuffer_rotate_quaternion:
+ * @framebuffer: A #CoglFramebuffer pointer
+ * @quaternion: A #CoglQuaternion
+ *
+ * Multiplies the current model-view matrix by one that rotates
+ * according to the rotation described by @quaternion.
+ *
+ * Since: 2.0
+ * Stability: unstable
+ */
+void
+cogl_framebuffer_rotate_quaternion (CoglFramebuffer *framebuffer,
+                                    const CoglQuaternion *quaternion);
+
+/**
+ * cogl_framebuffer_rotate_euler:
+ * @framebuffer: A #CoglFramebuffer pointer
+ * @euler: A #CoglEuler
+ *
+ * Multiplies the current model-view matrix by one that rotates
+ * according to the rotation described by @euler.
+ *
+ * Since: 2.0
+ * Stability: unstable
+ */
+void
+cogl_framebuffer_rotate_euler (CoglFramebuffer *framebuffer,
+                               const CoglEuler *euler);
+
+#endif /* COGL_ENABLE_EXPERIMENTAL_API */
+
+/**
+ * cogl_framebuffer_transform:
+ * @framebuffer: A #CoglFramebuffer pointer
+ * @matrix: the matrix to multiply with the current model-view
+ *
+ * Multiplies the current model-view matrix by the given matrix.
+ *
+ * Since: 1.10
+ * Stability: unstable
+ */
+void
+cogl_framebuffer_transform (CoglFramebuffer *framebuffer,
+                            const CoglMatrix *matrix);
+
+/**
+ * cogl_framebuffer_get_modelview_matrix:
+ * @framebuffer: A #CoglFramebuffer pointer
+ * @matrix: (out): return location for the model-view matrix
+ *
+ * Stores the current model-view matrix in @matrix.
+ *
+ * Since: 1.10
+ * Stability: unstable
+ */
+void
+cogl_framebuffer_get_modelview_matrix (CoglFramebuffer *framebuffer,
+                                       CoglMatrix *matrix);
+
+/**
+ * cogl_framebuffer_set_modelview_matrix:
+ * @framebuffer: A #CoglFramebuffer pointer
+ * @matrix: the new model-view matrix
+ *
+ * Sets @matrix as the new model-view matrix.
+ *
+ * Since: 1.10
+ * Stability: unstable
+ */
+void
+cogl_framebuffer_set_modelview_matrix (CoglFramebuffer *framebuffer,
+                                       const CoglMatrix *matrix);
+
+/**
+ * cogl_framebuffer_perspective:
+ * @framebuffer: A #CoglFramebuffer pointer
+ * @fov_y: Vertical field of view angle in degrees.
+ * @aspect: The (width over height) aspect ratio for display
+ * @z_near: The distance to the near clipping plane (Must be positive,
+ *   and must not be 0)
+ * @z_far: The distance to the far clipping plane (Must be positive)
+ *
+ * Replaces the current projection matrix with a perspective matrix
+ * based on the provided values.
+ *
+ * <note>You should be careful not to have to great a @z_far / @z_near
+ * ratio since that will reduce the effectiveness of depth testing
+ * since there wont be enough precision to identify the depth of
+ * objects near to each other.</note>
+ *
+ * Since: 1.10
+ * Stability: unstable
+ */
+void
+cogl_framebuffer_perspective (CoglFramebuffer *framebuffer,
+                              float fov_y,
+                              float aspect,
+                              float z_near,
+                              float z_far);
+
+/**
+ * cogl_framebuffer_frustum:
+ * @framebuffer: A #CoglFramebuffer pointer
+ * @left: X position of the left clipping plane where it
+ *   intersects the near clipping plane
+ * @right: X position of the right clipping plane where it
+ *   intersects the near clipping plane
+ * @bottom: Y position of the bottom clipping plane where it
+ *   intersects the near clipping plane
+ * @top: Y position of the top clipping plane where it intersects
+ *   the near clipping plane
+ * @z_near: The distance to the near clipping plane (Must be positive)
+ * @z_far: The distance to the far clipping plane (Must be positive)
+ *
+ * Replaces the current projection matrix with a perspective matrix
+ * for a given viewing frustum defined by 4 side clip planes that
+ * all cross through the origin and 2 near and far clip planes.
+ *
+ * Since: 1.10
+ * Stability: unstable
+ */
+void
+cogl_framebuffer_frustum (CoglFramebuffer *framebuffer,
+                          float left,
+                          float right,
+                          float bottom,
+                          float top,
+                          float z_near,
+                          float z_far);
+
+/**
+ * cogl_framebuffer_orthographic:
+ * @framebuffer: A #CoglFramebuffer pointer
+ * @x_1: The x coordinate for the first vertical clipping plane
+ * @y_1: The y coordinate for the first horizontal clipping plane
+ * @x_2: The x coordinate for the second vertical clipping plane
+ * @y_2: The y coordinate for the second horizontal clipping plane
+ * @near: The <emphasis>distance</emphasis> to the near clipping
+ *   plane (will be <emphasis>negative</emphasis> if the plane is
+ *   behind the viewer)
+ * @far: The <emphasis>distance</emphasis> to the far clipping
+ *   plane (will be <emphasis>negative</emphasis> if the plane is
+ *   behind the viewer)
+ *
+ * Replaces the current projection matrix with an orthographic projection
+ * matrix.
+ *
+ * Since: 1.10
+ * Stability: unstable
+ */
+void
+cogl_framebuffer_orthographic (CoglFramebuffer *framebuffer,
+                               float x_1,
+                               float y_1,
+                               float x_2,
+                               float y_2,
+                               float near,
+                               float far);
+
+/**
+ * cogl_framebuffer_get_projection_matrix:
+ * @framebuffer: A #CoglFramebuffer pointer
+ * @matrix: (out): return location for the projection matrix
+ *
+ * Stores the current projection matrix in @matrix.
+ *
+ * Since: 1.10
+ * Stability: unstable
+ */
+void
+cogl_framebuffer_get_projection_matrix (CoglFramebuffer *framebuffer,
+                                        CoglMatrix *matrix);
+
+/**
+ * cogl_framebuffer_set_projection_matrix:
+ * @framebuffer: A #CoglFramebuffer pointer
+ * @matrix: the new projection matrix
+ *
+ * Sets @matrix as the new projection matrix.
+ *
+ * Since: 1.10
+ * Stability: unstable
+ */
+void
+cogl_framebuffer_set_projection_matrix (CoglFramebuffer *framebuffer,
+                                        const CoglMatrix *matrix);
+
+/**
+ * cogl_framebuffer_push_scissor_clip:
+ * @framebuffer: A #CoglFramebuffer pointer
+ * @x: left edge of the clip rectangle in window coordinates
+ * @y: top edge of the clip rectangle in window coordinates
+ * @width: width of the clip rectangle
+ * @height: height of the clip rectangle
+ *
+ * Specifies a rectangular clipping area for all subsequent drawing
+ * operations. Any drawing commands that extend outside the rectangle
+ * will be clipped so that only the portion inside the rectangle will
+ * be displayed. The rectangle dimensions are not transformed by the
+ * current model-view matrix.
+ *
+ * The rectangle is intersected with the current clip region. To undo
+ * the effect of this function, call cogl_framebuffer_pop_clip().
+ *
+ * Since: 1.10
+ * Stability: unstable
+ */
+void
+cogl_framebuffer_push_scissor_clip (CoglFramebuffer *framebuffer,
+                                    int x,
+                                    int y,
+                                    int width,
+                                    int height);
+
+/**
+ * cogl_framebuffer_push_rectangle_clip:
+ * @framebuffer: A #CoglFramebuffer pointer
+ * @x_1: x coordinate for top left corner of the clip rectangle
+ * @y_1: y coordinate for top left corner of the clip rectangle
+ * @x_2: x coordinate for bottom right corner of the clip rectangle
+ * @y_2: y coordinate for bottom right corner of the clip rectangle
+ *
+ * Specifies a modelview transformed rectangular clipping area for all
+ * subsequent drawing operations. Any drawing commands that extend
+ * outside the rectangle will be clipped so that only the portion
+ * inside the rectangle will be displayed. The rectangle dimensions
+ * are transformed by the current model-view matrix.
+ *
+ * The rectangle is intersected with the current clip region. To undo
+ * the effect of this function, call cogl_framebuffer_pop_clip().
+ *
+ * Since: 1.10
+ * Stability: unstable
+ */
+void
+cogl_framebuffer_push_rectangle_clip (CoglFramebuffer *framebuffer,
+                                      float x_1,
+                                      float y_1,
+                                      float x_2,
+                                      float y_2);
+
+/**
+ * cogl_framebuffer_push_primitive_clip:
+ * @framebuffer: A #CoglFramebuffer pointer
+ * @primitive: A #CoglPrimitive describing a flat 2D shape
+ * @bounds_x1: x coordinate for the top-left corner of the primitives
+ *             bounds
+ * @bounds_y1: y coordinate for the top-left corner of the primitives
+ *             bounds
+ * @bounds_x2: x coordinate for the bottom-right corner of the
+ *             primitives bounds.
+ * @bounds_y2: y coordinate for the bottom-right corner of the
+ *             primitives bounds.
+ *
+ * Sets a new clipping area using a 2D shaped described with a
+ * #CoglPrimitive. The shape must not contain self overlapping
+ * geometry and must lie on a single 2D plane. A bounding box of the
+ * 2D shape in local coordinates (the same coordinates used to
+ * describe the shape) must be given. It is acceptable for the bounds
+ * to be larger than the true bounds but behaviour is undefined if the
+ * bounds are smaller than the true bounds.
+ *
+ * The primitive is transformed by the current model-view matrix and
+ * the silhouette is intersected with the previous clipping area.  To
+ * restore the previous clipping area, call
+ * cogl_framebuffer_pop_clip().
+ *
+ * Since: 1.10
+ * Stability: unstable
+ */
+void
+cogl_framebuffer_push_primitive_clip (CoglFramebuffer *framebuffer,
+                                      CoglPrimitive *primitive,
+                                      float bounds_x1,
+                                      float bounds_y1,
+                                      float bounds_x2,
+                                      float bounds_y2);
+
+/**
+ * cogl_framebuffer_pop_clip:
+ * @framebuffer: A #CoglFramebuffer pointer
+ *
+ * Reverts the clipping region to the state before the last call to
+ * cogl_framebuffer_push_scissor_clip(), cogl_framebuffer_push_rectangle_clip()
+ * cogl_framebuffer_push_path_clip(), or cogl_framebuffer_push_primitive_clip().
+ *
+ * Since: 1.10
+ * Stability: unstable
+ */
+void
+cogl_framebuffer_pop_clip (CoglFramebuffer *framebuffer);
+
+/**
+ * cogl_framebuffer_get_red_bits:
+ * @framebuffer: a pointer to a #CoglFramebuffer
+ *
+ * Retrieves the number of red bits of @framebuffer
+ *
+ * Return value: the number of bits
+ *
+ * Since: 1.8
+ * Stability: unstable
+ */
+int
+cogl_framebuffer_get_red_bits (CoglFramebuffer *framebuffer);
+
+/**
+ * cogl_framebuffer_get_green_bits:
+ * @framebuffer: a pointer to a #CoglFramebuffer
+ *
+ * Retrieves the number of green bits of @framebuffer
+ *
+ * Return value: the number of bits
+ *
+ * Since: 1.8
+ * Stability: unstable
+ */
+int
+cogl_framebuffer_get_green_bits (CoglFramebuffer *framebuffer);
+
+/**
+ * cogl_framebuffer_get_blue_bits:
+ * @framebuffer: a pointer to a #CoglFramebuffer
+ *
+ * Retrieves the number of blue bits of @framebuffer
+ *
+ * Return value: the number of bits
+ *
+ * Since: 1.8
+ * Stability: unstable
+ */
+int
+cogl_framebuffer_get_blue_bits (CoglFramebuffer *framebuffer);
+
+/**
+ * cogl_framebuffer_get_alpha_bits:
+ * @framebuffer: a pointer to a #CoglFramebuffer
+ *
+ * Retrieves the number of alpha bits of @framebuffer
+ *
+ * Return value: the number of bits
+ *
+ * Since: 1.8
+ * Stability: unstable
+ */
+int
+cogl_framebuffer_get_alpha_bits (CoglFramebuffer *framebuffer);
+
+/**
+ * cogl_framebuffer_get_depth_bits:
+ * @framebuffer: a pointer to a #CoglFramebuffer
+ *
+ * Retrieves the number of depth bits of @framebuffer
+ *
+ * Return value: the number of bits
+ *
+ * Since: 2.0
+ * Stability: unstable
+ */
+int
+cogl_framebuffer_get_depth_bits (CoglFramebuffer *framebuffer);
+
+/**
+ * cogl_framebuffer_get_dither_enabled:
+ * @framebuffer: a pointer to a #CoglFramebuffer
+ *
+ * Returns whether dithering has been requested for the given @framebuffer.
+ * See cogl_framebuffer_set_dither_enabled() for more details about dithering.
+ *
+ * <note>This may return %TRUE even when the underlying @framebuffer
+ * display pipeline does not support dithering. This value only represents
+ * the user's request for dithering.</note>
+ *
+ * Return value: %TRUE if dithering has been requested or %FALSE if not.
+ * Since: 1.8
+ * Stability: unstable
+ */
+CoglBool
+cogl_framebuffer_get_dither_enabled (CoglFramebuffer *framebuffer);
+
+/**
+ * cogl_framebuffer_set_dither_enabled:
+ * @framebuffer: a pointer to a #CoglFramebuffer
+ * @dither_enabled: %TRUE to enable dithering or %FALSE to disable
+ *
+ * Enables or disabled dithering if supported by the hardware.
+ *
+ * Dithering is a hardware dependent technique to increase the visible
+ * color resolution beyond what the underlying hardware supports by playing
+ * tricks with the colors placed into the framebuffer to give the illusion
+ * of other colors. (For example this can be compared to half-toning used
+ * by some news papers to show varying levels of grey even though their may
+ * only be black and white are available).
+ *
+ * If the current display pipeline for @framebuffer does not support dithering
+ * then this has no affect.
+ *
+ * Dithering is enabled by default.
+ *
+ * Since: 1.8
+ * Stability: unstable
+ */
+void
+cogl_framebuffer_set_dither_enabled (CoglFramebuffer *framebuffer,
+                                     CoglBool dither_enabled);
+
+/**
+ * cogl_framebuffer_get_depth_write_enabled:
+ * @framebuffer: a pointer to a #CoglFramebuffer
+ *
+ * Queries whether depth buffer writing is enabled for @framebuffer. This
+ * can be controlled via cogl_framebuffer_set_depth_write_enabled().
+ *
+ * Return value: %TRUE if depth writing is enabled or %FALSE if not.
+ * Since: 1.18
+ * Stability: unstable
+ */
+CoglBool
+cogl_framebuffer_get_depth_write_enabled (CoglFramebuffer *framebuffer);
+
+/**
+ * cogl_framebuffer_set_depth_write_enabled:
+ * @framebuffer: a pointer to a #CoglFramebuffer
+ * @depth_write_enabled: %TRUE to enable depth writing or %FALSE to disable
+ *
+ * Enables or disables depth buffer writing when rendering to @framebuffer.
+ * If depth writing is enabled for both the framebuffer and the rendering
+ * pipeline, and the framebuffer has an associated depth buffer, depth
+ * information will be written to this buffer during rendering.
+ *
+ * Depth buffer writing is enabled by default.
+ *
+ * Since: 1.18
+ * Stability: unstable
+ */
+void
+cogl_framebuffer_set_depth_write_enabled (CoglFramebuffer *framebuffer,
+                                          CoglBool depth_write_enabled);
+
+/**
+ * cogl_framebuffer_get_color_mask:
+ * @framebuffer: a pointer to a #CoglFramebuffer
+ *
+ * Gets the current #CoglColorMask of which channels would be written to the
+ * current framebuffer. Each bit set in the mask means that the
+ * corresponding color would be written.
+ *
+ * Returns: A #CoglColorMask
+ * Since: 1.8
+ * Stability: unstable
+ */
+CoglColorMask
+cogl_framebuffer_get_color_mask (CoglFramebuffer *framebuffer);
+
+/**
+ * cogl_framebuffer_set_color_mask:
+ * @framebuffer: a pointer to a #CoglFramebuffer
+ * @color_mask: A #CoglColorMask of which color channels to write to
+ *              the current framebuffer.
+ *
+ * Defines a bit mask of which color channels should be written to the
+ * given @framebuffer. If a bit is set in @color_mask that means that
+ * color will be written.
+ *
+ * Since: 1.8
+ * Stability: unstable
+ */
+void
+cogl_framebuffer_set_color_mask (CoglFramebuffer *framebuffer,
+                                 CoglColorMask color_mask);
+
+/**
+ * cogl_framebuffer_set_depth_texture_enabled:
+ * @framebuffer: A #CoglFramebuffer
+ * @enabled: TRUE or FALSE
+ *
+ * If @enabled is #TRUE, the depth buffer used when rendering to @framebuffer
+ * is available as a texture. You can retrieve the texture with
+ * cogl_framebuffer_get_depth_texture().
+ *
+ * <note>It's possible that your GPU does not support depth textures. You
+ * should check the %COGL_FEATURE_ID_DEPTH_TEXTURE feature before using this
+ * function.</note>
+ * <note>It's not valid to call this function after the framebuffer has been
+ * allocated as the creation of the depth texture is done at allocation time.
+ * </note>
+ *
+ * Since: 1.14
+ * Stability: unstable
+ */
+void
+cogl_framebuffer_set_depth_texture_enabled (CoglFramebuffer *framebuffer,
+                                            CoglBool enabled);
+
+/**
+ * cogl_framebuffer_get_depth_texture_enabled:
+ * @framebuffer: A #CoglFramebuffer
+ *
+ * Queries whether texture based depth buffer has been enabled via
+ * cogl_framebuffer_set_depth_texture_enabled().
+ *
+ * Return value: %TRUE if a depth texture has been enabled, else
+ *               %FALSE.
+ *
+ * Since: 1.14
+ * Stability: unstable
+ */
+CoglBool
+cogl_framebuffer_get_depth_texture_enabled (CoglFramebuffer *framebuffer);
+
+/**
+ * cogl_framebuffer_get_depth_texture:
+ * @framebuffer: A #CoglFramebuffer
+ *
+ * Retrieves the depth buffer of @framebuffer as a #CoglTexture. You need to
+ * call cogl_framebuffer_get_depth_texture(fb, TRUE); before using this
+ * function.
+ *
+ * <note>Calling this function implicitely allocates the framebuffer.</note>
+ * <note>The texture returned stays valid as long as the framebuffer stays
+ * valid.</note>
+ *
+ * Returns: (transfer none): the depth texture
+ *
+ * Since: 1.14
+ * Stability: unstable
+ */
+CoglTexture *
+cogl_framebuffer_get_depth_texture (CoglFramebuffer *framebuffer);
+
+/**
+ * cogl_framebuffer_set_samples_per_pixel:
+ * @framebuffer: A #CoglFramebuffer framebuffer
+ * @samples_per_pixel: The minimum number of samples per pixel
+ *
+ * Requires that when rendering to @framebuffer then @n point samples
+ * should be made per pixel which will all contribute to the final
+ * resolved color for that pixel. The idea is that the hardware aims
+ * to get quality similar to what you would get if you rendered
+ * everything twice as big (for 4 samples per pixel) and then scaled
+ * that image back down with filtering. It can effectively remove the
+ * jagged edges of polygons and should be more efficient than if you
+ * were to manually render at a higher resolution and downscale
+ * because the hardware is often able to take some shortcuts. For
+ * example the GPU may only calculate a single texture sample for all
+ * points of a single pixel, and for tile based architectures all the
+ * extra sample data (such as depth and stencil samples) may be
+ * handled on-chip and so avoid increased demand on system memory
+ * bandwidth.
+ *
+ * By default this value is usually set to 0 and that is referred to
+ * as "single-sample" rendering. A value of 1 or greater is referred
+ * to as "multisample" rendering.
+ *
+ * <note>There are some semantic differences between single-sample
+ * rendering and multisampling with just 1 point sample such as it
+ * being redundant to use the cogl_framebuffer_resolve_samples() and
+ * cogl_framebuffer_resolve_samples_region() apis with single-sample
+ * rendering.</note>
+ *
+ * <note>It's recommended that
+ * cogl_framebuffer_resolve_samples_region() be explicitly used at the
+ * end of rendering to a point sample buffer to minimize the number of
+ * samples that get resolved. By default Cogl will implicitly resolve
+ * all framebuffer samples but if only a small region of a
+ * framebuffer has changed this can lead to redundant work being
+ * done.</note>
+ *
+ * Since: 1.8
+ * Stability: unstable
+ */
+void
+cogl_framebuffer_set_samples_per_pixel (CoglFramebuffer *framebuffer,
+                                        int samples_per_pixel);
+
+/**
+ * cogl_framebuffer_get_samples_per_pixel:
+ * @framebuffer: A #CoglFramebuffer framebuffer
+ *
+ * Gets the number of points that are sampled per-pixel when
+ * rasterizing geometry. Usually by default this will return 0 which
+ * means that single-sample not multisample rendering has been chosen.
+ * When using a GPU supporting multisample rendering it's possible to
+ * increase the number of samples per pixel using
+ * cogl_framebuffer_set_samples_per_pixel().
+ *
+ * Calling cogl_framebuffer_get_samples_per_pixel() before the
+ * framebuffer has been allocated will simply return the value set
+ * using cogl_framebuffer_set_samples_per_pixel(). After the
+ * framebuffer has been allocated the value will reflect the actual
+ * number of samples that will be made by the GPU.
+ *
+ * Returns: The number of point samples made per pixel when
+ *          rasterizing geometry or 0 if single-sample rendering
+ *          has been chosen.
+ *
+ * Since: 1.10
+ * Stability: unstable
+ */
+int
+cogl_framebuffer_get_samples_per_pixel (CoglFramebuffer *framebuffer);
+
+
+/**
+ * cogl_framebuffer_resolve_samples:
+ * @framebuffer: A #CoglFramebuffer framebuffer
+ *
+ * When point sample rendering (also known as multisample rendering)
+ * has been enabled via cogl_framebuffer_set_samples_per_pixel()
+ * then you can optionally call this function (or
+ * cogl_framebuffer_resolve_samples_region()) to explicitly resolve
+ * the point samples into values for the final color buffer.
+ *
+ * Some GPUs will implicitly resolve the point samples during
+ * rendering and so this function is effectively a nop, but with other
+ * architectures it is desirable to defer the resolve step until the
+ * end of the frame.
+ *
+ * Since Cogl will automatically ensure samples are resolved if the
+ * target color buffer is used as a source this API only needs to be
+ * used if explicit control is desired - perhaps because you want to
+ * ensure that the resolve is completed in advance to avoid later
+ * having to wait for the resolve to complete.
+ *
+ * If you are performing incremental updates to a framebuffer you
+ * should consider using cogl_framebuffer_resolve_samples_region()
+ * instead to avoid resolving redundant pixels.
+ *
+ * Since: 1.8
+ * Stability: unstable
+ */
+void
+cogl_framebuffer_resolve_samples (CoglFramebuffer *framebuffer);
+
+/**
+ * cogl_framebuffer_resolve_samples_region:
+ * @framebuffer: A #CoglFramebuffer framebuffer
+ * @x: top-left x coordinate of region to resolve
+ * @y: top-left y coordinate of region to resolve
+ * @width: width of region to resolve
+ * @height: height of region to resolve
+ *
+ * When point sample rendering (also known as multisample rendering)
+ * has been enabled via cogl_framebuffer_set_samples_per_pixel()
+ * then you can optionally call this function (or
+ * cogl_framebuffer_resolve_samples()) to explicitly resolve the point
+ * samples into values for the final color buffer.
+ *
+ * Some GPUs will implicitly resolve the point samples during
+ * rendering and so this function is effectively a nop, but with other
+ * architectures it is desirable to defer the resolve step until the
+ * end of the frame.
+ *
+ * Use of this API is recommended if incremental, small updates to
+ * a framebuffer are being made because by default Cogl will
+ * implicitly resolve all the point samples of the framebuffer which
+ * can result in redundant work if only a small number of samples have
+ * changed.
+ *
+ * Because some GPUs implicitly resolve point samples this function
+ * only guarantees that at-least the region specified will be resolved
+ * and if you have rendered to a larger region then it's possible that
+ * other samples may be implicitly resolved.
+ *
+ * Since: 1.8
+ * Stability: unstable
+ */
+void
+cogl_framebuffer_resolve_samples_region (CoglFramebuffer *framebuffer,
+                                         int x,
+                                         int y,
+                                         int width,
+                                         int height);
+
+/**
+ * cogl_framebuffer_get_context:
+ * @framebuffer: A #CoglFramebuffer
+ *
+ * Can be used to query the #CoglContext a given @framebuffer was
+ * instantiated within. This is the #CoglContext that was passed to
+ * cogl_onscreen_new() for example.
+ *
+ * Return value: (transfer none): The #CoglContext that the given
+ *               @framebuffer was instantiated within.
+ * Since: 1.8
+ * Stability: unstable
+ */
+CoglContext *
+cogl_framebuffer_get_context (CoglFramebuffer *framebuffer);
+
+/**
+ * cogl_framebuffer_clear:
+ * @framebuffer: A #CoglFramebuffer
+ * @buffers: A mask of #CoglBufferBit<!-- -->'s identifying which auxiliary
+ *   buffers to clear
+ * @color: The color to clear the color buffer too if specified in
+ *         @buffers.
+ *
+ * Clears all the auxiliary buffers identified in the @buffers mask, and if
+ * that includes the color buffer then the specified @color is used.
+ *
+ * Since: 1.8
+ * Stability: unstable
+ */
+void
+cogl_framebuffer_clear (CoglFramebuffer *framebuffer,
+                        unsigned long buffers,
+                        const CoglColor *color);
+
+/**
+ * cogl_framebuffer_clear4f:
+ * @framebuffer: A #CoglFramebuffer
+ * @buffers: A mask of #CoglBufferBit<!-- -->'s identifying which auxiliary
+ *   buffers to clear
+ * @red: The red component of color to clear the color buffer too if
+ *       specified in @buffers.
+ * @green: The green component of color to clear the color buffer too if
+ *         specified in @buffers.
+ * @blue: The blue component of color to clear the color buffer too if
+ *        specified in @buffers.
+ * @alpha: The alpha component of color to clear the color buffer too if
+ *         specified in @buffers.
+ *
+ * Clears all the auxiliary buffers identified in the @buffers mask, and if
+ * that includes the color buffer then the specified @color is used.
+ *
+ * Since: 1.8
+ * Stability: unstable
+ */
+void
+cogl_framebuffer_clear4f (CoglFramebuffer *framebuffer,
+                          unsigned long buffers,
+                          float red,
+                          float green,
+                          float blue,
+                          float alpha);
+
+/**
+ * cogl_framebuffer_draw_primitive:
+ * @framebuffer: A destination #CoglFramebuffer
+ * @pipeline: A #CoglPipeline state object
+ * @primitive: A #CoglPrimitive geometry object
+ *
+ * Draws the given @primitive geometry to the specified destination
+ * @framebuffer using the graphics processing state described by @pipeline.
+ *
+ * This drawing api doesn't support high-level meta texture types such
+ * as #CoglTexture2DSliced so it is the user's responsibility to
+ * ensure that only low-level textures that can be directly sampled by
+ * a GPU such as #CoglTexture2D, #CoglTextureRectangle or #CoglTexture3D
+ * are associated with layers of the given @pipeline.
+ *
+ * <note>This api doesn't support any of the legacy global state options such
+ * as cogl_set_depth_test_enabled(), cogl_set_backface_culling_enabled() or
+ * cogl_program_use()</note>
+ *
+ * Stability: unstable
+ * Since: 1.10
+ * Deprecated: 1.16: Use #CoglPrimitive<!-- -->s and
+ *                   cogl_primitive_draw() instead
+ */
+COGL_DEPRECATED_IN_1_16_FOR (cogl_primitive_draw)
+void
+cogl_framebuffer_draw_primitive (CoglFramebuffer *framebuffer,
+                                 CoglPipeline *pipeline,
+                                 CoglPrimitive *primitive);
+
+/**
+ * cogl_framebuffer_vdraw_attributes:
+ * @framebuffer: A destination #CoglFramebuffer
+ * @pipeline: A #CoglPipeline state object
+ * @mode: The #CoglVerticesMode defining the topology of vertices
+ * @first_vertex: The vertex offset within the given attributes to draw from
+ * @n_vertices: The number of vertices to draw from the given attributes
+ * @...: A set of vertex #CoglAttribute<!-- -->s defining vertex geometry
+ *
+ * First defines a geometry primitive by grouping a set of vertex attributes;
+ * specifying a @first_vertex; a number of vertices (@n_vertices) and
+ * specifying  what kind of topology the vertices have via @mode.
+ *
+ * Then the function draws the given @primitive geometry to the specified
+ * destination @framebuffer using the graphics processing pipeline described by
+ * @pipeline.
+ *
+ * The list of #CoglAttribute<!-- -->s define the attributes of the vertices to
+ * be drawn, such as positions, colors and normals and should be %NULL
+ * terminated.
+ *
+ * This drawing api doesn't support high-level meta texture types such
+ * as #CoglTexture2DSliced so it is the user's responsibility to
+ * ensure that only low-level textures that can be directly sampled by
+ * a GPU such as #CoglTexture2D, #CoglTextureRectangle or #CoglTexture3D
+ * are associated with layers of the given @pipeline.
+ *
+ * Stability: unstable
+ * Since: 1.10
+ * Deprecated: 1.16: Use #CoglPrimitive<!-- -->s and
+ *                   cogl_primitive_draw() instead
+ */
+COGL_DEPRECATED_IN_1_16_FOR (cogl_primitive_draw)
+void
+cogl_framebuffer_vdraw_attributes (CoglFramebuffer *framebuffer,
+                                   CoglPipeline *pipeline,
+                                   CoglVerticesMode mode,
+                                   int first_vertex,
+                                   int n_vertices,
+                                   ...) COGL_GNUC_NULL_TERMINATED;
+
+/**
+ * cogl_framebuffer_draw_attributes:
+ * @framebuffer: A destination #CoglFramebuffer
+ * @pipeline: A #CoglPipeline state object
+ * @mode: The #CoglVerticesMode defining the topology of vertices
+ * @first_vertex: The vertex offset within the given attributes to draw from
+ * @n_vertices: The number of vertices to draw from the given attributes
+ * @attributes: An array of pointers to #CoglAttribute<-- -->s defining vertex
+ *              geometry
+ * @n_attributes: The number of attributes in the @attributes array.
+ *
+ * First defines a geometry primitive by grouping a set of vertex @attributes;
+ * specifying a @first_vertex; a number of vertices (@n_vertices) and
+ * specifying  what kind of topology the vertices have via @mode.
+ *
+ * Then the function draws the given @primitive geometry to the specified
+ * destination @framebuffer using the graphics processing pipeline described by
+ * @pipeline.
+ *
+ * The list of #CoglAttribute<!-- -->s define the attributes of the vertices to
+ * be drawn, such as positions, colors and normals and the number of attributes
+ * is given as @n_attributes.
+ *
+ * This drawing api doesn't support high-level meta texture types such
+ * as #CoglTexture2DSliced so it is the user's responsibility to
+ * ensure that only low-level textures that can be directly sampled by
+ * a GPU such as #CoglTexture2D, #CoglTextureRectangle or #CoglTexture3D
+ * are associated with layers of the given @pipeline.
+ *
+ * <note>This api doesn't support any of the legacy global state options such
+ * as cogl_set_depth_test_enabled(), cogl_set_backface_culling_enabled() or
+ * cogl_program_use()</note>
+ *
+ * Stability: unstable
+ * Since: 1.10
+ * Deprecated: 1.16: Use #CoglPrimitive<!-- -->s and
+ *                   cogl_primitive_draw() instead
+ */
+COGL_DEPRECATED_IN_1_16_FOR (cogl_primitive_draw)
+void
+cogl_framebuffer_draw_attributes (CoglFramebuffer *framebuffer,
+                                  CoglPipeline *pipeline,
+                                  CoglVerticesMode mode,
+                                  int first_vertex,
+                                  int n_vertices,
+                                  CoglAttribute **attributes,
+                                  int n_attributes);
+
+/**
+ * cogl_framebuffer_vdraw_indexed_attributes:
+ * @framebuffer: A destination #CoglFramebuffer
+ * @pipeline: A #CoglPipeline state object
+ * @mode: The #CoglVerticesMode defining the topology of vertices
+ * @first_vertex: The vertex offset within the given attributes to draw from
+ * @n_vertices: The number of vertices to draw from the given attributes
+ * @indices: The array of indices used by the GPU to lookup attribute
+ *           data for each vertex.
+ * @...: A set of vertex #CoglAttribute<!-- -->s defining vertex geometry
+ *
+ * Behaves the same as cogl_framebuffer_vdraw_attributes() except that
+ * instead of reading vertex data sequentially from the specified
+ * attributes the @indices provide an indirection for how the data
+ * should be indexed allowing a random access order to be
+ * specified.
+ *
+ * For example an indices array of [0, 1, 2, 0, 2, 3] could be used
+ * used to draw two triangles (@mode = %COGL_VERTICES_MODE_TRIANGLES +
+ * @n_vertices = 6) but only provide attribute data for the 4 corners
+ * of a rectangle. When the GPU needs to read in each of the 6
+ * vertices it will read the @indices array for each vertex in
+ * sequence and use the index to look up the vertex attribute data. So
+ * here you can see that first and fourth vertex will point to the
+ * same data and third and fifth vertex will also point to shared
+ * data.
+ *
+ * Drawing with indices can be a good way of minimizing the size of a
+ * mesh by allowing you to avoid data for duplicate vertices because
+ * multiple entries in the index array can refer back to a single
+ * shared vertex.
+ *
+ * <note>The @indices array must be at least as long as @first_vertex
+ * + @n_vertices otherwise the GPU will overrun the indices array when
+ * looking up vertex data.</note>
+ *
+ * Since it's very common to want to draw a run of rectangles using
+ * indices to avoid duplicating vertex data you can use
+ * cogl_get_rectangle_indices() to get a set of indices that can be
+ * shared.
+ *
+ * This drawing api doesn't support high-level meta texture types such
+ * as #CoglTexture2DSliced so it is the user's responsibility to
+ * ensure that only low-level textures that can be directly sampled by
+ * a GPU such as #CoglTexture2D, #CoglTextureRectangle or
+ * #CoglTexture3D are associated with layers of the given @pipeline.
+ *
+ * <note>This api doesn't support any of the legacy global state
+ * options such as cogl_set_depth_test_enabled(),
+ * cogl_set_backface_culling_enabled() or cogl_program_use()</note>
+ *
+ * Stability: unstable
+ * Since: 1.10
+ * Deprecated: 1.16: Use #CoglPrimitive<!-- -->s and
+ *                   cogl_primitive_draw() instead
+ */
+COGL_DEPRECATED_IN_1_16_FOR (cogl_primitive_draw)
+void
+cogl_framebuffer_vdraw_indexed_attributes (CoglFramebuffer *framebuffer,
+                                           CoglPipeline *pipeline,
+                                           CoglVerticesMode mode,
+                                           int first_vertex,
+                                           int n_vertices,
+                                           CoglIndices *indices,
+                                           ...) COGL_GNUC_NULL_TERMINATED;
+
+/**
+ * cogl_framebuffer_draw_indexed_attributes:
+ * @framebuffer: A destination #CoglFramebuffer
+ * @pipeline: A #CoglPipeline state object
+ * @mode: The #CoglVerticesMode defining the topology of vertices
+ * @first_vertex: The vertex offset within the given attributes to draw from
+ * @n_vertices: The number of vertices to draw from the given attributes
+ * @indices: The array of indices used by the GPU to lookup attribute
+ *           data for each vertex.
+ * @attributes: An array of pointers to #CoglAttribute<-- -->s defining vertex
+ *              geometry
+ * @n_attributes: The number of attributes in the @attributes array.
+ *
+ * Behaves the same as cogl_framebuffer_draw_attributes() except that
+ * instead of reading vertex data sequentially from the specified
+ * @attributes the @indices provide an indirection for how the data
+ * should be indexed allowing a random access order to be
+ * specified.
+ *
+ * For example an indices array of [0, 1, 2, 0, 2, 3] could be used
+ * used to draw two triangles (@mode = %COGL_VERTICES_MODE_TRIANGLES +
+ * @n_vertices = 6) but only provide attribute data for the 4 corners
+ * of a rectangle. When the GPU needs to read in each of the 6
+ * vertices it will read the @indices array for each vertex in
+ * sequence and use the index to look up the vertex attribute data. So
+ * here you can see that first and fourth vertex will point to the
+ * same data and third and fifth vertex will also point to shared
+ * data.
+ *
+ * Drawing with indices can be a good way of minimizing the size of a
+ * mesh by allowing you to avoid data for duplicate vertices because
+ * multiple entries in the index array can refer back to a single
+ * shared vertex.
+ *
+ * <note>The @indices array must be at least as long as @first_vertex
+ * + @n_vertices otherwise the GPU will overrun the indices array when
+ * looking up vertex data.</note>
+ *
+ * Since it's very common to want to draw a run of rectangles using
+ * indices to avoid duplicating vertex data you can use
+ * cogl_get_rectangle_indices() to get a set of indices that can be
+ * shared.
+ *
+ * This drawing api doesn't support high-level meta texture types such
+ * as #CoglTexture2DSliced so it is the user's responsibility to
+ * ensure that only low-level textures that can be directly sampled by
+ * a GPU such as #CoglTexture2D, #CoglTextureRectangle or
+ * #CoglTexture3D are associated with layers of the given @pipeline.
+ *
+ * <note>This api doesn't support any of the legacy global state
+ * options such as cogl_set_depth_test_enabled(),
+ * cogl_set_backface_culling_enabled() or cogl_program_use()</note>
+ *
+ * Stability: unstable
+ * Since: 1.10
+ * Deprecated: 1.16: Use #CoglPrimitive<!-- -->s and
+ *                   cogl_primitive_draw() instead
+ */
+COGL_DEPRECATED_IN_1_16_FOR (cogl_primitive_draw)
+void
+cogl_framebuffer_draw_indexed_attributes (CoglFramebuffer *framebuffer,
+                                          CoglPipeline *pipeline,
+                                          CoglVerticesMode mode,
+                                          int first_vertex,
+                                          int n_vertices,
+                                          CoglIndices *indices,
+                                          CoglAttribute **attributes,
+                                          int n_attributes);
+
+/**
+ * cogl_framebuffer_draw_rectangle:
+ * @framebuffer: A destination #CoglFramebuffer
+ * @pipeline: A #CoglPipeline state object
+ * @x_1: X coordinate of the top-left corner
+ * @y_1: Y coordinate of the top-left corner
+ * @x_2: X coordinate of the bottom-right corner
+ * @y_2: Y coordinate of the bottom-right corner
+ *
+ * Draws a rectangle to @framebuffer with the given @pipeline state
+ * and with the top left corner positioned at (@x_1, @y_1) and the
+ * bottom right corner positioned at (@x_2, @y_2).
+ *
+ * <note>The position is the position before the rectangle has been
+ * transformed by the model-view matrix and the projection
+ * matrix.</note>
+ *
+ * <note>If you want to describe a rectangle with a texture mapped on
+ * it then you can use
+ * cogl_framebuffer_draw_textured_rectangle().</note>
+ *
+ * Since: 1.10
+ * Stability: unstable
+ */
+void
+cogl_framebuffer_draw_rectangle (CoglFramebuffer *framebuffer,
+                                 CoglPipeline *pipeline,
+                                 float x_1,
+                                 float y_1,
+                                 float x_2,
+                                 float y_2);
+
+/**
+ * cogl_framebuffer_draw_textured_rectangle:
+ * @framebuffer: A destination #CoglFramebuffer
+ * @pipeline: A #CoglPipeline state object
+ * @x_1: x coordinate upper left on screen.
+ * @y_1: y coordinate upper left on screen.
+ * @x_2: x coordinate lower right on screen.
+ * @y_2: y coordinate lower right on screen.
+ * @s_1: S texture coordinate of the top-left coorner
+ * @t_1: T texture coordinate of the top-left coorner
+ * @s_2: S texture coordinate of the bottom-right coorner
+ * @t_2: T texture coordinate of the bottom-right coorner
+ *
+ * Draws a textured rectangle to @framebuffer using the given
+ * @pipeline state with the top left corner positioned at (@x_1, @y_1)
+ * and the bottom right corner positioned at (@x_2, @y_2). The top
+ * left corner will have texture coordinates of (@s_1, @t_1) and the
+ * bottom right corner will have texture coordinates of (@s_2, @t_2).
+ *
+ * <note>The position is the position before the rectangle has been
+ * transformed by the model-view matrix and the projection
+ * matrix.</note>
+ *
+ * This is a high level drawing api that can handle any kind of
+ * #CoglMetaTexture texture such as #CoglTexture2DSliced textures
+ * which may internally be comprised of multiple low-level textures.
+ * This is unlike low-level drawing apis such as cogl_primitive_draw()
+ * which only support low level texture types that are directly
+ * supported by GPUs such as #CoglTexture2D.
+ *
+ * <note>The given texture coordinates will only be used for the first
+ * texture layer of the pipeline and if your pipeline has more than
+ * one layer then all other layers will have default texture
+ * coordinates of @s_1=0.0 @t_1=0.0 @s_2=1.0 @t_2=1.0 </note>
+ *
+ * The given texture coordinates should always be normalized such that
+ * (0, 0) corresponds to the top left and (1, 1) corresponds to the
+ * bottom right. To map an entire texture across the rectangle pass
+ * in @s_1=0, @t_1=0, @s_2=1, @t_2=1.
+ *
+ * <note>Even if you have associated a #CoglTextureRectangle texture
+ * with one of your @pipeline layers which normally implies working
+ * with non-normalized texture coordinates this api should still be
+ * passed normalized texture coordinates.</note>
+ *
+ * Since: 1.10
+ * Stability: unstable
+ */
+void
+cogl_framebuffer_draw_textured_rectangle (CoglFramebuffer *framebuffer,
+                                          CoglPipeline *pipeline,
+                                          float x_1,
+                                          float y_1,
+                                          float x_2,
+                                          float y_2,
+                                          float s_1,
+                                          float t_1,
+                                          float s_2,
+                                          float t_2);
+
+/**
+ * cogl_framebuffer_draw_multitextured_rectangle:
+ * @framebuffer: A destination #CoglFramebuffer
+ * @pipeline: A #CoglPipeline state object
+ * @x_1: x coordinate upper left on screen.
+ * @y_1: y coordinate upper left on screen.
+ * @x_2: x coordinate lower right on screen.
+ * @y_2: y coordinate lower right on screen.
+ * @tex_coords: (in) (array) (transfer none): An array containing groups of
+ *   4 float values: [s_1, t_1, s_2, t_2] that are interpreted as two texture
+ *   coordinates; one for the top left texel, and one for the bottom right
+ *   texel. Each value should be between 0.0 and 1.0, where the coordinate
+ *   (0.0, 0.0) represents the top left of the texture, and (1.0, 1.0) the
+ *   bottom right.
+ * @tex_coords_len: The length of the @tex_coords array. (For one layer
+ *   and one group of texture coordinates, this would be 4)
+ *
+ * Draws a textured rectangle to @framebuffer with the given @pipeline
+ * state with the top left corner positioned at (@x_1, @y_1) and the
+ * bottom right corner positioned at (@x_2, @y_2). As a pipeline may
+ * contain multiple texture layers this interface lets you supply
+ * texture coordinates for each layer of the pipeline.
+ *
+ * <note>The position is the position before the rectangle has been
+ * transformed by the model-view matrix and the projection
+ * matrix.</note>
+ *
+ * This is a high level drawing api that can handle any kind of
+ * #CoglMetaTexture texture for the first layer such as
+ * #CoglTexture2DSliced textures which may internally be comprised of
+ * multiple low-level textures.  This is unlike low-level drawing apis
+ * such as cogl_primitive_draw() which only support low level texture
+ * types that are directly supported by GPUs such as #CoglTexture2D.
+ *
+ * <note>This api can not currently handle multiple high-level meta
+ * texture layers. The first layer may be a high level meta texture
+ * such as #CoglTexture2DSliced but all other layers much be low
+ * level textures such as #CoglTexture2D and additionally they
+ * should be textures that can be sampled using normalized coordinates
+ * (so not #CoglTextureRectangle textures).</note>
+ *
+ * The top left texture coordinate for layer 0 of any pipeline will be
+ * (tex_coords[0], tex_coords[1]) and the bottom right coordinate will
+ * be (tex_coords[2], tex_coords[3]). The coordinates for layer 1
+ * would be (tex_coords[4], tex_coords[5]) (tex_coords[6],
+ * tex_coords[7]) and so on...
+ *
+ * The given texture coordinates should always be normalized such that
+ * (0, 0) corresponds to the top left and (1, 1) corresponds to the
+ * bottom right. To map an entire texture across the rectangle pass
+ * in tex_coords[0]=0, tex_coords[1]=0, tex_coords[2]=1,
+ * tex_coords[3]=1.
+ *
+ * <note>Even if you have associated a #CoglTextureRectangle texture
+ * which normally implies working with non-normalized texture
+ * coordinates this api should still be passed normalized texture
+ * coordinates.</note>
+ *
+ * The first pair of coordinates are for the first layer (with the
+ * smallest layer index) and if you supply less texture coordinates
+ * than there are layers in the current source material then default
+ * texture coordinates (0.0, 0.0, 1.0, 1.0) are generated.
+ *
+ * Since: 1.10
+ * Stability: unstable
+ */
+void
+cogl_framebuffer_draw_multitextured_rectangle (CoglFramebuffer *framebuffer,
+                                               CoglPipeline *pipeline,
+                                               float x_1,
+                                               float y_1,
+                                               float x_2,
+                                               float y_2,
+                                               const float *tex_coords,
+                                               int tex_coords_len);
+
+/**
+ * cogl_framebuffer_draw_rectangles:
+ * @framebuffer: A destination #CoglFramebuffer
+ * @pipeline: A #CoglPipeline state object
+ * @coordinates: (in) (array) (transfer none): an array of coordinates
+ *   containing groups of 4 float values: [x_1, y_1, x_2, y_2] that are
+ *   interpreted as two position coordinates; one for the top left of
+ *   the rectangle (x1, y1), and one for the bottom right of the
+ *   rectangle (x2, y2).
+ * @n_rectangles: number of rectangles defined in @coordinates.
+ *
+ * Draws a series of rectangles to @framebuffer with the given
+ * @pipeline state in the same way that
+ * cogl_framebuffer_draw_rectangle() does.
+ *
+ * The top left corner of the first rectangle is positioned at
+ * (coordinates[0], coordinates[1]) and the bottom right corner is
+ * positioned at (coordinates[2], coordinates[3]). The positions for
+ * the second rectangle are (coordinates[4], coordinates[5]) and
+ * (coordinates[6], coordinates[7]) and so on...
+ *
+ * <note>The position is the position before the rectangle has been
+ * transformed by the model-view matrix and the projection
+ * matrix.</note>
+ *
+ * As a general rule for better performance its recommended to use
+ * this this API instead of calling
+ * cogl_framebuffer_draw_textured_rectangle() separately for multiple
+ * rectangles if all of the rectangles will be drawn together with the
+ * same @pipeline state.
+ *
+ * Since: 1.10
+ * Stability: unstable
+ */
+void
+cogl_framebuffer_draw_rectangles (CoglFramebuffer *framebuffer,
+                                  CoglPipeline *pipeline,
+                                  const float *coordinates,
+                                  unsigned int n_rectangles);
+
+/**
+ * cogl_framebuffer_draw_textured_rectangles:
+ * @framebuffer: A destination #CoglFramebuffer
+ * @pipeline: A #CoglPipeline state object
+ * @coordinates: (in) (array) (transfer none): an array containing
+ *   groups of 8 float values: [x_1, y_1, x_2, y_2, s_1, t_1, s_2, t_2]
+ *   that have the same meaning as the arguments for
+ *   cogl_framebuffer_draw_textured_rectangle().
+ * @n_rectangles: number of rectangles to @coordinates to draw
+ *
+ * Draws a series of rectangles to @framebuffer with the given
+ * @pipeline state in the same way that
+ * cogl_framebuffer_draw_textured_rectangle() does.
+ *
+ * <note>The position is the position before the rectangle has been
+ * transformed by the model-view matrix and the projection
+ * matrix.</note>
+ *
+ * This is a high level drawing api that can handle any kind of
+ * #CoglMetaTexture texture such as #CoglTexture2DSliced textures
+ * which may internally be comprised of multiple low-level textures.
+ * This is unlike low-level drawing apis such as cogl_primitive_draw()
+ * which only support low level texture types that are directly
+ * supported by GPUs such as #CoglTexture2D.
+ *
+ * The top left corner of the first rectangle is positioned at
+ * (coordinates[0], coordinates[1]) and the bottom right corner is
+ * positioned at (coordinates[2], coordinates[3]). The top left
+ * texture coordinate is (coordinates[4], coordinates[5]) and the
+ * bottom right texture coordinate is (coordinates[6],
+ * coordinates[7]). The coordinates for subsequent rectangles
+ * are defined similarly by the subsequent coordinates.
+ *
+ * As a general rule for better performance its recommended to use
+ * this this API instead of calling
+ * cogl_framebuffer_draw_textured_rectangle() separately for multiple
+ * rectangles if all of the rectangles will be drawn together with the
+ * same @pipeline state.
+ *
+ * The given texture coordinates should always be normalized such that
+ * (0, 0) corresponds to the top left and (1, 1) corresponds to the
+ * bottom right. To map an entire texture across the rectangle pass
+ * in tex_coords[0]=0, tex_coords[1]=0, tex_coords[2]=1,
+ * tex_coords[3]=1.
+ *
+ * <note>Even if you have associated a #CoglTextureRectangle texture
+ * which normally implies working with non-normalized texture
+ * coordinates this api should still be passed normalized texture
+ * coordinates.</note>
+ *
+ * Since: 1.10
+ * Stability: unstable
+ */
+void
+cogl_framebuffer_draw_textured_rectangles (CoglFramebuffer *framebuffer,
+                                           CoglPipeline *pipeline,
+                                           const float *coordinates,
+                                           unsigned int n_rectangles);
+
+/* XXX: Should we take an n_buffers + buffer id array instead of using
+ * the CoglBufferBits type which doesn't seem future proof? */
+/**
+ * cogl_framebuffer_discard_buffers:
+ * @framebuffer: A #CoglFramebuffer
+ * @buffers: A #CoglBufferBit mask of which ancillary buffers you want
+ *           to discard.
+ *
+ * Declares that the specified @buffers no longer need to be referenced
+ * by any further rendering commands. This can be an important
+ * optimization to avoid subsequent frames of rendering depending on
+ * the results of a previous frame.
+ *
+ * For example; some tile-based rendering GPUs are able to avoid allocating and
+ * accessing system memory for the depth and stencil buffer so long as these
+ * buffers are not required as input for subsequent frames and that can save a
+ * significant amount of memory bandwidth used to save and restore their
+ * contents to system memory between frames.
+ *
+ * It is currently considered an error to try and explicitly discard the color
+ * buffer by passing %COGL_BUFFER_BIT_COLOR. This is because the color buffer is
+ * already implicitly discard when you finish rendering to a #CoglOnscreen
+ * framebuffer, and it's not meaningful to try and discard the color buffer of
+ * a #CoglOffscreen framebuffer since they are single-buffered.
+ *
+ *
+ * Since: 1.8
+ * Stability: unstable
+ */
+void
+cogl_framebuffer_discard_buffers (CoglFramebuffer *framebuffer,
+                                  unsigned long buffers);
+
+/**
+ * cogl_framebuffer_finish:
+ * @framebuffer: A #CoglFramebuffer pointer
+ *
+ * This blocks the CPU until all pending rendering associated with the
+ * specified framebuffer has completed. It's very rare that developers should
+ * ever need this level of synchronization with the GPU and should never be
+ * used unless you clearly understand why you need to explicitly force
+ * synchronization.
+ *
+ * One example might be for benchmarking purposes to be sure timing
+ * measurements reflect the time that the GPU is busy for not just the time it
+ * takes to queue rendering commands.
+ *
+ * Stability: unstable
+ * Since: 1.10
+ */
+void
+cogl_framebuffer_finish (CoglFramebuffer *framebuffer);
+
+/**
+ * cogl_framebuffer_read_pixels_into_bitmap:
+ * @framebuffer: A #CoglFramebuffer
+ * @x: The x position to read from
+ * @y: The y position to read from
+ * @source: Identifies which auxillary buffer you want to read
+ *          (only COGL_READ_PIXELS_COLOR_BUFFER supported currently)
+ * @bitmap: The bitmap to store the results in.
+ *
+ * This reads a rectangle of pixels from the given framebuffer where
+ * position (0, 0) is the top left. The pixel at (x, y) is the first
+ * read, and a rectangle of pixels with the same size as the bitmap is
+ * read right and downwards from that point.
+ *
+ * Currently Cogl assumes that the framebuffer is in a premultiplied
+ * format so if the format of @bitmap is non-premultiplied it will
+ * convert it. To read the pixel values without any conversion you
+ * should either specify a format that doesn't use an alpha channel or
+ * use one of the formats ending in PRE.
+ *
+ * Return value: %TRUE if the read succeeded or %FALSE otherwise. The
+ *  function is only likely to fail if the bitmap points to a pixel
+ *  buffer and it could not be mapped.
+ * Since: 1.10
+ * Stability: unstable
+ */
+CoglBool
+cogl_framebuffer_read_pixels_into_bitmap (CoglFramebuffer *framebuffer,
+                                          int x,
+                                          int y,
+                                          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
+ */
+CoglBool
+cogl_framebuffer_read_pixels (CoglFramebuffer *framebuffer,
+                              int x,
+                              int y,
+                              int width,
+                              int height,
+                              CoglPixelFormat format,
+                              uint8_t *pixels);
+
+/**
+ * cogl_get_draw_framebuffer:
+ *
+ * Gets the current #CoglFramebuffer as set using
+ * cogl_push_framebuffer()
+ *
+ * Return value: (transfer none): The current #CoglFramebuffer
+ * Stability: unstable
+ * Since: 1.8
+ */
+CoglFramebuffer *
+cogl_get_draw_framebuffer (void);
+
+#endif /* COGL_ENABLE_EXPERIMENTAL_API */
+
+/* XXX: Note these are defined outside the COGL_ENABLE_EXPERIMENTAL_API guard since
+ * otherwise the glib-mkenums stuff will get upset. */
+
+uint32_t
+cogl_framebuffer_error_quark (void);
+
+/**
+ * COGL_FRAMEBUFFER_ERROR:
+ *
+ * An error domain for reporting #CoglFramebuffer exceptions
+ */
+#define COGL_FRAMEBUFFER_ERROR (cogl_framebuffer_error_quark ())
+
+typedef enum { /*< prefix=COGL_FRAMEBUFFER_ERROR >*/
+  COGL_FRAMEBUFFER_ERROR_ALLOCATE
+} CoglFramebufferError;
+
+/**
+ * cogl_is_framebuffer:
+ * @object: A #CoglObject pointer
+ *
+ * Gets whether the given object references a #CoglFramebuffer.
+ *
+ * Return value: %TRUE if the object references a #CoglFramebuffer
+ *   and %FALSE otherwise.
+ * Since: 1.10
+ * Stability: unstable
+ */
+CoglBool
+cogl_is_framebuffer (void *object);
+
+COGL_END_DECLS
+
+#endif /* __COGL_FRAMEBUFFER_H */