Debug and Validation Layers

examples/headless/src/main.rs

@@ -139,6 +139,7 @@ async fn render(mut scenes: SceneSet, index: usize, args: &Args) -> Result<()> {
         width,
         height,
         antialiasing_method: vello::AaConfig::Area,
+        debug: vello::DebugLayers::none(),
     };
     let mut scene = Scene::new();
     scene.append(&fragment, Some(transform));

examples/simple/src/main.rs

@@ -7,7 +7,7 @@ use std::sync::Arc;
 use vello::kurbo::{Affine, Circle, Ellipse, Line, RoundedRect, Stroke};
 use vello::peniko::Color;
 use vello::util::{RenderContext, RenderSurface};
-use vello::{AaConfig, Renderer, RendererOptions, Scene};
+use vello::{AaConfig, DebugLayers, Renderer, RendererOptions, Scene};
 use winit::application::ApplicationHandler;
 use winit::dpi::LogicalSize;
 use winit::event::*;
@@ -151,6 +151,7 @@ impl<'s> ApplicationHandler for SimpleVelloApp<'s> {
                             width,
                             height,
                             antialiasing_method: AaConfig::Msaa16,
+                            debug: DebugLayers::none(),
                         },
                     )
                     .expect("failed to render to surface");

examples/with_winit/Cargo.toml

@@ -25,8 +25,9 @@ workspace = true
 name = "with_winit_bin"
 path = "src/main.rs"
 
+
 [dependencies]
-vello = { workspace = true, features = ["buffer_labels"] }
+vello = { workspace = true, features = ["buffer_labels", "debug_layers"] }
 scenes = { workspace = true }
 
 anyhow = { workspace = true }

examples/with_winit/src/lib.rs

@@ -162,6 +162,8 @@ struct VelloApp<'s> {
 
     prev_scene_ix: i32,
     modifiers: ModifiersState,
+
+    debug: vello::DebugLayers,
 }
 
 impl<'s> ApplicationHandler<UserEvent> for VelloApp<'s> {
@@ -329,6 +331,27 @@ impl<'s> ApplicationHandler<UserEvent> for VelloApp<'s> {
                                         },
                                     );
                                 }
+                                debug_layer @ ("1" | "2" | "3" | "4") => {
+                                    match debug_layer {
+                                        "1" => {
+                                            self.debug.toggle(vello::DebugLayers::BOUNDING_BOXES);
+                                        }
+                                        "2" => {
+                                            self.debug
+                                                .toggle(vello::DebugLayers::LINESOUP_SEGMENTS);
+                                        }
+                                        "3" => {
+                                            self.debug.toggle(vello::DebugLayers::LINESOUP_POINTS);
+                                        }
+                                        "4" => {
+                                            self.debug.toggle(vello::DebugLayers::VALIDATION);
+                                        }
+                                        _ => unreachable!(),
+                                    }
+                                    if !self.debug.is_empty() && !self.async_pipeline {
+                                        log::warn!("Debug Layers won't work without using `--async-pipeline`. Requested {:?}", self.debug);
+                                    }
+                                }
                                 _ => {}
                             }
                         }
@@ -464,6 +487,7 @@ impl<'s> ApplicationHandler<UserEvent> for VelloApp<'s> {
                     width,
                     height,
                     antialiasing_method,
+                    debug: self.debug,
                 };
                 self.scene.reset();
                 let mut transform = self.transform;
@@ -674,6 +698,8 @@ fn run(
         Some(render_state)
     };
 
+    let debug = vello::DebugLayers::none();
+
     let mut app = VelloApp {
         context: render_cx,
         renderers,
@@ -718,6 +744,7 @@ fn run(
         complexity: 0,
         prev_scene_ix: 0,
         modifiers: ModifiersState::default(),
+        debug,
     };
 
     event_loop.run_app(&mut app).expect("run to completion");
@@ -786,6 +813,7 @@ pub fn main() -> anyhow::Result<()> {
     #[cfg(not(target_arch = "wasm32"))]
     env_logger::builder()
         .format_timestamp(Some(env_logger::TimestampPrecision::Millis))
+        .filter_level(log::LevelFilter::Warn)
         .init();
     let args = parse_arguments();
     let scenes = args.args.select_scene_set()?;

vello/Cargo.toml

@@ -18,6 +18,7 @@ default = ["wgpu"]
 bump_estimate = ["vello_encoding/bump_estimate"]
 hot_reload = ["vello_shaders/compile"]
 buffer_labels = []
+debug_layers = []
 wgpu = ["dep:wgpu"]
 wgpu-profiler = ["dep:wgpu-profiler"]
 

vello/src/debug.rs

@@ -0,0 +1,119 @@
+// Copyright 2023 the Vello Authors
+// SPDX-License-Identifier: Apache-2.0 OR MIT
+
+#[cfg(all(feature = "debug_layers", feature = "wgpu"))]
+mod renderer;
+#[cfg(all(feature = "debug_layers", feature = "wgpu"))]
+mod validate;
+
+use std::fmt::Debug;
+
+#[cfg(all(feature = "debug_layers", feature = "wgpu"))]
+pub(crate) use renderer::*;
+
+/// Bitflags for enabled debug operations.
+///
+/// Currently, all layers additionally require the `debug_layers` feature.
+#[derive(Copy, Clone)]
+pub struct DebugLayers(u8);
+
+impl Debug for DebugLayers {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        let mut tuple = f.debug_tuple("DebugLayers");
+        if self.contains(Self::BOUNDING_BOXES) {
+            tuple.field(&"BOUNDING_BOXES");
+        }
+        if self.contains(Self::LINESOUP_SEGMENTS) {
+            tuple.field(&"LINESOUP_SEGMENTS");
+        }
+        if self.contains(Self::LINESOUP_POINTS) {
+            tuple.field(&"LINESOUP_POINTS");
+        }
+        if self.contains(Self::VALIDATION) {
+            tuple.field(&"VALIDATION");
+        }
+
+        tuple.finish()
+    }
+}
+
+// TODO: Currently all layers require read-back of the BumpAllocators buffer. This isn't strictly
+// necessary for layers other than `VALIDATION`. The debug visualizations use the bump buffer only
+// to obtain various instance counts for draws and these could instead get written out to an
+// indirect draw buffer. OTOH `VALIDATION` should always require readback since we want to be able
+// to run the same CPU-side tests for both CPU and GPU shaders.
+impl DebugLayers {
+    /// Visualize the bounding box of every path.
+    /// Requires the `debug_layers` feature.
+    pub const BOUNDING_BOXES: DebugLayers = DebugLayers(1 << 0);
+
+    /// Visualize the post-flattening line segments using line primitives.
+    /// Requires the `debug_layers` feature.
+    pub const LINESOUP_SEGMENTS: DebugLayers = DebugLayers(1 << 1);
+
+    /// Visualize the post-flattening line endpoints.
+    /// Requires the `debug_layers` feature.
+    pub const LINESOUP_POINTS: DebugLayers = DebugLayers(1 << 2);
+
+    /// Enable validation of internal buffer contents and visualize errors. Validation tests are
+    /// run on the CPU and require buffer contents to be read-back.
+    ///
+    /// Supported validation tests:
+    ///
+    ///    - Watertightness: validate that every line segment within a path is connected without
+    ///      any gaps. Line endpoints that don't precisely overlap another endpoint get visualized
+    ///      as red circles and logged to stderr.
+    ///
+    /// Requires the `debug_layers` feature.
+    pub const VALIDATION: DebugLayers = DebugLayers(1 << 3);
+
+    /// Construct a `DebugLayers` from the raw bits.
+    pub const fn from_bits(bits: u8) -> Self {
+        Self(bits)
+    }
+
+    /// Get the raw representation of this value.
+    pub const fn bits(self) -> u8 {
+        self.0
+    }
+
+    /// A `DebugLayers` with no layers enabled.
+    pub const fn none() -> Self {
+        Self(0)
+    }
+
+    /// A `DebugLayers` with all layers enabled.
+    pub const fn all() -> Self {
+        // Custom BitOr is not const, so need to manipulate the inner value here
+        Self(
+            Self::BOUNDING_BOXES.0
+                | Self::LINESOUP_SEGMENTS.0
+                | Self::LINESOUP_POINTS.0
+                | Self::VALIDATION.0,
+        )
+    }
+
+    /// True if this `DebugLayers` has no layers enabled.
+    pub const fn is_empty(self) -> bool {
+        self.0 == 0
+    }
+
+    /// Determine whether `self` is a superset of `mask`.
+    pub const fn contains(self, mask: DebugLayers) -> bool {
+        self.0 & mask.0 == mask.0
+    }
+
+    /// Toggle the value of the layers specified in mask.
+    pub fn toggle(&mut self, mask: DebugLayers) {
+        self.0 ^= mask.0;
+    }
+}
+
+/// Returns the union of the two input `DebugLayers`.
+impl std::ops::BitOr for DebugLayers {
+    type Output = Self;
+
+    fn bitor(self, rhs: Self) -> Self {
+        Self(self.0 | rhs.0)
+    }
+}