Add with_alpha for Brush, Gradient, Image

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]