From 6d9498da7cbe180ddc4b68ae3a48985631db46a0 Mon Sep 17 00:00:00 2001 From: Robert Bragg Date: Mon, 29 Jun 2009 17:10:34 +0100 Subject: [PATCH] Adds a cogl_flush() to give developers breaking into raw GL a fighting chance This function should only need to be called in exceptional circumstances since Cogl can normally determine internally when a flush is necessary. As an optimization Cogl drawing functions may batch up primitives internally, so if you are trying to use raw GL outside of Cogl you stand a better chance of being successful if you ask Cogl to flush any batched geometry before making your state changes. cogl_flush() ensures that the underlying driver is issued all the commands necessary to draw the batched primitives. It provides no guarantees about when the driver will complete the rendering. This provides no guarantees about the GL state upon returning and to avoid confusing Cogl you should aim to restore any changes you make before resuming use of Cogl. If you are making state changes with the intention of affecting Cogl drawing primitives you are 100% on your own since you stand a good chance of conflicting with Cogl internals. For example clutter-gst which currently uses direct GL calls to bind ARBfp programs will very likely break when Cogl starts to use ARBfb programs internally for the material API, but for now it can use cogl_flush() to at least ensure that the ARBfp program isn't applied to additional primitives. This does not provide a robust generalized solution supporting safe use of raw GL, its use is very much discouraged. --- clutter/clutter-main.c | 2 +- clutter/cogl/cogl.h.in | 42 ++++++++++++++++++++++----------- clutter/cogl/common/cogl.c | 4 ++-- clutter/eglnative/clutter-backend-egl.c | 2 +- clutter/eglx/clutter-backend-egl.c | 2 +- clutter/fruity/clutter-backend-fruity.c | 2 +- clutter/glx/clutter-backend-glx.c | 2 +- clutter/osx/clutter-stage-osx.c | 2 +- clutter/sdl/clutter-backend-sdl.c | 2 +- clutter/win32/clutter-backend-win32.c | 2 +- doc/reference/cogl/cogl-sections.txt | 3 +++ 11 files changed, 41 insertions(+), 24 deletions(-) diff --git a/clutter/clutter-main.c b/clutter/clutter-main.c index ae66792..84602f1 100644 --- a/clutter/clutter-main.c +++ b/clutter/clutter-main.c @@ -410,7 +410,7 @@ _clutter_do_pick (ClutterStage *stage, glGetIntegerv(GL_VIEWPORT, viewport); /* Make sure Cogl flushes any batched geometry to the GPU driver */ - _cogl_flush (); + cogl_flush (); /* Read the color of the screen co-ords pixel */ glReadPixels (x, viewport[3] - y -1, 1, 1, GL_RGBA, GL_UNSIGNED_BYTE, pixel); diff --git a/clutter/cogl/cogl.h.in b/clutter/cogl/cogl.h.in index cbd70f0..295cf0d 100644 --- a/clutter/cogl/cogl.h.in +++ b/clutter/cogl/cogl.h.in @@ -724,6 +724,34 @@ void cogl_read_pixels (int x, CoglPixelFormat format, guint8 *pixels); +/** + * cogl_flush: + * + * This function should only need to be called in exceptional circumstances. + * + * As an optimization Cogl drawing functions may batch up primitives + * internally, so if you are trying to use raw GL outside of Cogl you stand a + * better chance of being successful if you ask Cogl to flush any batched + * geometry before making your state changes. + * + * It only ensure that the underlying driver is issued all the commands + * necessary to draw the batched primitives. It provides no guarantees about + * when the driver will complete the rendering. + * + * This provides no guarantees about the GL state upon returning and to avoid + * confusing Cogl you should aim to restore any changes you make before + * resuming use of Cogl. + * + * If you are making state changes with the intention of affecting Cogl drawing + * primitives you are 100% on your own since you stand a good chance of + * conflicting with Cogl internals. For example clutter-gst which currently + * uses direct GL calls to bind ARBfp programs will very likely break when Cogl + * starts to use ARBfb programs itself for the material API. + * + * Since: 1.0 + */ +void cogl_flush (void); + /* * Internal API available only to Clutter. @@ -760,20 +788,6 @@ void cogl_flush_gl_state (int flags); /* private */ void _cogl_set_indirect_context (gboolean indirect); -/* private - * - * cogl_flush: - * - * As an optimization Cogl drawing functions may batch up primitives - * internally, so you need to call _cogl_flush to ensure that the - * drawing operations you have submitted for the current frame get - * flushed through to the driver and GPU. - * - * This must be called before issuing a swap buffers. - */ -void _cogl_flush (void); - - G_END_DECLS #undef __COGL_H_INSIDE__ diff --git a/clutter/cogl/common/cogl.c b/clutter/cogl/common/cogl.c index 29366b3..81a0312 100644 --- a/clutter/cogl/common/cogl.c +++ b/clutter/cogl/common/cogl.c @@ -708,7 +708,7 @@ cogl_flush_gl_state (int flags) #endif void -_cogl_flush (void) +cogl_flush (void) { _cogl_journal_flush (); } @@ -748,7 +748,7 @@ cogl_read_pixels (int x, /* make sure any batched primitives get emitted to the GL driver before * issuing our read pixels... */ - _cogl_flush (); + cogl_flush (); glReadPixels (x, y, width, height, GL_RGBA, GL_UNSIGNED_BYTE, pixels); diff --git a/clutter/eglnative/clutter-backend-egl.c b/clutter/eglnative/clutter-backend-egl.c index adaf3cb..e5f6c48 100644 --- a/clutter/eglnative/clutter-backend-egl.c +++ b/clutter/eglnative/clutter-backend-egl.c @@ -81,7 +81,7 @@ clutter_backend_egl_redraw (ClutterBackend *backend, eglWaitNative (EGL_CORE_NATIVE_ENGINE); clutter_actor_paint (CLUTTER_ACTOR (stage)); - _cogl_flush (); + cogl_flush (); eglWaitGL(); eglSwapBuffers (backend_egl->edpy, stage_egl->egl_surface); diff --git a/clutter/eglx/clutter-backend-egl.c b/clutter/eglx/clutter-backend-egl.c index af06f97..5a4057d 100644 --- a/clutter/eglx/clutter-backend-egl.c +++ b/clutter/eglx/clutter-backend-egl.c @@ -139,7 +139,7 @@ clutter_backend_egl_redraw (ClutterBackend *backend, /* this will cause the stage implementation to be painted as well */ clutter_actor_paint (CLUTTER_ACTOR (stage)); - _cogl_flush (); + cogl_flush (); /* Why this paint is done in backend as likely GL windowing system * specific calls, like swapping buffers. diff --git a/clutter/fruity/clutter-backend-fruity.c b/clutter/fruity/clutter-backend-fruity.c index 58c5e39..ecc005c 100644 --- a/clutter/fruity/clutter-backend-fruity.c +++ b/clutter/fruity/clutter-backend-fruity.c @@ -72,7 +72,7 @@ clutter_backend_egl_redraw (ClutterBackend *backend, eglWaitNative (EGL_CORE_NATIVE_ENGINE); clutter_actor_paint (CLUTTER_ACTOR (stage)); - _cogl_flush (); + cogl_flush (); eglWaitGL(); eglSwapBuffers (backend_egl->edpy, stage_egl->egl_surface); } diff --git a/clutter/glx/clutter-backend-glx.c b/clutter/glx/clutter-backend-glx.c index 140038f..51672be 100644 --- a/clutter/glx/clutter-backend-glx.c +++ b/clutter/glx/clutter-backend-glx.c @@ -498,7 +498,7 @@ clutter_backend_glx_redraw (ClutterBackend *backend, /* this will cause the stage implementation to be painted */ clutter_actor_paint (CLUTTER_ACTOR (stage)); - _cogl_flush (); + cogl_flush (); if (stage_x11->xwin != None) { diff --git a/clutter/osx/clutter-stage-osx.c b/clutter/osx/clutter-stage-osx.c index 962d4a7..ad3e3c5 100644 --- a/clutter/osx/clutter-stage-osx.c +++ b/clutter/osx/clutter-stage-osx.c @@ -128,7 +128,7 @@ clutter_stage_osx_state_update (ClutterStageOSX *self, - (void) drawRect: (NSRect) bounds { clutter_actor_paint (CLUTTER_ACTOR (self->stage_osx->wrapper)); - _cogl_flush (); + cogl_flush (); [[self openGLContext] flushBuffer]; } diff --git a/clutter/sdl/clutter-backend-sdl.c b/clutter/sdl/clutter-backend-sdl.c index 90c1167..146fdd0 100644 --- a/clutter/sdl/clutter-backend-sdl.c +++ b/clutter/sdl/clutter-backend-sdl.c @@ -68,7 +68,7 @@ clutter_backend_sdl_redraw (ClutterBackend *backend, ClutterStage *stage) { clutter_actor_paint (CLUTTER_ACTOR (stage)); - _cogl_flush (); + cogl_flush (); SDL_GL_SwapBuffers(); } diff --git a/clutter/win32/clutter-backend-win32.c b/clutter/win32/clutter-backend-win32.c index f1531a0..959bc53 100644 --- a/clutter/win32/clutter-backend-win32.c +++ b/clutter/win32/clutter-backend-win32.c @@ -297,7 +297,7 @@ clutter_backend_win32_redraw (ClutterBackend *backend, /* this will cause the stage implementation to be painted */ clutter_actor_paint (CLUTTER_ACTOR (stage)); - _cogl_flush (); + cogl_flush (); if (stage_win32->client_dc) SwapBuffers (stage_win32->client_dc); diff --git a/doc/reference/cogl/cogl-sections.txt b/doc/reference/cogl/cogl-sections.txt index c28ab52..f383e26 100644 --- a/doc/reference/cogl/cogl-sections.txt +++ b/doc/reference/cogl/cogl-sections.txt @@ -72,6 +72,9 @@ cogl_set_source_texture CoglReadPixelsFlags cogl_read_pixels + +cogl_flush + COGL_TYPE_ATTRIBUTE_TYPE COGL_TYPE_BUFFER_BIT -- 2.7.4