General API

General API — General purpose API

Synopsis

#define             COGL_INVALID_HANDLE
typedef             CoglHandle;
void                (*CoglFuncPtr)                      (void);
#define             COGL_PIXEL_FORMAT_24
#define             COGL_PIXEL_FORMAT_32
#define             COGL_A_BIT
#define             COGL_BGR_BIT
#define             COGL_AFIRST_BIT
#define             COGL_PREMULT_BIT
#define             COGL_UNORDERED_MASK
#define             COGL_UNPREMULT_MASK
enum                CoglPixelFormat;
enum                CoglBufferTarget;

gboolean            cogl_create_context                 (void);
void                cogl_destroy_context                (void);

enum                CoglFeatureFlags;
CoglFeatureFlags    cogl_get_features                   (void);
gboolean            cogl_features_available             (CoglFeatureFlags features);
gboolean            cogl_check_extension                (const gchar *name,
                                                         const gchar *ext);
CoglFuncPtr         cogl_get_proc_address               (const gchar *name);

void                cogl_perspective                    (float fovy,
                                                         float aspect,
                                                         float z_near,
                                                         float z_far);
void                cogl_frustum                        (float left,
                                                         float right,
                                                         float bottom,
                                                         float top,
                                                         float z_near,
                                                         float z_far);
void                cogl_setup_viewport                 (guint width,
                                                         guint height,
                                                         float fovy,
                                                         float aspect,
                                                         float z_near,
                                                         float z_far);
void                cogl_viewport                       (guint width,
                                                         guint height);
void                cogl_get_modelview_matrix           (CoglMatrix *matrix);
void                cogl_get_projection_matrix          (CoglMatrix *matrix);
void                cogl_get_viewport                   (float v[4]);

void                cogl_push_matrix                    (void);
void                cogl_pop_matrix                     (void);
void                cogl_scale                          (float x,
                                                         float y,
                                                         float z);
void                cogl_translate                      (float x,
                                                         float y,
                                                         float z);
void                cogl_rotate                         (float angle,
                                                         float x,
                                                         float y,
                                                         float z);

void                cogl_clear                          (const CoglColor *color);
void                cogl_get_bitmasks                   (gint *red,
                                                         gint *green,
                                                         gint *blue,
                                                         gint *alpha);
void                cogl_enable_depth_test              (gboolean setting);
void                cogl_enable_backface_culling        (gboolean setting);

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

void                cogl_set_source                     (CoglHandle material);
void                cogl_set_source_color               (const CoglColor *color);
void                cogl_set_source_color4ub            (guint8 red,
                                                         guint8 green,
                                                         guint8 blue,
                                                         guint8 alpha);
void                cogl_set_source_color4f             (float red,
                                                         float green,
                                                         float blue,
                                                         float alpha);
void                cogl_set_source_texture             (CoglHandle texture_handle);

Description

General utility functions for COGL.

Details

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 gpointer CoglHandle;

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


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_PIXEL_FORMAT_24

#define COGL_PIXEL_FORMAT_24    2


COGL_PIXEL_FORMAT_32

#define COGL_PIXEL_FORMAT_32    3


COGL_A_BIT

#define COGL_A_BIT              (1 << 4)


COGL_BGR_BIT

#define COGL_BGR_BIT            (1 << 5)


COGL_AFIRST_BIT

#define COGL_AFIRST_BIT         (1 << 6)


COGL_PREMULT_BIT

#define COGL_PREMULT_BIT        (1 << 7)


COGL_UNORDERED_MASK

#define COGL_UNORDERED_MASK     0x0F


COGL_UNPREMULT_MASK

#define COGL_UNPREMULT_MASK     0x7F


enum CoglPixelFormat

typedef enum
{
  COGL_PIXEL_FORMAT_ANY           = 0,
  COGL_PIXEL_FORMAT_A_8           = 1 | COGL_A_BIT,

  COGL_PIXEL_FORMAT_RGB_565       = 4,
  COGL_PIXEL_FORMAT_RGBA_4444     = 5 | COGL_A_BIT,
  COGL_PIXEL_FORMAT_RGBA_5551     = 6 | COGL_A_BIT,
  COGL_PIXEL_FORMAT_YUV           = 7,
  COGL_PIXEL_FORMAT_G_8           = 8,
  
  COGL_PIXEL_FORMAT_RGB_888       =  COGL_PIXEL_FORMAT_24,

  COGL_PIXEL_FORMAT_BGR_888       = (COGL_PIXEL_FORMAT_24 |
                                     COGL_BGR_BIT),

  COGL_PIXEL_FORMAT_RGBA_8888     =  COGL_PIXEL_FORMAT_32 |
                                     COGL_A_BIT,

  COGL_PIXEL_FORMAT_BGRA_8888     = (COGL_PIXEL_FORMAT_32 |
                                     COGL_A_BIT           |
                                     COGL_BGR_BIT),

  COGL_PIXEL_FORMAT_ARGB_8888     = (COGL_PIXEL_FORMAT_32 |
                                     COGL_A_BIT           |
                                     COGL_AFIRST_BIT),

  COGL_PIXEL_FORMAT_ABGR_8888     = (COGL_PIXEL_FORMAT_32 |
                                     COGL_A_BIT           |
                                     COGL_BGR_BIT         |
                                     COGL_AFIRST_BIT),

  COGL_PIXEL_FORMAT_RGBA_8888_PRE = (COGL_PIXEL_FORMAT_32 |
                                     COGL_A_BIT           |
                                     COGL_PREMULT_BIT),

  COGL_PIXEL_FORMAT_BGRA_8888_PRE = (COGL_PIXEL_FORMAT_32 |
                                     COGL_A_BIT           |
                                     COGL_PREMULT_BIT     |
                                     COGL_BGR_BIT),

  COGL_PIXEL_FORMAT_ARGB_8888_PRE = (COGL_PIXEL_FORMAT_32 |
                                     COGL_A_BIT           |
                                     COGL_PREMULT_BIT     |
                                     COGL_AFIRST_BIT),

  COGL_PIXEL_FORMAT_ABGR_8888_PRE = (COGL_PIXEL_FORMAT_32 |
                                     COGL_A_BIT           |
                                     COGL_PREMULT_BIT     |
                                     COGL_BGR_BIT         |
                                     COGL_AFIRST_BIT),
  
  COGL_PIXEL_FORMAT_RGBA_4444_PRE = (COGL_PIXEL_FORMAT_RGBA_4444 |
                                     COGL_A_BIT                  |
                                     COGL_PREMULT_BIT),

  COGL_PIXEL_FORMAT_RGBA_5551_PRE = (COGL_PIXEL_FORMAT_RGBA_5551 |
                                     COGL_A_BIT                  |
                                     COGL_PREMULT_BIT),
  
  
} CoglPixelFormat;

Pixel formats used by COGL.

COGL_PIXEL_FORMAT_ANY

Any format

COGL_PIXEL_FORMAT_A_8

8 bits alpha mask

COGL_PIXEL_FORMAT_RGB_565

RGB, 16 bits

COGL_PIXEL_FORMAT_RGBA_4444

RGBA, 16 bits

COGL_PIXEL_FORMAT_RGBA_5551

RGBA, 16 bits

COGL_PIXEL_FORMAT_YUV

FIXME

COGL_PIXEL_FORMAT_G_8

FIXME

COGL_PIXEL_FORMAT_RGB_888

RGB, 24 bits

COGL_PIXEL_FORMAT_BGR_888

BGR, 24 bits

COGL_PIXEL_FORMAT_RGBA_8888

RGBA, 32 bits

COGL_PIXEL_FORMAT_BGRA_8888

BGRA, 32 bits

COGL_PIXEL_FORMAT_ARGB_8888

ARGB, 32 bits

COGL_PIXEL_FORMAT_ABGR_8888

ABGR, 32 bits

COGL_PIXEL_FORMAT_RGBA_8888_PRE

Premultiplied RGBA, 32 bits

COGL_PIXEL_FORMAT_BGRA_8888_PRE

Premultiplied BGRA, 32 bits

COGL_PIXEL_FORMAT_ARGB_8888_PRE

Premultiplied ARGB, 32 bits

COGL_PIXEL_FORMAT_ABGR_8888_PRE

Premultiplied ABGR, 32 bits

COGL_PIXEL_FORMAT_RGBA_4444_PRE

Premultiplied RGBA, 16 bits

COGL_PIXEL_FORMAT_RGBA_5551_PRE

Premultiplied RGBA, 16 bits

Since 0.8


enum CoglBufferTarget

typedef enum
{
  COGL_WINDOW_BUFFER      = (1 << 1),
  COGL_MASK_BUFFER        = (1 << 2),
  COGL_OFFSCREEN_BUFFER   = (1 << 3)
} CoglBufferTarget;

Target flags for FBOs.

COGL_WINDOW_BUFFER

FIXME

COGL_MASK_BUFFER

FIXME

COGL_OFFSCREEN_BUFFER

FIXME

Since 0.8


cogl_create_context ()

gboolean            cogl_create_context                 (void);

FIXME

Returns :


cogl_destroy_context ()

void                cogl_destroy_context                (void);

FIXME


enum CoglFeatureFlags

typedef enum
{
  COGL_FEATURE_TEXTURE_RECTANGLE      = (1 << 1),
  COGL_FEATURE_TEXTURE_NPOT           = (1 << 2),
  COGL_FEATURE_TEXTURE_YUV            = (1 << 3),
  COGL_FEATURE_TEXTURE_READ_PIXELS    = (1 << 4),
  COGL_FEATURE_SHADERS_GLSL           = (1 << 5),
  COGL_FEATURE_OFFSCREEN              = (1 << 6),
  COGL_FEATURE_OFFSCREEN_MULTISAMPLE  = (1 << 7),
  COGL_FEATURE_OFFSCREEN_BLIT         = (1 << 8),
  COGL_FEATURE_FOUR_CLIP_PLANES       = (1 << 9),
  COGL_FEATURE_STENCIL_BUFFER         = (1 << 10),
  COGL_FEATURE_VBOS		      = (1 << 11)
} CoglFeatureFlags;

Flags for the supported features.

COGL_FEATURE_TEXTURE_RECTANGLE

ARB_texture_rectangle support

COGL_FEATURE_TEXTURE_NPOT

ARB_texture_non_power_of_two support

COGL_FEATURE_TEXTURE_YUV

ycbcr conversion support

COGL_FEATURE_TEXTURE_READ_PIXELS

glReadPixels() support

COGL_FEATURE_SHADERS_GLSL

GLSL support

COGL_FEATURE_OFFSCREEN

FBO support

COGL_FEATURE_OFFSCREEN_MULTISAMPLE

Multisample support on FBOs

COGL_FEATURE_OFFSCREEN_BLIT

Blit support on FBOs

COGL_FEATURE_FOUR_CLIP_PLANES

At least 4 clip planes available

COGL_FEATURE_STENCIL_BUFFER

Stencil buffer support

COGL_FEATURE_VBOS

VBO support

Since 0.8


cogl_get_features ()

CoglFeatureFlags    cogl_get_features                   (void);

Returns all of the features supported by COGL.

Returns :

A logical OR of all the supported COGL features.

Since 0.8


cogl_features_available ()

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

features :

A bitmask of features to check for

Returns :

TRUE if the features are available, FALSE otherwise.

cogl_check_extension ()

gboolean            cogl_check_extension                (const gchar *name,
                                                         const gchar *ext);

Check whether name occurs in list of extensions in ext.

name :

extension to check for

ext :

list of extensions

Returns :

TRUE if the extension occurs in the list, FALSE otherwize.

cogl_get_proc_address ()

CoglFuncPtr         cogl_get_proc_address               (const gchar *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.

name :

the name of the function.

Returns :

a pointer to the requested function or NULL if the function is not available.

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.

fovy :

Vertical of view angle in degrees.

aspect :

Aspect ratio of diesplay

z_near :

Nearest visible point

z_far :

Furthest visible point along the z-axis

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 the given viewing frustum.

left :

Left clipping plane

right :

Right clipping plane

bottom :

Bottom clipping plane

top :

Top clipping plane

z_near :

Nearest visible point

z_far :

Furthest visible point along the z-axis

Since 0.8.2


cogl_setup_viewport ()

void                cogl_setup_viewport                 (guint width,
                                                         guint height,
                                                         float fovy,
                                                         float aspect,
                                                         float z_near,
                                                         float z_far);

Replaces the current viewport and projection matrix with the given values. The viewport is placed at the top left corner of the window with the given width and height. The projection matrix is replaced with one that has a viewing angle of fovy along the y-axis and a view scaled according to aspect along the x-axis. The view is clipped according to z_near and z_far on the z-axis.

width :

Width of the viewport

height :

Height of the viewport

fovy :

Field of view angle in degrees

aspect :

Aspect ratio to determine the field of view along the x-axis

z_near :

Nearest visible point along the z-axis

z_far :

Furthest visible point along the z-axis

cogl_viewport ()

void                cogl_viewport                       (guint width,
                                                         guint height);

Replace the current viewport with the given values.

width :

Width of the viewport

height :

Height of the viewport

Since 0.8.2


cogl_get_modelview_matrix ()

void                cogl_get_modelview_matrix           (CoglMatrix *matrix);

Stores the current model-view matrix in matrix.

matrix :

pointer to a CoglMatrix to recieve the matrix

cogl_get_projection_matrix ()

void                cogl_get_projection_matrix          (CoglMatrix *matrix);

Stores the current projection matrix in matrix.

matrix :

pointer to a CoglMatrix to recieve the matrix

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.

v :

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

cogl_push_matrix ()

void                cogl_push_matrix                    (void);

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

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

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.

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.

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

void                cogl_clear                          (const CoglColor *color);

Clears the color buffer to color. The depth buffer and stencil buffers are also cleared.

color :

Background color to clear to

cogl_get_bitmasks ()

void                cogl_get_bitmasks                   (gint *red,
                                                         gint *green,
                                                         gint *blue,
                                                         gint *alpha);

Gets the number of bitplanes used for each of the color components in the color buffer. Pass NULL for any of the arguments if the value is not required.

red :

Return location for the number of red bits or NULL

green :

Return location for the number of green bits or NULL

blue :

Return location for the number of blue bits or NULL

alpha :

Return location for the number of alpha bits or NULL

cogl_enable_depth_test ()

void                cogl_enable_depth_test              (gboolean setting);

Sets whether depth testing is enabled. If it is disabled then the order that actors are layered on the screen depends solely on the order specified using clutter_actor_raise() and clutter_actor_lower(), otherwise it will also take into account the actor's depth. Depth testing is disabled by default.

setting :

TRUE to enable depth testing or FALSE to disable.

cogl_enable_backface_culling ()

void                cogl_enable_backface_culling        (gboolean 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. Only calls to cogl_texture_rectangle() and cogl_texture_polygon() are affected. Backface culling is disabled by default.

setting :

TRUE to enable backface culling or FALSE to disable.

enum CoglFogMode

typedef enum _CoglFogMode
{
  COGL_FOG_MODE_LINEAR,
  COGL_FOG_MODE_EXPONENTIAL,
  COGL_FOG_MODE_EXPONENTIAL_SQUARED
} 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:

  f = end - eye_distance / end - start

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

COGL_FOG_MODE_LINEAR

Calculates the fog blend factor as:
  f = end - eye_distance / end - start

COGL_FOG_MODE_EXPONENTIAL

Calculates the fog blend factor as:
  f = e ^ -(density * eye_distance)

COGL_FOG_MODE_EXPONENTIAL_SQUARED

Calculates the fog blend factor as:
  f = e ^ -(density * eye_distance)^2

Since 1.0


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

fog_color :

The color of the fog

mode :

A CoglFogMode that determines the equation used to calculate the fogging blend factor.

density :

Used by the EXPONENTIAL and EXPONENTIAL_SQUARED CoglFogMode equations.

z_near :

Position along z-axis where no fogging should be applied

z_far :

Position along z-axes where full fogging should be applied

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                     (CoglHandle material);

This function sets the source material that will be used to fill subsequent geometry emitted via the cogl API.

Note: in the future we may add the ability to set a front facing material, and a back facing material, in which case this function will set both to the same.

Since 1.0

material :

A CoglMaterial object

cogl_set_source_color ()

void                cogl_set_source_color               (const CoglColor *color);

Sets the source color using normalized values for each component. This color will be used for any subsequent drawing operation.

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

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.

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.

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             (CoglHandle texture_handle);

This is a convenience function for creating a material with the first layer set to texture_handle 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

texture_handle :

The Cogl texture you want as your source