Vello is a 2d graphics rendering engine, using [`wgpu`].
It efficiently draws large 2d scenes with interactive or near-interactive performance.
<!-- Impressive picture here -->
It is used as the rendering backend for [xilem], a UI toolkit.
## Examples
Our examples are provided in separate packages in the [`examples`](examples) folder.
This allows them to have independent dependencies and faster builds.
Examples must be selected using the `--package` (or `-p`) Cargo flag.
### Winit
Our [winit] example ([examples/with_winit](examples/with_winit)) demonstrates rendering to a [winit] window.
It also includes a collection of test scenes showing the capabilities of vello.
One of these scenes uses an incomplete svg parser/renderer to render the [GhostScript tiger].
```shell
cargo run -p with_winit
```
### Bevy
The [Bevy] example ([examples/with_bevy](examples/with_bevy)) demonstrates using vello within a [Bevy] application.
This currently draws to a [`wgpu`] `Texture` using `vello`, then uses that texture as the faces of a cube.
```shell
cargo run -p with_bevy
```
### Web
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](#winit).
```shell
cargo run --release -p run-wasm -- --package with_winit
```
Additionally, the web is not currently a primary target, so other issues are likely to arise.
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](https://xi.zulipchat.com/#narrow/stream/197075-gpu/topic/wgsl-analyzer.20issues)), 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.
## GPU abstraction
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 `Engine` uses `wgpu`.
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.
## History
Vello was previously known as `piet-gpu`. This prior incarnation used a custom cross-API hardware abstraction layer, called `piet-gpu-hal`, instead of [`wgpu`].
<!-- Some discussion of this transition can be found in the blog post [A requiem to piet-gpu-hal]() TODO: Once the blog post is published -->
There is a [vision](doc/vision.md) document which 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.
An archive of this version can be found in the branches [`custom-hal-archive-with-shaders`] and [`custom-hal-archive`].
This succeeded the previous prototype, [piet-metal], and included work adapted from [piet-dx12] by Brian Merchant.
<!-- TODO: Are these goals still correct? Are there new goals? Are these useful to have in the readme specifically, now that we're actually "encouraging" users -->
