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                    (ClutterFixed fovy,
                                                         ClutterFixed aspect,
                                                         ClutterFixed z_near,
                                                         ClutterFixed z_far);
void                cogl_frustum                        (ClutterFixed left,
                                                         ClutterFixed right,
                                                         ClutterFixed bottom,
                                                         ClutterFixed top,
                                                         ClutterFixed z_near,
                                                         ClutterFixed z_far);
void                cogl_setup_viewport                 (guint width,
                                                         guint height,
                                                         ClutterFixed fovy,
                                                         ClutterFixed aspect,
                                                         ClutterFixed z_near,
                                                         ClutterFixed z_far);
void                cogl_viewport                       (guint width,
                                                         guint height);
void                cogl_get_modelview_matrix           (ClutterFixed m[16]);
void                cogl_get_projection_matrix          (ClutterFixed m[16]);
void                cogl_get_viewport                   (ClutterFixed v[4]);

void                cogl_push_matrix                    (void);
void                cogl_pop_matrix                     (void);
void                cogl_scale                          (ClutterFixed x,
                                                         ClutterFixed y);
void                cogl_translatex                     (ClutterFixed x,
                                                         ClutterFixed y,
                                                         ClutterFixed z);
void                cogl_translate                      (gint x,
                                                         gint y,
                                                         gint z);
void                cogl_rotatex                        (ClutterFixed angle,
                                                         gint x,
                                                         gint y,
                                                         gint z);
void                cogl_rotate                         (gint angle,
                                                         gint x,
                                                         gint y,
                                                         gint z);

void                cogl_clip_set                       (ClutterFixed x_offset,
                                                         ClutterFixed y_offset,
                                                         ClutterFixed width,
                                                         ClutterFixed height);
void                cogl_clip_unset                     (void);
void                cogl_clip_stack_save                (void);
void                cogl_clip_stack_restore             (void);

void                cogl_enable_depth_test              (gboolean setting);
void                cogl_alpha_func                     (COGLenum func,
                                                         ClutterFixed ref);
void                cogl_fog_set                        (const ClutterColor *fog_color,
                                                         ClutterFixed density,
                                                         ClutterFixed z_near,
                                                         ClutterFixed 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.


enum CoglBufferTarget

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


cogl_perspective ()

void                cogl_perspective                    (ClutterFixed fovy,
                                                         ClutterFixed aspect,
                                                         ClutterFixed z_near,
                                                         ClutterFixed 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                        (ClutterFixed left,
                                                         ClutterFixed right,
                                                         ClutterFixed bottom,
                                                         ClutterFixed top,
                                                         ClutterFixed z_near,
                                                         ClutterFixed 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,
                                                         ClutterFixed fovy,
                                                         ClutterFixed aspect,
                                                         ClutterFixed z_near,
                                                         ClutterFixed 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           (ClutterFixed m[16]);

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

m :

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

cogl_get_projection_matrix ()

void                cogl_get_projection_matrix          (ClutterFixed m[16]);

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

m :

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

cogl_get_viewport ()

void                cogl_get_viewport                   (ClutterFixed 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 ClutterFixeds 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                          (ClutterFixed x,
                                                         ClutterFixed y);

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

x :

Amount to scale along the x-axis

y :

Amount to scale along the y-axis

cogl_translatex ()

void                cogl_translatex                     (ClutterFixed x,
                                                         ClutterFixed y,
                                                         ClutterFixed 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_translate ()

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

Integer version of cogl_translatex(). 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_rotatex ()

void                cogl_rotatex                        (ClutterFixed angle,
                                                         gint x,
                                                         gint y,
                                                         gint 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_rotate ()

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

Integer version of cogl_rotatex(). Multiplies the current model-view matrix by one that rotates the model around the vertex specified by x, y and z.

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

void                cogl_clip_set                       (ClutterFixed x_offset,
                                                         ClutterFixed y_offset,
                                                         ClutterFixed width,
                                                         ClutterFixed 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.

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

void                cogl_clip_unset                     (void);

Removes the current clipping rectangle so that all drawing operations extend to full size of the viewport again.


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_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_alpha_func ()

void                cogl_alpha_func                     (COGLenum func,
                                                         ClutterFixed ref);

Changes the alpha test to use the specified function specified in func, comparing with the value in ref. The default function is CGL_ALWAYS the initial reference value is 1.0.

func :

the comparison function to use, one of CGL_NEVER, CGL_LESS, CGL_EQUAL, CGL_LEQUAL, CGL_GREATER, CGL_NOTEQUAL, CGL_GEQUAL and GL_ALWAYS.

ref :

reference value.

cogl_fog_set ()

void                cogl_fog_set                        (const ClutterColor *fog_color,
                                                         ClutterFixed density,
                                                         ClutterFixed z_near,
                                                         ClutterFixed 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