Introduce non-generic ImageFrameCollection (#941)

* temporarily disable target frameworks

* drop DelegateProcessor

* drop IImageProcessingContext<TPixel>

* drop NamedColors<T>

* drop ColorBuilder<T>

* drop the *Base postfix for clean class hierarchies

* adding basic skeletons

* non-generic ImageFrameCollection API definition

* non-generic ImageFrameCollection tests

* cleanup + docs + more tests

* implement ImageFrameCollection methods

* tests for generic PixelOperations.To<TDest>()

* experimental implementation

* fix .ttinclude

* generate generic From<TSourcePixel>(...)

* fix RgbaVector <--> BT709 Gray pixel conversion

* Gray8 and Gray16 using ConvertFromRgbaScaledVector4() by default

* fixed all conversion tests

* ConstructGif_FromDifferentPixelTypes

* fix xmldoc and other StyelCop findings

* re-enable all target frameworks

* fix NonGenericAddFrame() and NonGenericInsertFrame()

* fix remaining bugs

Author: antonfirsov

.gitattributes

@@ -50,7 +50,7 @@
 *.svg               text        eol=lf
 *.targets           text        eol=lf
 *.tt                text        eol=lf
-*.ttinclude         text        eol=lf
+*.ttinclude         text        eol=crlf
 *.txt               text        eol=lf
 *.vb                text        eol=lf
 *.yml               text        eol=lf

src/ImageSharp/Common/Helpers/ImageMaths.cs

@@ -36,6 +36,17 @@ public static byte Get8BitBT709Luminance(byte r, byte g, byte b) =>
         public static ushort Get16BitBT709Luminance(ushort r, ushort g, ushort b) =>
             (ushort)((r * .2126F) + (g * .7152F) + (b * .0722F));
 
+        /// <summary>
+        /// Gets the luminance from the rgb components using the formula as specified by ITU-R Recommendation BT.709.
+        /// </summary>
+        /// <param name="r">The red component.</param>
+        /// <param name="g">The green component.</param>
+        /// <param name="b">The blue component.</param>
+        /// <returns>The <see cref="ushort"/>.</returns>
+        [MethodImpl(InliningOptions.ShortMethod)]
+        public static ushort Get16BitBT709Luminance(float r, float g, float b) =>
+            (ushort)((r * .2126F) + (g * .7152F) + (b * .0722F));
+
         /// <summary>
         /// Scales a value from a 16 bit <see cref="ushort"/> to it's 8 bit <see cref="byte"/> equivalent.
         /// </summary>
@@ -379,4 +390,4 @@ int GetMaxX(ImageFrame<TPixel> pixels)
             return GetBoundingRectangle(topLeft, bottomRight);
         }
     }
-}
+}

src/ImageSharp/Formats/Jpeg/Components/Decoder/JpegImagePostProcessor.cs

@@ -21,7 +21,7 @@ namespace SixLabors.ImageSharp.Formats.Jpeg.Components.Decoder
     /// (4) Packing <see cref="Image{TPixel}"/> pixels from the <see cref="Vector4"/> buffer. <br/>
     /// These operations are executed in <see cref="NumberOfPostProcessorSteps"/> steps.
     /// <see cref="PixelRowsPerStep"/> image rows are converted in one step,
-    /// which means that size of the allocated memory is limited (does not depend on <see cref="ImageFrame{TPixel}.Height"/>).
+    /// which means that size of the allocated memory is limited (does not depend on <see cref="ImageFrame.Height"/>).
     /// </summary>
     internal class JpegImagePostProcessor : IDisposable
     {
@@ -177,4 +177,4 @@ private void ConvertColorsInto<TPixel>(ImageFrame<TPixel> destination)
             }
         }
     }
-}
+}

src/ImageSharp/Image.cs

@@ -53,6 +53,11 @@ internal Image(
         /// </summary>
         protected Configuration Configuration { get; }
 
+        /// <summary>
+        /// Gets the <see cref="ImageFrameCollection"/> implementing the public <see cref="Frames"/> property.
+        /// </summary>
+        protected abstract ImageFrameCollection NonGenericFrameCollection { get; }
+
         /// <inheritdoc/>
         public PixelTypeInfo PixelType { get; }
 
@@ -65,6 +70,11 @@ internal Image(
         /// <inheritdoc/>
         public ImageMetadata Metadata { get; }
 
+        /// <summary>
+        /// Gets the frames of the image as (non-generic) <see cref="ImageFrameCollection"/>.
+        /// </summary>
+        public ImageFrameCollection Frames => this.NonGenericFrameCollection;
+
         /// <summary>
         /// Gets the pixel buffer.
         /// </summary>
@@ -137,4 +147,4 @@ public void Visit<TPixel>(Image<TPixel> image)
             }
         }
     }
-}
+}

src/ImageSharp/ImageFrame.LoadPixelData.cs

@@ -9,9 +9,9 @@
 namespace SixLabors.ImageSharp
 {
     /// <content>
-    /// Adds static methods allowing the creation of new image from raw pixel data.
+    /// Contains methods for loading raw pixel data.
     /// </content>
-    internal static class ImageFrame
+    public partial class ImageFrame
     {
         /// <summary>
         /// Create a new instance of the <see cref="Image{TPixel}"/> class from the given byte array in <typeparamref name="TPixel"/> format.
@@ -22,7 +22,7 @@ internal static class ImageFrame
         /// <param name="height">The height of the final image.</param>
         /// <typeparam name="TPixel">The pixel format.</typeparam>
         /// <returns>A new <see cref="Image{TPixel}"/>.</returns>
-        public static ImageFrame<TPixel> LoadPixelData<TPixel>(Configuration configuration, ReadOnlySpan<byte> data, int width, int height)
+        internal static ImageFrame<TPixel> LoadPixelData<TPixel>(Configuration configuration, ReadOnlySpan<byte> data, int width, int height)
             where TPixel : struct, IPixel<TPixel>
             => LoadPixelData(configuration, MemoryMarshal.Cast<byte, TPixel>(data), width, height);
 
@@ -35,7 +35,7 @@ public static ImageFrame<TPixel> LoadPixelData<TPixel>(Configuration configurati
         /// <param name="height">The height of the final image.</param>
         /// <typeparam name="TPixel">The pixel format.</typeparam>
         /// <returns>A new <see cref="Image{TPixel}"/>.</returns>
-        public static ImageFrame<TPixel> LoadPixelData<TPixel>(Configuration configuration, ReadOnlySpan<TPixel> data, int width, int height)
+        internal static ImageFrame<TPixel> LoadPixelData<TPixel>(Configuration configuration, ReadOnlySpan<TPixel> data, int width, int height)
             where TPixel : struct, IPixel<TPixel>
         {
             int count = width * height;
@@ -48,4 +48,4 @@ public static ImageFrame<TPixel> LoadPixelData<TPixel>(Configuration configurati
             return image;
         }
     }
-}
+}

src/ImageSharp/ImageFrame.cs

@@ -0,0 +1,91 @@
+// Copyright (c) Six Labors and contributors.
+// Licensed under the Apache License, Version 2.0.
+
+using System;
+
+using SixLabors.ImageSharp.Metadata;
+using SixLabors.ImageSharp.PixelFormats;
+using SixLabors.Memory;
+using SixLabors.Primitives;
+
+namespace SixLabors.ImageSharp
+{
+    /// <summary>
+    /// Represents a pixel-agnostic image frame containing all pixel data and <see cref="ImageFrameMetadata"/>.
+    /// In case of animated formats like gif, it contains the single frame in a animation.
+    /// In all other cases it is the only frame of the image.
+    /// </summary>
+    public abstract partial class ImageFrame : IDisposable
+    {
+        /// <summary>
+        /// Initializes a new instance of the <see cref="ImageFrame"/> class.
+        /// </summary>
+        /// <param name="configuration">The <see cref="Configuration"/>.</param>
+        /// <param name="width">The width.</param>
+        /// <param name="height">The height.</param>
+        /// <param name="metadata">The <see cref="ImageFrameMetadata"/>.</param>
+        protected ImageFrame(Configuration configuration, int width, int height, ImageFrameMetadata metadata)
+        {
+            Guard.NotNull(configuration, nameof(configuration));
+            Guard.NotNull(metadata, nameof(metadata));
+
+            this.Configuration = configuration;
+            this.MemoryAllocator = configuration.MemoryAllocator;
+            this.Width = width;
+            this.Height = height;
+            this.Metadata = metadata;
+        }
+
+        /// <summary>
+        /// Gets the <see cref="MemoryAllocator" /> to use for buffer allocations.
+        /// </summary>
+        public MemoryAllocator MemoryAllocator { get; }
+
+        /// <summary>
+        /// Gets the <see cref="Configuration"/> instance associated with this <see cref="ImageFrame{TPixel}"/>.
+        /// </summary>
+        internal Configuration Configuration { get; }
+
+        /// <summary>
+        /// Gets the width.
+        /// </summary>
+        public int Width { get; private set; }
+
+        /// <summary>
+        /// Gets the height.
+        /// </summary>
+        public int Height { get; private set; }
+
+        /// <summary>
+        /// Gets the metadata of the frame.
+        /// </summary>
+        public ImageFrameMetadata Metadata { get; }
+
+        /// <summary>
+        /// Gets the size of the frame.
+        /// </summary>
+        /// <returns>The <see cref="Size"/></returns>
+        public Size Size() => new Size(this.Width, this.Height);
+
+        /// <summary>
+        /// Gets the bounds of the frame.
+        /// </summary>
+        /// <returns>The <see cref="Rectangle"/></returns>
+        public Rectangle Bounds() => new Rectangle(0, 0, this.Width, this.Height);
+
+        /// <inheritdoc />
+        public abstract void Dispose();
+
+        internal abstract void CopyPixelsTo<TDestinationPixel>(Span<TDestinationPixel> destination)
+            where TDestinationPixel : struct, IPixel<TDestinationPixel>;
+
+        /// <summary>
+        /// Updates the size of the image frame.
+        /// </summary>
+        internal void UpdateSize(Size size)
+        {
+            this.Width = size.Width;
+            this.Height = size.Height;
+        }
+    }
+}