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