The Top-Level Context

The Top-Level Context — The top level application context.

Functions

Types and Values

Description

A CoglContext is the top most sandbox of Cogl state for an application or toolkit. Its main purpose is to act as a sandbox for the memory management of state objects. Normally an application will only create a single context since there is no way to share resources between contexts.

For those familiar with OpenGL or perhaps Cairo it should be understood that unlike these APIs a Cogl context isn't a rendering context as such. In other words Cogl doesn't aim to provide a state machine style model for configuring rendering parameters. Most rendering state in Cogl is directly associated with user managed objects called pipelines and geometry is drawn with a specific pipeline object to a framebuffer object and those 3 things fully define the state for drawing. This is an important part of Cogl's design since it helps you write orthogonal rendering components that can all access the same GPU without having to worry about what state other components have left you with.

Functions

cogl_context_new ()

CoglContext *
cogl_context_new (CoglDisplay *display,
                  GError **error);

Creates a new CoglContext which acts as an application sandbox for any state objects that are allocated.

Parameters

display

A CoglDisplay pointer

 

error

A GError return location.

 

Returns

A newly allocated CoglContext.

[transfer full]

Since 1.8

Stability Level: Unstable


cogl_is_context ()

gboolean
cogl_is_context (void *object);

Gets whether the given object references an existing context object.

Parameters

object

An object or NULL

 

Returns

TRUE if the handle references a CoglContext, FALSE otherwise

Since 1.10

Stability Level: Unstable


cogl_context_get_display ()

CoglDisplay *
cogl_context_get_display (CoglContext *context);

Retrieves the CoglDisplay that is internally associated with the given context . This will return the same CoglDisplay that was passed to cogl_context_new() or if NULL was passed to cogl_context_new() then this function returns a pointer to the display that was automatically setup internally.

Parameters

context

A CoglContext pointer

 

Returns

The CoglDisplay associated with the given context .

[transfer none]

Since 1.8

Stability Level: Unstable


cogl_has_feature ()

gboolean
cogl_has_feature (CoglContext *context,
                  CoglFeatureID feature);

Checks if a given feature is currently available

Cogl does not aim to be a lowest common denominator API, it aims to expose all the interesting features of GPUs to application which means applications have some responsibility to explicitly check that certain features are available before depending on them.

Parameters

context

A CoglContext pointer

 

feature

A CoglFeatureID

 

Returns

TRUE if the feature is currently supported or FALSE if not.

Since 1.10

Stability Level: Unstable


cogl_has_features ()

gboolean
cogl_has_features (CoglContext *context,
                   ...);

Checks if a list of features are all currently available.

This checks all of the listed features using cogl_has_feature() and returns TRUE if all the features are available or FALSE otherwise.

Parameters

context

A CoglContext pointer

 

...

A 0 terminated list of CoglFeatureIDs

 

Returns

TRUE if all the features are available, FALSE otherwise.

Since 1.10

Stability Level: Unstable


CoglFeatureCallback ()

void
(*CoglFeatureCallback) (CoglFeatureID feature,
                        void *user_data);

A callback used with cogl_foreach_feature() for enumerating all context level features supported by Cogl.

Parameters

feature

A single feature currently supported by Cogl

 

user_data

A private pointer passed to cogl_foreach_feature().

 

Since 0.10

Stability Level: Unstable


cogl_foreach_feature ()

void
cogl_foreach_feature (CoglContext *context,
                      CoglFeatureCallback callback,
                      void *user_data);

Iterates through all the context level features currently supported for a given context and for each feature callback is called.

Parameters

context

A CoglContext pointer

 

callback

A CoglFeatureCallback called for each supported feature

 

user_data

Private data to pass to the callback

 

Since 1.10

Stability Level: Unstable


cogl_push_matrix ()

void
cogl_push_matrix (void);

Stores the current model-view matrix on the matrix stack. The matrix can later be restored with cogl_pop_matrix().


cogl_pop_matrix ()

void
cogl_pop_matrix (void);

Restores the current model-view matrix from the matrix stack.


cogl_scale ()

void
cogl_scale (float x,
            float y,
            float z);

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

Parameters

x

Amount to scale along the x-axis

 

y

Amount to scale along the y-axis

 

z

Amount to scale along the z-axis

 

cogl_translate ()

void
cogl_translate (float x,
                float y,
                float z);

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

Parameters

x

Distance to translate along the x-axis

 

y

Distance to translate along the y-axis

 

z

Distance to translate along the z-axis

 

cogl_rotate ()

void
cogl_rotate (float angle,
             float x,
             float y,
             float z);

Multiplies the current model-view matrix by one that rotates the model around the vertex specified by x , y and z . The rotation follows the right-hand thumb rule so for example rotating by 10 degrees about the vertex (0, 0, 1) causes a small counter-clockwise rotation.

Parameters

angle

Angle in degrees to rotate.

 

x

X-component of vertex to rotate around.

 

y

Y-component of vertex to rotate around.

 

z

Z-component of vertex to rotate around.

 

cogl_transform ()

void
cogl_transform (const CoglMatrix *matrix);

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

Parameters

matrix

the matrix to multiply with the current model-view

 

Since 1.4


cogl_frustum ()

void
cogl_frustum (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.

Parameters

left

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

 

right

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

 

bottom

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

 

top

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

 

z_near

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

 

z_far

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

 

Since 0.8.2


cogl_perspective ()

void
cogl_perspective (float fovy,
                  float aspect,
                  float z_near,
                  float z_far);

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.

Parameters

fovy

Vertical field of view angle in degrees.

 

aspect

The (width over height) aspect ratio for display

 

z_near

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

 

z_far

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

 

cogl_ortho ()

void
cogl_ortho (float left,
            float right,
            float bottom,
            float top,
            float near,
            float far);

Replaces the current projection matrix with an orthographic projection matrix. See Figure 1, “” to see how the matrix is calculated.

Figure 1. 


This function copies the arguments from OpenGL's glOrtho() even though they are unnecessarily confusing due to the z near and z far arguments actually being a "distance" from the origin, where negative values are behind the viewer, instead of coordinates for the z clipping planes which would have been consistent with the left, right bottom and top arguments.

Parameters

left

The coordinate for the left clipping plane

 

right

The coordinate for the right clipping plane

 

bottom

The coordinate for the bottom clipping plane

 

top

The coordinate for the top clipping plane

 

near

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

 

far

The distance for the far clipping plane (negative if the plane is behind the viewer)

 

Since 1.0


cogl_get_modelview_matrix ()

void
cogl_get_modelview_matrix (CoglMatrix *matrix);

Stores the current model-view matrix in matrix .

Parameters

matrix

return location for the model-view matrix.

[out]

cogl_set_modelview_matrix ()

void
cogl_set_modelview_matrix (CoglMatrix *matrix);

Loads matrix as the new model-view matrix.

Parameters

matrix

the new model-view matrix

 

cogl_get_projection_matrix ()

void
cogl_get_projection_matrix (CoglMatrix *matrix);

Stores the current projection matrix in matrix .

Parameters

matrix

return location for the projection matrix.

[out]

cogl_set_projection_matrix ()

void
cogl_set_projection_matrix (CoglMatrix *matrix);

Loads matrix as the new projection matrix.

Parameters

matrix

the new projection matrix

 

cogl_set_viewport ()

void
cogl_set_viewport (int x,
                   int y,
                   int width,
                   int height);

cogl_set_viewport is deprecated and should not be used in newly-written code.

Replaces the current viewport with the given values.

Parameters

x

X offset of the viewport

 

y

Y offset of the viewport

 

width

Width of the viewport

 

height

Height of the viewport

 

Since 1.2


cogl_get_viewport ()

void
cogl_get_viewport (float v[4]);

Stores the current viewport in v . v [0] and v [1] get the x and y position of the viewport and v [2] and v [3] get the width and height.

Parameters

v

pointer to a 4 element array of floats to receive the viewport dimensions.

[out][array fixed-size=4]

cogl_set_source ()

void
cogl_set_source (void *material);

This function changes the material at the top of the source stack. The material at the top of this stack defines the GPU state used to process subsequent primitives, such as rectangles drawn with cogl_rectangle() or vertices drawn using cogl_vertex_buffer_draw().

Parameters

material

A CoglMaterial

 

Since 1.0


cogl_set_source_color ()

void
cogl_set_source_color (const CoglColor *color);

This is a convenience function for creating a solid fill source material from the given color. This color will be used for any subsequent drawing operation.

The color will be premultiplied by Cogl, so the color should be non-premultiplied. For example: use (1.0, 0.0, 0.0, 0.5) for semi-transparent red.

See also cogl_set_source_color4ub() and cogl_set_source_color4f() if you already have the color components.

Parameters

color

a CoglColor

 

Since 1.0


cogl_set_source_color4ub ()

void
cogl_set_source_color4ub (guint8 red,
                          guint8 green,
                          guint8 blue,
                          guint8 alpha);

This is a convenience function for creating a solid fill source material from the given color using unsigned bytes for each component. This color will be used for any subsequent drawing operation.

The value for each component is an unsigned byte in the range between 0 and 255.

Parameters

red

value of the red channel, between 0 and 255

 

green

value of the green channel, between 0 and 255

 

blue

value of the blue channel, between 0 and 255

 

alpha

value of the alpha channel, between 0 and 255

 

Since 1.0


cogl_set_source_color4f ()

void
cogl_set_source_color4f (float red,
                         float green,
                         float blue,
                         float alpha);

This is a convenience function for creating a solid fill source material from the given color using normalized values for each component. This color will be used for any subsequent drawing operation.

The value for each component is a fixed point number in the range between 0 and 1.0. If the values passed in are outside that range, they will be clamped.

Parameters

red

value of the red channel, between 0 and 1.0

 

green

value of the green channel, between 0 and 1.0

 

blue

value of the blue channel, between 0 and 1.0

 

alpha

value of the alpha channel, between 0 and 1.0

 

Since 1.0


cogl_set_source_texture ()

void
cogl_set_source_texture (CoglTexture *texture);

This is a convenience function for creating a material with the first layer set to texture and setting that material as the source with cogl_set_source.

Note: There is no interaction between calls to cogl_set_source_color and cogl_set_source_texture. If you need to blend a texture with a color then you can create a simple material like this:

material = cogl_material_new ();
cogl_material_set_color4ub (material, 0xff, 0x00, 0x00, 0x80);
cogl_material_set_layer (material, 0, tex_handle);
cogl_set_source (material);

Parameters

texture

The CoglTexture you want as your source

 

Since 1.0


cogl_get_source ()

void *
cogl_get_source (void);

Returns the current source material as previously set using cogl_set_source().

You should typically consider the returned material immutable and not try to change any of its properties unless you own a reference to that material. At times you may be able to get a reference to an internally managed materials and the result of modifying such materials is undefined.

Returns

The current source material.

Since 1.6


cogl_push_source ()

void
cogl_push_source (void *material);

Pushes the given material to the top of the source stack. The material at the top of this stack defines the GPU state used to process later primitives as defined by cogl_set_source().

Parameters

material

A CoglMaterial

 

Since 1.6


cogl_pop_source ()

void
cogl_pop_source (void);

Removes the material at the top of the source stack. The material at the top of this stack defines the GPU state used to process later primitives as defined by cogl_set_source().

Since 1.6


COGL_TYPE_BUFFER_BIT

#define COGL_TYPE_BUFFER_BIT (cogl_buffer_bit_get_type())

cogl_clear ()

void
cogl_clear (const CoglColor *color,
            unsigned long  buffers);

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

Parameters

color

Background color to clear to

 

buffers

A mask of CoglBufferBit's identifying which auxiliary buffers to clear

 

cogl_read_pixels ()

void
cogl_read_pixels (int x,
                  int y,
                  int width,
                  int height,
                  CoglReadPixelsFlags source,
                  CoglPixelFormat format,
                  guint8 *pixels);

cogl_read_pixels is deprecated and should not be used in newly-written code.

This reads a rectangle of pixels from the current framebuffer where position (0, 0) is the top left. The pixel at (x, y) is the first read, and the data is returned with a rowstride of (width * 4).

Currently Cogl assumes that the framebuffer is in a premultiplied format so if format 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.

Parameters

x

The window x position to start reading from

 

y

The window y position to start reading from

 

width

The width of the rectangle you want to read

 

height

The height of the rectangle you want to read

 

source

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

 

format

The pixel format you want the result in (only COGL_PIXEL_FORMAT_RGBA_8888 supported currently)

 

pixels

The location to write the pixel data.

 

cogl_flush ()

void
cogl_flush (void);

This function should only need to be called in exceptional circumstances.

As an optimization Cogl drawing functions may batch up primitives internally, so if you are trying to use raw GL outside of Cogl you stand a better chance of being successful if you ask Cogl to flush any batched geometry before making your state changes.

It only ensure that the underlying driver is issued all the commands necessary to draw the batched primitives. It provides no guarantees about when the driver will complete the rendering.

This provides no guarantees about the GL state upon returning and to avoid confusing Cogl you should aim to restore any changes you make before resuming use of Cogl.

If you are making state changes with the intention of affecting Cogl drawing primitives you are 100% on your own since you stand a good chance of conflicting with Cogl internals. For example clutter-gst which currently uses direct GL calls to bind ARBfp programs will very likely break when Cogl starts to use ARBfb programs itself for the material API.

Since 1.0

Types and Values

enum CoglFeatureID

All the capabilities that can vary between different GPUs supported by Cogl. Applications that depend on any of these features should explicitly check for them using cogl_has_feature() or cogl_has_features().

Members

COGL_FEATURE_ID_TEXTURE_NPOT_BASIC

The hardware supports non power of two textures, but you also need to check the COGL_FEATURE_ID_TEXTURE_NPOT_MIPMAP and COGL_FEATURE_ID_TEXTURE_NPOT_REPEAT features to know if the hardware supports npot texture mipmaps or repeat modes other than COGL_RENDERER_PIPELINE_WRAP_MODE_CLAMP_TO_EDGE respectively.

 

COGL_FEATURE_ID_TEXTURE_NPOT_MIPMAP

Mipmapping is supported in conjuntion with non power of two textures.

 

COGL_FEATURE_ID_TEXTURE_NPOT_REPEAT

Repeat modes other than COGL_RENDERER_PIPELINE_WRAP_MODE_CLAMP_TO_EDGE are supported by the hardware.

 

COGL_FEATURE_ID_TEXTURE_NPOT

Non power of two textures are supported by the hardware. This is a equivalent to the COGL_FEATURE_ID_TEXTURE_NPOT_BASIC, COGL_FEATURE_ID_TEXTURE_NPOT_MIPMAP and COGL_FEATURE_ID_TEXTURE_NPOT_REPEAT features combined.

 

COGL_FEATURE_ID_TEXTURE_RECTANGLE

Support for rectangular textures with non-normalized texture coordinates.

 

COGL_FEATURE_ID_TEXTURE_3D

3D texture support

 

COGL_FEATURE_ID_GLSL

GLSL support

 

COGL_FEATURE_ID_ARBFP

ARBFP support

 

COGL_FEATURE_ID_OFFSCREEN

Offscreen rendering support

 

COGL_FEATURE_ID_OFFSCREEN_MULTISAMPLE

Multisample support for offscreen framebuffers

 

COGL_FEATURE_ID_ONSCREEN_MULTIPLE

Multiple onscreen framebuffers supported.

 

COGL_FEATURE_ID_UNSIGNED_INT_INDICES

Set if COGL_RENDERER_INDICES_TYPE_UNSIGNED_INT is supported in cogl_indices_new().

 

COGL_FEATURE_ID_DEPTH_RANGE

cogl_pipeline_set_depth_range() support

 

COGL_FEATURE_ID_POINT_SPRITE

Whether cogl_pipeline_set_layer_point_sprite_coords_enabled() is supported.

 

COGL_FEATURE_ID_MAP_BUFFER_FOR_READ

Whether cogl_buffer_map() is supported with CoglBufferAccess including read support.

 

COGL_FEATURE_ID_MAP_BUFFER_FOR_WRITE

Whether cogl_buffer_map() is supported with CoglBufferAccess including write support.

 

COGL_FEATURE_ID_MIRRORED_REPEAT

Whether COGL_PIPELINE_WRAP_MODE_MIRRORED_REPEAT is supported.

 

COGL_FEATURE_ID_SWAP_BUFFERS_EVENT

Available if the window system supports reporting an event for swap buffer completions.

 

Since 1.10


enum CoglReadPixelsFlags

Flags for cogl_read_pixels()

Members

COGL_READ_PIXELS_COLOR_BUFFER

Read from the color buffer

 

Since 1.0