Documentation menu

vector_path

Describe immutable vector geometry with a fill, fill rule, and optional stroke.

Use vector_path(data) -> VectorPath when content is best described by retained contours rather than pixels. It accepts data convertible to Arc<PathData>, allowing the view and retained snapshots to share immutable geometry without copying every command.

Appearance

A path starts with solid black fill under the nonzero winding rule. Change that appearance with .fill(paint), remove the fill with .no_fill(), or choose another winding rule through .fill_rule(FillRule). Add .stroke(PathStroke) when the contour also needs an outline.

use hera_kit::{Color, PathData, View, ViewExt, vector_path};
use std::sync::Arc;

fn icon(data: Arc<PathData>) -> impl View {
    vector_path(data)
        .fill(Color::rgba(0.18, 0.25, 0.36, 1.0))
        .frame(24.0, 24.0)
}

The function accepts geometry prepared elsewhere. Use the protocol's PathData and PathCommand definitions when constructing contours, and keep within their validation limits.

Geometry and Layout

Although the path supplies geometry, its layout uses the finite bounds offered by its parent rather than deriving a general intrinsic size from the contours. An explicit frame gives it a deliberate layout extent, such as the 24-by-24 icon region in the example.

That frame does not automatically transform the path as a view box would. Prepare the contours in the intended local coordinates, or apply an explicit transform through the appropriate backend interface when the geometry needs another coordinate mapping.

Shared Geometry and Updates

Stable icon geometry can be reused through the same Arc<PathData>. If the contours change, provide a new immutable value so submitted scenes can continue to reference their earlier geometry safely.

The protocol path patch distinguishes preserving a field from clearing an optional fill or stroke. Ordinary Kit code lets reconciliation translate the new view description into the required operation.

See scene operations and render graph internals.

Component-Specific Reference

These methods configure the VectorPath returned by vector_path(data). They consume the description and return Self, retaining its shared immutable path geometry while replacing the selected appearance property.

MethodPurpose
fillAssigns a fill paint.
no_fillRemoves the interior fill.
fill_ruleSelects how contours determine the filled region.
strokeAssigns an outline style and paint.

fill

fn fill(self, paint: impl Into<Paint>) -> Self

Assigns the interior paint and enables filling even if an earlier no_fill call removed it. A new vector path starts with solid black fill. A later fill call replaces the existing paint without changing the contour commands or stroke.

no_fill

fn no_fill(self) -> Self

Removes the interior fill, allowing a stroked contour to appear as an outline. It leaves the fill rule and any stroke configuration intact. If neither a fill nor a stroke remains, the path contributes no visible paint.

fill_rule

fn fill_rule(self, rule: FillRule) -> Self

Chooses FillRule::NonZero, the default, or FillRule::EvenOdd for interpreting overlapping and nested contours. The rule determines the interior that receives fill paint. It does not modify the contour geometry or set the rule for a separate path clip.

stroke

fn stroke(self, stroke: PathStroke) -> Self

Assigns the outline’s StrokeStyle and Paint. The style includes width, line caps, line joins, miter limit, and dash configuration. Paths start without a stroke, and another call replaces the complete stroke value. To remove a previously configured stroke, construct the next path description without calling stroke.

Configuration Example

use hera_kit::{
    vector_path, Color, FillRule, PathCommand, PathData, PathStroke,
    Point, StrokeStyle, ViewExt,
};
use std::sync::Arc;

let triangle = Arc::new(PathData {
    commands: vec![
        PathCommand::MoveTo(Point::new(4.0, 20.0)),
        PathCommand::LineTo(Point::new(12.0, 4.0)),
        PathCommand::LineTo(Point::new(20.0, 20.0)),
        PathCommand::Close,
    ],
});
let outline = vector_path(triangle.clone())
    .no_fill()
    .stroke(PathStroke {
        style: StrokeStyle { width: 1.5, ..StrokeStyle::default() },
        paint: Color::rgba(0.2, 0.4, 0.7, 1.0).into(),
    })
    .frame(24.0, 24.0);
let filled = vector_path(triangle)
    .fill(Color::rgba(0.2, 0.4, 0.7, 1.0))
    .fill_rule(FillRule::EvenOdd)
    .frame(24.0, 24.0);

Both descriptions share the same contour data while choosing independent fill and stroke treatment. The frames reserve space without rescaling the authored coordinates.

Source Reference

The following files in the Hera checkout define the behavior described on this page.

  • crates/kit/src/view/primitives.rs
  • crates/protocol/src/scene/path.rs
  • crates/protocol/src/scene/nodes.rs