Primitives

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

Synopsis

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 x1,
                                                         float y1,
                                                         float x2,
                                                         float y2,
                                                         float x3,
                                                         float y3);
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 x1,
                                                         float y1,
                                                         float x2,
                                                         float y2,
                                                         float x3,
                                                         float y3);
void                cogl_path_line                      (float x1,
                                                         float y1,
                                                         float x2,
                                                         float y2);
void                cogl_path_polyline                  (float *coords,
                                                         gint num_points);
void                cogl_path_polygon                   (float *coords,
                                                         gint num_points);
void                cogl_path_rectangle                 (float x,
                                                         float y,
                                                         float width,
                                                         float height);
void                cogl_path_round_rectangle           (float x,
                                                         float y,
                                                         float width,
                                                         float height,
                                                         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);
void                cogl_set_source_color               (const CoglColor *color);
void                cogl_set_source_color4ub            (guint8 red,
                                                         guint8 green,
                                                         guint8 blue,
                                                         guint8 alpha);
void                cogl_set_source_color4f             (float red,
                                                         float green,
                                                         float blue,
                                                         float alpha);
void                cogl_set_source_texture             (CoglHandle texture_handle);
#define             cogl_color

void                cogl_rectangle                      (float x1,
                                                         float y1,
                                                         float x2,
                                                         float y2);
void                cogl_polygon                        (CoglTextureVertex *vertices,
                                                         guint n_vertices,
                                                         gboolean use_color);
void                cogl_rectangle_with_multitexture_coords
                                                        (float x1,
                                                         float y1,
                                                         float x2,
                                                         float y2,
                                                         const float *tex_coords,
                                                         gint tex_coords_len);
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);

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_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 x1,
                                                         float y1,
                                                         float x2,
                                                         float y2,
                                                         float x3,
                                                         float 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                       (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 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               (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 x1,
                                                         float y1,
                                                         float x2,
                                                         float y2,
                                                         float x3,
                                                         float 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                      (float x1,
                                                         float y1,
                                                         float x2,
                                                         float y2);

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.

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                  (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,
                                                         float y,
                                                         float width,
                                                         float height);

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

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           (float x,
                                                         float y,
                                                         float width,
                                                         float height,
                                                         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 :

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                   (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_set_source_color ()

void                cogl_set_source_color               (const CoglColor *color);

Sets the source color using normalized values for each component. This color will be used for any subsequent drawing operation.

See also cogl_set_source_color4ub() and cogl_set_source_color4f() if you already have the color components.

color :

a CoglColor

Since 1.0


cogl_set_source_color4ub ()

void                cogl_set_source_color4ub            (guint8 red,
                                                         guint8 green,
                                                         guint8 blue,
                                                         guint8 alpha);

Sets the source color using unsigned bytes for each component. This color will be used for any subsequent drawing operation.

The value for each component is an unsigned byte in the range between 0 and 255.

red :

value of the red channel, between 0 and 255

green :

value of the green channel, between 0 and 255

blue :

value of the blue channel, between 0 and 255

alpha :

value of the alpha channel, between 0 and 255

Since 1.0


cogl_set_source_color4f ()

void                cogl_set_source_color4f             (float red,
                                                         float green,
                                                         float blue,
                                                         float alpha);

Sets the source color using normalized values for each component. This color will be used for any subsequent drawing operation.

The value for each component is a fixed point number in the range between 0 and 1.0. If the values passed in are outside that range, they will be clamped.

red :

value of the red channel, between 0 and 1.0

green :

value of the green channel, between 0 and 1.0

blue :

value of the blue channel, between 0 and 1.0

alpha :

value of the alpha channel, between 0 and 1.0

Since 1.0


cogl_set_source_texture ()

void                cogl_set_source_texture             (CoglHandle texture_handle);

This is a convenience function for creating a material with the first layer set to texture_handle and setting that material as the source with cogl_set_source.

Since 1.0

texture_handle :

The Cogl texture you want as your source

cogl_color

#define cogl_color              cogl_color_REPLACED_BY_cogl_set_source_color


cogl_rectangle ()

void                cogl_rectangle                      (float x1,
                                                         float y1,
                                                         float x2,
                                                         float y2);

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

x1 :

X coordinate of the top-left corner

y1 :

Y coordinate of the top-left corner

x2 :

X coordinate of the bottom-right corner

y2 :

Y coordinate of the bottom-right corner

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_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_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