Merge pull request #1196 from SixLabors/sw/fake-async-codecs

Async APIs / Fake Async Codecs

Author: JimBobSquarePants

src/ImageSharp/Advanced/AdvancedImageExtensions.cs

@@ -2,9 +2,11 @@
 // Licensed under the Apache License, Version 2.0.
 
 using System;
-using System.Linq;
-using System.Runtime.InteropServices;
-
+using System.Collections.Generic;
+using System.IO;
+using System.Text;
+using System.Threading.Tasks;
+using SixLabors.ImageSharp.Formats;
 using SixLabors.ImageSharp.Memory;
 using SixLabors.ImageSharp.PixelFormats;
 
@@ -15,15 +17,66 @@ namespace SixLabors.ImageSharp.Advanced
     /// </summary>
     public static class AdvancedImageExtensions
     {
+        /// <summary>
+        /// For a given file path find the best encoder to use via its extension.
+        /// </summary>
+        /// <param name="source">The source image.</param>
+        /// <param name="filePath">The target file path to save the image to.</param>
+        /// <returns>The matching encoder.</returns>
+        public static IImageEncoder DetectEncoder(this Image source, string filePath)
+        {
+            Guard.NotNull(filePath, nameof(filePath));
+
+            string ext = Path.GetExtension(filePath);
+            IImageFormat format = source.GetConfiguration().ImageFormatsManager.FindFormatByFileExtension(ext);
+            if (format is null)
+            {
+                var sb = new StringBuilder();
+                sb.AppendLine($"No encoder was found for extension '{ext}'. Registered encoders include:");
+                foreach (IImageFormat fmt in source.GetConfiguration().ImageFormats)
+                {
+                    sb.AppendFormat(" - {0} : {1}{2}", fmt.Name, string.Join(", ", fmt.FileExtensions), Environment.NewLine);
+                }
+
+                throw new NotSupportedException(sb.ToString());
+            }
+
+            IImageEncoder encoder = source.GetConfiguration().ImageFormatsManager.FindEncoder(format);
+
+            if (encoder is null)
+            {
+                var sb = new StringBuilder();
+                sb.AppendLine($"No encoder was found for extension '{ext}' using image format '{format.Name}'. Registered encoders include:");
+                foreach (KeyValuePair<IImageFormat, IImageEncoder> enc in source.GetConfiguration().ImageFormatsManager.ImageEncoders)
+                {
+                    sb.AppendFormat(" - {0} : {1}{2}", enc.Key, enc.Value.GetType().Name, Environment.NewLine);
+                }
+
+                throw new NotSupportedException(sb.ToString());
+            }
+
+            return encoder;
+        }
+
         /// <summary>
         /// Accepts a <see cref="IImageVisitor"/> to implement a double-dispatch pattern in order to
         /// apply pixel-specific operations on non-generic <see cref="Image"/> instances
         /// </summary>
-        /// <param name="source">The source.</param>
-        /// <param name="visitor">The visitor.</param>
+        /// <param name="source">The source image.</param>
+        /// <param name="visitor">The image visitor.</param>
         public static void AcceptVisitor(this Image source, IImageVisitor visitor)
             => source.Accept(visitor);
 
+        /// <summary>
+        /// Accepts a <see cref="IImageVisitor"/> to implement a double-dispatch pattern in order to
+        /// apply pixel-specific operations on non-generic <see cref="Image"/> instances
+        /// </summary>
+        /// <param name="source">The source image.</param>
+        /// <param name="visitor">The image visitor.</param>
+        /// <returns>A  <see cref="Task"/> representing the asynchronous operation.</returns>
+        public static Task AcceptVisitorAsync(this Image source, IImageVisitorAsync visitor)
+            => source.AcceptAsync(visitor);
+
         /// <summary>
         /// Gets the configuration for the image.
         /// </summary>

src/ImageSharp/Advanced/IImageVisitor.cs

@@ -1,6 +1,7 @@
 // Copyright (c) Six Labors.
 // Licensed under the Apache License, Version 2.0.
 
+using System.Threading.Tasks;
 using SixLabors.ImageSharp.PixelFormats;
 
 namespace SixLabors.ImageSharp.Advanced
@@ -19,4 +20,20 @@ public interface IImageVisitor
         void Visit<TPixel>(Image<TPixel> image)
             where TPixel : unmanaged, IPixel<TPixel>;
     }
+
+    /// <summary>
+    /// A visitor to implement a double-dispatch pattern in order to apply pixel-specific operations
+    /// on non-generic <see cref="Image"/> instances.
+    /// </summary>
+    public interface IImageVisitorAsync
+    {
+        /// <summary>
+        /// Provides a pixel-specific implementation for a given operation.
+        /// </summary>
+        /// <param name="image">The image.</param>
+        /// <typeparam name="TPixel">The pixel type.</typeparam>
+        /// <returns>A <see cref="Task"/> representing the asynchronous operation.</returns>
+        Task VisitAsync<TPixel>(Image<TPixel> image)
+            where TPixel : unmanaged, IPixel<TPixel>;
+    }
 }

src/ImageSharp/Formats/Bmp/BmpDecoder.cs

@@ -2,6 +2,7 @@
 // Licensed under the Apache License, Version 2.0.
 
 using System.IO;
+using System.Threading.Tasks;
 using SixLabors.ImageSharp.Memory;
 using SixLabors.ImageSharp.PixelFormats;
 
@@ -27,6 +28,26 @@ public sealed class BmpDecoder : IImageDecoder, IBmpDecoderOptions, IImageInfoDe
         /// </summary>
         public RleSkippedPixelHandling RleSkippedPixelHandling { get; set; } = RleSkippedPixelHandling.Black;
 
+        /// <inheritdoc/>
+        public async Task<Image<TPixel>> DecodeAsync<TPixel>(Configuration configuration, Stream stream)
+           where TPixel : unmanaged, IPixel<TPixel>
+        {
+            Guard.NotNull(stream, nameof(stream));
+
+            var decoder = new BmpDecoderCore(configuration, this);
+
+            try
+            {
+                return await decoder.DecodeAsync<TPixel>(stream).ConfigureAwait(false);
+            }
+            catch (InvalidMemoryOperationException ex)
+            {
+                Size dims = decoder.Dimensions;
+
+                throw new InvalidImageContentException($"Can not decode image. Failed to allocate buffers for possibly degenerate dimensions: {dims.Width}x{dims.Height}. This error can happen for very large RLE bitmaps, which are not supported.", ex);
+            }
+        }
+
         /// <inheritdoc/>
         public Image<TPixel> Decode<TPixel>(Configuration configuration, Stream stream)
             where TPixel : unmanaged, IPixel<TPixel>
@@ -50,12 +71,23 @@ public Image<TPixel> Decode<TPixel>(Configuration configuration, Stream stream)
         /// <inheritdoc />
         public Image Decode(Configuration configuration, Stream stream) => this.Decode<Rgba32>(configuration, stream);
 
+        /// <inheritdoc />
+        public async Task<Image> DecodeAsync(Configuration configuration, Stream stream) => await this.DecodeAsync<Rgba32>(configuration, stream).ConfigureAwait(false);
+
         /// <inheritdoc/>
         public IImageInfo Identify(Configuration configuration, Stream stream)
         {
             Guard.NotNull(stream, nameof(stream));
 
             return new BmpDecoderCore(configuration, this).Identify(stream);
         }
+
+        /// <inheritdoc/>
+        public Task<IImageInfo> IdentifyAsync(Configuration configuration, Stream stream)
+        {
+            Guard.NotNull(stream, nameof(stream));
+
+            return new BmpDecoderCore(configuration, this).IdentifyAsync(stream);
+        }
     }
 }

src/ImageSharp/Formats/Bmp/BmpDecoderCore.cs

@@ -7,7 +7,9 @@
 using System.IO;
 using System.Numerics;
 using System.Runtime.CompilerServices;
+using System.Threading.Tasks;
 using SixLabors.ImageSharp.Common.Helpers;
+using SixLabors.ImageSharp.IO;
 using SixLabors.ImageSharp.Memory;
 using SixLabors.ImageSharp.Metadata;
 using SixLabors.ImageSharp.PixelFormats;
@@ -130,8 +132,40 @@ public BmpDecoderCore(Configuration configuration, IBmpDecoderOptions options)
         ///    <para><paramref name="stream"/> is null.</para>
         /// </exception>
         /// <returns>The decoded image.</returns>
-        public Image<TPixel> Decode<TPixel>(Stream stream)
+        public async Task<Image<TPixel>> DecodeAsync<TPixel>(Stream stream)
             where TPixel : unmanaged, IPixel<TPixel>
+        {
+            // if we can seek then we arn't in a context that errors on async operations
+            if (stream.CanSeek)
+            {
+                return this.Decode<TPixel>(stream);
+            }
+            else
+            {
+                // cheat for now do async copy of the stream into memory stream and use the sync version
+                // we should use an array pool backed memorystream implementation
+                using (var ms = new MemoryStream())
+                {
+                    await stream.CopyToAsync(ms).ConfigureAwait(false);
+                    ms.Position = 0;
+                    return this.Decode<TPixel>(ms);
+                }
+            }
+        }
+
+        /// <summary>
+        /// Decodes the image from the specified this._stream and sets
+        /// the data to image.
+        /// </summary>
+        /// <typeparam name="TPixel">The pixel format.</typeparam>
+        /// <param name="stream">The stream, where the image should be
+        /// decoded from. Cannot be null (Nothing in Visual Basic).</param>
+        /// <exception cref="System.ArgumentNullException">
+        ///    <para><paramref name="stream"/> is null.</para>
+        /// </exception>
+        /// <returns>The decoded image.</returns>
+        public Image<TPixel> Decode<TPixel>(Stream stream)
+        where TPixel : unmanaged, IPixel<TPixel>
         {
             try
             {
@@ -218,6 +252,20 @@ public IImageInfo Identify(Stream stream)
             return new ImageInfo(new PixelTypeInfo(this.infoHeader.BitsPerPixel), this.infoHeader.Width, this.infoHeader.Height, this.metadata);
         }
 
+        /// <summary>
+        /// Reads the raw image information from the specified stream.
+        /// </summary>
+        /// <param name="stream">The <see cref="Stream"/> containing image data.</param>
+        public async Task<IImageInfo> IdentifyAsync(Stream stream)
+        {
+            using (var ms = new FixedCapacityPooledMemoryStream(stream.Length))
+            {
+                await stream.CopyToAsync(ms).ConfigureAwait(false);
+                ms.Position = 0;
+                return this.Identify(ms);
+            }
+        }
+
         /// <summary>
         /// Returns the y- value based on the given height.
         /// </summary>

src/ImageSharp/Formats/Bmp/BmpEncoder.cs

@@ -1,7 +1,8 @@
-// Copyright (c) Six Labors.
+// Copyright (c) Six Labors.
 // Licensed under the Apache License, Version 2.0.
 
 using System.IO;
+using System.Threading.Tasks;
 using SixLabors.ImageSharp.Advanced;
 using SixLabors.ImageSharp.PixelFormats;
 using SixLabors.ImageSharp.Processing.Processors.Quantization;
@@ -39,5 +40,13 @@ public void Encode<TPixel>(Image<TPixel> image, Stream stream)
             var encoder = new BmpEncoderCore(this, image.GetMemoryAllocator());
             encoder.Encode(image, stream);
         }
+
+        /// <inheritdoc/>
+        public Task EncodeAsync<TPixel>(Image<TPixel> image, Stream stream)
+            where TPixel : unmanaged, IPixel<TPixel>
+        {
+            var encoder = new BmpEncoderCore(this, image.GetMemoryAllocator());
+            return encoder.EncodeAsync(image, stream);
+        }
     }
-}
+}

src/ImageSharp/Formats/Bmp/BmpEncoderCore.cs

@@ -5,7 +5,7 @@
 using System.Buffers;
 using System.IO;
 using System.Runtime.InteropServices;
-
+using System.Threading.Tasks;
 using SixLabors.ImageSharp.Advanced;
 using SixLabors.ImageSharp.Common.Helpers;
 using SixLabors.ImageSharp.Memory;
@@ -97,8 +97,32 @@ public BmpEncoderCore(IBmpEncoderOptions options, MemoryAllocator memoryAllocato
         /// <typeparam name="TPixel">The pixel format.</typeparam>
         /// <param name="image">The <see cref="ImageFrame{TPixel}"/> to encode from.</param>
         /// <param name="stream">The <see cref="Stream"/> to encode the image data to.</param>
-        public void Encode<TPixel>(Image<TPixel> image, Stream stream)
+        public async Task EncodeAsync<TPixel>(Image<TPixel> image, Stream stream)
             where TPixel : unmanaged, IPixel<TPixel>
+        {
+            if (stream.CanSeek)
+            {
+                this.Encode(image, stream);
+            }
+            else
+            {
+                using (var ms = new MemoryStream())
+                {
+                    this.Encode(image, ms);
+                    ms.Position = 0;
+                    await ms.CopyToAsync(stream).ConfigureAwait(false);
+                }
+            }
+        }
+
+        /// <summary>
+        /// Encodes the image to the specified stream from the <see cref="ImageFrame{TPixel}"/>.
+        /// </summary>
+        /// <typeparam name="TPixel">The pixel format.</typeparam>
+        /// <param name="image">The <see cref="ImageFrame{TPixel}"/> to encode from.</param>
+        /// <param name="stream">The <see cref="Stream"/> to encode the image data to.</param>
+        public void Encode<TPixel>(Image<TPixel> image, Stream stream)
+        where TPixel : unmanaged, IPixel<TPixel>
         {
             Guard.NotNull(image, nameof(image));
             Guard.NotNull(stream, nameof(stream));

src/ImageSharp/Formats/Gif/GifDecoder.cs

@@ -3,6 +3,7 @@
 
 using System;
 using System.IO;
+using System.Threading.Tasks;
 using SixLabors.ImageSharp.Memory;
 using SixLabors.ImageSharp.Metadata;
 using SixLabors.ImageSharp.PixelFormats;
@@ -24,6 +25,27 @@ public sealed class GifDecoder : IImageDecoder, IGifDecoderOptions, IImageInfoDe
         /// </summary>
         public FrameDecodingMode DecodingMode { get; set; } = FrameDecodingMode.All;
 
+        /// <inheritdoc/>
+        public async Task<Image<TPixel>> DecodeAsync<TPixel>(Configuration configuration, Stream stream)
+            where TPixel : unmanaged, IPixel<TPixel>
+        {
+            var decoder = new GifDecoderCore(configuration, this);
+
+            try
+            {
+                return await decoder.DecodeAsync<TPixel>(stream).ConfigureAwait(false);
+            }
+            catch (InvalidMemoryOperationException ex)
+            {
+                Size dims = decoder.Dimensions;
+
+                GifThrowHelper.ThrowInvalidImageContentException($"Can not decode image. Failed to allocate buffers for possibly degenerate dimensions: {dims.Width}x{dims.Height}.", ex);
+
+                // Not reachable, as the previous statement will throw a exception.
+                return null;
+            }
+        }
+
         /// <inheritdoc/>
         public Image<TPixel> Decode<TPixel>(Configuration configuration, Stream stream)
             where TPixel : unmanaged, IPixel<TPixel>
@@ -54,7 +76,19 @@ public IImageInfo Identify(Configuration configuration, Stream stream)
             return decoder.Identify(stream);
         }
 
+        /// <inheritdoc/>
+        public Task<IImageInfo> IdentifyAsync(Configuration configuration, Stream stream)
+        {
+            Guard.NotNull(stream, nameof(stream));
+
+            var decoder = new GifDecoderCore(configuration, this);
+            return decoder.IdentifyAsync(stream);
+        }
+
         /// <inheritdoc />
         public Image Decode(Configuration configuration, Stream stream) => this.Decode<Rgba32>(configuration, stream);
+
+        /// <inheritdoc />
+        public async Task<Image> DecodeAsync(Configuration configuration, Stream stream) => await this.DecodeAsync<Rgba32>(configuration, stream).ConfigureAwait(false);
     }
 }