Tracking issue: Documenting Vello's architecture

Nobody has claimed this yet.

In the process of the 0.1 release, I've written an ARCHITECTURE.md document. However, while that document lists files and resources, it only skims the *conceptual* architecture of Vello.

Right now, as far as I'm aware, the best resources for learning about Vello (besides reading the code and asking questions on Zulip) are [the Vello pipeline diagram](https://raw.githubusercontent.com/linebender/vello/vello-diagram/doc/images/vello-diagram.svg) and [the docs page listing Raph's blog articles](https://github.com/linebender/vello/blob/5d30f52625970f700b3e738b60796fa1eaeae3b1/doc/blogs.md).

## The diagram

I've written my feedback to the diagram in [a zulip thread](https://xi.zulipchat.com/#narrow/stream/197075-gpu/topic/vello.20architecture.20diagram):

> - The diagram is *very* arrow-rich, which makes it hard to read. Any other changes should move towards making arrows fewer and shorter.
> - The bump-allocation buffer symbols could probably be put directly into their respective "yellow box". At glance, only two of them are shared between multiple passes. For these you probably want to duplicate the box but have a dashed line between the two to remind the buffer is the same.
> - The diagram is fairly horizontal, but you can expect it to show up in pages which will have a vertical layout. As such, it would probably be better to have the difference "stages" to be in a strict vertical order (Inputs -> Input Processing -> Binning -> Coarse Rasterization -> Segment Sort -> Fine Rasterization -> PostScript tiger).
> - All boxes should be order in such away that arrows always flow to the right and down. Right now, "Path", "Tile" and "SegmentCount" have left-flowing arrows, which makes the flow hard to follow.
> - There should be a legend indicating what the different color boxes mean.

I think this feedback still stands.

Overall, a better architecture diagram could be a great launching point for a documentation effort; but of course, that's easier said than done.

## The blog articles

Our doc page mentions these articles about Vello:

> * [Requiem for piet-gpu-hal](https://raphlinus.github.io/rust/gpu/2023/01/07/requiem-piet-gpu-hal.html)
> * [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
> * [2D Graphics on Modern GPU](https://raphlinus.github.io/rust/graphics/gpu/2019/05/08/modern-2d.html), May 8, 2019

And these articles about GPU compute:

> * [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

My recap of the Vello articles

In chronological order:

- **2D Graphics on Modern GPU**
- Describes how a scene graph can be seen as a DAG of transforms, paths and operations.
- Describes an early pipeline of "tiling" -> "rendering"
- Covers general compute-related concepts; eg serialization formats, parallel culling, what "GPU threads" mean, etc.

- **piet-gpu progress report**
- Introduces piet-gpu-hal.
- Discusses the notion of render layers, and the introduces the notion of a reusable chunk of scene description (what later became SceneFragment).
- Discusses notions of performance, and the design goal of moving as much work as possible onto the GPU.

- **A sort-middle architecture for 2D graphics**
- Introduces the idea that prefix sum can be used for graphics rendering.
- Describes an architecture where canvas operations are represented as a single stream, where the monoid is the canvas state that the operation modifies.
- Describes the general pipeline of "binning" -> "coarse rasterization into tiles" -> "sort each tile" -> "fine rasterization". (Though it's rather light on details about when/how sorting *actually* happens)

- **Fast 2D rendering on GPU**
- Goes into more detail on the sort-middle pipeline.
- Mentions backdrop processing and curve flattening.
- Mentions better performance numbers.

- **piet-gpu progress: clipping**
- Describes the process of clipping in vector graphics; mentions the strategy of clipping as a Porter-Duff op.
- Describes the fine rasterization stage of the pipeline.
- Introduces the idea of using the stack monoid for bbox intersection.
- Explains how operations can be encoded as multiple compact streams.

- **Requiem for piet-gpu-hal**
- Goes over the pains of interoperability
- Mentions the pain points and potential future improvements of WebGPU.

My recap of the posts on GPU compute

In chronological order:

- **Prefix sum on Vulkan**
- Goes over the Vulkan memory model.
- Talks about the performance model as it relates to subgroup size.
- Lists portability considerations and abstraction layers

- **The stack monoid**
- Describes a first version of The Stack Monoid where the payload is an actual stack

- **The stack monoid revisited**
- Describes an in-place version of the stack monoid where the payload is a reduction of all the stack elements (eg for a clip stack, the intersection of all the clip rects).

- **Prefix sum on portable compute shaders**
- Lays out a progress report of trying to implement decoupled lookback in Metal.
- Explains how Metal lacks the necessary synchronization primitives to implement it, therefore WebGPU lacks them too.
- Explains the associated outreach work (eg filing issues with the WebGPU spec so that it doesn't falsely advertise support for these synchronization primitives).

### These blog posts aren't great documentation

A lot of these articles explore Vulkan, Metal, memory models, the limitations of such and such platform, etc, in a messy way. They overlap and cover designs we moved on from. They reflect Raph's thought process as he was trying different things in sequence and recording why they didn't work, and his understanding solidified.

In particular, there are three areas where these articles are not ideal as documentation:

- **The Vello encoding has evolved a lot** since the first articles were written. The "scene graph as a literal graph of paths and transforms" concept has been dropped. The single-stream approach has been replaced by packed multiplexed streams.
- **The descriptions of individual pipeline steps are confusing** for novices. I've read the sort-middle article at least five times and I'm still not clear what is being sorted. This isn't a dig at Raph: explaining this stuff is hard, and it requires *a lot* of visual aids. Making these visual-aids is time-consuming and we don't have great tools to produce them.
- **These articles focus a lot on historical info:** Vulkan, Metal, hardware abstraction layers, decoupled-lookback, whether we want to adopt WebGPU, why we don't want to adopt WebGPU yet, etc. Now that we've adopted WebGPU and decided we'll do without decoupled-lookback for now, we don't need to dump all these details on newcomers. We still want to say "here's all the things we considered and why we can't get them on WebGPU" just not as the primary focus.

## My ideal documentation

Ideally, I'd like our documentation to include:

- An explainer on prefix sum. (Which doesn't mention decoupled lookback.)
- An explainer on prefix sum with the stack monoid.
- The pipeline diagram.
- A short article describing each stage of the pipeline, with visual aids.
- An overview article with a links to each article above and a summary of their content.

Obviously this is easier said than done.

Any incremental work that gets our documentation closer to that state would be very welcome.

Start with ARCHITECTURE.md, the existing pipeline diagram, and doc/blogs.md, then compare those resources with the current Vello pipeline. Use the linked Zulip feedback to identify diagram improvements and organize incremental explainers for the stages, prefix sum, and stack monoid. Done means a clearer, current architecture documentation set with an overview linking the new material.

Written by the indexing model from the issue text.