CoglContext

typedef struct _CoglContext CoglContext;

cogl_is_context ()

CoglBool            cogl_is_context                     (void *object);

Gets whether the given object references an existing context object.

Since 1.10

Stability Level: Unstable

cogl_context_new ()

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

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

Since 1.8

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.

Since 1.8

Stability Level: Unstable

enum CoglFeatureID

typedef enum {
  COGL_FEATURE_ID_TEXTURE_NPOT_BASIC = 1,
  COGL_FEATURE_ID_TEXTURE_NPOT_MIPMAP,
  COGL_FEATURE_ID_TEXTURE_NPOT_REPEAT,
  COGL_FEATURE_ID_TEXTURE_NPOT,
  COGL_FEATURE_ID_TEXTURE_RECTANGLE,
  COGL_FEATURE_ID_TEXTURE_3D,
  COGL_FEATURE_ID_GLSL,
  COGL_FEATURE_ID_ARBFP,
  COGL_FEATURE_ID_OFFSCREEN,
  COGL_FEATURE_ID_OFFSCREEN_MULTISAMPLE,
  COGL_FEATURE_ID_ONSCREEN_MULTIPLE,
  COGL_FEATURE_ID_UNSIGNED_INT_INDICES,
  COGL_FEATURE_ID_DEPTH_RANGE,
  COGL_FEATURE_ID_POINT_SPRITE,
  COGL_FEATURE_ID_MAP_BUFFER_FOR_READ,
  COGL_FEATURE_ID_MAP_BUFFER_FOR_WRITE,
  COGL_FEATURE_ID_MIRRORED_REPEAT,
  COGL_FEATURE_ID_SWAP_BUFFERS_EVENT,
  COGL_FEATURE_ID_GLES2_CONTEXT,
  COGL_FEATURE_ID_DEPTH_TEXTURE,
  COGL_FEATURE_ID_PRESENTATION_TIME,
  COGL_FEATURE_ID_FENCE,
  COGL_FEATURE_ID_PER_VERTEX_POINT_SIZE,
  COGL_FEATURE_ID_TEXTURE_RG,
  COGL_FEATURE_ID_BUFFER_AGE,
} 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().

Since 1.10

cogl_has_feature ()

CoglBool            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.

Since 1.10

Stability Level: Unstable

cogl_has_features ()

CoglBool            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.

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.

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.

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.

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.

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.

cogl_transform ()

void                cogl_transform                      (const CoglMatrix *matrix);

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

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.

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.

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. 

Since 1.0

cogl_get_modelview_matrix ()

void                cogl_get_modelview_matrix           (CoglMatrix *matrix);

Stores the current model-view matrix in matrix.

cogl_set_modelview_matrix ()

void                cogl_set_modelview_matrix           (CoglMatrix *matrix);

Loads matrix as the new model-view matrix.

cogl_get_projection_matrix ()

void                cogl_get_projection_matrix          (CoglMatrix *matrix);

Stores the current projection matrix in matrix.

cogl_set_projection_matrix ()

void                cogl_set_projection_matrix          (CoglMatrix *matrix);

Loads matrix as the new projection matrix.

cogl_set_viewport ()

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

Replaces the current viewport with the given values.

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.

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

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.

Since 1.0

cogl_set_source_color4ub ()

void                cogl_set_source_color4ub            (uint8_t red,
                                                         uint8_t green,
                                                         uint8_t blue,
                                                         uint8_t 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.

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.

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

Since 1.0

cogl_get_source ()

void *              cogl_get_source                     (void);

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

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

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_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.

enum CoglReadPixelsFlags

typedef enum {
 /*< prefix=COGL_READ_PIXELS >*/
  COGL_READ_PIXELS_COLOR_BUFFER = 1L << 0
} CoglReadPixelsFlags;

Flags for cogl_framebuffer_read_pixels_into_bitmap()

Since 1.0

cogl_read_pixels ()

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

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.

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