[Breaking change] feat: support Win32ScreencapMethods speed test

docs/articles/overview-of-wrapper-and-api.md

@@ -24,7 +24,7 @@
 | --- | --- |
 | AdbScreencapMethods | `MaaAdbScreencapMethod` |
 | AdbInputMethods | `MaaAdbInputMethod` |
-| Win32ScreencapMethod | `MaaWin32ScreencapMethod` |
+| Win32ScreencapMethods | `MaaWin32ScreencapMethod` |
 | Win32InputMethod | `MaaWin32InputMethod` |
 | MacOSScreencapMethod | `MaaMacOSScreencapMethod` |
 | MacOSInputMethod | `MaaMacOSInputMethod` |

src/MaaFramework.Binding.Native/Extensions/DesktopWindowInfoExtensions.cs

@@ -9,7 +9,7 @@ public static class DesktopWindowInfoExtensions
     ///     Converts a <see cref="DesktopWindowInfo"/> to a <see cref="MaaWin32Controller"/>.
     /// </summary>
     /// <param name="info">The DesktopWindowInfo.</param>
-    /// <param name="screencapMethod">The screencap method.</param>
+    /// <param name="screencapMethods">The screencap methods.</param>
     /// <param name="mouseMethod">The mouse method.</param>
     /// <param name="keyboardMethod">The keyboard method.</param>
     /// <param name="hWnd">The new handle to a win32 window.</param>
@@ -18,7 +18,7 @@ public static class DesktopWindowInfoExtensions
     /// <returns>A MaaWin32Controller.</returns>
     /// <exception cref="ArgumentNullException"/>
     public static MaaWin32Controller ToWin32ControllerWith(this DesktopWindowInfo info,
-        Win32ScreencapMethod? screencapMethod = null,
+        Win32ScreencapMethods? screencapMethods = null,
         Win32InputMethod? mouseMethod = null,
         Win32InputMethod? keyboardMethod = null,
         nint? hWnd = null,
@@ -33,7 +33,7 @@ public static MaaWin32Controller ToWin32ControllerWith(this DesktopWindowInfo in
                 handle,
                 handle == info.Handle ? info.Name : string.Empty,
                 handle == info.Handle ? info.ClassName : string.Empty,
-                screencapMethod ?? info.ScreencapMethod,
+                screencapMethods ?? info.ScreencapMethods,
                 mouseMethod ?? info.MouseMethod,
                 keyboardMethod ?? info.KeyboardMethod
             ),
@@ -42,7 +42,7 @@ public static MaaWin32Controller ToWin32ControllerWith(this DesktopWindowInfo in
         );
     }
 
-    /// <inheritdoc cref="ToWin32ControllerWith(DesktopWindowInfo, Win32ScreencapMethod?, Win32InputMethod?, Win32InputMethod?, nint?, LinkOption, CheckStatusOption)"/>
+    /// <inheritdoc cref="ToWin32ControllerWith(DesktopWindowInfo, Win32ScreencapMethods?, Win32InputMethod?, Win32InputMethod?, nint?, LinkOption, CheckStatusOption)"/>
     public static MaaWin32Controller ToWin32Controller(this DesktopWindowInfo info,
         LinkOption link = LinkOption.Start,
         CheckStatusOption check = CheckStatusOption.ThrowIfNotSucceeded)
@@ -57,15 +57,15 @@ public static MaaWin32Controller ToWin32Controller(this DesktopWindowInfo info,
     /// </summary>
     /// <param name="info">The DesktopWindowInfo.</param>
     /// <param name="gamepadType">The type of virtual gamepad.</param>
-    /// <param name="screencapMethod">The screencap method.</param>
+    /// <param name="screencapMethods">The screencap methods.</param>
     /// <param name="hWnd">The new handle to a win32 window.</param>
     /// <param name="link">Executes <see cref="MaaController.LinkStart"/> if <see cref="LinkOption.Start"/>; otherwise, not link.</param>
     /// <param name="check">Checks LinkStart().Wait() status if <see cref="CheckStatusOption.ThrowIfNotSucceeded"/>; otherwise, not check.</param>
     /// <returns>A MaaGamepadController.</returns>
     /// <exception cref="ArgumentNullException"/>
     public static MaaGamepadController ToGamepadControllerWith(this DesktopWindowInfo info,
         GamepadType gamepadType,
-        Win32ScreencapMethod? screencapMethod = null,
+        Win32ScreencapMethods? screencapMethods = null,
         nint? hWnd = null,
         LinkOption link = LinkOption.Start,
         CheckStatusOption check = CheckStatusOption.ThrowIfNotSucceeded)
@@ -82,7 +82,7 @@ public static MaaGamepadController ToGamepadControllerWith(this DesktopWindowInf
                 handle,
                 handle == info.Handle ? info.Name : string.Empty,
                 handle == info.Handle ? info.ClassName : string.Empty,
-                screencapMethod ?? info.ScreencapMethod,
+                screencapMethods ?? info.ScreencapMethods,
                 Win32InputMethod.None,
                 Win32InputMethod.None
             ),
@@ -91,7 +91,7 @@ public static MaaGamepadController ToGamepadControllerWith(this DesktopWindowInf
         );
     }
 
-    /// <inheritdoc cref="ToGamepadControllerWith(DesktopWindowInfo, GamepadType, Win32ScreencapMethod?, nint?, LinkOption, CheckStatusOption)"/>
+    /// <inheritdoc cref="ToGamepadControllerWith(DesktopWindowInfo, GamepadType, Win32ScreencapMethods?, nint?, LinkOption, CheckStatusOption)"/>
     public static MaaGamepadController ToGamepadController(this DesktopWindowInfo info,
         GamepadType gamepadType,
         LinkOption link = LinkOption.Start,

src/MaaFramework.Binding.Native/MaaController/MaaGamepadController.cs

@@ -37,7 +37,7 @@ public class MaaGamepadController : MaaController
     [DebuggerBrowsable(DebuggerBrowsableState.Never)]
     private string DebuggerInfoString => _debugInfo is null
         ? "No Screencap"
-        : $"{nameof(_debugInfo.Name)} = {_debugInfo.Name}, {nameof(_debugInfo.ClassName)} = {_debugInfo.ClassName}, ScreencapMethod = {_debugInfo.ScreencapMethod}";
+        : $"{nameof(_debugInfo.Name)} = {_debugInfo.Name}, {nameof(_debugInfo.ClassName)} = {_debugInfo.ClassName}, ScreencapMethods = {_debugInfo.ScreencapMethods}";
 
     /// <summary>
     ///     Creates a <see cref="MaaGamepadController"/> instance.
@@ -54,7 +54,7 @@ public MaaGamepadController(GamepadType gamepadType, DesktopWindowInfo? info = n
     {
         var handle = info is null
             ? MaaGamepadControllerCreate(nint.Zero, (MaaGamepadType)gamepadType, 0UL)
-            : MaaGamepadControllerCreate(info.Handle, (MaaGamepadType)gamepadType, (MaaWin32ScreencapMethod)info.ScreencapMethod);
+            : MaaGamepadControllerCreate(info.Handle, (MaaGamepadType)gamepadType, (MaaWin32ScreencapMethod)info.ScreencapMethods);
         _ = MaaControllerAddSink(handle, MaaEventCallback, (nint)MaaHandleType.Controller);
         SetHandle(handle, needReleased: true);
 
@@ -67,12 +67,12 @@ public MaaGamepadController(GamepadType gamepadType, DesktopWindowInfo? info = n
 
     /// <param name="hWnd">Window handle for screencap (optional, can be <see cref="nint.Zero"/> if screencap not needed).</param>
     /// <param name="gamepadType">Type of virtual gamepad (<see cref="GamepadType.Xbox360"/> or <see cref="GamepadType.DualShock4"/>).</param>
-    /// <param name="screencapMethod">Win32 screencap method to use. Ignored if hWnd is <see cref="nint.Zero"/>.</param>
+    /// <param name="screencapMethods">Win32 screencap methods to use. Ignored if hWnd is <see cref="nint.Zero"/>.</param>
     /// <param name="link">Executes <see cref="IMaaController.LinkStart"/> if <see cref="LinkOption.Start"/>; otherwise, not link.</param>
     /// <param name="check">Checks LinkStart().Wait() status if <see cref="CheckStatusOption.ThrowIfNotSucceeded"/>; otherwise, not check.</param>
     /// <inheritdoc cref="Binding.MaaGamepadController(GamepadType, DesktopWindowInfo, LinkOption, CheckStatusOption)"/>
-    public MaaGamepadController(nint hWnd, GamepadType gamepadType, Win32ScreencapMethod screencapMethod, LinkOption link = LinkOption.Start, CheckStatusOption check = CheckStatusOption.ThrowIfNotSucceeded)
-        : this(gamepadType, hWnd == nint.Zero ? null : new(hWnd, string.Empty, string.Empty, screencapMethod, Win32InputMethod.None, Win32InputMethod.None), link, check)
+    public MaaGamepadController(nint hWnd, GamepadType gamepadType, Win32ScreencapMethods screencapMethods, LinkOption link = LinkOption.Start, CheckStatusOption check = CheckStatusOption.ThrowIfNotSucceeded)
+        : this(gamepadType, hWnd == nint.Zero ? null : new(hWnd, string.Empty, string.Empty, screencapMethods, Win32InputMethod.None, Win32InputMethod.None), link, check)
     {
     }
 

src/MaaFramework.Binding.Native/MaaController/MaaWin32Controller.cs

@@ -16,7 +16,7 @@ public class MaaWin32Controller : MaaController
     [DebuggerBrowsable(DebuggerBrowsableState.Never)]
     private string DebuggerDisplay => IsInvalid
         ? $"Invalid {GetType().Name}"
-        : $"{GetType().Name} {{ {nameof(_debugInfo.Name)} = {_debugInfo.Name}, {nameof(_debugInfo.ClassName)} = {_debugInfo.ClassName}, ScreencapMethod = {_debugInfo.ScreencapMethod}, MouseMethod = {_debugInfo.MouseMethod}, KeyboardMethod = {_debugInfo.KeyboardMethod} }}";
+        : $"{GetType().Name} {{ {nameof(_debugInfo.Name)} = {_debugInfo.Name}, {nameof(_debugInfo.ClassName)} = {_debugInfo.ClassName}, ScreencapMethods = {_debugInfo.ScreencapMethods}, MouseMethod = {_debugInfo.MouseMethod}, KeyboardMethod = {_debugInfo.KeyboardMethod} }}";
 
     /// <summary>
     ///     Creates a <see cref="MaaWin32Controller"/> instance.
@@ -34,7 +34,7 @@ public MaaWin32Controller(DesktopWindowInfo info, LinkOption link = LinkOption.S
         ArgumentNullException.ThrowIfNull(info);
         if (info.Handle == nint.Zero) throw new ArgumentException("Value cannot be zero.", "info.Handle");
 
-        var handle = MaaWin32ControllerCreate(info.Handle, (MaaWin32ScreencapMethod)info.ScreencapMethod, (MaaWin32InputMethod)info.MouseMethod, (MaaWin32InputMethod)info.KeyboardMethod);
+        var handle = MaaWin32ControllerCreate(info.Handle, (MaaWin32ScreencapMethod)info.ScreencapMethods, (MaaWin32InputMethod)info.MouseMethod, (MaaWin32InputMethod)info.KeyboardMethod);
         _ = MaaControllerAddSink(handle, MaaEventCallback, (nint)MaaHandleType.Controller);
         SetHandle(handle, needReleased: true);
 
@@ -45,14 +45,14 @@ public MaaWin32Controller(DesktopWindowInfo info, LinkOption link = LinkOption.S
     }
 
     /// <param name="hWnd">The handle to a win32 window.</param>
-    /// <param name="screencapMethod">The screencap method.</param>
+    /// <param name="screencapMethods">The screencap methods.</param>
     /// <param name="mouseMethod">The mouse method.</param>
     /// <param name="keyboardMethod">The keyboard method.</param>
     /// <param name="link">Executes <see cref="IMaaController.LinkStart"/> if <see cref="LinkOption.Start"/>; otherwise, not link.</param>
     /// <param name="check">Checks LinkStart().Wait() status if <see cref="CheckStatusOption.ThrowIfNotSucceeded"/>; otherwise, not check.</param>
     /// <inheritdoc cref="Binding.MaaWin32Controller(DesktopWindowInfo, LinkOption, CheckStatusOption)"/>
-    public MaaWin32Controller(nint hWnd, Win32ScreencapMethod screencapMethod, Win32InputMethod mouseMethod, Win32InputMethod keyboardMethod, LinkOption link = LinkOption.Start, CheckStatusOption check = CheckStatusOption.ThrowIfNotSucceeded)
-        : this(new DesktopWindowInfo(hWnd, string.Empty, string.Empty, screencapMethod, mouseMethod, keyboardMethod), link, check)
+    public MaaWin32Controller(nint hWnd, Win32ScreencapMethods screencapMethods, Win32InputMethod mouseMethod, Win32InputMethod keyboardMethod, LinkOption link = LinkOption.Start, CheckStatusOption check = CheckStatusOption.ThrowIfNotSucceeded)
+        : this(new DesktopWindowInfo(hWnd, string.Empty, string.Empty, screencapMethods, mouseMethod, keyboardMethod), link, check)
     {
     }
 }

src/MaaFramework.Binding.UnitTests/Test_IMaaController.cs

@@ -1,3 +1,3 @@
 using MaaFramework.Binding.Abstractions;
 using MaaFramework.Binding.Buffers;
 using System.Runtime.InteropServices;
@@ -118,18 +118,18 @@
 
         using var win32Native1 = new MaaWin32Controller(
             windowInfo.Handle,
-            Win32ScreencapMethod.GDI,
+            Win32ScreencapMethods.GDI,
             Win32InputMethod.SendMessage,
             Win32InputMethod.SendMessage);
         using var win32Native2 = new MaaWin32Controller(
             windowInfo.Handle,
-            Win32ScreencapMethod.GDI,
+            Win32ScreencapMethods.GDI,
             Win32InputMethod.SendMessage,
             Win32InputMethod.SendMessage,
             LinkOption.None);
         using var win32Native3 = new MaaWin32Controller(
             windowInfo.Handle,
-            Win32ScreencapMethod.GDI,
+            Win32ScreencapMethods.GDI,
             Win32InputMethod.SendMessage,
             Win32InputMethod.SendMessage,
             LinkOption.Start,

src/MaaFramework.Binding.UnitTests/Test_IMaaToolkit.cs

@@ -103,7 +103,7 @@ private static void Test_Win32_WindowInfos(MaaTypes type, IList<DesktopWindowInf
         using var maaController = type switch
         {
             MaaTypes.Native => windows[0].ToWin32ControllerWith(
-                screencapMethod: Win32ScreencapMethod.GDI,
+                screencapMethods: Win32ScreencapMethods.GDI,
                 mouseMethod: Win32InputMethod.SendMessage,
                 keyboardMethod: Win32InputMethod.SendMessage,
                 link: LinkOption.None),
@@ -118,7 +118,7 @@ private static void Test_Win32_WindowInfos(MaaTypes type, IList<DesktopWindowInf
         using var optionalArgumentDefaultValuesTest = type switch
         {
             MaaTypes.Native => windows[0].ToWin32ControllerWith(
-                screencapMethod: Win32ScreencapMethod.GDI,
+                screencapMethods: Win32ScreencapMethods.GDI,
                 mouseMethod: Win32InputMethod.SendMessage,
                 keyboardMethod: Win32InputMethod.SendMessage),
             _ => throw new NotImplementedException(),

src/MaaFramework.Binding/Enums/Controllers/Win32ScreencapMethods.cs

@@ -0,0 +1,60 @@
+//------------------------------------------------------------------------------
+// <auto-generated>
+//     This code was generated by a tool.
+//
+//     Changes to this file may cause incorrect behavior and will be lost if
+//     the code is regenerated.
+// </auto-generated>
+//------------------------------------------------------------------------------
+
+#pragma warning disable CS1573 // 参数在 XML 注释中没有匹配的 param 标记
+#pragma warning disable CS1591 // 缺少对公共可见类型或成员的 XML 注释
+
+namespace MaaFramework.Binding;
+
+/// <summary>
+///     Win32 screencap method flags
+/// 
+/// <para>Use bitwise OR to set the methods you need.
+/// <br/>MaaFramework will test all provided methods and use the fastest available one.</para>
+/// 
+/// <para>No default value. Client should choose one as default.</para>
+/// 
+/// <para>Predefined combinations:
+/// <br/>- Foreground: DXGI_DesktopDup_Window | ScreenDC
+/// <br/>- Background: FramePool | PrintWindow</para>
+/// 
+/// <para>Different applications use different rendering methods, there is no universal solution.</para>
+/// 
+/// <code>| Method                  | Speed     | Compatibility | Require Admin | Background Support | Notes                            |
+/// <br/>|-------------------------|-----------|---------------|---------------|--------------------|----------------------------------|
+/// <br/>| GDI                     | Fast      | Medium        | No            | No                 |                                  |
+/// <br/>| FramePool               | Very Fast | Medium        | No            | Yes                | Requires Windows 10 1903+        |
+/// <br/>| DXGI_DesktopDup         | Very Fast | Low           | No            | No                 | Desktop duplication (full screen)|
+/// <br/>| DXGI_DesktopDup_Window  | Very Fast | Low           | No            | No                 | Desktop duplication then crop    |
+/// <br/>| PrintWindow             | Medium    | Medium        | No            | Yes                |                                  |
+/// <br/>| ScreenDC                | Fast      | High          | No            | No                 |                                  |
+/// </code>
+/// 
+/// <para>Note: FramePool and PrintWindow support pseudo-minimize — when the target window
+///     <br/>is minimized, they make it transparent and click-through, then restore it without
+///     <br/>activation, allowing screencap to continue without disturbing the user.
+///     <br/>Other screencap methods will fail when the target window is minimized.</para>
+/// 
+/// </summary>
+[Flags]
+public enum Win32ScreencapMethods : System.UInt64
+{
+    None = 0,
+    GDI = 1,
+    FramePool = (1 << 1),
+    DXGI_DesktopDup = (1 << 2),
+    DXGI_DesktopDup_Window = (1 << 3),
+    PrintWindow = (1 << 4),
+    ScreenDC = (1 << 5),
+
+    All = ~None,
+    Foreground = DXGI_DesktopDup_Window | ScreenDC,
+    Background = FramePool | PrintWindow,
+}
+

src/MaaFramework.Binding/Infos/DesktopWindowInfo.cs

@@ -6,14 +6,14 @@
 /// <param name="Handle">Gets the handle to a window.</param>
 /// <param name="Name">Gets the window name.</param>
 /// <param name="ClassName">Gets the window class name.</param>
-/// <param name="ScreencapMethod">The screencap method.</param>
+/// <param name="ScreencapMethods">The screencap methods.</param>
 /// <param name="MouseMethod">The mouse method.</param>
 /// <param name="KeyboardMethod">The keyboard method.</param>
 public record DesktopWindowInfo(
     nint Handle,
     string Name,
     string ClassName,
-    Win32ScreencapMethod ScreencapMethod = Win32ScreencapMethod.DXGI_DesktopDup,
+    Win32ScreencapMethods ScreencapMethods = Win32ScreencapMethods.Background,
     Win32InputMethod MouseMethod = Win32InputMethod.Seize,
     Win32InputMethod KeyboardMethod = Win32InputMethod.Seize
 );