## Primitives

Primitives — Functions that draw various primitive 3D shapes

## Synopsis

    void                cogl_rectangle                      (float x_1,
                                                             float y_1,
                                                             float x_2,
                                                             float y_2);
    void                cogl_rectangles                     (const float *verts,
                                                             unsigned int 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,
                                                             unsigned int n_rects);
    void                cogl_rectangle_with_multitexture_coords
                                                            (float x1,
                                                             float y1,
                                                             float x2,
                                                             float y2,
                                                             const float *tex_coords,
                                                             int tex_coords_len);
    void                cogl_polygon                        (const CoglTextureVertex *vertices,
                                                             unsigned int 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,
                                                             int num_points);
    void                cogl_path_polygon                   (float *coords,
                                                             int 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);

## Description

The primitives API provides utilities for drawing some common 3D shapes in a more convenient way than the CoglVertexBuffer API provides.

## 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,
                                                             unsigned int 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. in. array. transfer none.
`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.

`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

Since 1.0

### cogl_rectangles_with_texture_coords ()

    void                cogl_rectangles_with_texture_coords (const float *verts,
                                                             unsigned int 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. in. array. transfer none.
`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,
                                                             int 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.

`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.. in. array. transfer none.
`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)

Since 1.0

### cogl_polygon ()

    void                cogl_polygon                        (const CoglTextureVertex *vertices,
                                                             unsigned int 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 COGL_MATERIAL_FILTER_NEAREST.

`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

Since 1.0

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

The angles are measured in degrees where 0° is in the direction of the positive X axis and 90° is in the direction of the positive Y axis. The angle of the arc begins at `angle_1` and heads towards `angle_2` (so if `angle_2` is less than `angle_1` it will decrease, otherwise it will increase).

`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 degrees at which the arc begin
`angle_2` : | Angle in degrees 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,
                                                             int 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.. in. array. transfer none.
`num_points` : | The total number of vertices.

### cogl_path_polygon ()

    void                cogl_path_polygon                   (float *coords,
                                                             int 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.. in. array. transfer none.
`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 interior of 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.

The interior of the shape is determined using the 'even-odd' rule. Any open sub-paths are treated as if there is an extra line joining the last point and first point. You can work out whether any point in the stage will be filled if you imagine drawing an infinitely long line in any direction from that point and then counting the number times it crosses a line in the path. If the number is odd it will be filled, otherwise it will not.

See Figure 1, “Example of filling various paths” for a demonstration of the fill rule.

Figure 1. Example of filling various paths

### cogl_path_fill_preserve ()

    void                cogl_path_fill_preserve             (void);

Fills the interior of the constructed shape using the current drawing color and preserves the path to be used again. See `cogl_path_fill()` for a description what is considered the interior of the shape.

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