add doc for BlendMode

Zentiph · Zentiph · commit c2f2d33fabf8 · 2025-11-03T14:23:40.000-05:00
diff --git a/src/color/model.rs b/src/color/model.rs
@@ -13,6 +13,85 @@ extern crate alloc;
 
 use crate::color::ColorFloat;
 
+/// An enum naming the supported color blending modes.
+/// Most descriptions and implementations of these blend modes
+/// come from the W3C: https://www.w3.org/TR/compositing-1/.
+///
+/// # Variants
+///
+/// - `Normal` - No blending. The blending formula simply selects the source color.
+///
+/// - `Multiply` - The source color is multiplied by the destination color and replaces
+///   the destination.
+///   The resultant color is always at least as dark as either the
+///   source or destination color.
+///   Multiplying any color with black results in black;
+///   multiplying any color with white preserves the original color.
+///
+/// - `Screen` - Multiplies the complements of the backdrop and source color values,
+///   then complements the result.
+///   The result color is always at least as light as
+///   either of the two constituent colors.
+///   Screening any color with white produces white;
+///   screening with black leaves the original color unchanged.
+///   The effect is similar to projecting multiple photographic slides simultaneously
+///   onto a single screen.
+///
+/// - `Overlay` - Multiplies or screens the colors, depending on the backdrop color
+///   value.
+///   Source colors overlay the backdrop while preserving its highlights and shadows.
+///   The backdrop color is not replaced but is mixed with the source color to reflect
+///   the lightness or darkness of the backdrop.
+///   Overlay is the inverse of the HardLight blend mode.
+///
+/// - `Darken` - Selects the darker of the backdrop and source colors.
+///   The backdrop is replaced with the source where the source is darker;
+///   otherwise, it is left unchanged.
+///
+/// - `Lighten` - Selects the lighter of the backdrop and source colors.
+///   The backdrop is replaced with the source where the source is lighter;
+///   otherwise, it is left unchanged.
+///   The result must be rounded down if it exceeds the range.
+///
+/// - `ColorDodge` - Brightens the backdrop color to reflect the source color.
+///   Painting with black produces no changes.
+///
+/// - `ColorBurn` - Darkens the backdrop color to reflect the source color.
+///   Painting with white produces no change.
+///
+/// - `HardLight` - Multiplies or screens the colors, depending on the source color
+///   value.
+///   The effect is similar to shining a harsh spotlight on the backdrop.
+///
+/// - `SoftLight` - Darkens or lightens the colors, depending on the source color value.
+///   The effect is similar to shining a diffused spotlight on the backdrop.
+///
+/// - `Difference` - Subtracts the darker of the two constituent colors from the lighter
+///   color.
+///   Painting with white inverts the backdrop color;
+///   painting with black produces no change.
+///
+/// - `Exclusion` - Produces an effect similar to that of the Difference mode but lower
+///   in contrast.
+///   Painting with white inverts the backdrop color;
+///   painting with black produces no change.
+///
+/// - `Hue` - Creates a color with the hue of the source color and the saturation and
+///   luminosity of the backdrop color.
+///
+/// - `Saturation` - Creates a color with the saturation of the source color and the hue
+///   and luminosity of the backdrop color.
+///   Painting with this mode in an area of the backdrop that is a pure gray
+///   (no saturation) produces no change.
+///
+/// - `Color` - Creates a color with the hue and saturation of the source color and the
+///   luminosity of the backdrop color.
+///   This preserves the gray levels of the backdrop and is useful for coloring
+///   monochrome images or tinting color images.
+///
+/// - `Luminosity` - Creates a color with the luminosity of the source color and the hue
+///   and saturation of the backdrop color.
+///   This produces an inverse effect to that of the Color mode.
 #[derive(Clone, Copy, Debug, PartialEq, Eq)]
 pub enum BlendMode {
     // separable blend modes
