The libart library
<<< Previous Page | Home | Up | Next Page >>>

# Extended Construction APIs

## Name

Extended Construction APIs -- Extended Construction API

## Synopsis

    struct      ArtVpathDash;
    ArtVpath*   art_vpath_dash                  (const ArtVpath *vpath,
                                                 const ArtVpathDash *dash);
    enum        ArtPathStrokeJoinType;
    enum        ArtPathStrokeCapType;
    ArtSVP*     art_svp_vpath_stroke            (ArtVpath *vpath,
                                                 ArtPathStrokeJoinType join,
                                                 ArtPathStrokeCapType cap,
                                                 double line_width,
                                                 double miter_limit,
                                                 double flatness);
    ArtVpath*   art_vpath_new_circle            (double x,
                                                 double y,
                                                 double r);

## Description

The simple construction APIs we have described just before allow you to build your own simple vector paths but it is often useful to be able to create circles, ellipses, straight lines with a non-zero width and such... To do so, we have the folowing functions available. Sample code for these API functions (namely, `art_svp_vpath_stroke` and `art_vpath_dash`) can be found there in the function `make_path`.

## Details

### struct ArtVpathDash

    struct ArtVpathDash {
      double offset;
      int n_dash;
      double *dash;
    };

This structure describes the dashing style to be applied with `art_vpath_dash` to a vpath.

Figure 1. Dashes

The folowing code examplifies how to use this structure: it creates the `dash_style` corresponding to the example represented in the figure above: the first dash (the black one) has a length of `dash_style.dash[0] - dash_style.offset`. The second dash has a length of `dash_style.dash[1]` and the third dash has a length of `dash_style.dash[0]`...

    static ArtSVP *
      ArtVpathDash dash_style;

      dash_style.offset = 5;
      dash_style.n_dash = 3;
      dash_style.dash = art_new (double, 3);
      dash_style.dash[0] = 10;
      dash_style.dash[1] = 20;

double `offset` | specifies the phase of the pattern. That is, how many pixels into the dash-list the pattern should actually begin.
int `n_dash` | number of elements in `dash`.
double *`dash` | the initial and alternating elements (second, fourth, and so on) of the dash_list are the even dashes, and the others are the odd dashes. Each element specifies a dash length. All of the elements must be nonzero. Specifying an odd-length list is equivalent to specifying the same list concatenated with itself to produce an even-length list

### art_vpath_dash ()

    ArtVpath*   art_vpath_dash                  (const ArtVpath *vpath,
                                                 const ArtVpathDash *dash);

Creates a new vpath that is the result of applying dash style `dash` to `vpath`.

This implementation has two known flaws:

First, it adds a spurious break at the beginning of the vpath. The only way I see to resolve this flaw is to run the state forward one dash break at the beginning, and fix up by looping back to the first dash break at the end. This is doable but of course adds some complexity.

Second, it does not suppress output points that are within epsilon of each other.

`vpath` : | Original vpath.
`dash` : | Dash style.
Returns : | Newly created vpath.

### enum ArtPathStrokeJoinType

    typedef enum {
      ART_PATH_STROKE_JOIN_MITER,
      ART_PATH_STROKE_JOIN_ROUND,
      ART_PATH_STROKE_JOIN_BEVEL
    } ArtPathStrokeJoinType;

### enum ArtPathStrokeCapType

    typedef enum {
      ART_PATH_STROKE_CAP_BUTT,
      ART_PATH_STROKE_CAP_ROUND,
      ART_PATH_STROKE_CAP_SQUARE
    } ArtPathStrokeCapType;

### art_svp_vpath_stroke ()

    ArtSVP*     art_svp_vpath_stroke            (ArtVpath *vpath,
                                                 ArtPathStrokeJoinType join,
                                                 ArtPathStrokeCapType cap,
                                                 double line_width,
                                                 double miter_limit,
                                                 double flatness);

Computes an svp representing the stroked outline of `vpath`. The width of the stroked line is `line_width`.

Lines are joined according to the `join` rule. Possible values are ART_PATH_STROKE_JOIN_MITER (for mitered joins), ART_PATH_STROKE_JOIN_ROUND (for round joins), and ART_PATH_STROKE_JOIN_BEVEL (for bevelled joins). The mitered join is converted to a bevelled join if the miter would extend to a distance of more than `miter_limit` * `line_width` from the actual join point.

If there are open subpaths, the ends of these subpaths are capped according to the `cap` rule. Possible values are ART_PATH_STROKE_CAP_BUTT (squared cap, extends exactly to end point), ART_PATH_STROKE_CAP_ROUND (rounded half-circle centered at the end point), and ART_PATH_STROKE_CAP_SQUARE (squared cap, extending half `line_width` past the end point).

The `flatness` parameter controls the accuracy of the rendering. It is most important for determining the number of points to use to approximate circular arcs for round lines and joins. In general, the resulting vector path will be within `flatness` pixels of the "ideal" path containing actual circular arcs. I reserve the right to use the `flatness` parameter to convert bevelled joins to miters for very small turn angles, as this would reduce the number of points in the resulting outline path.

The resulting path is "clean" with respect to self-intersections, i.e. the winding number is 0 or 1 at each point.

`vpath` : | ArtVPath to stroke.
`join` : | Join style.
`cap` : | Cap style.
`line_width` : | Width of stroke.
`miter_limit` : | Miter limit.
`flatness` : | Flatness.
Returns : | Resulting stroked outline in svp format.

### art_vpath_new_circle ()

    ArtVpath*   art_vpath_new_circle            (double x,
                                                 double y,
                                                 double r);

Creates a new polygon closely approximating a circle with center (`x`, `y`) and radius `r`. Currently, the number of points used in the approximation is fixed, but that will probably change.

`x` : | X coordinate of center.
`y` : | Y coordinate of center.
`r` : | radius.
Returns : | The newly created ArtVpath.

<<< Previous Page | Home | Up | Next Page >>>
Core Construction APIs | Transformation operations