Deprecate Mix::Clip and change the default blend mode

CHANGELOG.md

@@ -34,6 +34,7 @@ This release has an [MSRV] of 1.82.
   More generally, the angle directions are now described numerically to be unambiguous across coordinate systems.
   The angle unit is also now specified to be in radians. ([#130][] by [@tomcur][])
 - Breaking change: Update to [Kurbo v0.12.0](https://github.com/linebender/kurbo/releases/tag/v0.12.0). ([#127][] by [@nicoburns][])
+- `Mix::Clip` is now deprecated. To access the same functionality of optimised clips in Vello, you should now use `push_clip_layer`. ([#144][] by [@DJMcNab][])
 
 ## [0.4.1][] (2025-09-15)
 
@@ -175,6 +176,7 @@ This release has an [MSRV] of 1.70.
 [#127]: https://github.com/linebender/peniko/pull/127
 [#129]: https://github.com/linebender/peniko/pull/129
 [#130]: https://github.com/linebender/peniko/pull/130
+[#144]: https://github.com/linebender/peniko/pull/144
 
 [@dfrg]: https://github.com/dfrg
 [@DJMcNab]: https://github.com/DJMcNab

src/blend.rs

@@ -84,8 +84,14 @@ pub enum Mix {
     ///
     /// ![](https://www.w3.org/TR/compositing-1/examples/luminosity.png)
     Luminosity = 15,
-    /// `Clip` is the same as `Normal`, but the latter always creates an isolated blend group and the
-    /// former can optimize that out.
+    /// `Clip` was similar to `Normal`, but was optimised for clipping (by avoiding
+    /// blending in areas where there was no clip path).
+    ///
+    /// This optimisation is however unrelated to mixing, and so will no longer
+    /// be indicated with this enum.
+    ///
+    /// If you were using this with Vello, you should use the (new) `push_clip_layer` function instead.
+    #[deprecated(note = "Use `push_clip_layer` instead.", since = "0.5.0")]
     Clip = 128,
     // NOTICE: If a new value is added, be sure to update the bytemuck CheckedBitPattern impl.
 }
@@ -178,7 +184,7 @@ impl BlendMode {
 impl Default for BlendMode {
     fn default() -> Self {
         Self {
-            mix: Mix::Clip,
+            mix: Mix::Normal,
             compose: Compose::SrcOver,
         }
     }

src/impl_bytemuck.rs

@@ -165,6 +165,7 @@ unsafe impl bytemuck::Zeroable for Mix {}
 unsafe impl bytemuck::checked::CheckedBitPattern for Mix {
     type Bits = u8;
 
+    #[expect(deprecated, reason = "Mix::Clip is still a valid bit pattern for now.")]
     fn is_valid_bit_pattern(bits: &u8) -> bool {
         *bits <= Self::Luminosity as u8 || *bits == Self::Clip as u8
     }