Struct PathBuilder 

pub struct PathBuilder {
    pub style: PathStyle,
    /* private fields */
}

Builds a Path from lines and curves, and tessellates it into triangles.

Create a builder with crate::PathBuilder::fill or crate::PathBuilder::stroke, add commands, and call crate::PathBuilder::build. Paint the result with crate::Window::paint_path. Coordinates are in window pixels, so use the bounds that a canvas gives you.

Examples

let mut builder = PathBuilder::fill();
builder.move_to(point(px(0.), px(0.)));
builder.line_to(point(px(10.), px(0.)));
builder.line_to(point(px(0.), px(10.)));
builder.close();
let path = builder.build().unwrap();
assert_eq!(path.vertices.len() % 3, 0);
assert_eq!(path.bounds.size.width, px(10.));
assert_eq!(path.bounds.size.height, px(10.));

See drawing custom graphics for more.

Fields

style: PathStyle

How crate::PathBuilder::build tessellates the path. crate::PathBuilder::stroke, crate::PathBuilder::fill and crate::PathBuilder::with_style set it.

Implementations

impl PathBuilder

pub fn stroke(width: Pixels) -> Self

Returns a builder that strokes the path with a line width logical pixels wide.

The stroke has butt caps and miter joins, with a miter limit of 4. Use crate::PathBuilder::fill for a filled shape.

Examples

let mut builder = PathBuilder::stroke(px(2.));
builder.move_to(point(px(0.), px(5.)));
builder.line_to(point(px(20.), px(5.)));
let path = builder.build().unwrap();
assert_eq!(path.bounds.origin, point(px(0.), px(4.)));
assert_eq!(path.bounds.size, size(px(20.), px(2.)));

pub fn fill() -> Self

Returns a builder that fills the interior of the path using the even-odd rule.

An open sub-path is closed implicitly when it is filled. For the non-zero rule, pass a style to crate::PathBuilder::with_style.

pub fn with_style(self, style: PathStyle) -> Self

Replaces the style of this builder.

Use this for options that crate::PathBuilder::stroke and crate::PathBuilder::fill don’t set, such as the non-zero FillRule.

Examples

let style = PathStyle::Fill(FillOptions::default().with_fill_rule(FillRule::NonZero));
let mut builder = PathBuilder::fill().with_style(style);
builder.move_to(point(px(0.), px(0.)));
builder.line_to(point(px(10.), px(0.)));
builder.line_to(point(px(0.), px(10.)));
builder.close();
assert!(builder.build().is_ok());

pub fn dash_array(self, dash_array: &[Pixels]) -> Self

Sets the dash pattern of a stroked path.

The values alternate between dash and gap lengths, in logical pixels, measured along the path. An odd number of values is repeated, so [5, 3, 2] is the same as [5, 3, 2, 5, 3, 2]. The pattern has no effect on fills.

Pass a non-empty slice of finite, positive lengths. crate::PathBuilder::build returns an error for an empty or invalid pattern, including a length too small to advance along the path.

Examples

let mut solid = PathBuilder::stroke(px(1.));
solid.move_to(point(px(0.), px(0.)));
solid.line_to(point(px(20.), px(0.)));
let solid = solid.build().unwrap();

let mut dashed = PathBuilder::stroke(px(1.)).dash_array(&[px(4.), px(4.)]);
dashed.move_to(point(px(0.), px(0.)));
dashed.line_to(point(px(20.), px(0.)));
let dashed = dashed.build().unwrap();

assert!(dashed.vertices.len() > solid.vertices.len());
assert_eq!(dashed.bounds.size.width, px(20.));

pub fn move_to(&mut self, to: Point<Pixels>)

Starts a new sub-path at to. The current point becomes to.

pub fn line_to(&mut self, to: Point<Pixels>)

Adds a straight line from the current point to to.

pub fn curve_to(&mut self, to: Point<Pixels>, ctrl: Point<Pixels>)

Adds a quadratic Bézier curve from the current point to to, bent toward the control point ctrl.

pub fn cubic_bezier_to( &mut self, to: Point<Pixels>, control_a: Point<Pixels>, control_b: Point<Pixels>, )

Adds a cubic Bézier curve from the current point to to, shaped by the control points control_a and control_b.

pub fn arc_to( &mut self, radii: Point<Pixels>, x_rotation: Pixels, large_arc: bool, sweep: bool, to: Point<Pixels>, )

Adds an elliptical arc from the current point to to, in absolute coordinates.

radii gives the x and y radii in logical pixels. x_rotation is the rotation of the ellipse in degrees, even though its type is Pixels. large_arc and sweep choose one of the four possible arcs, as they do in SVG path data.

pub fn relative_arc_to( &mut self, radii: Point<Pixels>, x_rotation: Pixels, large_arc: bool, sweep: bool, to: Point<Pixels>, )

Adds an elliptical arc like crate::PathBuilder::arc_to, but to is relative to the current point. x_rotation is in degrees, as it is for arc_to.

pub fn add_polygon(&mut self, points: &[Point<Pixels>], closed: bool)

Adds points as a sub-path. If closed is true, the last point connects back to the first.

pub fn close(&mut self)

Closes the current sub-path with a line back to its start.

pub fn transform(&mut self, transform: Transform)

Replaces the transform that crate::PathBuilder::build applies with transform.

This discards the effect of any crate::PathBuilder::translate, crate::PathBuilder::scale or crate::PathBuilder::rotate calls made before it.

pub fn translate(&mut self, to: Point<Pixels>)

Moves the path by to when it is built.

Each transform call applies to the path after the transform calls before it.

Examples

let mut builder = PathBuilder::fill();
builder.move_to(point(px(0.), px(0.)));
builder.line_to(point(px(10.), px(0.)));
builder.line_to(point(px(0.), px(10.)));
builder.translate(point(px(5.), px(5.)));
let path = builder.build().unwrap();
assert_eq!(path.bounds.origin, point(px(5.), px(5.)));

pub fn scale(&mut self, scale: f32)

Scales the path by scale on both axes when it is built.

Stroke widths are not scaled, because the geometry is transformed before it is stroked.

Examples

let mut builder = PathBuilder::fill();
builder.move_to(point(px(0.), px(0.)));
builder.line_to(point(px(10.), px(0.)));
builder.line_to(point(px(0.), px(10.)));
builder.scale(2.);
let path = builder.build().unwrap();
assert_eq!(path.bounds.size.width, px(20.));
assert_eq!(path.bounds.size.height, px(20.));

pub fn rotate(&mut self, angle: f32)

Rotates the path by angle degrees around the origin when it is built.

pub fn build(self) -> Result<Path<Pixels>, Error>

Tessellates the path and returns it as a Path.

The transform is applied to the geometry first. A fill uses the FillOptions of its style. A stroke uses the StrokeOptions of its style and the dash array.

Building is the expensive step. Build a path once, and keep it while its shape doesn’t change, rather than rebuilding it every frame.

Errors

Returns an error if a point or the tolerance is NaN, if the mesh needs more vertices than a u16 index can address, or if the dash array is empty, has a length that isn’t finite and positive, or has a length too small to advance along the path.

Examples

let mut builder = PathBuilder::fill();
builder.move_to(point(px(0.), px(0.)));
builder.line_to(point(px(10.), px(0.)));
builder.line_to(point(px(0.), px(10.)));
builder.close();
let path = builder.build().unwrap();
assert!(path.vertices.len() >= 3);
assert_eq!(path.vertices.len() % 3, 0);

pub fn build_path(buf: VertexBuffers<Point, u16>) -> Path<Pixels>

Converts triangles from a lyon VertexBuffers into a Path. Each run of three indices is one triangle. An empty buffer gives an empty path at the origin.

Panics

Panics if an index is out of range for the buffer’s vertices.

Trait Implementations

impl Default for PathBuilder

fn default() -> Self

Returns the “default value” for a type.

impl From<NoAttributes<BuilderImpl>> for PathBuilder

fn from(builder: Builder) -> Self

Converts to this type from the input type.

impl From<WithSvg<BuilderImpl>> for PathBuilder

fn from(raw: WithSvg<BuilderImpl>) -> Self

Converts to this type from the input type.