4 * An object oriented GL/GLES Abstraction/Utility Layer
6 * Copyright (C) 2008,2009 Intel Corporation.
8 * This library is free software; you can redistribute it and/or
9 * modify it under the terms of the GNU Lesser General Public
10 * License as published by the Free Software Foundation; either
11 * version 2 of the License, or (at your option) any later version.
13 * This library is distributed in the hope that it will be useful,
14 * but WITHOUT ANY WARRANTY; without even the implied warranty of
15 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
16 * Lesser General Public License for more details.
18 * You should have received a copy of the GNU Lesser General Public
19 * License along with this library. If not, see <http://www.gnu.org/licenses/>.
24 #if !defined(__COGL_H_INSIDE__) && !defined(CLUTTER_COMPILATION)
25 #error "Only <cogl/cogl.h> can be included directly."
28 #ifndef __COGL2_PATH_H__
29 #define __COGL2_PATH_H__
31 #include <cogl/cogl-types.h>
37 * @short_description: Functions for constructing and drawing 2D paths.
39 * There are two levels on which drawing with cogl-paths can be used.
40 * The highest level functions construct various simple primitive
41 * shapes to be either filled or stroked. Using a lower-level set of
42 * functions more complex and arbitrary paths can be constructed by
43 * concatenating straight line, bezier curve and arc segments.
45 * When constructing arbitrary paths, the current pen location is
46 * initialized using the move_to command. The subsequent path segments
47 * implicitly use the last pen location as their first vertex and move
48 * the pen location to the last vertex they produce at the end. Also
49 * there are special versions of functions that allow specifying the
50 * vertices of the path segments relative to the last pen location
51 * rather then in the absolute coordinates.
54 typedef struct _CoglPath CoglPath;
56 #define COGL_PATH(obj) ((CoglPath *)(obj))
58 #define cogl_path_new cogl2_path_new
62 * Creates a new, empty path object. The default fill rule is
63 * %COGL_PATH_FILL_RULE_EVEN_ODD.
65 * Return value: A pointer to a newly allocated #CoglPath, which can
66 * be freed using cogl_object_unref().
75 * @path: A #CoglPath object
77 * Returns a new copy of the path in @path. The new path has a
78 * reference count of 1 so you should unref it with
79 * cogl_object_unref() if you no longer need it.
81 * Internally the path will share the data until one of the paths is
82 * modified so copying paths should be relatively cheap.
84 * Return value: a copy of the path in @path.
89 cogl_path_copy (CoglPath *path);
93 * @object: A #CoglObject
95 * Gets whether the given object references an existing path object.
97 * Return value: %TRUE if the object references a #CoglPath,
103 cogl_is_path (void *object);
105 #define cogl_path_move_to cogl2_path_move_to
108 * @x: X coordinate of the pen location to move to.
109 * @y: Y coordinate of the pen location to move to.
111 * Moves the pen to the given location. If there is an existing path
112 * this will start a new disjoint subpath.
117 cogl_path_move_to (CoglPath *path,
121 #define cogl_path_rel_move_to cogl2_path_rel_move_to
123 * cogl_path_rel_move_to:
124 * @x: X offset from the current pen location to move the pen to.
125 * @y: Y offset from the current pen location to move the pen to.
127 * Moves the pen to the given offset relative to the current pen
128 * location. If there is an existing path this will start a new
134 cogl_path_rel_move_to (CoglPath *path,
138 #define cogl_path_line_to cogl2_path_line_to
141 * @x: X coordinate of the end line vertex
142 * @y: Y coordinate of the end line vertex
144 * Adds a straight line segment to the current path that ends at the
150 cogl_path_line_to (CoglPath *path,
154 #define cogl_path_rel_line_to cogl2_path_rel_line_to
156 * cogl_path_rel_line_to:
157 * @x: X offset from the current pen location of the end line vertex
158 * @y: Y offset from the current pen location of the end line vertex
160 * Adds a straight line segment to the current path that ends at the
161 * given coordinates relative to the current pen location.
166 cogl_path_rel_line_to (CoglPath *path,
170 #define cogl_path_arc cogl2_path_arc
173 * @center_x: X coordinate of the elliptical arc center
174 * @center_y: Y coordinate of the elliptical arc center
175 * @radius_x: X radius of the elliptical arc
176 * @radius_y: Y radius of the elliptical arc
177 * @angle_1: Angle in degrees at which the arc begin
178 * @angle_2: Angle in degrees at which the arc ends
180 * Adds an elliptical arc segment to the current path. A straight line
181 * segment will link the current pen location with the first vertex
182 * of the arc. If you perform a move_to to the arcs start just before
183 * drawing it you create a free standing arc.
185 * The angles are measured in degrees where 0° is in the direction of
186 * the positive X axis and 90° is in the direction of the positive Y
187 * axis. The angle of the arc begins at @angle_1 and heads towards
188 * @angle_2 (so if @angle_2 is less than @angle_1 it will decrease,
189 * otherwise it will increase).
194 cogl_path_arc (CoglPath *path,
202 #define cogl_path_curve_to cogl2_path_curve_to
204 * cogl_path_curve_to:
205 * @x_1: X coordinate of the second bezier control point
206 * @y_1: Y coordinate of the second bezier control point
207 * @x_2: X coordinate of the third bezier control point
208 * @y_2: Y coordinate of the third bezier control point
209 * @x_3: X coordinate of the fourth bezier control point
210 * @y_3: Y coordinate of the fourth bezier control point
212 * Adds a cubic bezier curve segment to the current path with the given
213 * second, third and fourth control points and using current pen location
214 * as the first control point.
219 cogl_path_curve_to (CoglPath *path,
227 #define cogl_path_rel_curve_to cogl2_path_rel_curve_to
229 * cogl_path_rel_curve_to:
230 * @x_1: X coordinate of the second bezier control point
231 * @y_1: Y coordinate of the second bezier control point
232 * @x_2: X coordinate of the third bezier control point
233 * @y_2: Y coordinate of the third bezier control point
234 * @x_3: X coordinate of the fourth bezier control point
235 * @y_3: Y coordinate of the fourth bezier control point
237 * Adds a cubic bezier curve segment to the current path with the given
238 * second, third and fourth control points and using current pen location
239 * as the first control point. The given coordinates are relative to the
240 * current pen location.
245 cogl_path_rel_curve_to (CoglPath *path,
253 #define cogl_path_close cogl2_path_close
257 * Closes the path being constructed by adding a straight line segment
258 * to it that ends at the first vertex of the path.
263 cogl_path_close (CoglPath *path);
265 #define cogl_path_line cogl2_path_line
268 * @x_1: X coordinate of the start line vertex
269 * @y_1: Y coordinate of the start line vertex
270 * @x_2: X coordinate of the end line vertex
271 * @y_2: Y coordinate of the end line vertex
273 * Constructs a straight line shape starting and ending at the given
274 * coordinates. If there is an existing path this will start a new
280 cogl_path_line (CoglPath *path,
286 #define cogl_path_polyline cogl2_path_polyline
288 * cogl_path_polyline:
289 * @coords: (in) (array) (transfer none): A pointer to the first element of an
290 * array of fixed-point values that specify the vertex coordinates.
291 * @num_points: The total number of vertices.
293 * Constructs a series of straight line segments, starting from the
294 * first given vertex coordinate. If there is an existing path this
295 * will start a new disjoint sub-path. Each subsequent segment starts
296 * where the previous one ended and ends at the next given vertex
299 * The coords array must contain 2 * num_points values. The first value
300 * represents the X coordinate of the first vertex, the second value
301 * represents the Y coordinate of the first vertex, continuing in the same
302 * fashion for the rest of the vertices. (num_points - 1) segments will
308 cogl_path_polyline (CoglPath *path,
312 #define cogl_path_polygon cogl2_path_polygon
315 * @coords: (in) (array) (transfer none): A pointer to the first element of
316 * an array of fixed-point values that specify the vertex coordinates.
317 * @num_points: The total number of vertices.
319 * Constructs a polygonal shape of the given number of vertices. If
320 * there is an existing path this will start a new disjoint sub-path.
322 * The coords array must contain 2 * num_points values. The first value
323 * represents the X coordinate of the first vertex, the second value
324 * represents the Y coordinate of the first vertex, continuing in the same
325 * fashion for the rest of the vertices.
330 cogl_path_polygon (CoglPath *path,
334 #define cogl_path_rectangle cogl2_path_rectangle
336 * cogl_path_rectangle:
337 * @x_1: X coordinate of the top-left corner.
338 * @y_1: Y coordinate of the top-left corner.
339 * @x_2: X coordinate of the bottom-right corner.
340 * @y_2: Y coordinate of the bottom-right corner.
342 * Constructs a rectangular shape at the given coordinates. If there
343 * is an existing path this will start a new disjoint sub-path.
348 cogl_path_rectangle (CoglPath *path,
354 #define cogl_path_ellipse cogl2_path_ellipse
357 * @center_x: X coordinate of the ellipse center
358 * @center_y: Y coordinate of the ellipse center
359 * @radius_x: X radius of the ellipse
360 * @radius_y: Y radius of the ellipse
362 * Constructs an ellipse shape. If there is an existing path this will
363 * start a new disjoint sub-path.
368 cogl_path_ellipse (CoglPath *path,
374 #define cogl_path_round_rectangle cogl2_path_round_rectangle
376 * cogl_path_round_rectangle:
377 * @x_1: X coordinate of the top-left corner.
378 * @y_1: Y coordinate of the top-left corner.
379 * @x_2: X coordinate of the bottom-right corner.
380 * @y_2: Y coordinate of the bottom-right corner.
381 * @radius: Radius of the corner arcs.
382 * @arc_step: Angle increment resolution for subdivision of
385 * Constructs a rectangular shape with rounded corners. If there is an
386 * existing path this will start a new disjoint sub-path.
391 cogl_path_round_rectangle (CoglPath *path,
401 * @COGL_PATH_FILL_RULE_NON_ZERO: Each time the line crosses an edge of
402 * the path from left to right one is added to a counter and each time
403 * it crosses from right to left the counter is decremented. If the
404 * counter is non-zero then the point will be filled. See <xref
405 * linkend="fill-rule-non-zero"/>.
406 * @COGL_PATH_FILL_RULE_EVEN_ODD: If the line crosses an edge of the
407 * path an odd number of times then the point will filled, otherwise
408 * it won't. See <xref linkend="fill-rule-even-odd"/>.
410 * #CoglPathFillRule is used to determine how a path is filled. There
411 * are two options - 'non-zero' and 'even-odd'. To work out whether any
412 * point will be filled imagine drawing an infinetely long line in any
413 * direction from that point. The number of times and the direction
414 * that the edges of the path crosses this line determines whether the
415 * line is filled as described below. Any open sub paths are treated
416 * as if there was an extra line joining the first point and the last
419 * The default fill rule is %COGL_PATH_FILL_RULE_EVEN_ODD. The fill
420 * rule is attached to the current path so preserving a path with
421 * cogl_get_path() also preserves the fill rule. Calling
422 * cogl_path_new() resets the current fill rule to the default.
424 * <figure id="fill-rule-non-zero">
425 * <title>Example of filling various paths using the non-zero rule</title>
426 * <graphic fileref="fill-rule-non-zero.png" format="PNG"/>
429 * <figure id="fill-rule-even-odd">
430 * <title>Example of filling various paths using the even-odd rule</title>
431 * <graphic fileref="fill-rule-even-odd.png" format="PNG"/>
437 COGL_PATH_FILL_RULE_NON_ZERO,
438 COGL_PATH_FILL_RULE_EVEN_ODD
441 #define cogl_path_set_fill_rule cogl2_path_set_fill_rule
443 * cogl_path_set_fill_rule:
444 * @fill_rule: The new fill rule.
446 * Sets the fill rule of the current path to @fill_rule. This will
447 * affect how the path is filled when cogl_path_fill() is later
448 * called. Note that the fill rule state is attached to the path so
449 * calling cogl_get_path() will preserve the fill rule and calling
450 * cogl_path_new() will reset the fill rule back to the default.
455 cogl_path_set_fill_rule (CoglPath *path, CoglPathFillRule fill_rule);
457 #define cogl_path_get_fill_rule cogl2_path_get_fill_rule
459 * cogl_path_get_fill_rule:
461 * Retrieves the fill rule set using cogl_path_set_fill_rule().
463 * Return value: the fill rule that is used for the current path.
468 cogl_path_get_fill_rule (CoglPath *path);
470 #define cogl_path_fill cogl2_path_fill
474 * Fills the interior of the constructed shape using the current
477 * The interior of the shape is determined using the fill rule of the
478 * path. See %CoglPathFillRule for details.
480 * <note>The result of referencing sliced textures in your current
481 * pipeline when filling a path are undefined. You should pass
482 * the %COGL_TEXTURE_NO_SLICING flag when loading any texture you will
483 * use while filling a path.</note>
488 cogl_path_fill (CoglPath *path);
490 #define cogl_path_stroke cogl2_path_stroke
494 * Strokes the constructed shape using the current drawing color and a
495 * width of 1 pixel (regardless of the current transformation
501 cogl_path_stroke (CoglPath *path);
505 #endif /* __COGL2_PATH_H__ */