[−]Struct druid::piet::kurbo::BezPath
A Bézier path.
These docs assume basic familiarity with Bézier curves; for an introduction, see Pomax's wonderful A Primer on Bézier Curves.
This path can contain lines, quadratics (QuadBez
) and cubics
(CubicBez
), and may contain multiple subpaths.
Elements and Segments
A Bézier path can be represented in terms of either 'elements' (PathEl
)
or 'segments' (PathSeg
). Elements map closely to how Béziers are
generally used in PostScript-style drawing APIs; they can be thought of as
instructions for drawing the path. Segments more directly describe the
path itself, with each segment being an independent line or curve.
These different representations are useful in different contexts. For tasks like drawing, elements are a natural fit, but when doing hit-testing or subdividing, we need to have access to the segments.
Internally, a BezPath
is a list of PathEl
s; as such it implements
FromIterator<PathEl>
and Extend<PathEl>
:
use kurbo::{BezPath, Rect, Shape, Vec2}; let accuracy = 0.1; let rect = Rect::from_origin_size((0., 0.,), (10., 10.)); // these are equivalent let path1 = rect.to_path(accuracy); let path2: BezPath = rect.path_elements(accuracy).collect(); // extend a path with another path: let mut path = rect.to_path(accuracy); let shifted_rect = rect + Vec2::new(5.0, 10.0); path.extend(shifted_rect.to_path(accuracy));
You can iterate the elements of a BezPath
with the iter
method,
and the segments with the segments
method:
use kurbo::{BezPath, Line, PathEl, PathSeg, Point, Rect, Shape}; let accuracy = 0.1; let rect = Rect::from_origin_size((0., 0.,), (10., 10.)); // these are equivalent let path = rect.to_path(accuracy); let first_el = PathEl::MoveTo(Point::ZERO); let first_seg = PathSeg::Line(Line::new((0., 0.), (10., 0.))); assert_eq!(path.iter().next(), Some(first_el)); assert_eq!(path.segments().next(), Some(first_seg));
In addition, if you have some other type that implements
Iterator<Item=PathEl>
, you can adapt that to an iterator of segments with
the segments
free function.
Advanced functionality
In addition to the basic API, there are several useful pieces of advanced
functionality available on BezPath
:
flatten
does Bézier flattening, converting a curve to a series of line segmentsintersect_line
computes intersections of a path with a line, useful for things like subdividing
Implementations
impl BezPath
pub fn new() -> BezPath
Create a new path.
pub fn from_vec(v: Vec<PathEl, Global>) -> BezPath
Create a path from a vector of path elements.
BezPath
also implements FromIterator<PathEl>
, so it works with collect
:
// a very contrived example: use kurbo::{BezPath, PathEl}; let path = BezPath::new(); let as_vec: Vec<PathEl> = path.into_iter().collect(); let back_to_path: BezPath = as_vec.into_iter().collect();
pub fn push(&mut self, el: PathEl)
Push a generic path element onto the path.
pub fn move_to<P>(&mut self, p: P) where
P: Into<Point>,
P: Into<Point>,
Push a "move to" element onto the path.
pub fn line_to<P>(&mut self, p: P) where
P: Into<Point>,
P: Into<Point>,
Push a "line to" element onto the path.
pub fn quad_to<P>(&mut self, p1: P, p2: P) where
P: Into<Point>,
P: Into<Point>,
Push a "quad to" element onto the path.
pub fn curve_to<P>(&mut self, p1: P, p2: P, p3: P) where
P: Into<Point>,
P: Into<Point>,
Push a "curve to" element onto the path.
pub fn close_path(&mut self)
Push a "close path" element onto the path.
pub fn elements(&self) -> &[PathEl]
Get the path elements.
pub fn iter(&self) -> impl Iterator<Item = PathEl>
Returns an iterator over the path's elements.
pub fn segments(&self) -> impl Iterator<Item = PathSeg>
Iterate over the path segments.
pub fn flatten(&self, tolerance: f64, callback: impl FnMut(PathEl))
Flatten the path, invoking the callback repeatedly.
Flattening is the action of approximating a curve with a succession of line segments.
The tolerance value controls the maximum distance between the curved input
segments and their polyline approximations. (In technical terms, this is the
Hausdorff distance). The algorithm attempts to bound this distance between
by tolerance
but this is not absolutely guaranteed. The appropriate value
depends on the use, but for antialiasted rendering, a value of 0.25 has been
determined to give good results. The number of segments tends to scale as the
inverse square root of tolerance.
The callback will be called in order with each element of the generated path. Because the result is made of polylines, these will be straight-line path elements only, no curves.
This algorithm is based on the blog post Flattening quadratic Béziers but with some refinements. For one, there is a more careful approximation at cusps. For two, the algorithm is extended to work with cubic Béziers as well, by first subdividing into quadratics and then computing the subdivision of each quadratic. However, as a clever trick, these quadratics are subdivided fractionally, and their endpoints are not included.
TODO: write a paper explaining this in more detail.
Note: the flatten
function provides the same
functionality but works with slices and other PathEl
iterators.
pub fn get_seg(&self, ix: usize) -> Option<PathSeg>
Get the segment at the given element index.
The element index counts PathEl
elements, so
for example includes an initial Moveto
.
pub fn is_empty(&self) -> bool
Returns true
if the path contains no segments.
pub fn apply_affine(&mut self, affine: Affine)
Apply an affine transform to the path.
impl BezPath
pub fn from_path_segments(segments: impl Iterator<Item = PathSeg>) -> BezPath
Create a BezPath with segments corresponding to the sequence of
PathSeg
s
pub fn to_svg(&self) -> String
Convert the path to an SVG path string representation.
The current implementation doesn't take any special care to produce a short string (reducing precision, using relative movement).
pub fn write_to<W>(&self, writer: W) -> Result<(), Error> where
W: Write,
W: Write,
Write the SVG representation of this path to the provided buffer.
pub fn from_svg(data: &str) -> Result<BezPath, SvgParseError>
Try to parse a bezier path from an SVG path element.
This is implemented on a best-effort basis, intended for cases where the user controls the source of paths, and is not intended as a replacement for a general, robust SVG parser.
Trait Implementations
impl Clone for BezPath
pub fn clone(&self) -> BezPath
pub fn clone_from(&mut self, source: &Self)
1.0.0[src]
impl Data for BezPath
[src]
impl Debug for BezPath
impl Default for BezPath
impl Extend<PathEl> for BezPath
pub fn extend<I>(&mut self, iter: I) where
I: IntoIterator<Item = PathEl>,
I: IntoIterator<Item = PathEl>,
pub fn extend_one(&mut self, item: A)
[src]
pub fn extend_reserve(&mut self, additional: usize)
[src]
impl FromIterator<PathEl> for BezPath
pub fn from_iter<T>(iter: T) -> BezPath where
T: IntoIterator<Item = PathEl>,
T: IntoIterator<Item = PathEl>,
impl IntoIterator for BezPath
type Item = PathEl
The type of the elements being iterated over.
type IntoIter = IntoIter<PathEl, Global>
Which kind of iterator are we turning this into?
pub fn into_iter(self) -> <BezPath as IntoIterator>::IntoIter
impl<'a> IntoIterator for &'a BezPath
Allow iteration over references to BezPath
.
Note: the semantics are slightly different than simply iterating over the
slice, as it returns PathEl
items, rather than references.
type Item = PathEl
The type of the elements being iterated over.
type IntoIter = Cloned<Iter<'a, PathEl>>
Which kind of iterator are we turning this into?
pub fn into_iter(self) -> <&'a BezPath as IntoIterator>::IntoIter
impl<'a> Mul<&'a BezPath> for TranslateScale
type Output = BezPath
The resulting type after applying the *
operator.
pub fn mul(self, other: &BezPath) -> BezPath
impl<'a> Mul<&'a BezPath> for Affine
type Output = BezPath
The resulting type after applying the *
operator.
pub fn mul(self, other: &BezPath) -> BezPath
impl Mul<BezPath> for TranslateScale
type Output = BezPath
The resulting type after applying the *
operator.
pub fn mul(self, other: BezPath) -> BezPath
impl Mul<BezPath> for Affine
type Output = BezPath
The resulting type after applying the *
operator.
pub fn mul(self, other: BezPath) -> BezPath
impl Shape for BezPath
type PathElementsIter = IntoIter<PathEl, Global>
The iterator returned by the path_elements
method. Read more
pub fn path_elements(
&self,
_tolerance: f64
) -> <BezPath as Shape>::PathElementsIter
&self,
_tolerance: f64
) -> <BezPath as Shape>::PathElementsIter
pub fn to_path(&self, _tolerance: f64) -> BezPath
pub fn into_path(self, _tolerance: f64) -> BezPath
pub fn area(&self) -> f64
Signed area.
pub fn perimeter(&self, accuracy: f64) -> f64
pub fn winding(&self, pt: Point) -> i32
Winding number of point.
pub fn bounding_box(&self) -> Rect
pub fn as_path_slice(&self) -> Option<&[PathEl]>
pub fn path_segments(&self, tolerance: f64) -> Segments<Self::PathElementsIter>ⓘ
pub fn contains(&self, pt: Point) -> bool
pub fn as_line(&self) -> Option<Line>
pub fn as_rect(&self) -> Option<Rect>
pub fn as_rounded_rect(&self) -> Option<RoundedRect>
pub fn as_circle(&self) -> Option<Circle>
Auto Trait Implementations
impl RefUnwindSafe for BezPath
[src]
impl Send for BezPath
[src]
impl Sync for BezPath
[src]
impl Unpin for BezPath
[src]
impl UnwindSafe for BezPath
[src]
Blanket Implementations
impl<T> Any for T where
T: 'static + ?Sized,
[src]
T: 'static + ?Sized,
impl<T> Borrow<T> for T where
T: ?Sized,
[src]
T: ?Sized,
impl<T> BorrowMut<T> for T where
T: ?Sized,
[src]
T: ?Sized,
pub fn borrow_mut(&mut self) -> &mut T
[src]
impl<T> From<T> for T
[src]
impl<T, U> Into<U> for T where
U: From<T>,
[src]
U: From<T>,
impl<T> RoundFrom<T> for T
pub fn round_from(x: T) -> T
impl<T, U> RoundInto<U> for T where
U: RoundFrom<T>,
U: RoundFrom<T>,
pub fn round_into(self) -> U
impl<T> Same<T> for T
type Output = T
Should always be Self
impl<T> ToOwned for T where
T: Clone,
[src]
T: Clone,
type Owned = T
The resulting type after obtaining ownership.
pub fn to_owned(&self) -> T
[src]
pub fn clone_into(&self, target: &mut T)
[src]
impl<T, U> TryFrom<U> for T where
U: Into<T>,
[src]
U: Into<T>,
type Error = Infallible
The type returned in the event of a conversion error.
pub fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>
[src]
impl<T, U> TryInto<U> for T where
U: TryFrom<T>,
[src]
U: TryFrom<T>,