VectorPath Class

The path is the one that is drawn: its curves are their chords, within 1/16 of a pixel of the curve, and an open contour is closed by a straight segment. A point on the outline itself may be reported either way.

A segment is what a method of VectorPathBuilder adds: the path can be written in another format, or built again, from its segments. Every contour starts with a PathSegmentKind.MoveTo.

An arc is given as the arc of SVG paths that VectorPathBuilder.ArcTo takes, in pieces of at most a quarter turn, and an ellipse as two arcs of half a turn in a closed contour: the radii and the rotation are computed from the ellipse the path stores, and are those that were given to the builder to a few units of the last place only (exactly for an ellipse that is not turned). An arc of an ellipse that a transformation flattened to a segment is a PathSegmentKind.LineTo.

The rectangle is VectorPath.GetTightBounds spread by how far the stroke can reach from the path: half the width of the pen, its miters up to Pen.MiterLimit (with LineJoin.Miter), and the corners of square caps. It contains the stroke without computing it, and is larger than the stroke where the path has no sharp corner at its extremes; VectorPath.Widen then VectorPath.GetTightBounds gives the exact one. A pen with markers is widened: the result is then exact, and computing it allocates.

The stroke of PenAlignment.Inside stays within what the path fills; the one of PenAlignment.Outside reaches a whole width beyond the path. The units are those of the path: a pen that does not scale with the transformation of the canvas (Pen.ScalesWithTransform), and a hairline (a width of 0, one pixel of the canvas), reach that far only when the canvas is not scaled.

The path is measured as it is drawn: by the chords of its curves, within 1/16 of a pixel of the curve. A closed contour includes its closing segment; the gap between two contours is not counted. Each call walks the whole path: VectorPathMeasure walks it once for many questions.

The rectangle is computed from the curves, not from their chords: it contains everything a fill of the path paints. It does not account for the width of a stroke: see VectorPath.Widen. Empty for an empty path.

A positive distance gives the outline of what the path fills together with what a pen twice as wide as the distance strokes along its boundary: every side moves outward by the distance, and a hole gets smaller. A negative distance gives what the path fills less that stroke: every side moves inward, a hole gets larger, and a part of the shape that is narrower than twice the distance disappears. join is the shape of the corners that the sides move away from: the corners of a shape that grows, the corners of a hole, and the notches of a shape that shrinks; with LineJoin.Round, the result is what is within the distance of the shape. A curve of the path stays round whatever the join.

What moves is the boundary of the area, not each contour: contours that overlap are moved as the one shape they fill, and an open contour is closed by a straight segment, as when it is filled. A path that fills nothing (a line) has no outline to move: VectorPath.Widen gives the outline of its stroke.

The result is made as VectorPath.Combine makes it: closed contours of straight segments that do not cross, on a grid of 1/1024 of a pixel, for the size the path has. Transform a path before moving its outline, not after. Pass a cancellationToken when the path comes from untrusted input.

The contours come in the opposite order, and each one is followed the other way: an open contour starts where it ended, and a closed contour keeps its first point. The result paints the same pixels when it is filled or stroked; what follows a path in its direction changes side: the dashes of a pen, the points at a distance, a text on the path, and what FillRule.NonZero counts when the path is combined with another one.

A corner is a vertex between two straight segments of a contour: the vertices of an open contour between its ends, and every vertex of a closed contour, the one it starts at included. It becomes the arc of the circle of radius radius that touches both segments. Where a segment is too short for the circle to touch it before its middle, the circle is the smaller one that touches both segments at half the length of the shorter one: two corners never meet on a segment, and a rectangle gets the corners of VectorPathBuilder.AddRoundedRectangle.

The other vertices are kept: those where a curve or an arc starts or ends, and those where a contour goes back on itself. The result has arcs where the path had corners: it stays smooth when it is enlarged.

Filling the result paints what filling this path paints, with either fill rule: a path that crosses itself, or whose contours overlap, becomes the boundary of its area. This turns the pieces VectorPath.Widen gives into the outline of a stroke, which can be stroked in turn.

The result is made as VectorPath.Combine makes it, with the same precision and the same cost.

The stroke is the one VectorPath.Widen gives, caps, joins, miter limit, dashes, markers and Pen.Alignment included, and the answer is the one of VectorPath.Contains on it, without creating it: only the parts of the path that are within the reach of the pen from the point are stroked, and their pieces are tested against the point as they are computed. A point on the outline of the stroke may be reported either way; with an Pen.Alignment that is not PenAlignment.Center, the side of the path is decided without the grid of 1/1024 of a pixel that VectorPath.Widen moves the outline to.

The point is a point of the path, not of a canvas: as with VectorPath.Widen, the transformation of a canvas and Pen.ScalesWithTransform do not apply, and a hairline (a width of 0) is one unit wide. Each call flattens the whole path and measures the distance of each of its chords to the point, and the dashes are cut along the whole path; a point outside VectorPath.GetBounds is rejected without walking it.

The text has the segments of VectorPath.EnumerateSegments, with absolute coordinates, and numbers written so that reading them gives the same values, whatever the culture. Lines and Bézier curves are read back exactly; an arc is read back as the same arc to a few units of the last place.

The result is exact: curves are transformed as curves, and an ellipse stays an ellipse, whatever the transformation. Flattening happens when the result is drawn, so a path that is enlarged stays smooth.

The distances are those of VectorPath.GetLength and VectorPath.TryGetPointAtDistance: the contours follow each other, without the gap between them. A distance before the start of the path is its start, a distance beyond its end is its end.

The result is made of the chords the path is drawn with, which stay within 1/16 of a pixel of its curves at the size the path has: transform a path before taking a part of it, not after. The vertices of these chords are vertices of the result: a pen joins them as it joins any corner, where the stroke of the path itself is always round (the two only differ on curves a few pixels wide; LineJoin.Round makes them the same). A contour that is cut becomes an open contour; a closed contour that is kept entirely stays closed. A contour without length is not kept.

The path is the one that is drawn: its curves are their chords, within 1/16 of a pixel of the curve, a closed contour includes its closing segment, and the gap between two contours is no part of it. The distance along the path is the one VectorPath.TryGetPointAtDistance and VectorPath.Trim take. When several points are as near, the first one along the path is given. Each call walks the whole path: VectorPathMeasure walks it once for many positions.

The distance is measured as VectorPath.GetLength measures the path: the contours follow each other, without the gap between them. A distance before the start gives the first point, a distance beyond the end the last one. At a corner, the direction is the one of the segment that starts there. Each call walks the path from its start: VectorPathMeasure walks it once for many distances.

The result is the stroke as the library draws it: one closed convex contour for each segment, each join and each cap. The contours overlap and all turn the same way: fill them with FillRule.NonZero. It is not the outline of the stroke as a single contour, so stroking the result outlines every piece: VectorPath.Simplify makes that outline of it.

Curves are widened along their chords, which stay within 1/16 of a pixel of the curve at the size the path has: transform a path before widening it, not after. The brush of the pen is not used.

A dashed pen gives the contours of every dash: the size of the result grows with the length of the path divided by the length of the pattern, and nothing limits it.

The markers of the pen are contours of the result, like the pieces of the stroke. With an Pen.Alignment that is not PenAlignment.Center, the result is the outline of the side of the stroke that is kept (what VectorPath.Combine gives of the stroke of a pen twice as wide and of this path): closed contours of straight segments that do not overlap.