4 * An object oriented GL/GLES Abstraction/Utility Layer
6 * Copyright (C) 2008,2009,2012 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 __COGL_PATH_FUNCTIONS_H__
29 #define __COGL_PATH_FUNCTIONS_H__
31 /* The functions are declared separately because cogl-path.c needs to
32 get the function declarations from the old 1.0 API without
33 colliding with the enum declarations from the 2.0 API */
35 #include <cogl/cogl-types.h>
41 * @handle: A CoglHandle
43 * Gets whether the given handle references an existing path object.
45 * Return value: %TRUE if the handle references a #CoglPath,
49 cogl_is_path (CoglHandle handle);
52 * cogl_path_set_fill_rule:
53 * @fill_rule: The new fill rule.
55 * Sets the fill rule of the current path to @fill_rule. This will
56 * affect how the path is filled when cogl_path_fill() is later
57 * called. Note that the fill rule state is attached to the path so
58 * calling cogl_get_path() will preserve the fill rule and calling
59 * cogl_path_new() will reset the fill rule back to the default.
64 cogl_path_set_fill_rule (CoglPathFillRule fill_rule);
67 * cogl_path_get_fill_rule:
69 * Retrieves the fill rule set using cogl_path_set_fill_rule().
71 * Return value: the fill rule that is used for the current path.
76 cogl_path_get_fill_rule (void);
81 * Fills the interior of the constructed shape using the current
82 * drawing color. The current path is then cleared. To use the path
83 * again, call cogl_path_fill_preserve() instead.
85 * The interior of the shape is determined using the fill rule of the
86 * path. See %CoglPathFillRule for details.
89 cogl_path_fill (void);
92 * cogl_path_fill_preserve:
94 * Fills the interior of the constructed shape using the current
95 * drawing color and preserves the path to be used again. See
96 * cogl_path_fill() for a description what is considered the interior
102 cogl_path_fill_preserve (void);
107 * Strokes the constructed shape using the current drawing color and a
108 * width of 1 pixel (regardless of the current transformation
109 * matrix). To current path is then cleared. To use the path again,
110 * call cogl_path_stroke_preserve() instead.
113 cogl_path_stroke (void);
116 * cogl_path_stroke_preserve:
118 * Strokes the constructed shape using the current drawing color and
119 * preserves the path to be used again.
124 cogl_path_stroke_preserve (void);
129 * Clears the current path and starts a new one. Creating a new path
130 * also resets the fill rule to the default which is
131 * %COGL_PATH_FILL_RULE_EVEN_ODD.
136 cogl_path_new (void);
140 * @x: X coordinate of the pen location to move to.
141 * @y: Y coordinate of the pen location to move to.
143 * Moves the pen to the given location. If there is an existing path
144 * this will start a new disjoint subpath.
147 cogl_path_move_to (float x,
152 * cogl_path_rel_move_to:
153 * @x: X offset from the current pen location to move the pen to.
154 * @y: Y offset from the current pen location to move the pen to.
156 * Moves the pen to the given offset relative to the current pen
157 * location. If there is an existing path this will start a new
161 cogl_path_rel_move_to (float x,
166 * @x: X coordinate of the end line vertex
167 * @y: Y coordinate of the end line vertex
169 * Adds a straight line segment to the current path that ends at the
173 cogl_path_line_to (float x,
177 * cogl_path_rel_line_to:
178 * @x: X offset from the current pen location of the end line vertex
179 * @y: Y offset from the current pen location of the end line vertex
181 * Adds a straight line segment to the current path that ends at the
182 * given coordinates relative to the current pen location.
185 cogl_path_rel_line_to (float x,
191 * @center_x: X coordinate of the elliptical arc center
192 * @center_y: Y coordinate of the elliptical arc center
193 * @radius_x: X radius of the elliptical arc
194 * @radius_y: Y radius of the elliptical arc
195 * @angle_1: Angle in degrees at which the arc begin
196 * @angle_2: Angle in degrees at which the arc ends
198 * Adds an elliptical arc segment to the current path. A straight line
199 * segment will link the current pen location with the first vertex
200 * of the arc. If you perform a move_to to the arcs start just before
201 * drawing it you create a free standing arc.
203 * The angles are measured in degrees where 0° is in the direction of
204 * the positive X axis and 90° is in the direction of the positive Y
205 * axis. The angle of the arc begins at @angle_1 and heads towards
206 * @angle_2 (so if @angle_2 is less than @angle_1 it will decrease,
207 * otherwise it will increase).
210 cogl_path_arc (float center_x,
218 * cogl_path_curve_to:
219 * @x_1: X coordinate of the second bezier control point
220 * @y_1: Y coordinate of the second bezier control point
221 * @x_2: X coordinate of the third bezier control point
222 * @y_2: Y coordinate of the third bezier control point
223 * @x_3: X coordinate of the fourth bezier control point
224 * @y_3: Y coordinate of the fourth bezier control point
226 * Adds a cubic bezier curve segment to the current path with the given
227 * second, third and fourth control points and using current pen location
228 * as the first control point.
231 cogl_path_curve_to (float x_1,
239 * cogl_path_rel_curve_to:
240 * @x_1: X coordinate of the second bezier control point
241 * @y_1: Y coordinate of the second bezier control point
242 * @x_2: X coordinate of the third bezier control point
243 * @y_2: Y coordinate of the third bezier control point
244 * @x_3: X coordinate of the fourth bezier control point
245 * @y_3: Y coordinate of the fourth bezier control point
247 * Adds a cubic bezier curve segment to the current path with the given
248 * second, third and fourth control points and using current pen location
249 * as the first control point. The given coordinates are relative to the
250 * current pen location.
253 cogl_path_rel_curve_to (float x_1,
263 * Closes the path being constructed by adding a straight line segment
264 * to it that ends at the first vertex of the path.
267 cogl_path_close (void);
271 * @x_1: X coordinate of the start line vertex
272 * @y_1: Y coordinate of the start line vertex
273 * @x_2: X coordinate of the end line vertex
274 * @y_2: Y coordinate of the end line vertex
276 * Constructs a straight line shape starting and ending at the given
277 * coordinates. If there is an existing path this will start a new
281 cogl_path_line (float x_1,
287 * cogl_path_polyline:
288 * @coords: (in) (array) (transfer none): A pointer to the first element of an
289 * array of fixed-point values that specify the vertex coordinates.
290 * @num_points: The total number of vertices.
292 * Constructs a series of straight line segments, starting from the
293 * first given vertex coordinate. If there is an existing path this
294 * will start a new disjoint sub-path. Each subsequent segment starts
295 * where the previous one ended and ends at the next given vertex
298 * The coords array must contain 2 * num_points values. The first value
299 * represents the X coordinate of the first vertex, the second value
300 * represents the Y coordinate of the first vertex, continuing in the same
301 * fashion for the rest of the vertices. (num_points - 1) segments will
305 cogl_path_polyline (const float *coords,
311 * @coords: (in) (array) (transfer none): A pointer to the first element of
312 * an array of fixed-point values that specify the vertex coordinates.
313 * @num_points: The total number of vertices.
315 * Constructs a polygonal shape of the given number of vertices. If
316 * there is an existing path this will start a new disjoint sub-path.
318 * The coords array must contain 2 * num_points values. The first value
319 * represents the X coordinate of the first vertex, the second value
320 * represents the Y coordinate of the first vertex, continuing in the same
321 * fashion for the rest of the vertices.
324 cogl_path_polygon (const float *coords,
329 * cogl_path_rectangle:
330 * @x_1: X coordinate of the top-left corner.
331 * @y_1: Y coordinate of the top-left corner.
332 * @x_2: X coordinate of the bottom-right corner.
333 * @y_2: Y coordinate of the bottom-right corner.
335 * Constructs a rectangular shape at the given coordinates. If there
336 * is an existing path this will start a new disjoint sub-path.
339 cogl_path_rectangle (float x_1,
346 * @center_x: X coordinate of the ellipse center
347 * @center_y: Y coordinate of the ellipse center
348 * @radius_x: X radius of the ellipse
349 * @radius_y: Y radius of the ellipse
351 * Constructs an ellipse shape. If there is an existing path this will
352 * start a new disjoint sub-path.
355 cogl_path_ellipse (float center_x,
361 * cogl_path_round_rectangle:
362 * @x_1: X coordinate of the top-left corner.
363 * @y_1: Y coordinate of the top-left corner.
364 * @x_2: X coordinate of the bottom-right corner.
365 * @y_2: Y coordinate of the bottom-right corner.
366 * @radius: Radius of the corner arcs.
367 * @arc_step: Angle increment resolution for subdivision of
370 * Constructs a rectangular shape with rounded corners. If there is an
371 * existing path this will start a new disjoint sub-path.
374 cogl_path_round_rectangle (float x_1,
382 * cogl_get_path: (skip)
384 * Gets a pointer to the current path. The path can later be used
385 * again by calling cogl_path_set(). Note that the path isn't copied
386 * so if you later call any functions to add to the path it will
387 * affect the returned object too. No reference is taken on the path
388 * so if you want to retain it you should take your own reference with
391 * Return value: a pointer to the current path.
396 cogl_get_path (void);
399 * cogl_set_path: (skip)
400 * @path: A #CoglPath object
402 * Replaces the current path with @path. A reference is taken on the
403 * object so if you no longer need the path you should unref with
404 * cogl_object_unref().
409 cogl_set_path (CoglPath *path);
412 * cogl_path_copy: (skip)
413 * @path: A #CoglPath object
415 * Returns a new copy of the path in @path. The new path has a
416 * reference count of 1 so you should unref it with
417 * cogl_object_unref() if you no longer need it.
419 * Internally the path will share the data until one of the paths is
420 * modified so copying paths should be relatively cheap.
422 * Return value: (transfer full): a copy of the path in @path.
425 cogl_path_copy (CoglPath *path);
429 #endif /* __COGL_PATH_FUNCTIONS_H__ */