zgui

Vector and canvas

Draw icons and SVG documents with vector, draw shapes from Rust with canvas, pan and zoom with a view transform, plot data series, and keep drawings fast.

vector and canvas draw paths with the vector renderer. Use vector for drawings the view declares, such as icons and SVG documents. Use canvas for drawings Rust code builds or changes, such as charts, plots and editors.

Draw a vector

A vector element takes path notation or a complete SVG document:

use zgui::prelude::*;

const TICK: &str = "M20.5 7.1 L18.9 5.5 L9.6 14.8 L5.1 10.3 L3.5 11.9 L9.6 18.0 Z";

view! {
    vector(class = "icon", prop:d = TICK, prop:viewBox = "0 0 24 24")
}
.icon { width: 24px; height: 24px; color: #6ea8ff; }
.icon:hover { color: #ffb648; }
PropertyValue
dPath notation, one path per line
viewBoxMinimum x, minimum y, width, and height
svgA complete SVG source string. It wins over d.

A drawing has no intrinsic size, so set the element's width and height in CSS. With a view box, zgui scales the drawing uniformly to fit the content box and centers it on the other axis. Without one, coordinates are CSS pixels from the content box's top-left corner.

Colour a vector

A path without its own paint is filled with the element's computed color, and currentColor in an SVG document resolves to the same value. Colours written in the document stay as written. Three inherited custom properties override the defaults:

PropertyDefault
--zgui-fillThe computed color
--zgui-strokeNo stroke
--zgui-stroke-width1px

CSS fill and stroke declarations have no effect. Use the custom properties.

SVG support

The SVG reader supports paths, basic shapes, fills, strokes, fill and clip rules, transforms, opacity, clip paths, gradients, use, symbols, and markers. It ignores text, embedded images, filters, masks, patterns, and blend modes. A document that does not parse draws nothing.

Elements in one window with the same source string share one parsed drawing, so a page of identical icons parses the SVG once.

Build a vector from Rust

zgui::elements::vector() has typed methods: paths, document, view_box, hit_shape, fill, stroke, and stroke_width. paths, document, view_box, and hit_shape take plain values; use a reactive prop:d or prop:svg closure when the source must change. Without hit_shape, the whole box is the hit area.

Draw on a canvas

A canvas holds a retained scene of shapes and series. A shape is a path with its own fill, stroke, and clips, built with ShapeBuilder. Items paint in the order you push them.

Draw from a closure

The closure form suits drawings that follow signals:

use zgui::canvas::zgui_color::Color;
use zgui::canvas::{Brush, ShapeBuilder};
use zgui::elements::{canvas, kurbo};
use zgui::elements::kurbo::Shape as _;
use zgui::prelude::*;

let progress = RwSignal::new(0.6_f64);

let view = canvas().class("meter").draw(move |cx| {
    let width = f64::from(cx.size.width.0) * progress.get();
    let height = f64::from(cx.size.height.0);
    let path = kurbo::Rect::new(0.0, 0.0, width, height).to_path(0.1);
    cx.scene.push(
        ShapeBuilder::new(path)
            .fill(Brush::Solid(Color::srgb(0.2, 0.5, 0.9, 1.0)))
            .build(),
    );
});

The closure reruns when a signal it reads changes and when the content box changes size. Each run starts with an empty scene. cx.size is the content-box size in CSS pixels; cx.scale is the window's current device pixels per CSS pixel. The first run happens before layout with a zero size, so a size-dependent drawing settles one frame after it appears.

Edit a retained scene

Use a CanvasHandle when event handlers edit the scene, as in a drawing tool or a simulation:

let drawing = CanvasHandle::new();
let view = zgui::elements::canvas().class("pad").scene(&drawing);

drawing.draw(|scene| {
    scene.push(shape);
});

CanvasScene has push, replace, clear, shapes, push_series, push_series_lod, and set_transform. Edit it through CanvasHandle::draw on the UI thread; that marks every bound element for repaint.

To produce shapes on another thread, clone the SceneHandle from CanvasHandle::scene() and call SceneHandle::edit. That edit does not wake the UI loop. Follow it with a UI-side signal update or a CanvasHandle::draw call, or the change appears only on the next unrelated repaint.

Fill, stroke and clip shapes

Brush has four forms: Solid(color), Inherited { alpha } (the element's color, like currentColor), Linear { .. }, and Radial { .. }. Gradient coordinates are in canvas units.

ShapeBuilder methodEffect
new(path) / shared(arc)Start from a path, or from an Arc<BezPath> you keep
fill(brush) / fill_even_odd(brush)Fill with the non-zero or even-odd rule
stroke(brush, width)Stroke with round caps and joins
stroke_styled(brush, kurbo::Stroke)Stroke with your own caps, joins, and dashes
clipped(path)Clip the shape to a path; repeat to intersect clips

Coordinates and clipping

Canvas coordinates are CSS pixels from the content box's top-left corner. .view_box(x, y, width, height) makes them view-box units with the same uniform fit as vector. Stroke widths are canvas units, so they scale with a view box.

An unstyled canvas is 300 by 150 CSS pixels. A canvas does not clip its own drawing: put it inside a box with overflow: hidden to keep a plot inside its frame.

Pan and zoom

set_transform(affine) sets one view matrix that moves every shape and series. It applies before the view-box fit and is available on CanvasHandle, SceneHandle, and the scene in a draw closure. Draw the scene once, then move the view from event handlers:

use zgui::elements::kurbo::Affine;
use zgui::prelude::*;

let plot = CanvasHandle::new();
// ... plot.draw(|scene| { /* push shapes and series once */ });

let grab = RwSignal::new(None::<(f32, f64)>);
let offset = RwSignal::new(0.0_f64);

let press = move |cx: &mut EventCx<'_, events::PointerDown>| {
    grab.set(Some((cx.position.x.0, offset.get_untracked())));
    cx.capture_pointer();
};
let drag = {
    let plot = plot.clone();
    move |cx: &mut EventCx<'_, events::PointerMove>| {
        if let Some((start_x, start_offset)) = grab.get_untracked() {
            let dx = start_offset + f64::from(cx.position.x.0 - start_x);
            offset.set(dx);
            plot.set_transform(Affine::translate((dx, 0.0)));
        }
    }
};
let release = move |cx: &mut EventCx<'_, events::PointerUp>| {
    grab.set(None);
    cx.release_pointer();
};

let view = zgui::elements::canvas()
    .class("plot")
    .scene(&plot)
    .on(events::POINTER_DOWN, press)
    .on(events::POINTER_MOVE, drag)
    .on(events::POINTER_UP, release);

A view change does not count as a scene edit, so zgui reuses most of what it built for the shapes and series. What a change costs lists what is reused.

The transform survives clear, so a draw closure keeps it between runs. Setting it from inside a draw closure, though, reruns the closure and rebuilds the scene. For interactive pan and zoom, keep the scene in a CanvasHandle and call set_transform from the event handler.

Plot data with series

A Series holds plot data in data space as an Arc<[[f32; 2]]>, plus a to_canvas matrix that maps data to canvas units. Marker sizes and line widths are CSS pixels: to_canvas, the view transform, and the view box do not scale them. A CSS transform on the element does.

use std::sync::Arc;

use zgui::canvas::zgui_color::Color;
use zgui::canvas::{Brush, Lod, Marker, Series};
use zgui::elements::kurbo::{self, Affine};

let samples: Arc<[[f32; 2]]> = (0..100_000)
    .map(|i| {
        let x = i as f32 / 100.0;
        [x, x.sin()]
    })
    .collect();
let peaks: Arc<[[f32; 2]]> = Arc::from([[15.7, 1.0], [78.5, 1.0], [141.4, 1.0]]);
// x: one CSS pixel per data unit. y: -1..1 maps to 180..20.
let to_canvas = Affine::new([1.0, 0.0, 0.0, -80.0, 0.0, 100.0]);

// `plot` is the `CanvasHandle` from the pan example.
plot.draw(|scene| {
    scene.push_series_lod(
        Series::Line {
            data: samples.clone(),
            to_canvas,
            stroke: kurbo::Stroke::new(1.5),
            brush: Brush::Inherited { alpha: 1.0 },
        },
        Lod::Columns,
    );
    scene.push_series(Series::Points {
        data: peaks.clone(),
        to_canvas,
        marker: Marker::Circle { radius: 3.0 },
        fill: Some(Brush::Solid(Color::srgb(1.0, 0.7, 0.3, 1.0))),
        stroke: None,
    });
});
SeriesDraws
Series::Line { data, to_canvas, stroke, brush }One polyline with round joins. The stroke's caps apply; dashes are ignored.
Series::Points { data, to_canvas, marker, fill, stroke }One marker per point. stroke is Option<(Brush, f64)>.
MarkerShape
Marker::Circle { radius }A circle
Marker::Square { half }An axis-aligned square, half being half the side
Marker::Path(Arc<BezPath>)Any outline in CSS pixels, with its origin on the point

A NaN point ends a line run; a points series skips it. push_series paints the series above the shapes pushed so far. replace and clear remove all series. Series do not take part in hit testing.

zgui builds a series' geometry once per data allocation. Keep the data in one Arc and move it with the view transform instead of rebuilding the array. Data far from the origin keeps its precision.

Reduce dense lines

push_series_lod(series, Lod::Columns) reduces a Series::Line whose x values increase, when it has more than about eight points per device pixel column. zgui keeps the first, lowest, highest, and last point of each half-pixel column. Panning builds nothing new; zooming rebuilds the reduction only after the scale doubles or halves. Set --zgui-vector-lod: columns on the element to apply this to all of its line series.

Antialiasing makes the reduced line slightly lighter where the data is denser than a pixel, so the reduction is opt-in. Points series and shapes are always drawn exactly.

Keep drawings fast

Most drawings need no tuning. When a drawing is large, holds thousands of items, or changes every frame, how you build it decides how much work each frame does.

Rules

  • Build circles and rectangles with kurbo::Circle, kurbo::Rect, and kurbo::RoundedRect so zgui recognises them and draws them as quads or marks.
  • Put many similar shapes in one path (one shape with many subpaths) instead of many shapes. One part becomes one mark or path-glyph item.
  • Keep unchanged geometry in an Arc<BezPath> and pass it with ShapeBuilder::shared. zgui caches its work per allocation, so a draw closure that rebuilds its paths on every run misses every cache.
  • Plot data as series, keep the data Arc stable, and pan or zoom with set_transform.
  • Use Lod::Columns for long time-series lines.
  • Prefer an axis-aligned element transform. Rotation and skew move shapes off the quad, mask, path-glyph, and CPU-layer routes.
  • Recolour through color or --zgui-fill. A colour change re-rasterises nothing on the cheap routes.

Drawing routes

zgui picks a drawing route per shape. You do not choose it, but the shapes you build decide which routes are available. The cheaper routes come first:

RouteTakesCost
QuadsShapes made only of rectangles, rounded rectangles, circles, axis-aligned ellipses, and axis-aligned strokes, a few hundred at most and at least two device pixels apartSame as a CSS background
MarksThe same primitives in larger numbers, overlapping, or stroked lines in any directionOne instanced item per fill or stroke
Path glyphsMany copies (at least 8) of a few small outlines, such as a scatter of triangles, with a solid colour and no clip or dashEach outline rasterised once per scale, like a glyph
MasksA small solid shape (at most 64 KiB of coverage, 1024×256 texels) that does not change every frameRasterised once into the glyph atlas; recolouring and moving reuse it
CPU layerA whole drawing that needs a gradient or clip the routes above cannot draw, and has no seriesRasterised once into an image tile, then drawn like an image
GeneralEverything elseThe GPU vector rasteriser; its encoding is kept while the path Arc lives

Quads, masks, path glyphs, and CPU layers need an element transform that keeps the axes: a scale, a mirror, or a quarter turn (CPU layers: a positive scale only). Marks and series work under any 2D transform. Shapes with a gradient still use quads or marks when their geometry qualifies. Series always use marks, or path glyphs for Marker::Path.

A Marker::Path is drawn from outline tiles rasterised once per scale, so pans and zooms rasterise nothing new. A marker wider than 64 device pixels, a filled marker that crosses itself, or one under a rotating or skewing element transform falls back to the general route.

What a change costs

ChangeCost
Element moves or scrolls by whole device pixelsNothing is rasterised or encoded again
color or --zgui-fill changesQuads, marks, masks, and path glyphs only change colour. General-route shapes encode again, and a CPU layer that uses the inherited colour is rasterised again.
View transform pans or zoomsSee the table below
A scene edit (draw)Each shape is routed again; unchanged path Arcs keep their cached geometry
A shape changes in most framesIt leaves the mask route; a CPU layer that changes often is drawn shape by shape for a while

A view change from set_transform reuses work depending on each item's route:

ItemPan or uniform zoomRotation or non-uniform stretch
SeriesReusedReused
Shapes drawn as quads or marksReusedRebuilt
Shapes drawn as path glyphsReused on pan; rasterised again on zoomRebuilt
Shapes on the general routeEncoding reusedEncoding reused
Drawings on a CPU layerReused for whole-pixel pans; otherwise rasterised again (after a zoom settles)Rasterised again; a rotation draws shape by shape
Shapes on the mask routeRasterised againLeave the route

Large series and drawings

  • Very large series are built on a worker thread. Until that finishes, zgui draws the closest geometry it already has and redraws when the build is ready. On very long series, zgui draws only the chunks near the visible area.
  • A CPU layer is exact for one scale. During a zoom, zgui stretches the nearest tile and rasterises again about three frames after the zoom stops.
  • Drawings larger than 2048 pixels on a side are cut into 512-pixel tiles, and an edit rasterises only the tiles it touches.
  • New CPU layers are budgeted per frame, so a newly shown drawing can appear a frame or two later than the rest of the page.

Writing fast interfaces has the exact thresholds and the counters that show which route a shape took. The renderer architecture explains how each route is rasterised.

Next

On this page