vello_hybrid: Add better statistics for probing (#1779)

This PR adds a convenience method to get some more details about why the
probe exactly failed.

This PR was done with assistance of GPT Sol 5.6

Author: LaurenzV

sparse_strips/vello_common/src/probe.rs

@@ -28,17 +28,17 @@ const CIRCLE_CENTER_OFFSET_X: f64 = 1.5;
 const IMAGE_SOURCE_SIZE: f64 = 5.0;
 const PATH_TOLERANCE: f64 = 0.1;
 
-const ELEMENTS: [ProbeElement; 8] = [
-    ProbeElement::SolidRect,
-    ProbeElement::AlphaBlending,
-    ProbeElement::Gradient,
-    ProbeElement::ImageNearest,
+const ELEMENTS: [ProbeFeature; 8] = [
+    ProbeFeature::SolidRect,
+    ProbeFeature::AlphaBlending,
+    ProbeFeature::Gradient,
+    ProbeFeature::ImageNearest,
     // Temporarily disabled.
-    // ProbeElement::Filter,
-    ProbeElement::ImageBilinear,
-    ProbeElement::OpacityLayer,
-    ProbeElement::Blending,
-    ProbeElement::Transformed,
+    // ProbeFeature::Filter,
+    ProbeFeature::ImageBilinear,
+    ProbeFeature::OpacityLayer,
+    ProbeFeature::Blending,
+    ProbeFeature::Transformed,
 ];
 /// Per-channel absolute tolerance used when comparing probe pixels.
 const CHANNEL_TOLERANCE: u8 = 3;
@@ -63,6 +63,98 @@ pub struct ProbeResult {
     pub actual: ProbeImage,
 }
 
+/// A feature exercised by the renderer probe.
+///
+/// Each discriminant is the stable bit index used by [`ProbeStatistics::difference_mask`].
+/// Existing discriminants must not be changed when features are reordered, disabled, or added.
+#[repr(u8)]
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
+pub enum ProbeFeature {
+    /// Drawing a solid rectangle.
+    SolidRect = 0,
+    /// Alpha blending overlapping shapes.
+    AlphaBlending = 1,
+    /// Drawing a linear gradient.
+    Gradient = 2,
+    /// Drawing an image with nearest-neighbor sampling.
+    ImageNearest = 3,
+    /// Applying a filter effect.
+    Filter = 4,
+    /// Drawing an image with bilinear sampling.
+    ImageBilinear = 5,
+    /// Drawing within a layer with reduced opacity.
+    OpacityLayer = 6,
+    /// Drawing within a layer with a blend mode.
+    Blending = 7,
+    /// Drawing with a non-identity transform.
+    Transformed = 8,
+}
+
+/// Summary of the differences between the expected and actual probe images.
+#[derive(Debug, Clone, Copy, Default, PartialEq, Eq)]
+pub struct ProbeStatistics {
+    /// Number of active features exercised by the probe.
+    pub element_count: u8,
+    /// Width and height of the actual probe image.
+    pub actual_size: (u16, u16),
+    /// Number of pixels whose channels differ by more than the probe tolerance.
+    pub different_pixel_count: u32,
+    /// Largest absolute difference between corresponding red, green, blue, and alpha channels.
+    pub max_channel_discrepancy: [u8; 4],
+    /// Bitmask identifying probe features containing a pixel outside the probe tolerance.
+    ///
+    /// Bit `n` corresponds to the [`ProbeFeature`] whose discriminant is `n`.
+    pub difference_mask: u32,
+}
+
+impl ProbeStatistics {
+    /// Returns whether `feature` contained a pixel outside the probe tolerance.
+    pub fn differs(&self, feature: ProbeFeature) -> bool {
+        self.difference_mask & (1_u32 << feature as u8) != 0
+    }
+}
+
+impl ProbeResult {
+    /// Return the statistics of the probe.
+    pub fn statistics(&self) -> ProbeStatistics {
+        let layout = GridLayout::from_elements(&ELEMENTS);
+        let mut statistics = ProbeStatistics {
+            element_count: ELEMENTS.len() as u8,
+            actual_size: (self.actual.width, self.actual.height),
+            ..Default::default()
+        };
+
+        for (pixel_index, (expected, actual)) in self
+            .expected
+            .data
+            .chunks_exact(4)
+            .zip(self.actual.data.chunks_exact(4))
+            .enumerate()
+        {
+            if expected[3] != 0 || actual[3] != 0 {
+                for (max_discrepancy, (expected, actual)) in statistics
+                    .max_channel_discrepancy
+                    .iter_mut()
+                    .zip(expected.iter().zip(actual))
+                {
+                    *max_discrepancy = (*max_discrepancy).max(expected.abs_diff(*actual));
+                }
+            }
+
+            if !pixels_within_tolerance(expected, actual, CHANNEL_TOLERANCE) {
+                statistics.different_pixel_count += 1;
+
+                let cell_index = layout.cell_index_for_pixel(pixel_index);
+                if let Some(feature) = ELEMENTS.get(cell_index) {
+                    statistics.difference_mask |= 1_u32 << *feature as u8;
+                }
+            }
+        }
+
+        statistics
+    }
+}
+
 /// A probe image stored as RGBA8 bytes.
 #[derive(Debug, Clone)]
 pub struct ProbeImage {
@@ -132,19 +224,6 @@ pub trait ProbeRenderer {
     fn reset_paint_transform(&mut self);
 }
 
-#[derive(Clone, Copy, Debug)]
-enum ProbeElement {
-    SolidRect,
-    Transformed,
-    AlphaBlending,
-    Gradient,
-    ImageNearest,
-    // Filter,
-    ImageBilinear,
-    OpacityLayer,
-    Blending,
-}
-
 #[derive(Clone, Copy, Debug)]
 struct GridLayout {
     columns: usize,
@@ -154,13 +233,13 @@ struct GridLayout {
 }
 
 impl GridLayout {
-    fn from_elements(elements: &[ProbeElement]) -> Self {
+    fn from_elements(elements: &[ProbeFeature]) -> Self {
         let columns = ELEMENTS_PER_ROW.min(elements.len());
         let rows = elements.len().div_ceil(columns);
         let (cell_width, cell_height) = elements
             .iter()
             .copied()
-            .map(ProbeElement::bounds)
+            .map(ProbeFeature::bounds)
             .fold((0.0_f64, 0.0_f64), |(max_w, max_h), (w, h)| {
                 (max_w.max(w), max_h.max(h))
             });
@@ -174,10 +253,10 @@ impl GridLayout {
     }
 
     fn canvas_size(self) -> (u16, u16) {
-        let width = self.columns as f64 * self.cell_width
-            + self.columns.saturating_sub(1) as f64 * ELEMENT_MARGIN;
-        let height = self.rows as f64 * self.cell_height
-            + self.rows.saturating_sub(1) as f64 * ELEMENT_MARGIN;
+        let (cell_stride_x, cell_stride_y) = self.cell_stride();
+        // Margin only exists between cells, so subtract one.
+        let width = self.columns as f64 * cell_stride_x - ELEMENT_MARGIN;
+        let height = self.rows as f64 * cell_stride_y - ELEMENT_MARGIN;
         (width.ceil() as u16, height.ceil() as u16)
     }
 
@@ -186,23 +265,41 @@ impl GridLayout {
         Rect::new(0.0, 0.0, f64::from(width), f64::from(height))
     }
 
+    fn cell_stride(self) -> (f64, f64) {
+        (
+            self.cell_width + ELEMENT_MARGIN,
+            self.cell_height + ELEMENT_MARGIN,
+        )
+    }
+
     fn cell_rect(self, index: usize) -> Rect {
         let column = index % self.columns;
         let row = index / self.columns;
-        let x0 = column as f64 * (self.cell_width + ELEMENT_MARGIN);
-        let y0 = row as f64 * (self.cell_height + ELEMENT_MARGIN);
+        let (cell_stride_x, cell_stride_y) = self.cell_stride();
+        let x0 = column as f64 * cell_stride_x;
+        let y0 = row as f64 * cell_stride_y;
         Rect::new(x0, y0, x0 + self.cell_width, y0 + self.cell_height)
     }
+
+    fn cell_index_for_pixel(self, pixel_index: usize) -> usize {
+        let (cell_stride_x, cell_stride_y) = self.cell_stride();
+        let image_width = usize::from(self.canvas_size().0);
+        let x = pixel_index % image_width;
+        let y = pixel_index / image_width;
+        let column = x / cell_stride_x as usize;
+        let row = y / cell_stride_y as usize;
+        row * self.columns + column
+    }
 }
 
-impl ProbeElement {
+impl ProbeFeature {
     fn bounds(self) -> (f64, f64) {
         let (width, height) = match self {
             Self::SolidRect
             | Self::Gradient
             | Self::ImageNearest
             | Self::ImageBilinear
-            // | Self::Filter
+            | Self::Filter
             | Self::OpacityLayer => (RECT_SIZE, RECT_SIZE),
             Self::Transformed => (
                 RECT_SIZE * core::f64::consts::SQRT_2,
@@ -287,19 +384,19 @@ fn pixels_within_tolerance(expected: &[u8], actual: &[u8], channel_tolerance: u8
 fn draw_probe_element(
     ctx: &mut impl ProbeRenderer,
     cell: Rect,
-    element: ProbeElement,
+    element: ProbeFeature,
     image_nearest: &PaintType,
     image_bilinear: &PaintType,
 ) {
     match element {
-        ProbeElement::SolidRect => {
+        ProbeFeature::SolidRect => {
             ctx.set_paint(css::BLUE.into());
             ctx.fill_rect(&centered_rect(cell, RECT_SIZE, RECT_SIZE));
         }
-        ProbeElement::Transformed => {
+        ProbeFeature::Transformed => {
             draw_transformed_rect(ctx, centered_rect(cell, RECT_SIZE, RECT_SIZE));
         }
-        ProbeElement::AlphaBlending => {
+        ProbeFeature::AlphaBlending => {
             let center = cell.center();
             ctx.set_paint(css::YELLOW.with_alpha(0.5).into());
             ctx.fill_path(
@@ -312,18 +409,18 @@ fn draw_probe_element(
                     .to_path(PATH_TOLERANCE),
             );
         }
-        ProbeElement::Gradient => {
+        ProbeFeature::Gradient => {
             let rect = centered_rect(cell, RECT_SIZE, RECT_SIZE);
             ctx.set_paint(linear_gradient(&rect).into());
             ctx.fill_rect(&rect);
         }
-        ProbeElement::ImageNearest => draw_centered_padded_image(ctx, cell, image_nearest),
-        // ProbeElement::Filter => draw_blurred_rect(ctx, centered_rect(cell, RECT_SIZE, RECT_SIZE)),
-        ProbeElement::ImageBilinear => draw_centered_padded_image(ctx, cell, image_bilinear),
-        ProbeElement::OpacityLayer => {
+        ProbeFeature::ImageNearest => draw_centered_padded_image(ctx, cell, image_nearest),
+        ProbeFeature::Filter => draw_blurred_rect(ctx, centered_rect(cell, RECT_SIZE, RECT_SIZE)),
+        ProbeFeature::ImageBilinear => draw_centered_padded_image(ctx, cell, image_bilinear),
+        ProbeFeature::OpacityLayer => {
             draw_opacity_layer_rect(ctx, centered_rect(cell, RECT_SIZE, RECT_SIZE));
         }
-        ProbeElement::Blending => draw_layered_difference_circles(ctx, cell),
+        ProbeFeature::Blending => draw_layered_difference_circles(ctx, cell),
     }
 }
 
@@ -421,3 +518,71 @@ fn linear_gradient(rect: &Rect) -> Gradient {
         ..Default::default()
     }
 }
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use alloc::vec;
+
+    #[test]
+    fn probe_result_reports_pixel_and_cell_differences() {
+        let (width, height) = canvas_size();
+        let pixel_count = usize::from(width) * usize::from(height);
+        let expected = ProbeImage {
+            width,
+            height,
+            data: vec![255; pixel_count * 4],
+        };
+        let mut actual = expected.clone();
+        let layout = GridLayout::from_elements(&ELEMENTS);
+
+        let set_channel = |actual: &mut ProbeImage, cell_index: usize, channel: usize, value| {
+            let center = layout.cell_rect(cell_index).center();
+            let x = center.x.floor() as usize;
+            let y = center.y.floor() as usize;
+            actual.data[(y * usize::from(width) + x) * 4 + channel] = value;
+        };
+
+        // This stays within the probe tolerance.
+        set_channel(&mut actual, 0, 0, 254);
+
+        set_channel(&mut actual, 1, 0, 249);
+        set_channel(&mut actual, 5, 1, 0);
+        set_channel(&mut actual, 5, 3, 100);
+
+        let result = ProbeResult { expected, actual };
+        let statistics = result.statistics();
+        assert_eq!(
+            statistics,
+            ProbeStatistics {
+                element_count: ELEMENTS.len() as u8,
+                actual_size: (width, height),
+                different_pixel_count: 2,
+                max_channel_discrepancy: [6, 255, 0, 155],
+                difference_mask: (1 << 1) | (1 << 6),
+            }
+        );
+        assert!(statistics.differs(ProbeFeature::AlphaBlending));
+        assert!(statistics.differs(ProbeFeature::OpacityLayer));
+        assert!(!statistics.differs(ProbeFeature::Filter));
+        assert!(!statistics.differs(ProbeFeature::ImageBilinear));
+    }
+
+    #[test]
+    fn probe_statistics_reports_actual_size() {
+        let result = ProbeResult {
+            expected: ProbeImage {
+                width: 1,
+                height: 1,
+                data: vec![0; 4],
+            },
+            actual: ProbeImage {
+                width: 2,
+                height: 1,
+                data: vec![0; 8],
+            },
+        };
+
+        assert_eq!(result.statistics().actual_size, (2, 1));
+    }
+}

sparse_strips/vello_hybrid/src/lib.rs

@@ -94,7 +94,7 @@ pub use render::{AtlasTextureInfo, WebGlAtlasWriter, WebGlRenderer, WebGlTexture
 pub use render::{AtlasWriter, RenderTargetConfig, Renderer, TextureBindings};
 pub use render::{Config, GpuStrip, RenderSize};
 #[cfg(all(feature = "webgl", feature = "probe"))]
-pub use render::{Probe, ProbeResult};
+pub use render::{Probe, ProbeFeature, ProbeResult, ProbeStatistics};
 #[cfg(all(feature = "webgl", feature = "probe"))]
 pub use render::{WebGlPendingProbe, WebGlProbeError, WebGlProbeStatus};
 pub use resources::Resources;

sparse_strips/vello_hybrid/src/render/mod.rs

@@ -21,7 +21,7 @@ pub use common::{Config, GpuStrip, RenderSize};
 #[cfg(all(feature = "webgl", feature = "probe"))]
 pub use probe::{WebGlPendingProbe, WebGlProbeError, WebGlProbeStatus};
 #[cfg(all(feature = "webgl", feature = "probe"))]
-pub use vello_common::probe::{Probe, ProbeResult};
+pub use vello_common::probe::{Probe, ProbeFeature, ProbeResult, ProbeStatistics};
 #[cfg(feature = "webgl")]
 pub use webgl::{AtlasTextureInfo, WebGlAtlasWriter, WebGlRenderer, WebGlTextureWithDimensions};
 #[cfg(feature = "wgpu")]