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