## The Top-Level Context The Top-Level Context — The top level application context. |

## Synopsis

                        CoglContext;
    CoglBool            cogl_is_context                     (void *object);
    CoglContext *       cogl_context_new                    (CoglDisplay *display,
                                                             CoglError **error);
    CoglDisplay *       cogl_context_get_display            (CoglContext *context);

    enum                CoglFeatureID;
    CoglBool            cogl_has_feature                    (CoglContext *context,
                                                             CoglFeatureID feature);
    CoglBool            cogl_has_features                   (CoglContext *context,
                                                             ...);
    void                (*CoglFeatureCallback)              (CoglFeatureID feature,
                                                             void *user_data);
    void                cogl_foreach_feature                (CoglContext *context,
                                                             CoglFeatureCallback callback,
                                                             void *user_data);

    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_transform                      (const CoglMatrix *matrix);
    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_set_viewport                   (int x,
                                                             int y,
                                                             int width,
                                                             int height);
    void                cogl_get_viewport                   (float v[4]);

    void                cogl_set_source                     (void *material);
    void                cogl_set_source_color               (const CoglColor *color);
    void                cogl_set_source_color4ub            (uint8_t red,
                                                             uint8_t green,
                                                             uint8_t blue,
                                                             uint8_t alpha);
    void                cogl_set_source_color4f             (float red,
                                                             float green,
                                                             float blue,
                                                             float alpha);
    void                cogl_set_source_texture             (CoglTexture *texture);
    void *              cogl_get_source                     (void);
    void                cogl_push_source                    (void *material);
    void                cogl_pop_source                     (void);

    void                cogl_clear                          (const CoglColor *color,
                                                             unsigned long  buffers);

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

    void                cogl_flush                          (void);

## Description

A CoglContext is the top most sandbox of Cogl state for an application or toolkit. Its main purpose is to act as a sandbox for the memory management of state objects. Normally an application will only create a single context since there is no way to share resources between contexts.

For those familiar with OpenGL or perhaps Cairo it should be understood that unlike these APIs a Cogl context isn't a rendering context as such. In other words Cogl doesn't aim to provide a state machine style model for configuring rendering parameters. Most rendering state in Cogl is directly associated with user managed objects called pipelines and geometry is drawn with a specific pipeline object to a framebuffer object and those 3 things fully define the state for drawing. This is an important part of Cogl's design since it helps you write orthogonal rendering components that can all access the same GPU without having to worry about what state other components have left you with.

### Note

Cogl does not maintain internal references to the context for resources that depend on the context so applications. This is to help applications control the lifetime a context without us needing to introduce special api to handle the breakup of internal circular references due to internal resources and caches associated with the context.

One a context has been destroyed then all directly or indirectly dependant resources will be in an inconsistent state and should not be manipulated or queried in any way.

For applications that rely on the operating system to clean up resources this policy shouldn't affect them, but for applications that need to carefully destroy and re-create Cogl contexts multiple times throughout their lifetime (such as Android applications) they should be careful to destroy all context dependant resources, such as framebuffers or textures etc before unrefing and destroying the context.

## Details

### CoglContext

    typedef struct _CoglContext CoglContext;

### cogl_is_context ()

    CoglBool            cogl_is_context                     (void *object);

Gets whether the given object references an existing context object.

`object` : | An object or `NULL`
Returns : | `TRUE` if the `object` references a CoglContext, `FALSE` otherwise

Since 1.10

Stability Level: Unstable

### cogl_context_new ()

    CoglContext *       cogl_context_new                    (CoglDisplay *display,
                                                             CoglError **error);

Creates a new CoglContext which acts as an application sandbox for any state objects that are allocated.

`display` : | A CoglDisplay pointer
`error` : | A CoglError return location.
Returns : | A newly allocated CoglContext. [transfer full]

Since 1.8

Stability Level: Unstable

### cogl_context_get_display ()

    CoglDisplay *       cogl_context_get_display            (CoglContext *context);

Retrieves the CoglDisplay that is internally associated with the given `context`. This will return the same CoglDisplay that was passed to `cogl_context_new()` or if `NULL` was passed to `cogl_context_new()` then this function returns a pointer to the display that was automatically setup internally.

`context` : | A CoglContext pointer
Returns : | The CoglDisplay associated with the given `context`. [transfer none]

Since 1.8

Stability Level: Unstable

### enum CoglFeatureID

    typedef enum {
      COGL_FEATURE_ID_TEXTURE_NPOT_BASIC = 1,
      COGL_FEATURE_ID_TEXTURE_NPOT_MIPMAP,
      COGL_FEATURE_ID_TEXTURE_NPOT_REPEAT,
      COGL_FEATURE_ID_TEXTURE_NPOT,
      COGL_FEATURE_ID_TEXTURE_RECTANGLE,
      COGL_FEATURE_ID_TEXTURE_3D,
      COGL_FEATURE_ID_GLSL,
      COGL_FEATURE_ID_ARBFP,
      COGL_FEATURE_ID_OFFSCREEN,
      COGL_FEATURE_ID_OFFSCREEN_MULTISAMPLE,
      COGL_FEATURE_ID_ONSCREEN_MULTIPLE,
      COGL_FEATURE_ID_UNSIGNED_INT_INDICES,
      COGL_FEATURE_ID_DEPTH_RANGE,
      COGL_FEATURE_ID_POINT_SPRITE,
      COGL_FEATURE_ID_MAP_BUFFER_FOR_READ,
      COGL_FEATURE_ID_MAP_BUFFER_FOR_WRITE,
      COGL_FEATURE_ID_MIRRORED_REPEAT,
      COGL_FEATURE_ID_SWAP_BUFFERS_EVENT,
      COGL_FEATURE_ID_GLES2_CONTEXT,
      COGL_FEATURE_ID_DEPTH_TEXTURE,
      COGL_FEATURE_ID_PRESENTATION_TIME,
      COGL_FEATURE_ID_FENCE,
      COGL_FEATURE_ID_PER_VERTEX_POINT_SIZE,
    } CoglFeatureID;

All the capabilities that can vary between different GPUs supported by Cogl. Applications that depend on any of these features should explicitly check for them using `cogl_has_feature()` or `cogl_has_features()`.

`COGL_FEATURE_ID_TEXTURE_NPOT_BASIC` | The hardware supports non power of two textures, but you also need to check the `COGL_FEATURE_ID_TEXTURE_NPOT_MIPMAP` and `COGL_FEATURE_ID_TEXTURE_NPOT_REPEAT` features to know if the hardware supports npot texture mipmaps or repeat modes other than `COGL_PIPELINE_WRAP_MODE_CLAMP_TO_EDGE` respectively.
`COGL_FEATURE_ID_TEXTURE_NPOT_MIPMAP` | Mipmapping is supported in conjuntion with non power of two textures.
`COGL_FEATURE_ID_TEXTURE_NPOT_REPEAT` | Repeat modes other than `COGL_PIPELINE_WRAP_MODE_CLAMP_TO_EDGE` are supported by the hardware.
`COGL_FEATURE_ID_TEXTURE_NPOT` | Non power of two textures are supported by the hardware. This is a equivalent to the `COGL_FEATURE_ID_TEXTURE_NPOT_BASIC`, `COGL_FEATURE_ID_TEXTURE_NPOT_MIPMAP` and `COGL_FEATURE_ID_TEXTURE_NPOT_REPEAT` features combined.
`COGL_FEATURE_ID_TEXTURE_RECTANGLE` | Support for rectangular textures with non-normalized texture coordinates.
`COGL_FEATURE_ID_TEXTURE_3D` | 3D texture support
`COGL_FEATURE_ID_GLSL` | GLSL support
`COGL_FEATURE_ID_ARBFP` | ARBFP support
`COGL_FEATURE_ID_OFFSCREEN` | Offscreen rendering support
`COGL_FEATURE_ID_OFFSCREEN_MULTISAMPLE` | Multisample support for offscreen framebuffers
`COGL_FEATURE_ID_ONSCREEN_MULTIPLE` | Multiple onscreen framebuffers supported.
`COGL_FEATURE_ID_UNSIGNED_INT_INDICES` | Set if `COGL_INDICES_TYPE_UNSIGNED_INT` is supported in `cogl_indices_new()`.
`COGL_FEATURE_ID_DEPTH_RANGE` | cogl_pipeline_set_depth_range() support
`COGL_FEATURE_ID_POINT_SPRITE` | Whether `cogl_pipeline_set_layer_point_sprite_coords_enabled()` is supported.
`COGL_FEATURE_ID_MAP_BUFFER_FOR_READ` | Whether `cogl_buffer_map()` is supported with CoglBufferAccess including read support.
`COGL_FEATURE_ID_MAP_BUFFER_FOR_WRITE` | Whether `cogl_buffer_map()` is supported with CoglBufferAccess including write support.
`COGL_FEATURE_ID_MIRRORED_REPEAT` | Whether `COGL_PIPELINE_WRAP_MODE_MIRRORED_REPEAT` is supported.
`COGL_FEATURE_ID_SWAP_BUFFERS_EVENT` | Available if the window system supports reporting an event for swap buffer completions.
`COGL_FEATURE_ID_GLES2_CONTEXT` | Whether creating new GLES2 contexts is suported.
`COGL_FEATURE_ID_DEPTH_TEXTURE` | Whether CoglFramebuffer support rendering the depth buffer to a texture.
`COGL_FEATURE_ID_PRESENTATION_TIME` | Whether frame presentation time stamps will be recorded in CoglFrameInfo objects.
`COGL_FEATURE_ID_FENCE` |
`COGL_FEATURE_ID_PER_VERTEX_POINT_SIZE` | Whether cogl_point_size_in can be used as an attribute to set a per-vertex point size.

Since 1.10

### cogl_has_feature ()

    CoglBool            cogl_has_feature                    (CoglContext *context,
                                                             CoglFeatureID feature);

Checks if a given `feature` is currently available

Cogl does not aim to be a lowest common denominator API, it aims to expose all the interesting features of GPUs to application which means applications have some responsibility to explicitly check that certain features are available before depending on them.

`context` : | A CoglContext pointer
`feature` : | A CoglFeatureID
Returns : | `TRUE` if the `feature` is currently supported or `FALSE` if not.

Since 1.10

Stability Level: Unstable

### cogl_has_features ()

    CoglBool            cogl_has_features                   (CoglContext *context,
                                                             ...);

Checks if a list of features are all currently available.

This checks all of the listed features using `cogl_has_feature()` and returns `TRUE` if all the features are available or `FALSE` otherwise.

`context` : | A CoglContext pointer
`...` : | A 0 terminated list of CoglFeatureIDs
Returns : | `TRUE` if all the features are available, `FALSE` otherwise.

Since 1.10

Stability Level: Unstable

### CoglFeatureCallback ()

    void                (*CoglFeatureCallback)              (CoglFeatureID feature,
                                                             void *user_data);

A callback used with `cogl_foreach_feature()` for enumerating all context level features supported by Cogl.

`feature` : | A single feature currently supported by Cogl
`user_data` : | A private pointer passed to `cogl_foreach_feature()`.

Since 0.10

Stability Level: Unstable

### cogl_foreach_feature ()

    void                cogl_foreach_feature                (CoglContext *context,
                                                             CoglFeatureCallback callback,
                                                             void *user_data);

Iterates through all the context level features currently supported for a given `context` and for each feature `callback` is called.

`context` : | A CoglContext pointer
`callback` : | A CoglFeatureCallback called for each supported feature
`user_data` : | Private data to pass to the callback

Since 1.10

Stability Level: Unstable

### cogl_push_matrix ()

    void                cogl_push_matrix                    (void);

### Warning

`cogl_push_matrix` has been deprecated since version 1.10 and should not be used in newly-written code. Use `cogl_framebuffer_push_matrix()` instead

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

### Warning

`cogl_pop_matrix` has been deprecated since version 1.10 and should not be used in newly-written code. Use `cogl_framebuffer_pop_matrix()` instead

Restores the current model-view matrix from the matrix stack.

### cogl_scale ()

    void                cogl_scale                          (float x,
                                                             float y,
                                                             float z);

### Warning

`cogl_scale` has been deprecated since version 1.10 and should not be used in newly-written code. Use `cogl_framebuffer_pop_matrix()` instead

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

### Warning

`cogl_translate` has been deprecated since version 1.10 and should not be used in newly-written code. Use `cogl_framebuffer_translate()` instead

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

### Warning

`cogl_rotate` has been deprecated since version 1.10 and should not be used in newly-written code. Use `cogl_framebuffer_rotate()` instead

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

    void                cogl_transform                      (const CoglMatrix *matrix);

### Warning

`cogl_transform` has been deprecated since version 1.10 and should not be used in newly-written code. Use `cogl_framebuffer_transform()` instead

Multiplies the current model-view matrix by the given matrix.

`matrix` : | the matrix to multiply with the current model-view

Since 1.4

### cogl_frustum ()

    void                cogl_frustum                        (float left,
                                                             float right,
                                                             float bottom,
                                                             float top,
                                                             float z_near,
                                                             float z_far);

### Warning

`cogl_frustum` has been deprecated since version 1.10 and should not be used in newly-written code. Use `cogl_framebuffer_frustum()` instead

Replaces the current projection matrix with a perspective matrix for a given viewing frustum defined by 4 side clip planes that all cross through the origin and 2 near and far clip planes.

`left` : | X position of the left clipping plane where it intersects the near clipping plane
`right` : | X position of the right clipping plane where it intersects the near clipping plane
`bottom` : | Y position of the bottom clipping plane where it intersects the near clipping plane
`top` : | Y position of the top clipping plane where it intersects the near clipping plane
`z_near` : | The distance to the near clipping plane (Must be positive)
`z_far` : | The distance to the far clipping plane (Must be positive)

Since 0.8.2

### cogl_perspective ()

    void                cogl_perspective                    (float fovy,
                                                             float aspect,
                                                             float z_near,
                                                             float z_far);

### Warning

`cogl_perspective` has been deprecated since version 1.10 and should not be used in newly-written code. Use `cogl_framebuffer_perspective()` instead

Replaces the current projection matrix with a perspective matrix based on the provided values.

### Note

You should be careful not to have to great a `z_far` / `z_near` ratio since that will reduce the effectiveness of depth testing since there wont be enough precision to identify the depth of objects near to each other.

`fovy` : | Vertical field of view angle in degrees.
`aspect` : | The (width over height) aspect ratio for display
`z_near` : | The distance to the near clipping plane (Must be positive)
`z_far` : | The distance to the far clipping plane (Must be positive)

### cogl_ortho ()

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

### Warning

`cogl_ortho` has been deprecated since version 1.10 and should not be used in newly-written code. Use `cogl_framebuffer_orthographic()` instead

Replaces the current projection matrix with an orthographic projection matrix. See Figure 1, “” to see how the matrix is calculated.

Figure 1.

### Note

This function copies the arguments from OpenGL's `glOrtho()` even though they are unnecessarily confusing due to the z near and z far arguments actually being a "distance" from the origin, where negative values are behind the viewer, instead of coordinates for the z clipping planes which would have been consistent with the left, right bottom and top arguments.

`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 distance to the near clipping plane (negative if the plane is behind the viewer)
`far` : | The distance for the far clipping plane (negative if the plane is behind the viewer)

Since 1.0

### cogl_get_modelview_matrix ()

    void                cogl_get_modelview_matrix           (CoglMatrix *matrix);

### Warning

`cogl_get_modelview_matrix` has been deprecated since version 1.10 and should not be used in newly-written code. Use `cogl_framebuffer_get_modelview_matrix()` instead

Stores the current model-view matrix in `matrix`.

`matrix` : | return location for the model-view matrix. [out]

### cogl_set_modelview_matrix ()

    void                cogl_set_modelview_matrix           (CoglMatrix *matrix);

### Warning

`cogl_set_modelview_matrix` has been deprecated since version 1.10 and should not be used in newly-written code. Use `cogl_framebuffer_set_modelview_matrix()` instead

Loads `matrix` as the new model-view matrix.

`matrix` : | the new model-view matrix

### cogl_get_projection_matrix ()

    void                cogl_get_projection_matrix          (CoglMatrix *matrix);

### Warning

`cogl_get_projection_matrix` has been deprecated since version 1.10 and should not be used in newly-written code. Use `cogl_framebuffer_get_projection_matrix()` instead

Stores the current projection matrix in `matrix`.

`matrix` : | return location for the projection matrix. [out]

### cogl_set_projection_matrix ()

    void                cogl_set_projection_matrix          (CoglMatrix *matrix);

### Warning

`cogl_set_projection_matrix` has been deprecated since version 1.10 and should not be used in newly-written code. Use `cogl_framebuffer_set_projection_matrix()` instead

Loads matrix as the new projection matrix.

`matrix` : | the new projection matrix

### cogl_set_viewport ()

    void                cogl_set_viewport                   (int x,
                                                             int y,
                                                             int width,
                                                             int height);

### Warning

`cogl_set_viewport` has been deprecated since version 1.8 and should not be used in newly-written code. Use `cogl_framebuffer_set_viewport()` instead

Replaces the current viewport with the given values.

`x` : | X offset of the viewport
`y` : | Y offset of the viewport
`width` : | Width of the viewport
`height` : | Height of the viewport

Since 1.2

### cogl_get_viewport ()

    void                cogl_get_viewport                   (float v[4]);

### Warning

`cogl_get_viewport` has been deprecated since version 1.10 and should not be used in newly-written code. Use `cogl_framebuffer_get_viewport4fv()` instead

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. [out][array fixed-size=4]

### cogl_set_source ()

    void                cogl_set_source                     (void *material);

### Warning

`cogl_set_source` has been deprecated since version 1.16 and should not be used in newly-written code. Latest drawing apis all take an explicit CoglPipeline argument so this stack of CoglMaterials shouldn't be used.

This function changes the material at the top of the source stack. The material at the top of this stack defines the GPU state used to process subsequent primitives, such as rectangles drawn with `cogl_rectangle()` or vertices drawn using `cogl_vertex_buffer_draw()`.

`material` : | A CoglMaterial

Since 1.0

### cogl_set_source_color ()

    void                cogl_set_source_color               (const CoglColor *color);

### Warning

`cogl_set_source_color` has been deprecated since version 1.16 and should not be used in newly-written code. Latest drawing apis all take an explicit CoglPipeline argument so this stack of CoglMaterials shouldn't be used.

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            (uint8_t red,
                                                             uint8_t green,
                                                             uint8_t blue,
                                                             uint8_t alpha);

### Warning

`cogl_set_source_color4ub` has been deprecated since version 1.16 and should not be used in newly-written code. Latest drawing apis all take an explicit CoglPipeline argument so this stack of CoglMaterials shouldn't be used.

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

### Warning

`cogl_set_source_color4f` has been deprecated since version 1.16 and should not be used in newly-written code. Latest drawing apis all take an explicit CoglPipeline argument so this stack of CoglMaterials shouldn't be used.

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             (CoglTexture *texture);

### Warning

`cogl_set_source_texture` has been deprecated since version 1.16 and should not be used in newly-written code. Latest drawing apis all take an explicit CoglPipeline argument so this stack of CoglMaterials shouldn't be used.

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

`texture` : | The CoglTexture you want as your source

Since 1.0

### cogl_get_source ()

    void *              cogl_get_source                     (void);

### Warning

`cogl_get_source` has been deprecated since version 1.16 and should not be used in newly-written code. Latest drawing apis all take an explicit CoglPipeline argument so this stack of CoglMaterials shouldn't be used.

Returns the current source material as previously set using `cogl_set_source()`.

### Note

You should typically consider the returned material immutable and not try to change any of its properties unless you own a reference to that material. At times you may be able to get a reference to an internally managed materials and the result of modifying such materials is undefined.

Returns : | The current source material.

Since 1.6

### cogl_push_source ()

    void                cogl_push_source                    (void *material);

### Warning

`cogl_push_source` has been deprecated since version 1.16 and should not be used in newly-written code. Latest drawing apis all take an explicit CoglPipeline argument so this stack of CoglMaterials shouldn't be used.

Pushes the given `material` to the top of the source stack. The material at the top of this stack defines the GPU state used to process later primitives as defined by `cogl_set_source()`.

`material` : | A CoglMaterial

Since 1.6

### cogl_pop_source ()

    void                cogl_pop_source                     (void);

### Warning

`cogl_pop_source` has been deprecated since version 1.16 and should not be used in newly-written code. Latest drawing apis all take an explicit CoglPipeline argument so this stack of CoglMaterials shouldn't be used.

Removes the material at the top of the source stack. The material at the top of this stack defines the GPU state used to process later primitives as defined by `cogl_set_source()`.

Since 1.6

### cogl_clear ()

    void                cogl_clear                          (const CoglColor *color,
                                                             unsigned long  buffers);

### Warning

`cogl_clear` has been deprecated since version 1.16 and should not be used in newly-written code. Use `cogl_framebuffer_clear()` api instead

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

### enum CoglReadPixelsFlags

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

Flags for `cogl_framebuffer_read_pixels_into_bitmap()`

`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,
                                                             uint8_t *pixels);

### Warning

`cogl_read_pixels` has been deprecated since version 1.16 and should not be used in newly-written code. Use `cogl_framebuffer_read_pixels()` instead

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

Currently Cogl assumes that the framebuffer is in a premultiplied format so if `format` is non-premultiplied it will convert it. To read the pixel values without any conversion you should either specify a format that doesn't use an alpha channel or use one of the formats ending in PRE.

`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