## CoglFramebuffer: The Base Framebuffer Type

CoglFramebuffer: The Base Framebuffer Type

## Synopsis

    void                cogl_set_framebuffer                (CoglFramebuffer *buffer);
    void                cogl_push_framebuffer               (CoglFramebuffer *buffer);
    void                cogl_pop_framebuffer                (void);

## Description

## Details

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