## Primitives

Primitives — Functions that draw various primitive shapes and allow for construction of more complex paths.

## Synopsis

    void                cogl_color                          (const ClutterColor *color);
    void                cogl_path_fill                      (void);
    void                cogl_path_stroke                    (void);
    void                cogl_path_move_to                   (ClutterFixed x,
                                                             ClutterFixed y);
    void                cogl_path_close                     (void);
    void                cogl_path_line_to                   (ClutterFixed x,
                                                             ClutterFixed y);
    void                cogl_path_curve_to                  (ClutterFixed x1,
                                                             ClutterFixed y1,
                                                             ClutterFixed x2,
                                                             ClutterFixed y2,
                                                             ClutterFixed x3,
                                                             ClutterFixed y3);
    void                cogl_path_arc                       (ClutterFixed center_x,
                                                             ClutterFixed center_y,
                                                             ClutterFixed radius_x,
                                                             ClutterFixed radius_y,
                                                             ClutterAngle angle_1,
                                                             ClutterAngle angle_2);
    void                cogl_path_rel_move_to               (ClutterFixed x,
                                                             ClutterFixed y);
    void                cogl_path_rel_line_to               (ClutterFixed x,
                                                             ClutterFixed y);
    void                cogl_path_rel_curve_to              (ClutterFixed x1,
                                                             ClutterFixed y1,
                                                             ClutterFixed x2,
                                                             ClutterFixed y2,
                                                             ClutterFixed x3,
                                                             ClutterFixed y3);
    void                cogl_path_line                      (ClutterFixed x1,
                                                             ClutterFixed y1,
                                                             ClutterFixed x2,
                                                             ClutterFixed y2);
    void                cogl_path_polyline                  (ClutterFixed *coords,
                                                             gint num_points);
    void                cogl_path_polygon                   (ClutterFixed *coords,
                                                             gint num_points);
    void                cogl_path_rectangle                 (ClutterFixed x,
                                                             ClutterFixed y,
                                                             ClutterFixed width,
                                                             ClutterFixed height);
    void                cogl_path_round_rectangle           (ClutterFixed x,
                                                             ClutterFixed y,
                                                             ClutterFixed width,
                                                             ClutterFixed height,
                                                             ClutterFixed radius,
                                                             ClutterAngle arc_step);
    void                cogl_path_ellipse                   (ClutterFixed center_x,
                                                             ClutterFixed center_y,
                                                             ClutterFixed radius_x,
                                                             ClutterFixed radius_y);
    void                cogl_rectangle                      (gint x,
                                                             gint y,
                                                             guint width,
                                                             guint height);
    void                cogl_rectanglex                     (ClutterFixed x,
                                                             ClutterFixed y,
                                                             ClutterFixed width,
                                                             ClutterFixed height);

## Description

There are three levels on which drawing with cogl can be used. The highest level functions construct various simple primitive shapes to be either filled or stroked. Using a lower-level set of functions more complex and arbitrary paths can be constructed by concatenating straight line, bezier curve and arc segments. Additionally there are utility functions that draw the most common primitives - rectangles and trapezoids - in a maximaly optimized fashion.

When constructing arbitrary paths, the current pen location is initialized using the move_to command. The subsequent path segments implicitly use the last pen location as their first vertex and move the pen location to the last vertex they produce at the end. Also there are special versions of functions that allow specifying the vertices of the path segments relative to the last pen location rather then in the absolute coordinates.

## Details

### cogl_color ()

    void                cogl_color                          (const ClutterColor *color);

Changes the color of cogl's current paint, which is used for filling and stroking primitives.

`color` : | new current `ClutterColor`.

### cogl_path_fill ()

    void                cogl_path_fill                      (void);

Fills the constructed shape using the current drawing color.

### cogl_path_stroke ()

    void                cogl_path_stroke                    (void);

Strokes the constructed shape using the current drawing color and a width of 1 pixel (regardless of the current transformation matrix).

### cogl_path_move_to ()

    void                cogl_path_move_to                   (ClutterFixed x,
                                                             ClutterFixed y);

Clears the previously constructed shape and begins a new path contour by moving the pen to the given coordinates.

`x` : | X coordinate of the pen location to move to.
`y` : | Y coordinate of the pen location to move to.

### cogl_path_close ()

    void                cogl_path_close                     (void);

Closes the path being constructed by adding a straight line segment to it that ends at the first vertex of the path.

### cogl_path_line_to ()

    void                cogl_path_line_to                   (ClutterFixed x,
                                                             ClutterFixed y);

Adds a straight line segment to the current path that ends at the given coordinates.

`x` : | X coordinate of the end line vertex
`y` : | Y coordinate of the end line vertex

### cogl_path_curve_to ()

    void                cogl_path_curve_to                  (ClutterFixed x1,
                                                             ClutterFixed y1,
                                                             ClutterFixed x2,
                                                             ClutterFixed y2,
                                                             ClutterFixed x3,
                                                             ClutterFixed y3);

Adds a cubic bezier curve segment to the current path with the given second, third and fourth control points and using current pen location as the first control point.

`x1` : | X coordinate of the second bezier control point
`y1` : | Y coordinate of the second bezier control point
`x2` : | X coordinate of the third bezier control point
`y2` : | Y coordinate of the third bezier control point
`x3` : | X coordinate of the fourth bezier control point
`y3` : | Y coordinate of the fourth bezier control point

### cogl_path_arc ()

    void                cogl_path_arc                       (ClutterFixed center_x,
                                                             ClutterFixed center_y,
                                                             ClutterFixed radius_x,
                                                             ClutterFixed radius_y,
                                                             ClutterAngle angle_1,
                                                             ClutterAngle angle_2);

Adds an elliptical arc segment to the current path. A straight line segment will link the current pen location with the first vertex of the arc. If you perform a move_to to the arcs start just before drawing it you create a free standing arc.

`center_x` : | X coordinate of the elliptical arc center
`center_y` : | Y coordinate of the elliptical arc center
`radius_x` : | X radius of the elliptical arc
`radius_y` : | Y radious of the elliptical arc
`angle_1` : | Angle in the unit-circle at which the arc begin
`angle_2` : | Angle in the unit-circle at which the arc ends

### cogl_path_rel_move_to ()

    void                cogl_path_rel_move_to               (ClutterFixed x,
                                                             ClutterFixed y);

Clears the previously constructed shape and begins a new path contour by moving the pen to the given coordinates relative to the current pen location.

`x` : | X offset from the current pen location to move the pen to.
`y` : | Y offset from the current pen location to move the pen to.

### cogl_path_rel_line_to ()

    void                cogl_path_rel_line_to               (ClutterFixed x,
                                                             ClutterFixed y);

Adds a straight line segment to the current path that ends at the given coordinates relative to the current pen location.

`x` : | X offset from the current pen location of the end line vertex
`y` : | Y offset from the current pen location of the end line vertex

### cogl_path_rel_curve_to ()

    void                cogl_path_rel_curve_to              (ClutterFixed x1,
                                                             ClutterFixed y1,
                                                             ClutterFixed x2,
                                                             ClutterFixed y2,
                                                             ClutterFixed x3,
                                                             ClutterFixed y3);

Adds a cubic bezier curve segment to the current path with the given second, third and fourth control points and using current pen location as the first control point. The given coordinates are relative to the current pen location.

`x1` : | X coordinate of the second bezier control point
`y1` : | Y coordinate of the second bezier control point
`x2` : | X coordinate of the third bezier control point
`y2` : | Y coordinate of the third bezier control point
`x3` : | X coordinate of the fourth bezier control point
`y3` : | Y coordinate of the fourth bezier control point

### cogl_path_line ()

    void                cogl_path_line                      (ClutterFixed x1,
                                                             ClutterFixed y1,
                                                             ClutterFixed x2,
                                                             ClutterFixed y2);

Clears the previously constructed shape and constructs a straight line shape start and ending at the given coordinates.

`x1` : | X coordinate of the start line vertex
`y1` : | Y coordinate of the start line vertex
`x2` : | X coordinate of the end line vertex
`y2` : | Y coordinate of the end line vertex

### cogl_path_polyline ()

    void                cogl_path_polyline                  (ClutterFixed *coords,
                                                             gint num_points);

Clears the previously constructed shape and constructs a series of straight line segments, starting from the first given vertex coordinate. Each subsequent segment stars where the previous one ended and ends at the next given vertex coordinate.

The coords array must contain 2 * num_points values. The first value represents the X coordinate of the first vertex, the second value represents the Y coordinate of the first vertex, continuing in the same fashion for the rest of the vertices. (num_points - 1) segments will be constructed.

`coords` : | A pointer to the first element of an array of fixed-point values that specify the vertex coordinates.
`num_points` : | The total number of vertices.

### cogl_path_polygon ()

    void                cogl_path_polygon                   (ClutterFixed *coords,
                                                             gint num_points);

Clears the previously constructed shape and constructs a polygonal shape of the given number of vertices.

The coords array must contain 2 * num_points values. The first value represents the X coordinate of the first vertex, the second value represents the Y coordinate of the first vertex, continuing in the same fashion for the rest of the vertices.

`coords` : | A pointer to the first element of an array of fixed-point values that specify the vertex coordinates.
`num_points` : | The total number of vertices.

### cogl_path_rectangle ()

    void                cogl_path_rectangle                 (ClutterFixed x,
                                                             ClutterFixed y,
                                                             ClutterFixed width,
                                                             ClutterFixed height);

Clears the previously constructed shape and constructs a rectangular shape at the given coordinates.

`x` : | X coordinate of the top-left corner.
`y` : | Y coordinate of the top-left corner.
`width` : | Rectangle width.
`height` : | Rectangle height.

### cogl_path_round_rectangle ()

    void                cogl_path_round_rectangle           (ClutterFixed x,
                                                             ClutterFixed y,
                                                             ClutterFixed width,
                                                             ClutterFixed height,
                                                             ClutterFixed radius,
                                                             ClutterAngle arc_step);

Clears the previously constructed shape and constructs a rectangular shape with rounded corners.

`x` : | X coordinate of the top-left corner
`y` : | Y coordinate of the top-left corner
`width` : | Width of the rectangle
`height` : | Height of the rectangle
`radius` : | Radius of the corner arcs.
`arc_step` : | Angle increment resolution for subdivision of the corner arcs.

### cogl_path_ellipse ()

    void                cogl_path_ellipse                   (ClutterFixed center_x,
                                                             ClutterFixed center_y,
                                                             ClutterFixed radius_x,
                                                             ClutterFixed radius_y);

Clears the previously constructed shape and constructs an ellipse shape.

`center_x` : | X coordinate of the ellipse center
`center_y` : | Y coordinate of the ellipse center
`radius_x` : | X radius of the ellipse
`radius_y` : | Y radius of the ellipse

### cogl_rectangle ()

    void                cogl_rectangle                      (gint x,
                                                             gint y,
                                                             guint width,
                                                             guint height);

Fills a rectangle at the given coordinates with the current drawing color in a highly optimizied fashion.

`x` : | X coordinate of the top-left corner
`y` : | Y coordinate of the top-left corner
`width` : | Width of the rectangle
`height` : | Height of the rectangle

### cogl_rectanglex ()

    void                cogl_rectanglex                     (ClutterFixed x,
                                                             ClutterFixed y,
                                                             ClutterFixed width,
                                                             ClutterFixed height);

A fixed-point version of cogl_fast_fill_rectangle.

`x` : | X coordinate of the top-left corner
`y` : | Y coordinate of the top-left corner
`width` : | Width of the rectangle
`height` : | Height of the rectangle