cogl/cogl2-path.h

   1 /*
   2  * Cogl
   3  *
   4  * An object oriented GL/GLES Abstraction/Utility Layer
   5  *
   6  * Copyright (C) 2008,2009 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 __COGL2_PATH_H__
  29 #define __COGL2_PATH_H__
  30
  31 #include <cogl/cogl-types.h>
  32
  33 G_BEGIN_DECLS
  34
  35 /**
  36  * SECTION:cogl-paths
  37  * @short_description: Functions for constructing and drawing 2D paths.
  38  *
  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.
  44  *
  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.
  52  */
  53
  54 typedef struct _CoglPath CoglPath;
  55
  56 #define COGL_PATH(obj) ((CoglPath *)(obj))
  57
  58 #define cogl_path_new cogl2_path_new
  59 /**
  60  * cogl_path_new:
  61  *
  62  * Creates a new, empty path object. The default fill rule is
  63  * %COGL_PATH_FILL_RULE_EVEN_ODD.
  64  *
  65  * Return value: A pointer to a newly allocated #CoglPath, which can
  66  * be freed using cogl_object_unref().
  67  *
  68  * Since: 2.0
  69  */
  70 CoglPath *
  71 cogl_path_new (void);
  72
  73 /**
  74  * cogl_path_copy:
  75  * @path: A #CoglPath object
  76  *
  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.
  80  *
  81  * Internally the path will share the data until one of the paths is
  82  * modified so copying paths should be relatively cheap.
  83  *
  84  * Return value: a copy of the path in @path.
  85  *
  86  * Since: 2.0
  87  */
  88 CoglPath *
  89 cogl_path_copy (CoglPath *path);
  90
  91 /**
  92  * cogl_is_path:
  93  * @object: A #CoglObject
  94  *
  95  * Gets whether the given object references an existing path object.
  96  *
  97  * Return value: %TRUE if the object references a #CoglPath,
  98  *   %FALSE otherwise.
  99  *
 100  * Since: 2.0
 101  */
 102 gboolean
 103 cogl_is_path (void *object);
 104
 105 #define cogl_path_move_to cogl2_path_move_to
 106 /**
 107  * cogl_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.
 110  *
 111  * Moves the pen to the given location. If there is an existing path
 112  * this will start a new disjoint subpath.
 113  *
 114  * Since: 2.0
 115  */
 116 void
 117 cogl_path_move_to (CoglPath *path,
 118                    float x,
 119                    float y);
 120
 121 #define cogl_path_rel_move_to cogl2_path_rel_move_to
 122 /**
 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.
 126  *
 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
 129  * disjoint subpath.
 130  *
 131  * Since: 2.0
 132  */
 133 void
 134 cogl_path_rel_move_to (CoglPath *path,
 135                        float x,
 136                        float y);
 137
 138 #define cogl_path_line_to cogl2_path_line_to
 139 /**
 140  * cogl_path_line_to:
 141  * @x: X coordinate of the end line vertex
 142  * @y: Y coordinate of the end line vertex
 143  *
 144  * Adds a straight line segment to the current path that ends at the
 145  * given coordinates.
 146  *
 147  * Since: 2.0
 148  */
 149 void
 150 cogl_path_line_to (CoglPath *path,
 151                    float x,
 152                    float y);
 153
 154 #define cogl_path_rel_line_to cogl2_path_rel_line_to
 155 /**
 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
 159  *
 160  * Adds a straight line segment to the current path that ends at the
 161  * given coordinates relative to the current pen location.
 162  *
 163  * Since: 2.0
 164  */
 165 void
 166 cogl_path_rel_line_to (CoglPath *path,
 167                        float x,
 168                        float y);
 169
 170 #define cogl_path_arc cogl2_path_arc
 171 /**
 172  * cogl_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
 179  *
 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.
 184  *
 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).
 190  *
 191  * Since: 2.0
 192  */
 193 void
 194 cogl_path_arc (CoglPath *path,
 195                float center_x,
 196                float center_y,
 197                float radius_x,
 198                float radius_y,
 199                float angle_1,
 200                float angle_2);
 201
 202 #define cogl_path_curve_to cogl2_path_curve_to
 203 /**
 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
 211  *
 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.
 215  *
 216  * Since: 2.0
 217  */
 218 void
 219 cogl_path_curve_to (CoglPath *path,
 220                     float x_1,
 221                     float y_1,
 222                     float x_2,
 223                     float y_2,
 224                     float x_3,
 225                     float y_3);
 226
 227 #define cogl_path_rel_curve_to cogl2_path_rel_curve_to
 228 /**
 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
 236  *
 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.
 241  *
 242  * Since: 2.0
 243  */
 244 void
 245 cogl_path_rel_curve_to (CoglPath *path,
 246                         float x_1,
 247                         float y_1,
 248                         float x_2,
 249                         float y_2,
 250                         float x_3,
 251                         float y_3);
 252
 253 #define cogl_path_close cogl2_path_close
 254 /**
 255  * cogl_path_close:
 256  *
 257  * Closes the path being constructed by adding a straight line segment
 258  * to it that ends at the first vertex of the path.
 259  *
 260  * Since: 2.0
 261  */
 262 void
 263 cogl_path_close (CoglPath *path);
 264
 265 #define cogl_path_line cogl2_path_line
 266 /**
 267  * cogl_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
 272  *
 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
 275  * disjoint sub-path.
 276  *
 277  * Since: 2.0
 278  */
 279 void
 280 cogl_path_line (CoglPath *path,
 281                 float x_1,
 282                 float y_1,
 283                 float x_2,
 284                 float y_2);
 285
 286 #define cogl_path_polyline cogl2_path_polyline
 287 /**
 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.
 292  *
 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
 297  * coordinate.
 298  *
 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
 303  * be constructed.
 304  *
 305  * Since: 2.0
 306  */
 307 void
 308 cogl_path_polyline (CoglPath *path,
 309                     const float *coords,
 310                     int num_points);
 311
 312 #define cogl_path_polygon cogl2_path_polygon
 313 /**
 314  * cogl_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.
 318  *
 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.
 321  *
 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.
 326  *
 327  * Since: 2.0
 328  */
 329 void
 330 cogl_path_polygon (CoglPath *path,
 331                    const float *coords,
 332                    int num_points);
 333
 334 #define cogl_path_rectangle cogl2_path_rectangle
 335 /**
 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.
 341  *
 342  * Constructs a rectangular shape at the given coordinates. If there
 343  * is an existing path this will start a new disjoint sub-path.
 344  *
 345  * Since: 2.0
 346  */
 347 void
 348 cogl_path_rectangle (CoglPath *path,
 349                      float x_1,
 350                      float y_1,
 351                      float x_2,
 352                      float y_2);
 353
 354 #define cogl_path_ellipse cogl2_path_ellipse
 355 /**
 356  * cogl_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
 361  *
 362  * Constructs an ellipse shape. If there is an existing path this will
 363  * start a new disjoint sub-path.
 364  *
 365  * Since: 2.0
 366  */
 367 void
 368 cogl_path_ellipse (CoglPath *path,
 369                    float center_x,
 370                    float center_y,
 371                    float radius_x,
 372                    float radius_y);
 373
 374 #define cogl_path_round_rectangle cogl2_path_round_rectangle
 375 /**
 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
 383  * the corner arcs.
 384  *
 385  * Constructs a rectangular shape with rounded corners. If there is an
 386  * existing path this will start a new disjoint sub-path.
 387  *
 388  * Since: 2.0
 389  */
 390 void
 391 cogl_path_round_rectangle (CoglPath *path,
 392                            float x_1,
 393                            float y_1,
 394                            float x_2,
 395                            float y_2,
 396                            float radius,
 397                            float arc_step);
 398
 399 /**
 400  * CoglPathFillRule:
 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"/>.
 409  *
 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
 417  * point.
 418  *
 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.
 423  *
 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"/>
 427  * </figure>
 428  *
 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"/>
 432  * </figure>
 433  *
 434  * Since: 1.4
 435  */
 436 typedef enum {
 437   COGL_PATH_FILL_RULE_NON_ZERO,
 438   COGL_PATH_FILL_RULE_EVEN_ODD
 439 } CoglPathFillRule;
 440
 441 #define cogl_path_set_fill_rule cogl2_path_set_fill_rule
 442 /**
 443  * cogl_path_set_fill_rule:
 444  * @fill_rule: The new fill rule.
 445  *
 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.
 451  *
 452  * Since: 2.0
 453  */
 454 void
 455 cogl_path_set_fill_rule (CoglPath *path, CoglPathFillRule fill_rule);
 456
 457 #define cogl_path_get_fill_rule cogl2_path_get_fill_rule
 458 /**
 459  * cogl_path_get_fill_rule:
 460  *
 461  * Retrieves the fill rule set using cogl_path_set_fill_rule().
 462  *
 463  * Return value: the fill rule that is used for the current path.
 464  *
 465  * Since: 2.0
 466  */
 467 CoglPathFillRule
 468 cogl_path_get_fill_rule (CoglPath *path);
 469
 470 #define cogl_path_fill cogl2_path_fill
 471 /**
 472  * cogl_path_fill:
 473  *
 474  * Fills the interior of the constructed shape using the current
 475  * drawing color.
 476  *
 477  * The interior of the shape is determined using the fill rule of the
 478  * path. See %CoglPathFillRule for details.
 479  *
 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>
 484  *
 485  * Since: 2.0
 486  */
 487 void
 488 cogl_path_fill (CoglPath *path);
 489
 490 #define cogl_path_stroke cogl2_path_stroke
 491 /**
 492  * cogl_path_stroke:
 493  *
 494  * Strokes the constructed shape using the current drawing color and a
 495  * width of 1 pixel (regardless of the current transformation
 496  * matrix).
 497  *
 498  * Since: 2.0
 499  */
 500 void
 501 cogl_path_stroke (CoglPath *path);
 502
 503 G_END_DECLS
 504
 505 #endif /* __COGL2_PATH_H__ */
 506