CoglFramebuffer: The Framebuffer Interface

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

Functions

#define COGL_FRAMEBUFFER()
gboolean cogl_framebuffer_allocate ()
int cogl_framebuffer_get_width ()
int cogl_framebuffer_get_height ()
void cogl_framebuffer_set_viewport ()
float cogl_framebuffer_get_viewport_x ()
float cogl_framebuffer_get_viewport_y ()
float cogl_framebuffer_get_viewport_width ()
float cogl_framebuffer_get_viewport_height ()
void cogl_framebuffer_get_viewport4fv ()
CoglPixelFormat cogl_framebuffer_get_color_format ()
int cogl_framebuffer_get_red_bits ()
int cogl_framebuffer_get_green_bits ()
int cogl_framebuffer_get_blue_bits ()
CoglColorMask cogl_framebuffer_get_color_mask ()
void cogl_framebuffer_set_color_mask ()
void cogl_framebuffer_resolve_samples ()
void cogl_framebuffer_resolve_samples_region ()
CoglContext * cogl_framebuffer_get_context ()
void cogl_framebuffer_clear ()
void cogl_framebuffer_clear4f ()
gboolean cogl_framebuffer_read_pixels_into_bitmap ()
gboolean cogl_framebuffer_read_pixels ()
void cogl_framebuffer_set_dither_enabled ()
gboolean cogl_framebuffer_get_dither_enabled ()
void cogl_framebuffer_draw_primitive ()
void cogl_framebuffer_draw_attributes ()
void cogl_framebuffer_vdraw_attributes ()
void cogl_framebuffer_draw_indexed_attributes ()
void cogl_framebuffer_vdraw_indexed_attributes ()
void cogl_framebuffer_draw_rectangle ()
void cogl_framebuffer_draw_textured_rectangle ()
void cogl_framebuffer_draw_multitextured_rectangle ()
void cogl_framebuffer_draw_rectangles ()
void cogl_framebuffer_draw_textured_rectangles ()
void cogl_framebuffer_finish ()
void cogl_framebuffer_push_matrix ()
void cogl_framebuffer_pop_matrix ()
void cogl_framebuffer_identity_matrix ()
void cogl_framebuffer_scale ()
void cogl_framebuffer_translate ()
void cogl_framebuffer_rotate ()
void cogl_framebuffer_transform ()
void cogl_framebuffer_get_modelview_matrix ()
void cogl_framebuffer_set_modelview_matrix ()
void cogl_framebuffer_perspective ()
void cogl_framebuffer_frustum ()
void cogl_framebuffer_orthographic ()
void cogl_framebuffer_get_projection_matrix ()
void cogl_framebuffer_set_projection_matrix ()
void cogl_framebuffer_push_scissor_clip ()
void cogl_framebuffer_push_rectangle_clip ()
void cogl_framebuffer_push_primitive_clip ()
void cogl_framebuffer_pop_clip ()
CoglFramebuffer * cogl_get_draw_framebuffer ()
void cogl_set_framebuffer ()
void cogl_push_framebuffer ()
void cogl_pop_framebuffer ()

Types and Values

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.

Functions

COGL_FRAMEBUFFER()

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

cogl_framebuffer_allocate ()

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

Explicitly allocates a configured CoglFramebuffer allowing developers to check and handle any errors that might arise from an unsupported configuration so that fallback configurations may be tried.

Many applications don't support any fallback options at least when they are initially developed and in that case the don't need to use this API since Cogl will automatically allocate a framebuffer when it first gets used. The disadvantage of relying on automatic allocation is that the program will abort with an error message if there is an error during automatic allocation.

Parameters

framebuffer

A CoglFramebuffer

 

error

A pointer to a GError for returning exceptions.

 

Returns

TRUE if there were no error allocating the framebuffer, else FALSE.

Since 1.8

Stability Level: Unstable


cogl_framebuffer_get_width ()

int
cogl_framebuffer_get_width (CoglFramebuffer *framebuffer);

Queries the current width of the given framebuffer .

Parameters

framebuffer

A CoglFramebuffer

 

Returns

The width of framebuffer .

Since 1.8

Stability Level: Unstable


cogl_framebuffer_get_height ()

int
cogl_framebuffer_get_height (CoglFramebuffer *framebuffer);

Queries the current height of the given framebuffer .

Parameters

framebuffer

A CoglFramebuffer

 

Returns

The height of framebuffer .

Since 1.8

Stability Level: Unstable


cogl_framebuffer_set_viewport ()

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

Defines a scale and offset for everything rendered relative to the top-left of the destination framebuffer.

By default the viewport has an origin of (0,0) and width and height that match the framebuffer's size. Assuming a default projection and modelview matrix then you could translate the contents of a window down and right by leaving the viewport size unchanged by moving the offset to (10,10). The viewport coordinates are measured in pixels. If you left the x and y origin as (0,0) you could scale the windows contents down by specify and width and height that's half the real size of the framebuffer.

Although the function takes floating point arguments, existing drivers only allow the use of integer values. In the future floating point values will be exposed via a checkable feature.

Parameters

framebuffer

A CoglFramebuffer

 

x

The top-left x coordinate of the viewport origin (only integers supported currently)

 

y

The top-left y coordinate of the viewport origin (only integers supported currently)

 

width

The width of the viewport (only integers supported currently)

 

height

The height of the viewport (only integers supported currently)

 

Since 1.8

Stability Level: Unstable


cogl_framebuffer_get_viewport_x ()

float
cogl_framebuffer_get_viewport_x (CoglFramebuffer *framebuffer);

Queries the x coordinate of the viewport origin as set using cogl_framebuffer_set_viewport() or the default value which is 0.

Parameters

framebuffer

A CoglFramebuffer

 

Returns

The x coordinate of the viewport origin.

Since 1.8

Stability Level: Unstable


cogl_framebuffer_get_viewport_y ()

float
cogl_framebuffer_get_viewport_y (CoglFramebuffer *framebuffer);

Queries the y coordinate of the viewport origin as set using cogl_framebuffer_set_viewport() or the default value which is 0.

Parameters

framebuffer

A CoglFramebuffer

 

Returns

The y coordinate of the viewport origin.

Since 1.8

Stability Level: Unstable


cogl_framebuffer_get_viewport_width ()

float
cogl_framebuffer_get_viewport_width (CoglFramebuffer *framebuffer);

Queries the width of the viewport as set using cogl_framebuffer_set_viewport() or the default value which is the width of the framebuffer.

Parameters

framebuffer

A CoglFramebuffer

 

Returns

The width of the viewport.

Since 1.8

Stability Level: Unstable


cogl_framebuffer_get_viewport_height ()

float
cogl_framebuffer_get_viewport_height (CoglFramebuffer *framebuffer);

Queries the height of the viewport as set using cogl_framebuffer_set_viewport() or the default value which is the height of the framebuffer.

Parameters

framebuffer

A CoglFramebuffer

 

Returns

The height of the viewport.

Since 1.8

Stability Level: Unstable


cogl_framebuffer_get_viewport4fv ()

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

Queries the x, y, width and height components of the current viewport as set using cogl_framebuffer_set_viewport() or the default values which are 0, 0, framebuffer_width and framebuffer_height. The values are written into the given viewport array.

Parameters

framebuffer

A CoglFramebuffer

 

viewport

A pointer to an array of 4 floats to receive the (x, y, width, height) components of the current viewport.

 

Since 1.8

Stability Level: Unstable


cogl_framebuffer_get_color_format ()

CoglPixelFormat
cogl_framebuffer_get_color_format (CoglFramebuffer *framebuffer);

Queries the common CoglPixelFormat of all color buffers attached to this framebuffer. For an offscreen framebuffer created with cogl_offscreen_new_to_texture() this will correspond to the format of the texture.

Parameters

framebuffer

A CoglFramebuffer framebuffer

 

Since 1.8

Stability Level: Unstable


cogl_framebuffer_get_red_bits ()

int
cogl_framebuffer_get_red_bits (CoglFramebuffer *framebuffer);

Retrieves the number of red bits of framebuffer

Parameters

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

Parameters

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

Parameters

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.

Parameters

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.

Parameters

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

void
cogl_framebuffer_resolve_samples (CoglFramebuffer *framebuffer);

When point sample rendering (also known as multisample rendering) has been enabled via cogl_framebuffer_set_samples_per_pixel() then you can optionally call this function (or cogl_framebuffer_resolve_samples_region()) to explicitly resolve the point samples into values for the final color buffer.

Some GPUs will implicitly resolve the point samples during rendering and so this function is effectively a nop, but with other architectures it is desirable to defer the resolve step until the end of the frame.

Since Cogl will automatically ensure samples are resolved if the target color buffer is used as a source this API only needs to be used if explicit control is desired - perhaps because you want to ensure that the resolve is completed in advance to avoid later having to wait for the resolve to complete.

If you are performing incremental updates to a framebuffer you should consider using cogl_framebuffer_resolve_samples_region() instead to avoid resolving redundant pixels.

Parameters

framebuffer

A CoglFramebuffer framebuffer

 

Since 1.8

Stability Level: Unstable


cogl_framebuffer_resolve_samples_region ()

void
cogl_framebuffer_resolve_samples_region
                               (CoglFramebuffer *framebuffer,
                                int x,
                                int y,
                                int width,
                                int height);

When point sample rendering (also known as multisample rendering) has been enabled via cogl_framebuffer_set_samples_per_pixel() then you can optionally call this function (or cogl_framebuffer_resolve_samples()) to explicitly resolve the point samples into values for the final color buffer.

Some GPUs will implicitly resolve the point samples during rendering and so this function is effectively a nop, but with other architectures it is desirable to defer the resolve step until the end of the frame.

Use of this API is recommended if incremental, small updates to a framebuffer are being made because by default Cogl will implicitly resolve all the point samples of the framebuffer which can result in redundant work if only a small number of samples have changed.

Because some GPUs implicitly resolve point samples this function only guarantees that at-least the region specified will be resolved and if you have rendered to a larger region then it's possible that other samples may be implicitly resolved.

Parameters

framebuffer

A CoglFramebuffer framebuffer

 

x

top-left x coordinate of region to resolve

 

y

top-left y coordinate of region to resolve

 

width

width of region to resolve

 

height

height of region to resolve

 

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.

Parameters

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.

Parameters

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

gboolean
cogl_framebuffer_read_pixels_into_bitmap
                               (CoglFramebuffer *framebuffer,
                                int x,
                                int y,
                                CoglReadPixelsFlags source,
                                CoglBitmap *bitmap);

This reads a rectangle of pixels from the given framebuffer where position (0, 0) is the top left. The pixel at (x, y) is the first read, and a rectangle of pixels with the same size as the bitmap is read right and downwards from that point.

Currently Cogl assumes that the framebuffer is in a premultiplied format so if the format of bitmap is non-premultiplied it will convert it. To read the pixel values without any conversion you should either specify a format that doesn't use an alpha channel or use one of the formats ending in PRE.

Parameters

framebuffer

A CoglFramebuffer

 

x

The x position to read from

 

y

The y position to read from

 

source

Identifies which auxillary buffer you want to read (only COGL_READ_PIXELS_COLOR_BUFFER supported currently)

 

bitmap

The bitmap to store the results in.

 

Returns

TRUE if the read succeeded or FALSE otherwise. The function is only likely to fail if the bitmap points to a pixel buffer and it could not be mapped.

Since 1.10

Stability Level: Unstable


cogl_framebuffer_read_pixels ()

gboolean
cogl_framebuffer_read_pixels (CoglFramebuffer *framebuffer,
                              int x,
                              int y,
                              int width,
                              int height,
                              CoglPixelFormat format,
                              guint8 *pixels);

This is a convenience wrapper around cogl_framebuffer_read_pixels_into_bitmap() which allocates a temporary CoglBitmap to read pixel data directly into the given buffer. The rowstride of the buffer is assumed to be the width of the region times the bytes per pixel of the format. The source for the data is always taken from the color buffer. If you want to use any other rowstride or source, please use the cogl_framebuffer_read_pixels_into_bitmap() function directly.

The implementation of the function looks like this:

1
2
3
4
5
6
7
8
9
10
11
bitmap = cogl_bitmap_new_for_data (context,
                                   width, height,
                                   format,
                                   /<!-- -->* rowstride *<!-- -->/
                                   bpp * width,
                                   pixels);
cogl_framebuffer_read_pixels_into_bitmap (framebuffer,
                                          x, y,
                                          COGL_READ_PIXELS_COLOR_BUFFER,
                                          bitmap);
cogl_object_unref (bitmap);

Parameters

framebuffer

A CoglFramebuffer

 

x

The x position to read from

 

y

The y position to read from

 

width

The width of the region of rectangles to read

 

height

The height of the region of rectangles to read

 

format

The pixel format to store the data in

 

pixels

The address of the buffer to store the data in

 

Returns

TRUE if the read succeeded or FALSE otherwise.

Since 1.10

Stability Level: Unstable


cogl_framebuffer_set_dither_enabled ()

void
cogl_framebuffer_set_dither_enabled (CoglFramebuffer *framebuffer,
                                     gboolean dither_enabled);

Enables or disabled dithering if supported by the hardware.

Dithering is a hardware dependent technique to increase the visible color resolution beyond what the underlying hardware supports by playing tricks with the colors placed into the framebuffer to give the illusion of other colors. (For example this can be compared to half-toning used by some news papers to show varying levels of grey even though their may only be black and white are available).

If the current display pipeline for framebuffer does not support dithering then this has no affect.

Dithering is enabled by default.

Parameters

framebuffer

a pointer to a CoglFramebuffer

 

dither_enabled

TRUE to enable dithering or FALSE to disable

 

Since 1.8

Stability Level: Unstable


cogl_framebuffer_get_dither_enabled ()

gboolean
cogl_framebuffer_get_dither_enabled (CoglFramebuffer *framebuffer);

Returns whether dithering has been requested for the given framebuffer . See cogl_framebuffer_set_dither_enabled() for more details about dithering.

This may return TRUE even when the underlying framebuffer display pipeline does not support dithering. This value only represents the user's request for dithering.

Parameters

framebuffer

a pointer to a CoglFramebuffer

 

Returns

TRUE if dithering has been requested or FALSE if not.

Since 1.8

Stability Level: Unstable


cogl_framebuffer_draw_primitive ()

void
cogl_framebuffer_draw_primitive (CoglFramebuffer *framebuffer,
                                 CoglPipeline *pipeline,
                                 CoglPrimitive *primitive);

Draws the given primitive geometry to the specified destination framebuffer using the graphics processing state described by pipeline .

This drawing api doesn't support high-level meta texture types such as CoglTexture2DSliced so it is the user's responsibility to ensure that only low-level textures that can be directly sampled by a GPU such as CoglTexture2D, CoglTextureRectangle or CoglTexture3D are associated with layers of the given pipeline .

This api doesn't support any of the legacy global state options such as cogl_set_depth_test_enabled(), cogl_set_backface_culling_enabled() or cogl_program_use()

Parameters

framebuffer

A destination CoglFramebuffer

 

pipeline

A CoglPipeline state object

 

primitive

A CoglPrimitive geometry object

 

Since 1.10

Stability Level: Unstable


cogl_framebuffer_draw_attributes ()

void
cogl_framebuffer_draw_attributes (CoglFramebuffer *framebuffer,
                                  CoglPipeline *pipeline,
                                  CoglVerticesMode mode,
                                  int first_vertex,
                                  int n_vertices,
                                  CoglAttribute **attributes,
                                  int n_attributes);

First defines a geometry primitive by grouping a set of vertex attributes ; specifying a first_vertex ; a number of vertices (n_vertices ) and specifying what kind of topology the vertices have via mode .

Then the function draws the given primitive geometry to the specified destination framebuffer using the graphics processing pipeline described by pipeline .

The list of CoglAttributes define the attributes of the vertices to be drawn, such as positions, colors and normals and the number of attributes is given as n_attributes .

This drawing api doesn't support high-level meta texture types such as CoglTexture2DSliced so it is the user's responsibility to ensure that only low-level textures that can be directly sampled by a GPU such as CoglTexture2D, CoglTextureRectangle or CoglTexture3D are associated with layers of the given pipeline .

This api doesn't support any of the legacy global state options such as cogl_set_depth_test_enabled(), cogl_set_backface_culling_enabled() or cogl_program_use()

Parameters

framebuffer

A destination CoglFramebuffer

 

pipeline

A CoglPipeline state object

 

mode

The CoglVerticesMode defining the topology of vertices

 

first_vertex

The vertex offset within the given attributes to draw from

 

n_vertices

The number of vertices to draw from the given attributes

 

attributes

An array of pointers to CoglAttribute<-- -->s defining vertex geometry

 

n_attributes

The number of attributes in the attributes array.

 

Since 1.10

Stability Level: Unstable


cogl_framebuffer_vdraw_attributes ()

void
cogl_framebuffer_vdraw_attributes (CoglFramebuffer *framebuffer,
                                   CoglPipeline *pipeline,
                                   CoglVerticesMode mode,
                                   int first_vertex,
                                   int n_vertices,
                                   ...);

First defines a geometry primitive by grouping a set of vertex attributes; specifying a first_vertex ; a number of vertices (n_vertices ) and specifying what kind of topology the vertices have via mode .

Then the function draws the given primitive geometry to the specified destination framebuffer using the graphics processing pipeline described by pipeline .

The list of CoglAttributes define the attributes of the vertices to be drawn, such as positions, colors and normals and should be NULL terminated.

This drawing api doesn't support high-level meta texture types such as CoglTexture2DSliced so it is the user's responsibility to ensure that only low-level textures that can be directly sampled by a GPU such as CoglTexture2D, CoglTextureRectangle or CoglTexture3D are associated with layers of the given pipeline .

Parameters

framebuffer

A destination CoglFramebuffer

 

pipeline

A CoglPipeline state object

 

mode

The CoglVerticesMode defining the topology of vertices

 

first_vertex

The vertex offset within the given attributes to draw from

 

n_vertices

The number of vertices to draw from the given attributes

 

...

A set of vertex CoglAttributes defining vertex geometry

 

Since 1.10

Stability Level: Unstable


cogl_framebuffer_draw_indexed_attributes ()

void
cogl_framebuffer_draw_indexed_attributes
                               (CoglFramebuffer *framebuffer,
                                CoglPipeline *pipeline,
                                CoglVerticesMode mode,
                                int first_vertex,
                                int n_vertices,
                                CoglIndices *indices,
                                CoglAttribute **attributes,
                                int n_attributes);

Behaves the same as cogl_framebuffer_draw_attributes() except that instead of reading vertex data sequentially from the specified attributes the indices provide an indirection for how the data should be indexed allowing a random access order to be specified.

For example an indices array of [0, 1, 2, 0, 2, 3] could be used used to draw two triangles (mode = COGL_VERTICES_MODE_TRIANGLES + n_vertices = 6) but only provide attribute data for the 4 corners of a rectangle. When the GPU needs to read in each of the 6 vertices it will read the indices array for each vertex in sequence and use the index to look up the vertex attribute data. So here you can see that first and fourth vertex will point to the same data and third and fifth vertex will also point to shared data.

Drawing with indices can be a good way of minimizing the size of a mesh by allowing you to avoid data for duplicate vertices because multiple entries in the index array can refer back to a single shared vertex.

The indices array must be at least as long as first_vertex + n_vertices otherwise the GPU will overrun the indices array when looking up vertex data.

Since it's very common to want to draw a run of rectangles using indices to avoid duplicating vertex data you can use cogl_get_rectangle_indices() to get a set of indices that can be shared.

This drawing api doesn't support high-level meta texture types such as CoglTexture2DSliced so it is the user's responsibility to ensure that only low-level textures that can be directly sampled by a GPU such as CoglTexture2D, CoglTextureRectangle or CoglTexture3D are associated with layers of the given pipeline .

This api doesn't support any of the legacy global state options such as cogl_set_depth_test_enabled(), cogl_set_backface_culling_enabled() or cogl_program_use()

Parameters

framebuffer

A destination CoglFramebuffer

 

pipeline

A CoglPipeline state object

 

mode

The CoglVerticesMode defining the topology of vertices

 

first_vertex

The vertex offset within the given attributes to draw from

 

n_vertices

The number of vertices to draw from the given attributes

 

indices

The array of indices used by the GPU to lookup attribute data for each vertex.

 

attributes

An array of pointers to CoglAttribute<-- -->s defining vertex geometry

 

n_attributes

The number of attributes in the attributes array.

 

Since 1.10

Stability Level: Unstable


cogl_framebuffer_vdraw_indexed_attributes ()

void
cogl_framebuffer_vdraw_indexed_attributes
                               (CoglFramebuffer *framebuffer,
                                CoglPipeline *pipeline,
                                CoglVerticesMode mode,
                                int first_vertex,
                                int n_vertices,
                                CoglIndices *indices,
                                ...);

Behaves the same as cogl_framebuffer_vdraw_attributes() except that instead of reading vertex data sequentially from the specified attributes the indices provide an indirection for how the data should be indexed allowing a random access order to be specified.

For example an indices array of [0, 1, 2, 0, 2, 3] could be used used to draw two triangles (mode = COGL_VERTICES_MODE_TRIANGLES + n_vertices = 6) but only provide attribute data for the 4 corners of a rectangle. When the GPU needs to read in each of the 6 vertices it will read the indices array for each vertex in sequence and use the index to look up the vertex attribute data. So here you can see that first and fourth vertex will point to the same data and third and fifth vertex will also point to shared data.

Drawing with indices can be a good way of minimizing the size of a mesh by allowing you to avoid data for duplicate vertices because multiple entries in the index array can refer back to a single shared vertex.

The indices array must be at least as long as first_vertex + n_vertices otherwise the GPU will overrun the indices array when looking up vertex data.

Since it's very common to want to draw a run of rectangles using indices to avoid duplicating vertex data you can use cogl_get_rectangle_indices() to get a set of indices that can be shared.

This drawing api doesn't support high-level meta texture types such as CoglTexture2DSliced so it is the user's responsibility to ensure that only low-level textures that can be directly sampled by a GPU such as CoglTexture2D, CoglTextureRectangle or CoglTexture3D are associated with layers of the given pipeline .

This api doesn't support any of the legacy global state options such as cogl_set_depth_test_enabled(), cogl_set_backface_culling_enabled() or cogl_program_use()

Parameters

framebuffer

A destination CoglFramebuffer

 

pipeline

A CoglPipeline state object

 

mode

The CoglVerticesMode defining the topology of vertices

 

first_vertex

The vertex offset within the given attributes to draw from

 

n_vertices

The number of vertices to draw from the given attributes

 

indices

The array of indices used by the GPU to lookup attribute data for each vertex.

 

...

A set of vertex CoglAttributes defining vertex geometry

 

Since 1.10

Stability Level: Unstable


cogl_framebuffer_draw_rectangle ()

void
cogl_framebuffer_draw_rectangle (CoglFramebuffer *framebuffer,
                                 CoglPipeline *pipeline,
                                 float x_1,
                                 float y_1,
                                 float x_2,
                                 float y_2);

Draws a rectangle to framebuffer with the given pipeline state and with the top left corner positioned at (x_1 , y_1 ) and the bottom right corner positioned at (x_2 , y_2 ).

The position is the position before the rectangle has been transformed by the model-view matrix and the projection matrix.
If you want to describe a rectangle with a texture mapped on it then you can use cogl_framebuffer_draw_textured_rectangle().

Parameters

framebuffer

A destination CoglFramebuffer

 

pipeline

A CoglPipeline state object

 

x_1

X coordinate of the top-left corner

 

y_1

Y coordinate of the top-left corner

 

x_2

X coordinate of the bottom-right corner

 

y_2

Y coordinate of the bottom-right corner

 

Since 1.10

Stability Level: Unstable


cogl_framebuffer_draw_textured_rectangle ()

void
cogl_framebuffer_draw_textured_rectangle
                               (CoglFramebuffer *framebuffer,
                                CoglPipeline *pipeline,
                                float x_1,
                                float y_1,
                                float x_2,
                                float y_2,
                                float s_1,
                                float t_1,
                                float s_2,
                                float t_2);

Draws a textured rectangle to framebuffer using the given pipeline state with the top left corner positioned at (x_1 , y_1 ) and the bottom right corner positioned at (x_2 , y_2 ). The top left corner will have texture coordinates of (s_1 , t_1 ) and the bottom right corner will have texture coordinates of (s_2 , t_2 ).

The position is the position before the rectangle has been transformed by the model-view matrix and the projection matrix.

This is a high level drawing api that can handle any kind of CoglMetaTexture texture such as CoglTexture2DSliced textures which may internally be comprised of multiple low-level textures. This is unlike low-level drawing apis such as cogl_framebuffer_draw_primitive() or cogl_framebuffer_draw_attributes() which only support low level texture types that are directly supported by GPUs such as CoglTexture2D.

The given texture coordinates will only be used for the first texture layer of the pipeline and if your pipeline has more than one layer then all other layers will have default texture coordinates of s_1=0.0 t_1=0.0 s_2=1.0 t_2=1.0

The given texture coordinates should always be normalized such that (0, 0) corresponds to the top left and (1, 1) corresponds to the bottom right. To map an entire texture across the rectangle pass in s_1 =0, t_1 =0, s_2 =1, t_2 =1.

Even if you have associated a CoglTextureRectangle texture with one of your pipeline layers which normally implies working with non-normalized texture coordinates this api should still be passed normalized texture coordinates.

Parameters

framebuffer

A destination CoglFramebuffer

 

pipeline

A CoglPipeline state object

 

x_1

x coordinate upper left on screen.

 

y_1

y coordinate upper left on screen.

 

x_2

x coordinate lower right on screen.

 

y_2

y coordinate lower right on screen.

 

s_1

S texture coordinate of the top-left coorner

 

t_1

T texture coordinate of the top-left coorner

 

s_2

S texture coordinate of the bottom-right coorner

 

t_2

T texture coordinate of the bottom-right coorner

 

Since 1.10

Stability Level: Unstable


cogl_framebuffer_draw_multitextured_rectangle ()

void
cogl_framebuffer_draw_multitextured_rectangle
                               (CoglFramebuffer *framebuffer,
                                CoglPipeline *pipeline,
                                float x_1,
                                float y_1,
                                float x_2,
                                float y_2,
                                const float *tex_coords,
                                int tex_coords_len);

Draws a textured rectangle to framebuffer with the given pipeline state with the top left corner positioned at (x_1 , y_1 ) and the bottom right corner positioned at (x_2 , y_2 ). As a pipeline may contain multiple texture layers this interface lets you supply texture coordinates for each layer of the pipeline.

The position is the position before the rectangle has been transformed by the model-view matrix and the projection matrix.

This is a high level drawing api that can handle any kind of CoglMetaTexture texture for the first layer such as CoglTexture2DSliced textures which may internally be comprised of multiple low-level textures. This is unlike low-level drawing apis such as cogl_framebuffer_draw_primitive() or cogl_framebuffer_draw_attributes() which only support low level texture types that are directly supported by GPUs such as CoglTexture2D.

This api can not currently handle multiple high-level meta texture layers. The first layer may be a high level meta texture such as CoglTexture2DSliced but all other layers much be low level textures such as CoglTexture2D and additionally they should be textures that can be sampled using normalized coordinates (so not CoglTextureRectangle textures).

The top left texture coordinate for layer 0 of any pipeline will be (tex_coords[0], tex_coords[1]) and the bottom right coordinate will be (tex_coords[2], tex_coords[3]). The coordinates for layer 1 would be (tex_coords[4], tex_coords[5]) (tex_coords[6], tex_coords[7]) and so on...

The given texture coordinates should always be normalized such that (0, 0) corresponds to the top left and (1, 1) corresponds to the bottom right. To map an entire texture across the rectangle pass in tex_coords[0]=0, tex_coords[1]=0, tex_coords[2]=1, tex_coords[3]=1.

Even if you have associated a CoglTextureRectangle texture which normally implies working with non-normalized texture coordinates this api should still be passed normalized texture coordinates.

The first pair of coordinates are for the first layer (with the smallest layer index) and if you supply less texture coordinates than there are layers in the current source material then default texture coordinates (0.0, 0.0, 1.0, 1.0) are generated.

Parameters

framebuffer

A destination CoglFramebuffer

 

pipeline

A CoglPipeline state object

 

x_1

x coordinate upper left on screen.

 

y_1

y coordinate upper left on screen.

 

x_2

x coordinate lower right on screen.

 

y_2

y coordinate lower right on screen.

 

tex_coords

An array containing groups of 4 float values: [s_1, t_1, s_2, t_2] that are interpreted as two texture coordinates; one for the top left texel, and one for the bottom right texel. Each value should be between 0.0 and 1.0, where the coordinate (0.0, 0.0) represents the top left of the texture, and (1.0, 1.0) the bottom right.

[in][array][transfer none]

tex_coords_len

The length of the tex_coords array. (For one layer and one group of texture coordinates, this would be 4)

 

Since 1.10

Stability Level: Unstable


cogl_framebuffer_draw_rectangles ()

void
cogl_framebuffer_draw_rectangles (CoglFramebuffer *framebuffer,
                                  CoglPipeline *pipeline,
                                  const float *verts,
                                  unsigned int n_rects);

Draws a series of rectangles to framebuffer with the given pipeline state in the same way that cogl_framebuffer_draw_rectangle() does.

The top left corner of the first rectangle is positioned at (coordinates[0], coordinates[1]) and the bottom right corner is positioned at (coordinates[2], coordinates[3]). The positions for the second rectangle are (coordinates[4], coordinates[5]) and (coordinates[6], coordinates[7]) and so on...

The position is the position before the rectangle has been transformed by the model-view matrix and the projection matrix.

As a general rule for better performance its recommended to use this this API instead of calling cogl_framebuffer_draw_textured_rectangle() separately for multiple rectangles if all of the rectangles will be drawn together with the same pipeline state.

Parameters

framebuffer

A destination CoglFramebuffer

 

pipeline

A CoglPipeline state object

 

coordinates

an array of coordinates containing groups of 4 float values: [x_1, y_1, x_2, y_2] that are interpreted as two position coordinates; one for the top left of the rectangle (x1, y1), and one for the bottom right of the rectangle (x2, y2).

[in][array][transfer none]

n_rectangles

number of rectangles defined in coordinates .

 

Since 1.10

Stability Level: Unstable


cogl_framebuffer_draw_textured_rectangles ()

void
cogl_framebuffer_draw_textured_rectangles
                               (CoglFramebuffer *framebuffer,
                                CoglPipeline *pipeline,
                                const float *coordinates,
                                unsigned int n_rectangles);

Draws a series of rectangles to framebuffer with the given pipeline state in the same way that cogl_framebuffer_draw_textured_rectangle() does.

The position is the position before the rectangle has been transformed by the model-view matrix and the projection matrix.

This is a high level drawing api that can handle any kind of CoglMetaTexture texture such as CoglTexture2DSliced textures which may internally be comprised of multiple low-level textures. This is unlike low-level drawing apis such as cogl_framebuffer_draw_primitive() or cogl_framebuffer_draw_attributes() which only support low level texture types that are directly supported by GPUs such as CoglTexture2D.

The top left corner of the first rectangle is positioned at (coordinates[0], coordinates[1]) and the bottom right corner is positioned at (coordinates[2], coordinates[3]). The top left texture coordinate is (coordinates[4], coordinates[5]) and the bottom right texture coordinate is (coordinates[6], coordinates[7]). The coordinates for subsequent rectangles are defined similarly by the subsequent coordinates.

As a general rule for better performance its recommended to use this this API instead of calling cogl_framebuffer_draw_textured_rectangle() separately for multiple rectangles if all of the rectangles will be drawn together with the same pipeline state.

The given texture coordinates should always be normalized such that (0, 0) corresponds to the top left and (1, 1) corresponds to the bottom right. To map an entire texture across the rectangle pass in tex_coords[0]=0, tex_coords[1]=0, tex_coords[2]=1, tex_coords[3]=1.

Even if you have associated a CoglTextureRectangle texture which normally implies working with non-normalized texture coordinates this api should still be passed normalized texture coordinates.

Parameters

framebuffer

A destination CoglFramebuffer

 

pipeline

A CoglPipeline state object

 

coordinates

an array containing groups of 8 float values: [x_1, y_1, x_2, y_2, s_1, t_1, s_2, t_2] that have the same meaning as the arguments for cogl_framebuffer_draw_textured_rectangle().

[in][array][transfer none]

n_rectangles

number of rectangles to coordinates to draw

 

Since 1.10

Stability Level: Unstable


cogl_framebuffer_finish ()

void
cogl_framebuffer_finish (CoglFramebuffer *framebuffer);

This blocks the CPU until all pending rendering associated with the specified framebuffer has completed. It's very rare that developers should ever need this level of synchronization with the GPU and should never be used unless you clearly understand why you need to explicitly force synchronization.

One example might be for benchmarking purposes to be sure timing measurements reflect the time that the GPU is busy for not just the time it takes to queue rendering commands.

Parameters

framebuffer

A CoglFramebuffer pointer

 

Since 1.10

Stability Level: Unstable


cogl_framebuffer_push_matrix ()

void
cogl_framebuffer_push_matrix (CoglFramebuffer *framebuffer);

Copies the current model-view matrix onto the matrix stack. The matrix can later be restored with cogl_framebuffer_pop_matrix().

Parameters

framebuffer

A CoglFramebuffer pointer

 

Since 1.10


cogl_framebuffer_pop_matrix ()

void
cogl_framebuffer_pop_matrix (CoglFramebuffer *framebuffer);

Restores the model-view matrix on the top of the matrix stack.

Parameters

framebuffer

A CoglFramebuffer pointer

 

Since 1.10


cogl_framebuffer_identity_matrix ()

void
cogl_framebuffer_identity_matrix (CoglFramebuffer *framebuffer);

Resets the current model-view matrix to the identity matrix.

Parameters

framebuffer

A CoglFramebuffer pointer

 

Since 1.10

Stability Level: Unstable


cogl_framebuffer_scale ()

void
cogl_framebuffer_scale (CoglFramebuffer *framebuffer,
                        float x,
                        float y,
                        float z);

Multiplies the current model-view matrix by one that scales the x, y and z axes by the given values.

Parameters

framebuffer

A CoglFramebuffer pointer

 

x

Amount to scale along the x-axis

 

y

Amount to scale along the y-axis

 

z

Amount to scale along the z-axis

 

Since 1.10

Stability Level: Unstable


cogl_framebuffer_translate ()

void
cogl_framebuffer_translate (CoglFramebuffer *framebuffer,
                            float x,
                            float y,
                            float z);

Multiplies the current model-view matrix by one that translates the model along all three axes according to the given values.

Parameters

framebuffer

A CoglFramebuffer pointer

 

x

Distance to translate along the x-axis

 

y

Distance to translate along the y-axis

 

z

Distance to translate along the z-axis

 

Since 1.10

Stability Level: Unstable


cogl_framebuffer_rotate ()

void
cogl_framebuffer_rotate (CoglFramebuffer *framebuffer,
                         float angle,
                         float x,
                         float y,
                         float z);

Multiplies the current model-view matrix by one that rotates the model around the vertex specified by x , y and z . The rotation follows the right-hand thumb rule so for example rotating by 10 degrees about the vertex (0, 0, 1) causes a small counter-clockwise rotation.

Parameters

framebuffer

A CoglFramebuffer pointer

 

angle

Angle in degrees to rotate.

 

x

X-component of vertex to rotate around.

 

y

Y-component of vertex to rotate around.

 

z

Z-component of vertex to rotate around.

 

Since 1.10

Stability Level: Unstable


cogl_framebuffer_transform ()

void
cogl_framebuffer_transform (CoglFramebuffer *framebuffer,
                            const CoglMatrix *matrix);

Multiplies the current model-view matrix by the given matrix.

Parameters

framebuffer

A CoglFramebuffer pointer

 

matrix

the matrix to multiply with the current model-view

 

Since 1.10

Stability Level: Unstable


cogl_framebuffer_get_modelview_matrix ()

void
cogl_framebuffer_get_modelview_matrix (CoglFramebuffer *framebuffer,
                                       CoglMatrix *matrix);

Stores the current model-view matrix in matrix .

Parameters

framebuffer

A CoglFramebuffer pointer

 

matrix

return location for the model-view matrix.

[out]

Since 1.10

Stability Level: Unstable


cogl_framebuffer_set_modelview_matrix ()

void
cogl_framebuffer_set_modelview_matrix (CoglFramebuffer *framebuffer,
                                       CoglMatrix *matrix);

Sets matrix as the new model-view matrix.

Parameters

framebuffer

A CoglFramebuffer pointer

 

matrix

the new model-view matrix

 

Since 1.10

Stability Level: Unstable


cogl_framebuffer_perspective ()

void
cogl_framebuffer_perspective (CoglFramebuffer *framebuffer,
                              float fov_y,
                              float aspect,
                              float z_near,
                              float z_far);

Replaces the current projection matrix with a perspective matrix based on the provided values.

You should be careful not to have to great a z_far / z_near ratio since that will reduce the effectiveness of depth testing since there wont be enough precision to identify the depth of objects near to each other.

Parameters

framebuffer

A CoglFramebuffer pointer

 

fov_y

Vertical field of view angle in degrees.

 

aspect

The (width over height) aspect ratio for display

 

z_near

The distance to the near clipping plane (Must be positive, and must not be 0)

 

z_far

The distance to the far clipping plane (Must be positive)

 

Since 1.10

Stability Level: Unstable


cogl_framebuffer_frustum ()

void
cogl_framebuffer_frustum (CoglFramebuffer *framebuffer,
                          float left,
                          float right,
                          float bottom,
                          float top,
                          float z_near,
                          float z_far);

Replaces the current projection matrix with a perspective matrix for a given viewing frustum defined by 4 side clip planes that all cross through the origin and 2 near and far clip planes.

Parameters

framebuffer

A CoglFramebuffer pointer

 

left

X position of the left clipping plane where it intersects the near clipping plane

 

right

X position of the right clipping plane where it intersects the near clipping plane

 

bottom

Y position of the bottom clipping plane where it intersects the near clipping plane

 

top

Y position of the top clipping plane where it intersects the near clipping plane

 

z_near

The distance to the near clipping plane (Must be positive)

 

z_far

The distance to the far clipping plane (Must be positive)

 

Since 1.10

Stability Level: Unstable


cogl_framebuffer_orthographic ()

void
cogl_framebuffer_orthographic (CoglFramebuffer *framebuffer,
                               float x_1,
                               float y_1,
                               float x_2,
                               float y_2,
                               float near,
                               float far);

Replaces the current projection matrix with an orthographic projection matrix.

Parameters

framebuffer

A CoglFramebuffer pointer

 

x_1

The x coordinate for the first vertical clipping plane

 

y_1

The y coordinate for the first horizontal clipping plane

 

x_2

The x coordinate for the second vertical clipping plane

 

y_2

The y coordinate for the second horizontal clipping plane

 

near

The distance to the near clipping plane (will be negative if the plane is behind the viewer)

 

far

The distance to the far clipping plane (will be negative if the plane is behind the viewer)

 

Since 1.10

Stability Level: Unstable


cogl_framebuffer_get_projection_matrix ()

void
cogl_framebuffer_get_projection_matrix
                               (CoglFramebuffer *framebuffer,
                                CoglMatrix *matrix);

Stores the current projection matrix in matrix .

Parameters

framebuffer

A CoglFramebuffer pointer

 

matrix

return location for the projection matrix.

[out]

Since 1.10

Stability Level: Unstable


cogl_framebuffer_set_projection_matrix ()

void
cogl_framebuffer_set_projection_matrix
                               (CoglFramebuffer *framebuffer,
                                CoglMatrix *matrix);

Sets matrix as the new projection matrix.

Parameters

framebuffer

A CoglFramebuffer pointer

 

matrix

the new projection matrix

 

Since 1.10

Stability Level: Unstable


cogl_framebuffer_push_scissor_clip ()

void
cogl_framebuffer_push_scissor_clip (CoglFramebuffer *framebuffer,
                                    int x,
                                    int y,
                                    int width,
                                    int height);

Specifies a rectangular clipping area for all subsequent drawing operations. Any drawing commands that extend outside the rectangle will be clipped so that only the portion inside the rectangle will be displayed. The rectangle dimensions are not transformed by the current model-view matrix.

The rectangle is intersected with the current clip region. To undo the effect of this function, call cogl_framebuffer_pop_clip().

Parameters

framebuffer

A CoglFramebuffer pointer

 

x

left edge of the clip rectangle in window coordinates

 

y

top edge of the clip rectangle in window coordinates

 

width

width of the clip rectangle

 

height

height of the clip rectangle

 

Since 1.10

Stability Level: Unstable


cogl_framebuffer_push_rectangle_clip ()

void
cogl_framebuffer_push_rectangle_clip (CoglFramebuffer *framebuffer,
                                      float x_1,
                                      float y_1,
                                      float x_2,
                                      float y_2);

Specifies a modelview transformed rectangular clipping area for all subsequent drawing operations. Any drawing commands that extend outside the rectangle will be clipped so that only the portion inside the rectangle will be displayed. The rectangle dimensions are transformed by the current model-view matrix.

The rectangle is intersected with the current clip region. To undo the effect of this function, call cogl_framebuffer_pop_clip().

Parameters

framebuffer

A CoglFramebuffer pointer

 

x_1

x coordinate for top left corner of the clip rectangle

 

y_1

y coordinate for top left corner of the clip rectangle

 

x_2

x coordinate for bottom right corner of the clip rectangle

 

y_2

y coordinate for bottom right corner of the clip rectangle

 

Since 1.10

Stability Level: Unstable


cogl_framebuffer_push_primitive_clip ()

void
cogl_framebuffer_push_primitive_clip (CoglFramebuffer *framebuffer,
                                      CoglPrimitive *primitive,
                                      float bounds_x1,
                                      float bounds_y1,
                                      float bounds_x2,
                                      float bounds_y2);

Sets a new clipping area using a 2D shaped described with a CoglPrimitive. The shape must not contain self overlapping geometry and must lie on a single 2D plane. A bounding box of the 2D shape in local coordinates (the same coordinates used to describe the shape) must be given. It is acceptable for the bounds to be larger than the true bounds but behaviour is undefined if the bounds are smaller than the true bounds.

The primitive is transformed by the current model-view matrix and the silhouette is intersected with the previous clipping area. To restore the previous clipping area, call cogl_framebuffer_pop_clip().

Parameters

framebuffer

A CoglFramebuffer pointer

 

primitive

A CoglPrimitive describing a flat 2D shape

 

bounds_x1

x coordinate for the top-left corner of the primitives bounds

 

bounds_y1

y coordinate for the top-left corner of the primitives bounds

 

bounds_x2

x coordinate for the top-left corner of the primitives bounds

 

bounds_y2

x coordinate for the bottom-right corner of the primitives bounds.

 

bounds_x1

y coordinate for the bottom-right corner of the primitives bounds.

 

Since 1.10

Stability Level: Unstable


cogl_framebuffer_pop_clip ()

void
cogl_framebuffer_pop_clip (CoglFramebuffer *framebuffer);

Reverts the clipping region to the state before the last call to cogl_framebuffer_push_clip().

Parameters

framebuffer

A CoglFramebuffer pointer

 

Since 1.10

Stability Level: Unstable


cogl_get_draw_framebuffer ()

CoglFramebuffer *
cogl_get_draw_framebuffer (void);

Gets the current CoglFramebuffer as set using cogl_push_framebuffer()

Returns

The current CoglFramebuffer

Since 1.8

Stability Level: Unstable


cogl_set_framebuffer ()

void
cogl_set_framebuffer (CoglFramebuffer *buffer);

cogl_set_framebuffer is deprecated and should not be used in newly-written code.

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.

Parameters

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

Parameters

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

Types and Values

CoglFramebuffer

typedef struct _CoglFramebuffer CoglFramebuffer;