brl/mutter
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

docs: This improves the documentation for cogl_push_framebuffer

Browse Source 
This adds an example of how to setup a Clutter style 2D coordinate space
and clarifies what state is owned by a framebuffer. (projection,
modelview, viewport and clip stack)

When we expose more cogl_framebuffer API this example will hopefully be
migrated into a more extensive introduction to using framebuffers.
This commit is contained in:
Robert Bragg 2010-04-01 13:15:12 +01:00
parent d2d890a33e
commit 412a468d5e
1 changed files with 75 additions and 10 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

81
clutter/cogl/cogl/cogl.h
View File

@ -840,10 +840,9 @@ cogl_clip_stack_restore (void) G_GNUC_DEPRECATED;
* @buffer: The #CoglHandle of a Cogl framebuffer; either onscreen or
* offscreen.
*
* This redirects all subsequent drawing to the specified framebuffer. This
* can either be an offscreen buffer created with
* cogl_offscreen_new_to_texture () or you can revert to your original
* onscreen window 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
*/
@ -855,10 +854,76 @@ cogl_set_framebuffer (CoglHandle buffer);
* @buffer: The #CoglHandle of a Cogl framebuffer; either onscreen or
* offscreen.
*
* Redirects all subsequent drawing to the specified framebuffer. This
* can either be an offscreen buffer created with
* cogl_offscreen_new_to_texture () or you can revert to your original
* onscreen window 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:
* <itemizedlist>
* <li>The projection matrix</li>
* <li>The modelview matrix stack</li>
* <li>The viewport</li>
* <li>The clip stack</li>
* </itemizedlist>
* 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:
*
* |[
* 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 (CoglHandle framebuffer,
* unsigned int framebuffer_width,
* unsigned int framebuffer_height)
* {
* ClutterActor *stage = clutter_stage_get_default ();
* ClutterPerspective perspective;
*
* clutter_stage_get_perspective (CLUTTER_STAGE (stage), &perspective);
*
* cogl_push_framebuffer (framebuffer);
* setup_viewport (framebuffer_width,
* framebuffer_height,
* perspective->fovy,
* perspective.aspect,
* perspective.z_near,
* perspective.z_far);
* cogl_pop_framebuffer ();
* }
* ]|
*
* The previous framebuffer can be restored by calling cogl_pop_framebuffer()
*