![]() |
![]() |
![]() |
Cogl 2.0 Reference Manual | ![]() |
---|---|---|---|---|
Top | Description |
CoglFramebuffer: The Framebuffer InterfaceCoglFramebuffer: The Framebuffer Interface — A common interface for manipulating framebuffers |
CoglFramebuffer; #define COGL_FRAMEBUFFER (X) #define cogl_framebuffer_allocate #define cogl_framebuffer_get_width #define cogl_framebuffer_get_height #define cogl_framebuffer_set_viewport #define cogl_framebuffer_get_viewport_x #define cogl_framebuffer_get_viewport_y #define cogl_framebuffer_get_viewport_width #define cogl_framebuffer_get_viewport_height #define cogl_framebuffer_get_viewport4fv #define cogl_framebuffer_get_red_bits #define cogl_framebuffer_get_green_bits #define cogl_framebuffer_get_blue_bits #define cogl_framebuffer_get_color_mask #define cogl_framebuffer_set_color_mask #define cogl_framebuffer_get_context #define cogl_framebuffer_clear #define cogl_framebuffer_clear4f #define cogl_framebuffer_swap_buffers #define cogl_framebuffer_swap_region #define cogl_framebuffer_add_swap_buffers_callback #define cogl_framebuffer_remove_swap_buffers_callback void cogl_framebuffer_finish (CoglFramebuffer *framebuffer
); #define cogl_get_draw_framebuffer void cogl_set_framebuffer (CoglFramebuffer *buffer
); void cogl_push_framebuffer (CoglFramebuffer *buffer
); void cogl_pop_framebuffer (void
);
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.
#define cogl_framebuffer_set_viewport cogl_framebuffer_set_viewport_EXP
#define cogl_framebuffer_get_viewport_x cogl_framebuffer_get_viewport_x_EXP
#define cogl_framebuffer_get_viewport_y cogl_framebuffer_get_viewport_y_EXP
#define cogl_framebuffer_get_viewport_width cogl_framebuffer_get_viewport_width_EXP
#define cogl_framebuffer_get_viewport_height cogl_framebuffer_get_viewport_height_EXP
#define cogl_framebuffer_get_viewport4fv cogl_framebuffer_get_viewport4fv_EXP
#define cogl_framebuffer_get_red_bits cogl_framebuffer_get_red_bits_EXP
Retrieves the number of red bits of framebuffer
|
a pointer to a CoglFramebuffer |
Returns : |
the number of bits |
Since 1.8
Stability Level: Unstable
#define cogl_framebuffer_get_green_bits cogl_framebuffer_get_green_bits_EXP
Retrieves the number of green bits of framebuffer
|
a pointer to a CoglFramebuffer |
Returns : |
the number of bits |
Since 1.8
Stability Level: Unstable
#define cogl_framebuffer_get_blue_bits cogl_framebuffer_get_blue_bits_EXP
Retrieves the number of blue bits of framebuffer
|
a pointer to a CoglFramebuffer |
Returns : |
the number of bits |
Since 1.8
Stability Level: Unstable
#define cogl_framebuffer_get_color_mask cogl_framebuffer_get_color_mask_EXP
Gets the current CoglColorMask of which channels would be written to the current framebuffer. Each bit set in the mask means that the corresponding color would be written.
|
a pointer to a CoglFramebuffer |
Returns : |
A CoglColorMask |
Since 1.8
Stability Level: Unstable
#define cogl_framebuffer_set_color_mask cogl_framebuffer_set_color_mask_EXP
Defines a bit mask of which color channels should be written to the
given framebuffer
. If a bit is set in color_mask
that means that
color will be written.
|
a pointer to a CoglFramebuffer |
|
A CoglColorMask of which color channels to write to the current framebuffer. |
Since 1.8
Stability Level: Unstable
#define cogl_framebuffer_clear cogl_framebuffer_clear_EXP
Clears all the auxiliary buffers identified in the buffers
mask, and if
that includes the color buffer then the specified color
is used.
|
A CoglFramebuffer |
|
A mask of CoglBufferBit's identifying which auxiliary buffers to clear |
|
The color to clear the color buffer too if specified in
buffers . |
Since 1.8
Stability Level: Unstable
#define cogl_framebuffer_clear4f cogl_framebuffer_clear4f_EXP
Clears all the auxiliary buffers identified in the buffers
mask, and if
that includes the color buffer then the specified color
is used.
|
A CoglFramebuffer |
|
A mask of CoglBufferBit's identifying which auxiliary buffers to clear |
|
The red component of color to clear the color buffer too if
specified in buffers . |
|
The green component of color to clear the color buffer too if
specified in buffers . |
|
The blue component of color to clear the color buffer too if
specified in buffers . |
|
The alpha component of color to clear the color buffer too if
specified in buffers . |
Since 1.8
Stability Level: Unstable
#define cogl_framebuffer_swap_buffers cogl_framebuffer_swap_buffers_EXP
Swaps the current back buffer being rendered too, to the front for display.
This function also implicitly discards the contents of the color, depth and
stencil buffers as if cogl_framebuffer_discard_buffers()
were used. The
significance of the discard is that you should not expect to be able to
start a new frame that incrementally builds on the contents of the previous
frame.
|
A CoglFramebuffer |
Since 1.8
Stability Level: Unstable
#define cogl_framebuffer_swap_region cogl_framebuffer_swap_region_EXP
Swaps a region of the back buffer being rendered too, to the front for
display. rectangles
represents the region as array of n_rectangles
each
defined by 4 sequential (x, y, width, height) integers.
This function also implicitly discards the contents of the color, depth and
stencil buffers as if cogl_framebuffer_discard_buffers()
were used. The
significance of the discard is that you should not expect to be able to
start a new frame that incrementally builds on the contents of the previous
frame.
|
A CoglFramebuffer |
|
An array of integer 4-tuples representing rectangles as (x, y, width, height) tuples. |
|
The number of 4-tuples to be read from rectangles
|
Since 1.8
Stability Level: Unstable
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.
|
A CoglFramebuffer pointer |
Since 1.10
Stability Level: Unstable
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.
|
A CoglFramebuffer object, either onscreen or offscreen. |
Since 1.2
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 |
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()
|
A CoglFramebuffer object, either onscreen or offscreen. |
Since 1.2