|author||Chad Brokaw <firstname.lastname@example.org>||Fri Apr 14 09:00:06 2023 -0400|
|committer||Chad Brokaw <email@example.com>||Fri Apr 14 09:00:06 2023 -0400|
pin tested revs
An experimental GPU compute-centric 2D renderer
Vello is a 2d graphics rendering engine, using
wgpu. It efficiently draws large 2d scenes with interactive or near-interactive performance.
It is used as the rendering backend for Xilem, a UI toolkit.
Quickstart to run an example program:
cargo run -p with_winit
This repository also includes
vello_svg, which supports converting a
Tree into a Vello scene.
This is currently incomplete; see its crate level documentation for more information.
This is used in the winit example for the SVG rendering.
Our examples are provided in separate packages in the
examples folder. This allows them to have independent dependencies and faster builds. Examples must be selected using the
-p) Cargo flag.
Our winit example (examples/with_winit) demonstrates rendering to a winit window. By default, this renders GhostScript Tiger all SVG files in examples/assets/downloads directory (using
vello_svg). A custom list of SVG file paths (and directories to render all SVG files from) can be provided as arguments instead. It also includes a collection of test scenes showing the capabilities of
vello, which can be shown with
cargo run -p with_winit
Some default test scenes can be downloaded from Wikimedia Commons using the
download subcommand. This also supports downloading from user-provided URLS.
cargo run -p with_winit -- download
The Bevy example (examples/with_bevy) demonstrates using Vello within a Bevy application. This currently draws to a
vello, then uses that texture as the faces of a cube.
cargo run -p with_bevy
We aim to target all environments which can support WebGPU with the default limits. We defer to
wgpu for this support. Other platforms are more tricky, and may require special building/running procedures.
Because Vello relies heavily on compute shaders, we rely on the emerging WebGPU standard to run on the web. Until browser support becomes widespread, it will probably be necessary to use development browser versions (e.g. Chrome Canary) and explicitly enable WebGPU.
The following command builds and runs a web version of the winit demo. This uses
cargo-run-wasm to build the example for web, and host a local server for it
Other examples use the
-p shorthand, but
cargo-run-wasm requires the full
--package to be specified
cargo run_wasm --package with_winit
The web is not currently a primary target for vello, and WebGPU implementations are incomplete, so you might run into issues running this example.
with_winit example supports running on Android, using cargo apk.
cargo apk run -p with_winit
cargo apk doesn't support running in release mode without configuration. See their crates page docs (around
See also cargo-apk#16. To run in release mode, you must add the following to
$HOMEto your home directory):
[package.metadata.android.signing.release] path = "$HOME/.android/debug.keystore" keystore_password = "android"
Discussion of Vello development happens in the Xi Zulip, specifically the #gpu stream. All public content can be read without logging in
We implement a limited, simple preprocessor for our shaders, as wgsl has insufficient code-sharing for our needs.
This implements only classes of statements.
import, which imports from
endif, as standard. These must be at the start of their lines.
src/shaders.rs). Note also that this definitions cannot currently be used in-code (
imports may be used instead)
This format is compatible with
wgsl-analyzer, which we recommend using. If you run into any issues, please report them on Zulip (#gpu > wgsl-analyzer issues), and/or on the
wgsl-analyzer issue tracker.
Note that new imports must currently be added to
.vscode/settings.json for this support to work correctly.
wgsl-analyzer only supports imports in very few syntactic locations, so we limit their use to these places.
Our rendering code does not directly interact with
wgpu. Instead, we generate a
Recording, a simple value type, then an
Engine plays that recording to the actual GPU. The only currently implemented
The idea is that this can abstract easily over multiple GPU back-ends, without either the render logic needing to be polymorphic or having dynamic dispatch at the GPU abstraction. The goal is to be more agile.
The major goal of Vello is to provide a high quality GPU accelerated renderer suitable for a range of 2D graphics applications, including rendering for GUI applications, creative tools, and scientific visualization. The roadmap for 2023 explains the goals and plans for the next few months of development
Vello emerges from being a research project, which attempts to answer these hypotheses:
To what extent is a compute-centered approach better than rasterization (Direct2D)?
To what extent do “advanced” GPU features (subgroups, descriptor arrays, device-scoped barriers) help?
Can we improve quality and extend the imaging model in useful ways?
Another goal of the overall project is to explain how the renderer is built, and to advance the state of building applications on GPU compute shaders more generally. Much of the progress on Vello is documented in blog entries. See doc/blogs.md for pointers to those.
Vello was previously known as
piet-gpu. This prior incarnation used a custom cross-API hardware abstraction layer, called
piet-gpu-hal, instead of
An archive of this version can be found in the branches
custom-hal-archive. This succeeded the previous prototype, piet-metal, and included work adapted from piet-dx12.
The decision to lay down
piet-gpu-hal in favor of WebGPU is discussed in detail in the blog post Requiem for piet-gpu-hal.
A vision document dated December 2020 explained the longer-term goals of the project, and how we might get there. Many of these items are out-of-date or completed, but it still may provide some useful background.
Vello takes inspiration from many other rendering projects, including:
Licensed under either of
at your option.
In addition, all files in the
shader directory and subdirectories thereof are alternatively licensed under the Unlicense (shader/UNLICENSE or http://unlicense.org/). For clarity, these files are also licensed under either of the above licenses. The intent is for this research to be used in as broad a context as possible.
The files in subdirectories of the
examples/assets directory are licensed solely under their respective licenses, available in the
LICENSE file in their directories.
Contributions are welcome by pull request. The Rust code of conduct applies.
Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be licensed as above, without any additional terms or conditions.