Merge pull request #1314 from SixLabors/sp/byte-to-tpixel-wrapping

Image.WrapMemory<TPixel> APIs wrapping Memory<byte>

Author: JimBobSquarePants

src/ImageSharp/Image.WrapMemory.cs

@@ -17,7 +17,7 @@ public abstract partial class Image
     {
         /// <summary>
         /// Wraps an existing contiguous memory area of 'width' x 'height' pixels,
-        /// allowing to view/manipulate it as an ImageSharp <see cref="Image{TPixel}"/> instance.
+        /// allowing to view/manipulate it as an <see cref="Image{TPixel}"/> instance.
         /// </summary>
         /// <typeparam name="TPixel">The pixel type</typeparam>
         /// <param name="configuration">The <see cref="Configuration"/></param>
@@ -38,14 +38,15 @@ public static Image<TPixel> WrapMemory<TPixel>(
         {
             Guard.NotNull(configuration, nameof(configuration));
             Guard.NotNull(metadata, nameof(metadata));
+            Guard.IsTrue(pixelMemory.Length == width * height, nameof(pixelMemory), "The length of the input memory doesn't match the specified image size");
 
             var memorySource = MemoryGroup<TPixel>.Wrap(pixelMemory);
             return new Image<TPixel>(configuration, memorySource, width, height, metadata);
         }
 
         /// <summary>
         /// Wraps an existing contiguous memory area of 'width' x 'height' pixels,
-        /// allowing to view/manipulate it as an ImageSharp <see cref="Image{TPixel}"/> instance.
+        /// allowing to view/manipulate it as an <see cref="Image{TPixel}"/> instance.
         /// </summary>
         /// <typeparam name="TPixel">The pixel type</typeparam>
         /// <param name="configuration">The <see cref="Configuration"/></param>
@@ -64,7 +65,7 @@ public static Image<TPixel> WrapMemory<TPixel>(
 
         /// <summary>
         /// Wraps an existing contiguous memory area of 'width' x 'height' pixels,
-        /// allowing to view/manipulate it as an ImageSharp <see cref="Image{TPixel}"/> instance.
+        /// allowing to view/manipulate it as an <see cref="Image{TPixel}"/> instance.
         /// The memory is being observed, the caller remains responsible for managing it's lifecycle.
         /// </summary>
         /// <typeparam name="TPixel">The pixel type.</typeparam>
@@ -81,7 +82,7 @@ public static Image<TPixel> WrapMemory<TPixel>(
 
         /// <summary>
         /// Wraps an existing contiguous memory area of 'width' x 'height' pixels,
-        /// allowing to view/manipulate it as an ImageSharp <see cref="Image{TPixel}"/> instance.
+        /// allowing to view/manipulate it as an <see cref="Image{TPixel}"/> instance.
         /// The ownership of the <paramref name="pixelMemoryOwner"/> is being transferred to the new <see cref="Image{TPixel}"/> instance,
         /// meaning that the caller is not allowed to dispose <paramref name="pixelMemoryOwner"/>.
         /// It will be disposed together with the result image.
@@ -105,14 +106,15 @@ public static Image<TPixel> WrapMemory<TPixel>(
         {
             Guard.NotNull(configuration, nameof(configuration));
             Guard.NotNull(metadata, nameof(metadata));
+            Guard.IsTrue(pixelMemoryOwner.Memory.Length == width * height, nameof(pixelMemoryOwner), "The length of the input memory doesn't match the specified image size");
 
             var memorySource = MemoryGroup<TPixel>.Wrap(pixelMemoryOwner);
             return new Image<TPixel>(configuration, memorySource, width, height, metadata);
         }
 
         /// <summary>
         /// Wraps an existing contiguous memory area of 'width' x 'height' pixels,
-        /// allowing to view/manipulate it as an ImageSharp <see cref="Image{TPixel}"/> instance.
+        /// allowing to view/manipulate it as an <see cref="Image{TPixel}"/> instance.
         /// The ownership of the <paramref name="pixelMemoryOwner"/> is being transferred to the new <see cref="Image{TPixel}"/> instance,
         /// meaning that the caller is not allowed to dispose <paramref name="pixelMemoryOwner"/>.
         /// It will be disposed together with the result image.
@@ -134,7 +136,7 @@ public static Image<TPixel> WrapMemory<TPixel>(
 
         /// <summary>
         /// Wraps an existing contiguous memory area of 'width' x 'height' pixels,
-        /// allowing to view/manipulate it as an ImageSharp <see cref="Image{TPixel}"/> instance.
+        /// allowing to view/manipulate it as an <see cref="Image{TPixel}"/> instance.
         /// The ownership of the <paramref name="pixelMemoryOwner"/> is being transferred to the new <see cref="Image{TPixel}"/> instance,
         /// meaning that the caller is not allowed to dispose <paramref name="pixelMemoryOwner"/>.
         /// It will be disposed together with the result image.
@@ -150,5 +152,73 @@ public static Image<TPixel> WrapMemory<TPixel>(
             int height)
             where TPixel : unmanaged, IPixel<TPixel>
             => WrapMemory(Configuration.Default, pixelMemoryOwner, width, height);
+
+        /// <summary>
+        /// Wraps an existing contiguous memory area of 'width' x 'height' pixels,
+        /// allowing to view/manipulate it as an <see cref="Image{TPixel}"/> instance.
+        /// </summary>
+        /// <typeparam name="TPixel">The pixel type</typeparam>
+        /// <param name="configuration">The <see cref="Configuration"/></param>
+        /// <param name="byteMemory">The byte memory representing the pixel data.</param>
+        /// <param name="width">The width of the memory image.</param>
+        /// <param name="height">The height of the memory image.</param>
+        /// <param name="metadata">The <see cref="ImageMetadata"/>.</param>
+        /// <exception cref="ArgumentNullException">The configuration is null.</exception>
+        /// <exception cref="ArgumentNullException">The metadata is null.</exception>
+        /// <returns>An <see cref="Image{TPixel}"/> instance</returns>
+        public static Image<TPixel> WrapMemory<TPixel>(
+            Configuration configuration,
+            Memory<byte> byteMemory,
+            int width,
+            int height,
+            ImageMetadata metadata)
+            where TPixel : unmanaged, IPixel<TPixel>
+        {
+            Guard.NotNull(configuration, nameof(configuration));
+            Guard.NotNull(metadata, nameof(metadata));
+
+            var memoryManager = new ByteMemoryManager<TPixel>(byteMemory);
+
+            Guard.IsTrue(memoryManager.Memory.Length == width * height, nameof(byteMemory), "The length of the input memory doesn't match the specified image size");
+
+            var memorySource = MemoryGroup<TPixel>.Wrap(memoryManager.Memory);
+            return new Image<TPixel>(configuration, memorySource, width, height, metadata);
+        }
+
+        /// <summary>
+        /// Wraps an existing contiguous memory area of 'width' x 'height' pixels,
+        /// allowing to view/manipulate it as an <see cref="Image{TPixel}"/> instance.
+        /// </summary>
+        /// <typeparam name="TPixel">The pixel type</typeparam>
+        /// <param name="configuration">The <see cref="Configuration"/></param>
+        /// <param name="byteMemory">The byte memory representing the pixel data.</param>
+        /// <param name="width">The width of the memory image.</param>
+        /// <param name="height">The height of the memory image.</param>
+        /// <exception cref="ArgumentNullException">The configuration is null.</exception>
+        /// <returns>An <see cref="Image{TPixel}"/> instance.</returns>
+        public static Image<TPixel> WrapMemory<TPixel>(
+            Configuration configuration,
+            Memory<byte> byteMemory,
+            int width,
+            int height)
+            where TPixel : unmanaged, IPixel<TPixel>
+            => WrapMemory<TPixel>(configuration, byteMemory, width, height, new ImageMetadata());
+
+        /// <summary>
+        /// Wraps an existing contiguous memory area of 'width' x 'height' pixels,
+        /// allowing to view/manipulate it as an <see cref="Image{TPixel}"/> instance.
+        /// The memory is being observed, the caller remains responsible for managing it's lifecycle.
+        /// </summary>
+        /// <typeparam name="TPixel">The pixel type.</typeparam>
+        /// <param name="byteMemory">The byte memory representing the pixel data.</param>
+        /// <param name="width">The width of the memory image.</param>
+        /// <param name="height">The height of the memory image.</param>
+        /// <returns>An <see cref="Image{TPixel}"/> instance.</returns>
+        public static Image<TPixel> WrapMemory<TPixel>(
+            Memory<byte> byteMemory,
+            int width,
+            int height)
+            where TPixel : unmanaged, IPixel<TPixel>
+            => WrapMemory<TPixel>(Configuration.Default, byteMemory, width, height);
     }
 }

src/ImageSharp/Memory/ByteMemoryManager{T}.cs

@@ -0,0 +1,57 @@
+// Copyright (c) Six Labors.
+// Licensed under the Apache License, Version 2.0.
+using System;
+using System.Buffers;
+using System.Runtime.CompilerServices;
+using System.Runtime.InteropServices;
+
+namespace SixLabors.ImageSharp.Memory
+{
+    /// <summary>
+    /// A custom <see cref="MemoryManager{T}"/> that can wrap <see cref="Memory{T}"/> of <see cref="byte"/> instances
+    /// and cast them to be <see cref="Memory{T}"/> for any arbitrary unmanaged <typeparamref name="T"/> value type.
+    /// </summary>
+    /// <typeparam name="T">The value type to use when casting the wrapped <see cref="Memory{T}"/> instance.</typeparam>
+    internal sealed class ByteMemoryManager<T> : MemoryManager<T>
+        where T : unmanaged
+    {
+        /// <summary>
+        /// The wrapped <see cref="Memory{T}"/> of <see cref="byte"/> instance.
+        /// </summary>
+        private readonly Memory<byte> memory;
+
+        /// <summary>
+        /// Initializes a new instance of the <see cref="ByteMemoryManager{T}"/> class.
+        /// </summary>
+        /// <param name="memory">The <see cref="Memory{T}"/> of <see cref="byte"/> instance to wrap.</param>
+        public ByteMemoryManager(Memory<byte> memory)
+        {
+            this.memory = memory;
+        }
+
+        /// <inheritdoc/>
+        protected override void Dispose(bool disposing)
+        {
+        }
+
+        /// <inheritdoc/>
+        public override Span<T> GetSpan()
+        {
+            return MemoryMarshal.Cast<byte, T>(this.memory.Span);
+        }
+
+        /// <inheritdoc/>
+        public override MemoryHandle Pin(int elementIndex = 0)
+        {
+            // We need to adjust the offset into the wrapped byte segment,
+            // as the input index refers to the target-cast memory of T.
+            // We just have to shift this index by the byte size of T.
+            return this.memory.Slice(elementIndex * Unsafe.SizeOf<T>()).Pin();
+        }
+
+        /// <inheritdoc/>
+        public override void Unpin()
+        {
+        }
+    }
+}

src/ImageSharp/Memory/MemoryOwnerExtensions.cs

@@ -13,13 +13,27 @@ namespace SixLabors.ImageSharp.Memory
     /// </summary>
     internal static class MemoryOwnerExtensions
     {
+        /// <summary>
+        /// Gets a <see cref="Span{T}"/> from an <see cref="IMemoryOwner{T}"/> instance.
+        /// </summary>
+        /// <param name="buffer">The buffer</param>
+        /// <returns>The <see cref="Span{T}"/></returns>
         [MethodImpl(MethodImplOptions.AggressiveInlining)]
         public static Span<T> GetSpan<T>(this IMemoryOwner<T> buffer)
-            => buffer.Memory.Span;
+        {
+            return buffer.Memory.Span;
+        }
 
+        /// <summary>
+        /// Gets the length of an <see cref="IMemoryOwner{T}"/> internal buffer.
+        /// </summary>
+        /// <param name="buffer">The buffer</param>
+        /// <returns>The length of the buffer</returns>
         [MethodImpl(MethodImplOptions.AggressiveInlining)]
         public static int Length<T>(this IMemoryOwner<T> buffer)
-            => buffer.GetSpan().Length;
+        {
+            return buffer.Memory.Length;
+        }
 
         /// <summary>
         /// Gets a <see cref="Span{T}"/> to an offsetted position inside the buffer.
@@ -56,8 +70,16 @@ public static void Clear<T>(this IMemoryOwner<T> buffer)
             buffer.GetSpan().Clear();
         }
 
+        /// <summary>
+        /// Gets a reference to the first item in the internal buffer for an <see cref="IMemoryOwner{T}"/> instance.
+        /// </summary>
+        /// <param name="buffer">The buffer</param>
+        /// <returns>A reference to the first item within the memory wrapped by <paramref name="buffer"/></returns>
+        [MethodImpl(MethodImplOptions.AggressiveInlining)]
         public static ref T GetReference<T>(this IMemoryOwner<T> buffer)
-            where T : struct =>
-            ref MemoryMarshal.GetReference(buffer.GetSpan());
+            where T : struct
+        {
+            return ref MemoryMarshal.GetReference(buffer.GetSpan());
+        }
     }
 }

src/ImageSharp/Processing/Processors/Dithering/OrderedDither.cs

@@ -262,7 +262,7 @@ public PaletteDitherRowOperation(
                 this.source = source;
                 this.bounds = bounds;
                 this.scale = processor.DitherScale;
-                this.bitDepth = ImageMaths.GetBitsNeededForColorDepth(processor.Palette.Span.Length);
+                this.bitDepth = ImageMaths.GetBitsNeededForColorDepth(processor.Palette.Length);
             }
 
             [MethodImpl(InliningOptions.ShortMethod)]