CoglFramebuffer: The Framebuffer Interface

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

Synopsis

                    CoglFramebuffer;
#define             COGL_FRAMEBUFFER                    (X)
gboolean            cogl_framebuffer_allocate           (CoglFramebuffer *framebuffer,
                                                         GError **error);
int                 cogl_framebuffer_get_width          (CoglFramebuffer *framebuffer);
int                 cogl_framebuffer_get_height         (CoglFramebuffer *framebuffer);
void                cogl_framebuffer_set_viewport       (CoglFramebuffer *framebuffer,
                                                         float x,
                                                         float y,
                                                         float width,
                                                         float height);
float               cogl_framebuffer_get_viewport_x     (CoglFramebuffer *framebuffer);
float               cogl_framebuffer_get_viewport_y     (CoglFramebuffer *framebuffer);
float               cogl_framebuffer_get_viewport_width (CoglFramebuffer *framebuffer);
float               cogl_framebuffer_get_viewport_height
                                                        (CoglFramebuffer *framebuffer);
void                cogl_framebuffer_get_viewport4fv    (CoglFramebuffer *framebuffer,
                                                         float *viewport);
int                 cogl_framebuffer_get_red_bits       (CoglFramebuffer *framebuffer);
int                 cogl_framebuffer_get_green_bits     (CoglFramebuffer *framebuffer);
int                 cogl_framebuffer_get_blue_bits      (CoglFramebuffer *framebuffer);
CoglColorMask       cogl_framebuffer_get_color_mask     (CoglFramebuffer *framebuffer);
void                cogl_framebuffer_set_color_mask     (CoglFramebuffer *framebuffer,
                                                         CoglColorMask color_mask);
CoglContext *       cogl_framebuffer_get_context        (CoglFramebuffer *framebuffer);
void                cogl_framebuffer_clear              (CoglFramebuffer *framebuffer,
                                                         unsigned long  buffers,
                                                         const CoglColor *color);
void                cogl_framebuffer_clear4f            (CoglFramebuffer *framebuffer,
                                                         unsigned long  buffers,
                                                         float red,
                                                         float green,
                                                         float blue,
                                                         float alpha);
void                cogl_framebuffer_swap_buffers       (CoglFramebuffer *framebuffer);
void                cogl_framebuffer_swap_region        (CoglFramebuffer *framebuffer,
                                                         const int *rectangles,
                                                         int n_rectangles);
unsigned int        cogl_framebuffer_add_swap_buffers_callback
                                                        (CoglFramebuffer *framebuffer,
                                                         CoglSwapBuffersNotify callback,
                                                         void *user_data);
void                cogl_framebuffer_remove_swap_buffers_callback
                                                        (CoglFramebuffer *framebuffer,
                                                         unsigned int id);

CoglFramebuffer *   cogl_get_draw_framebuffer           (void);
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 ()

gboolean            cogl_framebuffer_allocate           (CoglFramebuffer *framebuffer,
                                                         GError **error);

cogl_framebuffer_get_width ()

int                 cogl_framebuffer_get_width          (CoglFramebuffer *framebuffer);

cogl_framebuffer_get_height ()

int                 cogl_framebuffer_get_height         (CoglFramebuffer *framebuffer);

cogl_framebuffer_set_viewport ()

void                cogl_framebuffer_set_viewport       (CoglFramebuffer *framebuffer,
                                                         float x,
                                                         float y,
                                                         float width,
                                                         float height);

cogl_framebuffer_get_viewport_x ()

float               cogl_framebuffer_get_viewport_x     (CoglFramebuffer *framebuffer);

cogl_framebuffer_get_viewport_y ()

float               cogl_framebuffer_get_viewport_y     (CoglFramebuffer *framebuffer);

cogl_framebuffer_get_viewport_width ()

float               cogl_framebuffer_get_viewport_width (CoglFramebuffer *framebuffer);

cogl_framebuffer_get_viewport_height ()

float               cogl_framebuffer_get_viewport_height
                                                        (CoglFramebuffer *framebuffer);

cogl_framebuffer_get_viewport4fv ()

void                cogl_framebuffer_get_viewport4fv    (CoglFramebuffer *framebuffer,
                                                         float *viewport);

cogl_framebuffer_get_red_bits ()

int                 cogl_framebuffer_get_red_bits       (CoglFramebuffer *framebuffer);

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 ()

int                 cogl_framebuffer_get_green_bits     (CoglFramebuffer *framebuffer);

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 ()

int                 cogl_framebuffer_get_blue_bits      (CoglFramebuffer *framebuffer);

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 ()

CoglColorMask       cogl_framebuffer_get_color_mask     (CoglFramebuffer *framebuffer);

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 ()

void                cogl_framebuffer_set_color_mask     (CoglFramebuffer *framebuffer,
                                                         CoglColorMask color_mask);

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 ()

CoglContext *       cogl_framebuffer_get_context        (CoglFramebuffer *framebuffer);

cogl_framebuffer_clear ()

void                cogl_framebuffer_clear              (CoglFramebuffer *framebuffer,
                                                         unsigned long  buffers,
                                                         const CoglColor *color);

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 ()

void                cogl_framebuffer_clear4f            (CoglFramebuffer *framebuffer,
                                                         unsigned long  buffers,
                                                         float red,
                                                         float green,
                                                         float blue,
                                                         float alpha);

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 ()

void                cogl_framebuffer_swap_buffers       (CoglFramebuffer *framebuffer);

cogl_framebuffer_swap_region ()

void                cogl_framebuffer_swap_region        (CoglFramebuffer *framebuffer,
                                                         const int *rectangles,
                                                         int n_rectangles);

cogl_framebuffer_add_swap_buffers_callback ()

unsigned int        cogl_framebuffer_add_swap_buffers_callback
                                                        (CoglFramebuffer *framebuffer,
                                                         CoglSwapBuffersNotify callback,
                                                         void *user_data);

cogl_framebuffer_remove_swap_buffers_callback ()

void                cogl_framebuffer_remove_swap_buffers_callback
                                                        (CoglFramebuffer *framebuffer,
                                                         unsigned int id);

cogl_get_draw_framebuffer ()

CoglFramebuffer *   cogl_get_draw_framebuffer           (void);

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:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
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