## 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:

    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