[cogl/wip/rib/master-next: 9/12] framebuffer: Make framebuffer_clear APIs public experimental

[Robert Bragg <rbragg src gnome org>]

commit 1e5c39a7b98825506803fe999ebf0dfc0ce44a0f
Author: Robert Bragg <robert linux intel com>
Date:   Tue Aug 2 16:27:59 2011 +0100

    framebuffer: Make framebuffer_clear APIs public experimental
    
    This makes cogl_framebuffer_clear and cogl_framebuffer_clear4f public as
    experimental API. Since these functions take explicit framebuffer
    pointers you don't need to push/pop a framebuffer just to clear it. Also
    these functions are implicitly tied to a specific CoglContext via the
    framebuffer pointer unlike cogl_clear.

 cogl/cogl-framebuffer-private.h                    |   13 ------
 cogl/cogl-framebuffer.c                            |   42 +++++++------------
 cogl/cogl-framebuffer.h                            |   45 ++++++++++++++++++++
 cogl/cogl.c                                        |    2 +-
 .../cogl-2.0-experimental-sections.txt             |    2 +
 5 files changed, 63 insertions(+), 41 deletions(-)
---
diff --git a/cogl/cogl-framebuffer-private.h b/cogl/cogl-framebuffer-private.h
index 3a0c09f..9d6b96d 100644
--- a/cogl/cogl-framebuffer-private.h
+++ b/cogl/cogl-framebuffer-private.h
@@ -154,19 +154,6 @@ _cogl_framebuffer_clear_without_flush4f (CoglFramebuffer *framebuffer,
                                          float alpha);
 
 void
-_cogl_framebuffer_clear (CoglFramebuffer *framebuffer,
-                         unsigned long buffers,
-                         const CoglColor *color);
-
-void
-_cogl_framebuffer_clear4f (CoglFramebuffer *framebuffer,
-                           unsigned long buffers,
-                           float red,
-                           float green,
-                           float blue,
-                           float alpha);
-
-void
 _cogl_framebuffer_dirty (CoglFramebuffer *framebuffer);
 
 CoglClipState *
diff --git a/cogl/cogl-framebuffer.c b/cogl/cogl-framebuffer.c
index ac00d54..48a4218 100644
--- a/cogl/cogl-framebuffer.c
+++ b/cogl/cogl-framebuffer.c
@@ -288,12 +288,12 @@ _cogl_framebuffer_dirty (CoglFramebuffer *framebuffer)
 }
 
 void
-_cogl_framebuffer_clear4f (CoglFramebuffer *framebuffer,
-                           unsigned long buffers,
-                           float red,
-                           float green,
-                           float blue,
-                           float alpha)
+cogl_framebuffer_clear4f (CoglFramebuffer *framebuffer,
+                          unsigned long buffers,
+                          float red,
+                          float green,
+                          float blue,
+                          float alpha)
 {
   CoglClipStack *clip_stack = _cogl_framebuffer_get_clip_stack (framebuffer);
   int scissor_x0;
@@ -442,35 +442,23 @@ cleared:
     _cogl_framebuffer_dirty (framebuffer);
 }
 
-/* XXX: We'll need to consider if this API is a good approach for the
- * planned, public, CoglFramebuffer API. A framebuffer may have
- * multiple color buffers associated with it and the user may want to
- * only clear a subset of those buffers. Flags aren't a great
- * mechanism for handling this, but I don't think it would be very
- * convenient if you had to explicitly enumerate the individual
- * ancillary buffers to clear them.
- *
- * My current expectation is that we'll keep this flag based API but
- * also add a way to enumerate the individual color buffers for
- * clearing individually.
- *
- * Note: the 'buffers' and 'color' arguments were switched around on
+/* Note: the 'buffers' and 'color' arguments were switched around on
  * purpose compared to the original cogl_clear API since it was odd
  * that you would be expected to specify a color before even
  * necessarily choosing to clear the color buffer.
  */
 void
-_cogl_framebuffer_clear (CoglFramebuffer *framebuffer,
-                         unsigned long buffers,
-                         const CoglColor *color)
+cogl_framebuffer_clear (CoglFramebuffer *framebuffer,
+                        unsigned long buffers,
+                        const CoglColor *color)
 {
   g_return_if_fail (framebuffer->allocated);
 
-  _cogl_framebuffer_clear4f (framebuffer, buffers,
-                             cogl_color_get_red_float (color),
-                             cogl_color_get_green_float (color),
-                             cogl_color_get_blue_float (color),
-                             cogl_color_get_alpha_float (color));
+  cogl_framebuffer_clear4f (framebuffer, buffers,
+                            cogl_color_get_red_float (color),
+                            cogl_color_get_green_float (color),
+                            cogl_color_get_blue_float (color),
+                            cogl_color_get_alpha_float (color));
 }
 
 int
diff --git a/cogl/cogl-framebuffer.h b/cogl/cogl-framebuffer.h
index f37250b..3c26b24 100644
--- a/cogl/cogl-framebuffer.h
+++ b/cogl/cogl-framebuffer.h
@@ -271,10 +271,55 @@ cogl_framebuffer_set_color_mask (CoglFramebuffer *framebuffer,
  *
  * Return value: The #CoglContext that the given @framebuffer was
  *               instantiated within.
+ * Since: 1.8
+ * Stability: unstable
  */
 CoglContext *
 cogl_framebuffer_get_context (CoglFramebuffer *framebuffer);
 
+#define cogl_framebuffer_clear cogl_framebuffer_clear_EXP
+/**
+ * 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.
+ */
+void
+cogl_framebuffer_clear (CoglFramebuffer *framebuffer,
+                        unsigned long buffers,
+                        const CoglColor *color);
+
+#define cogl_framebuffer_clear4f cogl_framebuffer_clear4f_EXP
+/**
+ * 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.
+ */
+void
+cogl_framebuffer_clear4f (CoglFramebuffer *framebuffer,
+                          unsigned long buffers,
+                          float red,
+                          float green,
+                          float blue,
+                          float alpha);
+
 #define cogl_framebuffer_swap_buffers cogl_framebuffer_swap_buffers_EXP
 void
 cogl_framebuffer_swap_buffers (CoglFramebuffer *framebuffer);
diff --git a/cogl/cogl.c b/cogl/cogl.c
index 10c2cd8..67231f4 100644
--- a/cogl/cogl.c
+++ b/cogl/cogl.c
@@ -136,7 +136,7 @@ cogl_check_extension (const char *name, const char *ext)
 void
 cogl_clear (const CoglColor *color, unsigned long buffers)
 {
-  _cogl_framebuffer_clear (cogl_get_draw_framebuffer (), buffers, color);
+  cogl_framebuffer_clear (cogl_get_draw_framebuffer (), buffers, color);
 }
 
 static gboolean
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 382dcd4..6c0809c 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
@@ -323,6 +323,8 @@ cogl_framebuffer_get_blue_bits
 cogl_framebuffer_get_color_mask
 cogl_framebuffer_set_color_mask
 cogl_framebuffer_get_context
+cogl_framebuffer_clear
+cogl_framebuffer_clear4f
 cogl_framebuffer_swap_buffers
 cogl_framebuffer_swap_region
 cogl_framebuffer_add_swap_buffers_callback