General API

## General API General API — General purpose API |

## Synopsis

    #define             COGL_INVALID_HANDLE
    typedef             CoglHandle;
    CoglHandle          cogl_handle_ref                     (CoglHandle handle);
    void                cogl_handle_unref                   (CoglHandle Handle);

    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;
    enum                CoglBufferBit;
    enum                CoglAttributeType;

    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);
    GOptionGroup *      cogl_get_option_group               (void);

    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_frustum                        (float left,
                                                             float right,
                                                             float bottom,
                                                             float top,
                                                             float z_near,
                                                             float z_far);
    void                cogl_perspective                    (float fovy,
                                                             float aspect,
                                                             float z_near,
                                                             float z_far);
    void                cogl_ortho                          (float left,
                                                             float right,
                                                             float bottom,
                                                             float top,
                                                             float near,
                                                             float far);

    void                cogl_get_modelview_matrix           (CoglMatrix *matrix);
    void                cogl_set_modelview_matrix           (CoglMatrix *matrix);
    void                cogl_get_projection_matrix          (CoglMatrix *matrix);
    void                cogl_set_projection_matrix          (CoglMatrix *matrix);
    void                cogl_viewport                       (guint width,
                                                             guint height);
    void                cogl_get_viewport                   (float v[4]);

    void                cogl_clear                          (const CoglColor *color,
                                                             gulong buffers);
    void                cogl_get_bitmasks                   (gint *red,
                                                             gint *green,
                                                             gint *blue,
                                                             gint *alpha);
    void                cogl_set_depth_test_enabled         (gboolean setting);
    gboolean            cogl_get_depth_test_enabled         (void);
    void                cogl_set_backface_culling_enabled   (gboolean setting);
    gboolean            cogl_get_backface_culling_enabled   (void);

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

    enum                CoglReadPixelsFlags;
    void                cogl_read_pixels                    (int x,
                                                             int y,
                                                             int width,
                                                             int height,
                                                             CoglReadPixelsFlags source,
                                                             CoglPixelFormat format,
                                                             guint8 *pixels);

    void                cogl_flush                          (void);
    void                cogl_begin_gl                       (void);
    void                cogl_end_gl                         (void);

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

### cogl_handle_ref ()

    CoglHandle          cogl_handle_ref                     (CoglHandle handle);

Increases the reference count of `handle` by 1

`handle` : | a CoglHandle
Returns : | the handle, with its reference count increased

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

`Handle` : | a CoglHandle

### 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 { /*< prefix=COGL_PIXEL_FORMAT >*/
      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_OFFSCREEN_BUFFER   = (1 << 2)
    } CoglBufferTarget;

Target flags for FBOs.

`COGL_WINDOW_BUFFER` | FIXME
`COGL_OFFSCREEN_BUFFER` | FIXME

Since 0.8

### enum CoglBufferBit

    typedef enum {
      COGL_BUFFER_BIT_COLOR   = 1L<<0,
      COGL_BUFFER_BIT_DEPTH   = 1L<<1,
      COGL_BUFFER_BIT_STENCIL = 1L<<2
    } CoglBufferBit;

Types of auxiliary buffers

`COGL_BUFFER_BIT_COLOR` | Selects the primary color buffer
`COGL_BUFFER_BIT_DEPTH` | Selects the depth buffer
`COGL_BUFFER_BIT_STENCIL` | Selects the stencil buffer

Since 1.0

### enum CoglAttributeType

    typedef enum _CoglAttributeType
    {
      COGL_ATTRIBUTE_TYPE_BYTE = GL_BYTE,
      COGL_ATTRIBUTE_TYPE_UNSIGNED_BYTE = GL_UNSIGNED_BYTE,
      COGL_ATTRIBUTE_TYPE_SHORT = GL_SHORT,
      COGL_ATTRIBUTE_TYPE_UNSIGNED_SHORT = GL_UNSIGNED_SHORT,
      COGL_ATTRIBUTE_TYPE_FLOAT = GL_FLOAT
    } CoglAttributeType;

Data types for the components of `cogl_vertex_buffer_add()`

`COGL_ATTRIBUTE_TYPE_BYTE` | Data is the same size of a byte
`COGL_ATTRIBUTE_TYPE_UNSIGNED_BYTE` | Data is the same size of an unsigned byte
`COGL_ATTRIBUTE_TYPE_SHORT` | Data is the same size of a short integer
`COGL_ATTRIBUTE_TYPE_UNSIGNED_SHORT` | Data is the same size of an unsigned short integer
`COGL_ATTRIBUTE_TYPE_FLOAT` | Data is the same size of a float

Since 1.0

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

Returns : | a GOptionGroup

Since 1.0

### 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_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_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_ortho ()

    void                cogl_ortho                          (float left,
                                                             float right,
                                                             float bottom,
                                                             float top,
                                                             float near,
                                                             float far);

Replaces the current projection matrix with a parallel projection matrix.

`left` : | The coordinate for the left clipping plane
`right` : | The coordinate for the right clipping plane
`bottom` : | The coordinate for the bottom clipping plane
`top` : | The coordinate for the top clipping plane
`near` : | The coordinate for the near clipping plane (may be negative if the plane is behind the viewer)
`far` : | The coordinate for the far clipping plane (may be negative if the plane is behind the viewer)

Since 1.0

### 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_set_modelview_matrix ()

    void                cogl_set_modelview_matrix           (CoglMatrix *matrix);

Loads matrix as the new model-view matrix.

`matrix` : | pointer to a CoglMatrix to set as the new model-view 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_set_projection_matrix ()

    void                cogl_set_projection_matrix          (CoglMatrix *matrix);

Loads matrix as the new projection matrix.

`matrix` : | pointer to a CoglMatrix to set as the new projection matrix

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

    void                cogl_clear                          (const CoglColor *color,
                                                             gulong buffers);

Clears all the auxiliary buffers identified in the `buffers` mask, and if that includes the color buffer then the specified `color` is used.

`color` : | Background color to clear to
`buffers` : | A mask of CoglBufferBit's identifying which auxiliary buffers to clear

### 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_set_depth_test_enabled ()

    void                cogl_set_depth_test_enabled         (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_get_depth_test_enabled ()

    gboolean            cogl_get_depth_test_enabled         (void);

Queries if depth testing has been enabled via `cogl_set_depth_test_enable()`

Returns : | `TRUE` if depth testing is enabled, and `FALSE` otherwise

### cogl_set_backface_culling_enabled ()

    void                cogl_set_backface_culling_enabled   (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. This only affects calls to the cogl_rectangle* family of functions and cogl_vertex_buffer_draw*. Backface culling is disabled by default.

`setting` : | `TRUE` to enable backface culling or `FALSE` to disable.

### cogl_get_backface_culling_enabled ()

    gboolean            cogl_get_backface_culling_enabled   (void);

Queries if backface culling has been enabled via `cogl_set_backface_culling_enabled()`

Returns : | `TRUE` if backface culling is enabled, and `FALSE` otherwise

### enum CoglFogMode

    typedef enum {
      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()`.

### Note

The fogging functions only work correctly when primitives use unmultiplied alpha colors. By default Cogl will premultiply textures and `cogl_set_source_color()` will premultiply colors, so unless you explicitly load your textures requesting an unmultiplied internal format and use `cogl_material_set_color()` you can only use fogging with fully opaque primitives. This might improve in the future when we can depend on fragment shaders.

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

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.

`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

### enum CoglReadPixelsFlags

    typedef enum { /*< prefix=COGL_READ_PIXELS >*/
      COGL_READ_PIXELS_COLOR_BUFFER = 1L << 0
    } CoglReadPixelsFlags;

Flags for `cogl_read_pixels()`

`COGL_READ_PIXELS_COLOR_BUFFER` | Read from the color buffer

Since 1.0

### cogl_read_pixels ()

    void                cogl_read_pixels                    (int x,
                                                             int y,
                                                             int width,
                                                             int height,
                                                             CoglReadPixelsFlags source,
                                                             CoglPixelFormat format,
                                                             guint8 *pixels);

This reads a rectangle of pixels from the current draw buffer 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)

`x` : | The window x position to start reading from
`y` : | The window y position to start reading from
`width` : | The width of the rectangle you want to read
`height` : | The height of the rectangle you want to read
`source` : | Identifies which auxillary buffer you want to read (only COGL_READ_PIXELS_COLOR_BUFFER supported currently)
`format` : | The pixel format you want the result in (only COGL_PIXEL_FORMAT_RGBA_8888 supported currently)
`pixels` : | The location to write the pixel data.

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

    {
       - 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()`:

    {
       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:

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

Note: no special material state is flushed, so if you want Cogl to setup a simplified material state it is your responsibility to set a simple source material before calling cogl_begin_gl. E.g. by calling `cogl_set_source_color4ub()`.

Note: It is your responsibility to restore any OpenGL state that you modify to how it was after calling `cogl_begin_gl()` if you don't do this then the result of further Cogl calls is undefined.

Note: You can not nest begin/end blocks.

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