## Primitives

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

## Synopsis

    void                cogl_rectangle                      (float x_1,
                                                             float y_1,
                                                             float x_2,
                                                             float y_2);
    void                cogl_rectangles                     (const float *verts,
                                                             guint n_rects);
    void                cogl_rectangle_with_texture_coords  (float x1,
                                                             float y1,
                                                             float x2,
                                                             float y2,
                                                             float tx1,
                                                             float ty1,
                                                             float tx2,
                                                             float ty2);
    void                cogl_rectangles_with_texture_coords (const float *verts,
                                                             guint n_rects);
    void                cogl_rectangle_with_multitexture_coords
                                                            (float x1,
                                                             float y1,
                                                             float x2,
                                                             float y2,
                                                             const float *tex_coords,
                                                             gint tex_coords_len);
    void                cogl_polygon                        (CoglTextureVertex *vertices,
                                                             guint n_vertices,
                                                             gboolean use_color);

    void                cogl_path_new                       (void);
    void                cogl_path_move_to                   (float x,
                                                             float y);
    void                cogl_path_close                     (void);
    void                cogl_path_line_to                   (float x,
                                                             float y);
    void                cogl_path_curve_to                  (float x_1,
                                                             float y_1,
                                                             float x_2,
                                                             float y_2,
                                                             float x_3,
                                                             float y_3);
    void                cogl_path_arc                       (float center_x,
                                                             float center_y,
                                                             float radius_x,
                                                             float radius_y,
                                                             float angle_1,
                                                             float angle_2);
    void                cogl_path_rel_move_to               (float x,
                                                             float y);
    void                cogl_path_rel_line_to               (float x,
                                                             float y);
    void                cogl_path_rel_curve_to              (float x_1,
                                                             float y_1,
                                                             float x_2,
                                                             float y_2,
                                                             float x_3,
                                                             float y_3);
    void                cogl_path_line                      (float x_1,
                                                             float y_1,
                                                             float x_2,
                                                             float y_2);
    void                cogl_path_polyline                  (float *coords,
                                                             gint num_points);
    void                cogl_path_polygon                   (float *coords,
                                                             gint num_points);
    void                cogl_path_rectangle                 (float x_1,
                                                             float y_1,
                                                             float x_2,
                                                             float y_2);
    void                cogl_path_round_rectangle           (float x_1,
                                                             float y_1,
                                                             float x_2,
                                                             float y_2,
                                                             float radius,
                                                             float arc_step);
    void                cogl_path_ellipse                   (float center_x,
                                                             float center_y,
                                                             float radius_x,
                                                             float radius_y);

    void                cogl_path_fill                      (void);
    void                cogl_path_fill_preserve             (void);
    void                cogl_path_stroke                    (void);
    void                cogl_path_stroke_preserve           (void);
    #define             cogl_color

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

    void                cogl_rectangle                      (float x_1,
                                                             float y_1,
                                                             float x_2,
                                                             float y_2);

Fills a rectangle at the given coordinates with the current source material

`x_1` : | X coordinate of the top-left corner
`y_1` : | Y coordinate of the top-left corner
`x_2` : | X coordinate of the bottom-right corner
`y_2` : | Y coordinate of the bottom-right corner

### cogl_rectangles ()

    void                cogl_rectangles                     (const float *verts,
                                                             guint n_rects);

Draws a series of rectangles in the same way that `cogl_rectangle()` does. In some situations it can give a significant performance boost to use this function rather than calling `cogl_rectangle()` separately for each rectangle.

`verts` should point to an array of floats with `n_rects` * 4 elements. Each group of 4 values corresponds to the parameters x1, y1, x2, and y2, and have the same meaning as in `cogl_rectangle()`.

`verts` : | an array of vertices
`n_rects` : | number of rectangles to draw

Since 1.0

### cogl_rectangle_with_texture_coords ()

    void                cogl_rectangle_with_texture_coords  (float x1,
                                                             float y1,
                                                             float x2,
                                                             float y2,
                                                             float tx1,
                                                             float ty1,
                                                             float tx2,
                                                             float ty2);

Draw a rectangle using the current material and supply texture coordinates to be used for the first texture layer of the material. To draw the entire texture pass in `tx1`=0.0 `ty1`=0.0 `tx2`=1.0 `ty2`=1.0.

Since 1.0

`x1` : | x coordinate upper left on screen.
`y1` : | y coordinate upper left on screen.
`x2` : | x coordinate lower right on screen.
`y2` : | y coordinate lower right on screen.
`tx1` : | x part of texture coordinate to use for upper left pixel
`ty1` : | y part of texture coordinate to use for upper left pixel
`tx2` : | x part of texture coordinate to use for lower right pixel
`ty2` : | y part of texture coordinate to use for left pixel

### cogl_rectangles_with_texture_coords ()

    void                cogl_rectangles_with_texture_coords (const float *verts,
                                                             guint n_rects);

Draws a series of rectangles in the same way that `cogl_rectangle_with_texture_coords()` does. In some situations it can give a significant performance boost to use this function rather than calling `cogl_rectangle_with_texture_coords()` separately for each rectangle.

`verts` should point to an array of floats with `n_rects` * 8 elements. Each group of 8 values corresponds to the parameters x1, y1, x2, y2, tx1, ty1, tx2 and ty2 and have the same meaning as in `cogl_rectangle_with_texture_coords()`.

`verts` : | an array of vertices
`n_rects` : | number of rectangles to draw

Since 0.8.6

### cogl_rectangle_with_multitexture_coords ()

    void                cogl_rectangle_with_multitexture_coords
                                                            (float x1,
                                                             float y1,
                                                             float x2,
                                                             float y2,
                                                             const float *tex_coords,
                                                             gint tex_coords_len);

This function draws a rectangle using the current source material to texture or fill with. As a material may contain multiple texture layers this interface lets you supply texture coordinates for each layer of the material.

The first pair of coordinates are for the first layer (with the smallest layer index) and if you supply less texture coordinates than there are layers in the current source material then default texture coordinates (0.0, 0.0, 1.0, 1.0) are generated.

Since 1.0

`x1` : | x coordinate upper left on screen.
`y1` : | y coordinate upper left on screen.
`x2` : | x coordinate lower right on screen.
`y2` : | y coordinate lower right on screen.
`tex_coords` : | An array containing groups of 4 float values: [tx1, ty1, tx2, ty2] that are interpreted as two texture coordinates; one for the upper left texel, and one for the lower right texel. Each value should be between 0.0 and 1.0, where the coordinate (0.0, 0.0) represents the top left of the texture, and (1.0, 1.0) the bottom right.
`tex_coords_len` : | The length of the tex_coords array. (e.g. for one layer and one group of texture coordinates, this would be 4)

### cogl_polygon ()

    void                cogl_polygon                        (CoglTextureVertex *vertices,
                                                             guint n_vertices,
                                                             gboolean use_color);

Draws a convex polygon using the current source material to fill / texture with according to the texture coordinates passed.

If `use_color` is `TRUE` then the color will be changed for each vertex using the value specified in the color member of CoglTextureVertex. This can be used for example to make the texture fade out by setting the alpha value of the color.

All of the texture coordinates must be in the range [0,1] and repeating the texture is not supported.

Because of the way this function is implemented it will currently only work if either the texture is not sliced or the backend is not OpenGL ES and the minifying and magnifying functions are both set to CGL_NEAREST.

Since 1.0

`vertices` : | An array of CoglTextureVertex structs
`n_vertices` : | The length of the vertices array
`use_color` : | `TRUE` if the color member of CoglTextureVertex should be used

### cogl_path_new ()

    void                cogl_path_new                       (void);

Clears the current path and starts a new one.

Since 1.0

### cogl_path_move_to ()

    void                cogl_path_move_to                   (float x,
                                                             float y);

Moves the pen to the given location. If there is an existing path this will start a new disjoint subpath.

`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                   (float x,
                                                             float 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                  (float x_1,
                                                             float y_1,
                                                             float x_2,
                                                             float y_2,
                                                             float x_3,
                                                             float y_3);

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.

`x_1` : | X coordinate of the second bezier control point
`y_1` : | Y coordinate of the second bezier control point
`x_2` : | X coordinate of the third bezier control point
`y_2` : | Y coordinate of the third bezier control point
`x_3` : | X coordinate of the fourth bezier control point
`y_3` : | Y coordinate of the fourth bezier control point

### cogl_path_arc ()

    void                cogl_path_arc                       (float center_x,
                                                             float center_y,
                                                             float radius_x,
                                                             float radius_y,
                                                             float angle_1,
                                                             float 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 radius 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               (float x,
                                                             float y);

Moves the pen to the given offset relative to the current pen location. If there is an existing path this will start a new disjoint subpath.

`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               (float x,
                                                             float 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              (float x_1,
                                                             float y_1,
                                                             float x_2,
                                                             float y_2,
                                                             float x_3,
                                                             float y_3);

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.

`x_1` : | X coordinate of the second bezier control point
`y_1` : | Y coordinate of the second bezier control point
`x_2` : | X coordinate of the third bezier control point
`y_2` : | Y coordinate of the third bezier control point
`x_3` : | X coordinate of the fourth bezier control point
`y_3` : | Y coordinate of the fourth bezier control point

### cogl_path_line ()

    void                cogl_path_line                      (float x_1,
                                                             float y_1,
                                                             float x_2,
                                                             float y_2);

Constructs a straight line shape starting and ending at the given coordinates. If there is an existing path this will start a new disjoint sub-path.

`x_1` : | X coordinate of the start line vertex
`y_1` : | Y coordinate of the start line vertex
`x_2` : | X coordinate of the end line vertex
`y_2` : | Y coordinate of the end line vertex

### cogl_path_polyline ()

    void                cogl_path_polyline                  (float *coords,
                                                             gint num_points);

Constructs a series of straight line segments, starting from the first given vertex coordinate. If there is an existing path this will start a new disjoint sub-path. Each subsequent segment starts 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                   (float *coords,
                                                             gint num_points);

Constructs a polygonal shape of the given number of vertices. If there is an existing path this will start a new disjoint sub-path.

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                 (float x_1,
                                                             float y_1,
                                                             float x_2,
                                                             float y_2);

Constructs a rectangular shape at the given coordinates. If there is an existing path this will start a new disjoint sub-path.

`x_1` : | X coordinate of the top-left corner.
`y_1` : | Y coordinate of the top-left corner.
`x_2` : | X coordinate of the bottom-right corner.
`y_2` : | Y coordinate of the bottom-right corner.

### cogl_path_round_rectangle ()

    void                cogl_path_round_rectangle           (float x_1,
                                                             float y_1,
                                                             float x_2,
                                                             float y_2,
                                                             float radius,
                                                             float arc_step);

Constructs a rectangular shape with rounded corners. If there is an existing path this will start a new disjoint sub-path.

`x_1` : | X coordinate of the top-left corner.
`y_1` : | Y coordinate of the top-left corner.
`x_2` : | X coordinate of the bottom-right corner.
`y_2` : | Y coordinate of the bottom-right corner.
`radius` : | Radius of the corner arcs.
`arc_step` : | Angle increment resolution for subdivision of the corner arcs.

### cogl_path_ellipse ()

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

Constructs an ellipse shape. If there is an existing path this will start a new disjoint sub-path.

`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_path_fill ()

    void                cogl_path_fill                      (void);

Fills the constructed shape using the current drawing color. The current path is then cleared. To use the path again, call `cogl_path_fill_preserve()` instead.

### cogl_path_fill_preserve ()

    void                cogl_path_fill_preserve             (void);

Fills the constructed shape using the current drawing color and preserves the path to be used again.

Since 1.0

### 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). To current path is then cleared. To use the path again, call `cogl_path_stroke_preserve()` instead.

### cogl_path_stroke_preserve ()

    void                cogl_path_stroke_preserve           (void);

Strokes the constructed shape using the current drawing color and preserves the path to be used again.

Since 1.0

### cogl_color

    #define cogl_color                      cogl_color_REPLACED_BY_cogl_set_source_color