1 /* CPML - Cairo Path Manipulation Library
2 * Copyright (C) 2008, 2009 Nicola Fontana <ntd at entidi.it>
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.
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.
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.
22 * SECTION:cpml-primitive
23 * @Section_Id:CpmlPrimitive
24 * @title: CpmlPrimitive
25 * @short_description: Basic component of segments
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 %CAIRO_PATH_ARC_TO type (check #CpmlPrimitiveType
30 * for further information) and without %CAIRO_PATH_MOVE_TO 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.
38 * This is another name for #cairo_path_data_type_t type. Although
39 * phisically they are the same struct, #CpmlPrimitiveType conceptually
40 * embodies an important difference: it can be used to specify the
41 * special %CAIRO_PATH_ARC_TO primitive. This is not a native cairo
42 * primitive and having two different types is a good way to make clear
43 * when a function expect or not embedded arc-to primitives.
48 * @segment: the source #CpmlSegment
49 * @org: a pointer to the first point of the primitive
50 * @data: the array of the path data, prepended by the header
52 * As for #CpmlSegment, also the primitive is unobtrusive. This
53 * means CpmlPrimitive does not include any coordinates but instead
54 * keeps pointers to the original segment (and, by transition, to
55 * the underlying #CpmlPath struct).
59 #include "cpml-primitive.h"
60 #include "cpml-line.h"
62 #include "cpml-curve.h"
63 #include "cpml-close.h"
70 static void dump_cairo_point (const cairo_path_data_t
*path_data
);
74 * cpml_primitive_copy:
75 * @primitive: the destination #CpmlPrimitive
76 * @src: the source #CpmlPrimitive
78 * Copies @src in @primitive. This is a shallow copy: the internal fields
79 * of @primitive refer to the same memory as the original @src primitive.
84 cpml_primitive_copy(CpmlPrimitive
*primitive
, const CpmlPrimitive
*src
)
86 return memcpy(primitive
, src
, sizeof(CpmlPrimitive
));
90 * cpml_primitive_from_segment:
91 * @primitive: the destination #CpmlPrimitive struct
92 * @segment: the source segment
94 * Initializes @primitive to the first primitive of @segment.
99 cpml_primitive_from_segment(CpmlPrimitive
*primitive
, CpmlSegment
*segment
)
101 primitive
->segment
= segment
;
103 /* The first element of a CpmlSegment is always a CAIRO_PATH_MOVE_TO,
104 * as ensured by cpml_segment_from_cairo() and by the browsing APIs,
105 * so the origin is in the second data item */
106 primitive
->org
= &segment
->data
[1];
108 /* Also, the segment APIs ensure that @segment is prepended by
109 * only one CAIRO_PATH_MOVE_TO */
110 primitive
->data
= segment
->data
+ segment
->data
[0].header
.length
;
116 * cpml_primitive_reset:
117 * @primitive: a #CpmlPrimitive
119 * Resets @primitive so it refers to the first primitive of the
123 cpml_primitive_reset(CpmlPrimitive
*primitive
)
125 cpml_primitive_from_segment(primitive
, primitive
->segment
);
129 * cpml_primitive_next:
130 * @primitive: a #CpmlPrimitive
133 * Changes @primitive so it refers to the next primitive on the
134 * source segment. If there are no more primitives, @primitive is
135 * not changed and 0 is returned.
137 * Returns: 1 on success, 0 if no next primitive found or errors
140 cpml_primitive_next(CpmlPrimitive
*primitive
)
142 cairo_path_data_t
*new_data
;
144 new_data
= primitive
->data
+ primitive
->data
->header
.length
;
145 if (new_data
- primitive
->segment
->data
>= primitive
->segment
->num_data
)
148 /* TODO: this is a temporary workaround to be removed as soon as
149 * the issue #21 will be resolved */
150 if (new_data
->header
.type
== CAIRO_PATH_MOVE_TO
)
153 primitive
->org
= cpml_primitive_get_point(primitive
, -1);
154 primitive
->data
= new_data
;
160 * cpml_primitive_get_npoints:
161 * @primitive: a #CpmlPrimitive
163 * Gets the number of points required to identify @primitive.
164 * It is similar to cpml_primitive_type_get_npoints() but using
165 * a @primitive instance instead of a type.
167 * Returns: the number of points or -1 on errors
170 cpml_primitive_get_npoints(const CpmlPrimitive
*primitive
)
172 return cpml_primitive_type_get_npoints(primitive
->data
->header
.type
);
176 * cpml_primitive_get_point:
177 * @primitive: a #CpmlPrimitive
178 * @npoint: the index of the point to retrieve
180 * Gets the specified @npoint from @primitive. The index starts
181 * at 0: if @npoint is 0, the start point (the origin) is
182 * returned, 1 for the second point and so on. If @npoint is
183 * negative, it is considered as a negative index from the end,
184 * so that -1 is the end point, -2 the point before the end point
187 * %CAIRO_PATH_CLOSE_PATH is managed in a special way: if @npoint
188 * is -1 or 1 and @primitive is a close-path, this function cycles
189 * the source #CpmlSegment and returns the first point. This is
190 * needed because requesting the end point (or the second point)
191 * of a close path is a valid operation and must returns the start
194 * Returns: a pointer to the requested point (in cairo format)
195 * or %NULL if the point is outside the valid range
198 cpml_primitive_get_point(const CpmlPrimitive
*primitive
, int npoint
)
202 /* For a start point request, simply return the origin
203 * without further checking */
205 return primitive
->org
;
207 /* The CAIRO_PATH_CLOSE_PATH special case */
208 if (primitive
->data
->header
.type
== CAIRO_PATH_CLOSE_PATH
&&
209 (npoint
== 1 || npoint
== -1))
210 return &primitive
->segment
->data
[1];
212 npoints
= cpml_primitive_get_npoints(primitive
);
216 /* If npoint is negative, consider it as a negative index from the end */
218 npoint
= npoints
+ npoint
;
220 /* Out of range condition */
221 if (npoint
< 0 || npoint
>= npoints
)
224 return npoint
== 0 ? primitive
->org
: &primitive
->data
[npoint
];
228 * cpml_primitive_to_cairo:
229 * @primitive: a #CpmlPrimitive
230 * @cr: the destination cairo context
232 * Renders a single @primitive to the @cr cairo context.
233 * As a special case, if the primitive is a #CAIRO_PATH_CLOSE_PATH,
234 * an equivalent line is rendered, because a close path left alone
237 * Also a #CAIRO_PATH_ARC_TO primitive is treated specially, as it
238 * is not natively supported by cairo and has its own rendering API.
241 cpml_primitive_to_cairo(const CpmlPrimitive
*primitive
, cairo_t
*cr
)
244 cairo_path_data_t
*path_data
;
246 cairo_move_to(cr
, primitive
->org
->point
.x
, primitive
->org
->point
.y
);
248 switch (primitive
->data
->header
.type
) {
250 case CAIRO_PATH_CLOSE_PATH
:
251 path_data
= cpml_primitive_get_point(primitive
, -1);
252 cairo_line_to(cr
, path_data
->point
.x
, path_data
->point
.y
);
255 case CAIRO_PATH_ARC_TO
:
256 cpml_arc_to_cairo(primitive
, cr
);
260 path
.status
= CAIRO_STATUS_SUCCESS
;
261 path
.data
= primitive
->data
;
262 path
.num_data
= primitive
->data
->header
.length
;
263 cairo_append_path(cr
, &path
);
269 * cpml_primitive_dump:
270 * @primitive: a #CpmlPrimitive
271 * @org_also: whether to output also the origin coordinates
273 * Dumps info on the specified @primitive to stdout: useful for
274 * debugging purposes. If @org_also is 1, a %CAIRO_PATH_MOVE_TO
275 * to the origin is prepended to the data otherwise the
276 * <structfield>org</structfield> field is not used.
279 cpml_primitive_dump(const CpmlPrimitive
*primitive
, cairo_bool_t org_also
)
281 const cairo_path_data_t
*data
;
282 int type
, n
, npoints
;
284 data
= primitive
->data
;
285 type
= data
->header
.type
;
286 npoints
= cpml_primitive_get_npoints(primitive
);
288 printf("Unhandled primitive type (%d)\n", type
);
292 /* Dump the origin movement, if requested */
295 dump_cairo_point(primitive
->org
);
301 case CAIRO_PATH_LINE_TO
:
305 case CAIRO_PATH_ARC_TO
:
309 case CAIRO_PATH_CURVE_TO
:
313 case CAIRO_PATH_CLOSE_PATH
:
314 printf("Path close");
318 printf("Unknown primitive (type = %d)", type
);
322 for (n
= 1; n
< npoints
; ++n
)
323 dump_cairo_point(cpml_primitive_get_point(primitive
, n
));
329 * cpml_primitive_put_intersections_with_segment:
330 * @primitive: a #CpmlPrimitive
331 * @segment: a #CpmlSegment
332 * @dest: the destination vector of #CpmlPair
333 * @max: maximum number of intersections to return
335 * Computes the intersections between @segment and @primitive by
336 * sequentially scanning the primitives in @segment and looking
337 * for intersections with @primitive.
338 * If the intersections are more than @max, only the first @max pairs
339 * are stored in @dest.
341 * Returns: the number of intersections found
344 cpml_primitive_put_intersections_with_segment(const CpmlPrimitive
*primitive
,
345 const CpmlSegment
*segment
,
346 CpmlPair
*dest
, int max
)
348 CpmlPrimitive portion
;
351 cpml_primitive_from_segment(&portion
, (CpmlSegment
*) segment
);
354 while (found
< max
) {
355 found
+= cpml_primitive_intersection(&portion
, primitive
,
356 dest
+found
, max
-found
);
357 if (!cpml_primitive_next(&portion
))
366 * cpml_primitive_type_get_npoints:
367 * @type: a primitive type
369 * Gets the number of points required to identify the @type primitive.
372 * This function is primitive dependent, that is every primitive has
373 * its own implementation.
376 * Returns: the number of points or -1 on errors
379 cpml_primitive_type_get_npoints(CpmlPrimitiveType type
)
383 case CAIRO_PATH_LINE_TO
:
384 return cpml_line_type_get_npoints();
386 case CAIRO_PATH_ARC_TO
:
387 return cpml_arc_type_get_npoints();
389 case CAIRO_PATH_CURVE_TO
:
390 return cpml_curve_type_get_npoints();
392 case CAIRO_PATH_CLOSE_PATH
:
393 return cpml_close_type_get_npoints();
403 * cpml_primitive_get_length:
404 * @primitive: a #CpmlPrimitive
406 * Abstracts the length() family functions by providing a common
407 * way to access the underlying primitive-specific implementation.
408 * The function returns the length of @primitive.
411 * This function is primitive dependent, that is every primitive has
412 * its own implementation.
415 * Returns: the requested length or 0 on errors
418 cpml_primitive_get_length(const CpmlPrimitive
*primitive
)
420 switch (primitive
->data
->header
.type
) {
422 case CAIRO_PATH_LINE_TO
:
423 case CAIRO_PATH_CLOSE_PATH
:
424 return cpml_line_get_length(primitive
);
426 case CAIRO_PATH_ARC_TO
:
427 return cpml_arc_get_length(primitive
);
429 case CAIRO_PATH_CURVE_TO
:
430 return cpml_curve_get_length(primitive
);
440 * cpml_primitive_extents:
441 * @primitive: a #CpmlPrimitive
442 * @extents: where to store the extents
444 * Abstracts the extents() family functions by providing a common
445 * way to access the underlying primitive-specific implementation.
446 * The function stores in @extents the bounding box of @primitive.
449 * This function is primitive dependent, that is every primitive has
450 * its own implementation.
454 cpml_primitive_extents(const CpmlPrimitive
*primitive
, CpmlExtents
*extents
)
456 switch (primitive
->data
->header
.type
) {
458 case CAIRO_PATH_LINE_TO
:
459 case CAIRO_PATH_CLOSE_PATH
:
460 return cpml_line_extents(primitive
, extents
);
462 case CAIRO_PATH_ARC_TO
:
463 return cpml_arc_extents(primitive
, extents
);
465 case CAIRO_PATH_CURVE_TO
:
466 return cpml_curve_extents(primitive
, extents
);
469 extents
->is_defined
= 0;
475 * cpml_primitive_pair_at:
476 * @primitive: a #CpmlPrimitive
477 * @pair: the destination #CpmlPair
478 * @pos: the position value
480 * Abstracts the pair_at() family functions by providing a common
481 * way to access the underlying primitive-specific implementation.
483 * It gets the coordinates of the point lying on @primitive
484 * at position @pos. @pos is an homogeneous factor where 0 is the
485 * start point, 1 the end point, 0.5 the mid point and so on.
486 * The relation 0 < @pos < 1 should be satisfied, although some
487 * primitives accept value outside this range.
490 * This function is primitive dependent, that is every primitive has
491 * its own implementation.
495 cpml_primitive_pair_at(const CpmlPrimitive
*primitive
,
496 CpmlPair
*pair
, double pos
)
498 switch (primitive
->data
->header
.type
) {
500 case CAIRO_PATH_LINE_TO
:
501 cpml_line_pair_at(primitive
, pair
, pos
);
504 case CAIRO_PATH_ARC_TO
:
505 cpml_arc_pair_at(primitive
, pair
, pos
);
508 case CAIRO_PATH_CURVE_TO
:
509 cpml_curve_pair_at(primitive
, pair
, pos
);
512 case CAIRO_PATH_CLOSE_PATH
:
513 cpml_close_pair_at(primitive
, pair
, pos
);
522 * cpml_primitive_vector_at:
523 * @primitive: a #CpmlPrimitive
524 * @vector: the destination #CpmlVector
525 * @pos: the position value
527 * Abstracts the vector_at() family functions by providing a common
528 * way to access the underlying primitive-specific implementation.
530 * It gets the steepness of the point at position @pos on @primitive.
531 * @pos is an homogeneous factor where 0 is the start point, 1 the
532 * end point, 0.5 the mid point and so on.
533 * The relation 0 < @pos < 1 should be satisfied, although some
534 * primitives accept value outside this range.
537 * This function is primitive dependent, that is every primitive has
538 * its own implementation.
542 cpml_primitive_vector_at(const CpmlPrimitive
*primitive
,
543 CpmlVector
*vector
, double pos
)
545 switch (primitive
->data
->header
.type
) {
547 case CAIRO_PATH_LINE_TO
:
548 cpml_line_vector_at(primitive
, vector
, pos
);
551 case CAIRO_PATH_ARC_TO
:
552 cpml_arc_vector_at(primitive
, vector
, pos
);
555 case CAIRO_PATH_CURVE_TO
:
556 cpml_curve_vector_at(primitive
, vector
, pos
);
559 case CAIRO_PATH_CLOSE_PATH
:
560 cpml_close_vector_at(primitive
, vector
, pos
);
569 * cpml_primitive_near_pos:
570 * @primitive: a #CpmlPrimitive
571 * @pair: the coordinates of the subject point
573 * Returns the pos value of the point on @primitive nearest to @pair.
574 * The returned value is always between 0 and 1 or -1 in case of errors.
577 * This function is primitive dependent, that is every primitive has
578 * its own implementation.
581 * Returns: the requested pos value between 0 and 1 or -1 on errors
584 cpml_primitive_near_pos(const CpmlPrimitive
*primitive
, const CpmlPair
*pair
)
586 switch (primitive
->data
->header
.type
) {
588 case CAIRO_PATH_LINE_TO
:
589 return cpml_line_near_pos(primitive
, pair
);
591 case CAIRO_PATH_ARC_TO
:
592 return cpml_arc_near_pos(primitive
, pair
);
594 case CAIRO_PATH_CURVE_TO
:
595 return cpml_curve_near_pos(primitive
, pair
);
597 case CAIRO_PATH_CLOSE_PATH
:
598 return cpml_close_near_pos(primitive
, pair
);
608 * cpml_primitive_join:
609 * @primitive: the first #CpmlPrimitive
610 * @primitive2: the second #CpmlPrimitive
612 * Joins two primitive modifying the end point of @primitive and the
613 * start point of @primitive2 so that the resulting points will overlap.
616 * <title>TODO</title>
618 * <listitem>Actually, the join is done by extending the end vector
619 * of @primitive and the start vector of @primitive2 and
620 * interpolating the intersection: this means no primitive
621 * dependent code is needed. Anyway, it is likely to change
622 * in the future because this approach is quite naive when
623 * curves are involved.</listitem>
627 * Returns: 1 on success, 0 if the end vector of @primitive
628 * and the start vector of @primitive2 are parallel
631 cpml_primitive_join(CpmlPrimitive
*primitive
, CpmlPrimitive
*primitive2
)
633 cairo_path_data_t
*end1
, *start2
;
634 CpmlPrimitive line1
, line2
;
635 cairo_path_data_t data1
[2], data2
[2];
638 end1
= cpml_primitive_get_point(primitive
, -1);
639 start2
= cpml_primitive_get_point(primitive2
, 0);
641 /* Check if the primitives are yet connected */
642 if (end1
->point
.x
== start2
->point
.x
&& end1
->point
.y
== start2
->point
.y
)
645 line1
.org
= cpml_primitive_get_point(primitive
, -2);
647 data1
[0].header
.type
= CAIRO_PATH_LINE_TO
;
652 data2
[0].header
.type
= CAIRO_PATH_LINE_TO
;
653 data2
[1] = *cpml_primitive_get_point(primitive2
, 1);
655 if (!cpml_line_intersection(&line1
, &line2
, &joint
, 1))
658 cpml_pair_to_cairo(&joint
, end1
);
659 cpml_pair_to_cairo(&joint
, start2
);
665 * cpml_primitive_intersection:
666 * @primitive: the first #CpmlPrimitive
667 * @primitive2: the second #CpmlPrimitive
668 * @dest: the destination #CpmlPair (or a vector of #CpmlPair)
669 * @max: maximum number of intersections to return
671 * Finds the intersection points between the given primitives and
672 * returns the result in @dest. The size of @dest should be enough
673 * to store @max #CpmlPair. The absoulte max number of intersections
674 * is dependent from the type of the primitive involved in the
675 * operation. If there are at least one Bézier curve involved, up to
676 * 4 intersections could be returned. Otherwise, if there is an arc
677 * the intersections will be 2 at maximum. For line line primitives,
678 * there is only 1 point (or obviously 0 if the lines do not intersect).
681 * This function is primitive dependent: every new primitive must
682 * expose API to get intersections with any other primitive type
683 * (excluding %CAIRO_PATH_CLOSE_PATH, as it is converted to a line
685 * <para>The convention used by CPML is that a primitive should
686 * expose only intersection APIs dealing with lower complexity
687 * primitives. This is required to avoid double functions:
688 * you will have only a cpml_curve_intersection_with_line() function,
689 * not a cpml_line_intersection_with_curve(), as the latter is
690 * easily reproduced by calling the former with @primitive2
691 * and @primitive swapped.
694 * Returns: the number of intersection points found or 0 if the
695 * primitives do not intersect
698 cpml_primitive_intersection(const CpmlPrimitive
*primitive
,
699 const CpmlPrimitive
*primitive2
,
700 CpmlPair
*dest
, int max
)
702 CpmlPrimitiveType type1
, type2
;
704 type1
= primitive
->data
->header
.type
;
705 type2
= primitive
->data
->header
.type
;
707 /* Close path primitives are treated as line-to */
708 if (type1
== CAIRO_PATH_CLOSE_PATH
)
709 type1
= CAIRO_PATH_LINE_TO
;
710 if (type2
== CAIRO_PATH_CLOSE_PATH
)
711 type2
= CAIRO_PATH_LINE_TO
;
713 /* Order the two primitives in ascending complexity, to facilitate
714 * the dispatcher logic */
715 if (cpml_primitive_type_get_npoints(type1
) > cpml_primitive_type_get_npoints(type2
)) {
716 const CpmlPrimitive
*tmp_primitive
;
717 CpmlPrimitiveType tmp_type
;
720 tmp_primitive
= primitive
;
723 primitive
= primitive2
;
726 primitive2
= tmp_primitive
;
729 /* Dispatcher: probably there's a smarter way to do this */
732 case CAIRO_PATH_LINE_TO
:
733 if (type2
== CAIRO_PATH_LINE_TO
)
734 return cpml_line_intersection(primitive2
, primitive
,
736 else if (type2
== CAIRO_PATH_ARC_TO
)
737 return cpml_arc_intersection_with_line(primitive2
, primitive
,
739 else if (type2
== CAIRO_PATH_CURVE_TO
)
740 return cpml_curve_intersection_with_line(primitive2
, primitive
,
744 case CAIRO_PATH_ARC_TO
:
745 if (type2
== CAIRO_PATH_ARC_TO
)
746 return cpml_arc_intersection(primitive2
, primitive
,
748 else if (type2
== CAIRO_PATH_CURVE_TO
)
749 return cpml_curve_intersection_with_arc(primitive2
, primitive
,
753 case CAIRO_PATH_CURVE_TO
:
754 if (type2
== CAIRO_PATH_CURVE_TO
)
755 return cpml_curve_intersection(primitive2
, primitive
,
763 /* Primitive combination not found */
768 * cpml_primitive_offset:
769 * @primitive: a #CpmlPrimitive
770 * @offset: distance for the computed offset primitive
772 * Given a primitive, computes the same (or approximated) parallel
773 * primitive distant @offset from the original one and returns
774 * the result by changing @primitive.
777 * This function is primitive dependent, that is every primitive has
778 * its own implementation.
782 cpml_primitive_offset(CpmlPrimitive
*primitive
, double offset
)
784 switch (primitive
->data
->header
.type
) {
786 case CAIRO_PATH_LINE_TO
:
787 cpml_line_offset(primitive
, offset
);
790 case CAIRO_PATH_ARC_TO
:
791 cpml_arc_offset(primitive
, offset
);
794 case CAIRO_PATH_CURVE_TO
:
795 cpml_curve_offset(primitive
, offset
);
798 case CAIRO_PATH_CLOSE_PATH
:
799 cpml_close_offset(primitive
, offset
);
808 dump_cairo_point(const cairo_path_data_t
*path_data
)
810 printf("(%g %g) ", path_data
->point
.x
, path_data
->point
.y
);