[cogl/wip/rib/master-next: 6/44] framebuffer: Adds experimental _finish() API

[Robert Bragg <rbragg src gnome org>]

commit 6b23c116e908eea7bafada078b32d079d1185600
Author: Robert Bragg <robert linux intel com>
Date:   Wed Sep 28 15:19:38 2011 +0100

    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                            |    7 +++++++
 cogl/cogl-framebuffer.h                            |   19 +++++++++++++++++++
 .../cogl-2.0-experimental-sections.txt             |    1 +
 3 files changed, 27 insertions(+), 0 deletions(-)
---
diff --git a/cogl/cogl-framebuffer.c b/cogl/cogl-framebuffer.c
index 29d4eb5..bcaa446 100644
--- a/cogl/cogl-framebuffer.c
+++ b/cogl/cogl-framebuffer.c
@@ -2019,6 +2019,13 @@ cogl_framebuffer_remove_swap_buffers_callback (CoglFramebuffer *framebuffer,
 }
 
 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)
 {
diff --git a/cogl/cogl-framebuffer.h b/cogl/cogl-framebuffer.h
index ad4d1e4..e168e6d 100644
--- a/cogl/cogl-framebuffer.h
+++ b/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))
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 571c84b..c3a9679 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
@@ -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