Rename with_alpha_factor to multiply_alpha (#52)

Part of #51

CHANGELOG.md

@@ -23,6 +23,7 @@ This release has an [MSRV] of 1.70.
 ### Changed
 
 - Breaking: Mark `Format` as `#[non_exhaustive]` ([#47][] by [@DJMcNab][])
+- Rename `with_alpha_factor` to `multiply_alpha` ([#52][] by [@DJMcNab][])
 
 ### Fixed
 
@@ -48,6 +49,7 @@ This release has an [MSRV] of 1.70.
 [#40]: https://github.com/linebender/peniko/pull/40
 [#46]: https://github.com/linebender/peniko/pull/46
 [#47]: https://github.com/linebender/peniko/pull/47
+[#52]: https://github.com/linebender/peniko/pull/52
 
 [@DJMcNab]: https://github.com/DJMcNab
 [@ratmice]: https://github.com/ratmice

Cargo.toml

@@ -105,7 +105,7 @@ clippy.cargo = { level = "warn", priority = -1 }
 ## Explicit per-crate exceptions, should be manually checked occasionally.
 # There are lots of conversion to u8 color field, which in degenerate cases might not work
 # properly, but generally are fine.
-# E.g. `with_alpha_factor` sets the alpha to `0` for a negative provided `alpha`
+# E.g. `multiply_alpha` sets the alpha to `0` for a negative provided `alpha`
 # clippy.cast_possible_truncation = "warn"
 # Most enums are correctly exhaustive, as this is a vocabulary crate.
 # clippy.exhaustive_enums = "warn"

src/brush.rs

@@ -42,23 +42,31 @@ impl Default for Brush {
 }
 
 impl Brush {
-    /// Returns the brush with the alpha component multiplied by the specified
-    /// factor.
+    /// Returns the brush 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]
-    pub fn with_alpha_factor(self, alpha: f32) -> Self {
+    #[doc(alias = "with_alpha_factor")]
+    #[track_caller]
+    pub fn multiply_alpha(self, alpha: f32) -> Self {
+        debug_assert!(
+            alpha.is_finite() && alpha >= 0.0,
+            "A non-finite or negative alpha ({alpha}) is meaningless."
+        );
         if alpha == 1.0 {
             self
         } else {
             match self {
-                Self::Solid(color) => color.with_alpha_factor(alpha).into(),
+                Self::Solid(color) => color.multiply_alpha(alpha).into(),
                 Self::Gradient(mut gradient) => {
                     gradient
                         .stops
                         .iter_mut()
-                        .for_each(|stop| *stop = stop.with_alpha_factor(alpha));
+                        .for_each(|stop| *stop = stop.multiply_alpha(alpha));
                     gradient.into()
                 }
-                Self::Image(image) => image.with_alpha_factor(alpha).into(),
+                Self::Image(image) => image.multiply_alpha(alpha).into(),
             }
         }
     }

src/color.rs

@@ -18,6 +18,7 @@ pub struct Color {
     /// Blue component.
     pub b: u8,
     /// Alpha component.
+    // If changing type, also change the docs on Self::multiply_alpha
     pub a: u8,
 }
 
@@ -142,7 +143,25 @@ impl Color {
     /// Returns the color 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)
+    }
+
+    /// Returns the color with the alpha component multiplied by `alpha`.
+    /// The behaviour of this transformation is undefined if `alpha` is negative.
+    ///
+    /// If the resulting alpha would overflow, this currently saturates (to opaque).
+    #[must_use]
+    #[track_caller]
+    pub fn multiply_alpha(self, alpha: f32) -> Self {
+        debug_assert!(
+            alpha.is_finite() && alpha >= 0.0,
+            "A non-finite or negative alpha ({alpha}) is meaningless."
+        );
         let mut result = self;
         result.a = ((result.a as f32) * alpha).round() as u8;
         result

src/gradient.rs

@@ -38,10 +38,24 @@ impl ColorStop {
     /// 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)
+    }
+
+    /// 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.with_alpha_factor(alpha),
+            color: self.color.multiply_alpha(alpha),
         }
     }
 }

src/image.rs

@@ -71,9 +71,17 @@ impl Image {
         self
     }
 
-    /// Builder method for setting the image alpha.
+    /// Returns the image with the alpha multiplier multiplied again 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]
-    pub fn with_alpha_factor(mut self, alpha: f32) -> Self {
+    #[track_caller]
+    pub fn multiply_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 = ((self.alpha as f32) * alpha).round() as u8;
         self
     }