Images and drawing
Choose between decoded images, declarative vectors, imperative canvases, GPU surfaces, custom elements, and shader effects.
zgui has four elements for visual content. Pick one by what you have to draw:
| Element | Input | Use it for |
|---|---|---|
image | PNG, JPEG, WebP, or GIF bytes | Photographs and raster assets |
vector | Path notation or an SVG document | Icons, logos, and other static vector art |
canvas | Shapes and data series that Rust code builds | Charts, plots, editors, and generated drawings |
surface | A wgpu texture from another renderer | Games, video, and other GPU subsystems |
All four are ordinary elements. CSS sets their box, border, clipping, opacity, transform, and paint order. Their content is not a child subtree.
image and surface can give layout a natural size or aspect ratio. vector and canvas have no
natural size and draw into whatever box CSS gives them. An unstyled canvas is 300 by 150 CSS
pixels; an unstyled vector can have zero area.
When none of these fits:
- A custom element is one retained widget that measures its own children and paints quads, paths, and glyph runs.
- A custom shader fills, shapes, or filters a box with your own WGSL.
Performance
- An image is decoded once, at the size it is displayed, and drawn from a texture.
- A surface stays in its own texture and is composited as one quad.
vector,canvas, and custom-element paths share the vector renderer. Simple and repeated shapes are rasterised once or not at all, and other paths keep their GPU work while the geometry is unchanged. Keep drawings fast has the rules.
Animation
CSS transitions and keyframe animations, which properties are cheap to animate, animation events, enter and exit animations, and per-frame animation from Rust with request_frame.
Images
Load raster images from files or memory, size and fit them with CSS, label them for screen readers, and understand decoding and caching.