Cogl.Framebuffer

g Cogl.Framebuffer Cogl.Framebuffer GObject.GInterface GObject.GInterface GObject.GInterface->Cogl.Framebuffer

Implementations:

Cogl.Onscreen

Methods

class

error_quark ()

allocate ()

cancel_fence_callback (closure)

clear (buffers, color)

clear4f (buffers, red, green, blue, alpha)

discard_buffers (buffers)

draw_attributes (pipeline, mode, first_vertex, n_vertices, attributes, n_attributes)

draw_indexed_attributes (pipeline, mode, first_vertex, n_vertices, indices, attributes, n_attributes)

draw_multitextured_rectangle (pipeline, x_1, y_1, x_2, y_2, tex_coords, tex_coords_len)

draw_primitive (pipeline, primitive)

draw_rectangle (pipeline, x_1, y_1, x_2, y_2)

draw_rectangles (pipeline, coordinates, n_rectangles)

draw_textured_rectangle (pipeline, x_1, y_1, x_2, y_2, s_1, t_1, s_2, t_2)

draw_textured_rectangles (pipeline, coordinates, n_rectangles)

finish ()

frustum (left, right, bottom, top, z_near, z_far)

get_alpha_bits ()

get_blue_bits ()

get_color_mask ()

get_context ()

get_depth_bits ()

get_depth_texture ()

get_depth_texture_enabled ()

get_depth_write_enabled ()

get_dither_enabled ()

get_green_bits ()

get_height ()

get_is_stereo ()

get_modelview_matrix ()

get_projection_matrix ()

get_red_bits ()

get_samples_per_pixel ()

get_stereo_mode ()

get_viewport4fv ()

get_viewport_height ()

get_viewport_width ()

get_viewport_x ()

get_viewport_y ()

get_width ()

identity_matrix ()

orthographic (x_1, y_1, x_2, y_2, near, far)

perspective (fov_y, aspect, z_near, z_far)

pop_clip ()

pop_matrix ()

push_matrix ()

push_primitive_clip (primitive, bounds_x1, bounds_y1, bounds_x2, bounds_y2)

push_rectangle_clip (x_1, y_1, x_2, y_2)

push_scissor_clip (x, y, width, height)

read_pixels (x, y, width, height, format, pixels)

read_pixels_into_bitmap (x, y, source, bitmap)

resolve_samples ()

resolve_samples_region (x, y, width, height)

rotate (angle, x, y, z)

rotate_euler (euler)

rotate_quaternion (quaternion)

scale (x, y, z)

set_color_mask (color_mask)

set_depth_texture_enabled (enabled)

set_depth_write_enabled (depth_write_enabled)

set_dither_enabled (dither_enabled)

set_modelview_matrix (matrix)

set_projection_matrix (matrix)

set_samples_per_pixel (samples_per_pixel)

set_stereo_mode (stereo_mode)

set_viewport (x, y, width, height)

transform (matrix)

translate (x, y, z)

Virtual Methods

None

Properties

None

Signals

None

Fields

None

Class Details

class Cogl.Framebuffer
Bases:

GObject.GInterface

classmethod error_quark()
Return type:

int

allocate()
Raises:

GLib.Error

Returns:

True if there were no error allocating the framebuffer, else False.

Return type:

int

Explicitly allocates a configured Cogl.Framebuffer 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.

New in version 1.8.

cancel_fence_callback(closure)
Parameters:

closure (Cogl.FenceClosure) – The Cogl.FenceClosure returned from cogl_framebuffer_add_fence_callback()

Removes a fence previously submitted with cogl_framebuffer_add_fence_callback(); the callback will not be called.

New in version 2.0.

clear(buffers, color)
Parameters:

  • buffers (int) – A mask of Cogl.BufferBit ‘s identifying which auxiliary buffers to clear

  • color (Cogl.Color) – The color to clear the color buffer too if specified in buffers.

Clears all the auxiliary buffers identified in the buffers mask, and if that includes the color buffer then the specified color is used.

New in version 1.8.

clear4f(buffers, red, green, blue, alpha)
Parameters:

  • buffers (int) – A mask of Cogl.BufferBit ‘s identifying which auxiliary buffers to clear

  • red (float) – The red component of color to clear the color buffer too if specified in buffers.

  • green (float) – The green component of color to clear the color buffer too if specified in buffers.

  • blue (float) – The blue component of color to clear the color buffer too if specified in buffers.

  • alpha (float) – The alpha component of color to clear the color buffer too if specified in buffers.

Clears all the auxiliary buffers identified in the buffers mask, and if that includes the color buffer then the specified color is used.

New in version 1.8.

discard_buffers(buffers)
Parameters:

buffers (int) – A Cogl.BufferBit mask of which ancillary buffers you want to discard.

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.BufferBit.COLOR. This is because the color buffer is already implicitly discard when you finish rendering to a Cogl.Onscreen framebuffer, and it’s not meaningful to try and discard the color buffer of a #CoglOffscreen framebuffer since they are single-buffered.

New in version 1.8.

draw_attributes(pipeline, mode, first_vertex, n_vertices, attributes, n_attributes)
Parameters:

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 self using the graphics processing pipeline described by pipeline.

The list of Cogl.Attribute s 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 Cogl.Texture2DSliced so it is the user’s responsibility to ensure that only low-level textures that can be directly sampled by a GPU such as Cogl.Texture2D, Cogl.TextureRectangle or Cogl.Texture3D 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()

New in version 1.10.

Deprecated since version 1.16: Use Cogl.Primitive s and Cogl.Primitive.draw() instead

draw_indexed_attributes(pipeline, mode, first_vertex, n_vertices, indices, attributes, n_attributes)
Parameters:

  • pipeline (Cogl.Pipeline) – A Cogl.Pipeline state object

  • mode (Cogl.VerticesMode) – The Cogl.VerticesMode defining the topology of vertices

  • first_vertex (int) – The vertex offset within the given attributes to draw from

  • n_vertices (int) – The number of vertices to draw from the given attributes

  • indices (Cogl.Indices) – The array of indices used by the GPU to lookup attribute data for each vertex.

  • attributes (Cogl.Attribute) – An array of pointers to Cogl.Attribute<– –>s defining vertex geometry

  • n_attributes (int) – The number of attributes in the attributes array.

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.VerticesMode.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 Cogl.Texture2DSliced so it is the user’s responsibility to ensure that only low-level textures that can be directly sampled by a GPU such as Cogl.Texture2D, Cogl.TextureRectangle or Cogl.Texture3D 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()

New in version 1.10.

Deprecated since version 1.16: Use Cogl.Primitive s and Cogl.Primitive.draw() instead

draw_multitextured_rectangle(pipeline, x_1, y_1, x_2, y_2, tex_coords, tex_coords_len)
Parameters:

  • pipeline (Cogl.Pipeline) – A Cogl.Pipeline state object

  • x_1 (float) – x coordinate upper left on screen.

  • y_1 (float) – y coordinate upper left on screen.

  • x_2 (float) – x coordinate lower right on screen.

  • y_2 (float) – y coordinate lower right on screen.

  • tex_coords ([float]) – 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.

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

Draws a textured rectangle to self 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 Cogl.Texture2DSliced 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 Cogl.Texture2D.

This api can not currently handle multiple high-level meta texture layers. The first layer may be a high level meta texture such as Cogl.Texture2DSliced but all other layers much be low level textures such as Cogl.Texture2D and additionally they should be textures that can be sampled using normalized coordinates (so not Cogl.TextureRectangle 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 Cogl.TextureRectangle 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.

New in version 1.10.

draw_primitive(pipeline, primitive)
Parameters:

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

This drawing api doesn’t support high-level meta texture types such as Cogl.Texture2DSliced so it is the user’s responsibility to ensure that only low-level textures that can be directly sampled by a GPU such as Cogl.Texture2D, Cogl.TextureRectangle or Cogl.Texture3D 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()

New in version 1.10.

Deprecated since version 1.16: Use Cogl.Primitive s and Cogl.Primitive.draw() instead

draw_rectangle(pipeline, x_1, y_1, x_2, y_2)
Parameters:

  • pipeline (Cogl.Pipeline) – A Cogl.Pipeline state object

  • x_1 (float) – X coordinate of the top-left corner

  • y_1 (float) – Y coordinate of the top-left corner

  • x_2 (float) – X coordinate of the bottom-right corner

  • y_2 (float) – Y coordinate of the bottom-right corner

Draws a rectangle to self 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().

New in version 1.10.

draw_rectangles(pipeline, coordinates, n_rectangles)
Parameters:

  • pipeline (Cogl.Pipeline) – A Cogl.Pipeline state object

  • coordinates ([float]) – 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).

  • n_rectangles (int) – number of rectangles defined in coordinates.

Draws a series of rectangles to self 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.

New in version 1.10.

draw_textured_rectangle(pipeline, x_1, y_1, x_2, y_2, s_1, t_1, s_2, t_2)
Parameters:

  • pipeline (Cogl.Pipeline) – A Cogl.Pipeline state object

  • x_1 (float) – x coordinate upper left on screen.

  • y_1 (float) – y coordinate upper left on screen.

  • x_2 (float) – x coordinate lower right on screen.

  • y_2 (float) – y coordinate lower right on screen.

  • s_1 (float) – S texture coordinate of the top-left coorner

  • t_1 (float) – T texture coordinate of the top-left coorner

  • s_2 (float) – S texture coordinate of the bottom-right coorner

  • t_2 (float) – T texture coordinate of the bottom-right coorner

Draws a textured rectangle to self 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 Cogl.Texture2DSliced 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 Cogl.Texture2D.

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 Cogl.TextureRectangle 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.

New in version 1.10.

draw_textured_rectangles(pipeline, coordinates, n_rectangles)
Parameters:

Draws a series of rectangles to self 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 Cogl.Texture2DSliced 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 Cogl.Texture2D.

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 Cogl.TextureRectangle texture which normally implies working with non-normalized texture coordinates this api should still be passed normalized texture coordinates.

New in version 1.10.

finish()

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.

New in version 1.10.

frustum(left, right, bottom, top, z_near, z_far)
Parameters:

  • left (float) – X position of the left clipping plane where it intersects the near clipping plane

  • right (float) – X position of the right clipping plane where it intersects the near clipping plane

  • bottom (float) – Y position of the bottom clipping plane where it intersects the near clipping plane

  • top (float) – Y position of the top clipping plane where it intersects the near clipping plane

  • z_near (float) – The distance to the near clipping plane (Must be positive)

  • z_far (float) – The distance to the far clipping plane (Must be positive)

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.

New in version 1.10.

get_alpha_bits()
Returns:

the number of bits

Return type:

int

Retrieves the number of alpha bits of self

New in version 1.8.

get_blue_bits()
Returns:

the number of bits

Return type:

int

Retrieves the number of blue bits of self

New in version 1.8.

get_color_mask()
Returns:

A Cogl.ColorMask

Return type:

Cogl.ColorMask

Gets the current Cogl.ColorMask of which channels would be written to the current framebuffer. Each bit set in the mask means that the corresponding color would be written.

New in version 1.8.

get_context()
Returns:

The Cogl.Context that the given self was instantiated within.

Return type:

Cogl.Context

Can be used to query the Cogl.Context a given self was instantiated within. This is the Cogl.Context that was passed to Cogl.Onscreen.new() for example.

New in version 1.8.

get_depth_bits()
Returns:

the number of bits

Return type:

int

Retrieves the number of depth bits of self

New in version 2.0.

get_depth_texture()
Returns:

the depth texture

Return type:

Cogl.Texture

Retrieves the depth buffer of self as a Cogl.Texture. You need to call Cogl.Framebuffer.get_depth_texture(fb, True); before using this function.

Calling this function implicitely allocates the framebuffer. The texture returned stays valid as long as the framebuffer stays valid.

New in version 1.14.

get_depth_texture_enabled()
Returns:

True if a depth texture has been enabled, else False.

Return type:

int

Queries whether texture based depth buffer has been enabled via Cogl.Framebuffer.set_depth_texture_enabled().

New in version 1.14.

get_depth_write_enabled()
Returns:

True if depth writing is enabled or False if not.

Return type:

int

Queries whether depth buffer writing is enabled for self. This can be controlled via Cogl.Framebuffer.set_depth_write_enabled().

New in version 1.18.

get_dither_enabled()
Returns:

True if dithering has been requested or False if not.

Return type:

int

Returns whether dithering has been requested for the given self. See Cogl.Framebuffer.set_dither_enabled() for more details about dithering.

This may return True even when the underlying self display pipeline does not support dithering. This value only represents the user’s request for dithering.

New in version 1.8.

get_green_bits()
Returns:

the number of bits

Return type:

int

Retrieves the number of green bits of self

New in version 1.8.

get_height()
Returns:

The height of self.

Return type:

int

Queries the current height of the given self.

New in version 1.8.

get_is_stereo()
Return type:

int

get_modelview_matrix()
Returns:

return location for the model-view matrix

Return type:

matrix: Cogl.Matrix

Stores the current model-view matrix in matrix.

New in version 1.10.

get_projection_matrix()
Returns:

return location for the projection matrix

Return type:

matrix: Cogl.Matrix

Stores the current projection matrix in matrix.

New in version 1.10.

get_red_bits()
Returns:

the number of bits

Return type:

int

Retrieves the number of red bits of self

New in version 1.8.

get_samples_per_pixel()
Returns:

The number of point samples made per pixel when rasterizing geometry or 0 if single-sample rendering has been chosen.

Return type:

int

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.

New in version 1.10.

get_stereo_mode()
Returns:

A Cogl.StereoMode

Return type:

Cogl.StereoMode

Gets the current Cogl.StereoMode, which defines which stereo buffers should be drawn to. See Cogl.Framebuffer.set_stereo_mode().

New in version 1.20.

get_viewport4fv()
Returns:

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

Return type:

viewport: [float]

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.

New in version 1.8.

get_viewport_height()
Returns:

The height of the viewport.

Return type:

float

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

New in version 1.8.

get_viewport_width()
Returns:

The width of the viewport.

Return type:

float

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

New in version 1.8.

get_viewport_x()
Returns:

The x coordinate of the viewport origin.

Return type:

float

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

New in version 1.8.

get_viewport_y()
Returns:

The y coordinate of the viewport origin.

Return type:

float

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

New in version 1.8.

get_width()
Returns:

The width of self.

Return type:

int

Queries the current width of the given self.

New in version 1.8.

identity_matrix()

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

New in version 1.10.

orthographic(x_1, y_1, x_2, y_2, near, far)
Parameters:

  • x_1 (float) – The x coordinate for the first vertical clipping plane

  • y_1 (float) – The y coordinate for the first horizontal clipping plane

  • x_2 (float) – The x coordinate for the second vertical clipping plane

  • y_2 (float) – The y coordinate for the second horizontal clipping plane

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

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

Replaces the current projection matrix with an orthographic projection matrix.

New in version 1.10.

perspective(fov_y, aspect, z_near, z_far)
Parameters:

  • fov_y (float) – Vertical field of view angle in degrees.

  • aspect (float) – The (width over height) aspect ratio for display

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

  • z_far (float) – The distance to the far clipping plane (Must be positive)

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.

New in version 1.10.

pop_clip()

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

New in version 1.10.

pop_matrix()

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

New in version 1.10.

push_matrix()

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

New in version 1.10.

push_primitive_clip(primitive, bounds_x1, bounds_y1, bounds_x2, bounds_y2)
Parameters:

  • primitive (Cogl.Primitive) – A Cogl.Primitive describing a flat 2D shape

  • bounds_x1 (float) – x coordinate for the top-left corner of the primitives bounds

  • bounds_y1 (float) – y coordinate for the top-left corner of the primitives bounds

  • bounds_x2 (float) – x coordinate for the bottom-right corner of the primitives bounds.

  • bounds_y2 (float) – y coordinate for the bottom-right corner of the primitives bounds.

Sets a new clipping area using a 2D shaped described with a Cogl.Primitive. 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().

New in version 1.10.

push_rectangle_clip(x_1, y_1, x_2, y_2)
Parameters:

  • x_1 (float) – x coordinate for top left corner of the clip rectangle

  • y_1 (float) – y coordinate for top left corner of the clip rectangle

  • x_2 (float) – x coordinate for bottom right corner of the clip rectangle

  • y_2 (float) – y coordinate for bottom right corner of the clip rectangle

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

New in version 1.10.

push_scissor_clip(x, y, width, height)
Parameters:

  • x (int) – left edge of the clip rectangle in window coordinates

  • y (int) – top edge of the clip rectangle in window coordinates

  • width (int) – width of the clip rectangle

  • height (int) – height of the clip rectangle

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

New in version 1.10.

read_pixels(x, y, width, height, format, pixels)
Parameters:

  • x (int) – The x position to read from

  • y (int) – The y position to read from

  • width (int) – The width of the region of rectangles to read

  • height (int) – The height of the region of rectangles to read

  • format (Cogl.PixelFormat) – The pixel format to store the data in

  • pixels (int) – The address of the buffer to store the data in

Returns:

True if the read succeeded or False otherwise.

Return type:

int

This is a convenience wrapper around Cogl.Framebuffer.read_pixels_into_bitmap() which allocates a temporary Cogl.Bitmap 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:

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

New in version 1.10.

read_pixels_into_bitmap(x, y, source, bitmap)
Parameters:
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.

Return type:

int

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.

New in version 1.10.

resolve_samples()

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.

New in version 1.8.

resolve_samples_region(x, y, width, height)
Parameters:

  • x (int) – top-left x coordinate of region to resolve

  • y (int) – top-left y coordinate of region to resolve

  • width (int) – width of region to resolve

  • height (int) – height of region to resolve

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.

New in version 1.8.

rotate(angle, x, y, z)
Parameters:

  • angle (float) – Angle in degrees to rotate.

  • x (float) – X-component of vertex to rotate around.

  • y (float) – Y-component of vertex to rotate around.

  • z (float) – Z-component of vertex to rotate around.

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.

New in version 1.10.

rotate_euler(euler)
Parameters:

euler (Cogl.Euler) – A Cogl.Euler

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

New in version 2.0.

rotate_quaternion(quaternion)
Parameters:

quaternion (Cogl.Quaternion) – A Cogl.Quaternion

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

New in version 2.0.

scale(x, y, z)
Parameters:

  • x (float) – Amount to scale along the x-axis

  • y (float) – Amount to scale along the y-axis

  • z (float) – Amount to scale along the z-axis

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

New in version 1.10.

set_color_mask(color_mask)
Parameters:

color_mask (Cogl.ColorMask) – A Cogl.ColorMask of which color channels to write to the current framebuffer.

Defines a bit mask of which color channels should be written to the given self. If a bit is set in color_mask that means that color will be written.

New in version 1.8.

set_depth_texture_enabled(enabled)
Parameters:

enabled (int) – True or False

If enabled is True, the depth buffer used when rendering to self is available as a texture. You can retrieve the texture with Cogl.Framebuffer.get_depth_texture().

It’s possible that your GPU does not support depth textures. You should check the Cogl.FeatureID.OGL_FEATURE_ID_DEPTH_TEXTURE feature before using this function. It’s not valid to call this function after the framebuffer has been allocated as the creation of the depth texture is done at allocation time.

New in version 1.14.

set_depth_write_enabled(depth_write_enabled)
Parameters:

depth_write_enabled (int) – True to enable depth writing or False to disable

Enables or disables depth buffer writing when rendering to self. If depth writing is enabled for both the framebuffer and the rendering pipeline, and the framebuffer has an associated depth buffer, depth information will be written to this buffer during rendering.

Depth buffer writing is enabled by default.

New in version 1.18.

set_dither_enabled(dither_enabled)
Parameters:

dither_enabled (int) – True to enable dithering or False to disable

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 self does not support dithering then this has no affect.

Dithering is enabled by default.

New in version 1.8.

set_modelview_matrix(matrix)
Parameters:

matrix (Cogl.Matrix) – the new model-view matrix

Sets matrix as the new model-view matrix.

New in version 1.10.

set_projection_matrix(matrix)
Parameters:

matrix (Cogl.Matrix) – the new projection matrix

Sets matrix as the new projection matrix.

New in version 1.10.

set_samples_per_pixel(samples_per_pixel)
Parameters:

samples_per_pixel (int) – The minimum number of samples per pixel

Requires that when rendering to self 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.

There are some semantic differences between single-sample rendering and multisampling with just 1 point sample such as it being redundant to use the Cogl.Framebuffer.resolve_samples() and Cogl.Framebuffer.resolve_samples_region() apis with single-sample rendering. It’s recommended that Cogl.Framebuffer.resolve_samples_region() be explicitly used at the end of rendering to a point sample buffer to minimize the number of samples that get resolved. By default Cogl will implicitly resolve all framebuffer samples but if only a small region of a framebuffer has changed this can lead to redundant work being done.

New in version 1.8.

set_stereo_mode(stereo_mode)
Parameters:

stereo_mode (Cogl.StereoMode) – A Cogl.StereoMode specifying which stereo buffers should be drawn tow.

Sets which stereo buffers should be drawn to. The default is Cogl.StereoMode.BOTH, which means that both the left and right buffers will be affected by drawing. For this to have an effect, the display system must support stereo drawables, and the framebuffer must have been created with stereo enabled. (See Cogl.OnscreenTemplate.set_stereo_enabled(), Cogl.Framebuffer.get_is_stereo().)

New in version 1.20.

set_viewport(x, y, width, height)
Parameters:

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

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

  • width (float) – The width of the viewport (only integers supported currently)

  • height (float) – The height of the viewport (only integers supported currently)

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.

New in version 1.8.

transform(matrix)
Parameters:

matrix (Cogl.Matrix) – the matrix to multiply with the current model-view

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

New in version 1.10.

translate(x, y, z)
Parameters:

  • x (float) – Distance to translate along the x-axis

  • y (float) – Distance to translate along the y-axis

  • z (float) – Distance to translate along the z-axis

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

New in version 1.10.