Merge pull request #3073 from SixLabors/js/antialis-threshold-

Replace AntialiasSubpixelDepth with AntialiasThreshold

Author: JimBobSquarePants

src/ImageSharp/GraphicsOptions.cs

@@ -6,11 +6,12 @@
 namespace SixLabors.ImageSharp;
 
 /// <summary>
-/// Options for influencing the drawing functions.
+/// Provides configuration for controlling how graphics operations are rendered,
+/// including antialiasing, pixel blending, alpha composition, and coverage thresholding.
 /// </summary>
 public class GraphicsOptions : IDeepCloneable<GraphicsOptions>
 {
-    private int antialiasSubpixelDepth = 16;
+    private float antialiasThreshold = .5F;
     private float blendPercentage = 1F;
 
     /// <summary>
@@ -24,61 +25,62 @@ private GraphicsOptions(GraphicsOptions source)
     {
         this.AlphaCompositionMode = source.AlphaCompositionMode;
         this.Antialias = source.Antialias;
-        this.AntialiasSubpixelDepth = source.AntialiasSubpixelDepth;
+        this.AntialiasThreshold = source.AntialiasThreshold;
         this.BlendPercentage = source.BlendPercentage;
         this.ColorBlendingMode = source.ColorBlendingMode;
     }
 
     /// <summary>
     /// Gets or sets a value indicating whether antialiasing should be applied.
-    /// Defaults to true.
+    /// When <see langword="true"/>, edges are rendered with smooth sub-pixel coverage.
+    /// When <see langword="false"/>, coverage is snapped to binary (fully opaque or fully transparent)
+    /// using <see cref="AntialiasThreshold"/> as the cutoff.
+    /// Defaults to <see langword="true"/>.
     /// </summary>
     public bool Antialias { get; set; } = true;
 
     /// <summary>
-    /// Gets or sets a value indicating the number of subpixels to use while rendering with antialiasing enabled.
-    /// Defaults to 16.
+    /// Gets or sets the coverage threshold used when <see cref="Antialias"/> is <see langword="false"/>.
+    /// Pixels with antialiased coverage above this value are rendered as fully opaque;
+    /// pixels below are discarded. Valid range is 0 to 1. Lower values preserve more
+    /// thin features at small sizes. Defaults to <c>0.5F</c>.
     /// </summary>
-    public int AntialiasSubpixelDepth
+    public float AntialiasThreshold
     {
-        get
-        {
-            return this.antialiasSubpixelDepth;
-        }
+        get => this.antialiasThreshold;
 
         set
         {
-            Guard.MustBeGreaterThanOrEqualTo(value, 0, nameof(this.AntialiasSubpixelDepth));
-            this.antialiasSubpixelDepth = value;
+            Guard.MustBeBetweenOrEqualTo(value, 0F, 1F, nameof(this.AntialiasThreshold));
+            this.antialiasThreshold = value;
         }
     }
 
     /// <summary>
-    /// Gets or sets a value between indicating the blending percentage to apply to the drawing operation.
-    /// Range 0..1; Defaults to 1.
+    /// Gets or sets the blending percentage applied to the drawing operation.
+    /// A value of <c>1.0</c> applies the operation at full strength; <c>0.0</c> makes it invisible.
+    /// Valid range is 0 to 1. Defaults to <c>1.0F</c>.
     /// </summary>
     public float BlendPercentage
     {
-        get
-        {
-            return this.blendPercentage;
-        }
+        get => this.blendPercentage;
 
         set
         {
-            Guard.MustBeBetweenOrEqualTo(value, 0, 1F, nameof(this.BlendPercentage));
+            Guard.MustBeBetweenOrEqualTo(value, 0F, 1F, nameof(this.BlendPercentage));
             this.blendPercentage = value;
         }
     }
 
     /// <summary>
-    /// Gets or sets a value indicating the color blending mode to apply to the drawing operation.
+    /// Gets or sets the color blending mode used to combine source and destination pixel colors.
     /// Defaults to <see cref="PixelColorBlendingMode.Normal"/>.
     /// </summary>
     public PixelColorBlendingMode ColorBlendingMode { get; set; } = PixelColorBlendingMode.Normal;
 
     /// <summary>
-    /// Gets or sets a value indicating the alpha composition mode to apply to the drawing operation
+    /// Gets or sets the alpha composition mode that determines how source and destination alpha
+    /// channels are combined using Porter-Duff operators.
     /// Defaults to <see cref="PixelAlphaCompositionMode.SrcOver"/>.
     /// </summary>
     public PixelAlphaCompositionMode AlphaCompositionMode { get; set; } = PixelAlphaCompositionMode.SrcOver;

tests/ImageSharp.Tests/GraphicsOptionsTests.cs

@@ -13,7 +13,7 @@ public class GraphicsOptionsTests
     private readonly GraphicsOptions cloneGraphicsOptions = new GraphicsOptions().DeepClone();
 
     [Fact]
-    public void CloneGraphicsOptionsIsNotNull() => Assert.True(this.cloneGraphicsOptions != null);
+    public void CloneGraphicsOptionsIsNotNull() => Assert.NotNull(this.cloneGraphicsOptions);
 
     [Fact]
     public void DefaultGraphicsOptionsAntialias()
@@ -23,35 +23,35 @@ public void DefaultGraphicsOptionsAntialias()
     }
 
     [Fact]
-    public void DefaultGraphicsOptionsAntialiasSuppixelDepth()
+    public void DefaultGraphicsOptionsAntialiasThreshold()
     {
-        const int Expected = 16;
-        Assert.Equal(Expected, this.newGraphicsOptions.AntialiasSubpixelDepth);
-        Assert.Equal(Expected, this.cloneGraphicsOptions.AntialiasSubpixelDepth);
+        const float expected = .5F;
+        Assert.Equal(expected, this.newGraphicsOptions.AntialiasThreshold);
+        Assert.Equal(expected, this.cloneGraphicsOptions.AntialiasThreshold);
     }
 
     [Fact]
     public void DefaultGraphicsOptionsBlendPercentage()
     {
-        const float Expected = 1F;
-        Assert.Equal(Expected, this.newGraphicsOptions.BlendPercentage);
-        Assert.Equal(Expected, this.cloneGraphicsOptions.BlendPercentage);
+        const float expected = 1F;
+        Assert.Equal(expected, this.newGraphicsOptions.BlendPercentage);
+        Assert.Equal(expected, this.cloneGraphicsOptions.BlendPercentage);
     }
 
     [Fact]
     public void DefaultGraphicsOptionsColorBlendingMode()
     {
-        const PixelColorBlendingMode Expected = PixelColorBlendingMode.Normal;
-        Assert.Equal(Expected, this.newGraphicsOptions.ColorBlendingMode);
-        Assert.Equal(Expected, this.cloneGraphicsOptions.ColorBlendingMode);
+        const PixelColorBlendingMode expected = PixelColorBlendingMode.Normal;
+        Assert.Equal(expected, this.newGraphicsOptions.ColorBlendingMode);
+        Assert.Equal(expected, this.cloneGraphicsOptions.ColorBlendingMode);
     }
 
     [Fact]
     public void DefaultGraphicsOptionsAlphaCompositionMode()
     {
-        const PixelAlphaCompositionMode Expected = PixelAlphaCompositionMode.SrcOver;
-        Assert.Equal(Expected, this.newGraphicsOptions.AlphaCompositionMode);
-        Assert.Equal(Expected, this.cloneGraphicsOptions.AlphaCompositionMode);
+        const PixelAlphaCompositionMode expected = PixelAlphaCompositionMode.SrcOver;
+        Assert.Equal(expected, this.newGraphicsOptions.AlphaCompositionMode);
+        Assert.Equal(expected, this.cloneGraphicsOptions.AlphaCompositionMode);
     }
 
     [Fact]
@@ -61,7 +61,7 @@ public void NonDefaultClone()
         {
             AlphaCompositionMode = PixelAlphaCompositionMode.DestAtop,
             Antialias = false,
-            AntialiasSubpixelDepth = 23,
+            AntialiasThreshold = .33F,
             BlendPercentage = .25F,
             ColorBlendingMode = PixelColorBlendingMode.HardLight,
         };
@@ -79,7 +79,7 @@ public void CloneIsDeep()
 
         actual.AlphaCompositionMode = PixelAlphaCompositionMode.DestAtop;
         actual.Antialias = false;
-        actual.AntialiasSubpixelDepth = 23;
+        actual.AntialiasThreshold = .67F;
         actual.BlendPercentage = .25F;
         actual.ColorBlendingMode = PixelColorBlendingMode.HardLight;
 

tests/ImageSharp.Tests/TestUtilities/GraphicsOptionsComparer.cs

@@ -6,13 +6,11 @@ namespace SixLabors.ImageSharp.Tests.TestUtilities;
 public class GraphicsOptionsComparer : IEqualityComparer<GraphicsOptions>
 {
     public bool Equals(GraphicsOptions x, GraphicsOptions y)
-    {
-        return x.AlphaCompositionMode == y.AlphaCompositionMode
-            && x.Antialias == y.Antialias
-            && x.AntialiasSubpixelDepth == y.AntialiasSubpixelDepth
-            && x.BlendPercentage == y.BlendPercentage
-            && x.ColorBlendingMode == y.ColorBlendingMode;
-    }
+        => x.AlphaCompositionMode == y.AlphaCompositionMode
+        && x.Antialias == y.Antialias
+        && x.AntialiasThreshold == y.AntialiasThreshold
+        && x.BlendPercentage == y.BlendPercentage
+        && x.ColorBlendingMode == y.ColorBlendingMode;
 
     public int GetHashCode(GraphicsOptions obj) => obj.GetHashCode();
 }