Normalize handling of transparent pixels with color components on encode.

Author: JimBobSquarePants

src/ImageSharp/Formats/AlphaAwareImageEncoder.cs

@@ -0,0 +1,15 @@
+// Copyright (c) Six Labors.
+// Licensed under the Six Labors Split License.
+
+namespace SixLabors.ImageSharp.Formats;
+
+/// <summary>
+/// Acts as a base encoder for all formats that are aware of and can handle alpha transparency.
+/// </summary>
+public abstract class AlphaAwareImageEncoder : ImageEncoder
+{
+    /// <summary>
+    /// Gets or initializes the mode that determines how transparent pixels are handled during encoding.
+    /// </summary>
+    public TransparentColorMode TransparentColorMode { get; init; }
+}

src/ImageSharp/Formats/Bmp/BmpEncoderCore.cs

@@ -0,0 +1,97 @@
+// Copyright (c) Six Labors.
+// Licensed under the Six Labors Split License.
+
+using System.Buffers;
+using System.Numerics;
+using System.Runtime.Intrinsics;
+using SixLabors.ImageSharp.Memory;
+using SixLabors.ImageSharp.PixelFormats;
+
+namespace SixLabors.ImageSharp.Formats;
+
+/// <summary>
+/// Provides utilities for encoding images.
+/// </summary>
+internal static class EncodingUtilities
+{
+    public static bool ShouldClearTransparentPixels<TPixel>(TransparentColorMode mode)
+        where TPixel : unmanaged, IPixel<TPixel>
+        => mode == TransparentColorMode.Clear &&
+                   TPixel.GetPixelTypeInfo().AlphaRepresentation == PixelAlphaRepresentation.Unassociated;
+
+    /// <summary>
+    /// Convert transparent pixels, to pixels represented by <paramref name="color"/>, which can yield
+    /// to better compression in some cases.
+    /// </summary>
+    /// <typeparam name="TPixel">The type of the pixel.</typeparam>
+    /// <param name="clone">The cloned <see cref="ImageFrame{TPixel}"/> where the transparent pixels will be changed.</param>
+    /// <param name="color">The color to replace transparent pixels with.</param>
+    public static void ClearTransparentPixels<TPixel>(ImageFrame<TPixel> clone, Color color)
+        where TPixel : unmanaged, IPixel<TPixel>
+    {
+        Buffer2DRegion<TPixel> buffer = clone.PixelBuffer.GetRegion();
+        ClearTransparentPixels(clone.Configuration, ref buffer, color);
+    }
+
+    /// <summary>
+    /// Convert transparent pixels, to pixels represented by <paramref name="color"/>, which can yield
+    /// to better compression in some cases.
+    /// </summary>
+    /// <typeparam name="TPixel">The type of the pixel.</typeparam>
+    /// <param name="configuration">The configuration.</param>
+    /// <param name="clone">The cloned <see cref="Buffer2DRegion{T}"/> where the transparent pixels will be changed.</param>
+    /// <param name="color">The color to replace transparent pixels with.</param>
+    public static void ClearTransparentPixels<TPixel>(
+        Configuration configuration,
+        ref Buffer2DRegion<TPixel> clone,
+        Color color)
+        where TPixel : unmanaged, IPixel<TPixel>
+    {
+        using IMemoryOwner<Vector4> vectors = configuration.MemoryAllocator.Allocate<Vector4>(clone.Width);
+        Span<Vector4> vectorsSpan = vectors.GetSpan();
+        Vector4 replacement = color.ToScaledVector4();
+        for (int y = 0; y < clone.Height; y++)
+        {
+            Span<TPixel> span = clone.DangerousGetRowSpan(y);
+            PixelOperations<TPixel>.Instance.ToVector4(configuration, span, vectorsSpan, PixelConversionModifiers.Scale);
+            ClearTransparentPixelRow(vectorsSpan, replacement);
+            PixelOperations<TPixel>.Instance.FromVector4Destructive(configuration, vectorsSpan, span, PixelConversionModifiers.Scale);
+        }
+    }
+
+    private static void ClearTransparentPixelRow(
+        Span<Vector4> vectorsSpan,
+        Vector4 replacement)
+    {
+        if (Vector128.IsHardwareAccelerated)
+        {
+            Vector128<float> replacement128 = replacement.AsVector128();
+
+            for (int i = 0; i < vectorsSpan.Length; i++)
+            {
+                ref Vector4 v = ref vectorsSpan[i];
+                Vector128<float> v128 = v.AsVector128();
+
+                // Do `vector == 0`
+                Vector128<float> mask = Vector128.Equals(v128, Vector128<float>.Zero);
+
+                // Replicate the result for W to all elements (is AllBitsSet if the W was 0 and Zero otherwise)
+                mask = Vector128.Shuffle(mask, Vector128.Create(3, 3, 3, 3));
+
+                // Use the mask to select the replacement vector
+                // (replacement & mask) | (v128 & ~mask)
+                v = Vector128.ConditionalSelect(mask, replacement128, v128).AsVector4();
+            }
+        }
+        else
+        {
+            for (int i = 0; i < vectorsSpan.Length; i++)
+            {
+                if (vectorsSpan[i].W == 0F)
+                {
+                    vectorsSpan[i] = replacement;
+                }
+            }
+        }
+    }
+}

src/ImageSharp/Formats/EncodingUtilities.cs

@@ -665,7 +665,7 @@ private void RestoreToBackground<TPixel>(ImageFrame<TPixel> frame)
             return;
         }
 
-        Rectangle interest = Rectangle.Intersect(frame.Bounds(), this.restoreArea.Value);
+        Rectangle interest = Rectangle.Intersect(frame.Bounds, this.restoreArea.Value);
         Buffer2DRegion<TPixel> pixelRegion = frame.PixelBuffer.GetRegion(interest);
         pixelRegion.Clear();
 

src/ImageSharp/Formats/Gif/GifDecoderCore.cs

@@ -67,6 +67,8 @@ internal sealed class GifEncoderCore
     /// </summary>
     private readonly ushort? repeatCount;
 
+    private readonly TransparentColorMode transparentColorMode;
+
     /// <summary>
     /// Initializes a new instance of the <see cref="GifEncoderCore"/> class.
     /// </summary>
@@ -83,6 +85,7 @@ public GifEncoderCore(Configuration configuration, GifEncoder encoder)
         this.pixelSamplingStrategy = encoder.PixelSamplingStrategy;
         this.backgroundColor = encoder.BackgroundColor;
         this.repeatCount = encoder.RepeatCount;
+        this.transparentColorMode = encoder.TransparentColorMode;
     }
 
     /// <summary>
@@ -131,18 +134,40 @@ public void Encode<TPixel>(Image<TPixel> image, Stream stream, CancellationToken
             }
         }
 
+        // Quantize the first frame. Checking to see whether we can clear the transparent pixels
+        // to allow for a smaller color palette and encoded result.
         using (IQuantizer<TPixel> frameQuantizer = this.quantizer.CreatePixelSpecificQuantizer<TPixel>(this.configuration))
         {
+            ImageFrame<TPixel>? clonedFrame = null;
+            Configuration configuration = this.configuration;
+            TransparentColorMode mode = this.transparentColorMode;
+            IPixelSamplingStrategy strategy = this.pixelSamplingStrategy;
+            if (EncodingUtilities.ShouldClearTransparentPixels<TPixel>(mode))
+            {
+                clonedFrame = image.Frames.RootFrame.Clone();
+
+                GifFrameMetadata frameMeta = clonedFrame.Metadata.GetGifMetadata();
+                Color background = frameMeta.DisposalMode == FrameDisposalMode.RestoreToBackground
+                    ? this.backgroundColor ?? Color.Transparent
+                    : Color.Transparent;
+
+                EncodingUtilities.ClearTransparentPixels(clonedFrame, background);
+            }
+
+            ImageFrame<TPixel> encodingFrame = clonedFrame ?? image.Frames.RootFrame;
+
             if (useGlobalTable)
             {
-                frameQuantizer.BuildPalette(this.pixelSamplingStrategy, image);
-                quantized = frameQuantizer.QuantizeFrame(image.Frames.RootFrame, image.Bounds);
+                frameQuantizer.BuildPalette(configuration, mode, strategy, image);
+                quantized = frameQuantizer.QuantizeFrame(encodingFrame, image.Bounds);
             }
             else
             {
-                frameQuantizer.BuildPalette(this.pixelSamplingStrategy, image.Frames.RootFrame);
-                quantized = frameQuantizer.QuantizeFrame(image.Frames.RootFrame, image.Bounds);
+                frameQuantizer.BuildPalette(configuration, mode, strategy, encodingFrame);
+                quantized = frameQuantizer.QuantizeFrame(encodingFrame, image.Bounds);
             }
+
+            clonedFrame?.Dispose();
         }
 
         // Write the header.
@@ -236,52 +261,49 @@ private void EncodeAdditionalFrames<TPixel>(
         // This frame is reused to store de-duplicated pixel buffers.
         using ImageFrame<TPixel> encodingFrame = new(previousFrame.Configuration, previousFrame.Size);
 
-        for (int i = 1; i < image.Frames.Count; i++)
+        try
         {
-            if (cancellationToken.IsCancellationRequested)
+            for (int i = 1; i < image.Frames.Count; i++)
             {
-                if (hasPaletteQuantizer)
-                {
-                    paletteQuantizer.Dispose();
-                }
+                cancellationToken.ThrowIfCancellationRequested();
 
-                return;
-            }
+                // Gather the metadata for this frame.
+                ImageFrame<TPixel> currentFrame = image.Frames[i];
+                ImageFrame<TPixel>? nextFrame = i < image.Frames.Count - 1 ? image.Frames[i + 1] : null;
+                GifFrameMetadata gifMetadata = GetGifFrameMetadata(currentFrame, globalTransparencyIndex);
+                bool useLocal = this.colorTableMode == FrameColorTableMode.Local || (gifMetadata.ColorTableMode == FrameColorTableMode.Local);
 
-            // Gather the metadata for this frame.
-            ImageFrame<TPixel> currentFrame = image.Frames[i];
-            ImageFrame<TPixel>? nextFrame = i < image.Frames.Count - 1 ? image.Frames[i + 1] : null;
-            GifFrameMetadata gifMetadata = GetGifFrameMetadata(currentFrame, globalTransparencyIndex);
-            bool useLocal = this.colorTableMode == FrameColorTableMode.Local || (gifMetadata.ColorTableMode == FrameColorTableMode.Local);
+                if (!useLocal && !hasPaletteQuantizer && i > 0)
+                {
+                    // The palette quantizer can reuse the same global pixel map across multiple frames since the palette is unchanging.
+                    // This allows a reduction of memory usage across multi-frame gifs using a global palette
+                    // and also allows use to reuse the cache from previous runs.
+                    int transparencyIndex = gifMetadata.HasTransparency ? gifMetadata.TransparencyIndex : -1;
+                    paletteQuantizer = new(this.configuration, this.quantizer!.Options, globalPalette, transparencyIndex);
+                    hasPaletteQuantizer = true;
+                }
 
-            if (!useLocal && !hasPaletteQuantizer && i > 0)
-            {
-                // The palette quantizer can reuse the same global pixel map across multiple frames since the palette is unchanging.
-                // This allows a reduction of memory usage across multi-frame gifs using a global palette
-                // and also allows use to reuse the cache from previous runs.
-                int transparencyIndex = gifMetadata.HasTransparency ? gifMetadata.TransparencyIndex : -1;
-                paletteQuantizer = new(this.configuration, this.quantizer!.Options, globalPalette, transparencyIndex);
-                hasPaletteQuantizer = true;
+                this.EncodeAdditionalFrame(
+                    stream,
+                    previousFrame,
+                    currentFrame,
+                    nextFrame,
+                    encodingFrame,
+                    useLocal,
+                    gifMetadata,
+                    paletteQuantizer,
+                    previousDisposalMode);
+
+                previousFrame = currentFrame;
+                previousDisposalMode = gifMetadata.DisposalMode;
             }
-
-            this.EncodeAdditionalFrame(
-                stream,
-                previousFrame,
-                currentFrame,
-                nextFrame,
-                encodingFrame,
-                useLocal,
-                gifMetadata,
-                paletteQuantizer,
-                previousDisposalMode);
-
-            previousFrame = currentFrame;
-            previousDisposalMode = gifMetadata.DisposalMode;
         }
-
-        if (hasPaletteQuantizer)
+        finally
         {
-            paletteQuantizer.Dispose();
+            if (hasPaletteQuantizer)
+            {
+                paletteQuantizer.Dispose();
+            }
         }
     }
 
@@ -324,7 +346,9 @@ private void EncodeAdditionalFrame<TPixel>(
         // We use it to determine the value to use to replace duplicate pixels.
         int transparencyIndex = metadata.HasTransparency ? metadata.TransparencyIndex : -1;
 
-        ImageFrame<TPixel>? previous = previousDisposalMode == FrameDisposalMode.RestoreToBackground ? null : previousFrame;
+        ImageFrame<TPixel>? previous = previousDisposalMode == FrameDisposalMode.RestoreToBackground
+            ? null :
+            previousFrame;
 
         Color background = metadata.DisposalMode == FrameDisposalMode.RestoreToBackground
             ? this.backgroundColor ?? Color.Transparent
@@ -341,6 +365,11 @@ private void EncodeAdditionalFrame<TPixel>(
                 background,
                 true);
 
+        if (EncodingUtilities.ShouldClearTransparentPixels<TPixel>(this.transparentColorMode))
+        {
+            EncodingUtilities.ClearTransparentPixels(encodingFrame, background);
+        }
+
         using IndexedImageFrame<TPixel> quantized = this.QuantizeAdditionalFrameAndUpdateMetadata(
                 encodingFrame,
                 bounds,

src/ImageSharp/Formats/Gif/GifEncoderCore.cs

@@ -30,7 +30,7 @@ public interface IAnimatedImageEncoder
 /// <summary>
 /// Acts as a base class for all image encoders that allow encoding animation sequences.
 /// </summary>
-public abstract class AnimatedImageEncoder : ImageEncoder, IAnimatedImageEncoder
+public abstract class AnimatedImageEncoder : AlphaAwareImageEncoder, IAnimatedImageEncoder
 {
     /// <inheritdoc/>
     public Color? BackgroundColor { get; init; }

src/ImageSharp/Formats/IAnimatedImageEncoder.cs

@@ -24,7 +24,7 @@ public interface IQuantizingImageEncoder
 /// <summary>
 /// Acts as a base class for all image encoders that allow color palette generation via quantization.
 /// </summary>
-public abstract class QuantizingImageEncoder : ImageEncoder, IQuantizingImageEncoder
+public abstract class QuantizingImageEncoder : AlphaAwareImageEncoder, IQuantizingImageEncoder
 {
     /// <inheritdoc/>
     public IQuantizer? Quantizer { get; init; }

src/ImageSharp/Formats/IQuantizingImageEncoder.cs

@@ -63,7 +63,6 @@ public void Encode<TPixel>(
             this.entries[i].Entry.ImageOffset = (uint)stream.Position;
 
             // We crop the frame to the size specified in the metadata.
-            // TODO: we can optimize this by cropping the frame only if the new size is both required and different.
             using Image<TPixel> encodingFrame = new(width, height);
             for (int y = 0; y < height; y++)
             {
@@ -82,6 +81,8 @@ public void Encode<TPixel>(
                     UseDoubleHeight = true,
                     SkipFileHeader = true,
                     SupportTransparency = false,
+                    TransparentColorMode = this.encoder.TransparentColorMode,
+                    PixelSamplingStrategy = this.encoder.PixelSamplingStrategy,
                     BitsPerPixel = encodingMetadata.BmpBitsPerPixel
                 },
                 IconFrameCompression.Png => new PngEncoder()
@@ -90,6 +91,7 @@ public void Encode<TPixel>(
                     // https://devblogs.microsoft.com/oldnewthing/20101022-00/?p=12473
                     BitDepth = PngBitDepth.Bit8,
                     ColorType = PngColorType.RgbWithAlpha,
+                    TransparentColorMode = this.encoder.TransparentColorMode,
                     CompressionLevel = PngCompressionLevel.BestCompression
                 },
                 _ => throw new NotSupportedException(),

src/ImageSharp/Formats/Icon/IconEncoderCore.cs

@@ -68,12 +68,6 @@ public PngEncoder()
     /// </summary>
     public PngChunkFilter? ChunkFilter { get; init; }
 
-    /// <summary>
-    /// Gets a value indicating whether fully transparent pixels that may contain R, G, B values which are not 0,
-    /// should be converted to transparent black, which can yield in better compression in some cases.
-    /// </summary>
-    public PngTransparentColorMode TransparentColorMode { get; init; }
-
     /// <inheritdoc/>
     protected override void Encode<TPixel>(Image<TPixel> image, Stream stream, CancellationToken cancellationToken)
     {