framebuffer: Adds experimental _finish() API

This adds a new experimental function, cogl_framebuffer_finish(), which
can be used to explicitly synchronize the CPU with the GPU. It's rare
that this level of explicit synchronization is desirable but for example
it can be useful during performance analysys to make sure measurements
reflect the working time of the GPU not just the time to queue commands.

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

cogl/cogl-framebuffer.c

@@ -2018,6 +2018,13 @@ cogl_framebuffer_remove_swap_buffers_callback (CoglFramebuffer *framebuffer,
   winsys->onscreen_remove_swap_buffers_callback (onscreen, id);
 }
 
+void
+cogl_framebuffer_finish (CoglFramebuffer *framebuffer)
+{
+  _cogl_framebuffer_flush_journal (framebuffer);
+  GE (framebuffer->context, glFinish ());
+}
+
 void
 cogl_onscreen_set_swap_throttled (CoglOnscreen *onscreen,
                                   gboolean throttled)

cogl/cogl-framebuffer.h

@@ -561,6 +561,25 @@ void
 cogl_framebuffer_remove_swap_buffers_callback (CoglFramebuffer *framebuffer,
                                                unsigned int id);
 
+/**
+ * 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);
 
 typedef struct _CoglOnscreen CoglOnscreen;
 #define COGL_ONSCREEN(X) ((CoglOnscreen *)(X))

doc/reference/cogl-2.0-experimental/cogl-2.0-experimental-sections.txt

@@ -332,6 +332,7 @@ cogl_framebuffer_swap_buffers
 cogl_framebuffer_swap_region
 cogl_framebuffer_add_swap_buffers_callback
 cogl_framebuffer_remove_swap_buffers_callback
+cogl_framebuffer_finish
 
 <SUBSECTION>
 cogl_get_draw_framebuffer