vello: make Scene clip/layers honor fill rule (even-odd clips)

Scene layer APIs now take a `Fill` for the clip shape (`push_layer`, `push_clip_layer`, `push_luminance_mask_layer`), fixing the long-standing hardcoded `Fill::NonZero` clip behavior and aligning with sparse-strips renderers.

This is required for correctness in CSS/SVG semantics (e.g. `clip-rule`, `fill-rule`, and masking/clipPath content that relies on even-odd holes).

To make even-odd clipping actually work end-to-end, plumb the fill rule through the clip pipeline:

- Give `BEGIN_CLIP` a 1-word info slot so clip draw flags can be stored.
- Populate clip `draw_flags` for `BEGIN_CLIP` in `draw_leaf`.
- In `clip_leaf`, propagate `info_offset` from `BEGIN_CLIP` to the corresponding `END_CLIP`.
- In coarse, apply clip layers with the correct fill rule by propagating `BEGIN_CLIP` draw flags through to `END_CLIP`, and by updating the “clip-zero” fast path to respect even-odd backdrop parity (GPU + CPU paths).

Author: waywardmonkeys

CHANGELOG.md

@@ -18,6 +18,7 @@ This release has an [MSRV][] of 1.88.
 ### Changed
 
 - Breaking change: wgpu has been updated to wgpu 27. ([#1280][] by [@theoparis][])  
+- Breaking change: make `Scene` clip / layers honor fill rule (even-odd clips). ([#1332][] by [@waywardmonkeys][])
 
 ### Fixed
 
@@ -383,6 +384,7 @@ This release has an [MSRV][] of 1.75.
 [#1273]: https://github.com/linebender/vello/pull/1273
 [#1280]: https://github.com/linebender/vello/pull/1280
 [#1323]: https://github.com/linebender/vello/pull/1323
+[#1332]: https://github.com/linebender/vello/pull/1332
 
 <!-- Note that this still comparing against 0.5.0, because 0.5.1 is a cherry-picked patch -->
 [Unreleased]: https://github.com/linebender/vello/compare/v0.5.0...HEAD

examples/scenes/src/test_scenes.rs

@@ -769,7 +769,7 @@ mod impls {
             &rect,
         );
         let alpha = params.time.sin() as f32 * 0.5 + 0.5;
-        scene.push_layer(Mix::Normal, alpha, Affine::IDENTITY, &rect);
+        scene.push_layer(Fill::NonZero, Mix::Normal, alpha, Affine::IDENTITY, &rect);
         scene.fill(
             Fill::NonZero,
             Affine::translate((100.0, 100.0)) * Affine::scale(0.2),
@@ -1125,6 +1125,7 @@ mod impls {
         let mut depth = 0;
         for (width, color) in &options[..params.complexity.min(options.len() - 1)] {
             scene.push_layer(
+                Fill::NonZero,
                 Mix::Normal,
                 0.9,
                 Affine::IDENTITY,
@@ -1152,7 +1153,7 @@ mod impls {
                 const CLIPS_PER_FILL: usize = 3;
                 for _ in 0..CLIPS_PER_FILL {
                     let rot = Affine::rotate(rng.random_range(0.0..PI));
-                    scene.push_clip_layer(translate * rot, &base_tri);
+                    scene.push_clip_layer(Fill::NonZero, translate * rot, &base_tri);
                 }
                 let rot = Affine::rotate(rng.random_range(0.0..PI));
                 let color = Color::new([rng.random(), rng.random(), rng.random(), 1.]);
@@ -1212,7 +1213,7 @@ mod impls {
                 PathEl::LineTo((X0, Y1).into()),
                 PathEl::ClosePath,
             ];
-            scene.push_clip_layer(Affine::IDENTITY, &path);
+            scene.push_clip_layer(Fill::NonZero, Affine::IDENTITY, &path);
         }
         let rect = Rect::new(X0, Y0, X1, Y1);
         scene.fill(
@@ -1243,7 +1244,11 @@ mod impls {
             None,
             &make_diamond(1024.0, 125.0),
         );
-        scene.push_clip_layer(Affine::IDENTITY, &make_diamond(1024.0, 150.0));
+        scene.push_clip_layer(
+            Fill::NonZero,
+            Affine::IDENTITY,
+            &make_diamond(1024.0, 150.0),
+        );
         scene.fill(
             Fill::NonZero,
             Affine::IDENTITY,
@@ -1271,11 +1276,11 @@ mod impls {
             scene.fill(Fill::NonZero, transform, &radial, None, &rect);
         }
         const COLORS: &[Color] = &[palette::css::RED, palette::css::LIME, palette::css::BLUE];
-        scene.push_layer(Mix::Normal, 1.0, transform, &rect);
+        scene.push_layer(Fill::NonZero, Mix::Normal, 1.0, transform, &rect);
         for (i, c) in COLORS.iter().enumerate() {
             let linear = Gradient::new_linear((0.0, 0.0), (0.0, 200.0))
                 .with_stops([palette::css::WHITE, *c]);
-            scene.push_layer(blend, 1.0, transform, &rect);
+            scene.push_layer(Fill::NonZero, blend, 1.0, transform, &rect);
             // squash the ellipse
             let a = transform
                 * Affine::translate((100., 100.))
@@ -1579,7 +1584,7 @@ mod impls {
                 PathEl::ClosePath,
             ]
         };
-        scene.push_clip_layer(Affine::IDENTITY, &clip);
+        scene.push_clip_layer(Fill::NonZero, Affine::IDENTITY, &clip);
         {
             let text_size = 60.0 + 40.0 * (params.time as f32).sin();
             let s = "Some clipped text!";
@@ -1594,6 +1599,41 @@ mod impls {
         }
         scene.pop_layer();
 
+        // Even-odd clip-layer demo: a self-intersecting star ("pentagram") has different results
+        // under non-zero vs even-odd fill rules (even-odd produces a hole).
+        let demo_rect = Rect::new(250.0, 20.0, 450.0, 220.0);
+        scene.fill(
+            Fill::NonZero,
+            Affine::IDENTITY,
+            palette::css::BLUE,
+            None,
+            &demo_rect,
+        );
+        let mut star = BezPath::new();
+        let center = Point::new(350.0, 120.0);
+        let outer_r = 90.0;
+        let start_angle = -std::f64::consts::FRAC_PI_2;
+        let pts: [Point; 5] = core::array::from_fn(|i| {
+            let a = start_angle + (i as f64) * (2.0 * std::f64::consts::PI / 5.0);
+            center + Vec2::new(a.cos() * outer_r, a.sin() * outer_r)
+        });
+        let order = [0_usize, 2, 4, 1, 3];
+        star.move_to(pts[order[0]]);
+        for &idx in &order[1..] {
+            star.line_to(pts[idx]);
+        }
+        star.close_path();
+
+        scene.push_clip_layer(Fill::EvenOdd, Affine::IDENTITY, &star);
+        scene.fill(
+            Fill::NonZero,
+            Affine::IDENTITY,
+            palette::css::RED,
+            None,
+            &demo_rect,
+        );
+        scene.pop_layer();
+
         let large_background_rect = Rect::new(-1000.0, -1000.0, 2000.0, 2000.0);
         let inside_clip_rect = Rect::new(11.0, 13.399999999999999, 59.0, 56.6);
         let outside_clip_rect = Rect::new(
@@ -1606,6 +1646,7 @@ mod impls {
         let scale = 2.0;
 
         scene.push_layer(
+            Fill::NonZero,
             BlendMode {
                 mix: Mix::Normal,
                 compose: Compose::SrcOver,
@@ -1926,6 +1967,7 @@ mod impls {
             },
         );
         scene.push_layer(
+            Fill::NonZero,
             BlendMode::new(Mix::Normal, Compose::SrcOver),
             1.0,
             Affine::IDENTITY,
@@ -1949,6 +1991,7 @@ mod impls {
             },
         );
         scene.push_luminance_mask_layer(
+            Fill::NonZero,
             1.0,
             Affine::IDENTITY,
             &Rect {
@@ -1993,6 +2036,7 @@ mod impls {
             .unwrap();
         // HACK: Porter-Duff "over" the base color, restoring full alpha
         scene.push_layer(
+            Fill::NonZero,
             BlendMode::new(Mix::Normal, Compose::SrcOver),
             1.0,
             Affine::IDENTITY,
@@ -2028,6 +2072,7 @@ mod impls {
             },
         );
         scene.push_luminance_mask_layer(
+            Fill::NonZero,
             1.0,
             Affine::IDENTITY,
             &Rect {

vello/src/scene.rs

@@ -82,6 +82,8 @@ impl Scene {
     /// Pushes a new layer clipped by the specified shape and composed with
     /// previous layers using the specified blend mode.
     ///
+    /// The `fill_rule` controls how the `clip` shape is interpreted.
+    ///
     /// Every drawing command after this call will be clipped by the shape
     /// until the layer is [popped](Self::pop_layer).
     /// For layers which are only added for clipping, you should
@@ -93,6 +95,7 @@ impl Scene {
     #[track_caller]
     pub fn push_layer(
         &mut self,
+        fill_rule: Fill,
         blend: impl Into<BlendMode>,
         alpha: f32,
         transform: Affine,
@@ -107,6 +110,7 @@ impl Scene {
         }
         self.push_layer_inner(
             DrawBeginClip::new(blend, alpha.clamp(0.0, 1.0)),
+            fill_rule,
             transform,
             clip,
         );
@@ -118,6 +122,8 @@ impl Scene {
     /// That is, content drawn between this and the matching `pop_layer` call will serve
     /// as a luminance mask for the prior content in this layer.
     ///
+    /// The `fill_rule` controls how the `clip` shape is interpreted.
+    ///
     /// Every drawing command after this call will be clipped by the shape
     /// until the layer is [popped](Self::pop_layer).
     ///
@@ -135,16 +141,25 @@ impl Scene {
     /// This issue only occurs if there are no intermediate opaque layers, so can be worked around
     /// by drawing something opaque (or having an opaque `base_color`), then putting a layer around your entire scene
     /// with a [`Compose::SrcOver`].
-    pub fn push_luminance_mask_layer(&mut self, alpha: f32, transform: Affine, clip: &impl Shape) {
+    pub fn push_luminance_mask_layer(
+        &mut self,
+        fill_rule: Fill,
+        alpha: f32,
+        transform: Affine,
+        clip: &impl Shape,
+    ) {
         self.push_layer_inner(
             DrawBeginClip::luminance_mask(alpha.clamp(0.0, 1.0)),
+            fill_rule,
             transform,
             clip,
         );
     }
 
     /// Pushes a new layer clipped by the specified `clip` shape.
     ///
+    /// The `fill_rule` controls how the `clip` shape is interpreted.
+    ///
     /// The pushed layer is intended to not impact the "source" for blending; that is, any blends
     /// within this layer will still include content from before this method was called in the "source"
     /// of that blend operation.
@@ -157,20 +172,21 @@ impl Scene {
     ///
     /// **However, the transforms are *not* saved or modified by the layer stack.**
     /// That is, the `transform` argument to this function only applies a transform to the `clip` shape.
-    pub fn push_clip_layer(&mut self, transform: Affine, clip: &impl Shape) {
-        self.push_layer_inner(DrawBeginClip::clip(), transform, clip);
+    pub fn push_clip_layer(&mut self, fill_rule: Fill, transform: Affine, clip: &impl Shape) {
+        self.push_layer_inner(DrawBeginClip::clip(), fill_rule, transform, clip);
     }
 
     /// Helper for logic shared between [`Self::push_layer`] and [`Self::push_luminance_mask_layer`]
     fn push_layer_inner(
         &mut self,
         parameters: DrawBeginClip,
+        fill_rule: Fill,
         transform: Affine,
         clip: &impl Shape,
     ) {
         let t = Transform::from_kurbo(&transform);
         self.encoding.encode_transform(t);
-        self.encoding.encode_fill_style(Fill::NonZero);
+        self.encoding.encode_fill_style(fill_rule);
         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.
@@ -894,7 +910,7 @@ impl ColorPainter for DrawColorGlyphs<'_> {
         };
         self.clip_depth += 1;
         self.scene
-            .push_clip_layer(self.last_transform().to_kurbo(), &path.0);
+            .push_clip_layer(Fill::NonZero, self.last_transform().to_kurbo(), &path.0);
     }
 
     fn push_clip_box(&mut self, clip_box: skrifa::raw::types::BoundingBox<f32>) {
@@ -909,7 +925,7 @@ impl ColorPainter for DrawColorGlyphs<'_> {
         }
         self.clip_depth += 1;
         self.scene
-            .push_clip_layer(self.last_transform().to_kurbo(), &clip_box);
+            .push_clip_layer(Fill::NonZero, self.last_transform().to_kurbo(), &clip_box);
     }
 
     fn pop_clip(&mut self) {
@@ -949,8 +965,13 @@ impl ColorPainter for DrawColorGlyphs<'_> {
             // TODO:
             _ => Compose::SrcOver,
         };
-        self.scene
-            .push_layer(blend, 1.0, self.last_transform().to_kurbo(), &self.clip_box);
+        self.scene.push_layer(
+            Fill::NonZero,
+            blend,
+            1.0,
+            self.last_transform().to_kurbo(),
+            &self.clip_box,
+        );
     }
 
     fn pop_layer(&mut self) {

vello_encoding/src/draw.rs

@@ -37,7 +37,7 @@ impl DrawTag {
     pub const BLUR_RECT: Self = Self(0x2d4); // info: 11, scene: 5 (DrawBlurRoundedRect)
 
     /// Begin layer/clip.
-    pub const BEGIN_CLIP: Self = Self(0x9);
+    pub const BEGIN_CLIP: Self = Self(0x49);
 
     /// End layer/clip.
     pub const END_CLIP: Self = Self(0x21);

vello_shaders/shader/clip_leaf.wgsl

@@ -193,6 +193,8 @@ fn main(
         draw_monoids[ix].path_ix = u32(path_ix);
         // Make EndClip point to the same draw data as BeginClip
         draw_monoids[ix].scene_offset = draw_monoids[parent_ix].scene_offset;
+        // Make EndClip point to the same info (draw flags) as BeginClip
+        draw_monoids[ix].info_offset = draw_monoids[parent_ix].info_offset;
         if grandparent >= 0 {
             bbox = sh_bbox[grandparent];
         } else if grandparent + i32(stack_size) >= 0 {

vello_shaders/shader/coarse.wgsl

@@ -410,7 +410,9 @@ fn main(
                         write_image(di + 1u);
                     }
                     case DRAWTAG_BEGIN_CLIP: {
-                        if tile.segment_count_or_ix == 0u && tile.backdrop == 0 {
+                        let even_odd = (draw_flags & DRAW_INFO_FLAGS_FILL_RULE_BIT) != 0u;
+                        let backdrop_clear = select(tile.backdrop, abs(tile.backdrop) & 1, even_odd) == 0;
+                        if tile.segment_count_or_ix == 0u && backdrop_clear {
                             clip_zero_depth = clip_depth + 1u;
                         } else {
                             write_begin_clip();
@@ -421,8 +423,7 @@ fn main(
                     }
                     case DRAWTAG_END_CLIP: {
                         clip_depth -= 1u;
-                        // A clip shape is always a non-zero fill (draw_flags=0).
-                        write_path(tile, tile_ix, /*draw_flags=*/0u);
+                        write_path(tile, tile_ix, draw_flags);
                         let blend = scene[dd];
                         let alpha = bitcast<f32>(scene[dd + 1u]);
                         write_end_clip(CmdEndClip(blend, alpha));

vello_shaders/shader/draw_leaf.wgsl

@@ -131,6 +131,9 @@ fn main(
                 case DRAWTAG_FILL_COLOR: {
                     info[di] = draw_flags;
                 }
+                case DRAWTAG_BEGIN_CLIP: {
+                    info[di] = draw_flags;
+                }
                 case DRAWTAG_FILL_LIN_GRADIENT: {
                     info[di] = draw_flags;
                     var p0 = bitcast<vec2<f32>>(vec2(scene[dd + 1u], scene[dd + 2u]));

vello_shaders/shader/shared/drawtag.wgsl

@@ -23,7 +23,7 @@ const DRAWTAG_FILL_RAD_GRADIENT = 0x29cu;
 const DRAWTAG_FILL_SWEEP_GRADIENT = 0x254u;
 const DRAWTAG_FILL_IMAGE = 0x28Cu;
 const DRAWTAG_BLURRED_ROUNDED_RECT = 0x2d4u;
-const DRAWTAG_BEGIN_CLIP = 0x9u;
+const DRAWTAG_BEGIN_CLIP = 0x49u;
 const DRAWTAG_END_CLIP = 0x21u;
 
 /// The first word of each draw info stream entry contains the flags. This is not a part of the

vello_shaders/src/cpu/clip_leaf.rs

@@ -66,6 +66,8 @@ fn clip_leaf_main(
             draw_monoids[clip_el.ix as usize].path_ix = tos.path_ix;
             draw_monoids[clip_el.ix as usize].scene_offset =
                 draw_monoids[tos.parent_ix as usize].scene_offset;
+            draw_monoids[clip_el.ix as usize].info_offset =
+                draw_monoids[tos.parent_ix as usize].info_offset;
         }
     }
 }

vello_shaders/src/cpu/coarse.rs

@@ -334,7 +334,13 @@ fn coarse_main(
                                 tile_state.write_blur_rect(config, bump, ptcl, rgba_color, di + 1);
                             }
                             DrawTag::BEGIN_CLIP => {
-                                if tile.segment_count_or_ix == 0 && tile.backdrop == 0 {
+                                let even_odd = (draw_flags & DRAW_INFO_FLAGS_FILL_RULE_BIT) != 0;
+                                let backdrop_clear = if even_odd {
+                                    tile.backdrop.abs() & 1 == 0
+                                } else {
+                                    tile.backdrop == 0
+                                };
+                                if tile.segment_count_or_ix == 0 && backdrop_clear {
                                     clip_zero_depth = clip_depth + 1;
                                 } else {
                                     tile_state.write_begin_clip(config, bump, ptcl);
@@ -347,8 +353,7 @@ fn coarse_main(
                             }
                             DrawTag::END_CLIP => {
                                 clip_depth -= 1;
-                                // A clip shape is always a non-zero fill (draw_flags=0).
-                                tile_state.write_path(config, bump, ptcl, tile, 0);
+                                tile_state.write_path(config, bump, ptcl, tile, draw_flags);
                                 let blend = scene[dd as usize];
                                 let alpha = f32::from_bits(scene[dd as usize + 1]);
                                 tile_state.write_end_clip(config, bump, ptcl, blend, alpha);