From 480e5a5e2fb1ed5c38da083bfa00c1ae6b9b2486 Mon Sep 17 00:00:00 2001 From: Daniel McNab <36049421+DJMcNab@users.noreply.github.com> Date: Thu, 5 Jan 2023 22:56:46 +0000 Subject: [PATCH] Update the README to reflect velloness (#233) Co-authored-by: Raph Levien --- README.md | 150 ++++++++++++++---- .../{third-party => roboto}/LICENSE.txt | 0 .../Roboto-Regular.ttf | Bin examples/with_winit/src/simple_text.rs | 2 +- 4 files changed, 121 insertions(+), 31 deletions(-) rename examples/assets/{third-party => roboto}/LICENSE.txt (100%) rename examples/assets/{third-party => roboto}/Roboto-Regular.ttf (100%) diff --git a/README.md b/README.md index 97ca590..5390bcc 100644 --- a/README.md +++ b/README.md @@ -1,47 +1,145 @@ +
+ # vello -This repo contains the new prototype for a new compute-centric 2D GPU renderer (formerly known as piet-gpu). +**An experimental GPU compute-centric 2D renderer** -> **Warning** -> This README is a work in progress. Previous versions are included below for reference +[![Xi Zulip](https://img.shields.io/badge/Xi%20Zulip-%23gpu-blue?logo=Zulip)](https://xi.zulipchat.com/#narrow/stream/197075-gpu) +[![dependency status](https://deps.rs/repo/github/linebender/vello/status.svg)](https://deps.rs/repo/github/linebender/vello) +[![MIT/Apache 2.0](https://img.shields.io/badge/license-MIT%2FApache-blue.svg)](#license) + + + -It succeeds the previous prototype, [piet-metal]. +
-The latest version is a middleware for [`wgpu`]. This is used as the rendering backend for -[xilem], a UI toolkit. +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. + +## 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. + +## Shader templating + +We implement a limited, simple preprocessor for our shaders, as wgsl has insufficient code-sharing for our needs. + +This implements only classes of statements. + +1. `import`, which imports from `shader/shared` +2. `ifdef`, `ifndef`, `else` and `endif`, as standard. + These must be at the start of their lines. + Note that there is no support for creating definitions in-shader, these are only specified externally (in `src/shaders.rs`). + Note also that this definitions cannot currently be used in-code (`import`s 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](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`]. + + +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. ## Goals + + The main goal is to answer research questions about the future of 2D rendering: -- Is a compute-centered approach better than rasterization ([Direct2D])? How much so? +- Is a compute-centered approach better than rasterization ([Direct2D])? How much so? -- To what extent do "advanced" GPU features (subgroups, descriptor arrays) help? +- To what extent do "advanced" GPU features (subgroups, descriptor arrays) help? -- Can we improve quality and extend the imaging model in useful ways? +- Can we improve quality and extend the imaging model in useful ways? ## Blogs and other writing Much of the research progress on piet-gpu is documented in blog entries. See [doc/blogs.md](doc/blogs.md) for pointers to those. -There is a much larger and detailed [vision](doc/vision.md) that explains the longer-term goals of the project, and how we might get there. + -## History +## License -A prior incarnation used a custom cross-API hal. An archive of this version can be found in the branches [`custom-hal-archive-with-shaders`] and [`custom-hal-archive`]. +Licensed under either of -## License and contributions. +- Apache License, Version 2.0 + ([LICENSE-APACHE](LICENSE-APACHE) or ) +- MIT license + ([LICENSE-MIT](LICENSE-MIT) or ) -The piet-gpu project is dual-licensed under both [Apache 2.0](LICENSE-APACHE) and [MIT](LICENSE_MIT) licenses. +at your option. -In addition, the shaders are provided under the terms of the [Unlicense](./shader/UNLICENSE). The intent is for this research to be used in as broad a context as possible. +In addition, all files in the [`shader`](shader) directory and subdirectories thereof are alternatively +licensed under the Unlicense ([shader/UNLICENSE](shader/UNLICENSE) or ). +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 dx12 backend was adapted from piet-dx12 by Brian Merchant. +The files in subdirectories of the [`examples/assets`](examples/assets) directory are licensed solely under +their respective licenses, available in the `LICENSE` file in their directories. + +## Contribution 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. + [piet-metal]: https://github.com/linebender/piet-metal [direct2d]: https://docs.microsoft.com/en-us/windows/win32/direct2d/direct2d-portal [`wgpu`]: https://wgpu.rs/ @@ -49,16 +147,8 @@ Contributions are welcome by pull request. The [Rust code of conduct] applies. [rust code of conduct]: https://www.rust-lang.org/policies/code-of-conduct [`custom-hal-archive-with-shaders`]: https://github.com/linebender/piet-gpu/tree/custom-hal-archive-with-shaders [`custom-hal-archive`]: https://github.com/linebender/piet-gpu/tree/custom-hal-archive - - -# vello - -This crate is currently a highly experimental proof-of-concept port of the piet-gpu renderer to the WGSL shader language, so it could be run on WebGPU. Depending on how well it works out, it may become the authoritative source for piet-gpu. - -The shaders are actually handlebars templates over WGSL, as it's important to share common data structures; it's likely we'll use the template mechanism to supply various parameters which are not supported by the WGSL language, for example to specify grayscale or RGBA buffer output for fine rasterization. - -This crate also uses a very different approach to the GPU abstraction than piet-gpu. That is essentially a HAL that supports an immediate mode approach to creating resources and submitting commands. Here, we generate a `Recording`, which is basically a simple value type, then an `Engine` plays that recording to the actual GPU. 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. - -Scene encoding is shared with piet-gpu, and currently uses piet-scene in the same repo with no changes. - -This module is still an experimental work in progress. Contributions can be made with the same policy as the root repo, but expect things to change quickly. +[piet-dx12]: https://github.com/bzm3r/piet-dx12 +[GhostScript tiger]: https://commons.wikimedia.org/wiki/File:Ghostscript_Tiger.svg +[winit]: https://github.com/rust-windowing/winit +[Bevy]: https://bevyengine.org/ +[`wgsl-analyzer`]: https://marketplace.visualstudio.com/items?itemName=wgsl-analyzer.wgsl-analyzer diff --git a/examples/assets/third-party/LICENSE.txt b/examples/assets/roboto/LICENSE.txt similarity index 100% rename from examples/assets/third-party/LICENSE.txt rename to examples/assets/roboto/LICENSE.txt diff --git a/examples/assets/third-party/Roboto-Regular.ttf b/examples/assets/roboto/Roboto-Regular.ttf similarity index 100% rename from examples/assets/third-party/Roboto-Regular.ttf rename to examples/assets/roboto/Roboto-Regular.ttf diff --git a/examples/with_winit/src/simple_text.rs b/examples/with_winit/src/simple_text.rs index a7d1827..86da701 100644 --- a/examples/with_winit/src/simple_text.rs +++ b/examples/with_winit/src/simple_text.rs @@ -27,7 +27,7 @@ use vello::{ // This is very much a hack to get things working. // On Windows, can set this to "c:\\Windows\\Fonts\\seguiemj.ttf" to get color emoji -const FONT_DATA: &[u8] = include_bytes!("../../assets/third-party/Roboto-Regular.ttf"); +const FONT_DATA: &[u8] = include_bytes!("../../assets/roboto/Roboto-Regular.ttf"); pub struct SimpleText { gcx: GlyphContext,