Normalize encoders and update refs

Author: JimBobSquarePants

src/ImageSharp/Formats/FormatConnectingMetadata.cs

@@ -45,7 +45,7 @@ public class FormatConnectingMetadata
     /// Gets the default background color of the canvas when animating.
     /// This color may be used to fill the unused space on the canvas around the frames,
     /// as well as the transparent pixels of the first frame.
-    /// The background color is also used when the disposal mode is <see cref="FrameDisposalMode.RestoreToBackground"/>.
+    /// The background color is also used when a frame disposal mode is <see cref="FrameDisposalMode.RestoreToBackground"/>.
     /// </summary>
     /// <remarks>
     /// Defaults to <see cref="Color.Transparent"/>.

src/ImageSharp/Formats/Gif/GifEncoder.cs

@@ -6,7 +6,7 @@ namespace SixLabors.ImageSharp.Formats.Gif;
 /// <summary>
 /// Image encoder for writing image data to a stream in gif format.
 /// </summary>
-public sealed class GifEncoder : QuantizingImageEncoder
+public sealed class GifEncoder : QuantizingAnimatedImageEncoder
 {
     /// <summary>
     /// Gets the color table mode: Global or local.

src/ImageSharp/Formats/Gif/GifEncoderCore.cs

@@ -54,6 +54,19 @@ internal sealed class GifEncoderCore
     /// </summary>
     private readonly IPixelSamplingStrategy pixelSamplingStrategy;
 
+    /// <summary>
+    /// The default background color of the canvas when animating.
+    /// This color may be used to fill the unused space on the canvas around the frames,
+    /// as well as the transparent pixels of the first frame.
+    /// The background color is also used when a frame disposal mode is <see cref="FrameDisposalMode.RestoreToBackground"/>.
+    /// </summary>
+    private readonly Color? backgroundColor;
+
+    /// <summary>
+    /// The number of times any animation is repeated.
+    /// </summary>
+    private readonly ushort? repeatCount;
+
     /// <summary>
     /// Initializes a new instance of the <see cref="GifEncoderCore"/> class.
     /// </summary>
@@ -68,6 +81,8 @@ public GifEncoderCore(Configuration configuration, GifEncoder encoder)
         this.hasQuantizer = encoder.Quantizer is not null;
         this.colorTableMode = encoder.ColorTableMode;
         this.pixelSamplingStrategy = encoder.PixelSamplingStrategy;
+        this.backgroundColor = encoder.BackgroundColor;
+        this.repeatCount = encoder.RepeatCount;
     }
 
     /// <summary>
@@ -141,9 +156,17 @@ public void Encode<TPixel>(Image<TPixel> image, Stream stream, CancellationToken
             frameMetadata.TransparencyIndex = ClampIndex(derivedTransparencyIndex);
         }
 
-        byte backgroundIndex = derivedTransparencyIndex >= 0
-            ? frameMetadata.TransparencyIndex
-            : gifMetadata.BackgroundColorIndex;
+        byte backgroundIndex;
+        if (this.backgroundColor.HasValue)
+        {
+            backgroundIndex = GetBackgroundIndex(quantized, this.backgroundColor.Value);
+        }
+        else
+        {
+            backgroundIndex = derivedTransparencyIndex >= 0
+               ? frameMetadata.TransparencyIndex
+               : gifMetadata.BackgroundColorIndex;
+        }
 
         // Get the number of bits.
         int bitDepth = ColorNumerics.GetBitsNeededForColorDepth(quantized.Palette.Length);
@@ -161,15 +184,21 @@ public void Encode<TPixel>(Image<TPixel> image, Stream stream, CancellationToken
 
             // Write application extensions.
             XmpProfile? xmpProfile = image.Metadata.XmpProfile ?? image.Frames.RootFrame.Metadata.XmpProfile;
-            this.WriteApplicationExtensions(stream, image.Frames.Count, gifMetadata.RepeatCount, xmpProfile);
+            this.WriteApplicationExtensions(stream, image.Frames.Count, this.repeatCount ?? gifMetadata.RepeatCount, xmpProfile);
         }
 
         this.EncodeFirstFrame(stream, frameMetadata, quantized);
 
         // Capture the global palette for reuse on subsequent frames and cleanup the quantized frame.
         TPixel[] globalPalette = image.Frames.Count == 1 ? [] : quantized.Palette.ToArray();
 
-        this.EncodeAdditionalFrames(stream, image, globalPalette, derivedTransparencyIndex, frameMetadata.DisposalMode);
+        this.EncodeAdditionalFrames(
+            stream,
+            image,
+            globalPalette,
+            derivedTransparencyIndex,
+            frameMetadata.DisposalMode,
+            cancellationToken);
 
         stream.WriteByte(GifConstants.EndIntroducer);
 
@@ -194,7 +223,8 @@ private void EncodeAdditionalFrames<TPixel>(
         Image<TPixel> image,
         ReadOnlyMemory<TPixel> globalPalette,
         int globalTransparencyIndex,
-        FrameDisposalMode previousDisposalMode)
+        FrameDisposalMode previousDisposalMode,
+        CancellationToken cancellationToken)
         where TPixel : unmanaged, IPixel<TPixel>
     {
         if (image.Frames.Count == 1)
@@ -213,6 +243,16 @@ private void EncodeAdditionalFrames<TPixel>(
 
         for (int i = 1; i < image.Frames.Count; i++)
         {
+            if (cancellationToken.IsCancellationRequested)
+            {
+                if (hasPaletteQuantizer)
+                {
+                    paletteQuantizer.Dispose();
+                }
+
+                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;
@@ -291,6 +331,10 @@ private void EncodeAdditionalFrame<TPixel>(
 
         ImageFrame<TPixel>? previous = previousDisposalMode == FrameDisposalMode.RestoreToBackground ? null : previousFrame;
 
+        Color background = metadata.DisposalMode == FrameDisposalMode.RestoreToBackground
+            ? this.backgroundColor ?? Color.Transparent
+            : Color.Transparent;
+
         // Deduplicate and quantize the frame capturing only required parts.
         (bool difference, Rectangle bounds) =
             AnimationUtilities.DeDuplicatePixels(
@@ -299,7 +343,7 @@ private void EncodeAdditionalFrame<TPixel>(
                 currentFrame,
                 nextFrame,
                 encodingFrame,
-                Color.Transparent,
+                background,
                 true);
 
         using IndexedImageFrame<TPixel> quantized = this.QuantizeAdditionalFrameAndUpdateMetadata(
@@ -428,14 +472,12 @@ private IndexedImageFrame<TPixel> QuantizeAdditionalFrameAndUpdateMetadata<TPixe
     private static byte ClampIndex(int value) => (byte)Numerics.Clamp(value, byte.MinValue, byte.MaxValue);
 
     /// <summary>
-    /// Returns the index of the most transparent color in the palette.
+    /// Returns the index of the transparent color in the palette.
     /// </summary>
     /// <param name="quantized">The current quantized frame.</param>
     /// <param name="metadata">The current gif frame metadata.</param>
     /// <typeparam name="TPixel">The pixel format.</typeparam>
-    /// <returns>
-    /// The <see cref="int"/>.
-    /// </returns>
+    /// <returns>The <see cref="int"/>.</returns>
     private static int GetTransparentIndex<TPixel>(IndexedImageFrame<TPixel>? quantized, GifFrameMetadata? metadata)
         where TPixel : unmanaged, IPixel<TPixel>
     {
@@ -463,6 +505,36 @@ private static int GetTransparentIndex<TPixel>(IndexedImageFrame<TPixel>? quanti
         return index;
     }
 
+    /// <summary>
+    /// Returns the index of the background color in the palette.
+    /// </summary>
+    /// <param name="quantized">The current quantized frame.</param>
+    /// <param name="background">The background color to match.</param>
+    /// <typeparam name="TPixel">The pixel format.</typeparam>
+    /// <returns>The <see cref="byte"/>.</returns>
+    private static byte GetBackgroundIndex<TPixel>(IndexedImageFrame<TPixel>? quantized, Color background)
+        where TPixel : unmanaged, IPixel<TPixel>
+    {
+        int index = -1;
+        if (quantized != null)
+        {
+            TPixel backgroundPixel = background.ToPixel<TPixel>();
+            ReadOnlySpan<TPixel> palette = quantized.Palette.Span;
+            for (int i = 0; i < palette.Length; i++)
+            {
+                if (!backgroundPixel.Equals(palette[i]))
+                {
+                    continue;
+                }
+
+                index = i;
+                break;
+            }
+        }
+
+        return (byte)Numerics.Clamp(index, 0, 255);
+    }
+
     /// <summary>
     /// Writes the file header signature and version to the stream.
     /// </summary>

src/ImageSharp/Formats/IAnimatedImageEncoder.cs

@@ -0,0 +1,43 @@
+// Copyright (c) Six Labors.
+// Licensed under the Six Labors Split License.
+
+namespace SixLabors.ImageSharp.Formats;
+
+/// <summary>
+/// Defines the contract for all image encoders that allow encoding animation sequences.
+/// </summary>
+public interface IAnimatedImageEncoder
+{
+    /// <summary>
+    /// Gets the default background color of the canvas when animating in supported encoders.
+    /// This color may be used to fill the unused space on the canvas around the frames,
+    /// as well as the transparent pixels of the first frame.
+    /// The background color is also used when a frame disposal mode is <see cref="FrameDisposalMode.RestoreToBackground"/>.
+    /// </summary>
+    Color? BackgroundColor { get; }
+
+    /// <summary>
+    /// Gets the number of times any animation is repeated in supported encoders.
+    /// </summary>
+    ushort? RepeatCount { get; }
+
+    /// <summary>
+    /// Gets a value indicating whether the root frame is shown as part of the animated sequence in supported encoders.
+    /// </summary>
+    bool? AnimateRootFrame { get; }
+}
+
+/// <summary>
+/// Acts as a base class for all image encoders that allow encoding animation sequences.
+/// </summary>
+public abstract class AnimatedImageEncoder : ImageEncoder, IAnimatedImageEncoder
+{
+    /// <inheritdoc/>
+    public Color? BackgroundColor { get; init; }
+
+    /// <inheritdoc/>
+    public ushort? RepeatCount { get; init; }
+
+    /// <inheritdoc/>
+    public bool? AnimateRootFrame { get; init; } = true;
+}

src/ImageSharp/Formats/IQuantizingImageEncoder.cs

@@ -0,0 +1,50 @@
+// Copyright (c) Six Labors.
+// Licensed under the Six Labors Split License.
+
+using SixLabors.ImageSharp.Processing.Processors.Quantization;
+
+namespace SixLabors.ImageSharp.Formats;
+
+/// <summary>
+/// Defines the contract for all image encoders that allow color palette generation via quantization.
+/// </summary>
+public interface IQuantizingImageEncoder
+{
+    /// <summary>
+    /// Gets the quantizer used to generate the color palette.
+    /// </summary>
+    IQuantizer? Quantizer { get; }
+
+    /// <summary>
+    /// Gets the <see cref="IPixelSamplingStrategy"/> used for quantization when building color palettes.
+    /// </summary>
+    IPixelSamplingStrategy PixelSamplingStrategy { get; }
+}
+
+/// <summary>
+/// Acts as a base class for all image encoders that allow color palette generation via quantization.
+/// </summary>
+public abstract class QuantizingImageEncoder : ImageEncoder, IQuantizingImageEncoder
+{
+    /// <inheritdoc/>
+    public IQuantizer? Quantizer { get; init; }
+
+    /// <inheritdoc/>
+    public IPixelSamplingStrategy PixelSamplingStrategy { get; init; } = new DefaultPixelSamplingStrategy();
+}
+
+/// <summary>
+/// Acts as a base class for all image encoders that allow color palette generation via quantization when
+/// encoding animation sequences.
+/// </summary>
+public abstract class QuantizingAnimatedImageEncoder : QuantizingImageEncoder, IAnimatedImageEncoder
+{
+    /// <inheritdoc/>
+    public Color? BackgroundColor { get; }
+
+    /// <inheritdoc/>
+    public ushort? RepeatCount { get; }
+
+    /// <inheritdoc/>
+    public bool? AnimateRootFrame { get; }
+}

src/ImageSharp/Formats/Png/PngEncoder.cs

@@ -1,6 +1,5 @@
 // Copyright (c) Six Labors.
 // Licensed under the Six Labors Split License.
-#nullable disable
 
 using SixLabors.ImageSharp.Processing.Processors.Quantization;
 
@@ -9,7 +8,7 @@ namespace SixLabors.ImageSharp.Formats.Png;
 /// <summary>
 /// Image encoder for writing image data to a stream in png format.
 /// </summary>
-public class PngEncoder : QuantizingImageEncoder
+public class PngEncoder : QuantizingAnimatedImageEncoder
 {
     /// <summary>
     /// Initializes a new instance of the <see cref="PngEncoder"/> class.