CoglFramebuffer: The Framebuffer Interface

CoglFramebuffer: The Framebuffer Interface — A common interface for manipulating framebuffers

Synopsis

                    CoglFramebuffer;
#define             COGL_FRAMEBUFFER                    (X)
#define             cogl_framebuffer_allocate
#define             cogl_framebuffer_get_width
#define             cogl_framebuffer_get_height
#define             cogl_framebuffer_set_viewport
#define             cogl_framebuffer_get_viewport_x
#define             cogl_framebuffer_get_viewport_y
#define             cogl_framebuffer_get_viewport_width
#define             cogl_framebuffer_get_viewport_height
#define             cogl_framebuffer_get_viewport4fv
#define             cogl_framebuffer_get_red_bits
#define             cogl_framebuffer_get_green_bits
#define             cogl_framebuffer_get_blue_bits
#define             cogl_framebuffer_get_color_mask
#define             cogl_framebuffer_set_color_mask
#define             cogl_framebuffer_get_context
#define             cogl_framebuffer_clear
#define             cogl_framebuffer_clear4f
#define             cogl_framebuffer_swap_buffers
#define             cogl_framebuffer_swap_region
#define             cogl_framebuffer_add_swap_buffers_callback
#define             cogl_framebuffer_remove_swap_buffers_callback

#define             cogl_get_draw_framebuffer
void                cogl_set_framebuffer                (CoglFramebuffer *buffer);
void                cogl_push_framebuffer               (CoglFramebuffer *buffer);
void                cogl_pop_framebuffer                (void);

Description

Framebuffers are a collection of buffers that can be rendered too. A framebuffer may be comprised of one or more color buffers, an optional depth buffer and an optional stencil buffer. Other configuration parameters are associated with framebuffers too such as whether the framebuffer supports multi-sampling (an anti-aliasing technique) or dithering.

There are two kinds of framebuffer in Cogl, CoglOnscreen framebuffers and CoglOffscreen framebuffers. As the names imply offscreen framebuffers are for rendering something offscreen (perhaps to a texture which is bound as one of the color buffers). The exact semantics of onscreen framebuffers depends on the window system backend that you are using, but typically you can expect rendering to a CoglOnscreen framebuffer will be immediately visible to the user.

If you want to create a new framebuffer then you should start by looking at the CoglOnscreen and CoglOffscreen constructor functions, such as cogl_offscreen_new_to_texture() or cogl_onscreen_new(). The CoglFramebuffer interface deals with all aspects that are common between those two types of framebuffer.

Setup of a new CoglFramebuffer happens in two stages. There is a configuration stage where you specify all the options and ancillary buffers you want associated with your framebuffer and then when you are happy with the configuration you can "allocate" the framebuffer using cogl_framebuffer_allocate(). Technically explicitly calling cogl_framebuffer_allocate() is optional for convenience and the framebuffer will automatically be allocated when you first try to draw to it, but if you do the allocation manually then you can also catch any possible errors that may arise from your configuration.

Details

CoglFramebuffer

typedef struct _CoglFramebuffer CoglFramebuffer;

COGL_FRAMEBUFFER()

#define COGL_FRAMEBUFFER(X) ((CoglFramebuffer *)(X))

cogl_framebuffer_allocate

#define cogl_framebuffer_allocate cogl_framebuffer_allocate_EXP

cogl_framebuffer_get_width

#define cogl_framebuffer_get_width cogl_framebuffer_get_width_EXP

cogl_framebuffer_get_height

#define cogl_framebuffer_get_height cogl_framebuffer_get_height_EXP

cogl_framebuffer_set_viewport

#define cogl_framebuffer_set_viewport cogl_framebuffer_set_viewport_EXP

cogl_framebuffer_get_viewport_x

#define cogl_framebuffer_get_viewport_x cogl_framebuffer_get_viewport_x_EXP

cogl_framebuffer_get_viewport_y

#define cogl_framebuffer_get_viewport_y cogl_framebuffer_get_viewport_y_EXP

cogl_framebuffer_get_viewport_width

#define cogl_framebuffer_get_viewport_width cogl_framebuffer_get_viewport_width_EXP

cogl_framebuffer_get_viewport_height

#define cogl_framebuffer_get_viewport_height cogl_framebuffer_get_viewport_height_EXP

cogl_framebuffer_get_viewport4fv

#define cogl_framebuffer_get_viewport4fv cogl_framebuffer_get_viewport4fv_EXP

cogl_framebuffer_get_red_bits

#define cogl_framebuffer_get_red_bits cogl_framebuffer_get_red_bits_EXP

Retrieves the number of red bits of framebuffer

framebuffer :

a pointer to a CoglFramebuffer

Returns :

the number of bits

Since 1.8

Stability Level: Unstable


cogl_framebuffer_get_green_bits

#define cogl_framebuffer_get_green_bits cogl_framebuffer_get_green_bits_EXP

Retrieves the number of green bits of framebuffer

framebuffer :

a pointer to a CoglFramebuffer

Returns :

the number of bits

Since 1.8

Stability Level: Unstable


cogl_framebuffer_get_blue_bits

#define cogl_framebuffer_get_blue_bits cogl_framebuffer_get_blue_bits_EXP

Retrieves the number of blue bits of framebuffer

framebuffer :

a pointer to a CoglFramebuffer

Returns :

the number of bits

Since 1.8

Stability Level: Unstable


cogl_framebuffer_get_color_mask

#define cogl_framebuffer_get_color_mask cogl_framebuffer_get_color_mask_EXP

Gets the current CoglColorMask of which channels would be written to the current framebuffer. Each bit set in the mask means that the corresponding color would be written.

framebuffer :

a pointer to a CoglFramebuffer

Returns :

A CoglColorMask

Since 1.8

Stability Level: Unstable


cogl_framebuffer_set_color_mask

#define cogl_framebuffer_set_color_mask cogl_framebuffer_set_color_mask_EXP

Defines a bit mask of which color channels should be written to the given framebuffer. If a bit is set in color_mask that means that color will be written.

framebuffer :

a pointer to a CoglFramebuffer

color_mask :

A CoglColorMask of which color channels to write to the current framebuffer.

Since 1.8

Stability Level: Unstable


cogl_framebuffer_get_context

#define cogl_framebuffer_get_context cogl_framebuffer_get_context_EXP

cogl_framebuffer_clear

#define cogl_framebuffer_clear cogl_framebuffer_clear_EXP

Clears all the auxiliary buffers identified in the buffers mask, and if that includes the color buffer then the specified color is used.

framebuffer :

A CoglFramebuffer

buffers :

A mask of CoglBufferBit's identifying which auxiliary buffers to clear

color :

The color to clear the color buffer too if specified in buffers.

Since 1.8

Stability Level: Unstable


cogl_framebuffer_clear4f

#define cogl_framebuffer_clear4f cogl_framebuffer_clear4f_EXP

Clears all the auxiliary buffers identified in the buffers mask, and if that includes the color buffer then the specified color is used.

framebuffer :

A CoglFramebuffer

buffers :

A mask of CoglBufferBit's identifying which auxiliary buffers to clear

red :

The red component of color to clear the color buffer too if specified in buffers.

green :

The green component of color to clear the color buffer too if specified in buffers.

blue :

The blue component of color to clear the color buffer too if specified in buffers.

alpha :

The alpha component of color to clear the color buffer too if specified in buffers.

Since 1.8

Stability Level: Unstable


cogl_framebuffer_swap_buffers

#define cogl_framebuffer_swap_buffers cogl_framebuffer_swap_buffers_EXP

cogl_framebuffer_swap_region

#define cogl_framebuffer_swap_region cogl_framebuffer_swap_region_EXP

cogl_framebuffer_add_swap_buffers_callback

#define             cogl_framebuffer_add_swap_buffers_callback

cogl_framebuffer_remove_swap_buffers_callback

#define             cogl_framebuffer_remove_swap_buffers_callback

cogl_get_draw_framebuffer

#define cogl_get_draw_framebuffer cogl_get_draw_framebuffer_EXP

cogl_set_framebuffer ()

void                cogl_set_framebuffer                (CoglFramebuffer *buffer);

This redirects all subsequent drawing to the specified framebuffer. This can either be an offscreen buffer created with cogl_offscreen_new_to_texture() or in the future it may be an onscreen framebuffers too.

buffer :

A CoglFramebuffer object, either onscreen or offscreen.

Since 1.2


cogl_push_framebuffer ()

void                cogl_push_framebuffer               (CoglFramebuffer *buffer);

Redirects all subsequent drawing to the specified framebuffer. This can either be an offscreen buffer created with cogl_offscreen_new_to_texture() or in the future it may be an onscreen framebuffer too.

You should understand that a framebuffer owns the following state:

  • The projection matrix
  • The modelview matrix stack
  • The viewport
  • The clip stack

So these items will automatically be saved and restored when you push and pop between different framebuffers.

Also remember a newly allocated framebuffer will have an identity matrix for the projection and modelview matrices which gives you a coordinate space like OpenGL with (-1, -1) corresponding to the top left of the viewport, (1, 1) corresponding to the bottom right and +z coming out towards the viewer.

If you want to set up a coordinate space like Clutter does with (0, 0) corresponding to the top left and (framebuffer_width, framebuffer_height) corresponding to the bottom right you can do so like this:

static void
setup_viewport (unsigned int width,
                unsigned int height,
                float fovy,
                float aspect,
                float z_near,
                float z_far)
{
  float z_camera;
  CoglMatrix projection_matrix;
  CoglMatrix mv_matrix;

  cogl_set_viewport (0, 0, width, height);
  cogl_perspective (fovy, aspect, z_near, z_far);

  cogl_get_projection_matrix (&projection_matrix);
  z_camera = 0.5 * projection_matrix.xx;

  cogl_matrix_init_identity (&mv_matrix);
  cogl_matrix_translate (&mv_matrix, -0.5f, -0.5f, -z_camera);
  cogl_matrix_scale (&mv_matrix, 1.0f / width, -1.0f / height, 1.0f / width);
  cogl_matrix_translate (&mv_matrix, 0.0f, -1.0 * height, 0.0f);
  cogl_set_modelview_matrix (&mv_matrix);
}

static void
my_init_framebuffer (ClutterStage *stage,
                     CoglFramebuffer *framebuffer,
                     unsigned int framebuffer_width,
                     unsigned int framebuffer_height)
{
  ClutterPerspective perspective;

  clutter_stage_get_perspective (stage, &perspective);

  cogl_push_framebuffer (framebuffer);
  setup_viewport (framebuffer_width,
                  framebuffer_height,
                  perspective.fovy,
                  perspective.aspect,
                  perspective.z_near,
                  perspective.z_far);
}

The previous framebuffer can be restored by calling cogl_pop_framebuffer()

buffer :

A CoglFramebuffer object, either onscreen or offscreen.

Since 1.2


cogl_pop_framebuffer ()

void                cogl_pop_framebuffer                (void);

Restores the framebuffer that was previously at the top of the stack. All subsequent drawing will be redirected to this framebuffer.

Since 1.2