CpmlArc

cpml_arc_info ()

cairo_bool_t        cpml_arc_info                       (const CpmlPrimitive *arc,
                                                         CpmlPair *center,
                                                         double *r,
                                                         double *start,
                                                         double *end);

Given an arc, this function calculates and returns its basic data. Any pointer can be NULL, in which case the requested info is not returned. This function can fail (when the three points lay on a straight line, for example) in which case 0 is returned and no data can be considered valid.

The radius r can be 0 when the three points are coincidents: a circle with radius 0 is considered a valid path.

When the start and end angle are returned, together with their values these angles implicitely gives another important information: the arc direction.

If start < end the arc must be rendered with increasing angle value (clockwise direction using the ordinary cairo coordinate system) while if start > end the arc must be rendered in reverse order (that is counterclockwise in the cairo world). This is the reason the angle values are returned in the range { -M_PI < value < 3*M_PI } inclusive instead of the usual { -M_PI < value < M_PI } range.

cpml_arc_to_cairo ()

void                cpml_arc_to_cairo                   (const CpmlPrimitive *arc,
                                                         cairo_t *cr);

Renders arc to the cr cairo context. As cairo does not support arcs natively, it is approximated using one or more Bézier curves.

The number of curves used is dependent from the angle of the arc. Anyway, this function uses internally the hardcoded M_PI_2 value as threshold value. This means the maximum arc approximated by a single curve will be a quarter of a circle and, consequently, a whole circle will be approximated by 4 Bézier curves.

cpml_arc_to_curves ()

void                cpml_arc_to_curves                  (const CpmlPrimitive *arc,
                                                         CpmlSegment *segment,
                                                         size_t n_curves);

Converts arc to a serie of n_curves Bézier curves and puts them inside segment. Obviously, segment must have enough space to contain at least n_curves curves.

This function works in a similar way as cpml_arc_to_cairo() but has two important differences: it does not need a cairo context and the number of curves to be generated is explicitely defined. The latter difference allows a more specific error control from the application: in the file src/cairo-arc.c, found in the cairo tarball (at least in cairo-1.9.1), there is a table showing the magnitude of error of this curve approximation algorithm.