Extended Construction APIs


Extended Construction APIs -- Extended Construction API


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);


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.


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 offsetspecifies the phase of the pattern. That is, how many pixels into the dash-list the pattern should actually begin.
int n_dashnumber of elements in dash.
double *dashthe 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 {
} ArtPathStrokeJoinType;

enum ArtPathStrokeCapType

typedef enum {
} 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.