adg/adg-path.c

   1 /* ADG - Automatic Drawing Generation
   2  * Copyright (C) 2007,2008,2009 Nicola Fontana <ntd at entidi.it>
   3  *
   4  * This library is free software; you can redistribute it and/or
   5  * modify it under the terms of the GNU Lesser General Public
   6  * License as published by the Free Software Foundation; either
   7  * version 2 of the License, or (at your option) any later version.
   8  *
   9  * This library is distributed in the hope that it will be useful,
  10  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  11  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  12  * Lesser General Public License for more details.
  13  *
  14  * You should have received a copy of the GNU Lesser General Public
  15  * License along with this library; if not, write to the
  16  * Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
  17  * Boston, MA  02110-1301, USA.
  18  */
  19
  20
  21 /**
  22  * SECTION:path
  23  * @title: AdgPath
  24  * @short_description: The basic model representing a generic path
  25  *
  26  * The #AdgPath model is a virtual path: in a few words, it is a
  27  * simple conceptual #cairo_path_t struct. This class implements
  28  * methods to manipulate the underlying cairo path.
  29  *
  30  * Although some of the provided methods are clearly based on the
  31  * original cairo path manipulation API, their behavior could be
  32  * sligthly different. This is intentional, because the ADG provides
  33  * additional path manipulation algorithms, sometime quite complex,
  34  * and a more restrictive filter on the path quality is required.
  35  * Also, the ADG is designed to be used by technicians while cairo
  36  * targets a broader range of developers.
  37  *
  38  * As an example, following the rule of the less surprise, some
  39  * cairo functions guess the current point when it is not defined,
  40  * while the #AdgPath methods trigger a warning without other effect.
  41  * Furthermore, after a cairo_path_close_path() call a MOVE_TO
  42  * primitive to the starting point of the segment is automatically
  43  * added by cairo while in the ADG, after an adg_path_close(), the
  44  * current point is simply unset.
  45  **/
  46
  47 #include "adg-path.h"
  48 #include "adg-path-private.h"
  49 #include "adg-intl.h"
  50
  51 #include <math.h>
  52
  53 #define PARENT_CLASS    ((AdgModelClass *) adg_path_parent_class)
  54
  55
  56 static void             finalize                (GObject        *object);
  57 static void             changed                 (AdgModel       *model);
  58 static void             clear_cairo_path        (AdgPath        *path);
  59 static cairo_path_t *   get_cairo_path          (AdgPath        *path);
  60 static GArray *         arc_to_curves           (GArray         *array,
  61                                                  const cairo_path_data_t *src);
  62 static void             append_valist           (AdgPath        *path,
  63                                                  cairo_path_data_type_t type,
  64                                                  int             length,
  65                                                  va_list         var_args);
  66
  67
  68 G_DEFINE_TYPE(AdgPath, adg_path, ADG_TYPE_MODEL);
  69
  70
  71 static void
  72 adg_path_class_init(AdgPathClass *klass)
  73 {
  74     GObjectClass *gobject_class;
  75     AdgModelClass *model_class;
  76
  77     gobject_class = (GObjectClass *) klass;
  78     model_class = (AdgModelClass *) klass;
  79
  80     g_type_class_add_private(klass, sizeof(AdgPathPrivate));
  81
  82     gobject_class->finalize = finalize;
  83
  84     model_class->changed = changed;
  85 }
  86
  87 static void
  88 adg_path_init(AdgPath *path)
  89 {
  90     AdgPathPrivate *priv = G_TYPE_INSTANCE_GET_PRIVATE(path, ADG_TYPE_PATH,
  91                                                        AdgPathPrivate);
  92
  93     priv->cp_is_valid = FALSE;
  94     priv->path = g_array_new(FALSE, FALSE, sizeof(cairo_path_data_t));
  95     priv->cairo_path.status = CAIRO_STATUS_INVALID_PATH_DATA;
  96     priv->cairo_path.data = NULL;
  97     priv->cairo_path.num_data = 0;
  98
  99     path->priv = priv;
 100 }
 101
 102 static void
 103 finalize(GObject *object)
 104 {
 105     AdgPath *path = (AdgPath *) object;
 106
 107     g_array_free(path->priv->path, TRUE);
 108     clear_cairo_path(path);
 109
 110     ((GObjectClass *) PARENT_CLASS)->finalize(object);
 111 }
 112
 113
 114 /**
 115  * adg_path_new:
 116  *
 117  * Creates a new path model. The path must be constructed in the @callback
 118  * function: AdgPath will cache and reuse the cairo_copy_path() returned by
 119  * the cairo context after the @callback call.
 120  *
 121  * Return value: the new model
 122  **/
 123 AdgModel *
 124 adg_path_new(void)
 125 {
 126     return (AdgModel *) g_object_new(ADG_TYPE_PATH, NULL);
 127 }
 128
 129
 130 /**
 131  * adg_path_get_cairo_path:
 132  * @path: an #AdgPath
 133  *
 134  * Gets a pointer to the cairo path structure of @path. The return value
 135  * is owned by @path and must be considered read-only.
 136  *
 137  * This function also converts %CAIRO_PATH_ARC_TO primitives, not
 138  * recognized by cairo, into approximated Bézier curves. The conversion
 139  * is cached so any furter request is O(1). This cache is cleared
 140  * whenever @path is modified (by adding a new primitive or by calling
 141  * adg_path_clear()).
 142  *
 143  * <important>
 144  * <title>TODO</title>
 145  * <itemizedlist>
 146  * <listitem>Actually, the arcs are approximated to Bézier using the
 147  *           hardcoded max angle of PI/2. This should be customizable
 148  *           by adding, for instance, a property to the #AdgPath class
 149  *           with a default value of PI/2.</listitem>
 150  * </itemizedlist>
 151  * </important>
 152  *
 153  * Return value: a pointer to the internal cairo path or %NULL on errors
 154  **/
 155 const cairo_path_t *
 156 adg_path_get_cairo_path(AdgPath *path)
 157 {
 158     g_return_val_if_fail(ADG_IS_PATH(path), NULL);
 159
 160     return get_cairo_path(path);
 161 }
 162
 163 /**
 164  * adg_path_get_cpml_path:
 165  * @path: an #AdgPath
 166  *
 167  * Gets a pointer to the cairo path structure of @path. The return
 168  * value is owned by @path and must not be freed.
 169  *
 170  * This function is similar to adg_path_get_cairo_path() but has
 171  * two important differences: firstly the arc primitives are not
 172  * expanded to Bézier curves so the returned path is effectively
 173  * the path stored internally in @path. Secondly, the returned
 174  * path is not read-only.
 175  *
 176  * The returned path is allowed to be modified as long as its size
 177  * is retained and it keeps a valid path. Also, after modifying
 178  * @path the returned path has no meaning and is likely to contain
 179  * plain garbage.
 180  *
 181  * Return value: a pointer to the internal cpml path or %NULL on errors
 182  **/
 183 cairo_path_t *
 184 adg_path_get_cpml_path(AdgPath *path)
 185 {
 186     cairo_path_t *cpml_path;
 187
 188     g_return_val_if_fail(ADG_IS_PATH(path), NULL);
 189
 190     clear_cairo_path(path);
 191
 192     cpml_path = &path->priv->cpml_path;
 193     cpml_path->status = CAIRO_STATUS_SUCCESS;
 194     cpml_path->data = (cairo_path_data_t *) path->priv->path->data;
 195     cpml_path->num_data = path->priv->path->len;
 196
 197     return cpml_path;
 198 }
 199
 200 /**
 201  * adg_path_get_current_point:
 202  * @path: an #AdgPath
 203  * @x:    return value for x coordinate of the current point
 204  * @y:    return value for y coordinate of the current point
 205  *
 206  * Gets the current point of @path, which is conceptually the
 207  * final point reached by the path so far.
 208  *
 209  * If there is no defined current point, @x and @y will both be set
 210  * to 0 and a warning will be triggered. It is possible to check this
 211  * in advance with adg_path_has_current_point().
 212  *
 213  * Most #AdgPath methods alter the current point and most of them
 214  * expect a current point to be defined otherwise will fail triggering
 215  * a warning. Check the description of every method for specific details.
 216  **/
 217 void
 218 adg_path_get_current_point(AdgPath *path, gdouble *x, gdouble *y)
 219 {
 220     g_return_if_fail(ADG_IS_PATH(path));
 221
 222     if (path->priv->cp_is_valid) {
 223         *x = path->priv->cp.x;
 224         *y = path->priv->cp.y;
 225     } else {
 226         *x = *y = 0.;
 227         g_return_if_reached();
 228     }
 229 }
 230
 231 /**
 232  * adg_path_has_current_point:
 233  * @path: an #AdgPath
 234  *
 235  * Returns whether a current point is defined on @path.
 236  * See adg_path_get_current_point() for details on the current point.
 237  *
 238  * Return value: whether a current point is defined
 239  **/
 240 gboolean
 241 adg_path_has_current_point(AdgPath *path)
 242 {
 243     g_return_val_if_fail(ADG_IS_PATH(path), FALSE);
 244
 245     return path->priv->cp_is_valid;
 246 }
 247
 248 /**
 249  * adg_path_clear:
 250  * @path: an #AdgPath
 251  *
 252  * Releases the internal memory hold by @path and resets its status,
 253  * so that after this call @path contains an empty path.
 254  **/
 255 void
 256 adg_path_clear(AdgPath *path)
 257 {
 258     g_return_if_fail(ADG_IS_PATH(path));
 259
 260     g_array_set_size(path->priv->path, 0);
 261     clear_cairo_path(path);
 262 }
 263
 264
 265 /**
 266  * adg_path_append:
 267  * @path: an #AdgPath
 268  * @type: a #cairo_data_type_t value
 269  * @...:  point data, specified as #AdgPair pointers
 270  *
 271  * Generic method to append a primitive to @path. The number of #AdgPair
 272  * structs depends on @type: there is no way with this function to
 273  * reserve more cairo_path_data_t structs than what is needed by the
 274  * primitive.
 275  *
 276  * This function accepts also the special %CAIRO_PATH_ARC_TO primitive.
 277  *
 278  * If @path has no current point while the requested primitive needs it,
 279  * a warning message will be triggered without other effect.
 280  **/
 281 void
 282 adg_path_append(AdgPath *path, cairo_path_data_type_t type, ...)
 283 {
 284     va_list var_args;
 285
 286     va_start(var_args, type);
 287     adg_path_append_valist(path, type, var_args);
 288     va_end(var_args);
 289 }
 290
 291 /**
 292  * adg_path_append_valist:
 293  * @path:     an #AdgPath
 294  * @type:     a #cairo_data_type_t value
 295  * @var_args: point data, specified as #AdgPair pointers
 296  *
 297  * va_list version of adg_path_append().
 298  **/
 299 void
 300 adg_path_append_valist(AdgPath *path, cairo_path_data_type_t type,
 301                        va_list var_args)
 302 {
 303     gint length;
 304
 305     g_return_if_fail(ADG_IS_PATH(path));
 306
 307     switch (type) {
 308
 309     case CAIRO_PATH_CLOSE_PATH:
 310         g_return_if_fail(path->priv->cp_is_valid);
 311         length = 1;
 312         break;
 313
 314     case CAIRO_PATH_MOVE_TO:
 315         length = 2;
 316         break;
 317
 318     case CAIRO_PATH_LINE_TO:
 319         g_return_if_fail(path->priv->cp_is_valid);
 320         length = 2;
 321         break;
 322
 323     case CAIRO_PATH_ARC_TO:
 324         g_return_if_fail(path->priv->cp_is_valid);
 325         length = 3;
 326         break;
 327
 328     case CAIRO_PATH_CURVE_TO:
 329         g_return_if_fail(path->priv->cp_is_valid);
 330         length = 4;
 331         break;
 332
 333     default:
 334         g_assert_not_reached();
 335         return;
 336     }
 337
 338     append_valist(path, type, length, var_args);
 339 }
 340
 341
 342 /**
 343  * adg_path_move_to:
 344  * @path: an #AdgPath
 345  * @x:    the new x coordinate
 346  * @y:    the new y coordinate
 347  *
 348  * Begins a new segment. After this call the current point will be (@x, @y).
 349  **/
 350 void
 351 adg_path_move_to(AdgPath *path, gdouble x, gdouble y)
 352 {
 353     AdgPair p;
 354
 355     p.x = x;
 356     p.y = y;
 357
 358     adg_path_append(path, CAIRO_PATH_MOVE_TO, &p);
 359 }
 360
 361 /**
 362  * adg_path_line_to:
 363  * @path: an #AdgPath
 364  * @x:    the new x coordinate
 365  * @y:    the new y coordinate
 366  *
 367  * Adds a line to @path from the current point to position (@x, @y).
 368  * After this call the current point will be (@x, @y).
 369  *
 370  * If @path has no current point before this call, this function will
 371  * trigger a warning without other effect.
 372  **/
 373 void
 374 adg_path_line_to(AdgPath *path, gdouble x, gdouble y)
 375 {
 376     AdgPair p;
 377
 378     p.x = x;
 379     p.y = y;
 380
 381     adg_path_append(path, CAIRO_PATH_LINE_TO, &p);
 382 }
 383
 384 /**
 385  * adg_path_arc_to:
 386  * @path: an #AdgPath
 387  * @x1:   the x coordinate of an intermediate point
 388  * @y1:   the y coordinate of an intermediate point
 389  * @x2:   the x coordinate of the end of the arc
 390  * @y2:   the y coordinate of the end of the arc
 391  *
 392  * Adds an arc to the path from the current point to (@x2, @y2),
 393  * passing throught (@x1, @y1). After this call the current point
 394  * will be (@x2, @y2).
 395  *
 396  * If @path has no current point before this call, this function will
 397  * trigger a warning without other effect.
 398  **/
 399 void
 400 adg_path_arc_to(AdgPath *path, gdouble x1, gdouble y1, gdouble x2, gdouble y2)
 401 {
 402     AdgPair p[2];
 403
 404     p[0].x = x1;
 405     p[0].y = y1;
 406     p[1].x = x2;
 407     p[1].y = y2;
 408
 409     adg_path_append(path, CAIRO_PATH_ARC_TO, &p[0], &p[1]);
 410 }
 411
 412 /**
 413  * adg_path_curve_to:
 414  * @path: an #AdgPath
 415  * @x1:   the x coordinate of the first control point
 416  * @y1:   the y coordinate of the first control point
 417  * @x2:   the x coordinate of the second control point
 418  * @y2:   the y coordinate of the second control point
 419  * @x3:   the x coordinate of the end of the curve
 420  * @y3:   the y coordinate of the end of the curve
 421  *
 422  * Adds a cubic Bézier curve to the path from the current point to
 423  * position (@x3, @y3), using (@x1, @y1) and (@x2, @y2) as the
 424  * control points. After this call the current point will be (@x3, @y3).
 425  *
 426  * If @path has no current point before this call, this function will
 427  * trigger a warning without other effect.
 428  **/
 429 void
 430 adg_path_curve_to(AdgPath *path, gdouble x1, gdouble y1,
 431                   gdouble x2, gdouble y2, gdouble x3, gdouble y3)
 432 {
 433     AdgPair p[3];
 434
 435     p[0].x = x1;
 436     p[0].y = y1;
 437     p[1].x = x2;
 438     p[1].y = y2;
 439     p[2].x = x3;
 440     p[2].y = y3;
 441
 442     adg_path_append(path, CAIRO_PATH_CURVE_TO, &p[0], &p[1], &p[2]);
 443 }
 444
 445 /**
 446  * adg_path_close:
 447  * @path: an #AdgPath
 448  *
 449  * Adds a line segment to the path from the current point to the
 450  * beginning of the current segment, (the most recent point passed
 451  * to an adg_path_move_to()), and closes this segment.
 452  * After this call the current point will be unset.
 453  *
 454  * The behavior of adg_path_close() is distinct from simply calling
 455  * adg_line_to() with the coordinates of the segment starting point.
 456  * When a closed segment is stroked, there are no caps on the ends.
 457  * Instead, there is a line join connecting the final and initial
 458  * primitive of the segment.
 459  *
 460  * If @path has no current point before this call, this function will
 461  * trigger a warning without other effect.
 462  **/
 463 void
 464 adg_path_close(AdgPath *path)
 465 {
 466     adg_path_append(path, CAIRO_PATH_CLOSE_PATH);
 467 }
 468
 469 /**
 470  * adg_path_arc
 471  * @path:  an #AdgPath
 472  * @xc:    x position of the center of the arc
 473  * @yc:    y position of the center of the arc
 474  * @r:     the radius of the arc
 475  * @start: the start angle, in radians
 476  * @end:   the end angle, in radians
 477  *
 478  * A more usual way to add an arc to @path. After this call, the current
 479  * point will be the computed end point of the arc. The arc will be
 480  * rendered in increasing angle, accordling to @start and @end. This means
 481  * if @start is less than @end, the arc will be rendered in clockwise
 482  * direction (accordling to the default cairo coordinate system) while if
 483  * @start is greather than @end, the arc will be rendered in couterclockwise
 484  * direction.
 485  *
 486  * By explicitely setting the whole arc data, the start point could be
 487  * different from the current point. In this case, if @path has no
 488  * current point before the call a %CAIRO_PATH_MOVE_TO to the start
 489  * point of the arc will be automatically prepended to the arc.
 490  * If @path has a current point, a %CAIRO_PATH_LINE_TO to the start
 491  * point of the arc will be used instead of the moveto.
 492  **/
 493 void
 494 adg_path_arc(AdgPath *path, gdouble xc, gdouble yc, gdouble r,
 495              gdouble start, gdouble end)
 496 {
 497     AdgPair center, p[3];
 498
 499     g_return_if_fail(ADG_IS_PATH(path));
 500
 501     center.x = xc;
 502     center.y = yc;
 503
 504     cpml_vector_from_angle(&p[0], start, r);
 505     cpml_vector_from_angle(&p[1], (end-start) / 2, r);
 506     cpml_vector_from_angle(&p[2], end, r);
 507
 508     cpml_pair_add(&p[0], &center);
 509     cpml_pair_add(&p[1], &center);
 510     cpml_pair_add(&p[2], &center);
 511
 512     if (!path->priv->cp_is_valid)
 513         adg_path_append(path, CAIRO_PATH_MOVE_TO, &p[0]);
 514     else if (p[0].x != path->priv->cp.x || p[0].y != path->priv->cp.y)
 515         adg_path_append(path, CAIRO_PATH_LINE_TO, &p[0]);
 516
 517     adg_path_append(path, CAIRO_PATH_ARC_TO, &p[1], &p[2]);
 518 }
 519
 520
 521 /**
 522  * adg_path_dump:
 523  * @path: an #AdgPath
 524  *
 525  * Dumps the data content of @path to stdout in a human readable format.
 526  **/
 527 void
 528 adg_path_dump(AdgPath *path)
 529 {
 530     CpmlSegment segment;
 531     cairo_path_t *cairo_path;
 532
 533     g_return_if_fail(ADG_IS_PATH(path));
 534
 535     cairo_path = get_cairo_path(path);
 536
 537     g_return_if_fail(cairo_path != NULL);
 538
 539     if (!cpml_segment_from_cairo(&segment, cairo_path)) {
 540         g_print("Invalid path data to dump!\n");
 541     } else {
 542         do {
 543             cpml_segment_dump(&segment);
 544         } while (cpml_segment_next(&segment));
 545     }
 546 }
 547
 548
 549 static void
 550 changed(AdgModel *model)
 551 {
 552     adg_path_clear((AdgPath *) model);
 553
 554     PARENT_CLASS->changed(model);
 555 }
 556
 557 static void
 558 clear_cairo_path(AdgPath *path)
 559 {
 560     cairo_path_t *cairo_path = &path->priv->cairo_path;
 561
 562     if (cairo_path->data == NULL)
 563         return;
 564
 565     g_free(cairo_path->data);
 566
 567     cairo_path->status = CAIRO_STATUS_INVALID_PATH_DATA;
 568     cairo_path->data = NULL;
 569     cairo_path->num_data = 0;
 570 }
 571
 572 static cairo_path_t *
 573 get_cairo_path(AdgPath *path)
 574 {
 575     cairo_path_t *cairo_path;
 576     const GArray *src;
 577     GArray *dst;
 578     const cairo_path_data_t *p_src;
 579     int i;
 580
 581     /* Check for cached result */
 582     cairo_path = &path->priv->cairo_path;
 583     if (cairo_path->data != NULL)
 584         return cairo_path;
 585
 586     src = path->priv->path;
 587     dst = g_array_sized_new(FALSE, FALSE, sizeof(cairo_path_data_t), src->len);
 588
 589     /* Cycle the path and convert arcs to Bézier curves */
 590     for (i = 0; i < src->len; i += p_src->header.length) {
 591         p_src = (const cairo_path_data_t *) src->data + i;
 592
 593         if (p_src->header.type == CAIRO_PATH_ARC_TO)
 594             dst = arc_to_curves(dst, p_src);
 595         else
 596             dst = g_array_append_vals(dst, p_src, p_src->header.length);
 597     }
 598
 599     cairo_path->status = CAIRO_STATUS_SUCCESS;
 600     cairo_path->num_data = dst->len;
 601     cairo_path->data = (cairo_path_data_t *) g_array_free(dst, FALSE);
 602
 603     return cairo_path;
 604 }
 605
 606 static GArray *
 607 arc_to_curves(GArray *array, const cairo_path_data_t *src)
 608 {
 609     CpmlPrimitive arc;
 610     double start, end;
 611
 612     /* Build the arc primitive: the arc origin is supposed to be the previous
 613      * point (src-1): this means a primitive must exist before the arc */
 614     arc.segment = NULL;
 615     arc.org = (cairo_path_data_t *) (src-1);
 616     arc.data = (cairo_path_data_t *) src;
 617
 618     if (cpml_arc_info(&arc, NULL, NULL, &start, &end)) {
 619         CpmlSegment segment;
 620         int n_curves;
 621         cairo_path_data_t *curves;
 622
 623         n_curves = ceil(fabs(end-start) / M_PI_2);
 624         curves = g_new(cairo_path_data_t, n_curves * 4);
 625         segment.data = curves;
 626         cpml_arc_to_curves(&arc, &segment, n_curves);
 627
 628         array = g_array_append_vals(array, curves, n_curves * 4);
 629
 630         g_free(curves);
 631     }
 632
 633     return array;
 634 }
 635
 636 static void
 637 append_valist(AdgPath *path, cairo_path_data_type_t type,
 638               int length, va_list var_args)
 639 {
 640     AdgPathPrivate *priv;
 641     cairo_path_data_t item;
 642
 643     priv = path->priv;
 644
 645     /* Append the header item */
 646     item.header.type = type;
 647     item.header.length = length;
 648     priv->path = g_array_append_val(priv->path, item);
 649     priv->cp_is_valid = FALSE;
 650
 651     /* Append the data items (that is, the AdgPair points) */
 652     while (--length) {
 653         cpml_pair_to_cairo(va_arg(var_args, AdgPair *), &item);
 654         priv->path = g_array_append_val(priv->path, item);
 655         priv->cp_is_valid = TRUE;
 656     }
 657
 658     /* Save the last point as the current point */
 659     if (priv->cp_is_valid)
 660         cpml_pair_from_cairo(&priv->cp, &item);
 661
 662     /* Invalidate cairo_path: should be recomputed */
 663     clear_cairo_path(path);
 664 }