DecodedBlock cleanup & better comments

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

@@ -0,0 +1,58 @@
+// <copyright file="DecodedBlock.cs" company="James Jackson-South">
+// Copyright (c) James Jackson-South and contributors.
+// Licensed under the Apache License, Version 2.0.
+// </copyright>
+
+namespace ImageSharp.Formats.Jpg
+{
+    using System;
+
+    /// <summary>
+    /// A structure to store unprocessed <see cref="Block8x8F"/> instances and their coordinates while scanning the image.
+    /// The <see cref="Block"/> is present in a "raw" decoded frequency-domain form.
+    /// We need to apply IDCT and unzigging to transform them into color-space blocks.
+    /// </summary>
+    internal struct DecodedBlock
+    {
+        /// <summary>
+        /// A value indicating whether the <see cref="DecodedBlock"/> instance is initialized.
+        /// </summary>
+        public bool Initialized;
+
+        /// <summary>
+        /// X coordinate of the current block, in units of 8x8. (The third block in the first row has (bx, by) = (2, 0))
+        /// </summary>
+        public int Bx;
+
+        /// <summary>
+        /// Y coordinate of the current block, in units of 8x8. (The third block in the first row has (bx, by) = (2, 0))
+        /// </summary>
+        public int By;
+
+        /// <summary>
+        /// The <see cref="Block8x8F"/>
+        /// </summary>
+        public Block8x8F Block;
+
+        /// <summary>
+        /// Store the block data into a <see cref="DecodedBlock"/> at the given index of an <see cref="DecodedBlockArray"/>.
+        /// </summary>
+        /// <param name="blockArray">The array <see cref="DecodedBlockArray"/></param>
+        /// <param name="index">The index in the array</param>
+        /// <param name="bx">X coordinate of the block</param>
+        /// <param name="by">Y coordinate of the block</param>
+        /// <param name="block">The <see cref="Block8x8F"/></param>
+        public static void Store(ref DecodedBlockArray blockArray, int index, int bx, int by, ref Block8x8F block)
+        {
+            if (index >= blockArray.Count)
+            {
+                throw new IndexOutOfRangeException("Block index is out of range in DecodedBlock.Store()!");
+            }
+
+            blockArray.Buffer[index].Initialized = true;
+            blockArray.Buffer[index].Bx = bx;
+            blockArray.Buffer[index].By = by;
+            blockArray.Buffer[index].Block = block;
+        }
+    }
+}

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

@@ -0,0 +1,55 @@
+// <copyright file="DecodedBlockArray.cs" company="James Jackson-South">
+// Copyright (c) James Jackson-South and contributors.
+// Licensed under the Apache License, Version 2.0.
+// </copyright>
+
+namespace ImageSharp.Formats.Jpg
+{
+    using System;
+    using System.Buffers;
+
+    /// <summary>
+    /// Because <see cref="System.Array.Length"/> has no information for rented arrays,
+    /// we need to store the count and the buffer separately when storing pooled <see cref="DecodedBlock"/> arrays.
+    /// </summary>
+    internal struct DecodedBlockArray : IDisposable
+    {
+        /// <summary>
+        /// The <see cref="ArrayPool{T}"/> used to pool data in <see cref="JpegDecoderCore.DecodedBlocks"/>.
+        /// Should always clean arrays when returning!
+        /// </summary>
+        private static readonly ArrayPool<DecodedBlock> ArrayPool = ArrayPool<DecodedBlock>.Create();
+
+        /// <summary>
+        /// Initializes a new instance of the <see cref="DecodedBlockArray"/> struct. Rents a buffer.
+        /// </summary>
+        /// <param name="count">The number of valid <see cref="DecodedBlock"/>-s</param>
+        public DecodedBlockArray(int count)
+        {
+            this.Count = count;
+            this.Buffer = ArrayPool.Rent(count);
+        }
+
+        /// <summary>
+        /// Gets the number of actual <see cref="DecodedBlock"/>-s inside <see cref="Buffer"/>
+        /// </summary>
+        public int Count { get; }
+
+        /// <summary>
+        /// Gets the rented buffer.
+        /// </summary>
+        public DecodedBlock[] Buffer { get; private set; }
+
+        /// <summary>
+        /// Returns the rented buffer to the pool.
+        /// </summary>
+        public void Dispose()
+        {
+            if (this.Buffer != null)
+            {
+                ArrayPool.Return(this.Buffer, true);
+                this.Buffer = null;
+            }
+        }
+    }
+}

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

@@ -1,101 +0,0 @@
-// <copyright file="DecodedBlockMemento.cs" company="James Jackson-South">
-// Copyright (c) James Jackson-South and contributors.
-// Licensed under the Apache License, Version 2.0.
-// </copyright>
-
-namespace ImageSharp.Formats.Jpg
-{
-    using System;
-    using System.Buffers;
-
-    /// <summary>
-    /// A structure to store unprocessed <see cref="Block8x8F"/> instances and their coordinates while scanning the image.
-    /// </summary>
-    internal struct DecodedBlockMemento
-    {
-        /// <summary>
-        /// A value indicating whether the <see cref="DecodedBlockMemento"/> instance is initialized.
-        /// </summary>
-        public bool Initialized;
-
-        /// <summary>
-        /// X coordinate of the current block, in units of 8x8. (The third block in the first row has (bx, by) = (2, 0))
-        /// </summary>
-        public int Bx;
-
-        /// <summary>
-        /// Y coordinate of the current block, in units of 8x8. (The third block in the first row has (bx, by) = (2, 0))
-        /// </summary>
-        public int By;
-
-        /// <summary>
-        /// The <see cref="Block8x8F"/>
-        /// </summary>
-        public Block8x8F Block;
-
-        /// <summary>
-        /// Store the block data into a <see cref="DecodedBlockMemento"/> at the given index of an <see cref="DecodedBlockMemento.Array"/>.
-        /// </summary>
-        /// <param name="blockArray">The array <see cref="DecodedBlockMemento.Array"/></param>
-        /// <param name="index">The index in the array</param>
-        /// <param name="bx">X coordinate of the block</param>
-        /// <param name="by">Y coordinate of the block</param>
-        /// <param name="block">The <see cref="Block8x8F"/></param>
-        public static void Store(ref DecodedBlockMemento.Array blockArray, int index, int bx, int by, ref Block8x8F block)
-        {
-            if (index >= blockArray.Count)
-            {
-                throw new IndexOutOfRangeException("Block index is out of range in DecodedBlockMemento.Store()!");
-            }
-
-            blockArray.Buffer[index].Initialized = true;
-            blockArray.Buffer[index].Bx = bx;
-            blockArray.Buffer[index].By = by;
-            blockArray.Buffer[index].Block = block;
-        }
-
-        /// <summary>
-        /// Because <see cref="System.Array.Length"/> has no information for rented arrays, we need to store the count and the buffer separately.
-        /// </summary>
-        public struct Array : IDisposable
-        {
-            /// <summary>
-            /// The <see cref="ArrayPool{T}"/> used to pool data in <see cref="JpegDecoderCore.DecodedBlocks"/>.
-            /// Should always clean arrays when returning!
-            /// </summary>
-            private static readonly ArrayPool<DecodedBlockMemento> ArrayPool = ArrayPool<DecodedBlockMemento>.Create();
-
-            /// <summary>
-            /// Initializes a new instance of the <see cref="Array"/> struct. Rents a buffer.
-            /// </summary>
-            /// <param name="count">The number of valid <see cref="DecodedBlockMemento"/>-s</param>
-            public Array(int count)
-            {
-                this.Count = count;
-                this.Buffer = ArrayPool.Rent(count);
-            }
-
-            /// <summary>
-            /// Gets the number of actual <see cref="DecodedBlockMemento"/>-s inside <see cref="Buffer"/>
-            /// </summary>
-            public int Count { get; }
-
-            /// <summary>
-            /// Gets the rented buffer.
-            /// </summary>
-            public DecodedBlockMemento[] Buffer { get; private set; }
-
-            /// <summary>
-            /// Returns the rented buffer to the pool.
-            /// </summary>
-            public void Dispose()
-            {
-                if (this.Buffer != null)
-                {
-                    ArrayPool.Return(this.Buffer, true);
-                    this.Buffer = null;
-                }
-            }
-        }
-    }
-}

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

@@ -121,10 +121,10 @@ namespace ImageSharp.Formats.Jpg
         }
 
         /// <summary>
-        /// Loads the data from the given <see cref="DecodedBlockMemento"/> into the block.
+        /// Loads the data from the given <see cref="DecodedBlock"/> into the block.
         /// </summary>
-        /// <param name="memento">The <see cref="DecodedBlockMemento"/></param>
+        /// <param name="memento">The <see cref="DecodedBlock"/></param>
-        public void LoadMemento(ref DecodedBlockMemento memento)
+        public void LoadMemento(ref DecodedBlock memento)
         {
             this.bx = memento.Bx;
             this.by = memento.By;
@@ -204,8 +204,8 @@ namespace ImageSharp.Formats.Jpg
                             }
 
                             // Store the decoded block
-                            DecodedBlockMemento.Array blocks = decoder.DecodedBlocks[this.ComponentIndex];
+                            DecodedBlockArray blocks = decoder.DecodedBlocks[this.ComponentIndex];
-                            DecodedBlockMemento.Store(ref blocks, blockIndex, this.bx, this.by, ref this.data.Block);
+                            DecodedBlock.Store(ref blocks, blockIndex, this.bx, this.by, ref this.data.Block);
                         }
 
                         // for j

src/ImageSharp.Formats.Jpeg/JpegDecoderCore.cs

@@ -87,7 +87,7 @@ namespace ImageSharp.Formats
             this.QuantizationTables = new Block8x8F[MaxTq + 1];
             this.Temp = new byte[2 * Block8x8F.ScalarCount];
             this.ComponentArray = new Component[MaxComponents];
-            this.DecodedBlocks = new DecodedBlockMemento.Array[MaxComponents];
+            this.DecodedBlocks = new DecodedBlockArray[MaxComponents];
         }
 
         /// <summary>
@@ -101,10 +101,12 @@ namespace ImageSharp.Formats
         public HuffmanTree[] HuffmanTrees { get; }
 
         /// <summary>
-        /// Gets the saved state between progressive-mode scans.
+        /// Gets the array of <see cref="DecodedBlockArray"/>-s storing the "raw" frequency-domain decoded blocks.
-        /// TODO: Also save non-progressive data here. (Helps splitting and parallelizing JpegScanDecoder-s loop)
+        /// We need to apply IDCT and unzigging to transform them into color-space blocks.
+        /// This is done by <see cref="ProcessBlocksIntoJpegImageChannels{TColor}"/>.
+        /// When <see cref="IsProgressive"/>==true, we are touching these blocks each time we process a Scan.
         /// </summary>
-        public DecodedBlockMemento.Array[] DecodedBlocks { get; }
+        public DecodedBlockArray[] DecodedBlocks { get; }
 
         /// <summary>
         /// Gets the quantization tables, in zigzag order.
@@ -191,7 +193,7 @@ namespace ImageSharp.Formats
                 this.HuffmanTrees[i].Dispose();
             }
 
-            foreach (DecodedBlockMemento.Array blockArray in this.DecodedBlocks)
+            foreach (DecodedBlockArray blockArray in this.DecodedBlocks)
             {
                 blockArray.Dispose();
             }
@@ -461,7 +463,7 @@ namespace ImageSharp.Formats
 
         /// <summary>
         /// Process the blocks in <see cref="DecodedBlocks"/> into Jpeg image channels (<see cref="YCbCrImage"/> and <see cref="JpegPixelArea"/>)
-        /// The blocks are expected in a "raw" frequency-domain decoded format. We need to apply IDCT and unzigging to transform them into color-space blocks.
+        /// <see cref="DecodedBlocks"/> are in a "raw" frequency-domain form. We need to apply IDCT and unzigging to transform them into color-space blocks.
         /// We can copy these blocks into <see cref="JpegPixelArea"/>-s afterwards.
         /// </summary>
         /// <typeparam name="TColor">The pixel type</typeparam>
@@ -477,7 +479,7 @@ namespace ImageSharp.Formats
                         JpegScanDecoder.Init(&scanDecoder);
 
                         scanDecoder.ComponentIndex = componentIndex;
-                        DecodedBlockMemento.Array blockArray = this.DecodedBlocks[componentIndex];
+                        DecodedBlockArray blockArray = this.DecodedBlocks[componentIndex];
                         for (int i = 0; i < blockArray.Count; i++)
                         {
                             scanDecoder.LoadMemento(ref blockArray.Buffer[i]);
@@ -1316,7 +1318,7 @@ namespace ImageSharp.Formats
             {
                 int count = this.TotalMCUCount * this.ComponentArray[i].HorizontalFactor
                            * this.ComponentArray[i].VerticalFactor;
-                this.DecodedBlocks[i] = new DecodedBlockMemento.Array(count);
+                this.DecodedBlocks[i] = new DecodedBlockArray(count);
             }
         }
     }