Type Alias Path

Source

pub type Path = Handle<SkPath>;

Expand description

Path contain geometry. Path may be empty, or contain one or more verbs that outline a figure. Path always starts with a move verb to a Cartesian coordinate, and may be followed by additional verbs that add lines or curves. Adding a close verb makes the geometry into a continuous loop, a closed contour. Path may contain any number of contours, each beginning with a move verb.

Path contours may contain only a move verb, or may also contain lines, quadratic beziers, conics, and cubic beziers. Path contours may be open or closed.

When used to draw a filled area, Path describes whether the fill is inside or outside the geometry. Path also describes the winding rule used to fill overlapping contours.

Internally, Path lazily computes metrics likes bounds and convexity. Call Path::update_bounds_cache to make Path thread safe.

Aliased Type§

pub struct Path(/* private fields */);

Implementations§

Source §

impl Path

Path contain geometry. Path may be empty, or contain one or more verbs that outline a figure. Path always starts with a move verb to a Cartesian coordinate, and may be followed by additional verbs that add lines or curves. Adding a close verb makes the geometry into a continuous loop, a closed contour. Path may contain any number of contours, each beginning with a move verb.

Path contours may contain only a move verb, or may also contain lines, quadratic beziers, conics, and cubic beziers. Path contours may be open or closed.

When used to draw a filled area, Path describes whether the fill is inside or outside the geometry. Path also describes the winding rule used to fill overlapping contours.

Internally, Path lazily computes metrics likes bounds and convexity. Call Path::update_bounds_cache to make Path thread safe.

Source

pub fn raw( points: &[Point], verbs: &[PathVerb], conic_weights: &[scalar], fill_type: PathFillType, is_volatile: impl Into<Option<bool>>, ) -> Self

Create a new path with the specified spans.

The points and weights arrays are read in order, based on the sequence of verbs.

Move 1 point Line 1 point Quad 2 points Conic 2 points and 1 weight Cubic 3 points Close 0 points

If an illegal sequence of verbs is encountered, or the specified number of points or weights is not sufficient given the verbs, an empty Path is returned.

A legal sequence of verbs consists of any number of Contours. A contour always begins with a Move verb, followed by 0 or more segments: Line, Quad, Conic, Cubic, followed by an optional Close.

Source

pub fn new_from( points: &[Point], verbs: &[u8], conic_weights: &[scalar], fill_type: PathFillType, is_volatile: impl Into<Option<bool>>, ) -> Self

👎Deprecated since 0.88.0: use raw()

Create a new path with the specified spans.

The points and weights arrays are read in order, based on the sequence of verbs.

Move 1 point Line 1 point Quad 2 points Conic 2 points and 1 weight Cubic 3 points Close 0 points

If an illegal sequence of verbs is encountered, or the specified number of points or weights is not sufficient given the verbs, an empty Path is returned.

A legal sequence of verbs consists of any number of Contours. A contour always begins with a Move verb, followed by 0 or more segments: Line, Quad, Conic, Cubic, followed by an optional Close.

Source

pub fn rect_with_fill_type( rect: impl AsRef<Rect>, fill_type: PathFillType, dir: impl Into<Option<PathDirection>>, ) -> Self

Source

pub fn rect( rect: impl AsRef<Rect>, dir: impl Into<Option<PathDirection>>, ) -> Self

Source

pub fn oval( oval: impl AsRef<Rect>, dir: impl Into<Option<PathDirection>>, ) -> Self

Source

pub fn oval_with_start_index( oval: impl AsRef<Rect>, dir: PathDirection, start_index: usize, ) -> Self

Source

pub fn circle( center: impl Into<Point>, radius: scalar, dir: impl Into<Option<PathDirection>>, ) -> Self

Source

pub fn rrect( rect: impl AsRef<RRect>, dir: impl Into<Option<PathDirection>>, ) -> Self

Source

pub fn rrect_with_start_index( rect: impl AsRef<RRect>, dir: PathDirection, start_index: usize, ) -> Self

Source

pub fn polygon( pts: &[Point], is_closed: bool, fill_type: impl Into<Option<PathFillType>>, is_volatile: impl Into<Option<bool>>, ) -> Self

Source

pub fn line(a: impl Into<Point>, b: impl Into<Point>) -> Self

Source

pub fn new_with_fill_type(fill_type: PathFillType) -> Self

Constructs an empty Path. By default, Path has no verbs, no Point, and no weights.

Returns: empty Path

example: https://fiddle.skia.org/c/@Path_empty_constructor

Source

pub fn new() -> Self

Source

pub fn snapshot(&self) -> Self

Returns a copy of this path in the current state.

Source

pub fn is_interpolatable(&self, compare: &Path) -> bool

Returns true if Path contain equal verbs and equal weights. If Path contain one or more conics, the weights must match.

conic_to() may add different verbs depending on conic weight, so it is not trivial to interpolate a pair of Path containing conics with different conic weight values.

compare - Path to compare

Returns: true if Path verb array and weights are equivalent

example: https://fiddle.skia.org/c/@Path_isInterpolatable

Source

pub fn interpolate(&self, ending: &Path, weight: scalar) -> Option<Self>

Interpolates between Path with Point array of equal size. Copy verb array and weights to out, and set out Point array to a weighted average of this Point array and ending Point array, using the formula: (Path Point * weight) + ending Point * (1 - weight).

weight is most useful when between zero (ending Point array) and one (this Point_Array); will work with values outside of this range.

interpolate() returns an empty Path if Point array is not the same size as ending Point array. Call is_interpolatable() to check Path compatibility prior to calling make_interpolate().

ending - Point array averaged with this Point array
weight - contribution of this Point array, and one minus contribution of ending Point array

Returns: Path replaced by interpolated averages

example: https://fiddle.skia.org/c/@Path_interpolate

Source

pub fn interpolate_inplace( &self, ending: &Path, weight: scalar, out: &mut Path, ) -> bool

Interpolates between Path with Point array of equal size. Copy verb array and weights to out, and set out Point array to a weighted average of this Point array and ending Point array, using the formula: (Path Point * weight) + ending Point * (1 - weight).

weight is most useful when between zero (ending Point array) and one (this Point_Array); will work with values outside of this range.

interpolate_inplace() returns false and leaves out unchanged if Point array is not the same size as ending Point array. Call is_interpolatable() to check Path compatibility prior to calling interpolate_inplace().

ending - Point array averaged with this Point array
weight - contribution of this Point array, and one minus contribution of ending Point array
out - Path replaced by interpolated averages

Returns: true if Path contain same number of Point

example: https://fiddle.skia.org/c/@Path_interpolate

Source

pub fn fill_type(&self) -> PathFillType

Returns PathFillType, the rule used to fill Path.

Returns: current PathFillType setting

Source

pub fn with_fill_type(&self, new_fill_type: PathFillType) -> Path

Source

pub fn is_inverse_fill_type(&self) -> bool

Returns if FillType describes area outside Path geometry. The inverse fill area extends indefinitely.

Returns: true if FillType is InverseWinding or InverseEvenOdd

Source

pub fn with_toggle_inverse_fill_type(&self) -> Self

Creates an Path with the same properties and data, and with PathFillType replaced with its inverse. The inverse of PathFillType describes the area unmodified by the original FillType.

Source

pub fn is_convex(&self) -> bool

Returns true if the path is convex. If necessary, it will first compute the convexity.

Source

pub fn is_oval(&self) -> Option<Rect>

Returns true if this path is recognized as an oval or circle.

bounds receives bounds of oval.

bounds is unmodified if oval is not found.

bounds - storage for bounding Rect of oval; may be None

Returns: true if Path is recognized as an oval or circle

example: https://fiddle.skia.org/c/@Path_isOval

Source

pub fn is_rrect(&self) -> Option<RRect>

Returns RRect if path is representable as RRect. Returns None if path is representable as oval, circle, or Rect.

Returns: RRect if Path contains only RRect

example: https://fiddle.skia.org/c/@Path_isRRect

Source

pub fn is_empty(&self) -> bool

Returns if Path is empty. Empty Path may have FillType but has no Point, Verb, or conic weight. Path::default() constructs empty Path; reset() and rewind() make Path empty.

Returns: true if the path contains no Verb array

Source

pub fn is_last_contour_closed(&self) -> bool

Returns if contour is closed. Contour is closed if Path Verb array was last modified by close(). When stroked, closed contour draws crate::paint::Join instead of crate::paint::Cap at first and last Point.

Returns: true if the last contour ends with a [Verb::Close]

example: https://fiddle.skia.org/c/@Path_isLastContourClosed

Source

pub fn is_finite(&self) -> bool

Returns true for finite Point array values between negative SK_ScalarMax and positive SK_ScalarMax. Returns false for any Point array value of SK_ScalarInfinity, SK_ScalarNegativeInfinity, or SK_ScalarNaN.

Returns: true if all Point values are finite

Source

pub fn is_volatile(&self) -> bool

Returns true if the path is volatile; it will not be altered or discarded by the caller after it is drawn. Path by default have volatile set false, allowing crate::Surface to attach a cache of data which speeds repeated drawing. If true, crate::Surface may not speed repeated drawing.

Returns: true if caller will alter Path after drawing

Source

pub fn with_is_volatile(&self, is_volatile: bool) -> Self

Return a copy of Path with is_volatile indicating whether it will be altered or discarded by the caller after it is drawn. Path by default have volatile set false, allowing Skia to attach a cache of data which speeds repeated drawing.

Mark temporary paths, discarded or modified after use, as volatile to inform Skia that the path need not be cached.

Mark animating Path volatile to improve performance. Mark unchanging Path non-volatile to improve repeated rendering.

raster surface Path draws are affected by volatile for some shadows. GPU surface Path draws are affected by volatile for some shadows and concave geometries.

is_volatile - true if caller will alter Path after drawing

Returns: Path

Source

pub fn is_line_degenerate( p1: impl Into<Point>, p2: impl Into<Point>, exact: bool, ) -> bool

Tests if line between Point pair is degenerate. Line with no length or that moves a very short distance is degenerate; it is treated as a point.

exact changes the equality test. If true, returns true only if p1 equals p2. If false, returns true if p1 equals or nearly equals p2.

p1 - line start point
p2 - line end point
exact - if false, allow nearly equals

Returns: true if line is degenerate; its length is effectively zero

example: https://fiddle.skia.org/c/@Path_IsLineDegenerate

Source

pub fn is_quad_degenerate( p1: impl Into<Point>, p2: impl Into<Point>, p3: impl Into<Point>, exact: bool, ) -> bool

Tests if quad is degenerate. Quad with no length or that moves a very short distance is degenerate; it is treated as a point.

p1 - quad start point
p2 - quad control point
p3 - quad end point
exact - if true, returns true only if p1, p2, and p3 are equal; if false, returns true if p1, p2, and p3 are equal or nearly equal

Returns: true if quad is degenerate; its length is effectively zero

Source

pub fn is_cubic_degenerate( p1: impl Into<Point>, p2: impl Into<Point>, p3: impl Into<Point>, p4: impl Into<Point>, exact: bool, ) -> bool

Tests if cubic is degenerate. Cubic with no length or that moves a very short distance is degenerate; it is treated as a point.

p1 - cubic start point
p2 - cubic control point 1
p3 - cubic control point 2
p4 - cubic end point
exact - if true, returns true only if p1, p2, p3, and p4 are equal; if false, returns true if p1, p2, p3, and p4 are equal or nearly equal

Returns: true if cubic is degenerate; its length is effectively zero

Source

pub fn is_line(&self) -> Option<(Point, Point)>

Returns true if Path contains only one line; Verb array has two entries: [Verb::Move], [Verb::Line]. If Path contains one line and line is not None, line is set to line start point and line end point. Returns false if Path is not one line; line is unaltered.

line - storage for line. May be None

Returns: true if Path contains exactly one line

example: https://fiddle.skia.org/c/@Path_isLine

Source

pub fn points(&self) -> &[Point]

Return a read-only view into the path’s points.

Source

pub fn verbs(&self) -> &[PathVerb] ⓘ

Return a read-only view into the path’s verbs.

Source

pub fn conic_weights(&self) -> &[scalar] ⓘ

Return a read-only view into the path’s conic-weights.

Source

pub fn count_points(&self) -> usize

Source

pub fn count_verbs(&self) -> usize

Source

pub fn last_pt(&self) -> Option<Point>

Return the last point, or None

Returns: The last if the path contains one or more Point, else returns None

example: https://fiddle.skia.org/c/@Path_getLastPt

Source §

impl Path

Source

pub fn get_point(&self, index: usize) -> Option<Point>

👎Deprecated since 0.91.0: use points()

Returns Point at index in Point array. Valid range for index is 0 to count_points() - 1. Returns None if index is out of range. DEPRECATED

index - Point array element selector

Returns: Point array value

example: https://fiddle.skia.org/c/@Path_getPoint

Source

pub fn get_points(&self, points: &mut [Point]) -> usize

👎Deprecated since 0.91.0

Returns number of points in Path. Copies N points from the path into the span, where N = min(#points, span capacity) DEPRECATED

points - span to receive the points. may be empty

Returns: the number of points in the path

example: https://fiddle.skia.org/c/@Path_getPoints

Source

pub fn get_verbs(&self, verbs: &mut [u8]) -> usize

👎Deprecated since 0.91.0

Returns number of points in Path. Copies N points from the path into the span, where N = min(#points, span capacity) DEPRECATED

verbs - span to store the verbs. may be empty.

Returns: the number of verbs in the path

example: https://fiddle.skia.org/c/@Path_getVerbs

Source §

impl Path

Source

pub fn approximate_bytes_used(&self) -> usize

Returns the approximate byte size of the Path in memory.

Returns: approximate size

Source

pub fn bounds(&self) -> &Rect

Returns minimum and maximum axes values of Point array. Returns (0, 0, 0, 0) if Path contains no points. Returned bounds width and height may be larger or smaller than area affected when Path is drawn.

Rect returned includes all Point added to Path, including Point associated with [Verb::Move] that define empty contours.

Returns: bounds of all Point in Point array

Source

pub fn update_bounds_cache(&mut self) -> &mut Self

Updates internal bounds so that subsequent calls to bounds() are instantaneous. Unaltered copies of Path may also access cached bounds through bounds().

For now, identical to calling bounds() and ignoring the returned value.

Call to prepare Path subsequently drawn from multiple threads, to avoid a race condition where each draw separately computes the bounds.

Source

pub fn compute_tight_bounds(&self) -> Rect

Returns minimum and maximum axes values of the lines and curves in Path. Returns (0, 0, 0, 0) if Path contains no points. Returned bounds width and height may be larger or smaller than area affected when Path is drawn.

Includes Point associated with [Verb::Move] that define empty contours.

Behaves identically to bounds() when Path contains only lines. If Path contains curves, computed bounds includes the maximum extent of the quad, conic, or cubic; is slower than bounds(); and unlike bounds(), does not cache the result.

Returns: tight bounds of curves in Path

example: https://fiddle.skia.org/c/@Path_computeTightBounds

Source

pub fn conservatively_contains_rect(&self, rect: impl AsRef<Rect>) -> bool

Returns true if rect is contained by Path. May return false when rect is contained by Path.

For now, only returns true if Path has one contour and is convex. rect may share points and edges with Path and be contained. Returns true if rect is empty, that is, it has zero width or height; and the Point or line described by rect is contained by Path.

rect - Rect, line, or Point checked for containment

Returns: true if rect is contained

example: https://fiddle.skia.org/c/@Path_conservativelyContainsRect

Source §

impl Path

Source

pub fn convert_conic_to_quads( p0: impl Into<Point>, p1: impl Into<Point>, p2: impl Into<Point>, w: scalar, pts: &mut [Point], pow2: usize, ) -> Option<usize>

Approximates conic with quad array. Conic is constructed from start Point p0, control Point p1, end Point p2, and weight w. Quad array is stored in pts; this storage is supplied by caller. Maximum quad count is 2 to the pow2. Every third point in array shares last Point of previous quad and first Point of next quad. Maximum pts storage size is given by: (1 + 2 * (1 << pow2)) * sizeof(Point).

Returns quad count used the approximation, which may be smaller than the number requested.

conic weight determines the amount of influence conic control point has on the curve. w less than one represents an elliptical section. w greater than one represents a hyperbolic section. w equal to one represents a parabolic section.

Two quad curves are sufficient to approximate an elliptical conic with a sweep of up to 90 degrees; in this case, set pow2 to one.

p0 - conic start Point
p1 - conic control Point
p2 - conic end Point
w - conic weight
pts - storage for quad array
pow2 - quad count, as power of two, normally 0 to 5 (1 to 32 quad curves)

Returns: number of quad curves written to pts

Source

pub fn is_rect(&self) -> Option<(Rect, bool, PathDirection)>

Returns Some(Rect, bool, PathDirection) if Path is equivalent to Rect when filled. If false: rect, is_closed, and direction are unchanged. If true: rect, is_closed, and direction are written to.

rect may be smaller than the Path bounds. Path bounds may include [Verb::Move] points that do not alter the area drawn by the returned rect.

Returns: Some(rect, is_closed, direction) if Path contains Rect

rect - bounds of Rect
is_closed - set to true if Path is closed
direction - to Rect direction

example: https://fiddle.skia.org/c/@Path_isRect

Source §

impl Path

Source

pub fn try_make_transform(&self, matrix: &Matrix) -> Option<Path>

Return a copy of Path with verb array, Point array, and weight transformed by matrix. try_make_transform may change verbs and increase their number.

If the resulting path has any non-finite values, returns None.

matrix - Matrix to apply to Path

Returns: Path if finite, or None

Source

pub fn try_make_offset(&self, d: impl Into<Vector>) -> Option<Path>

Source

pub fn try_make_scale(&self, (sx, sy): (scalar, scalar)) -> Option<Path>

Source

pub fn with_transform(&self, matrix: &Matrix) -> Path

Return a copy of Path with verb array, Point array, and weight transformed by matrix. with_transform may change verbs and increase their number.

If the resulting path has any non-finite values, this will still return a path but that path will return true for is_finite().

The newer pattern is to call try_make_transform which will only return a path if the result is finite.

matrix - Matrix to apply to Path

Returns: Path

example: https://fiddle.skia.org/c/@Path_transform

Source

pub fn make_transform(&self, m: &Matrix) -> Path

Source

pub fn with_offset(&self, d: impl Into<Vector>) -> Path

Returns Path with Point array offset by (d.x, d.y).

d - offset added to Point array coordinates

Returns: Path

example: https://fiddle.skia.org/c/@Path_offset

Source

pub fn segment_masks(&self) -> SegmentMask

Returns a mask, where each set bit corresponds to a SegmentMask constant if Path contains one or more verbs of that type. Returns zero if Path contains no lines, or curves: quads, conics, or cubics.

segment_masks() returns a cached result; it is very fast.

Returns: SegmentMask bits or zero

Source §

impl Path

Source

pub fn set_is_volatile(&mut self, is_volatile: bool) -> &mut Self

Specifies whether Path is volatile; whether it will be altered or discarded by the caller after it is drawn. Path by default have volatile set false, allowing Device to attach a cache of data which speeds repeated drawing.

Mark temporary paths, discarded or modified after use, as volatile to inform Device that the path need not be cached.

Mark animating Path volatile to improve performance. Mark unchanging Path non-volatile to improve repeated rendering.

raster surface Path draws are affected by volatile for some shadows. GPU surface Path draws are affected by volatile for some shadows and concave geometries.

is_volatile - true if caller will alter Path after drawing

Returns: reference to Path

Source

pub fn swap(&mut self, other: &mut Path) -> &mut Self

Exchanges the verb array, Point array, weights, and PathFillType with other. Cached state is also exchanged. swap() internally exchanges pointers, so it is lightweight and does not allocate memory.

swap() usage has largely been replaced by PartialEq. Path do not copy their content on assignment until they are written to, making assignment as efficient as swap().

other - Path exchanged by value

example: https://fiddle.skia.org/c/@Path_swap

Source

pub fn set_fill_type(&mut self, ft: PathFillType) -> &mut Self

Sets FillType, the rule used to fill Path. While there is no check that ft is legal, values outside of FillType are not supported.

Source

pub fn toggle_inverse_fill_type(&mut self) -> &mut Self

Replaces FillType with its inverse. The inverse of FillType describes the area unmodified by the original FillType.

Source

pub fn reset(&mut self) -> &mut Self

Sets Path to its initial state. Removes verb array, Point array, and weights, and sets FillType to Winding. Internal storage associated with Path is released.

Returns: reference to Path

example: https://fiddle.skia.org/c/@Path_reset

Source §

impl Path

Source

pub fn detach(&mut self) -> Self

Returns a copy of this path in the current state, and resets the path to empty.

Source

pub fn iter(&self) -> PathIter<'_> ⓘ

Source §

impl Path

Source

pub fn contains(&self, point: impl Into<Point>) -> bool

Returns true if the point is contained by Path, taking into account PathFillType.

point - the point to test

Returns: true if Point is in Path

example: https://fiddle.skia.org/c/@Path_contains

Source

pub fn dump_as_data(&self, dump_as_hex: bool) -> Data

Writes text representation of Path to Data. Set dump_as_hex true to generate exact binary representations of floating point numbers used in Point array and conic weights.

dump_as_hex - true if scalar values are written as hexadecimal

example: https://fiddle.skia.org/c/@Path_dump

Source

pub fn dump(&self)

See Path::dump_as_data()

Source

pub fn dump_hex(&self)

See Path::dump_as_data()

Source

pub fn serialize(&self) -> Data

Writes Path to buffer, returning the buffer written to, wrapped in Data.

serialize() writes PathFillType, verb array, Point array, conic weight, and additionally writes computed information like convexity and bounds.

serialize() should only be used in concert with read_from_memory(). The format used for Path in memory is not guaranteed.

Returns: Path data wrapped in Data buffer

example: https://fiddle.skia.org/c/@Path_serialize

Source

pub fn deserialize(data: &Data) -> Option<Path>

Source

pub fn generation_id(&self) -> u32

(See skbug.com/40032862) Returns a non-zero, globally unique value. A different value is returned if verb array, Point array, or conic weight changes.

Setting PathFillType does not change generation identifier.

Each time the path is modified, a different generation identifier will be returned. PathFillType does affect generation identifier on Android framework.

Returns: non-zero, globally unique value

example: https://fiddle.skia.org/c/@Path_getGenerationID

Source

pub fn is_valid(&self) -> bool

Returns if Path data is consistent. Corrupt Path data is detected if internal values are out of range or internal storage does not match array dimensions.

Returns: true if Path data is consistent

Source §