Merge pull request #2180 from SixLabors/js/decoder-options

Introduce Shared General Decoder Options plus Specialization

Author: JimBobSquarePants

src/ImageSharp/Advanced/AotCompilerTools.cs

@@ -178,7 +178,7 @@ private static unsafe void AotCompileImage<TPixel>()
             img.CloneAs<Short2>(default);
             img.CloneAs<Short4>(default);
 
-            ImageFrame.LoadPixelData<TPixel>(default, default(ReadOnlySpan<TPixel>), default, default);
+            ImageFrame.LoadPixelData(default, default(ReadOnlySpan<TPixel>), default, default);
             ImageFrame.LoadPixelData<TPixel>(default, default(ReadOnlySpan<byte>), default, default);
         }
 
@@ -217,14 +217,14 @@ private static void AotCompileImageEncoderInternals<TPixel>()
         private static void AotCompileImageDecoderInternals<TPixel>()
             where TPixel : unmanaged, IPixel<TPixel>
         {
-            default(WebpDecoderCore).Decode<TPixel>(default, default, default);
-            default(BmpDecoderCore).Decode<TPixel>(default, default, default);
-            default(GifDecoderCore).Decode<TPixel>(default, default, default);
-            default(JpegDecoderCore).Decode<TPixel>(default, default, default);
-            default(PbmDecoderCore).Decode<TPixel>(default, default, default);
-            default(PngDecoderCore).Decode<TPixel>(default, default, default);
-            default(TgaDecoderCore).Decode<TPixel>(default, default, default);
-            default(TiffDecoderCore).Decode<TPixel>(default, default, default);
+            default(WebpDecoderCore).Decode<TPixel>(default, default);
+            default(BmpDecoderCore).Decode<TPixel>(default, default);
+            default(GifDecoderCore).Decode<TPixel>(default, default);
+            default(JpegDecoderCore).Decode<TPixel>(default, default);
+            default(PbmDecoderCore).Decode<TPixel>(default, default);
+            default(PngDecoderCore).Decode<TPixel>(default, default);
+            default(TgaDecoderCore).Decode<TPixel>(default, default);
+            default(TiffDecoderCore).Decode<TPixel>(default, default);
         }
 
         /// <summary>
@@ -286,9 +286,7 @@ private static void AotCompileImageEncoder<TPixel, TEncoder>()
         private static void AotCompileImageDecoder<TPixel, TDecoder>()
            where TPixel : unmanaged, IPixel<TPixel>
            where TDecoder : class, IImageDecoder
-        {
-            default(TDecoder).Decode<TPixel>(default, default, default);
-        }
+            => default(TDecoder).Decode<TPixel>(default, default, default);
 
         /// <summary>
         /// This method pre-seeds the all <see cref="IImageProcessor" /> in the AoT compiler.

src/ImageSharp/Formats/Bmp/BmpDecoder.cs

@@ -10,43 +10,40 @@ namespace SixLabors.ImageSharp.Formats.Bmp
     /// <summary>
     /// Image decoder for generating an image out of a Windows bitmap stream.
     /// </summary>
-    /// <remarks>
-    /// Does not support the following formats at the moment:
-    /// <list type="bullet">
-    ///    <item>JPG</item>
-    ///    <item>PNG</item>
-    ///    <item>Some OS/2 specific subtypes like: Bitmap Array, Color Icon, Color Pointer, Icon, Pointer.</item>
-    /// </list>
-    /// Formats will be supported in a later releases. We advise always
-    /// to use only 24 Bit Windows bitmaps.
-    /// </remarks>
-    public sealed class BmpDecoder : IImageDecoder, IBmpDecoderOptions, IImageInfoDetector
+    public class BmpDecoder : IImageDecoderSpecialized<BmpDecoderOptions>
     {
-        /// <summary>
-        /// Gets or sets a value indicating how to deal with skipped pixels, which can occur during decoding run length encoded bitmaps.
-        /// </summary>
-        public RleSkippedPixelHandling RleSkippedPixelHandling { get; set; } = RleSkippedPixelHandling.Black;
-
         /// <inheritdoc/>
-        public Image<TPixel> Decode<TPixel>(Configuration configuration, Stream stream, CancellationToken cancellationToken)
-            where TPixel : unmanaged, IPixel<TPixel>
+        IImageInfo IImageInfoDetector.Identify(DecoderOptions options, Stream stream, CancellationToken cancellationToken)
         {
+            Guard.NotNull(options, nameof(options));
             Guard.NotNull(stream, nameof(stream));
 
-            var decoder = new BmpDecoderCore(configuration, this);
-            return decoder.Decode<TPixel>(configuration, stream, cancellationToken);
+            return new BmpDecoderCore(new() { GeneralOptions = options }).Identify(options.Configuration, stream, cancellationToken);
         }
 
-        /// <inheritdoc />
-        public Image Decode(Configuration configuration, Stream stream, CancellationToken cancellationToken)
-            => this.Decode<Rgba32>(configuration, stream, cancellationToken);
+        /// <inheritdoc/>
+        Image<TPixel> IImageDecoder.Decode<TPixel>(DecoderOptions options, Stream stream, CancellationToken cancellationToken)
+            => ((IImageDecoderSpecialized<BmpDecoderOptions>)this).Decode<TPixel>(new() { GeneralOptions = options }, stream, cancellationToken);
+
+        /// <inheritdoc/>
+        Image IImageDecoder.Decode(DecoderOptions options, Stream stream, CancellationToken cancellationToken)
+          => ((IImageDecoderSpecialized<BmpDecoderOptions>)this).Decode(new() { GeneralOptions = options }, stream, cancellationToken);
 
         /// <inheritdoc/>
-        public IImageInfo Identify(Configuration configuration, Stream stream, CancellationToken cancellationToken)
+        Image<TPixel> IImageDecoderSpecialized<BmpDecoderOptions>.Decode<TPixel>(BmpDecoderOptions options, Stream stream, CancellationToken cancellationToken)
         {
+            Guard.NotNull(options, nameof(options));
             Guard.NotNull(stream, nameof(stream));
 
-            return new BmpDecoderCore(configuration, this).Identify(configuration, stream, cancellationToken);
+            Image<TPixel> image = new BmpDecoderCore(options).Decode<TPixel>(options.GeneralOptions.Configuration, stream, cancellationToken);
+
+            ImageDecoderUtilities.Resize(options.GeneralOptions, image);
+
+            return image;
         }
+
+        /// <inheritdoc/>
+        Image IImageDecoderSpecialized<BmpDecoderOptions>.Decode(BmpDecoderOptions options, Stream stream, CancellationToken cancellationToken)
+            => ((IImageDecoderSpecialized<BmpDecoderOptions>)this).Decode<Rgba32>(options, stream, cancellationToken);
     }
 }

src/ImageSharp/Formats/Bmp/BmpDecoderCore.cs

@@ -89,34 +89,38 @@ internal sealed class BmpDecoderCore : IImageDecoderInternals
         /// </summary>
         private BmpInfoHeader infoHeader;
 
+        /// <summary>
+        /// The global configuration.
+        /// </summary>
+        private readonly Configuration configuration;
+
         /// <summary>
         /// Used for allocating memory during processing operations.
         /// </summary>
         private readonly MemoryAllocator memoryAllocator;
 
         /// <summary>
-        /// The bitmap decoder options.
+        /// How to deal with skipped pixels,
+        /// which can occur during decoding run length encoded bitmaps.
         /// </summary>
-        private readonly IBmpDecoderOptions options;
+        private readonly RleSkippedPixelHandling rleSkippedPixelHandling;
 
         /// <summary>
         /// Initializes a new instance of the <see cref="BmpDecoderCore"/> class.
         /// </summary>
-        /// <param name="configuration">The configuration.</param>
         /// <param name="options">The options.</param>
-        public BmpDecoderCore(Configuration configuration, IBmpDecoderOptions options)
+        public BmpDecoderCore(BmpDecoderOptions options)
         {
-            this.Configuration = configuration;
-            this.memoryAllocator = configuration.MemoryAllocator;
-            this.options = options;
+            this.Options = options.GeneralOptions;
+            this.rleSkippedPixelHandling = options.RleSkippedPixelHandling;
+            this.configuration = options.GeneralOptions.Configuration;
+            this.memoryAllocator = this.configuration.MemoryAllocator;
         }
 
         /// <inheritdoc />
-        public Configuration Configuration { get; }
+        public DecoderOptions Options { get; }
 
-        /// <summary>
-        /// Gets the dimensions of the image.
-        /// </summary>
+        /// <inheritdoc />
         public Size Dimensions => new(this.infoHeader.Width, this.infoHeader.Height);
 
         /// <inheritdoc />
@@ -128,7 +132,7 @@ public Image<TPixel> Decode<TPixel>(BufferedReadStream stream, CancellationToken
             {
                 int bytesPerColorMapEntry = this.ReadImageHeaders(stream, out bool inverted, out byte[] palette);
 
-                image = new Image<TPixel>(this.Configuration, this.infoHeader.Width, this.infoHeader.Height, this.metadata);
+                image = new Image<TPixel>(this.configuration, this.infoHeader.Width, this.infoHeader.Height, this.metadata);
 
                 Buffer2D<TPixel> pixels = image.GetRootFramePixelBuffer();
 
@@ -325,7 +329,7 @@ private void ReadRle<TPixel>(BmpCompression compression, Buffer2D<TPixel> pixels
                             byte colorIdx = bufferRow[x];
                             if (undefinedPixelsSpan[rowStartIdx + x])
                             {
-                                switch (this.options.RleSkippedPixelHandling)
+                                switch (this.rleSkippedPixelHandling)
                                 {
                                     case RleSkippedPixelHandling.FirstColorOfPalette:
                                         color.FromBgr24(Unsafe.As<byte, Bgr24>(ref colors[colorIdx * 4]));
@@ -397,7 +401,7 @@ private void ReadRle24<TPixel>(Buffer2D<TPixel> pixels, int width, int height, b
                             int idx = rowStartIdx + (x * 3);
                             if (undefinedPixelsSpan[yMulWidth + x])
                             {
-                                switch (this.options.RleSkippedPixelHandling)
+                                switch (this.rleSkippedPixelHandling)
                                 {
                                     case RleSkippedPixelHandling.FirstColorOfPalette:
                                         color.FromBgr24(Unsafe.As<byte, Bgr24>(ref bufferSpan[idx]));
@@ -943,7 +947,7 @@ private void ReadRgb24<TPixel>(Buffer2D<TPixel> pixels, int width, int height, b
                 int newY = Invert(y, height, inverted);
                 Span<TPixel> pixelSpan = pixels.DangerousGetRowSpan(newY);
                 PixelOperations<TPixel>.Instance.FromBgr24Bytes(
-                    this.Configuration,
+                    this.configuration,
                     rowSpan,
                     pixelSpan,
                     width);
@@ -971,7 +975,7 @@ private void ReadRgb32Fast<TPixel>(Buffer2D<TPixel> pixels, int width, int heigh
                 int newY = Invert(y, height, inverted);
                 Span<TPixel> pixelSpan = pixels.DangerousGetRowSpan(newY);
                 PixelOperations<TPixel>.Instance.FromBgra32Bytes(
-                    this.Configuration,
+                    this.configuration,
                     rowSpan,
                     pixelSpan,
                     width);
@@ -1006,7 +1010,7 @@ private void ReadRgb32Slow<TPixel>(Buffer2D<TPixel> pixels, int width, int heigh
                 this.stream.Read(rowSpan);
 
                 PixelOperations<Bgra32>.Instance.FromBgra32Bytes(
-                    this.Configuration,
+                    this.configuration,
                     rowSpan,
                     bgraRowSpan,
                     width);
@@ -1042,7 +1046,7 @@ private void ReadRgb32Slow<TPixel>(Buffer2D<TPixel> pixels, int width, int heigh
                     Span<TPixel> pixelSpan = pixels.DangerousGetRowSpan(newY);
 
                     PixelOperations<TPixel>.Instance.FromBgra32Bytes(
-                        this.Configuration,
+                        this.configuration,
                         rowSpan,
                         pixelSpan,
                         width);
@@ -1056,7 +1060,7 @@ private void ReadRgb32Slow<TPixel>(Buffer2D<TPixel> pixels, int width, int heigh
             {
                 this.stream.Read(rowSpan);
                 PixelOperations<Bgra32>.Instance.FromBgra32Bytes(
-                    this.Configuration,
+                    this.configuration,
                     rowSpan,
                     bgraRowSpan,
                     width);

src/ImageSharp/Formats/Bmp/BmpDecoderOptions.cs

@@ -0,0 +1,20 @@
+// Copyright (c) Six Labors.
+// Licensed under the Six Labors Split License.
+
+namespace SixLabors.ImageSharp.Formats.Bmp
+{
+    /// <summary>
+    /// Configuration options for decoding Windows Bitmap images.
+    /// </summary>
+    public sealed class BmpDecoderOptions : ISpecializedDecoderOptions
+    {
+        /// <inheritdoc/>
+        public DecoderOptions GeneralOptions { get; set; } = new();
+
+        /// <summary>
+        /// Gets or sets the value indicating how to deal with skipped pixels,
+        /// which can occur during decoding run length encoded bitmaps.
+        /// </summary>
+        public RleSkippedPixelHandling RleSkippedPixelHandling { get; set; }
+    }
+}

src/ImageSharp/Formats/Bmp/IBmpDecoderOptions.cs

@@ -0,0 +1,49 @@
+// Copyright (c) Six Labors.
+// Licensed under the Six Labors Split License.
+
+using System;
+using SixLabors.ImageSharp.Processing;
+using SixLabors.ImageSharp.Processing.Processors.Transforms;
+
+namespace SixLabors.ImageSharp.Formats
+{
+    /// <summary>
+    /// Provides general configuration options for decoding image formats.
+    /// </summary>
+    public sealed class DecoderOptions
+    {
+        private static readonly Lazy<DecoderOptions> LazyOptions = new(() => new());
+
+        private uint maxFrames = int.MaxValue;
+
+        /// <summary>
+        /// Gets the shared default general decoder options instance.
+        /// </summary>
+        internal static DecoderOptions Default { get; } = LazyOptions.Value;
+
+        /// <summary>
+        /// Gets or sets a custom Configuration instance to be used by the image processing pipeline.
+        /// </summary>
+        public Configuration Configuration { get; set; } = Configuration.Default;
+
+        /// <summary>
+        /// Gets or sets the target size to decode the image into.
+        /// </summary>
+        public Size? TargetSize { get; set; } = null;
+
+        /// <summary>
+        /// Gets or sets the sampler to use when resizing during decoding.
+        /// </summary>
+        public IResampler Sampler { get; set; } = KnownResamplers.Box;
+
+        /// <summary>
+        /// Gets or sets a value indicating whether to ignore encoded metadata when decoding.
+        /// </summary>
+        public bool SkipMetadata { get; set; } = false;
+
+        /// <summary>
+        /// Gets or sets the maximum number of image frames to decode, inclusive.
+        /// </summary>
+        public uint MaxFrames { get => this.maxFrames; set => this.maxFrames = Math.Clamp(value, 1, int.MaxValue); }
+    }
+}

src/ImageSharp/Formats/DecoderOptions.cs

@@ -3,45 +3,40 @@
 
 using System.IO;
 using System.Threading;
-using SixLabors.ImageSharp.Metadata;
 using SixLabors.ImageSharp.PixelFormats;
 
 namespace SixLabors.ImageSharp.Formats.Gif
 {
     /// <summary>
     /// Decoder for generating an image out of a gif encoded stream.
     /// </summary>
-    public sealed class GifDecoder : IImageDecoder, IGifDecoderOptions, IImageInfoDetector
+    public sealed class GifDecoder : IImageDecoder
     {
-        /// <summary>
-        /// Gets or sets a value indicating whether the metadata should be ignored when the image is being decoded.
-        /// </summary>
-        public bool IgnoreMetadata { get; set; } = false;
-
-        /// <summary>
-        /// Gets or sets the decoding mode for multi-frame images
-        /// </summary>
-        public FrameDecodingMode DecodingMode { get; set; } = FrameDecodingMode.All;
-
         /// <inheritdoc/>
-        public Image<TPixel> Decode<TPixel>(Configuration configuration, Stream stream, CancellationToken cancellationToken)
-            where TPixel : unmanaged, IPixel<TPixel>
+        IImageInfo IImageInfoDetector.Identify(DecoderOptions options, Stream stream, CancellationToken cancellationToken)
         {
-            var decoder = new GifDecoderCore(configuration, this);
-            return decoder.Decode<TPixel>(configuration, stream, cancellationToken);
-        }
+            Guard.NotNull(options, nameof(options));
+            Guard.NotNull(stream, nameof(stream));
 
-        /// <inheritdoc />
-        public Image Decode(Configuration configuration, Stream stream, CancellationToken cancellationToken)
-            => this.Decode<Rgba32>(configuration, stream, cancellationToken);
+            return new GifDecoderCore(options).Identify(options.Configuration, stream, cancellationToken);
+        }
 
         /// <inheritdoc/>
-        public IImageInfo Identify(Configuration configuration, Stream stream, CancellationToken cancellationToken)
+        Image<TPixel> IImageDecoder.Decode<TPixel>(DecoderOptions options, Stream stream, CancellationToken cancellationToken)
         {
+            Guard.NotNull(options, nameof(options));
             Guard.NotNull(stream, nameof(stream));
 
-            var decoder = new GifDecoderCore(configuration, this);
-            return decoder.Identify(configuration, stream, cancellationToken);
+            GifDecoderCore decoder = new(options);
+            Image<TPixel> image = decoder.Decode<TPixel>(options.Configuration, stream, cancellationToken);
+
+            ImageDecoderUtilities.Resize(options, image);
+
+            return image;
         }
+
+        /// <inheritdoc/>
+        Image IImageDecoder.Decode(DecoderOptions options, Stream stream, CancellationToken cancellationToken)
+            => ((IImageDecoder)this).Decode<Rgba32>(options, stream, cancellationToken);
     }
 }