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.

Reviewed-by: Neil Roberts <neil@linux.intel.com>

cogl/cogl-framebuffer-private.h

@@ -153,19 +153,6 @@ _cogl_framebuffer_clear_without_flush4f (CoglFramebuffer *framebuffer,
                                          float blue,
                                          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);
 

cogl/cogl-framebuffer.c

@@ -288,7 +288,7 @@ _cogl_framebuffer_dirty (CoglFramebuffer *framebuffer)
 }
 
 void
-_cogl_framebuffer_clear4f (CoglFramebuffer *framebuffer,
+cogl_framebuffer_clear4f (CoglFramebuffer *framebuffer,
                           unsigned long buffers,
                           float red,
                           float green,
@@ -442,31 +442,19 @@ 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,
+cogl_framebuffer_clear (CoglFramebuffer *framebuffer,
                         unsigned long buffers,
                         const CoglColor *color)
 {
   g_return_if_fail (framebuffer->allocated);
 
-  _cogl_framebuffer_clear4f (framebuffer, buffers,
+  cogl_framebuffer_clear4f (framebuffer, buffers,
                             cogl_color_get_red_float (color),
                             cogl_color_get_green_float (color),
                             cogl_color_get_blue_float (color),

cogl/cogl-framebuffer.h

@@ -277,6 +277,55 @@ cogl_framebuffer_set_color_mask (CoglFramebuffer *framebuffer,
 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.
+ *
+ * Since: 1.8
+ * Stability: unstable
+ */
+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.
+ *
+ * Since: 1.8
+ * Stability: unstable
+ */
+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);

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

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