![]() |
![]() |
![]() |
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) gboolean cogl_framebuffer_allocate (CoglFramebuffer *framebuffer
,GError **error
); int cogl_framebuffer_get_width (CoglFramebuffer *framebuffer
); int cogl_framebuffer_get_height (CoglFramebuffer *framebuffer
); void cogl_framebuffer_set_viewport (CoglFramebuffer *framebuffer
,float x
,float y
,float width
,float height
); float cogl_framebuffer_get_viewport_x (CoglFramebuffer *framebuffer
); float cogl_framebuffer_get_viewport_y (CoglFramebuffer *framebuffer
); float cogl_framebuffer_get_viewport_width (CoglFramebuffer *framebuffer
); float cogl_framebuffer_get_viewport_height (CoglFramebuffer *framebuffer
); void cogl_framebuffer_get_viewport4fv (CoglFramebuffer *framebuffer
,float *viewport
); int cogl_framebuffer_get_red_bits (CoglFramebuffer *framebuffer
); int cogl_framebuffer_get_green_bits (CoglFramebuffer *framebuffer
); int cogl_framebuffer_get_blue_bits (CoglFramebuffer *framebuffer
); CoglColorMask cogl_framebuffer_get_color_mask (CoglFramebuffer *framebuffer
); void cogl_framebuffer_set_color_mask (CoglFramebuffer *framebuffer
,CoglColorMask color_mask
); CoglContext * cogl_framebuffer_get_context (CoglFramebuffer *framebuffer
); void cogl_framebuffer_clear (CoglFramebuffer *framebuffer
,unsigned long buffers
,const CoglColor *color
); void cogl_framebuffer_clear4f (CoglFramebuffer *framebuffer
,unsigned long buffers
,float red
,float green
,float blue
,float alpha
); void cogl_framebuffer_swap_buffers (CoglFramebuffer *framebuffer
); void cogl_framebuffer_swap_region (CoglFramebuffer *framebuffer
,const int *rectangles
,int n_rectangles
); unsigned int cogl_framebuffer_add_swap_buffers_callback (CoglFramebuffer *framebuffer
,CoglSwapBuffersNotify callback
,void *user_data
); void cogl_framebuffer_remove_swap_buffers_callback (CoglFramebuffer *framebuffer
,unsigned int id
); CoglFramebuffer * cogl_get_draw_framebuffer (void
); 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.
gboolean cogl_framebuffer_allocate (CoglFramebuffer *framebuffer
,GError **error
);
void cogl_framebuffer_set_viewport (CoglFramebuffer *framebuffer
,float x
,float y
,float width
,float height
);
float cogl_framebuffer_get_viewport_x (CoglFramebuffer *framebuffer
);
float cogl_framebuffer_get_viewport_y (CoglFramebuffer *framebuffer
);
float cogl_framebuffer_get_viewport_width (CoglFramebuffer *framebuffer
);
float cogl_framebuffer_get_viewport_height
(CoglFramebuffer *framebuffer
);
void cogl_framebuffer_get_viewport4fv (CoglFramebuffer *framebuffer
,float *viewport
);
int cogl_framebuffer_get_red_bits (CoglFramebuffer *framebuffer
);
Retrieves the number of red bits of framebuffer
|
a pointer to a CoglFramebuffer |
Returns : |
the number of bits |
Since 1.8
Stability Level: Unstable
int cogl_framebuffer_get_green_bits (CoglFramebuffer *framebuffer
);
Retrieves the number of green bits of framebuffer
|
a pointer to a CoglFramebuffer |
Returns : |
the number of bits |
Since 1.8
Stability Level: Unstable
int cogl_framebuffer_get_blue_bits (CoglFramebuffer *framebuffer
);
Retrieves the number of blue bits of framebuffer
|
a pointer to a CoglFramebuffer |
Returns : |
the number of bits |
Since 1.8
Stability Level: Unstable
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.
|
a pointer to a CoglFramebuffer |
Returns : |
A CoglColorMask |
Since 1.8
Stability Level: Unstable
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.
|
a pointer to a CoglFramebuffer |
|
A CoglColorMask of which color channels to write to the current framebuffer. |
Since 1.8
Stability Level: Unstable
CoglContext * cogl_framebuffer_get_context (CoglFramebuffer *framebuffer
);
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.
|
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
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.
|
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
void cogl_framebuffer_swap_region (CoglFramebuffer *framebuffer
,const int *rectangles
,int n_rectangles
);
unsigned int cogl_framebuffer_add_swap_buffers_callback (CoglFramebuffer *framebuffer
,CoglSwapBuffersNotify callback
,void *user_data
);
void cogl_framebuffer_remove_swap_buffers_callback (CoglFramebuffer *framebuffer
,unsigned int id
);
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