CoglFramebuffer

typedef void CoglFramebuffer;

COGL_FRAMEBUFFER()

#define             COGL_FRAMEBUFFER(X)

cogl_framebuffer_allocate ()

CoglBool            cogl_framebuffer_allocate           (CoglFramebuffer *framebuffer,
                                                         CoglError **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.

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.

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.

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.

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.

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.

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.

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.

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.

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

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

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

Since 1.8

Stability Level: Unstable

cogl_framebuffer_get_alpha_bits ()

int                 cogl_framebuffer_get_alpha_bits     (CoglFramebuffer *framebuffer);

Retrieves the number of alpha bits of framebuffer

Since 1.8

Stability Level: Unstable

cogl_framebuffer_get_depth_bits ()

int                 cogl_framebuffer_get_depth_bits     (CoglFramebuffer *framebuffer);

Retrieves the number of depth bits of framebuffer

Since 2.0

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.

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.

Since 1.8

Stability Level: Unstable

cogl_framebuffer_get_samples_per_pixel ()

int                 cogl_framebuffer_get_samples_per_pixel
                                                        (CoglFramebuffer *framebuffer);

Gets the number of points that are sampled per-pixel when rasterizing geometry. Usually by default this will return 0 which means that single-sample not multisample rendering has been chosen. When using a GPU supporting multisample rendering it's possible to increase the number of samples per pixel using cogl_framebuffer_set_samples_per_pixel().

Calling cogl_framebuffer_get_samples_per_pixel() before the framebuffer has been allocated will simply return the value set using cogl_framebuffer_set_samples_per_pixel(). After the framebuffer has been allocated the value will reflect the actual number of samples that will be made by the GPU.

Since 1.10

Stability Level: Unstable

cogl_framebuffer_set_samples_per_pixel ()

void                cogl_framebuffer_set_samples_per_pixel
                                                        (CoglFramebuffer *framebuffer,
                                                         int samples_per_pixel);

Requires that when rendering to framebuffer then n point samples should be made per pixel which will all contribute to the final resolved color for that pixel. The idea is that the hardware aims to get quality similar to what you would get if you rendered everything twice as big (for 4 samples per pixel) and then scaled that image back down with filtering. It can effectively remove the jagged edges of polygons and should be more efficient than if you were to manually render at a higher resolution and downscale because the hardware is often able to take some shortcuts. For example the GPU may only calculate a single texture sample for all points of a single pixel, and for tile based architectures all the extra sample data (such as depth and stencil samples) may be handled on-chip and so avoid increased demand on system memory bandwidth.

By default this value is usually set to 0 and that is referred to as "single-sample" rendering. A value of 1 or greater is referred to as "multisample" rendering.

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.

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.

Since 1.8

Stability Level: Unstable

cogl_framebuffer_get_context ()

CoglContext *       cogl_framebuffer_get_context        (CoglFramebuffer *framebuffer);

Can be used to query the CoglContext a given framebuffer was instantiated within. This is the CoglContext that was passed to cogl_onscreen_new() for example.

Since 1.8

Stability Level: Unstable

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.

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.

Since 1.8

Stability Level: Unstable

cogl_framebuffer_read_pixels_into_bitmap ()

CoglBool            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.

Since 1.10

Stability Level: Unstable

cogl_framebuffer_read_pixels ()

CoglBool            cogl_framebuffer_read_pixels        (CoglFramebuffer *framebuffer,
                                                         int x,
                                                         int y,
                                                         int width,
                                                         int height,
                                                         CoglPixelFormat format,
                                                         uint8_t *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
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35

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

Since 1.10

Stability Level: Unstable

cogl_framebuffer_set_dither_enabled ()

void                cogl_framebuffer_set_dither_enabled (CoglFramebuffer *framebuffer,
                                                         CoglBool 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.

Since 1.8

Stability Level: Unstable

cogl_framebuffer_get_dither_enabled ()

CoglBool            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.

Since 1.8

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

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

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_primitive_draw() which only support low level texture types that are directly supported by GPUs such as CoglTexture2D.

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.

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.

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_primitive_draw() which only support low level texture types that are directly supported by GPUs such as CoglTexture2D.

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.

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.

Since 1.10

Stability Level: Unstable

cogl_framebuffer_draw_rectangles ()

void                cogl_framebuffer_draw_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_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...

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.

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.

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

Since 1.10

Stability Level: Unstable

cogl_framebuffer_discard_buffers ()

void                cogl_framebuffer_discard_buffers    (CoglFramebuffer *framebuffer,
                                                         unsigned long  buffers);

Declares that the specified buffers no longer need to be referenced by any further rendering commands. This can be an important optimization to avoid subsequent frames of rendering depending on the results of a previous frame.

For example; some tile-based rendering GPUs are able to avoid allocating and accessing system memory for the depth and stencil buffer so long as these buffers are not required as input for subsequent frames and that can save a significant amount of memory bandwidth used to save and restore their contents to system memory between frames.

It is currently considered an error to try and explicitly discard the color buffer by passing COGL_BUFFER_BIT_COLOR. This is because the color buffer is already implicitly discard when you finish rendering to a CoglOnscreen framebuffer, and it's not meaningful to try and discard the color buffer of a CoglOffscreen framebuffer since they are single-buffered.

Since 1.8

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.

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

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.

Since 1.10

cogl_framebuffer_identity_matrix ()

void                cogl_framebuffer_identity_matrix    (CoglFramebuffer *framebuffer);

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

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.

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.

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 axis-vector specified by x, y and z. The rotation follows the right-hand thumb rule so for example rotating by 10 degrees about the axis-vector (0, 0, 1) causes a small counter-clockwise rotation.

Since 1.10

Stability Level: Unstable

cogl_framebuffer_rotate_euler ()

void                cogl_framebuffer_rotate_euler       (CoglFramebuffer *framebuffer,
                                                         const CoglEuler *euler);

Multiplies the current model-view matrix by one that rotates according to the rotation described by euler.

Since 2.0

Stability Level: Unstable

cogl_framebuffer_rotate_quaternion ()

void                cogl_framebuffer_rotate_quaternion  (CoglFramebuffer *framebuffer,
                                                         const CoglQuaternion *quaternion);

Multiplies the current model-view matrix by one that rotates according to the rotation described by quaternion.

Since 2.0

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.

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.

Since 1.10

Stability Level: Unstable

cogl_framebuffer_set_modelview_matrix ()

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

Sets matrix as 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.

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.

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.

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.

Since 1.10

Stability Level: Unstable

cogl_framebuffer_set_projection_matrix ()

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

Sets matrix as 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().

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

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

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_scissor_clip(), cogl_framebuffer_push_rectangle_clip() cogl_framebuffer_push_path_clip(), or cogl_framebuffer_push_primitive_clip().

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

Since 1.8

Stability Level: Unstable

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.

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:

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
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68

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

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