## Clipping Clipping — Fuctions for manipulating a stack of clipping regions |

## Synopsis

    void                cogl_clip_push_rectangle            (float x0,
                                                             float y0,
                                                             float x1,
                                                             float y1);
    void                cogl_clip_push_window_rectangle     (int x_offset,
                                                             int y_offset,
                                                             int width,
                                                             int height);
    void                cogl_clip_push_from_path            (void);
    void                cogl_clip_push_from_path_preserve   (void);
    void                cogl_clip_push_primitive            (CoglPrimitive *primitive,
                                                             float bounds_x1,
                                                             float bounds_y1,
                                                             float bounds_x2,
                                                             float bounds_y2);
    void                cogl_clip_pop                       (void);

## Description

To support clipping your geometry to rectangles or paths Cogl exposes a stack based API whereby each clip region you push onto the stack is intersected with the previous region.

## Details

### cogl_clip_push_rectangle ()

    void                cogl_clip_push_rectangle            (float x0,
                                                             float y0,
                                                             float x1,
                                                             float y1);

Specifies a rectangular clipping area for all subsequent drawing operations. Any drawing commands that extend outside the rectangle will be clipped so that only the portion inside the rectangle will be displayed. The rectangle dimensions are transformed by the current model-view matrix.

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

`x0` : | x coordinate for top left corner of the clip rectangle
`y0` : | y coordinate for top left corner of the clip rectangle
`x1` : | x coordinate for bottom right corner of the clip rectangle
`y1` : | y coordinate for bottom right corner of the clip rectangle

Since 1.2

### cogl_clip_push_window_rectangle ()

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

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

`x_offset` : | left edge of the clip rectangle in window coordinates
`y_offset` : | top edge of the clip rectangle in window coordinates
`width` : | width of the clip rectangle
`height` : | height of the clip rectangle

Since 1.2

### cogl_clip_push_from_path ()

    void                cogl_clip_push_from_path            (void);

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

Since 1.0

Stability Level: Unstable

### cogl_clip_push_from_path_preserve ()

    void                cogl_clip_push_from_path_preserve   (void);

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

Since 1.0

### cogl_clip_push_primitive ()

    void                cogl_clip_push_primitive            (CoglPrimitive *primitive,
                                                             float bounds_x1,
                                                             float bounds_y1,
                                                             float bounds_x2,
                                                             float bounds_y2);

Sets a new clipping area using a 2D shaped described with a CoglPrimitive. The shape must not contain self overlapping geometry and must lie on a single 2D plane. A bounding box of the 2D shape in local coordinates (the same coordinates used to describe the shape) must be given. It is acceptable for the bounds to be larger than the true bounds but behaviour is undefined if the bounds are smaller than the true bounds.

The primitive is transformed by the current model-view matrix and the silhouette is intersected with the previous clipping area. To restore the previous clipping area, call `cogl_clip_pop()`.

`primitive` : | A CoglPrimitive describing a flat 2D shape
`bounds_x1` : | x coordinate for the top-left corner of the primitives bounds
`bounds_y1` : | y coordinate for the top-left corner of the primitives bounds
`bounds_x2` : | x coordinate for the top-left corner of the primitives bounds
`bounds_y2` : | x coordinate for the bottom-right corner of the primitives bounds.
`bounds_x1` : | y coordinate for the bottom-right corner of the primitives bounds.

Since 1.10

Stability Level: Unstable

### cogl_clip_pop ()

    void                cogl_clip_pop                       (void);

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