1 /* CPML - Cairo Path Manipulation Library
2 * Copyright (C) 2008,2009,2010,2011,2012 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.
25 * @short_description: Manipulation of circular arcs
27 * The following functions manipulate %CPML_ARC #CpmlPrimitive.
28 * No validation is made on the input so use the following methods
29 * only when you are sure the <varname>primitive</varname> argument
30 * is effectively an arc-to.
32 * The arc primitive is defined by 3 points: the first one is the usual
33 * implicit point got from the previous primitive, the second point is
34 * an arbitrary intermediate point laying on the arc and the third point
35 * is the end of the arc. These points identify univocally an arc:
36 * furthermore, the intermediate point also gives the side of
39 * As a special case, when the first point is coincident with the end
40 * point the primitive is considered a circle with diameter defined by
41 * the segment between the first and the intermediate point.
45 * An arc is not a native cairo primitive and should be treated specially.
49 * Using these CPML APIs you are free to use %CPML_ARC whenever
50 * you want but, if you are directly accessing the struct fields, you
51 * are responsible of converting arcs to curves before passing them
52 * to cairo. In other words, do not directly feed #CpmlPath struct to
53 * cairo (throught cairo_append_path() for example) or at least do not
54 * expect it will work.
56 * The conversion is provided by two APIs: cpml_arc_to_cairo() and
57 * cpml_arc_to_curves(). The former directly renders to a cairo context
58 * and is internally used by all the ..._to_cairo() functions when an
59 * arc is met. The latter provided a more powerful (and more complex)
60 * approach as it allows to specify the number of curves to use and do
61 * not need a cairo context.
66 * <listitem>the get_closest_pos() method must be implemented;</listitem>
67 * <listitem>the put_intersections() method must be implemented;</listitem>
75 #include "cpml-internal.h"
76 #include "cpml-extents.h"
77 #include "cpml-segment.h"
78 #include "cpml-primitive.h"
79 #include "cpml-primitive-private.h"
81 #include "cpml-curve.h"
85 /* Hardcoded max angle of the arc to be approximated by a Bézier curve:
86 * this influence the arc quality (the default value is got from cairo) */
87 #define ARC_MAX_ANGLE M_PI_2
89 /* Macro to save typing and make put_extents() code cleaner */
90 #define ANGLE_INCLUDED(d) \
91 ((start < (d) && end > (d)) || (start > (d) && end < (d)))
94 static double get_length (const CpmlPrimitive
*arc
);
95 static void put_extents (const CpmlPrimitive
*arc
,
96 CpmlExtents
*extents
);
97 static void put_pair_at (const CpmlPrimitive
*arc
,
100 static void put_vector_at (const CpmlPrimitive
*arc
,
103 static void offset (CpmlPrimitive
*arc
,
105 static int get_center (const CpmlPair
*p
,
107 static void get_angles (const CpmlPair
*p
,
108 const CpmlPair
*center
,
111 static void arc_to_curve (CpmlPrimitive
*curve
,
112 const CpmlPair
*center
,
118 const _CpmlPrimitiveClass
*
119 _cpml_arc_get_class(void)
121 static _CpmlPrimitiveClass
*p_class
= NULL
;
123 if (p_class
== NULL
) {
124 static _CpmlPrimitiveClass class_data
= {
135 p_class
= &class_data
;
144 * @arc: (in): the #CpmlPrimitive arc data
145 * @center: (out) (allow-none): where to store the center coordinates
146 * @r: (out) (allow-none): where to store the radius
147 * @start: (out) (allow-none): where to store the starting angle
148 * @end: (out) (allow-none): where to store the ending angle
150 * Given an @arc, this function calculates and returns its basic data.
151 * Any pointer can be %NULL, in which case the requested info is not
152 * returned. This function can fail (when the three points lay on a
153 * straight line, for example) in which case 0 is returned and no
154 * data can be considered valid.
156 * The radius @r can be 0 when the three points are coincidents: a
157 * circle with radius 0 is considered a valid path.
159 * When the start and end angle are returned, together with their
160 * values these angles implicitely gives another important information:
163 * If @start < @end the arc must be rendered with increasing angle
164 * value (clockwise direction using the ordinary cairo coordinate
165 * system) while if @start > @end the arc must be rendered in reverse
166 * order (that is counterclockwise in the cairo world). This is the
167 * reason the angle values are returned in the range
168 * { -M_PI < value < 3*M_PI } inclusive instead of the usual
169 * { -M_PI < value < M_PI } range.
171 * Returns: (type boolean): %1 if the function worked succesfully,
177 cpml_arc_info(const CpmlPrimitive
*arc
, CpmlPair
*center
,
178 double *r
, double *start
, double *end
)
180 CpmlPair p
[3], l_center
;
182 cpml_pair_from_cairo(&p
[0], arc
->org
);
183 cpml_pair_from_cairo(&p
[1], &arc
->data
[1]);
184 cpml_pair_from_cairo(&p
[2], &arc
->data
[2]);
186 if (! get_center(p
, &l_center
))
193 *r
= cpml_pair_distance(&p
[0], &l_center
);
195 if (start
!= NULL
|| end
!= NULL
) {
196 double l_start
, l_end
;
198 get_angles(p
, &l_center
, &l_start
, &l_end
);
211 * @arc: (in): the #CpmlPrimitive arc data
212 * @cr: (inout): the destination cairo context
214 * Renders @arc to the @cr cairo context. As cairo does not support
215 * arcs natively, it is approximated using one or more Bézier curves.
217 * The number of curves used is dependent from the angle of the arc.
218 * Anyway, this function uses internally the hardcoded %M_PI_2 value
219 * as threshold value. This means the maximum arc approximated by a
220 * single curve will be a quarter of a circle and, consequently, a
221 * whole circle will be approximated by 4 Bézier curves.
226 cpml_arc_to_cairo(const CpmlPrimitive
*arc
, cairo_t
*cr
)
229 double r
, start
, end
;
233 cairo_path_data_t data
[4];
235 if (!cpml_arc_info(arc
, ¢er
, &r
, &start
, &end
))
238 n_curves
= ceil(fabs(end
-start
) / ARC_MAX_ANGLE
);
239 step
= (end
-start
) / (double) n_curves
;
242 for (angle
= start
; n_curves
--; angle
+= step
) {
243 arc_to_curve(&curve
, ¢er
, r
, angle
, angle
+step
);
245 curve
.data
[1].point
.x
, curve
.data
[1].point
.y
,
246 curve
.data
[2].point
.x
, curve
.data
[2].point
.y
,
247 curve
.data
[3].point
.x
, curve
.data
[3].point
.y
);
252 * cpml_arc_to_curves:
253 * @arc: (in): the #CpmlPrimitive arc data
254 * @segment: (out): the destination #CpmlSegment
255 * @n_curves: (in): number of Bézier to use
257 * Converts @arc to a serie of @n_curves Bézier curves and puts them
258 * inside @segment. Obviously, @segment must have enough space to
259 * contain at least @n_curves curves.
261 * This function works in a similar way as cpml_arc_to_cairo() but
262 * has two important differences: it does not need a cairo context
263 * and the number of curves to be generated is explicitely defined.
264 * The latter difference allows a more specific error control from
265 * the application: in the file src/cairo-arc.c, found in the cairo
266 * tarball (at least in cairo-1.9.1), there is a table showing the
267 * magnitude of error of this curve approximation algorithm.
272 cpml_arc_to_curves(const CpmlPrimitive
*arc
, CpmlSegment
*segment
,
276 double r
, start
, end
;
280 if (!cpml_arc_info(arc
, ¢er
, &r
, &start
, &end
))
283 step
= (end
-start
) / (double) n_curves
;
284 segment
->num_data
= n_curves
*4;
285 curve
.segment
= segment
;
286 curve
.data
= segment
->data
;
288 for (angle
= start
; n_curves
--; angle
+= step
) {
289 arc_to_curve(&curve
, ¢er
, r
, angle
, angle
+step
);
296 get_length(const CpmlPrimitive
*arc
)
298 double r
, start
, end
, delta
;
300 if (!cpml_arc_info(arc
, NULL
, &r
, &start
, &end
) || start
== end
)
311 put_extents(const CpmlPrimitive
*arc
, CpmlExtents
*extents
)
313 double r
, start
, end
;
314 CpmlPair center
, pair
;
316 extents
->is_defined
= 0;
318 if (!cpml_arc_info(arc
, ¢er
, &r
, &start
, &end
))
321 /* Add the right quadrant point if needed */
322 if (ANGLE_INCLUDED(0) || ANGLE_INCLUDED(M_PI
* 2)) {
323 pair
.x
= center
.x
+ r
;
325 cpml_extents_pair_add(extents
, &pair
);
328 /* Add the bottom quadrant point if needed */
329 if (ANGLE_INCLUDED(M_PI_2
) || ANGLE_INCLUDED(M_PI_2
* 5)) {
331 pair
.y
= center
.y
+ r
;
332 cpml_extents_pair_add(extents
, &pair
);
335 /* Add the left quadrant point if needed */
336 if (ANGLE_INCLUDED(M_PI
)) {
337 pair
.x
= center
.x
- r
;
339 cpml_extents_pair_add(extents
, &pair
);
342 /* Add the top quadrant point if needed */
343 if (ANGLE_INCLUDED(M_PI_2
* 3) || ANGLE_INCLUDED(-M_PI_2
)) {
345 pair
.y
= center
.y
- r
;
346 cpml_extents_pair_add(extents
, &pair
);
349 /* Add the start point */
350 cpml_primitive_put_point(arc
, 0, &pair
);
351 cpml_extents_pair_add(extents
, &pair
);
353 /* Add the end point */
354 cpml_primitive_put_point(arc
, -1, &pair
);
355 cpml_extents_pair_add(extents
, &pair
);
359 put_pair_at(const CpmlPrimitive
*arc
, double pos
, CpmlPair
*pair
)
362 cpml_pair_from_cairo(pair
, arc
->org
);
363 } else if (pos
== 1.) {
364 cpml_pair_from_cairo(pair
, &arc
->data
[2]);
367 double r
, start
, end
, angle
;
369 if (!cpml_arc_info(arc
, ¢er
, &r
, &start
, &end
))
372 angle
= (end
-start
)*pos
+ start
;
373 cpml_vector_from_angle(pair
, angle
);
374 cpml_vector_set_length(pair
, r
);
382 put_vector_at(const CpmlPrimitive
*arc
, double pos
, CpmlVector
*vector
)
384 double start
, end
, angle
;
386 if (!cpml_arc_info(arc
, NULL
, NULL
, &start
, &end
))
389 angle
= (end
-start
)*pos
+ start
;
390 cpml_vector_from_angle(vector
, angle
);
391 cpml_vector_normal(vector
);
394 vector
->x
= -vector
->x
;
395 vector
->y
= -vector
->y
;
400 offset(CpmlPrimitive
*arc
, double offset
)
402 CpmlPair p
[3], center
;
405 cpml_pair_from_cairo(&p
[0], arc
->org
);
406 cpml_pair_from_cairo(&p
[1], &arc
->data
[1]);
407 cpml_pair_from_cairo(&p
[2], &arc
->data
[2]);
409 if (!get_center(p
, ¢er
))
412 r
= cpml_pair_distance(&p
[0], ¢er
) + offset
;
414 /* Offset the three points by calculating their vector from the center,
415 * setting the new radius as length and readding the center */
423 cpml_vector_set_length(&p
[0], r
);
424 cpml_vector_set_length(&p
[1], r
);
425 cpml_vector_set_length(&p
[2], r
);
434 cpml_pair_to_cairo(&p
[0], arc
->org
);
435 cpml_pair_to_cairo(&p
[1], &arc
->data
[1]);
436 cpml_pair_to_cairo(&p
[2], &arc
->data
[2]);
440 get_center(const CpmlPair
*p
, CpmlPair
*dest
)
445 /* When p[0] == p[2], p[0]..p[1] is considered the diameter of a circle */
446 if (p
[0].x
== p
[2].x
&& p
[0].y
== p
[2].y
) {
447 dest
->x
= (p
[0].x
+ p
[1].x
) / 2;
448 dest
->y
= (p
[0].y
+ p
[1].y
) / 2;
452 /* Translate the 3 points of -p0, to simplify the formula */
453 b
.x
= p
[1].x
- p
[0].x
;
454 b
.y
= p
[1].y
- p
[0].y
;
455 c
.x
= p
[2].x
- p
[0].x
;
456 c
.y
= p
[2].y
- p
[0].y
;
458 /* Check for division by 0, that is the case where the 3 given points
459 * are laying on a straight line and there is no fitting circle */
460 d
= (b
.x
*c
.y
- b
.y
*c
.x
) * 2;
464 b2
= b
.x
*b
.x
+ b
.y
*b
.y
;
465 c2
= c
.x
*c
.x
+ c
.y
*c
.y
;
467 dest
->x
= (c
.y
*b2
- b
.y
*c2
) / d
+ p
[0].x
;
468 dest
->y
= (b
.x
*c2
- c
.x
*b2
) / d
+ p
[0].y
;
474 get_angles(const CpmlPair
*p
, const CpmlPair
*center
,
475 double *start
, double *end
)
480 /* Calculate the starting angle */
481 vector
.x
= p
[0].x
- center
->x
;
482 vector
.y
= p
[0].y
- center
->y
;
483 *start
= cpml_vector_angle(&vector
);
485 if (p
[0].x
== p
[2].x
&& p
[0].y
== p
[2].y
) {
486 /* When p[0] and p[2] are cohincidents, p[0]..p[1] is the diameter
487 * of a circle: return by convention start=start end=start+2PI */
488 *end
= *start
+ M_PI
*2;
490 /* Calculate the mid and end angle: cpml_vector_angle()
491 * returns an angle between -M_PI and M_PI */
492 vector
.x
= p
[1].x
- center
->x
;
493 vector
.y
= p
[1].y
- center
->y
;
494 mid
= cpml_vector_angle(&vector
);
495 vector
.x
= p
[2].x
- center
->x
;
496 vector
.y
= p
[2].y
- center
->y
;
497 *end
= cpml_vector_angle(&vector
);
500 /* If the middle angle is outside the start..end range,
501 * the arc should be reversed (that is, start must
502 * be greather than end) */
503 if (mid
< *start
|| mid
> *end
)
506 /* Here the arc is reversed: if the middle angle is
507 * outside the end..start range, the arc should be
508 * re-reversed to get a straight arc (that is, end
509 * must be greather than start) */
510 if (mid
< *end
|| mid
> *start
)
517 arc_to_curve(CpmlPrimitive
*curve
, const CpmlPair
*center
,
518 double r
, double start
, double end
)
520 double r_sin1
, r_cos1
;
521 double r_sin2
, r_cos2
;
524 r_sin1
= r
*sin(start
);
525 r_cos1
= r
*cos(start
);
529 h
= 4./3. * tan((end
-start
) / 4.);
531 curve
->data
[0].header
.type
= CPML_CURVE
;
532 curve
->data
[0].header
.length
= 4;
533 curve
->data
[1].point
.x
= center
->x
+ r_cos1
- h
*r_sin1
;
534 curve
->data
[1].point
.y
= center
->y
+ r_sin1
+ h
*r_cos1
;
535 curve
->data
[2].point
.x
= center
->x
+ r_cos2
+ h
*r_sin2
;
536 curve
->data
[2].point
.y
= center
->y
+ r_sin2
- h
*r_cos2
;
537 curve
->data
[3].point
.x
= center
->x
+ r_cos2
;
538 curve
->data
[3].point
.y
= center
->y
+ r_sin2
;