From db49bed50c7e8f28a13090b2b15bd7f25d858f11 Mon Sep 17 00:00:00 2001 From: Raph Levien Date: Wed, 13 Jul 2022 12:07:55 -0700 Subject: [PATCH] Doc improvements Explain the shader compilation approach. Also add links while I'm at it. --- README.md | 3 ++- doc/blogs.md | 7 +++++++ doc/shader_compilation.md | 25 +++++++++++++++++++++++++ piet-gpu/Cargo.toml | 1 + 4 files changed, 35 insertions(+), 1 deletion(-) create mode 100644 doc/shader_compilation.md diff --git a/README.md b/README.md index aec92ba..a239c91 100644 --- a/README.md +++ b/README.md @@ -42,7 +42,7 @@ In addition, the shaders are provided under the terms of the [Unlicense]. The in The dx12 backend was adapted from piet-dx12 by Brian Merchant. -Contributions are welcome by pull request. The [Rust code of conduct] applies. +Contributions are welcome by pull request. The [Rust code of conduct] applies. Pull requests should be against the `dev` branch; see [shader_compilation.md] for explanation and details. [piet-metal]: https://github.com/linebender/piet-metal [Direct2D]: https://docs.microsoft.com/en-us/windows/win32/direct2d/direct2d-portal @@ -53,3 +53,4 @@ Contributions are welcome by pull request. The [Rust code of conduct] applies. [Druid]: https://github.com/linebender/druid [Unlicense]: https://unlicense.org/ [Rust code of conduct]: https://www.rust-lang.org/policies/code-of-conduct +[shader_compilation.md]: ./doc/shader_compilation.md diff --git a/doc/blogs.md b/doc/blogs.md index eff8fed..2eb1c8d 100644 --- a/doc/blogs.md +++ b/doc/blogs.md @@ -2,6 +2,7 @@ Much of the research progress on piet-gpu is documented in blog entries. Here are the most relevant: +* [piet-gpu progress: clipping](https://raphlinus.github.io/rust/graphics/gpu/2022/02/24/piet-gpu-clipping.html), Feb 24, 2022 * [Fast 2D rendering on GPU](https://raphlinus.github.io/rust/graphics/gpu/2020/06/13/fast-2d-rendering.html), Jun 13, 2020 * [A sort-middle architecture for 2D graphics](https://raphlinus.github.io/rust/graphics/gpu/2020/06/12/sort-middle.html), Jun 12, 2020 * [piet-gpu progress report](https://raphlinus.github.io/rust/graphics/gpu/2020/06/01/piet-gpu-progress.html), Jun 1, 2020 @@ -9,6 +10,12 @@ Much of the research progress on piet-gpu is documented in blog entries. Here ar There are some posts more general to GPU compute programming that might be of some interest: +* [The stack monoid revisited](https://raphlinus.github.io/gpu/2021/05/13/stack-monoid-revisited.html), May 13, 2021 +* [Prefix sum on portable compute shaders](https://raphlinus.github.io/gpu/2021/11/17/prefix-sum-portable.html), Nov 17, 2021 * [The stack monoid](https://raphlinus.github.io/gpu/2020/09/05/stack-monoid.html), Sep 5, 2020 * [Prefix sum on Vulkan](https://raphlinus.github.io/gpu/2020/04/30/prefix-sum.html), Apr 30, 2020 * [GPU resources](https://raphlinus.github.io/gpu/2020/02/12/gpu-resources.html), Feb 12, 2020 + +A paper, [Fast GPU bounding boxes on tree-structured scenes], describes the algorithm to compute bounding boxes for clipping and blending. + +[Fast GPU bounding boxes on tree-structured scenes]: https://arxiv.org/abs/2205.11659 \ No newline at end of file diff --git a/doc/shader_compilation.md b/doc/shader_compilation.md new file mode 100644 index 0000000..8dac2fa --- /dev/null +++ b/doc/shader_compilation.md @@ -0,0 +1,25 @@ +# How shader compilation works + +We use git branches to support shader compilation in the cloud. The `dev` branch contains only shader source files (in GLSL format), while the `main` branch contains generated shaders. On every push to the `dev` branch, a GitHub action runs which compiles the shaders and pushes those to `main`. + +Thus, you can run piet-gpu from the `main` branch without requiring any shader compilation tools. Also, the `dev` branch has a relatively clean history, and PRs can be made against it without having to worry about merge conflicts in the generated shader files. + +If you do want to make changes to the shaders, you'll need some tools installed: + +* [Ninja] +* [Vulkan SDK] (mostly for glslangValidate, spirv-cross) +* [DirectX Shader Compiler][DXC] + +The GitHub action runs on Windows so the DXC signing can succeed (note that [hassle-rs] may provide an alternate solution). We currently only compile to MSL on Metal, not AIR, due to tooling friction. The Metal shader compiler is available on Windows, but a barrier to running in CI is that downloading it appears to require an Apple account. Longer term we will want to figure out a solution to this, because the piet-gpu vision involves ahead-of-time compilation of shaders as much as possible. + +Right now the scripts for compiling shaders are done in hand-written ninja files. This is likely to change, as the number of permutations will increase, and we also may want access to metadata from the shader compilation process. + +Following a few general rules should hopefully keep things running smoothly: + +* Prepare all PRs against the `dev` branch, not `main`. +* Don't commit generated shaders in the PR. +* Don't commit directly to `main`, it will cause divergence. + +[Ninja]: https://ninja-build.org/ +[Vulkan SDK]: https://www.lunarg.com/vulkan-sdk/ +[DXC]: https://github.com/microsoft/DirectXShaderCompiler diff --git a/piet-gpu/Cargo.toml b/piet-gpu/Cargo.toml index faaffbd..4c63760 100644 --- a/piet-gpu/Cargo.toml +++ b/piet-gpu/Cargo.toml @@ -3,6 +3,7 @@ name = "piet-gpu" version = "0.1.0" authors = ["Raph Levien "] description = "A compute-centric GPU 2D renderer." +readme = "README.md" license = "MIT/Apache-2.0" edition = "2018"