simbleau
commented
6 months ago This is a great recap and summary of the architecture, but we should also talk about how we will make the documentation available to the users and help them accomplish their tasks.
"Who is our customer?" for this documentation.
I 100% agree the blogs are not good documentation. That being said, I also want to be candid and say probably 1% of people using Vello have a desire to contribute. Most people want to use vello, not learn it. Similarly, those needing to use wgpu/vulkan don't care about how the graphics calls translate to machine instructions.
These areas of focus seem more interesting:
- A tutorial series like https://sotrh.github.io/learn-wgpu/
- A TLDR section on architecture (similarly, why Vello is probably your best choice right now)
- Dedicated section to the cases like SVG/Bevy/Lottie
- A pull request template
- A contributing guide
I don't think it would be too hard to get off the ground with something like docusaurus. I'm happy to contribute to the docs as well
PoignardAzur
nicoburns
armansito
DJMcNab
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 and the docs page listing Raph's blog articles.
The diagram
I've written my feedback to the diagram in a zulip thread:
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:
And these articles about GPU compute:
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:
My ideal documentation
Ideally, I'd like our documentation to include:
Obviously this is easier said than done.
Any incremental work that gets our documentation closer to that state would be very welcome.