Add InterpolationAlphaSpace to Gradient (#115)

Work towards linebender/vello#1056, I think
the best solution is to support both both ways of dealing with alpha
during interpolation, thus we need to repr this in `Gradient` with newly
introduced `InterpolationAlphaSpace`. `InterpolationAlphaSpace` and it's
docs are copied from linebender/color#191.

Depends on linebender/color#191

This is breaking change.

---------

Signed-off-by: sagudev <[email protected]>

Author: sagudev

CHANGELOG.md

@@ -20,11 +20,13 @@ This release has an [MSRV] of 1.82.
 - `Style` now impl `PartialEq`. ([#114][] by [@liferooter][])
 - Add `Bgra8` variant to `ImageFormat`. ([#120][] by [@sagudev][])
 - Provide `ImageAlphaType` with `ImageData`. ([#121][] by [@sagudev][])
+- Breaking change: Add `InterpolationAlphaSpace` to `Gradient` to chose how color channels should be handled when interpolating between transparent colors. ([#121][] by [@sagudev][])
 
 ### Changed
 
 - Breaking change: `Image` has been renamed to `ImageBrush`, which now consists of an `ImageData` and an `ImageSampler`. ([#117][], [#123][] by [@nicoburns][], [@DJMcNab][])
 - Breaking change: `Font` has been renamed to `FontData` to match `ImageData`. ([#126][] by [@nicoburns][])
+- Update to `color` 0.3.2. ([#115][] by [@sagudev][])
 
 ### Raw Resource Changes
 
@@ -147,6 +149,7 @@ This release has an [MSRV] of 1.70.
 [#103]: https://github.com/linebender/peniko/pull/103
 [#104]: https://github.com/linebender/peniko/pull/104
 [#114]: https://github.com/linebender/peniko/pull/114
+[#115]: https://github.com/linebender/peniko/pull/115
 [#117]: https://github.com/linebender/peniko/pull/117
 [#120]: https://github.com/linebender/peniko/pull/120
 [#121]: https://github.com/linebender/peniko/pull/121

Cargo.lock

@@ -37,7 +37,7 @@ serde = [
 kurbo = { version = "0.12.0", default-features = false }
 smallvec = "1.15.0"
 bytemuck = { version = "1.23.0", default-features = false, optional = true }
-color = { version = "0.3.1", default-features = false }
+color = { version = "0.3.2", default-features = false }
 linebender_resource_handle = { version = "0.1.0", default-features = false }
 serde = { version = "1.0.219", default-features = false, optional = true, features = [
     "alloc",

Cargo.toml

@@ -219,6 +219,39 @@ impl SweepGradientPosition {
     }
 }
 
+/// Defines how color channels should be handled when interpolating
+/// between transparent colors.
+#[derive(Clone, Copy, Default, Debug, PartialEq)]
+#[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
+pub enum InterpolationAlphaSpace {
+    /// Colors are interpolated with their color channels premultiplied by the alpha
+    /// channel. This is almost always what you want.
+    ///
+    /// Used when interpolating colors in the premultiplied alpha space, which allows
+    /// for correct interpolation when colors are transparent. This matches behavior
+    /// described in [CSS Color Module Level 4 § 12.3].
+    ///
+    /// Following the convention of CSS Color Module Level 4, in cylindrical color
+    /// spaces the hue channel is not premultiplied. If it were, interpolation would
+    /// give undesirable results. See also [`color::PremulColor`].
+    ///
+    /// [CSS Color Module Level 4 § 12.3]: https://drafts.csswg.org/css-color/#interpolation-alpha
+    #[default]
+    Premultiplied = 0,
+    /// Colors are interpolated without premultiplying their color channels by the alpha channel.
+    ///
+    /// This causes color information to leak out of transparent colors. For example, when
+    /// interpolating from a fully transparent red to a fully opaque blue in sRGB, this
+    /// method will go through an intermediate purple.
+    ///
+    /// Used when interpolating colors in the unpremultiplied (straight) alpha space.
+    /// This matches behavior of gradients in the HTML `canvas` element.
+    /// See [The 2D rendering context § Fill and stroke styles].
+    ///
+    /// [The 2D rendering context § Fill and stroke styles]: https://html.spec.whatwg.org/multipage/#interpolation
+    Unpremultiplied = 1,
+}
+
 /// Properties for the supported [gradient](Gradient) types.
 #[derive(Copy, Clone, PartialEq, Debug)]
 #[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
@@ -271,6 +304,8 @@ pub struct Gradient {
     ///
     /// [CSS Color Module Level 4 § 12.4]: https://drafts.csswg.org/css-color/#hue-interpolation
     pub hue_direction: HueDirection,
+    /// Alpha space to be used for interpolation
+    pub interpolation_alpha_space: InterpolationAlphaSpace,
     /// Color stop collection.
     pub stops: ColorStops,
 }
@@ -286,6 +321,7 @@ impl Default for Gradient {
             extend: Extend::default(),
             interpolation_cs: DEFAULT_GRADIENT_COLOR_SPACE,
             hue_direction: HueDirection::default(),
+            interpolation_alpha_space: InterpolationAlphaSpace::default(),
             stops: ColorStops::default(),
         }
     }
@@ -299,6 +335,7 @@ impl Gradient {
             extend: Extend::default(),
             interpolation_cs: DEFAULT_GRADIENT_COLOR_SPACE,
             hue_direction: HueDirection::default(),
+            interpolation_alpha_space: InterpolationAlphaSpace::default(),
             stops: ColorStops::default(),
         }
     }
@@ -311,6 +348,7 @@ impl Gradient {
             extend: Extend::default(),
             interpolation_cs: DEFAULT_GRADIENT_COLOR_SPACE,
             hue_direction: HueDirection::default(),
+            interpolation_alpha_space: InterpolationAlphaSpace::default(),
             stops: ColorStops::default(),
         }
     }
@@ -333,6 +371,7 @@ impl Gradient {
             extend: Extend::default(),
             interpolation_cs: DEFAULT_GRADIENT_COLOR_SPACE,
             hue_direction: HueDirection::default(),
+            interpolation_alpha_space: InterpolationAlphaSpace::default(),
             stops: ColorStops::default(),
         }
     }
@@ -345,6 +384,7 @@ impl Gradient {
             extend: Extend::default(),
             interpolation_cs: DEFAULT_GRADIENT_COLOR_SPACE,
             hue_direction: HueDirection::default(),
+            interpolation_alpha_space: InterpolationAlphaSpace::default(),
             stops: ColorStops::default(),
         }
     }
@@ -363,6 +403,16 @@ impl Gradient {
         self
     }
 
+    /// Builder method for setting the interpolation alpha space.
+    #[must_use]
+    pub const fn with_interpolation_alpha_space(
+        mut self,
+        interpolation_alpha_space: InterpolationAlphaSpace,
+    ) -> Self {
+        self.interpolation_alpha_space = interpolation_alpha_space;
+        self
+    }
+
     /// Builder method for setting the hue direction when interpolating within a cylindrical color space.
     #[must_use]
     pub const fn with_hue_direction(mut self, hue_direction: HueDirection) -> Self {

src/gradient.rs

@@ -47,8 +47,8 @@ pub use linebender_resource_handle::{self, Blob, FontData, WeakBlob};
 pub use blend::{BlendMode, Compose, Mix};
 pub use brush::{Brush, BrushRef, Extend};
 pub use gradient::{
-    ColorStop, ColorStops, ColorStopsSource, Gradient, GradientKind, LinearGradientPosition,
-    RadialGradientPosition, SweepGradientPosition,
+    ColorStop, ColorStops, ColorStopsSource, Gradient, GradientKind, InterpolationAlphaSpace,
+    LinearGradientPosition, RadialGradientPosition, SweepGradientPosition,
 };
 pub use image::{
     ImageAlphaType, ImageBrush, ImageBrushRef, ImageData, ImageFormat, ImageQuality, ImageSampler,