feat: Win32 截图方式测速 (#1183)

MistEO · web-flow · commit d068b135b9bb · 2026-03-05T21:41:46.000+08:00
diff --git a/docs/en_us/2.4-ControlMethods.md b/docs/en_us/2.4-ControlMethods.md
@@ -80,9 +80,9 @@ Different programs on Win32 handle input differently, so there is no universal m
 
 > Reference: [MaaDef.h](https://github.com/MaaXYZ/MaaFramework/blob/main/include/MaaFramework/MaaDef.h#L242-L250)
 
-Select one of the values below.
+Combine the selected methods below using **bitwise OR** to provide a single value. MaaFramework will try all provided methods and select the fastest available method.
 
-No default value. Client can choose one as the default.
+No default value. Client can choose one combination as the default.
 
 Different programs on Win32 handle rendering differently, so there is no universal method.
 
@@ -97,6 +97,12 @@ Different programs on Win32 handle rendering differently, so there is no univers
 
 > [!NOTE]
 >
+> Three predefined combination macros are provided:  
+>
+> - `MaaWin32ScreencapMethod_All`: all screencap methods  
+> - `MaaWin32ScreencapMethod_Foreground`: `DXGI_DesktopDup_Window | ScreenDC`  
+> - `MaaWin32ScreencapMethod_Background`: `FramePool | PrintWindow`  
+>
 > FramePool and PrintWindow have built-in pseudo-minimize support: when the target window is minimized, they make it transparent and click-through, then restore it without activation, allowing screencap to continue without disturbing the user.  
 > Other screencap methods will fail when the target window is minimized. Please avoid minimizing the window when using those methods.
 
@@ -178,4 +184,4 @@ The wlroots compositor to be controlled must support the following protocols:
 * Wayland Core Protocols
 * `virtual-keyboard-unstable-v1`
 * `wlr-screencopy-unstable-v1`
-* `wlr-virtual-pointer-unstable-v1`
+* `wlr-virtual-pointer-unstable-v1`
diff --git a/docs/zh_cn/2.4-控制方式说明.md b/docs/zh_cn/2.4-控制方式说明.md
@@ -80,9 +80,9 @@ Win32 下不同程序处理输入的方法不同，不存在一个通用方式
 
 > 参考 [MaaDef.h](https://github.com/MaaXYZ/MaaFramework/blob/main/include/MaaFramework/MaaDef.h#L242-L250)
 
-选择下面的值提供。
+将下面选择的方式 **按位或** 合并为一个值提供。MaaFramework 将会尝试所有提供的方式，选择最快的可用方式。
 
-无默认值。Client 可以选择一个作为默认值。
+无默认值。Client 可以选择一个组合作为默认值。
 
 Win32 下不同程序处理绘制的方法不同，不存在一个通用方式。
 
@@ -97,6 +97,12 @@ Win32 下不同程序处理绘制的方法不同，不存在一个通用方式
 
 > [!NOTE]
 >
+> 提供了三个组合宏便于直接使用：  
+>
+> - `MaaWin32ScreencapMethod_All`：所有截图方式  
+> - `MaaWin32ScreencapMethod_Foreground`：`DXGI_DesktopDup_Window | ScreenDC`  
+> - `MaaWin32ScreencapMethod_Background`：`FramePool | PrintWindow`  
+>
 > FramePool 和 PrintWindow 内置了伪最小化支持：当目标窗口被最小化时，会将窗口设为透明并开启点击穿透，以不激活的方式恢复窗口，从而在不打扰用户的情况下继续截图。  
 > 其他截图方式在窗口最小化后无法获取有效内容，请避免窗口最小化。
 
diff --git a/include/MaaFramework/MaaDef.h b/include/MaaFramework/MaaDef.h
@@ -294,12 +294,17 @@ typedef uint64_t MaaAdbInputMethod;
 
 // MaaWin32ScreencapMethod:
 /**
- * @brief Win32 screencap method
+ * @brief Win32 screencap method flags
  *
- * No bitwise OR, select ONE method only.
+ * Use bitwise OR to set the methods you need.
+ * MaaFramework will test all provided methods and use the fastest available one.
  *
  * No default value. Client should choose one as default.
  *
+ * Predefined combinations:
+ * - Foreground: DXGI_DesktopDup_Window | ScreenDC
+ * - Background: FramePool | PrintWindow
+ *
  * Different applications use different rendering methods, there is no universal solution.
  *
  * | Method                  | Speed     | Compatibility | Require Admin | Background Support | Notes                            |
@@ -325,6 +330,11 @@ typedef uint64_t MaaWin32ScreencapMethod;
 #define MaaWin32ScreencapMethod_PrintWindow (1ULL << 4)
 #define MaaWin32ScreencapMethod_ScreenDC (1ULL << 5)
 
+#define MaaWin32ScreencapMethod_All (~MaaWin32ScreencapMethod_None)
+#define MaaWin32ScreencapMethod_Foreground                                                                \
+    (MaaWin32ScreencapMethod_DXGI_DesktopDup_Window | MaaWin32ScreencapMethod_ScreenDC)
+#define MaaWin32ScreencapMethod_Background (MaaWin32ScreencapMethod_FramePool | MaaWin32ScreencapMethod_PrintWindow)
+
 // MaaWin32InputMethod:
 /**
  * @brief Win32 input method
diff --git a/source/MaaWin32ControlUnit/Manager/Win32ControlUnitMgr.cpp b/source/MaaWin32ControlUnit/Manager/Win32ControlUnitMgr.cpp
@@ -1,7 +1,10 @@
 #include "Win32ControlUnitMgr.h"
 
+#include <chrono>
+
 #include "MaaFramework/MaaMsg.h"
 #include "MaaUtils/Logger.h"
+#include "MaaUtils/Time.hpp"
 
 #include "Input/LegacyEventInput.h"
 #include "Input/MessageInput.h"
@@ -34,6 +37,7 @@ Win32ControlUnitMgr::Win32ControlUnitMgr(
 bool Win32ControlUnitMgr::connect()
 {
     connected_ = false;
+    screencap_.reset();
 
 #ifndef MAA_WIN32_COMPATIBLE
     // 设置 Per-Monitor DPI Aware V2，确保 GetClientRect/GetWindowRect 等 API 返回物理像素。
@@ -52,77 +56,14 @@ bool Win32ControlUnitMgr::connect()
             LogError << "hwnd_ is invalid";
             return false;
         }
-
-        // FramePool 和 PrintWindow 内置伪最小化支持，允许最小化窗口
-        bool supports_minimized =
-            screencap_method_ == MaaWin32ScreencapMethod_FramePool || screencap_method_ == MaaWin32ScreencapMethod_PrintWindow;
-        if (!supports_minimized && IsIconic(hwnd_)) {
-            LogError << "hwnd_ is minimized";
-            return false;
-        }
     }
     else {
         LogWarn << "hwnd_ is nullptr";
     }
 
-    switch (screencap_method_) {
-    case MaaWin32ScreencapMethod_GDI:
-        screencap_ = std::make_shared<GdiScreencap>(hwnd_);
-        break;
-    case MaaWin32ScreencapMethod_FramePool:
-        screencap_ = std::make_shared<FramePoolWithPseudoMinimizeScreencap>(hwnd_);
-        break;
-    case MaaWin32ScreencapMethod_DXGI_DesktopDup:
-        screencap_ = std::make_shared<DesktopDupScreencap>(hwnd_);
-        break;
-    case MaaWin32ScreencapMethod_DXGI_DesktopDup_Window:
-        screencap_ = std::make_shared<DesktopDupWindowScreencap>(hwnd_);
-        break;
-    case MaaWin32ScreencapMethod_PrintWindow:
-        screencap_ = std::make_shared<PrintWindowWithPseudoMinimizeScreencap>(hwnd_);
-        break;
-    case MaaWin32ScreencapMethod_ScreenDC:
-        screencap_ = std::make_shared<ScreenDCScreencap>(hwnd_);
-        break;
-
-    default:
-        LogError << "Unknown screencap method: " << static_cast<int>(screencap_method_);
-        break;
-    }
-
-    auto make_input = [&](MaaWin32InputMethod method) -> std::shared_ptr<InputBase> {
-        switch (method) {
-        case MaaWin32InputMethod_Seize:
-            return std::make_shared<SeizeInput>(hwnd_, false);
-        case MaaWin32InputMethod_SendMessage:
-            return std::make_shared<MessageInput>(hwnd_, MessageInput::Config { .mode = MessageInput::Mode::SendMessage });
-        case MaaWin32InputMethod_PostMessage:
-            return std::make_shared<MessageInput>(hwnd_, MessageInput::Config { .mode = MessageInput::Mode::PostMessage });
-        case MaaWin32InputMethod_LegacyEvent:
-            return std::make_shared<LegacyEventInput>(hwnd_, true);
-        case MaaWin32InputMethod_PostThreadMessage:
-            return std::make_shared<PostThreadMessageInput>(hwnd_);
-        case MaaWin32InputMethod_SendMessageWithCursorPos:
-            return std::make_shared<MessageInput>(
-                hwnd_,
-                MessageInput::Config { .mode = MessageInput::Mode::SendMessage, .with_cursor_pos = true, .block_input = false });
-        case MaaWin32InputMethod_PostMessageWithCursorPos:
-            return std::make_shared<MessageInput>(
-                hwnd_,
-                MessageInput::Config { .mode = MessageInput::Mode::PostMessage, .with_cursor_pos = true, .block_input = false });
-        case MaaWin32InputMethod_SendMessageWithWindowPos:
-            return std::make_shared<MessageInput>(
-                hwnd_,
-                MessageInput::Config { .mode = MessageInput::Mode::SendMessage, .with_window_pos = true, .block_input = false });
-        case MaaWin32InputMethod_PostMessageWithWindowPos:
-            return std::make_shared<MessageInput>(
-                hwnd_,
-                MessageInput::Config { .mode = MessageInput::Mode::PostMessage, .with_window_pos = true, .block_input = false });
-        default:
-            LogError << "Unknown input method: " << static_cast<int>(method);
-            return nullptr;
-        }
-    };
+    if (!init_screencap()) {
+        return false;
+    }
 
     if (mouse_method_ == keyboard_method_) {
         mouse_ = make_input(mouse_method_);
@@ -137,6 +78,132 @@ bool Win32ControlUnitMgr::connect()
     return true;
 }
 
+std::unordered_map<Win32ControlUnitMgr::ScreencapMethod, std::shared_ptr<ScreencapBase>> Win32ControlUnitMgr::build_screencap_units() const
+{
+    std::unordered_map<ScreencapMethod, std::shared_ptr<ScreencapBase>> units;
+
+    const auto add = [&](MaaWin32ScreencapMethod flag, ScreencapMethod method, auto factory) {
+        if (screencap_method_ & flag) {
+            units.emplace(method, factory());
+        }
+    };
+
+    add(MaaWin32ScreencapMethod_GDI, ScreencapMethod::GDI, [this] { return std::make_shared<GdiScreencap>(hwnd_); });
+    add(MaaWin32ScreencapMethod_FramePool, ScreencapMethod::FramePool, [this] {
+        return std::make_shared<FramePoolWithPseudoMinimizeScreencap>(hwnd_);
+    });
+    add(MaaWin32ScreencapMethod_DXGI_DesktopDup, ScreencapMethod::DXGI_DesktopDup, [this] {
+        return std::make_shared<DesktopDupScreencap>(hwnd_);
+    });
+    add(MaaWin32ScreencapMethod_DXGI_DesktopDup_Window, ScreencapMethod::DXGI_DesktopDup_Window, [this] {
+        return std::make_shared<DesktopDupWindowScreencap>(hwnd_);
+    });
+    add(MaaWin32ScreencapMethod_PrintWindow, ScreencapMethod::PrintWindow, [this] {
+        return std::make_shared<PrintWindowWithPseudoMinimizeScreencap>(hwnd_);
+    });
+    add(MaaWin32ScreencapMethod_ScreenDC, ScreencapMethod::ScreenDC, [this] { return std::make_shared<ScreenDCScreencap>(hwnd_); });
+
+    return units;
+}
+
+bool Win32ControlUnitMgr::init_screencap()
+{
+    if (screencap_method_ == MaaWin32ScreencapMethod_None) {
+        LogWarn << "No screencap method selected";
+        return true;
+    }
+
+    auto units = build_screencap_units();
+    if (units.empty()) {
+        LogError << "No available screencap method to test";
+        return false;
+    }
+
+    screencap_ = speed_test(units);
+    if (!screencap_) {
+        LogError << "failed to select screencap method";
+        return false;
+    }
+
+    return true;
+}
+
+std::shared_ptr<InputBase> Win32ControlUnitMgr::make_input(MaaWin32InputMethod method) const
+{
+    switch (method) {
+    case MaaWin32InputMethod_Seize:
+        return std::make_shared<SeizeInput>(hwnd_, false);
+    case MaaWin32InputMethod_SendMessage:
+        return std::make_shared<MessageInput>(hwnd_, MessageInput::Config { .mode = MessageInput::Mode::SendMessage });
+    case MaaWin32InputMethod_PostMessage:
+        return std::make_shared<MessageInput>(hwnd_, MessageInput::Config { .mode = MessageInput::Mode::PostMessage });
+    case MaaWin32InputMethod_LegacyEvent:
+        return std::make_shared<LegacyEventInput>(hwnd_, true);
+    case MaaWin32InputMethod_PostThreadMessage:
+        return std::make_shared<PostThreadMessageInput>(hwnd_);
+    case MaaWin32InputMethod_SendMessageWithCursorPos:
+        return std::make_shared<MessageInput>(
+            hwnd_,
+            MessageInput::Config { .mode = MessageInput::Mode::SendMessage, .with_cursor_pos = true, .block_input = false });
+    case MaaWin32InputMethod_PostMessageWithCursorPos:
+        return std::make_shared<MessageInput>(
+            hwnd_,
+            MessageInput::Config { .mode = MessageInput::Mode::PostMessage, .with_cursor_pos = true, .block_input = false });
+    case MaaWin32InputMethod_SendMessageWithWindowPos:
+        return std::make_shared<MessageInput>(
+            hwnd_,
+            MessageInput::Config { .mode = MessageInput::Mode::SendMessage, .with_window_pos = true, .block_input = false });
+    case MaaWin32InputMethod_PostMessageWithWindowPos:
+        return std::make_shared<MessageInput>(
+            hwnd_,
+            MessageInput::Config { .mode = MessageInput::Mode::PostMessage, .with_window_pos = true, .block_input = false });
+    default:
+        LogError << "Unknown input method: " << static_cast<int>(method);
+        return nullptr;
+    }
+}
+
+std::shared_ptr<ScreencapBase>
+    Win32ControlUnitMgr::speed_test(const std::unordered_map<ScreencapMethod, std::shared_ptr<ScreencapBase>>& units) const
+{
+    LogFunc;
+
+    ScreencapMethod fastest = ScreencapMethod::UnknownYet;
+    auto cost = std::chrono::milliseconds::max();
+
+    auto check = [&fastest, &cost](ScreencapMethod method, std::chrono::steady_clock::time_point start) {
+        auto duration = duration_since(start);
+        if (duration < cost) {
+            fastest = method;
+            cost = duration;
+        }
+        LogInfo << VAR(method) << VAR(duration);
+    };
+
+    for (auto& [method, unit] : units) {
+        LogInfo << "Warming up" << method;
+        if (!unit->screencap()) {
+            LogWarn << "failed to warm up" << method;
+        }
+
+        LogInfo << "Testing" << method;
+        auto now = std::chrono::steady_clock::now();
+        if (!unit->screencap()) {
+            LogWarn << "failed to test" << method;
+            continue;
+        }
+        check(method, now);
+    }
+
+    if (fastest == ScreencapMethod::UnknownYet) {
+        LogError << "cannot find any method to screencap!";
+        return nullptr;
+    }
+
+    LogInfo << "The fastest method is" << fastest << VAR(cost);
+    return units.at(fastest);
+}
+
 bool Win32ControlUnitMgr::connected() const
 {
     // 除了检查连接标志，还需要检查窗口是否仍然有效
diff --git a/source/MaaWin32ControlUnit/Manager/Win32ControlUnitMgr.h b/source/MaaWin32ControlUnit/Manager/Win32ControlUnitMgr.h
@@ -1,6 +1,8 @@
 #pragma once
 
 #include <filesystem>
+#include <ostream>
+#include <unordered_map>
 
 #include "Base/UnitBase.h"
 #include "ControlUnit/ControlUnitAPI.h"
@@ -52,6 +54,24 @@ class Win32ControlUnitMgr : public Win32ControlUnitAPI
 
     virtual json::object get_info() const override;
 
+private:
+    enum class ScreencapMethod
+    {
+        UnknownYet,
+        GDI,
+        FramePool,
+        DXGI_DesktopDup,
+        DXGI_DesktopDup_Window,
+        PrintWindow,
+        ScreenDC,
+    };
+
+    std::unordered_map<ScreencapMethod, std::shared_ptr<ScreencapBase>> build_screencap_units() const;
+    bool init_screencap();
+    std::shared_ptr<InputBase> make_input(MaaWin32InputMethod method) const;
+
+    std::shared_ptr<ScreencapBase> speed_test(const std::unordered_map<ScreencapMethod, std::shared_ptr<ScreencapBase>>& units) const;
+
 private:
     HWND hwnd_ = nullptr;
     MaaWin32ScreencapMethod screencap_method_ = MaaWin32ScreencapMethod_None;
diff --git a/source/binding/NodeJS/src/apis/constant.cpp b/source/binding/NodeJS/src/apis/constant.cpp
@@ -61,6 +61,9 @@ static maajs::ValueType load_win32_screencap_method(maajs::EnvType env)
     DEM(MaaWin32ScreencapMethod, DXGI_DesktopDup_Window);
     DEM(MaaWin32ScreencapMethod, PrintWindow);
     DEM(MaaWin32ScreencapMethod, ScreenDC);
+    DEM(MaaWin32ScreencapMethod, All);
+    DEM(MaaWin32ScreencapMethod, Foreground);
+    DEM(MaaWin32ScreencapMethod, Background);
 
     return obj;
 }
diff --git a/source/binding/NodeJS/src/apis/constant.d.ts b/source/binding/NodeJS/src/apis/constant.d.ts
@@ -59,12 +59,17 @@ declare global {
         >
 
         /**
-         * Win32 screencap method.
+         * Win32 screencap method flags.
          *
-         * No bitwise OR, select ONE method only.
+         * Use bitwise OR to set the methods you need.
+         * MaaFramework will test all provided methods and use the fastest available one.
          *
          * No default value. Client should choose one as default.
          *
+         * Predefined combinations:
+         * - Foreground: DXGI_DesktopDup_Window | ScreenDC
+         * - Background: FramePool | PrintWindow
+         *
          * Different applications use different rendering methods, there is no universal solution.
          *
          * | Method                  | Speed     | Compatibility | Require Admin | Background Support | Notes                            |
@@ -87,7 +92,10 @@ declare global {
             | 'DXGI_DesktopDup'
             | 'DXGI_DesktopDup_Window'
             | 'PrintWindow'
-            | 'ScreenDC',
+            | 'ScreenDC'
+            | 'All'
+            | 'Foreground'
+            | 'Background',
             ScreencapOrInputMethods
         >
 
diff --git a/source/binding/Python/maa/controller.py b/source/binding/Python/maa/controller.py
diff --git a/source/binding/Python/maa/define.py b/source/binding/Python/maa/define.py
diff --git a/source/modules/MaaFramework.cppm b/source/modules/MaaFramework.cppm

Original file line number	Diff line number	Diff line change
`@@ -61,6 +61,9 @@ static maajs::ValueType load_win32_screencap_method(maajs::EnvType env)`
`61`	`61`	`DEM(MaaWin32ScreencapMethod, DXGI_DesktopDup_Window);`
`62`	`62`	`DEM(MaaWin32ScreencapMethod, PrintWindow);`
`63`	`63`	`DEM(MaaWin32ScreencapMethod, ScreenDC);`
	`64`	`+ DEM(MaaWin32ScreencapMethod, All);`
	`65`	`+ DEM(MaaWin32ScreencapMethod, Foreground);`
	`66`	`+ DEM(MaaWin32ScreencapMethod, Background);`
`64`	`67`
`65`	`68`	`return obj;`
`66`	`69`	`}`
Original file line number	Diff line number	Diff line change
`@@ -59,12 +59,17 @@ declare global {`
`59`	`59`	`>`
`60`	`60`
`61`	`61`	`/**`
`62`		`- * Win32 screencap method.`
	`62`	`+ * Win32 screencap method flags.`
`63`	`63`	`*`
`64`		`- * No bitwise OR, select ONE method only.`
	`64`	`+ * Use bitwise OR to set the methods you need.`
	`65`	`+ * MaaFramework will test all provided methods and use the fastest available one.`
`65`	`66`	`*`
`66`	`67`	`* No default value. Client should choose one as default.`
`67`	`68`	`*`
	`69`	`+ * Predefined combinations:`
	`70`	`+ * - Foreground: DXGI_DesktopDup_Window \| ScreenDC`
	`71`	`+ * - Background: FramePool \| PrintWindow`
	`72`	`+ *`
`68`	`73`	`* Different applications use different rendering methods, there is no universal solution.`
`69`	`74`	`*`
`70`	`75`	`* \| Method \| Speed \| Compatibility \| Require Admin \| Background Support \| Notes \|`
`@@ -87,7 +92,10 @@ declare global {`
`87`	`92`	`\| 'DXGI_DesktopDup'`
`88`	`93`	`\| 'DXGI_DesktopDup_Window'`
`89`	`94`	`\| 'PrintWindow'`
`90`		`- \| 'ScreenDC',`
	`95`	`+ \| 'ScreenDC'`
	`96`	`+ \| 'All'`
	`97`	`+ \| 'Foreground'`
	`98`	`+ \| 'Background',`
`91`	`99`	`ScreencapOrInputMethods`
`92`	`100`	`>`
`93`	`101`