General API

General API — General purpose API

Synopsis

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

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           (float m[16]);
void                cogl_get_projection_matrix          (float m[16]);
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);

                    CoglClipStackState;
void                cogl_clip_set                       (float x_offset,
                                                         float y_offset,
                                                         float width,
                                                         float height);
void                cogl_clip_set_from_path             (void);
void                cogl_clip_set_from_path_preserve    (void);
void                cogl_clip_unset                     (void);
void                cogl_clip_stack_save                (void);
void                cogl_clip_stack_restore             (void);
void                cogl_clip_ensure                    (void);

void                cogl_enable_depth_test              (gboolean setting);
void                cogl_enable_backface_culling        (gboolean setting);
void                cogl_fog_set                        (const CoglColor *fog_color,
                                                         float density,
                                                         float z_near,
                                                         float z_far);

Description

General utility functions for COGL.

Details

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_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           (float m[16]);

Stores the current model-view matrix in m. The matrix is in column-major order.

m :

pointer to a 4x4 array of floats to receive the matrix

cogl_get_projection_matrix ()

void                cogl_get_projection_matrix          (float m[16]);

Stores the current projection matrix in m. The matrix is in column-major order.

m :

pointer to a 4x4 array of floats to receive 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.

CoglClipStackState

typedef struct {
  /* Stack of stacks */
  GSList *stacks;

  gboolean stack_dirty;
  gboolean stencil_used;
} CoglClipStackState;


cogl_clip_set ()

void                cogl_clip_set                       (float x_offset,
                                                         float y_offset,
                                                         float width,
                                                         float 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 transformed by the current model-view matrix.

The rectangle is intersected with the current clip region. To undo the effect of this function, call cogl_clip_unset().

x_offset :

left edge of the clip rectangle

y_offset :

top edge of the clip rectangle

width :

width of the clip rectangle

height :

height of the clip rectangle

cogl_clip_set_from_path ()

void                cogl_clip_set_from_path             (void);

Sets a new clipping area using the current path. The current path is then cleared. The clipping area is intersected with the previous clipping area. To restore the previous clipping area, call cogl_clip_unset().

Since 1.0


cogl_clip_set_from_path_preserve ()

void                cogl_clip_set_from_path_preserve    (void);

Sets a new clipping area using the current path. The current path is then cleared. The clipping area is intersected with the previous clipping area. To restore the previous clipping area, call cogl_clip_unset().

Since 1.0


cogl_clip_unset ()

void                cogl_clip_unset                     (void);

Reverts the clipping region to the state before the last call to cogl_clip_set().


cogl_clip_stack_save ()

void                cogl_clip_stack_save                (void);

Save the entire state of the clipping stack and then clear all clipping. The previous state can be returned to with cogl_clip_stack_restore(). Each call to cogl_clip_set() after this must be matched by a call to cogl_clip_unset() before calling cogl_clip_stack_restore().

Since 0.8.2


cogl_clip_stack_restore ()

void                cogl_clip_stack_restore             (void);

Restore the state of the clipping stack that was previously saved by cogl_clip_stack_save().

Since 0.8.2


cogl_clip_ensure ()

void                cogl_clip_ensure                    (void);

Ensures that the current clipping region has been set in GL. This will automatically be called before any Cogl primitives but it maybe be neccessary to call if you are using raw GL calls with clipping.

Since 1.0


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.

cogl_fog_set ()

void                cogl_fog_set                        (const CoglColor *fog_color,
                                                         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 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 the next call to cogl_paint_init().

fog_color :

The color of the fog

density :

Ignored

z_near :

Position along z-axis where no fogging should be applied

z_far :

Position along z-axes where full fogging should be applied