cogl/cogl-path-functions.h

   1 /*
   2  * Cogl
   3  *
   4  * An object oriented GL/GLES Abstraction/Utility Layer
   5  *
   6  * Copyright (C) 2008,2009,2012 Intel Corporation.
   7  *
   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.
  12  *
  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.
  17  *
  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/>.
  20  *
  21  *
  22  */
  23
  24 #if !defined(__COGL_H_INSIDE__) && !defined(CLUTTER_COMPILATION)
  25 #error "Only <cogl/cogl.h> can be included directly."
  26 #endif
  27
  28 #ifndef __COGL_PATH_FUNCTIONS_H__
  29 #define __COGL_PATH_FUNCTIONS_H__
  30
  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 */
  34
  35 #include <cogl/cogl-types.h>
  36
  37 G_BEGIN_DECLS
  38
  39 /**
  40  * cogl_is_path:
  41  * @handle: A CoglHandle
  42  *
  43  * Gets whether the given handle references an existing path object.
  44  *
  45  * Return value: %TRUE if the handle references a #CoglPath,
  46  *   %FALSE otherwise
  47  */
  48 gboolean
  49 cogl_is_path (CoglHandle handle);
  50
  51 /**
  52  * cogl_path_set_fill_rule:
  53  * @fill_rule: The new fill rule.
  54  *
  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.
  60  *
  61  * Since: 1.4
  62  */
  63 void
  64 cogl_path_set_fill_rule (CoglPathFillRule fill_rule);
  65
  66 /**
  67  * cogl_path_get_fill_rule:
  68  *
  69  * Retrieves the fill rule set using cogl_path_set_fill_rule().
  70  *
  71  * Return value: the fill rule that is used for the current path.
  72  *
  73  * Since: 1.4
  74  */
  75 CoglPathFillRule
  76 cogl_path_get_fill_rule (void);
  77
  78 /**
  79  * cogl_path_fill:
  80  *
  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.
  84  *
  85  * The interior of the shape is determined using the fill rule of the
  86  * path. See %CoglPathFillRule for details.
  87  **/
  88 void
  89 cogl_path_fill (void);
  90
  91 /**
  92  * cogl_path_fill_preserve:
  93  *
  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
  97  * of the shape.
  98  *
  99  * Since: 1.0
 100  **/
 101 void
 102 cogl_path_fill_preserve (void);
 103
 104 /**
 105  * cogl_path_stroke:
 106  *
 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.
 111  **/
 112 void
 113 cogl_path_stroke (void);
 114
 115 /**
 116  * cogl_path_stroke_preserve:
 117  *
 118  * Strokes the constructed shape using the current drawing color and
 119  * preserves the path to be used again.
 120  *
 121  * Since: 1.0
 122  **/
 123 void
 124 cogl_path_stroke_preserve (void);
 125
 126 /**
 127  * cogl_path_new:
 128  *
 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.
 132  *
 133  * Since: 1.0
 134  */
 135 void
 136 cogl_path_new (void);
 137
 138 /**
 139  * cogl_path_move_to:
 140  * @x: X coordinate of the pen location to move to.
 141  * @y: Y coordinate of the pen location to move to.
 142  *
 143  * Moves the pen to the given location. If there is an existing path
 144  * this will start a new disjoint subpath.
 145   **/
 146 void
 147 cogl_path_move_to (float x,
 148                    float y);
 149
 150
 151 /**
 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.
 155  *
 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
 158  * disjoint subpath.
 159  **/
 160 void
 161 cogl_path_rel_move_to (float x,
 162                        float y);
 163
 164 /**
 165  * cogl_path_line_to:
 166  * @x: X coordinate of the end line vertex
 167  * @y: Y coordinate of the end line vertex
 168  *
 169  * Adds a straight line segment to the current path that ends at the
 170  * given coordinates.
 171  **/
 172 void
 173 cogl_path_line_to (float x,
 174                    float y);
 175
 176 /**
 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
 180  *
 181  * Adds a straight line segment to the current path that ends at the
 182  * given coordinates relative to the current pen location.
 183  **/
 184 void
 185 cogl_path_rel_line_to (float x,
 186                        float y);
 187
 188
 189 /**
 190  * cogl_path_arc:
 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
 197  *
 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.
 202  *
 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).
 208  **/
 209 void
 210 cogl_path_arc (float center_x,
 211                float center_y,
 212                float radius_x,
 213                float radius_y,
 214                float angle_1,
 215                float angle_2);
 216
 217 /**
 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
 225  *
 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.
 229  **/
 230 void
 231 cogl_path_curve_to (float x_1,
 232                     float y_1,
 233                     float x_2,
 234                     float y_2,
 235                     float x_3,
 236                     float y_3);
 237
 238 /**
 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
 246  *
 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.
 251  */
 252 void
 253 cogl_path_rel_curve_to (float x_1,
 254                         float y_1,
 255                         float x_2,
 256                         float y_2,
 257                         float x_3,
 258                         float y_3);
 259
 260 /**
 261  * cogl_path_close:
 262  *
 263  * Closes the path being constructed by adding a straight line segment
 264  * to it that ends at the first vertex of the path.
 265  **/
 266 void
 267 cogl_path_close (void);
 268
 269 /**
 270  * cogl_path_line:
 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
 275  *
 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
 278  * disjoint sub-path.
 279  **/
 280 void
 281 cogl_path_line (float x_1,
 282                 float y_1,
 283                 float x_2,
 284                 float y_2);
 285
 286 /**
 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.
 291  *
 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
 296  * coordinate.
 297  *
 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
 302  * be constructed.
 303  **/
 304 void
 305 cogl_path_polyline (const float *coords,
 306                     int          num_points);
 307
 308
 309 /**
 310  * cogl_path_polygon:
 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.
 314  *
 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.
 317  *
 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.
 322  **/
 323 void
 324 cogl_path_polygon (const float *coords,
 325                    int          num_points);
 326
 327
 328 /**
 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.
 334  *
 335  * Constructs a rectangular shape at the given coordinates. If there
 336  * is an existing path this will start a new disjoint sub-path.
 337  **/
 338 void
 339 cogl_path_rectangle (float x_1,
 340                      float y_1,
 341                      float x_2,
 342                      float y_2);
 343
 344 /**
 345  * cogl_path_ellipse:
 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
 350  *
 351  * Constructs an ellipse shape. If there is an existing path this will
 352  * start a new disjoint sub-path.
 353  **/
 354 void
 355 cogl_path_ellipse (float center_x,
 356                    float center_y,
 357                    float radius_x,
 358                    float radius_y);
 359
 360 /**
 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
 368  * the corner arcs.
 369  *
 370  * Constructs a rectangular shape with rounded corners. If there is an
 371  * existing path this will start a new disjoint sub-path.
 372  **/
 373 void
 374 cogl_path_round_rectangle (float x_1,
 375                            float y_1,
 376                            float x_2,
 377                            float y_2,
 378                            float radius,
 379                            float arc_step);
 380
 381 /**
 382  * cogl_get_path: (skip)
 383  *
 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
 389  * cogl_object_ref().
 390  *
 391  * Return value: a pointer to the current path.
 392  *
 393  * Since: 1.4
 394  */
 395 CoglPath *
 396 cogl_get_path (void);
 397
 398 /**
 399  * cogl_set_path: (skip)
 400  * @path: A #CoglPath object
 401  *
 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().
 405  *
 406  * Since: 1.4
 407  */
 408 void
 409 cogl_set_path (CoglPath *path);
 410
 411 /**
 412  * cogl_path_copy: (skip)
 413  * @path: A #CoglPath object
 414  *
 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.
 418  *
 419  * Internally the path will share the data until one of the paths is
 420  * modified so copying paths should be relatively cheap.
 421  *
 422  * Return value: (transfer full): a copy of the path in @path.
 423  */
 424 CoglPath *
 425 cogl_path_copy (CoglPath *path);
 426
 427 G_END_DECLS
 428
 429 #endif /* __COGL_PATH_FUNCTIONS_H__ */
 430