Fix doc problems

Author: PoignardAzur

.clippy.toml

@@ -1 +1 @@
-doc-valid-idents = ["WebGPU", ".."]
+doc-valid-idents = ["WebGPU", "PostScript", ".."]

ARCHITECTURE.md

@@ -1,47 +1,55 @@
 
 # Architecture
 
-This document should be update semi-regularly. Feel free to open an issue if it hasn't been updated in a few years.
+This document should be updated semi-regularly. Feel free to open an issue if it hasn't been updated in more than a year.
 
 ## Goals
 
 The major goal of Vello is to provide a high quality GPU accelerated renderer suitable for a range of 2D graphics applications, including rendering for GUI applications, creative tools, and scientific visualization.
-The [roadmap for 2023](doc/roadmap_2023.md) explains the goals and plans for the next few months of development
 
 Vello emerges from being a research project, which attempts to answer these hypotheses:
 
 - To what extent is a compute-centered approach better than rasterization ([Direct2D])?
 - To what extent do "advanced" GPU features (subgroups, descriptor arrays, device-scoped barriers) help?
 - Can we improve quality and extend the imaging model in useful ways?
 
-Another goal of the overall project is to explain how the renderer is built, and to advance the state of building applications on GPU compute shaders more generally. 
+Another goal of the overall project is to explain how the renderer is built, and to advance the state of building applications on GPU compute shaders more generally.
 Much of the progress on Vello is documented in blog entries.
 See [doc/blogs.md](doc/blogs.md) for pointers to those.
 
 
+## Roadmap
+
+The [roadmap for 2023](doc/roadmap_2023.md) is still largely applicable.
+The "Semi-stable encoding format" section and most of the "CPU fallback" section can be considered implemented.
+
+Our current priority is to fill in missing features and to fix rendering artifacts, so that Vello can reach feature parity with other 2D graphics engines.
+
+
 ## File structure
 
 The repository is structured as such:
 
 - `crates/`
   - `encoding/` - Types that represent the data that needs to be rendered.
-  - `shaders/` - Infrastructure to compile pipelines and shaders; see "Shader templating".
+  - `shaders/` - Infrastructure to compile pipelines and shaders; see "Shader templating". Note that the `vello` crate doesn't currently import this crate (see #467).
   - `tests/` - Helper code for writing tests; current has a single smoke test and not much else.
 - `doc/` - Various documents detailing the vision for Vello as it was developed. This directory should probably be refactored away; adding to it not recommended.
 - `examples/` - Example projects using Vello. Each example is its own crate, with its own dependencies. The simplest example is the `shapes` one.
-- `integrations/vello_svg` - An SVG rendered based on vello and usvg. Used in examples. May be moved to `crates/` in the future.
-- `shader/` - This is where the magic happens. WGSL shaders that define the compute operations (mostly variations of prefix scan) that vello does to render a scene.
+- `integrations/vello_svg` - An SVG rendered based on Vello and usvg. Used in examples. May be moved to `crates/` in the future.
+- `shader/` - This is where the magic happens. WGSL shaders that define the compute operations (often variations of prefix sum) that Vello does to render a scene.
   - `shared/` - Shared types, functions and constants included in other shaders through non-standard `#import` preprocessor directives (see "Shader templating").
-- `src/` - Code for the main Vello crate.
+- `src/` - Code for the main `vello` crate.
   - `shaders/` - Same as `crates/shaders/` above. The duplication should eventually be removed (see #467).
-  - `cpu_shader/` - Function that perform the same work as their equivalently-named WGSL shaders for the CPU fallbacks. The name is a bit loose, they're not "shaders" in any real sense.
+  - `cpu_shader/` - Functions that perform the same work as their equivalently-named WGSL shaders for the CPU fallbacks. The name is a bit loose; they're "shaders" in the sense that they work on resource bindings with the exact same layout as actual GPU shaders.
 
 
 ## Shader templating
 
-We implement a limited, simple preprocessor for our shaders, as wgsl has insufficient code-sharing for our needs.
+WGSL has no meta-programming support, which limits code-sharing.
+We use a strategy common to many projects (eg Bevy) which is to implement a limited, simple preprocessor for our shaders.
 
-This implements only classes of statements.
+This preprocessor implements the following directives:
 
 1. `import`, which imports from `shader/shared`
 2. `ifdef`, `ifndef`, `else` and `endif`, as standard.
@@ -55,6 +63,11 @@ Note that new imports must currently be added to `.vscode/settings.json` for thi
 `wgsl-analyzer` only supports imports in very few syntactic locations, so we limit their use to these places.
 
 
+## Path encoding
+
+See [Path segment encoding](./doc/pathseg.md) document.
+
+
 ## Intermediary layers
 
 There are multiple layers of separation between "draw shape in Scene" and "commands are sent to wgpu":
@@ -73,7 +86,7 @@ The code in `cpu_shader/*.rs` and `cpu_dispatch.rs` provides *some* support for
 
 - It's called through WgpuEngine, so the dependency on wgpu is still there.
 - Fine rasterization (the part at the end that puts pixels on screen) doesn't work in CPU yet (see #386).
-- Every single wgsl shader needs a CPU equivalent, which is pretty cumbersome.
+- Every single WGSL shader needs a CPU equivalent, which is pretty cumbersome.
 
 Still, it's useful for testing and debugging.
 

README.md

@@ -14,8 +14,8 @@
 
 </div>
 
-Vello is an experimental 2d graphics rendering engine written in Rust, using [`wgpu`].
-It efficiently draws large 2d scenes with interactive or near-interactive performance.
+Vello is an experimental 2D graphics rendering engine written in Rust, with a focus on GPU compute.
+It can draw large 2D scenes with interactive or near-interactive performance, using [`wgpu`] for GPU access.
 
 Quickstart to run an example program:
 ```shell
@@ -24,31 +24,39 @@ cargo run -p with_winit
 
 ![image](https://github.com/linebender/vello/assets/8573618/cc2b742e-2135-4b70-8051-c49aeddb5d19)
 
-It is used as the rendering backend for [Xilem], a native Rust GUI toolkit.
+It is used as the rendering backend for [Xilem], a Rust GUI toolkit.
 
+> [!WARNING]
+> Vello can currently be considered in an alpha state. In particular, we're still working on the following:
+>
+> - [Major rendering artifacts when drawing more than 64k objects](https://github.com/linebender/vello/issues/334).
+> - [Implementing blur and filter effects](https://github.com/linebender/vello/issues/476).
+> - [Properly implenting strokes](https://github.com/linebender/vello/issues/303) and [supporting all SVG stroke caps](https://github.com/linebender/vello/issues/280).
+> - [Conflations artifacts](https://github.com/linebender/vello/issues/49).
+> - [GPU memory allocation strategy](https://github.com/linebender/vello/issues/366)
 
 ## Motivation
 
-Vello is meant to fill the same place in the graphics stack as other vector graphics renderers like [Skia](https://skia.org/), [Cairo](https://www.cairographics.org/), and its predecessor project [Piet](https://www.cairographics.org/).
-On a basic level, that means it provides tools to render shapes, images, gradients, texts, etc, using a PostScript-inspired API, the same that powers SVG files and [the browser `<canvas>` element](https://developer.mozilla.org/en-US/docs/Web/API/CanvasRenderingContext2D).
+Vello is meant to fill the same place in the graphics stack as other vector graphics renderers like [Skia](https://skia.org/), [Cairo](https://www.cairographics.org/), and its predecessor project [Piet](https://github.com/linebender/piet).
+On a basic level, that means it provides tools to render shapes, images, gradients, text, etc, using a PostScript-inspired API, the same that powers SVG files and [the browser `<canvas>` element](https://developer.mozilla.org/en-US/docs/Web/API/CanvasRenderingContext2D).
 
 Vello's selling point is that it gets better performance than other renderers by better leveraging the GPU.
 In traditional PostScript renderers, some steps of the render process like sorting and clipping either need to be handled in the CPU or done through the use of intermediary textures.
-Vello avoids this by using prefix-scan algorithms to parallelize work that usually needs to happen in sequence, so that work can be offloaded to the GPU with minimal use of temporary buffers.
+Vello avoids this by using prefix-sum algorithms to parallelize work that usually needs to happen in sequence, so that work can be offloaded to the GPU with minimal use of temporary buffers.
 
 
 ## Getting started
 
 Vello is meant to be integrated deep in UI render stacks.
-While drawing in a Vello scene is easy, actually rendering that scene to a surface setting up a wgpu context, which is a non-trivial task.
+While drawing in a Vello scene is easy, actually rendering that scene to a surface requires setting up a wgpu context, which is a non-trivial task.
 
 To use Vello as the renderer for your PDF reader / GUI toolkit / etc, your code will have to look roughly like this:
 
 ```rust
 // Initialize wgpu and get handles
 let device: wgpu::Device = ...;
 let queue: wgpu::Queue = ...;
-let render_surface: wpg::RenderSurface<'_> = ...;
+let surface: wpgu::Surface<'_> = ...;
 let texture_format: wgpu::TextureFormat = ...;
 let mut renderer = Renderer::new(
       &device,
@@ -62,24 +70,22 @@ let mut renderer = Renderer::new(
 
 // Create scene and draw stuff in it
 let mut scene = vello::Scene::new();
-
-let circle = vello::Circle::new((420.0, 200.0), 120.0);
-let circle_fill_color = vello::Color::rgb(0.9529, 0.5451, 0.6588);
 scene.fill(
    vello::peniko::Fill::NonZero,
    vello::Affine::IDENTITY,
-   circle_fill_color,
+   vello::Color::rgb8(242, 140, 168),
    None,
-   &circle,
+   &vello::Circle::new((420.0, 200.0), 120.0),
 );
 
+// Draw more stuff
 scene.push_layer(...);
 scene.fill(...);
 scene.stroke(...);
 scene.pop_layer(...);
 
 // Render to your window/buffer/etc.
-let surface_texture = render_state.surface.get_current_texture()
+let surface_texture = surface.get_current_texture()
    .expect("failed to get surface texture");
 vello::block_on_wgpu(
       &device,
@@ -210,7 +216,7 @@ 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.
+licensed as noted in the "License" section, without any additional terms or conditions.
 
 ## History
 

src/lib.rs

@@ -26,11 +26,11 @@
 //!
 //! To use Vello as the renderer for your PDF reader / GUI toolkit / etc, your code will have to look roughly like this:
 //!
-//! ```rust
+//! ```ignore
 //! // Initialize wgpu and get handles
 //! let device: wgpu::Device = ...;
 //! let queue: wgpu::Queue = ...;
-//! let render_surface: wpg::RenderSurface<'_> = ...;
+//! let surface: wpgu::Surface<'_> = ...;
 //! let texture_format: wgpu::TextureFormat = ...;
 //! let mut renderer = Renderer::new(
 //!       &device,
@@ -44,24 +44,22 @@
 //!
 //! // Create scene and draw stuff in it
 //! let mut scene = vello::Scene::new();
-//!
-//! let circle = vello::Circle::new((420.0, 200.0), 120.0);
-//! let circle_fill_color = vello::Color::rgb(0.9529, 0.5451, 0.6588);
 //! scene.fill(
 //!    vello::peniko::Fill::NonZero,
 //!    vello::Affine::IDENTITY,
-//!    circle_fill_color,
+//!    vello::Color::rgb8(242, 140, 168),
 //!    None,
-//!    &circle,
+//!    &vello::Circle::new((420.0, 200.0), 120.0),
 //! );
 //!
+//! // Draw more stuff
 //! scene.push_layer(...);
 //! scene.fill(...);
 //! scene.stroke(...);
 //! scene.pop_layer(...);
 //!
 //! // Render to your window/buffer/etc.
-//! let surface_texture = render_state.surface.get_current_texture()
+//! let surface_texture = surface.get_current_texture()
 //!    .expect("failed to get surface texture");
 //! vello::block_on_wgpu(
 //!       &device,

src/scene.rs

@@ -54,7 +54,7 @@ impl Scene {
         self.encoding
             .encode_transform(Transform::from_kurbo(&transform));
         self.encoding.encode_fill_style(Fill::NonZero);
-        if !self.encoding.encode_shape(shape, true) {
+        if !self.encoding.encode_shape(clip, true) {
             // If the layer shape is invalid, encode a valid empty path. This suppresses
             // all drawing until the layer is popped.
             self.encoding