Add with_alpha for Brush, Gradient, Image (#67)

There is now a `with_alpha` to go along with `multiply_alpha` that sets
the alpha to the given value. This makes it work the same as for colors
with the same sort of API.

While doing this, some code for multiplying alpha on a gradient was
moved to `Gradient` to make the interfaces the same on all things that
support this.

Fixes #51.

CHANGELOG.md

@@ -19,6 +19,7 @@ This release has an [MSRV] of 1.82.
 
 - `Image` now stores the alpha as an `f32` ([#65][] by [@waywardmonkeys][])
 - Use `color` crate. See below for details ([#63][] by [@waywardmonkeys][])
+- `Gradient`, `Image`, `Brush` now have `with_alpha` and `Gradient` also gets a `multiply_alpha` ([#67][] by [@waywardmonkeys][])
 
 ### Color Changes
 
@@ -76,6 +77,7 @@ This release has an [MSRV] of 1.70.
 [#52]: https://github.com/linebender/peniko/pull/52
 [#63]: https://github.com/linebender/peniko/pull/63
 [#65]: https://github.com/linebender/peniko/pull/65
+[#67]: https://github.com/linebender/peniko/pull/67
 
 [@DJMcNab]: https://github.com/DJMcNab
 [@ratmice]: https://github.com/ratmice

src/brush.rs

@@ -56,6 +56,16 @@ impl Default for Brush {
 }
 
 impl Brush {
+    /// Returns the brush with the alpha component set to `alpha`.
+    #[must_use]
+    pub fn with_alpha(self, alpha: f32) -> Self {
+        match self {
+            Self::Solid(color) => color.with_alpha(alpha).into(),
+            Self::Gradient(gradient) => gradient.with_alpha(alpha).into(),
+            Self::Image(image) => image.with_alpha(alpha).into(),
+        }
+    }
+
     /// Returns the brush with the alpha component multiplied by `alpha`.
     /// The behaviour of this transformation is undefined if `alpha` is negative.
     ///
@@ -73,13 +83,7 @@ impl Brush {
         } else {
             match self {
                 Self::Solid(color) => color.multiply_alpha(alpha).into(),
-                Self::Gradient(mut gradient) => {
-                    gradient
-                        .stops
-                        .iter_mut()
-                        .for_each(|stop| *stop = stop.multiply_alpha(alpha));
-                    gradient.into()
-                }
+                Self::Gradient(gradient) => gradient.multiply_alpha(alpha).into(),
                 Self::Image(image) => image.multiply_alpha(alpha).into(),
             }
         }

src/gradient.rs

@@ -36,29 +36,37 @@ impl PartialEq for ColorStop {
 impl Eq for ColorStop {}
 
 impl ColorStop {
-    /// Returns the color stop with the alpha component multiplied by the specified
-    /// factor.
+    /// Returns the color stop with the alpha component set to `alpha`.
     #[must_use]
-    #[deprecated(
-        since = "0.2.0",
-        note = "This method has been renamed to `multiply_alpha`."
-    )]
-    pub fn with_alpha_factor(self, alpha: f32) -> Self {
-        self.multiply_alpha(alpha)
+    pub fn with_alpha(self, alpha: f32) -> Self {
+        Self {
+            offset: self.offset,
+            color: self.color.with_alpha(alpha),
+        }
     }
 
     /// Returns the color stop with the alpha component multiplied by `alpha`.
     /// The behaviour of this transformation is undefined if `alpha` is negative.
     ///
     /// If any resulting alphas would overflow, these currently saturate (to opaque).
     #[must_use]
-    #[track_caller]
     pub fn multiply_alpha(self, alpha: f32) -> Self {
         Self {
             offset: self.offset,
             color: self.color.multiply_alpha(alpha),
         }
     }
+
+    /// Returns the color stop with the alpha component multiplied by the specified
+    /// factor.
+    #[must_use]
+    #[deprecated(
+        since = "0.2.0",
+        note = "This method has been renamed to `multiply_alpha`."
+    )]
+    pub fn with_alpha_factor(self, alpha: f32) -> Self {
+        self.multiply_alpha(alpha)
+    }
 }
 
 impl<CS: ColorSpace> From<(f32, AlphaColor<CS>)> for ColorStop {
@@ -225,6 +233,25 @@ impl Gradient {
         stops.collect_stops(&mut self.stops);
         self
     }
+
+    /// Returns the gradient with the alpha component for all color stops set to `alpha`.
+    #[must_use]
+    pub fn with_alpha(mut self, alpha: f32) -> Self {
+        self.stops
+            .iter_mut()
+            .for_each(|stop| *stop = stop.with_alpha(alpha));
+        self
+    }
+
+    /// Returns the gradient with the alpha component for all color stops
+    /// multiplied by `alpha`.
+    #[must_use]
+    pub fn multiply_alpha(mut self, alpha: f32) -> Self {
+        self.stops
+            .iter_mut()
+            .for_each(|stop| *stop = stop.multiply_alpha(alpha));
+        self
+    }
 }
 
 /// Trait for types that represent a source of color stops.

src/image.rs

@@ -67,6 +67,18 @@ impl Image {
         self
     }
 
+    /// Returns the image with the alpha multiplier set to `alpha`.
+    #[must_use]
+    #[track_caller]
+    pub fn with_alpha(mut self, alpha: f32) -> Self {
+        debug_assert!(
+            alpha.is_finite() && alpha >= 0.0,
+            "A non-finite or negative alpha ({alpha}) is meaningless."
+        );
+        self.alpha = alpha;
+        self
+    }
+
     /// Returns the image with the alpha multiplier multiplied again by `alpha`.
     /// The behaviour of this transformation is undefined if `alpha` is negative.
     #[must_use]