src/cpml/cpml-primitive.c

   1 /* CPML - Cairo Path Manipulation Library
   2  * Copyright (C) 2008,2009,2010,2011,2012  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:cpml-primitive
  23  * @Section_Id:CpmlPrimitive
  24  * @title: CpmlPrimitive
  25  * @short_description: Basic component of segments
  26  *
  27  * A primitive is an atomic geometric element found inside #CpmlSegment.
  28  * The available primitives are the same defined by #cairo_path_data_type_t
  29  * with the additional #CPML_ARC type (check #CpmlPrimitiveType
  30  * for further information) and without #CPML_MOVE as it is not
  31  * considered a primitive and it is managed in different way: the move-to
  32  * primitives are only used to define the origin of a segment.
  33  *
  34  * Since: 1.0
  35  **/
  36
  37 /**
  38  * CpmlPrimitiveType:
  39  * @CPML_MOVE:  equivalent to %CAIRO_PATH_MOVE_TO
  40  * @CPML_LINE:  equivalent to %CAIRO_PATH_LINE_TO
  41  * @CPML_CURVE: equivalent to %CAIRO_PATH_CURVE_TO
  42  * @CPML_CLOSE: equivalent to %CAIRO_PATH_CLOSE_PATH
  43  * @CPML_ARC:   an arc representation at CPML level
  44  *
  45  * This is a type compatible with #cairo_path_data_type_t type. It is
  46  * basically the same enum but it embodies an important difference:
  47  * it can be used to specify the special #CPML_ARC primitive. Having
  48  * two different types is a good way to make clear when a function
  49  * expect or not embedded #CPML_ARC primitives.
  50  *
  51  * Arcs are used extensively in technical drawing: some operations are
  52  * trivials with arcs and a nightmare with cubic Bézier curves. Actually,
  53  * at least up to version 1.10.2, the cairo library does not support arc
  54  * primitives natively and there is no plan they will be ever supported.
  55  *
  56  * The CPML library supports arc natively, converting them to curves
  57  * when the #CpmlSegment is returned to the cairo context, for instance
  58  * when using cpml_segment_to_cairo().
  59  *
  60  * Since: 1.0
  61  **/
  62
  63 /**
  64  * CpmlPrimitive:
  65  * @segment: the source #CpmlSegment
  66  * @org: a pointer to the first point of the primitive
  67  * @data: the array of the path data, prepended by the header
  68  *
  69  * As for #CpmlSegment, also the primitive is unobtrusive. This
  70  * means CpmlPrimitive does not include any coordinates but instead
  71  * keeps pointers to the original segment (and, by transition, to
  72  * the underlying #CpmlPath struct).
  73  *
  74  * Since: 1.0
  75  **/
  76
  77
  78 #include "cpml-internal.h"
  79 #include "cpml-extents.h"
  80 #include "cpml-segment.h"
  81 #include "cpml-primitive.h"
  82 #include "cpml-primitive-private.h"
  83 #include "cpml-arc.h"
  84 #include "cpml-curve.h"
  85 #include <string.h>
  86 #include <stdio.h>
  87
  88
  89 static const _CpmlPrimitiveClass *
  90                 _cpml_class_from_type   (CpmlPrimitiveType        type);
  91 static const _CpmlPrimitiveClass *
  92                 _cpml_class_from_obj    (const CpmlPrimitive     *primitive);
  93 static cairo_path_data_t *
  94                 _cpml_get_point         (const CpmlPrimitive     *primitive,
  95                                          int     n_point);
  96 static void     _cpml_dump_point        (const cairo_path_data_t *path_data);
  97
  98
  99 /**
 100  * cpml_primitive_type_get_n_points:
 101  * @type: a primitive type
 102  *
 103  * Gets the number of points required to identify the @type primitive.
 104  *
 105  * Returns: the number of points or %0 on errors
 106  *
 107  * Since: 1.0
 108  **/
 109 size_t
 110 cpml_primitive_type_get_n_points(CpmlPrimitiveType type)
 111 {
 112     const _CpmlPrimitiveClass *class_data = _cpml_class_from_type(type);
 113
 114     if (class_data == NULL)
 115         return 0;
 116
 117     return class_data->n_points;
 118 }
 119
 120 /**
 121  * cpml_primitive_from_segment:
 122  * @primitive: (out): the destination #CpmlPrimitive struct
 123  * @segment:   (in):  the source segment
 124  *
 125  * Initializes @primitive to the first primitive of @segment.
 126  *
 127  * Since: 1.0
 128  **/
 129 void
 130 cpml_primitive_from_segment(CpmlPrimitive *primitive, CpmlSegment *segment)
 131 {
 132     primitive->segment = segment;
 133
 134     /* The first element of a CpmlSegment is always a CPML_MOVE,
 135      * as ensured by cpml_segment_from_cairo() and by the browsing APIs,
 136      * so the origin is in the second data item */
 137     primitive->org = segment->data + 1;
 138
 139     /* Also, the segment APIs ensure that @segment is prepended by
 140      * only one CPML_MOVE */
 141     primitive->data = segment->data + segment->data->header.length;
 142 }
 143
 144 /**
 145  * cpml_primitive_copy:
 146  * @primitive: (out): the destination #CpmlPrimitive
 147  * @src:       (in):  the source #CpmlPrimitive
 148  *
 149  * Copies @src in @primitive. This is a shallow copy: the internal fields
 150  * of @primitive refer to the same memory as the original @src primitive.
 151  *
 152  * Since: 1.0
 153  **/
 154 void
 155 cpml_primitive_copy(CpmlPrimitive *primitive, const CpmlPrimitive *src)
 156 {
 157     memcpy(primitive, src, sizeof(CpmlPrimitive));
 158 }
 159
 160 /**
 161  * cpml_primitive_reset:
 162  * @primitive: (inout): a #CpmlPrimitive
 163  *
 164  * Resets @primitive so it refers to the first primitive of the
 165  * source segment.
 166  *
 167  * Since: 1.0
 168  **/
 169 void
 170 cpml_primitive_reset(CpmlPrimitive *primitive)
 171 {
 172     cpml_primitive_from_segment(primitive, primitive->segment);
 173 }
 174
 175 /**
 176  * cpml_primitive_next:
 177  * @primitive: (inout): a #CpmlPrimitive
 178  *
 179  * Changes @primitive so it refers to the next primitive on the
 180  * source segment. If there are no more primitives, @primitive is
 181  * not changed and 0 is returned.
 182  *
 183  * Returns: (type boolean): %1 on success,
 184  *                          %0 if no next primitive found or errors
 185  *
 186  * Since: 1.0
 187  **/
 188 int
 189 cpml_primitive_next(CpmlPrimitive *primitive)
 190 {
 191     cairo_path_data_t *new_data;
 192     const cairo_path_data_t *end_data;
 193
 194     new_data = primitive->data + primitive->data->header.length;
 195     end_data = primitive->segment->data + primitive->segment->num_data;
 196
 197     if (new_data >= end_data)
 198         return 0;
 199
 200     primitive->org = _cpml_get_point(primitive, -1);
 201     primitive->data = new_data;
 202
 203     return 1;
 204 }
 205
 206 /**
 207  * cpml_primitive_get_n_points:
 208  * @primitive: a #CpmlPrimitive
 209  *
 210  * Gets the number of points required to identify @primitive.
 211  * It is similar to cpml_primitive_type_get_n_points() but using
 212  * a @primitive instance instead of a type.
 213  *
 214  * Returns: the number of points or %0 on errors
 215  *
 216  * <!-- Virtual: n_points -->
 217  *
 218  * Since: 1.0
 219  **/
 220 size_t
 221 cpml_primitive_get_n_points(const CpmlPrimitive *primitive)
 222 {
 223     return cpml_primitive_type_get_n_points(primitive->data->header.type);
 224 }
 225
 226 /**
 227  * cpml_primitive_get_length:
 228  * @primitive: a #CpmlPrimitive
 229  *
 230  * Abstracts the length() family functions by providing a common
 231  * way to access the underlying primitive-specific implementation.
 232  * The function returns the length of @primitive.
 233  *
 234  * Returns: the requested length or 0 on errors
 235  *
 236  * <!-- Virtual: get_length -->
 237  *
 238  * Since: 1.0
 239  **/
 240 double
 241 cpml_primitive_get_length(const CpmlPrimitive *primitive)
 242 {
 243     const _CpmlPrimitiveClass *class_data = _cpml_class_from_obj(primitive);
 244
 245     if (class_data == NULL || class_data->get_length == NULL)
 246         return 0;
 247
 248     return class_data->get_length(primitive);
 249 }
 250
 251 /**
 252  * cpml_primitive_put_extents:
 253  * @primitive: (in):  a #CpmlPrimitive
 254  * @extents:   (out): where to store the extents
 255  *
 256  * Abstracts the extents() family functions by providing a common
 257  * way to access the underlying primitive-specific implementation.
 258  *
 259  * This function stores in @extents the bounding box of @primitive.
 260  *
 261  * On errors, that is if the extents cannot be calculated for some
 262  * reason, this function does nothing.
 263  *
 264  * <!-- Virtual: put_extents -->
 265  *
 266  * Since: 1.0
 267  **/
 268 void
 269 cpml_primitive_put_extents(const CpmlPrimitive *primitive,
 270                            CpmlExtents *extents)
 271 {
 272     const _CpmlPrimitiveClass *class_data = _cpml_class_from_obj(primitive);
 273
 274     if (class_data == NULL || class_data->put_extents == NULL)
 275         return;
 276
 277     class_data->put_extents(primitive, extents);
 278 }
 279
 280 /**
 281  * cpml_primitive_set_point:
 282  * @primitive: a #CpmlPrimitive
 283  * @n_point:   the index of the point to retrieve
 284  * @pair:      the source #CpmlPair
 285  *
 286  * Sets the specified @n_point of @primitive to @pair. The @n_point
 287  * index starts from 0: if @n_point is 0, the start point (the origin)
 288  * is changed, 1 for the second point and so on. If @n_point is
 289  * negative, it is considered as a negative index from the end, so
 290  * that -1 is the end point, -2 the point before the end point and
 291  * so on.
 292  *
 293  * #CPML_CLOSE is managed in a special way: if @n_point
 294  * is -1 or 1 and @primitive is a close-path, this function cycles
 295  * the source #CpmlSegment and returns the first point. This is
 296  * needed because requesting the end point (or the second point)
 297  * of a close path is a valid operation and must returns the origin
 298  * of the segment.
 299  *
 300  * Since: 1.0
 301  **/
 302 void
 303 cpml_primitive_set_point(CpmlPrimitive *primitive,
 304                          int n_point, const CpmlPair *pair)
 305 {
 306     cairo_path_data_t *point = _cpml_get_point(primitive, n_point);
 307
 308     if (point != NULL)
 309         cpml_pair_to_cairo(pair, point);
 310 }
 311
 312 /**
 313  * cpml_primitive_put_point:
 314  * @primitive: (in):  a #CpmlPrimitive
 315  * @n_point:   (in):  the index of the point to retrieve
 316  * @pair:      (out): the destination #CpmlPair
 317  *
 318  * Gets the specified @n_point from @primitive and stores it into
 319  * @pair. The @n_point index is subject to the same rules explained
 320  * in the cpml_primitive_set_point() function.
 321  *
 322  * Since: 1.0
 323  **/
 324 void
 325 cpml_primitive_put_point(const CpmlPrimitive *primitive,
 326                          int n_point, CpmlPair *pair)
 327 {
 328     const cairo_path_data_t *point = _cpml_get_point(primitive, n_point);
 329
 330     if (point != NULL)
 331         cpml_pair_from_cairo(pair, point);
 332 }
 333
 334 /**
 335  * cpml_primitive_put_pair_at:
 336  * @primitive: (in):  a #CpmlPrimitive
 337  * @pos:       (in):  the position value
 338  * @pair:      (out): the destination #CpmlPair
 339  *
 340  * Abstracts the put_pair_at() family functions by providing a common
 341  * way to access the underlying primitive-specific implementation.
 342  *
 343  * It gets the coordinates of the point lying on @primitive
 344  * at position @pos. @pos is an homogeneous factor where 0 is the
 345  * start point, 1 the end point, 0.5 the mid point and so on.
 346  * @pos can be less than 0 or greater than %1, in which case the
 347  * coordinates of @pair are interpolated.
 348  *
 349  * On errors, that is if the coordinates cannot be calculated for
 350  * some reason, this function does nothing.
 351  *
 352  * <!-- Virtual: put_pair_at -->
 353  *
 354  * Since: 1.0
 355  **/
 356 void
 357 cpml_primitive_put_pair_at(const CpmlPrimitive *primitive,
 358                            double pos, CpmlPair *pair)
 359 {
 360     const _CpmlPrimitiveClass *class_data = _cpml_class_from_obj(primitive);
 361
 362     if (class_data == NULL || class_data->put_pair_at == NULL)
 363         return;
 364
 365     class_data->put_pair_at(primitive, pos, pair);
 366 }
 367
 368 /**
 369  * cpml_primitive_put_vector_at:
 370  * @primitive: (in):  a #CpmlPrimitive
 371  * @pos:       (in):  the position value
 372  * @vector:    (out): the destination #CpmlVector
 373  *
 374  * Abstracts the put_vector_at() family functions by providing a common
 375  * way to access the underlying primitive-specific implementation.
 376  *
 377  * It gets the steepness of the point at position @pos on @primitive.
 378  * @pos is an homogeneous factor where 0 is the start point, 1 the
 379  * end point, 0.5 the mid point and so on.
 380  * @pos can be less than 0 or greater than %1, in which case the
 381  * coordinates of @pair are interpolated.
 382  *
 383  * On errors, that is if the steepness cannot be calculated for
 384  * some reason, this function does nothing.
 385  *
 386  * <!-- Virtual: put_vector_at -->
 387  *
 388  * Since: 1.0
 389  **/
 390 void
 391 cpml_primitive_put_vector_at(const CpmlPrimitive *primitive,
 392                              double pos, CpmlVector *vector)
 393 {
 394     const _CpmlPrimitiveClass *class_data = _cpml_class_from_obj(primitive);
 395
 396     if (class_data == NULL || class_data->put_vector_at == NULL)
 397         return;
 398
 399     class_data->put_vector_at(primitive, pos, vector);
 400 }
 401
 402 /**
 403  * cpml_primitive_get_closest_pos:
 404  * @primitive: a #CpmlPrimitive
 405  * @pair:      the coordinates of the subject point
 406  *
 407  * Returns the pos value of the point on @primitive nearest to @pair.
 408  * The returned value is always clamped between %0 and %1.
 409  *
 410  * Returns: the requested pos value between %0 and %1, or %-1 on errors
 411  *
 412  * <!-- Virtual: get_closest_pos -->
 413  *
 414  * Since: 1.0
 415  **/
 416 double
 417 cpml_primitive_get_closest_pos(const CpmlPrimitive *primitive,
 418                                const CpmlPair *pair)
 419 {
 420     const _CpmlPrimitiveClass *class_data = _cpml_class_from_obj(primitive);
 421
 422     if (class_data == NULL || class_data->get_closest_pos == NULL)
 423         return -1;
 424
 425     return class_data->get_closest_pos(primitive, pair);
 426 }
 427
 428 /**
 429  * cpml_primitive_put_intersections:
 430  * @primitive:  (in):  the first #CpmlPrimitive
 431  * @primitive2: (in):  the second #CpmlPrimitive
 432  * @n_dest:     (in):  maximum number of intersections to return
 433  * @dest:       (out): the destination buffer that can contain @n_dest #CpmlPair
 434  *
 435  * Finds the intersection points between the given primitives and
 436  * returns the result in @dest. The size of @dest should be enough
 437  * to store @n_dest #CpmlPair. The maximum number of intersections
 438  * is dependent on the type of the primitive involved in the
 439  * operation. If there are at least one Bézier curve involved, up to
 440  * %4 intersections could be returned. Otherwise, if there is an arc
 441  * the intersections will be %2 at maximum. For line primitives, there
 442  * is only %1 point (or %0 if the lines are parallel).
 443  *
 444  * <note>
 445  * <para>
 446  * The convention used by the CPML library is that a primitive should
 447  * implement only the intersection algorithms with lower degree
 448  * primitives. This is required to avoid code duplication: intersection
 449  * between arc and Bézier curves must be implemented by #CPML_CURVE and
 450  * intersection between lines and arcs must be implemented by #CPML_ARC.
 451  * cpml_primitive_put_intersections() will take care of swapping the
 452  * arguments if they are not properly ordered.
 453  * </para>
 454  * </note>
 455  *
 456  * Returns: the number of intersection points found or 0 if the
 457  *          primitives do not intersect or on errors
 458  *
 459  * <!-- Virtual: put_intersections -->
 460  *
 461  * Since: 1.0
 462  **/
 463 size_t
 464 cpml_primitive_put_intersections(const CpmlPrimitive *primitive,
 465                                  const CpmlPrimitive *primitive2,
 466                                  size_t n_dest, CpmlPair *dest)
 467 {
 468     const _CpmlPrimitiveClass *class_data;
 469     size_t n_points, n_points2;
 470
 471     class_data = _cpml_class_from_obj(primitive);
 472
 473     if (class_data == NULL || class_data->put_intersections == NULL)
 474         return 0;
 475
 476     n_points = cpml_primitive_get_n_points(primitive);
 477     n_points2 = cpml_primitive_get_n_points(primitive2);
 478
 479     if (n_points == 0 || n_points2 == 0)
 480         return 0;
 481
 482     /* Primitives reordering: the first must be the more complex one */
 483     if (n_points < n_points2) {
 484         const CpmlPrimitive *old_primitive2 = primitive2;
 485         primitive2 = primitive;
 486         primitive = old_primitive2;
 487     }
 488
 489     return class_data->put_intersections(primitive, primitive2, n_dest, dest);
 490 }
 491
 492 /**
 493  * cpml_primitive_put_intersections_with_segment:
 494  * @primitive: (in):  a #CpmlPrimitive
 495  * @segment:   (in):  a #CpmlSegment
 496  * @n_dest:    (in):  maximum number of intersection pairs to return
 497  * @dest:      (out): the destination buffer of #CpmlPair
 498  *
 499  * Computes the intersections between @segment and @primitive by
 500  * sequentially scanning the primitives in @segment and looking
 501  * for their intersections with @primitive.
 502  *
 503  * If the intersections are more than @n_dest, only the first
 504  * @n_dest pairs are stored.
 505  *
 506  * Returns: the number of intersections found
 507  *
 508  * Since: 1.0
 509  **/
 510 size_t
 511 cpml_primitive_put_intersections_with_segment(const CpmlPrimitive *primitive,
 512                                               const CpmlSegment *segment,
 513                                               size_t n_dest, CpmlPair *dest)
 514 {
 515     CpmlPrimitive portion;
 516     size_t found;
 517
 518     cpml_primitive_from_segment(&portion, (CpmlSegment *) segment);
 519     found = 0;
 520
 521     while (found < n_dest) {
 522         found += cpml_primitive_put_intersections(&portion, primitive,
 523                                                   n_dest-found, dest+found);
 524         if (!cpml_primitive_next(&portion))
 525             break;
 526     }
 527
 528     return found;
 529 }
 530
 531 /**
 532  * cpml_primitive_offset:
 533  * @primitive: (inout): a #CpmlPrimitive
 534  * @offset:    (in):    distance for the computed offset primitive
 535  *
 536  * Given a primitive, computes the same (or approximated) parallel
 537  * primitive distant @offset from the original one and returns
 538  * the result by changing @primitive.
 539  *
 540  * On errors, that is if the offset primitive cannot be calculated
 541  * for some reason, this function does nothing.
 542  *
 543  * <!-- Virtual: offset -->
 544  *
 545  * Since: 1.0
 546  **/
 547 void
 548 cpml_primitive_offset(CpmlPrimitive *primitive, double offset)
 549 {
 550     const _CpmlPrimitiveClass *class_data = _cpml_class_from_obj(primitive);
 551
 552     if (class_data == NULL || class_data->offset == NULL)
 553         return;
 554
 555     class_data->offset(primitive, offset);
 556 }
 557
 558 /**
 559  * cpml_primitive_join:
 560  * @primitive:  (inout): the first #CpmlPrimitive
 561  * @primitive2: (inout): the second #CpmlPrimitive
 562  *
 563  * Joins two primitive modifying the end point of @primitive and the
 564  * start point of @primitive2 so that the resulting points will overlap.
 565  *
 566  * <important>
 567  * <title>TODO</title>
 568  * <itemizedlist>
 569  * <listitem>Actually, the join is done by extending the end vector
 570  *           of @primitive and the start vector of @primitive2 and
 571  *           interpolating the intersection: this means no primitive
 572  *           dependent code is needed. Anyway, it is likely to change
 573  *           in the future because this approach is quite naive when
 574  *           curves are involved.</listitem>
 575  * </itemizedlist>
 576  * </important>
 577  *
 578  * Returns: (type boolean): %1 on success,
 579  *                          %0 if the primitives cannot be joint
 580  *
 581  * <!-- Virtual: join -->
 582  *
 583  * Since: 1.0
 584  **/
 585 int
 586 cpml_primitive_join(CpmlPrimitive *primitive, CpmlPrimitive *primitive2)
 587 {
 588     cairo_path_data_t *end1, *start2;
 589     CpmlPrimitive line1, line2;
 590     cairo_path_data_t data1[2], data2[2];
 591     CpmlPair joint;
 592
 593     end1 = _cpml_get_point(primitive, -1);
 594     start2 = _cpml_get_point(primitive2, 0);
 595
 596     /* Check if the primitives are yet connected */
 597     if (end1->point.x == start2->point.x && end1->point.y == start2->point.y)
 598         return 1;
 599
 600     line1.org = _cpml_get_point(primitive, -2);
 601     line1.data = data1;
 602     data1[0].header.type = CPML_LINE;
 603     data1[1] = *end1;
 604
 605     line2.org = start2;
 606     line2.data = data2;
 607     data2[0].header.type = CPML_LINE;
 608     data2[1] = *_cpml_get_point(primitive2, 1);
 609
 610     if (!cpml_primitive_put_intersections(&line1, &line2, 1, &joint))
 611         return 0;
 612
 613     cpml_pair_to_cairo(&joint, end1);
 614     cpml_pair_to_cairo(&joint, start2);
 615
 616     return 1;
 617 }
 618
 619 /**
 620  * cpml_primitive_to_cairo:
 621  * @primitive: (in):    a #CpmlPrimitive
 622  * @cr:        (inout): the destination cairo context
 623  *
 624  * Renders a single @primitive to the @cr cairo context.
 625  * As a special case, if the primitive is a #CPML_CLOSE, an
 626  * equivalent line is rendered, because a close path left alone
 627  * is not renderable.
 628  *
 629  * Also a #CPML_ARC primitive is treated specially, as it is not
 630  * natively supported by cairo and has its own rendering API.
 631  *
 632  * Since: 1.0
 633  **/
 634 void
 635 cpml_primitive_to_cairo(const CpmlPrimitive *primitive, cairo_t *cr)
 636 {
 637     CpmlPrimitiveType type;
 638     cairo_path_t path;
 639     cairo_path_data_t *path_data;
 640
 641     cairo_move_to(cr, primitive->org->point.x, primitive->org->point.y);
 642
 643     type = primitive->data->header.type;
 644
 645     if (type == CPML_CLOSE) {
 646         path_data = _cpml_get_point(primitive, -1);
 647         cairo_line_to(cr, path_data->point.x, path_data->point.y);
 648     } else if (type == CPML_ARC) {
 649         cpml_arc_to_cairo(primitive, cr);
 650     } else {
 651         path.status = CAIRO_STATUS_SUCCESS;
 652         path.data = primitive->data;
 653         path.num_data = primitive->data->header.length;
 654         cairo_append_path(cr, &path);
 655     }
 656 }
 657
 658 /**
 659  * cpml_primitive_dump:
 660  * @primitive: a #CpmlPrimitive
 661  * @org_also:  whether to output also the origin coordinates
 662  *
 663  * Dumps info on the specified @primitive to stdout: useful for
 664  * debugging purposes. If @org_also is 1, a #CPML_MOVE to the
 665  * origin is prepended to the data otherwise the
 666  * <structfield>org</structfield> field is not used.
 667  *
 668  * Since: 1.0
 669  **/
 670 void
 671 cpml_primitive_dump(const CpmlPrimitive *primitive, int org_also)
 672 {
 673     const cairo_path_data_t *data;
 674     int type;
 675     const _CpmlPrimitiveClass *class_data;
 676     size_t n, n_points;
 677
 678     data = primitive->data;
 679     type = data->header.type;
 680     class_data = _cpml_class_from_type(type);
 681
 682     if (class_data == NULL) {
 683         printf("Unknown primitive type (%d)\n", type);
 684         return;
 685     }
 686
 687     /* Dump the origin, if requested */
 688     if (org_also) {
 689         printf("move to ");
 690         _cpml_dump_point(primitive->org);
 691         printf("\n");
 692     }
 693
 694     printf("%s ", class_data->name);
 695
 696     n_points = cpml_primitive_get_n_points(primitive);
 697     for (n = 1; n < n_points; ++n)
 698         _cpml_dump_point(_cpml_get_point(primitive, n));
 699
 700     printf("\n");
 701 }
 702
 703
 704 static const _CpmlPrimitiveClass *
 705 _cpml_class_from_type(CpmlPrimitiveType type)
 706 {
 707     if (type == CPML_LINE)
 708         return _cpml_line_get_class();
 709     else if (type == CPML_ARC)
 710         return _cpml_arc_get_class();
 711     else if (type == CPML_CURVE)
 712         return _cpml_curve_get_class();
 713     else if (type == CPML_CLOSE)
 714         return _cpml_close_get_class();
 715
 716     return NULL;
 717 }
 718
 719 static const _CpmlPrimitiveClass *
 720 _cpml_class_from_obj(const CpmlPrimitive *primitive)
 721 {
 722     return _cpml_class_from_type(primitive->data->header.type);
 723 }
 724
 725 /*
 726  * _cpml_get_point:
 727  * @primitive: a #CpmlPrimitive
 728  * @n_point:   the index of the point to retrieve
 729  *
 730  * Gets the specified @n_point from @primitive. The index starts
 731  * at 0: if @n_point is 0, the start point (the origin) is
 732  * returned, 1 for the second point and so on. If @n_point is
 733  * negative, it is considered as a negative index from the end,
 734  * so that -1 is the end point, -2 the point before the end point
 735  * and so on.
 736  *
 737  * #CPML_CLOSE is managed in a special way: if @n_point
 738  * is -1 or 1 and @primitive is a close-path, this function cycles
 739  * the source #CpmlSegment and returns the first point. This is
 740  * needed because requesting the end point (or the second point)
 741  * of a close path is a valid operation and must returns the start
 742  * of the segment.
 743  *
 744  * Returns: a pointer to the requested point (in cairo format)
 745  *          or %NULL if the point is outside the valid range
 746  *
 747  * Since: 1.0
 748  **/
 749 static cairo_path_data_t *
 750 _cpml_get_point(const CpmlPrimitive *primitive, int n_point)
 751 {
 752     size_t n_points;
 753
 754     /* For a start point request, simply return the origin
 755      * without further checking */
 756     if (n_point == 0)
 757         return primitive->org;
 758
 759     /* The CPML_CLOSE special case */
 760     if (primitive->data->header.type == CAIRO_PATH_CLOSE_PATH &&
 761         (n_point == 1 || n_point == -1))
 762         return &primitive->segment->data[1];
 763
 764     n_points = cpml_primitive_get_n_points(primitive);
 765     if (n_points == 0)
 766         return NULL;
 767
 768     /* If n_point is negative, consider it as a negative index from the end */
 769     if (n_point < 0)
 770         n_point = n_points + n_point;
 771
 772     /* Out of range condition */
 773     if (n_point < 0 || n_point >= n_points)
 774         return NULL;
 775
 776     return n_point == 0 ? primitive->org : &primitive->data[n_point];
 777 }
 778
 779 static void
 780 _cpml_dump_point(const cairo_path_data_t *path_data)
 781 {
 782     printf("(%g %g) ", path_data->point.x, path_data->point.y);
 783 }