Add WebGPU environment options and preference

Author: JimBobSquarePants

src/ImageSharp.Drawing.WebGPU/WEBGPU_BACKEND.md

@@ -27,6 +27,10 @@ The public WebGPU surface area around this backend is small and target-first.
 
 `WebGPUDeviceContext` is internal infrastructure used by targets and surfaces. It is not part of the public WebGPU entry-point model.
 
+`WebGPUEnvironment.Options` configures the library-managed WebGPU environment before first use. Set it before
+constructing WebGPU objects or calling support probes; the shared runtime reads the current options during first
+initialization and does not reconfigure an existing device after that point.
+
 Those types all exist to get a `DrawingCanvas` over a native WebGPU target. Once the canvas flushes, `WebGPUDrawingBackend` becomes the execution boundary.
 
 The support probes also live outside the backend:

src/ImageSharp.Drawing.WebGPU/WebGPUEnvironment.cs

@@ -9,6 +9,15 @@ namespace SixLabors.ImageSharp.Drawing.Processing.Backends;
 /// </summary>
 public static class WebGPUEnvironment
 {
+    /// <summary>
+    /// Gets or sets the options used when the library-managed WebGPU environment is initialized.
+    /// </summary>
+    /// <remarks>
+    /// Assign this before constructing WebGPU objects or calling support probes. The shared WebGPU runtime reads the
+    /// current options during first initialization; changing them later does not reconfigure an existing device.
+    /// </remarks>
+    public static WebGPUEnvironmentOptions Options { get; set; } = WebGPUEnvironmentOptions.Default;
+
     /// <summary>
     /// Gets or sets the callback invoked when the native WebGPU runtime reports an uncaptured device error.
     /// </summary>

src/ImageSharp.Drawing.WebGPU/WebGPUEnvironmentOptions.cs

@@ -0,0 +1,24 @@
+// Copyright (c) Six Labors.
+// Licensed under the Six Labors Split License.
+
+namespace SixLabors.ImageSharp.Drawing.Processing.Backends;
+
+/// <summary>
+/// Options for the library-managed WebGPU environment.
+/// </summary>
+/// <remarks>
+/// Assign these options before constructing WebGPU objects or calling support probes. The shared WebGPU runtime reads
+/// the current options during first initialization; changing them later does not reconfigure an existing device.
+/// </remarks>
+public sealed class WebGPUEnvironmentOptions
+{
+    /// <summary>
+    /// Gets the default WebGPU environment options.
+    /// </summary>
+    public static WebGPUEnvironmentOptions Default { get; } = new();
+
+    /// <summary>
+    /// Gets or sets the adapter power preference requested for the library-managed device.
+    /// </summary>
+    public WebGPUPowerPreference PowerPreference { get; set; } = WebGPUPowerPreference.HighPerformance;
+}

src/ImageSharp.Drawing.WebGPU/WebGPUPowerPreference.cs

@@ -0,0 +1,25 @@
+// Copyright (c) Six Labors.
+// Licensed under the Six Labors Split License.
+
+namespace SixLabors.ImageSharp.Drawing.Processing.Backends;
+
+/// <summary>
+/// Describes the adapter power preference requested for the library-managed WebGPU device.
+/// </summary>
+public enum WebGPUPowerPreference
+{
+    /// <summary>
+    /// Uses the native WebGPU runtime default.
+    /// </summary>
+    Default,
+
+    /// <summary>
+    /// Prefers a lower-power adapter when the platform provides one.
+    /// </summary>
+    LowPower,
+
+    /// <summary>
+    /// Prefers a high-performance adapter when the platform provides one.
+    /// </summary>
+    HighPerformance
+}

src/ImageSharp.Drawing.WebGPU/WebGPURuntime.cs

@@ -533,9 +533,17 @@ void Callback(RequestAdapterStatus status, Adapter* adapterPtr, byte* message, v
         }
 
         using PfnRequestAdapterCallback callbackPtr = PfnRequestAdapterCallback.From(Callback);
+        WebGPUEnvironmentOptions environmentOptions = WebGPUEnvironment.Options;
+
         RequestAdapterOptions options = new()
         {
-            PowerPreference = PowerPreference.HighPerformance
+            PowerPreference = environmentOptions.PowerPreference switch
+            {
+                WebGPUPowerPreference.Default => PowerPreference.Undefined,
+                WebGPUPowerPreference.LowPower => PowerPreference.LowPower,
+                WebGPUPowerPreference.HighPerformance => PowerPreference.HighPerformance,
+                _ => throw new InvalidOperationException("The WebGPU power preference mapping is incomplete.")
+            }
         };
 
         api.InstanceRequestAdapter(instance, in options, callbackPtr, null);