Bokeh blur implementation

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

@@ -61,13 +61,31 @@ public Buffer2D(MemorySource<T> memorySource, int width, int height)
             [MethodImpl(MethodImplOptions.AggressiveInlining)]
             get
             {
-                ImageSharp.DebugGuard.MustBeLessThan(x, this.Width, nameof(x));
-                ImageSharp.DebugGuard.MustBeLessThan(y, this.Height, nameof(y));
+                DebugGuard.MustBeLessThan(x, this.Width, nameof(x));
+                DebugGuard.MustBeLessThan(y, this.Height, nameof(y));
+
                 Span<T> span = this.Span;
                 return ref span[(this.Width * y) + x];
             }
         }
 
+        /// <summary>
+        /// Creates a new <see cref="Buffer2D{T}"/> instance that maps to a target rows interval from the current instance.
+        /// </summary>
+        /// <param name="y">The target vertical offset for the rows interval to retrieve.</param>
+        /// <param name="h">The desired number of rows to extract.</param>
+        /// <returns>The new <see cref="Buffer2D{T}"/> instance with the requested rows interval.</returns>
+        public Buffer2D<T> Slice(int y, int h)
+        {
+            DebugGuard.MustBeGreaterThanOrEqualTo(y, 0, nameof(y));
+            DebugGuard.MustBeGreaterThan(h, 0, nameof(h));
+            DebugGuard.MustBeLessThanOrEqualTo(y + h, this.Height, nameof(h));
+
+            Memory<T> slice = this.Memory.Slice(y * this.Width, h * this.Width);
+            var memory = new MemorySource<T>(slice);
+            return new Buffer2D<T>(memory, this.Width, h);
+        }
+
         /// <summary>
         /// Disposes the <see cref="Buffer2D{T}"/> instance
         /// </summary>
@@ -98,4 +116,4 @@ private static void SwapDimensionData(Buffer2D<T> a, Buffer2D<T> b)
             a.Height = bSize.Height;
         }
     }
-}
+}

src/ImageSharp/Processing/Extensions/BokehBlurExtensions.cs

@@ -2,6 +2,7 @@
 // Licensed under the Apache License, Version 2.0.
 
 using SixLabors.ImageSharp.Processing.Processors.Convolution;
+using SixLabors.ImageSharp.Processing.Processors.Convolution.Parameters;
 using SixLabors.Primitives;
 
 namespace SixLabors.ImageSharp.Processing
@@ -19,6 +20,15 @@ public static class BokehBlurExtensions
         public static IImageProcessingContext BokehBlur(this IImageProcessingContext source)
             => source.ApplyProcessor(new BokehBlurProcessor());
 
+        /// <summary>
+        /// Applies a bokeh blur to the image.
+        /// </summary>
+        /// <param name="source">The image this method extends.</param>
+        /// <param name="executionMode">The execution mode to use when applying the processor.</param>
+        /// <returns>The <see cref="IImageProcessingContext"/> to allow chaining of operations.</returns>
+        public static IImageProcessingContext BokehBlur(this IImageProcessingContext source, BokehBlurExecutionMode executionMode)
+            => source.ApplyProcessor(new BokehBlurProcessor(executionMode));
+
         /// <summary>
         /// Applies a bokeh blur to the image.
         /// </summary>
@@ -30,6 +40,18 @@ public static IImageProcessingContext BokehBlur(this IImageProcessingContext sou
         public static IImageProcessingContext BokehBlur(this IImageProcessingContext source, int radius, int components, float gamma)
             => source.ApplyProcessor(new BokehBlurProcessor(radius, components, gamma));
 
+        /// <summary>
+        /// Applies a bokeh blur to the image.
+        /// </summary>
+        /// <param name="source">The image this method extends.</param>
+        /// <param name="radius">The 'radius' value representing the size of the area to sample.</param>
+        /// <param name="components">The 'components' value representing the number of kernels to use to approximate the bokeh effect.</param>
+        /// <param name="gamma">The gamma highlight factor to use to emphasize bright spots in the source image</param>
+        /// <param name="executionMode">The execution mode to use when applying the processor.</param>
+        /// <returns>The <see cref="IImageProcessingContext"/> to allow chaining of operations.</returns>
+        public static IImageProcessingContext BokehBlur(this IImageProcessingContext source, int radius, int components, float gamma, BokehBlurExecutionMode executionMode)
+            => source.ApplyProcessor(new BokehBlurProcessor(radius, components, gamma, executionMode));
+
         /// <summary>
         /// Applies a bokeh blur to the image.
         /// </summary>
@@ -41,6 +63,18 @@ public static IImageProcessingContext BokehBlur(this IImageProcessingContext sou
         public static IImageProcessingContext BokehBlur(this IImageProcessingContext source, Rectangle rectangle)
             => source.ApplyProcessor(new BokehBlurProcessor(), rectangle);
 
+        /// <summary>
+        /// Applies a bokeh blur to the image.
+        /// </summary>
+        /// <param name="source">The image this method extends.</param>
+        /// <param name="rectangle">
+        /// The <see cref="Rectangle"/> structure that specifies the portion of the image object to alter.
+        /// </param>
+        /// <param name="executionMode">The execution mode to use when applying the processor.</param>
+        /// <returns>The <see cref="IImageProcessingContext"/> to allow chaining of operations.</returns>
+        public static IImageProcessingContext BokehBlur(this IImageProcessingContext source, Rectangle rectangle, BokehBlurExecutionMode executionMode)
+            => source.ApplyProcessor(new BokehBlurProcessor(executionMode), rectangle);
+
         /// <summary>
         /// Applies a bokeh blur to the image.
         /// </summary>
@@ -54,5 +88,20 @@ public static IImageProcessingContext BokehBlur(this IImageProcessingContext sou
         /// <returns>The <see cref="IImageProcessingContext"/> to allow chaining of operations.</returns>
         public static IImageProcessingContext BokehBlur(this IImageProcessingContext source, int radius, int components, float gamma, Rectangle rectangle)
             => source.ApplyProcessor(new BokehBlurProcessor(radius, components, gamma), rectangle);
+
+        /// <summary>
+        /// Applies a bokeh blur to the image.
+        /// </summary>
+        /// <param name="source">The image this method extends.</param>
+        /// <param name="radius">The 'radius' value representing the size of the area to sample.</param>
+        /// <param name="components">The 'components' value representing the number of kernels to use to approximate the bokeh effect.</param>
+        /// <param name="gamma">The gamma highlight factor to use to emphasize bright spots in the source image</param>
+        /// <param name="executionMode">The execution mode to use when applying the processor.</param>
+        /// <param name="rectangle">
+        /// The <see cref="Rectangle"/> structure that specifies the portion of the image object to alter.
+        /// </param>
+        /// <returns>The <see cref="IImageProcessingContext"/> to allow chaining of operations.</returns>
+        public static IImageProcessingContext BokehBlur(this IImageProcessingContext source, int radius, int components, float gamma, BokehBlurExecutionMode executionMode, Rectangle rectangle)
+            => source.ApplyProcessor(new BokehBlurProcessor(radius, components, gamma, executionMode), rectangle);
     }
 }

src/ImageSharp/Processing/Processors/Convolution/BokehBlurProcessor.cs

@@ -2,6 +2,7 @@
 // Licensed under the Apache License, Version 2.0.
 
 using SixLabors.ImageSharp.PixelFormats;
+using SixLabors.ImageSharp.Processing.Processors.Convolution.Parameters;
 
 namespace SixLabors.ImageSharp.Processing.Processors.Convolution
 {
@@ -25,11 +26,27 @@ public sealed class BokehBlurProcessor : IImageProcessor
         /// </summary>
         public const float DefaultGamma = 3F;
 
+        /// <summary>
+        /// The default execution mode used by the parameterless constructor.
+        /// </summary>
+        public const BokehBlurExecutionMode DefaultExecutionMode = BokehBlurExecutionMode.PreferLowMemoryUsage;
+
         /// <summary>
         /// Initializes a new instance of the <see cref="BokehBlurProcessor"/> class.
         /// </summary>
         public BokehBlurProcessor()
-            : this(DefaultRadius, DefaultComponents, DefaultGamma)
+            : this(DefaultRadius, DefaultComponents, DefaultGamma, DefaultExecutionMode)
+        {
+        }
+
+        /// <summary>
+        /// Initializes a new instance of the <see cref="BokehBlurProcessor"/> class.
+        /// </summary>
+        /// <param name="executionMode">
+        /// The execution mode to use when applying the processor.
+        /// </param>
+        public BokehBlurProcessor(BokehBlurExecutionMode executionMode)
+            : this(DefaultRadius, DefaultComponents, DefaultGamma, executionMode)
         {
         }
 
@@ -46,12 +63,33 @@ public BokehBlurProcessor()
         /// The gamma highlight factor to use to further process the image.
         /// </param>
         public BokehBlurProcessor(int radius, int components, float gamma)
+            : this(radius, components, gamma, DefaultExecutionMode)
+        {
+        }
+
+        /// <summary>
+        /// Initializes a new instance of the <see cref="BokehBlurProcessor"/> class.
+        /// </summary>
+        /// <param name="radius">
+        /// The 'radius' value representing the size of the area to sample.
+        /// </param>
+        /// <param name="components">
+        /// The number of components to use to approximate the original 2D bokeh blur convolution kernel.
+        /// </param>
+        /// <param name="gamma">
+        /// The gamma highlight factor to use to further process the image.
+        /// </param>
+        /// <param name="executionMode">
+        /// The execution mode to use when applying the processor.
+        /// </param>
+        public BokehBlurProcessor(int radius, int components, float gamma, BokehBlurExecutionMode executionMode)
         {
             Guard.MustBeGreaterThanOrEqualTo(gamma, 1, nameof(gamma));
 
             this.Radius = radius;
             this.Components = components;
             this.Gamma = gamma;
+            this.ExecutionMode = executionMode;
         }
 
         /// <summary>
@@ -69,6 +107,11 @@ public BokehBlurProcessor(int radius, int components, float gamma)
         /// </summary>
         public float Gamma { get; }
 
+        /// <summary>
+        /// Gets the exection mode to use when applying the effect.
+        /// </summary>
+        public BokehBlurExecutionMode ExecutionMode { get; }
+
         /// <inheritdoc />
         public IImageProcessor<TPixel> CreatePixelSpecificProcessor<TPixel>()
             where TPixel : struct, IPixel<TPixel>

src/ImageSharp/Processing/Processors/Convolution/BokehBlurProcessor{TPixel}.cs

@@ -36,7 +36,12 @@ internal class BokehBlurProcessor<TPixel> : ImageProcessor<TPixel>
         private readonly float gamma;
 
         /// <summary>
-        /// The maximum size of the kernel in either direction.
+        /// The execution mode to use when applying the effect
+        /// </summary>
+        private readonly BokehBlurExecutionMode executionMode;
+
+        /// <summary>
+        /// The maximum size of the kernel in either direction
         /// </summary>
         private readonly int kernelSize;
 
@@ -75,6 +80,7 @@ public BokehBlurProcessor(BokehBlurProcessor definition)
             this.kernelSize = (this.radius * 2) + 1;
             this.componentsCount = definition.Components;
             this.gamma = definition.Gamma;
+            this.executionMode = definition.ExecutionMode;
 
             // Reuse the initialized values from the cache, if possible
             var parameters = new BokehBlurParameters(this.radius, this.componentsCount);
@@ -271,30 +277,67 @@ protected override void OnFrameApply(ImageFrame<TPixel> source, Rectangle source
 
             // Create a 0-filled buffer to use to store the result of the component convolutions
             using (Buffer2D<Vector4> processing = configuration.MemoryAllocator.Allocate2D<Vector4>(source.Size(), AllocationOptions.Clean))
-            using (Buffer2D<ComplexVector4>
-                partialValues = configuration.MemoryAllocator.Allocate2D<ComplexVector4>(source.Size()),
-                firstPassValues = configuration.MemoryAllocator.Allocate2D<ComplexVector4>(source.Size()))
             {
-                // Perform two 1D convolutions for each component in the current instance
-                ref Complex64[] baseRef = ref MemoryMarshal.GetReference(this.kernels.AsSpan());
-                for (int i = 0; i < this.kernels.Length; i++)
+                if (this.executionMode == BokehBlurExecutionMode.PreferLowMemoryUsage)
                 {
-                    // Compute the resulting complex buffer for the current component
-                    var interest = Rectangle.Intersect(sourceRectangle, source.Bounds());
-                    Complex64[] kernel = Unsafe.Add(ref baseRef, i);
-                    this.ApplyConvolution(firstPassValues, source.PixelBuffer, interest, kernel, configuration);
-                    this.ApplyConvolution(partialValues, firstPassValues, interest, kernel, configuration);
-
-                    // Add the results of the convolution with the current kernel
-                    Vector4 parameters = this.kernelParameters[i];
-                    this.SumProcessingPartials(processing, partialValues, sourceRectangle, configuration, parameters.Z, parameters.W);
+                    // Memory usage priority: allocate a shared buffer and execute the second convolution in sequential mode
+                    using (Buffer2D<ComplexVector4> buffer = configuration.MemoryAllocator.Allocate2D<ComplexVector4>(source.Width, source.Height + this.radius))
+                    {
+                        Buffer2D<ComplexVector4> firstPassBuffer = buffer.Slice(this.radius, source.Height);
+                        Buffer2D<ComplexVector4> secondPassBuffer = buffer.Slice(0, source.Height);
+
+                        this.OnFrameApplyCore(source, sourceRectangle, configuration, processing, firstPassBuffer, secondPassBuffer);
+                    }
+                }
+                else
+                {
+                    // Performance priority: allocate two independent buffers and execute both convolutions in parallel mode
+                    using (Buffer2D<ComplexVector4>
+                        firstPassValues = configuration.MemoryAllocator.Allocate2D<ComplexVector4>(source.Size()),
+                        secondPassBuffer = configuration.MemoryAllocator.Allocate2D<ComplexVector4>(source.Size()))
+                    {
+                        this.OnFrameApplyCore(source, sourceRectangle, configuration, processing, firstPassValues, secondPassBuffer);
+                    }
                 }
 
                 // Apply the inverse gamma exposure pass, and write the final pixel data
                 this.ApplyInverseGammaExposure(source.PixelBuffer, processing, sourceRectangle, configuration);
             }
         }
 
+        /// <summary>
+        /// Computes and aggregates the convolution for each complex kernel component in the processor.
+        /// </summary>
+        /// <param name="source">The source image. Cannot be null.</param>
+        /// <param name="sourceRectangle">The <see cref="Rectangle" /> structure that specifies the portion of the image object to draw.</param>
+        /// <param name="configuration">The configuration.</param>
+        /// <param name="processingBuffer">The buffer with the raw pixel data to use to aggregate the results of each convolution.</param>
+        /// <param name="firstPassBuffer">The complex buffer to use for the first 1D convolution pass for each kernel.</param>
+        /// <param name="secondPassBuffer">The complex buffer to use for the second 1D convolution pass for each kernel.</param>
+        private void OnFrameApplyCore(
+            ImageFrame<TPixel> source,
+            Rectangle sourceRectangle,
+            Configuration configuration,
+            Buffer2D<Vector4> processingBuffer,
+            Buffer2D<ComplexVector4> firstPassBuffer,
+            Buffer2D<ComplexVector4> secondPassBuffer)
+        {
+            // Perform two 1D convolutions for each component in the current instance
+            ref Complex64[] baseRef = ref MemoryMarshal.GetReference(this.kernels.AsSpan());
+            for (int i = 0; i < this.kernels.Length; i++)
+            {
+                // Compute the resulting complex buffer for the current component
+                var interest = Rectangle.Intersect(sourceRectangle, source.Bounds());
+                Complex64[] kernel = Unsafe.Add(ref baseRef, i);
+                this.ApplyConvolution(firstPassBuffer, source.PixelBuffer, interest, kernel, configuration);
+                this.ApplyConvolution(secondPassBuffer, firstPassBuffer, interest, kernel, configuration);
+
+                // Add the results of the convolution with the current kernel
+                Vector4 parameters = this.kernelParameters[i];
+                this.SumProcessingPartials(processingBuffer, secondPassBuffer, sourceRectangle, configuration, parameters.Z, parameters.W);
+            }
+        }
+
         /// <summary>
         /// Applies the process to the specified portion of the specified <see cref="ImageFrame{TPixel}"/> at the specified location
         /// and with the specified size.
@@ -368,6 +411,12 @@ private void ApplyConvolution(
             var workingRectangle = Rectangle.FromLTRB(startX, startY, endX, endY);
             int width = workingRectangle.Width;
 
+            if (this.executionMode == BokehBlurExecutionMode.PreferLowMemoryUsage)
+            {
+                configuration = configuration.Clone();
+                configuration.MaxDegreeOfParallelism = 1;
+            }
+
             ParallelHelper.IterateRows(
                 workingRectangle,
                 configuration,

src/ImageSharp/Processing/Processors/Convolution/Parameters/BokehBlurExecutionMode.cs

@@ -0,0 +1,21 @@
+// Copyright (c) Six Labors and contributors.
+// Licensed under the Apache License, Version 2.0.
+
+namespace SixLabors.ImageSharp.Processing.Processors.Convolution.Parameters
+{
+    /// <summary>
+    /// An <see langword="enum"/> that indicates execution options for the <see cref="BokehBlurProcessor"/>.
+    /// </summary>
+    public enum BokehBlurExecutionMode
+    {
+        /// <summary>
+        /// Indicates that the maximum performance should be prioritized over memory usage.
+        /// </summary>
+        PreferMaximumPerformance,
+
+        /// <summary>
+        /// Indicates that the memory usage should be prioritized over raw performance.
+        /// </summary>
+        PreferLowMemoryUsage
+    }
+}