From 869a2b4167cb56131a6c89a2f6b043001891aadd Mon Sep 17 00:00:00 2001 From: Robert Bragg Date: Thu, 30 Apr 2009 22:19:43 +0100 Subject: [PATCH] [cogl-offscreen] Cleans up the cogl offscreen API and adds documentation There were several functions I believe no one is currently using that were only implemented in the GL backend (cogl_offscreen_blit_region and cogl_offscreen_blit) that have simply been removed so we have a chance to think about design later with a real use case. There was one nonsense function (cogl_offscreen_new_multisample) that sounded exciting but in all cases it just returned COGL_INVALID_HANDLE (though at least for GL it checked for multisampling support first!?) it has also been removed. The MASK draw buffer type has been removed. If we want to expose color masking later then I think it at least would be nicer to have the mask be a property that can be set on any draw buffer. The cogl_draw_buffer and cogl_{push,pop}_draw_buffer function prototypes have been moved up into cogl.h since they are for managing global Cogl state and not for modifying or creating the actual offscreen buffers. This also documents the API so for example desiphering the semantics of cogl_offscreen_new_to_texture() should be a bit easier now. --- cogl-offscreen.h | 99 ++++++------------------ cogl-types.h | 4 +- cogl.h.in | 29 +++++++ common/cogl-util.c | 1 - doc/reference/cogl/cogl-sections.txt | 4 +- gl/cogl-fbo.c | 109 ++------------------------- gles/cogl-fbo.c | 91 ++-------------------- gles/cogl-texture.c | 5 -- 8 files changed, 69 insertions(+), 273 deletions(-) diff --git a/cogl-offscreen.h b/cogl-offscreen.h index 6be6cf0f2..ca4edb49c 100644 --- a/cogl-offscreen.h +++ b/cogl-offscreen.h @@ -35,43 +35,47 @@ G_BEGIN_DECLS /** * SECTION:cogl-offscreen * @short_description: Fuctions for creating and manipulating offscreen - * frame buffer objects + * frame buffer objects * - * COGL allows creating and operating on FBOs (Framebuffer Objects). + * Cogl allows creating and operating on offscreen render targets. */ /* Offscreen api */ /** * cogl_offscreen_new_to_texture: - * @texhandle: + * @handle: A CoglHandle for a Cogl texture * - * Returns: + * This creates an offscreen buffer object using the given texture as the + * primary color buffer. It doesn't just initialize the contents of the + * offscreen buffer with the texture; they are tightly bound so that + * drawing to the offscreen buffer effectivly updates the contents of the + * given texture. You don't need to destroy the offscreen buffer before + * you can use the texture again. + * + * Note: This does not work with sliced Cogl textures. + * + * Returns: a CoglHandle for the new offscreen buffer or COGL_INVALID_HANDLE + * if it wasn't possible to create the buffer. */ CoglHandle cogl_offscreen_new_to_texture (CoglHandle texhandle); -/** - * cogl_offscreen_new_multisample: - * - * - * Returns: - */ -CoglHandle cogl_offscreen_new_multisample (void); - /** * cogl_offscreen_ref: - * @handle: + * @handle: A CoglHandle for an offscreen buffer * - * Returns: + * Increments the reference count on the offscreen buffer. + * + * Returns: For convenience it returns the given CoglHandle */ CoglHandle cogl_offscreen_ref (CoglHandle handle); /** * cogl_is_offscreen: - * @handle: A CoglHandle + * @handle: A CoglHandle for an offscreen buffer * - * Gets whether the given handle references an existing offscreen - * buffer object. + * Gets whether the given handle references an existing offscreen buffer + * object. * * Returns: %TRUE if the handle references an offscreen buffer, * %FALSE otherwise @@ -80,68 +84,13 @@ gboolean cogl_is_offscreen (CoglHandle handle); /** * cogl_offscreen_unref: - * @handle: + * @handle: A CoglHandle for an offscreen buffer * + * Decreases the reference count for the offscreen buffer and frees it when + * the count reaches 0. */ void cogl_offscreen_unref (CoglHandle handle); -/** - * cogl_offscreen_blit: - * @src_buffer: - * @dst_buffer: - * - */ -void cogl_offscreen_blit (CoglHandle src_buffer, - CoglHandle dst_buffer); - -/** - * cogl_offscreen_blit_region: - * @src_buffer: - * @dst_buffer: - * @src_x: - * @src_y: - * @src_w: - * @src_h: - * @dst_x: - * @dst_y: - * @dst_w: - * @dst_h: - * - */ -void cogl_offscreen_blit_region (CoglHandle src_buffer, - CoglHandle dst_buffer, - gint src_x, - gint src_y, - gint src_w, - gint src_h, - gint dst_x, - gint dst_y, - gint dst_w, - gint dst_h); - -/** - * cogl_draw_buffer: - * @target: - * @offscreen: - * - */ -void cogl_draw_buffer (CoglBufferTarget target, - CoglHandle offscreen); - -/** - * cogl_push_draw_buffer: - * - * Save cogl_draw_buffer() state. - */ -void cogl_push_draw_buffer (void); - -/** - * cogl_pop_draw_buffer: - * - * Restore cogl_draw_buffer() state. - */ -void cogl_pop_draw_buffer (void); - G_END_DECLS #endif /* __COGL_OFFSCREEN_H__ */ diff --git a/cogl-types.h b/cogl-types.h index b2c082bc8..a4ecd4193 100644 --- a/cogl-types.h +++ b/cogl-types.h @@ -228,7 +228,6 @@ GType cogl_feature_flags_get_type (void) G_GNUC_CONST; /** * CoglBufferTarget: * @COGL_WINDOW_BUFFER: FIXME - * @COGL_MASK_BUFFER: FIXME * @COGL_OFFSCREEN_BUFFER: FIXME * * Target flags for FBOs. @@ -238,8 +237,7 @@ GType cogl_feature_flags_get_type (void) G_GNUC_CONST; typedef enum { COGL_WINDOW_BUFFER = (1 << 1), - COGL_MASK_BUFFER = (1 << 2), - COGL_OFFSCREEN_BUFFER = (1 << 3) + COGL_OFFSCREEN_BUFFER = (1 << 2) } CoglBufferTarget; #define COGL_TYPE_BUFFER_TARGET (cogl_buffer_target_get_type ()) diff --git a/cogl.h.in b/cogl.h.in index 2422cd1da..594fc77ca 100644 --- a/cogl.h.in +++ b/cogl.h.in @@ -578,6 +578,35 @@ void cogl_clip_stack_save (void); */ void cogl_clip_stack_restore (void); +/** + * cogl_set_draw_buffer: + * @target: A #CoglBufferTarget that specifies what kind of draw buffer you + * are setting as the render target. + * @offscreen: If you are setting a draw buffer of type COGL_OFFSCREEN_BUFFER + * then this is a CoglHandle for the offscreen buffer. + * + * This redirects all subsequent drawing to the specified draw buffer. This + * can either be an offscreen buffer created with + * cogl_offscreen_new_to_texture () or you can revert to your original + * on screen window buffer. + */ +void cogl_set_draw_buffer (CoglBufferTarget target, + CoglHandle offscreen); + +/** + * cogl_push_draw_buffer: + * + * Save cogl_set_draw_buffer() state. + */ +void cogl_push_draw_buffer (void); + +/** + * cogl_pop_draw_buffer: + * + * Restore cogl_set_draw_buffer() state. + */ +void cogl_pop_draw_buffer (void); + /** * cogl_flush_gl_state: * @flags: flags controlling what is flushed; currently unused, pass in 0 diff --git a/common/cogl-util.c b/common/cogl-util.c index 1eb0db10e..d71b9ffd8 100644 --- a/common/cogl-util.c +++ b/common/cogl-util.c @@ -179,7 +179,6 @@ cogl_buffer_target_get_type (void) { static const GFlagsValue values[] = { { COGL_WINDOW_BUFFER, "COGL_WINDOW_BUFFER", "window-buffer" }, - { COGL_MASK_BUFFER, "COGL_MASK_BUFFER", "mask-buffer" }, { COGL_OFFSCREEN_BUFFER, "COGL_OFFSCREEN_BUFFER", "offscreen-buffer" }, { 0, NULL, NULL } }; diff --git a/doc/reference/cogl/cogl-sections.txt b/doc/reference/cogl/cogl-sections.txt index bc9d6afc1..ff8df1cbc 100644 --- a/doc/reference/cogl/cogl-sections.txt +++ b/doc/reference/cogl/cogl-sections.txt @@ -173,9 +173,7 @@ cogl_offscreen_new_to_texture cogl_offscreen_ref cogl_offscreen_unref cogl_is_offscreen -cogl_offscreen_blit -cogl_offscreen_blit_region -cogl_draw_buffer +cogl_set_draw_buffer cogl_offscreen_new_multisample diff --git a/gl/cogl-fbo.c b/gl/cogl-fbo.c index a5f6e22fd..db99e6ace 100644 --- a/gl/cogl-fbo.c +++ b/gl/cogl-fbo.c @@ -148,15 +148,6 @@ cogl_offscreen_new_to_texture (CoglHandle texhandle) return _cogl_offscreen_handle_new (fbo); } -CoglHandle -cogl_offscreen_new_multisample () -{ - if (!cogl_features_available (COGL_FEATURE_OFFSCREEN_MULTISAMPLE)) - return COGL_INVALID_HANDLE; - - return COGL_INVALID_HANDLE; -} - static void _cogl_offscreen_free (CoglFbo *fbo) { @@ -171,75 +162,7 @@ _cogl_offscreen_free (CoglFbo *fbo) } void -cogl_offscreen_blit_region (CoglHandle src_buffer, - CoglHandle dst_buffer, - int src_x, - int src_y, - int src_w, - int src_h, - int dst_x, - int dst_y, - int dst_w, - int dst_h) -{ - CoglFbo *src_fbo; - CoglFbo *dst_fbo; - - _COGL_GET_CONTEXT (ctx, NO_RETVAL); - - if (!cogl_features_available (COGL_FEATURE_OFFSCREEN_BLIT)) - return; - - /* Make sure these are valid fbo handles */ - if (!cogl_is_offscreen (src_buffer)) - return; - - if (!cogl_is_offscreen (dst_buffer)) - return; - - src_fbo = _cogl_offscreen_pointer_from_handle (src_buffer); - dst_fbo = _cogl_offscreen_pointer_from_handle (dst_buffer); - - /* Copy (and scale) a region from one to another framebuffer */ - GE( glBindFramebufferEXT (GL_READ_FRAMEBUFFER_EXT, src_fbo->gl_handle) ); - GE( glBindFramebufferEXT (GL_DRAW_FRAMEBUFFER_EXT, dst_fbo->gl_handle) ); - GE( glBlitFramebufferEXT (src_x, src_y, src_x + src_w, src_y + src_h, - dst_x, dst_y, dst_x + dst_w, dst_y + dst_h, - GL_COLOR_BUFFER_BIT, GL_LINEAR) ); -} - -void -cogl_offscreen_blit (CoglHandle src_buffer, - CoglHandle dst_buffer) -{ - CoglFbo *src_fbo; - CoglFbo *dst_fbo; - - _COGL_GET_CONTEXT (ctx, NO_RETVAL); - - if (!cogl_features_available (COGL_FEATURE_OFFSCREEN_BLIT)) - return; - - /* Make sure these are valid fbo handles */ - if (!cogl_is_offscreen (src_buffer)) - return; - - if (!cogl_is_offscreen (dst_buffer)) - return; - - src_fbo = _cogl_offscreen_pointer_from_handle (src_buffer); - dst_fbo = _cogl_offscreen_pointer_from_handle (dst_buffer); - - /* Copy (and scale) whole image from one to another framebuffer */ - GE( glBindFramebufferEXT (GL_READ_FRAMEBUFFER_EXT, src_fbo->gl_handle) ); - GE( glBindFramebufferEXT (GL_DRAW_FRAMEBUFFER_EXT, dst_fbo->gl_handle) ); - GE( glBlitFramebufferEXT (0, 0, src_fbo->width, src_fbo->height, - 0, 0, dst_fbo->width, dst_fbo->height, - GL_COLOR_BUFFER_BIT, GL_LINEAR) ); -} - -void -cogl_draw_buffer (CoglBufferTarget target, CoglHandle offscreen) +cogl_set_draw_buffer (CoglBufferTarget target, CoglHandle offscreen) { CoglFbo *fbo = NULL; CoglDrawBufferState *draw_buffer; @@ -301,10 +224,8 @@ cogl_draw_buffer (CoglBufferTarget target, CoglHandle offscreen) GE( glEnable (GL_SCISSOR_TEST) ); GE( glClear (GL_COLOR_BUFFER_BIT) ); GE( glPopAttrib () ); - } - else if ((target & COGL_WINDOW_BUFFER) || - (target & COGL_MASK_BUFFER)) + else if (target & COGL_WINDOW_BUFFER) { /* Check current draw buffer target */ if (draw_buffer->target == COGL_OFFSCREEN_BUFFER) @@ -322,23 +243,6 @@ cogl_draw_buffer (CoglBufferTarget target, CoglHandle offscreen) /* Bind window framebuffer object */ GE( glBindFramebufferEXT (GL_FRAMEBUFFER_EXT, 0) ); - - - if (target == COGL_WINDOW_BUFFER) - { - /* Draw to RGB channels */ - GE( glColorMask (GL_TRUE, GL_TRUE, GL_TRUE, GL_FALSE) ); - } - else if (target == COGL_MASK_BUFFER) - { - /* Draw only to ALPHA channel */ - GE( glColorMask (GL_FALSE, GL_FALSE, GL_FALSE, GL_TRUE) ); - } - else - { - /* Draw to all channels */ - GE( glColorMask (GL_TRUE, GL_TRUE, GL_TRUE, GL_TRUE) ); - } } /* Store new target */ @@ -389,14 +293,14 @@ cogl_pop_draw_buffer(void) to_pop = ctx->draw_buffer_stack->data; to_restore = ctx->draw_buffer_stack->next->data; - /* the logic in cogl_draw_buffer() only works if + /* the logic in cogl_set_draw_buffer() only works if * to_pop is still on top of the stack, because - * cogl_draw_buffer() needs to know the previous + * cogl_set_draw_buffer() needs to know the previous * state. */ - cogl_draw_buffer (to_restore->target, to_restore->offscreen); + cogl_set_draw_buffer (to_restore->target, to_restore->offscreen); - /* cogl_draw_buffer() should have set top of stack + /* cogl_set_draw_buffer() should have set top of stack * to to_restore */ g_assert (to_restore->target == to_pop->target); @@ -409,3 +313,4 @@ cogl_pop_draw_buffer(void) g_slice_free (CoglDrawBufferState, to_pop); } + diff --git a/gles/cogl-fbo.c b/gles/cogl-fbo.c index 2b8aa46fa..08b6cff13 100644 --- a/gles/cogl-fbo.c +++ b/gles/cogl-fbo.c @@ -130,15 +130,6 @@ cogl_offscreen_new_to_texture (CoglHandle texhandle) return _cogl_offscreen_handle_new (fbo); } -CoglHandle -cogl_offscreen_new_multisample () -{ - if (!cogl_features_available (COGL_FEATURE_OFFSCREEN_MULTISAMPLE)) - return COGL_INVALID_HANDLE; - - return COGL_INVALID_HANDLE; -} - static void _cogl_offscreen_free (CoglFbo *fbo) { @@ -153,31 +144,7 @@ _cogl_offscreen_free (CoglFbo *fbo) } void -cogl_offscreen_blit_region (CoglHandle src_buffer, - CoglHandle dst_buffer, - int src_x, - int src_y, - int src_w, - int src_h, - int dst_x, - int dst_y, - int dst_w, - int dst_h) -{ - /* Not supported on GLES */ - return; -} - -void -cogl_offscreen_blit (CoglHandle src_buffer, - CoglHandle dst_buffer) -{ - /* Not supported on GLES */ - return; -} - -void -cogl_draw_buffer (CoglBufferTarget target, CoglHandle offscreen) +cogl_set_draw_buffer (CoglBufferTarget target, CoglHandle offscreen) { CoglFbo *fbo = NULL; CoglDrawBufferState *draw_buffer; @@ -249,8 +216,7 @@ cogl_draw_buffer (CoglBufferTarget target, CoglHandle offscreen) scissor_box[2], scissor_box[3]); } - else if ((target & COGL_WINDOW_BUFFER) || - (target & COGL_MASK_BUFFER)) + else if (target & COGL_WINDOW_BUFFER) { /* Check current draw buffer target */ if (draw_buffer->target == COGL_OFFSCREEN_BUFFER) @@ -269,23 +235,6 @@ cogl_draw_buffer (CoglBufferTarget target, CoglHandle offscreen) /* Bind window framebuffer object */ GE( glBindFramebuffer (GL_FRAMEBUFFER, 0) ); - - - if (target == COGL_WINDOW_BUFFER) - { - /* Draw to RGB channels */ - GE( glColorMask (GL_TRUE, GL_TRUE, GL_TRUE, GL_TRUE) ); - } - else if (target == COGL_MASK_BUFFER) - { - /* Draw only to ALPHA channel */ - GE( glColorMask (GL_FALSE, GL_FALSE, GL_FALSE, GL_TRUE) ); - } - else - { - /* Draw to all channels */ - GE( glColorMask (GL_TRUE, GL_TRUE, GL_TRUE, GL_TRUE) ); - } } /* Store new target */ @@ -336,14 +285,14 @@ cogl_pop_draw_buffer(void) to_pop = ctx->draw_buffer_stack->data; to_restore = ctx->draw_buffer_stack->next->data; - /* the logic in cogl_draw_buffer() only works if + /* the logic in cogl_set_draw_buffer() only works if * to_pop is still on top of the stack, because - * cogl_draw_buffer() needs to know the previous + * cogl_set_draw_buffer() needs to know the previous * state. */ - cogl_draw_buffer (to_restore->target, to_restore->offscreen); + cogl_set_draw_buffer (to_restore->target, to_restore->offscreen); - /* cogl_draw_buffer() should have set top of stack + /* cogl_set_draw_buffer() should have set top of stack * to to_restore */ g_assert (to_restore->target == to_pop->target); @@ -373,12 +322,6 @@ cogl_offscreen_new_to_texture (CoglHandle texhandle) return COGL_INVALID_HANDLE; } -CoglHandle -cogl_offscreen_new_multisample () -{ - return COGL_INVALID_HANDLE; -} - CoglHandle cogl_offscreen_ref (CoglHandle handle) { @@ -391,27 +334,7 @@ cogl_offscreen_unref (CoglHandle handle) } void -cogl_offscreen_blit_region (CoglHandle src_buffer, - CoglHandle dst_buffer, - int src_x, - int src_y, - int src_w, - int src_h, - int dst_x, - int dst_y, - int dst_w, - int dst_h) -{ -} - -void -cogl_offscreen_blit (CoglHandle src_buffer, - CoglHandle dst_buffer) -{ -} - -void -cogl_draw_buffer (CoglBufferTarget target, CoglHandle offscreen) +cogl_set_draw_buffer (CoglBufferTarget target, CoglHandle offscreen) { } diff --git a/gles/cogl-texture.c b/gles/cogl-texture.c index 959332919..0954798d9 100644 --- a/gles/cogl-texture.c +++ b/gles/cogl-texture.c @@ -483,9 +483,6 @@ _cogl_texture_download_from_gl (CoglTexture *tex, _cogl_current_matrix_push (); _cogl_current_matrix_identity (); - /* Draw to all channels */ - cogl_draw_buffer (COGL_WINDOW_BUFFER | COGL_MASK_BUFFER, 0); - /* Direct copy operation */ if (ctx->texture_download_material == COGL_INVALID_HANDLE) @@ -582,8 +579,6 @@ _cogl_texture_download_from_gl (CoglTexture *tex, _cogl_set_current_matrix (COGL_MATRIX_MODELVIEW); _cogl_current_matrix_pop (); - cogl_draw_buffer (COGL_WINDOW_BUFFER, 0); - return TRUE; }