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) CoglBool cogl_framebuffer_allocate (CoglFramebuffer *framebuffer
,CoglError **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
); CoglPixelFormat cogl_framebuffer_get_color_format (CoglFramebuffer *framebuffer
); int cogl_framebuffer_get_red_bits (CoglFramebuffer *framebuffer
); int cogl_framebuffer_get_green_bits (CoglFramebuffer *framebuffer
); int cogl_framebuffer_get_blue_bits (CoglFramebuffer *framebuffer
); int cogl_framebuffer_get_alpha_bits (CoglFramebuffer *framebuffer
); int cogl_framebuffer_get_depth_bits (CoglFramebuffer *framebuffer
); CoglColorMask cogl_framebuffer_get_color_mask (CoglFramebuffer *framebuffer
); void cogl_framebuffer_set_color_mask (CoglFramebuffer *framebuffer
,CoglColorMask color_mask
); int cogl_framebuffer_get_samples_per_pixel (CoglFramebuffer *framebuffer
); void cogl_framebuffer_set_samples_per_pixel (CoglFramebuffer *framebuffer
,int samples_per_pixel
); void cogl_framebuffer_resolve_samples (CoglFramebuffer *framebuffer
); void cogl_framebuffer_resolve_samples_region (CoglFramebuffer *framebuffer
,int x
,int y
,int width
,int height
); CoglContext * cogl_framebuffer_get_context (CoglFramebuffer *framebuffer
); void cogl_framebuffer_clear (CoglFramebuffer *framebuffer
,CoglBufferBit buffers
,const CoglColor *color
); void cogl_framebuffer_clear4f (CoglFramebuffer *framebuffer
,CoglBufferBit buffers
,float red
,float green
,float blue
,float alpha
); CoglBool cogl_framebuffer_read_pixels_into_bitmap (CoglFramebuffer *framebuffer
,int x
,int y
,CoglReadPixelsFlags source
,CoglBitmap *bitmap
,CoglError **error
); CoglBool cogl_framebuffer_read_pixels (CoglFramebuffer *framebuffer
,int x
,int y
,int width
,int height
,CoglPixelFormat format
,uint8_t *pixels
); void cogl_framebuffer_set_dither_enabled (CoglFramebuffer *framebuffer
,CoglBool dither_enabled
); CoglBool cogl_framebuffer_get_dither_enabled (CoglFramebuffer *framebuffer
); void cogl_framebuffer_draw_rectangle (CoglFramebuffer *framebuffer
,CoglPipeline *pipeline
,float x_1
,float y_1
,float x_2
,float y_2
); 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
); 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
); void cogl_framebuffer_draw_rectangles (CoglFramebuffer *framebuffer
,CoglPipeline *pipeline
,const float *coordinates
,unsigned int n_rectangles
); void cogl_framebuffer_draw_textured_rectangles (CoglFramebuffer *framebuffer
,CoglPipeline *pipeline
,const float *coordinates
,unsigned int n_rectangles
); void cogl_framebuffer_discard_buffers (CoglFramebuffer *framebuffer
,CoglBufferBit buffers
); void cogl_framebuffer_finish (CoglFramebuffer *framebuffer
); void cogl_framebuffer_push_matrix (CoglFramebuffer *framebuffer
); void cogl_framebuffer_pop_matrix (CoglFramebuffer *framebuffer
); void cogl_framebuffer_identity_matrix (CoglFramebuffer *framebuffer
); void cogl_framebuffer_scale (CoglFramebuffer *framebuffer
,float x
,float y
,float z
); void cogl_framebuffer_translate (CoglFramebuffer *framebuffer
,float x
,float y
,float z
); void cogl_framebuffer_rotate (CoglFramebuffer *framebuffer
,float angle
,float x
,float y
,float z
); void cogl_framebuffer_rotate_euler (CoglFramebuffer *framebuffer
,const CoglEuler *euler
); void cogl_framebuffer_rotate_quaternion (CoglFramebuffer *framebuffer
,const CoglQuaternion *quaternion
); void cogl_framebuffer_transform (CoglFramebuffer *framebuffer
,const CoglMatrix *matrix
); void cogl_framebuffer_get_modelview_matrix (CoglFramebuffer *framebuffer
,CoglMatrix *matrix
); void cogl_framebuffer_set_modelview_matrix (CoglFramebuffer *framebuffer
,const CoglMatrix *matrix
); void cogl_framebuffer_perspective (CoglFramebuffer *framebuffer
,float fov_y
,float aspect
,float z_near
,float z_far
); void cogl_framebuffer_frustum (CoglFramebuffer *framebuffer
,float left
,float right
,float bottom
,float top
,float z_near
,float z_far
); void cogl_framebuffer_orthographic (CoglFramebuffer *framebuffer
,float x_1
,float y_1
,float x_2
,float y_2
,float near
,float far
); void cogl_framebuffer_get_projection_matrix (CoglFramebuffer *framebuffer
,CoglMatrix *matrix
); void cogl_framebuffer_set_projection_matrix (CoglFramebuffer *framebuffer
,const CoglMatrix *matrix
); void cogl_framebuffer_push_scissor_clip (CoglFramebuffer *framebuffer
,int x
,int y
,int width
,int height
); void cogl_framebuffer_push_rectangle_clip (CoglFramebuffer *framebuffer
,float x_1
,float y_1
,float x_2
,float y_2
); void cogl_framebuffer_push_primitive_clip (CoglFramebuffer *framebuffer
,CoglPrimitive *primitive
,float bounds_x1
,float bounds_y1
,float bounds_x2
,float bounds_y2
); void cogl_framebuffer_pop_clip (CoglFramebuffer *framebuffer
);
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 multisampling (an antialiasing 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_with_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.
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.

A CoglFramebuffer 

A pointer to a CoglError for returning exceptions. 
Returns : 
TRUE if there were no error allocating the framebuffer, else FALSE . 
Since 1.8
Stability Level: Unstable
int cogl_framebuffer_get_width (CoglFramebuffer *framebuffer
);
Queries the current width of the given framebuffer
.

A CoglFramebuffer 
Returns : 
The width of framebuffer . 
Since 1.8
Stability Level: Unstable
int cogl_framebuffer_get_height (CoglFramebuffer *framebuffer
);
Queries the current height of the given framebuffer
.

A CoglFramebuffer 
Returns : 
The height of framebuffer . 
Since 1.8
Stability Level: Unstable
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 topleft 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.

A CoglFramebuffer 

The topleft x coordinate of the viewport origin (only integers supported currently) 

The topleft y coordinate of the viewport origin (only integers supported currently) 

The width of the viewport (only integers supported currently) 

The height of the viewport (only integers supported currently) 
Since 1.8
Stability Level: Unstable
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.

A CoglFramebuffer 
Returns : 
The x coordinate of the viewport origin. 
Since 1.8
Stability Level: Unstable
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.

A CoglFramebuffer 
Returns : 
The y coordinate of the viewport origin. 
Since 1.8
Stability Level: Unstable
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.

A CoglFramebuffer 
Returns : 
The width of the viewport. 
Since 1.8
Stability Level: Unstable
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.

A CoglFramebuffer 
Returns : 
The height of the viewport. 
Since 1.8
Stability Level: Unstable
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.

A CoglFramebuffer 

A pointer to an array of 4 floats to receive the (x, y, width, height) components of the current viewport. [out callerallocates][array fixedsize=4] 
Since 1.8
Stability Level: Unstable
CoglPixelFormat cogl_framebuffer_get_color_format (CoglFramebuffer *framebuffer
);
Queries the common CoglPixelFormat of all color buffers attached
to this framebuffer. For an offscreen framebuffer created with
cogl_offscreen_new_with_texture()
this will correspond to the format
of the texture.

A CoglFramebuffer framebuffer 
Since 1.8
Stability Level: Unstable
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
int cogl_framebuffer_get_alpha_bits (CoglFramebuffer *framebuffer
);
Retrieves the number of alpha bits of framebuffer

a pointer to a CoglFramebuffer 
Returns : 
the number of bits 
Since 1.8
Stability Level: Unstable
int cogl_framebuffer_get_depth_bits (CoglFramebuffer *framebuffer
);
Retrieves the number of depth bits of framebuffer

a pointer to a CoglFramebuffer 
Returns : 
the number of bits 
Since 2.0
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
int cogl_framebuffer_get_samples_per_pixel
(CoglFramebuffer *framebuffer
);
Gets the number of points that are sampled perpixel when
rasterizing geometry. Usually by default this will return 0 which
means that singlesample 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.

A CoglFramebuffer framebuffer 
Returns : 
The number of point samples made per pixel when rasterizing geometry or 0 if singlesample rendering has been chosen. 
Since 1.10
Stability Level: Unstable
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 onchip and so avoid increased demand on system memory
bandwidth.
By default this value is usually set to 0 and that is referred to as "singlesample" rendering. A value of 1 or greater is referred to as "multisample" rendering.
cogl_framebuffer_resolve_samples()
and
cogl_framebuffer_resolve_samples_region()
apis with singlesample
rendering.
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.

A CoglFramebuffer framebuffer 

The minimum number of samples per pixel 
Since 1.8
Stability Level: Unstable
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.

A CoglFramebuffer framebuffer 
Since 1.8
Stability Level: Unstable
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 atleast 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.

A CoglFramebuffer framebuffer 

topleft x coordinate of region to resolve 

topleft y coordinate of region to resolve 

width of region to resolve 

height of region to resolve 
Since 1.8
Stability Level: Unstable
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.

A CoglFramebuffer 
Returns : 
The CoglContext that the given framebuffer was
instantiated within. 
Since 1.8
Stability Level: Unstable
void cogl_framebuffer_clear (CoglFramebuffer *framebuffer
,CoglBufferBit 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
,CoglBufferBit 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
CoglBool cogl_framebuffer_read_pixels_into_bitmap (CoglFramebuffer *framebuffer
,int x
,int y
,CoglReadPixelsFlags source
,CoglBitmap *bitmap
,CoglError **error
);
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 nonpremultiplied 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.

A CoglFramebuffer 

The x position to read from 

The y position to read from 

Identifies which auxillary buffer you want to read (only COGL_READ_PIXELS_COLOR_BUFFER supported currently) 

The bitmap to store the results in. 

A CoglError to catch exceptional errors 
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. 
Since 1.10
Stability Level: Unstable
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 
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); 

A CoglFramebuffer 

The x position to read from 

The y position to read from 

The width of the region of rectangles to read 

The height of the region of rectangles to read 

The pixel format to store the data in 

The address of the buffer to store the data in 
Returns : 
TRUE if the read succeeded or FALSE otherwise. 
Since 1.10
Stability Level: Unstable
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 halftoning 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.

a pointer to a CoglFramebuffer 

TRUE to enable dithering or FALSE to disable 
Since 1.8
Stability Level: Unstable
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.
TRUE
even when the underlying framebuffer
display pipeline does not support dithering. This value only represents
the user's request for dithering.

a pointer to a CoglFramebuffer 
Returns : 
TRUE if dithering has been requested or FALSE if not. 
Since 1.8
Stability Level: Unstable
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
).
cogl_framebuffer_draw_textured_rectangle()
.

A destination CoglFramebuffer 

A CoglPipeline state object 

X coordinate of the topleft corner 

Y coordinate of the topleft corner 

X coordinate of the bottomright corner 

Y coordinate of the bottomright corner 
Since 1.10
Stability Level: Unstable
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 lowlevel textures.
This is unlike lowlevel drawing apis such as cogl_primitive_draw()
which only support low level texture types that are directly
supported by GPUs such as CoglTexture2D.
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.
pipeline
layers which normally implies working
with nonnormalized texture coordinates this api should still be
passed normalized texture coordinates.

A destination CoglFramebuffer 

A CoglPipeline state object 

x coordinate upper left on screen. 

y coordinate upper left on screen. 

x coordinate lower right on screen. 

y coordinate lower right on screen. 

S texture coordinate of the topleft coorner 

T texture coordinate of the topleft coorner 

S texture coordinate of the bottomright coorner 

T texture coordinate of the bottomright coorner 
Since 1.10
Stability Level: Unstable
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 lowlevel textures. This is unlike lowlevel 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.

A destination CoglFramebuffer 

A CoglPipeline state object 

x coordinate upper left on screen. 

y coordinate upper left on screen. 

x coordinate lower right on screen. 

y coordinate lower right on screen. 

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. [in][array][transfer none] 

The length of the tex_coords array. (For one layer
and one group of texture coordinates, this would be 4) 
Since 1.10
Stability Level: Unstable
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.

A destination CoglFramebuffer 

A CoglPipeline state object 

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). [in][array][transfer none] 

number of rectangles defined in coordinates . 
Since 1.10
Stability Level: Unstable
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 lowlevel textures.
This is unlike lowlevel 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.

A destination CoglFramebuffer 

A CoglPipeline state object 

an array containing
groups of 8 float values: [x_1, y_1, x_2, y_2, s_1, t_1, s_2, t_2]
that have the same meaning as the arguments for
cogl_framebuffer_draw_textured_rectangle() . [in][array][transfer none]


number of rectangles to coordinates to draw 
Since 1.10
Stability Level: Unstable
void cogl_framebuffer_discard_buffers (CoglFramebuffer *framebuffer
,CoglBufferBit 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 tilebased 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 singlebuffered.

A CoglFramebuffer 

A CoglBufferBit mask of which ancillary buffers you want to discard. 
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_framebuffer_push_matrix (CoglFramebuffer *framebuffer
);
Copies the current modelview matrix onto the matrix stack. The matrix
can later be restored with cogl_framebuffer_pop_matrix()
.

A CoglFramebuffer pointer 
Since 1.10
void cogl_framebuffer_pop_matrix (CoglFramebuffer *framebuffer
);
Restores the modelview matrix on the top of the matrix stack.

A CoglFramebuffer pointer 
Since 1.10
void cogl_framebuffer_identity_matrix (CoglFramebuffer *framebuffer
);
Resets the current modelview matrix to the identity matrix.

A CoglFramebuffer pointer 
Since 1.10
Stability Level: Unstable
void cogl_framebuffer_scale (CoglFramebuffer *framebuffer
,float x
,float y
,float z
);
Multiplies the current modelview matrix by one that scales the x, y and z axes by the given values.

A CoglFramebuffer pointer 

Amount to scale along the xaxis 

Amount to scale along the yaxis 

Amount to scale along the zaxis 
Since 1.10
Stability Level: Unstable
void cogl_framebuffer_translate (CoglFramebuffer *framebuffer
,float x
,float y
,float z
);
Multiplies the current modelview matrix by one that translates the model along all three axes according to the given values.

A CoglFramebuffer pointer 

Distance to translate along the xaxis 

Distance to translate along the yaxis 

Distance to translate along the zaxis 
Since 1.10
Stability Level: Unstable
void cogl_framebuffer_rotate (CoglFramebuffer *framebuffer
,float angle
,float x
,float y
,float z
);
Multiplies the current modelview matrix by one that rotates the
model around the axisvector specified by x
, y
and z
. The
rotation follows the righthand thumb rule so for example rotating
by 10 degrees about the axisvector (0, 0, 1) causes a small
counterclockwise rotation.

A CoglFramebuffer pointer 

Angle in degrees to rotate. 

Xcomponent of vertex to rotate around. 

Ycomponent of vertex to rotate around. 

Zcomponent of vertex to rotate around. 
Since 1.10
Stability Level: Unstable
void cogl_framebuffer_rotate_euler (CoglFramebuffer *framebuffer
,const CoglEuler *euler
);
Multiplies the current modelview matrix by one that rotates
according to the rotation described by euler
.

A CoglFramebuffer pointer 

A CoglEuler 
Since 2.0
Stability Level: Unstable
void cogl_framebuffer_rotate_quaternion (CoglFramebuffer *framebuffer
,const CoglQuaternion *quaternion
);
Multiplies the current modelview matrix by one that rotates
according to the rotation described by quaternion
.

A CoglFramebuffer pointer 

A CoglQuaternion 
Since 2.0
Stability Level: Unstable
void cogl_framebuffer_transform (CoglFramebuffer *framebuffer
,const CoglMatrix *matrix
);
Multiplies the current modelview matrix by the given matrix.

A CoglFramebuffer pointer 

the matrix to multiply with the current modelview 
Since 1.10
Stability Level: Unstable
void cogl_framebuffer_get_modelview_matrix (CoglFramebuffer *framebuffer
,CoglMatrix *matrix
);
Stores the current modelview matrix in matrix
.

A CoglFramebuffer pointer 

return location for the modelview matrix. [out] 
Since 1.10
Stability Level: Unstable
void cogl_framebuffer_set_modelview_matrix (CoglFramebuffer *framebuffer
,const CoglMatrix *matrix
);
Sets matrix
as the new modelview matrix.

A CoglFramebuffer pointer 

the new modelview matrix 
Since 1.10
Stability Level: Unstable
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.
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.

A CoglFramebuffer pointer 

Vertical field of view angle in degrees. 

The (width over height) aspect ratio for display 

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

The distance to the far clipping plane (Must be positive) 
Since 1.10
Stability Level: Unstable
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.

A CoglFramebuffer pointer 

X position of the left clipping plane where it intersects the near clipping plane 

X position of the right clipping plane where it intersects the near clipping plane 

Y position of the bottom clipping plane where it intersects the near clipping plane 

Y position of the top clipping plane where it intersects the near clipping plane 

The distance to the near clipping plane (Must be positive) 

The distance to the far clipping plane (Must be positive) 
Since 1.10
Stability Level: Unstable
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.

A CoglFramebuffer pointer 

The x coordinate for the first vertical clipping plane 

The y coordinate for the first horizontal clipping plane 

The x coordinate for the second vertical clipping plane 

The y coordinate for the second horizontal clipping plane 

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

The distance to the far clipping plane (will be negative if the plane is behind the viewer) 
Since 1.10
Stability Level: Unstable
void cogl_framebuffer_get_projection_matrix (CoglFramebuffer *framebuffer
,CoglMatrix *matrix
);
Stores the current projection matrix in matrix
.

A CoglFramebuffer pointer 

return location for the projection matrix. [out] 
Since 1.10
Stability Level: Unstable
void cogl_framebuffer_set_projection_matrix (CoglFramebuffer *framebuffer
,const CoglMatrix *matrix
);
Sets matrix
as the new projection matrix.

A CoglFramebuffer pointer 

the new projection matrix 
Since 1.10
Stability Level: Unstable
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 modelview matrix.
The rectangle is intersected with the current clip region. To undo
the effect of this function, call cogl_framebuffer_pop_clip()
.

A CoglFramebuffer pointer 

left edge of the clip rectangle in window coordinates 

top edge of the clip rectangle in window coordinates 

width of the clip rectangle 

height of the clip rectangle 
Since 1.10
Stability Level: Unstable
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 modelview matrix.
The rectangle is intersected with the current clip region. To undo
the effect of this function, call cogl_framebuffer_pop_clip()
.

A CoglFramebuffer pointer 

x coordinate for top left corner of the clip rectangle 

y coordinate for top left corner of the clip rectangle 

x coordinate for bottom right corner of the clip rectangle 

y coordinate for bottom right corner of the clip rectangle 
Since 1.10
Stability Level: Unstable
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 modelview matrix and
the silhouette is intersected with the previous clipping area. To
restore the previous clipping area, call
cogl_framebuffer_pop_clip()
.

A CoglFramebuffer pointer 

A CoglPrimitive describing a flat 2D shape 

x coordinate for the topleft corner of the primitives bounds 

y coordinate for the topleft corner of the primitives bounds 

x coordinate for the bottomright corner of the primitives bounds. 

y coordinate for the bottomright corner of the primitives bounds. 
Since 1.10
Stability Level: Unstable
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()
.

A CoglFramebuffer pointer 
Since 1.10
Stability Level: Unstable