Implement discontiguous buffer handling

src/Directory.Build.props

@@ -23,7 +23,8 @@
   </PropertyGroup>
 
   <PropertyGroup Condition="'$(Configuration)' == 'Release'">
-    <TreatWarningsAsErrors>true</TreatWarningsAsErrors>
+<!-- TODO: re-enable when all Obsolete warnings are fixed -->
+<!--    <TreatWarningsAsErrors>true</TreatWarningsAsErrors>-->
   </PropertyGroup>
 
   <ItemGroup>

src/ImageSharp/Advanced/AdvancedImageExtensions.cs

@@ -2,6 +2,7 @@
 // Licensed under the Apache License, Version 2.0.
 
 using System;
+using System.Linq;
 using System.Runtime.InteropServices;
 
 using SixLabors.ImageSharp.Memory;
@@ -40,23 +41,66 @@ public static Configuration GetConfiguration(this ImageFrame source)
             => GetConfiguration((IConfigurationProvider)source);
 
         /// <summary>
-        /// Gets the configuration .
+        /// Gets the configuration.
         /// </summary>
         /// <param name="source">The source image</param>
         /// <returns>Returns the bounds of the image</returns>
         private static Configuration GetConfiguration(IConfigurationProvider source)
             => source?.Configuration ?? Configuration.Default;
 
         /// <summary>
-        /// Gets the representation of the pixels as a <see cref="Span{T}"/> of contiguous memory in the source image's pixel format
-        /// stored in row major order.
+        /// Gets the representation of the pixels as a <see cref="IMemoryGroup{T}"/> containing the backing pixel data of the image
+        /// stored in row major order, as a list of contiguous <see cref="Memory{T}"/> blocks in the source image's pixel format.
         /// </summary>
+        /// <param name="source">The source image.</param>
         /// <typeparam name="TPixel">The type of the pixel.</typeparam>
-        /// <param name="source">The source.</param>
+        /// <returns>The <see cref="IMemoryGroup{T}"/>.</returns>
+        /// <remarks>
+        /// Certain Image Processors may invalidate the returned <see cref="IMemoryGroup{T}"/> and all it's buffers,
+        /// therefore it's not recommended to mutate the image while holding a reference to it's <see cref="IMemoryGroup{T}"/>.
+        /// </remarks>
+        public static IMemoryGroup<TPixel> GetPixelMemoryGroup<TPixel>(this ImageFrame<TPixel> source)
+            where TPixel : struct, IPixel<TPixel>
+            => source?.PixelBuffer.MemoryGroup.View ?? throw new ArgumentNullException(nameof(source));
+
+        /// <summary>
+        /// Gets the representation of the pixels as a <see cref="IMemoryGroup{T}"/> containing the backing pixel data of the image
+        /// stored in row major order, as a list of contiguous <see cref="Memory{T}"/> blocks in the source image's pixel format.
+        /// </summary>
+        /// <param name="source">The source image.</param>
+        /// <typeparam name="TPixel">The type of the pixel.</typeparam>
+        /// <returns>The <see cref="IMemoryGroup{T}"/>.</returns>
+        /// <remarks>
+        /// Certain Image Processors may invalidate the returned <see cref="IMemoryGroup{T}"/> and all it's buffers,
+        /// therefore it's not recommended to mutate the image while holding a reference to it's <see cref="IMemoryGroup{T}"/>.
+        /// </remarks>
+        public static IMemoryGroup<TPixel> GetPixelMemoryGroup<TPixel>(this Image<TPixel> source)
+            where TPixel : struct, IPixel<TPixel>
+            => source?.Frames.RootFrame.GetPixelMemoryGroup() ?? throw new ArgumentNullException(nameof(source));
+
+        /// <summary>
+        /// Gets the representation of the pixels as a <see cref="Span{T}"/> in the source image's pixel format
+        /// stored in row major order, if the backing buffer is contiguous.
+        /// </summary>
+        /// <typeparam name="TPixel">The type of the pixel.</typeparam>
+        /// <param name="source">The source image.</param>
         /// <returns>The <see cref="Span{TPixel}"/></returns>
+        /// <exception cref="InvalidOperationException">Thrown when the backing buffer is discontiguous.</exception>
+        [Obsolete(
+            @"GetPixelSpan might fail, because the backing buffer could be discontiguous for large images. Use GetPixelMemoryGroup or GetPixelRowSpan instead!")]
         public static Span<TPixel> GetPixelSpan<TPixel>(this ImageFrame<TPixel> source)
             where TPixel : struct, IPixel<TPixel>
-            => source.GetPixelMemory().Span;
+        {
+            Guard.NotNull(source, nameof(source));
+
+            IMemoryGroup<TPixel> mg = source.GetPixelMemoryGroup();
+            if (mg.Count > 1)
+            {
+                throw new InvalidOperationException($"GetPixelSpan is invalid, since the backing buffer of this {source.Width}x{source.Height} sized image is discontiguos!");
+            }
+
+            return mg.Single().Span;
+        }
 
         /// <summary>
         /// Gets the representation of the pixels as a <see cref="Span{T}"/> of contiguous memory in the source image's pixel format
@@ -65,9 +109,16 @@ public static Span<TPixel> GetPixelSpan<TPixel>(this ImageFrame<TPixel> source)
         /// <typeparam name="TPixel">The type of the pixel.</typeparam>
         /// <param name="source">The source.</param>
         /// <returns>The <see cref="Span{TPixel}"/></returns>
+        /// <exception cref="InvalidOperationException">Thrown when the backing buffer is discontiguous.</exception>
+        [Obsolete(
+            @"GetPixelSpan might fail, because the backing buffer could be discontiguous for large images. Use GetPixelMemoryGroup or GetPixelRowSpan instead!")]
         public static Span<TPixel> GetPixelSpan<TPixel>(this Image<TPixel> source)
             where TPixel : struct, IPixel<TPixel>
-            => source.Frames.RootFrame.GetPixelSpan();
+        {
+            Guard.NotNull(source, nameof(source));
+
+            return source.Frames.RootFrame.GetPixelSpan();
+        }
 
         /// <summary>
         /// Gets the representation of the pixels as a <see cref="Span{T}"/> of contiguous memory
@@ -79,7 +130,13 @@ public static Span<TPixel> GetPixelSpan<TPixel>(this Image<TPixel> source)
         /// <returns>The <see cref="Span{TPixel}"/></returns>
         public static Span<TPixel> GetPixelRowSpan<TPixel>(this ImageFrame<TPixel> source, int rowIndex)
             where TPixel : struct, IPixel<TPixel>
-            => source.PixelBuffer.GetRowSpan(rowIndex);
+        {
+            Guard.NotNull(source, nameof(source));
+            Guard.MustBeGreaterThanOrEqualTo(rowIndex, 0, nameof(rowIndex));
+            Guard.MustBeLessThan(rowIndex, source.Height, nameof(rowIndex));
+
+            return source.PixelBuffer.GetRowSpanUnchecked(rowIndex);
+        }
 
         /// <summary>
         /// Gets the representation of the pixels as <see cref="Span{T}"/> of of contiguous memory
@@ -91,58 +148,12 @@ public static Span<TPixel> GetPixelRowSpan<TPixel>(this ImageFrame<TPixel> sourc
         /// <returns>The <see cref="Span{TPixel}"/></returns>
         public static Span<TPixel> GetPixelRowSpan<TPixel>(this Image<TPixel> source, int rowIndex)
             where TPixel : struct, IPixel<TPixel>
-            => source.Frames.RootFrame.GetPixelRowSpan(rowIndex);
-
-        /// <summary>
-        /// Returns a reference to the 0th element of the Pixel buffer,
-        /// allowing direct manipulation of pixel data through unsafe operations.
-        /// The pixel buffer is a contiguous memory area containing Width*Height TPixel elements laid out in row-major order.
-        /// </summary>
-        /// <typeparam name="TPixel">The Pixel format.</typeparam>
-        /// <param name="source">The source image frame</param>
-        /// <returns>A pinnable reference the first root of the pixel buffer.</returns>
-        [Obsolete("This method will be removed in our next release! Please use MemoryMarshal.GetReference(source.GetPixelSpan())!")]
-        public static ref TPixel DangerousGetPinnableReferenceToPixelBuffer<TPixel>(this ImageFrame<TPixel> source)
-            where TPixel : struct, IPixel<TPixel>
-            => ref DangerousGetPinnableReferenceToPixelBuffer((IPixelSource<TPixel>)source);
-
-        /// <summary>
-        /// Returns a reference to the 0th element of the Pixel buffer,
-        /// allowing direct manipulation of pixel data through unsafe operations.
-        /// The pixel buffer is a contiguous memory area containing Width*Height TPixel elements laid out in row-major order.
-        /// </summary>
-        /// <typeparam name="TPixel">The Pixel format.</typeparam>
-        /// <param name="source">The source image</param>
-        /// <returns>A pinnable reference the first root of the pixel buffer.</returns>
-        [Obsolete("This method will be removed in our next release! Please use MemoryMarshal.GetReference(source.GetPixelSpan())!")]
-        public static ref TPixel DangerousGetPinnableReferenceToPixelBuffer<TPixel>(this Image<TPixel> source)
-            where TPixel : struct, IPixel<TPixel>
-            => ref source.Frames.RootFrame.DangerousGetPinnableReferenceToPixelBuffer();
-
-        /// <summary>
-        /// Gets the representation of the pixels as a <see cref="Memory{T}"/> of contiguous memory in the source image's pixel format
-        /// stored in row major order.
-        /// </summary>
-        /// <typeparam name="TPixel">The Pixel format.</typeparam>
-        /// <param name="source">The source <see cref="ImageFrame{TPixel}"/></param>
-        /// <returns>The <see cref="Memory{T}"/></returns>
-        internal static Memory<TPixel> GetPixelMemory<TPixel>(this ImageFrame<TPixel> source)
-            where TPixel : struct, IPixel<TPixel>
         {
-            return source.PixelBuffer.MemorySource.Memory;
-        }
+            Guard.NotNull(source, nameof(source));
+            Guard.MustBeGreaterThanOrEqualTo(rowIndex, 0, nameof(rowIndex));
+            Guard.MustBeLessThan(rowIndex, source.Height, nameof(rowIndex));
 
-        /// <summary>
-        /// Gets the representation of the pixels as a <see cref="Memory{T}"/> of contiguous memory in the source image's pixel format
-        /// stored in row major order.
-        /// </summary>
-        /// <typeparam name="TPixel">The Pixel format.</typeparam>
-        /// <param name="source">The source <see cref="Image{TPixel}"/></param>
-        /// <returns>The <see cref="Memory{T}"/></returns>
-        internal static Memory<TPixel> GetPixelMemory<TPixel>(this Image<TPixel> source)
-            where TPixel : struct, IPixel<TPixel>
-        {
-            return source.Frames.RootFrame.GetPixelMemory();
+            return source.Frames.RootFrame.PixelBuffer.GetRowSpanUnchecked(rowIndex);
         }
 
         /// <summary>
@@ -153,9 +164,15 @@ internal static Memory<TPixel> GetPixelMemory<TPixel>(this Image<TPixel> source)
         /// <param name="source">The source.</param>
         /// <param name="rowIndex">The row.</param>
         /// <returns>The <see cref="Span{TPixel}"/></returns>
-        internal static Memory<TPixel> GetPixelRowMemory<TPixel>(this ImageFrame<TPixel> source, int rowIndex)
+        public static Memory<TPixel> GetPixelRowMemory<TPixel>(this ImageFrame<TPixel> source, int rowIndex)
             where TPixel : struct, IPixel<TPixel>
-            => source.PixelBuffer.GetRowMemory(rowIndex);
+        {
+            Guard.NotNull(source, nameof(source));
+            Guard.MustBeGreaterThanOrEqualTo(rowIndex, 0, nameof(rowIndex));
+            Guard.MustBeLessThan(rowIndex, source.Height, nameof(rowIndex));
+
+            return source.PixelBuffer.GetRowMemorySafe(rowIndex);
+        }
 
         /// <summary>
         /// Gets the representation of the pixels as <see cref="Span{T}"/> of of contiguous memory
@@ -165,9 +182,15 @@ internal static Memory<TPixel> GetPixelRowMemory<TPixel>(this ImageFrame<TPixel>
         /// <param name="source">The source.</param>
         /// <param name="rowIndex">The row.</param>
         /// <returns>The <see cref="Span{TPixel}"/></returns>
-        internal static Memory<TPixel> GetPixelRowMemory<TPixel>(this Image<TPixel> source, int rowIndex)
+        public static Memory<TPixel> GetPixelRowMemory<TPixel>(this Image<TPixel> source, int rowIndex)
             where TPixel : struct, IPixel<TPixel>
-            => source.Frames.RootFrame.GetPixelRowMemory(rowIndex);
+        {
+            Guard.NotNull(source, nameof(source));
+            Guard.MustBeGreaterThanOrEqualTo(rowIndex, 0, nameof(rowIndex));
+            Guard.MustBeLessThan(rowIndex, source.Height, nameof(rowIndex));
+
+            return source.Frames.RootFrame.PixelBuffer.GetRowMemorySafe(rowIndex);
+        }
 
         /// <summary>
         /// Gets the <see cref="MemoryAllocator"/> assigned to 'source'.
@@ -176,15 +199,5 @@ internal static Memory<TPixel> GetPixelRowMemory<TPixel>(this Image<TPixel> sour
         /// <returns>Returns the configuration.</returns>
         internal static MemoryAllocator GetMemoryAllocator(this IConfigurationProvider source)
             => GetConfiguration(source).MemoryAllocator;
-
-        /// <summary>
-        /// Returns a reference to the 0th element of the Pixel buffer.
-        /// Such a reference can be used for pinning but must never be dereferenced.
-        /// </summary>
-        /// <param name="source">The source image frame</param>
-        /// <returns>A reference to the element.</returns>
-        private static ref TPixel DangerousGetPinnableReferenceToPixelBuffer<TPixel>(IPixelSource<TPixel> source)
-            where TPixel : struct, IPixel<TPixel>
-            => ref MemoryMarshal.GetReference(source.PixelBuffer.GetSpan());
     }
 }

src/ImageSharp/Common/Helpers/Buffer2DUtils.cs

@@ -52,7 +52,7 @@ public static void Convolve4<TPixel>(
             {
                 int offsetY = (row + i - radiusY).Clamp(minRow, maxRow);
                 int offsetX = sourceOffsetColumnBase.Clamp(minColumn, maxColumn);
-                Span<TPixel> sourceRowSpan = sourcePixels.GetRowSpan(offsetY);
+                Span<TPixel> sourceRowSpan = sourcePixels.GetRowSpanUnchecked(offsetY);
                 var currentColor = sourceRowSpan[offsetX].ToVector4();
 
                 vector.Sum(Unsafe.Add(ref baseRef, i) * currentColor);
@@ -94,7 +94,7 @@ public static void Convolve4AndAccumulatePartials(
             int sourceOffsetColumnBase = column + minColumn;
 
             int offsetY = row.Clamp(minRow, maxRow);
-            ref ComplexVector4 sourceRef = ref MemoryMarshal.GetReference(sourceValues.GetRowSpan(offsetY));
+            ref ComplexVector4 sourceRef = ref MemoryMarshal.GetReference(sourceValues.GetRowSpanUnchecked(offsetY));
             ref Complex64 baseRef = ref MemoryMarshal.GetReference(kernel);
 
             for (int x = 0; x < kernelLength; x++)

src/ImageSharp/Common/Helpers/DenseMatrixUtils.cs

@@ -134,7 +134,7 @@ public static void Convolve2DImpl<TPixel>(
             for (int y = 0; y < matrixHeight; y++)
             {
                 int offsetY = (row + y - radiusY).Clamp(minRow, maxRow);
-                Span<TPixel> sourceRowSpan = sourcePixels.GetRowSpan(offsetY);
+                Span<TPixel> sourceRowSpan = sourcePixels.GetRowSpanUnchecked(offsetY);
 
                 for (int x = 0; x < matrixWidth; x++)
                 {
@@ -264,7 +264,7 @@ private static void ConvolveImpl<TPixel>(
             for (int y = 0; y < matrixHeight; y++)
             {
                 int offsetY = (row + y - radiusY).Clamp(minRow, maxRow);
-                Span<TPixel> sourceRowSpan = sourcePixels.GetRowSpan(offsetY);
+                Span<TPixel> sourceRowSpan = sourcePixels.GetRowSpanUnchecked(offsetY);
 
                 for (int x = 0; x < matrixWidth; x++)
                 {