cogl_object_ref ()

void *
cogl_object_ref (void *object);

Increases the reference count of object by 1

[skip]

cogl_object_unref ()

void
cogl_object_unref (void *object);

Drecreases the reference count of object by 1; if the reference count reaches 0, the resources allocated by object will be freed

[skip]

cogl_object_get_user_data ()

void *
cogl_object_get_user_data (CoglObject *object,
                           CoglUserDataKey *key);

Finds the user data previously associated with object using the given key . If no user data has been associated with object for the given key this function returns NULL.

[skip]

Since: 1.4

cogl_object_set_user_data ()

void
cogl_object_set_user_data (CoglObject *object,
                           CoglUserDataKey *key,
                           void *user_data,
                           CoglUserDataDestroyCallback destroy);

Associates some private user_data with a given CoglObject. To later remove the association call cogl_object_set_user_data() with the same key but NULL for the user_data .

[skip]

Since: 1.4

cogl_handle_ref ()

CoglHandle
cogl_handle_ref (CoglHandle handle);

Increases the reference count of handle by 1

cogl_handle_unref ()

void
cogl_handle_unref (CoglHandle handle);

Drecreases the reference count of handle by 1; if the reference count reaches 0, the resources allocated by handle will be freed

CoglFuncPtr ()

void
(*CoglFuncPtr) (void);

The type used by cogl for function pointers, note that this type is used as a generic catch-all cast for function pointers and the actual arguments and return type may be different.

cogl_get_features ()

CoglFeatureFlags
cogl_get_features (void);

Returns all of the features supported by COGL.

Since: 0.8

cogl_features_available ()

CoglBool
cogl_features_available (CoglFeatureFlags features);

Checks whether the given COGL features are available. Multiple features can be checked for by or-ing them together with the '|' operator. TRUE is only returned if all of the requested features are available.

cogl_get_proc_address ()

CoglFuncPtr
cogl_get_proc_address (const char *name);

Gets a pointer to a given GL or GL ES extension function. This acts as a wrapper around glXGetProcAddress() or whatever is the appropriate function for the current backend.

cogl_get_option_group ()

GOptionGroup *
cogl_get_option_group (void);

Retrieves the GOptionGroup used by Cogl to parse the command line options. Clutter uses this to handle the Cogl command line options during its initialization process.

Since: 1.0

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

cogl_set_backface_culling_enabled ()

void
cogl_set_backface_culling_enabled (CoglBool setting);

Sets whether textures positioned so that their backface is showing should be hidden. This can be used to efficiently draw two-sided textures or fully closed cubes without enabling depth testing. This only affects calls to the cogl_rectangle* family of functions and cogl_vertex_buffer_draw*. Backface culling is disabled by default.

cogl_get_backface_culling_enabled ()

CoglBool
cogl_get_backface_culling_enabled (void);

Queries if backface culling has been enabled via cogl_set_backface_culling_enabled()

cogl_set_fog ()

void
cogl_set_fog (const CoglColor *fog_color,
              CoglFogMode mode,
              float density,
              float z_near,
              float z_far);

Enables fogging. Fogging causes vertices that are further away from the eye to be rendered with a different color. The color is determined according to the chosen fog mode; at it's simplest the color is linearly interpolated so that vertices at z_near are drawn fully with their original color and vertices at z_far are drawn fully with fog_color . Fogging will remain enabled until you call cogl_disable_fog().

cogl_disable_fog ()

void
cogl_disable_fog (void);

This function disables fogging, so primitives drawn afterwards will not be blended with any previously set fog color.

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

cogl_begin_gl ()

void
cogl_begin_gl (void);

We do not advise nor reliably support the interleaving of raw GL drawing and Cogl drawing functions, but if you insist, cogl_begin_gl() and cogl_end_gl() provide a simple mechanism that may at least give you a fighting chance of succeeding.

Note: this doesn't help you modify the behaviour of Cogl drawing functions through the modification of GL state; that will never be reliably supported, but if you are trying to do something like:

1
2
3
4
5
6

{
   - setup some OpenGL state.
   - draw using OpenGL (e.g. glDrawArrays() )
   - reset modified OpenGL state.
   - continue using Cogl to draw
}

You should surround blocks of drawing using raw GL with cogl_begin_gl() and cogl_end_gl():

1
2
3
4
5
6
7
8

{
   cogl_begin_gl ();
   - setup some OpenGL state.
   - draw using OpenGL (e.g. glDrawArrays() )
   - reset modified OpenGL state.
   cogl_end_gl ();
   - continue using Cogl to draw
}

Don't ever try and do:

1
2
3
4
5

{
   - setup some OpenGL state.
   - use Cogl to draw
   - reset modified OpenGL state.
}

When the internals of Cogl evolves, this is very liable to break.

This function will flush all batched primitives, and subsequently flush all internal Cogl state to OpenGL as if it were going to draw something itself.

The result is that the OpenGL modelview matrix will be setup; the state corresponding to the current source material will be set up and other world state such as backface culling, depth and fogging enabledness will be sent to OpenGL.

Again we would like to stress, we do not advise the use of this API and if possible we would prefer to improve Cogl than have developers require raw OpenGL.

Since: 1.0

cogl_end_gl ()

void
cogl_end_gl (void);

This is the counterpart to cogl_begin_gl() used to delimit blocks of drawing code using raw OpenGL. Please refer to cogl_begin_gl() for full details.

Since: 1.0

CoglObject

typedef struct _CoglObject CoglObject;

Ref Func: cogl_object_ref Unref Func: cogl_object_unref Set Value Func: cogl_object_value_set_object Get Value Func: cogl_object_value_get_object

CoglUserDataKey

typedef struct {
  int unused;
} CoglUserDataKey;

A CoglUserDataKey is used to declare a key for attaching data to a CoglObject using cogl_object_set_user_data. The typedef only exists as a formality to make code self documenting since only the unique address of a CoglUserDataKey is used.

Typically you would declare a static CoglUserDataKey and set private data on an object something like this:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

static CoglUserDataKey path_private_key;

static void
destroy_path_private_cb (void *data)
{
  g_free (data);
}

static void
my_path_set_data (CoglPath *path, void *data)
{
  cogl_object_set_user_data (COGL_OBJECT (path),
                             &private_key,
                             data,
                             destroy_path_private_cb);
}

Since: 1.4

COGL_INVALID_HANDLE

#define COGL_INVALID_HANDLE NULL

A COGL handle that is not valid, used for unitialized handles as well as error conditions.

CoglHandle

typedef void * CoglHandle;

Type used for storing references to cogl objects, the CoglHandle is a fully opaque type without any public data members.

enum CoglPixelFormat

Pixel formats used by Cogl. For the formats with a byte per component, the order of the components specify the order in increasing memory addresses. So for example COGL_PIXEL_FORMAT_RGB_888 would have the red component in the lowest address, green in the next address and blue after that regardless of the endianness of the system.

For the formats with non byte aligned components the component order specifies the order within a 16-bit or 32-bit number from most significant bit to least significant. So for COGL_PIXEL_FORMAT_RGB_565, the red component would be in bits 11-15, the green component would be in 6-11 and the blue component would be in 1-5. Therefore the order in memory depends on the endianness of the system.

When uploading a texture COGL_PIXEL_FORMAT_ANY can be used as the internal format. Cogl will try to pick the best format to use internally and convert the texture data if necessary.

Since: 0.8

enum CoglBufferTarget

Target flags for FBOs.

Since: 0.8

enum CoglBufferBit

Types of auxiliary buffers

Since: 1.0

enum CoglAttributeType

Data types for the components of a vertex attribute.

Since: 1.0

enum CoglFeatureFlags

Flags for the supported features.

Since: 0.8

enum CoglFogMode

The fog mode determines the equation used to calculate the fogging blend factor while fogging is enabled. The simplest COGL_FOG_MODE_LINEAR mode determines f as:

1

f = end - eye_distance / end - start

Where eye_distance is the distance of the current fragment in eye coordinates from the origin.

1

f = end - eye_distance / end - start

1

f = e ^ -(density * eye_distance)

1

f = e ^ -(density * eye_distance)^2

Since: 1.0

enum CoglReadPixelsFlags

Flags for cogl_framebuffer_read_pixels_into_bitmap()

Since: 1.0