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

[Robert Bragg <rbragg src gnome org>]

commit fe16695e4a59bc83286836b5518f94d2885870bc
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 5cb8042..8305313 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 4fff834..d63ef15 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