[Breaking change] feat: support Win32ScreencapMethods speed test

[moomiji]

Summary by Sourcery

引入基于标志（flag）的 Win32 截屏配置，并更新控制器和测试以使用新的多方法 API。

新特性：

• 添加 Win32ScreencapMethods 标志枚举，以便配置多种 Win32 截屏策略，并支持基于速度的自动选择。

增强：

• 更新 DesktopWindowInfo 和 Win32/游戏手柄控制器，使其使用 Win32ScreencapMethods 来替代之前的单一方法枚举，并为前台/后台场景引入新的默认配置。

文档：

• 在封装器/API 概览中记录新的 Win32ScreencapMethods 枚举，并替换旧的 Win32ScreencapMethod 名称。

测试：

• 调整现有的控制器和工具包单元测试，使其使用 Win32ScreencapMethods，并验证更新后的 API 表面。

Original summary in English

Summary by Sourcery

Introduce flag-based Win32 screencap configuration and update controllers and tests to use the new multi-method API.

New Features:

• Add Win32ScreencapMethods flags enum to allow configuring multiple Win32 screencap strategies and automatic speed-based selection.

Enhancements:

• Update DesktopWindowInfo and Win32/gamepad controllers to use Win32ScreencapMethods instead of the previous single-method enum, including new defaults for foreground/background scenarios.

Documentation:

• Document the new Win32ScreencapMethods enum in the wrapper/API overview, replacing the old Win32ScreencapMethod name.

Tests:

• Adjust existing controller and toolkit unit tests to use Win32ScreencapMethods and validate the updated API surface.

[sourcery-ai]

Hey - 我在这里给出一些整体性的反馈：

• Win32ScreencapMethods 上的 XML 注释写的是 “No default value. Client should choose one as default.”，但 DesktopWindowInfo 现在默认将 ScreencapMethods = Background；建议让文档与这一行为保持一致，或者从 DesktopWindowInfo 中移除这个默认值。
• 在 DesktopWindowInfo 中将默认截图方式从 DXGI_DesktopDup 改为 Background (FramePool | PrintWindow)，对于所有依赖默认值的调用方来说，是一次行为上的破坏性变更；你可能需要考虑提供一个明确的迁移路径，或者提供一个保留旧 DXGI_DesktopDup 默认行为的辅助方法/工厂，以便于升级。

给 AI 代理的提示词

Please address the comments from this code review:

## Overall Comments
- The XML summary on Win32ScreencapMethods says "No default value. Client should choose one as default." but DesktopWindowInfo now assigns ScreencapMethods = Background by default; consider aligning the documentation with this behavior or removing the default from DesktopWindowInfo.
- Changing the default screencap from DXGI_DesktopDup to Background (FramePool | PrintWindow) in DesktopWindowInfo is a breaking behavioral change for all callers relying on the default; you may want to consider an explicit migration path or helper/factory preserving the old DXGI_DesktopDup default to ease upgrading.

---

Sourcery 对开源项目是免费的 —— 如果你喜欢我们的代码审查，请考虑分享给更多人 ✨

• X
• Mastodon
• LinkedIn
• Facebook

_{帮我变得更有用！请在每条评论下点击 👍 或 👎，我会根据你的反馈改进后续的审查。}

Original comment in English

Hey - I've left some high level feedback:

• The XML summary on Win32ScreencapMethods says "No default value. Client should choose one as default." but DesktopWindowInfo now assigns ScreencapMethods = Background by default; consider aligning the documentation with this behavior or removing the default from DesktopWindowInfo.
• Changing the default screencap from DXGI_DesktopDup to Background (FramePool | PrintWindow) in DesktopWindowInfo is a breaking behavioral change for all callers relying on the default; you may want to consider an explicit migration path or helper/factory preserving the old DXGI_DesktopDup default to ease upgrading.

Prompt for AI Agents

Please address the comments from this code review:

## Overall Comments
- The XML summary on Win32ScreencapMethods says "No default value. Client should choose one as default." but DesktopWindowInfo now assigns ScreencapMethods = Background by default; consider aligning the documentation with this behavior or removing the default from DesktopWindowInfo.
- Changing the default screencap from DXGI_DesktopDup to Background (FramePool | PrintWindow) in DesktopWindowInfo is a breaking behavioral change for all callers relying on the default; you may want to consider an explicit migration path or helper/factory preserving the old DXGI_DesktopDup default to ease upgrading.

---

Sourcery is free for open source - if you like our reviews please consider sharing them ✨

• X
• Mastodon
• LinkedIn
• Facebook

_{Help me be more useful! Please click 👍 or 👎 on each comment and I'll use the feedback to improve your reviews.}

[Copilot]

Pull request overview

This PR introduces a flags-based Win32 screencap configuration (Win32ScreencapMethods) and migrates the Win32-related wrapper surface (window info, controllers, extensions, docs, and unit tests) from the old single-choice Win32ScreencapMethod to the new multi-method API so the native layer can speed-test and select the fastest available capture strategy.

Changes:

• Added Win32ScreencapMethods [Flags] enum (and removed Win32ScreencapMethod) to support multi-method configuration and predefined foreground/background combinations.
• Updated DesktopWindowInfo, Win32/gamepad controllers, and DesktopWindowInfoExtensions to accept/pass Win32ScreencapMethods.
• Updated documentation and unit tests to reflect the new API surface.

Reviewed changes

Copilot reviewed 9 out of 9 changed files in this pull request and generated 4 comments.

Show a summary per file

File	Description
src/MaaFramework.Binding/Infos/DesktopWindowInfo.cs	Switches window info screencap configuration to Win32ScreencapMethods with a new default preset.
src/MaaFramework.Binding/Enums/Controllers/Win32ScreencapMethods.cs	Introduces the new flags enum and documents method tradeoffs and presets.
src/MaaFramework.Binding/Enums/Controllers/Win32ScreencapMethod.cs	Removes the legacy single-method enum.
src/MaaFramework.Binding.UnitTests/Test_IMaaToolkit.cs	Updates toolkit/controller construction tests to use Win32ScreencapMethods.
src/MaaFramework.Binding.UnitTests/Test_IMaaController.cs	Updates controller instantiation tests to use Win32ScreencapMethods.
src/MaaFramework.Binding.Native/MaaController/MaaWin32Controller.cs	Updates controller constructor overload and native call cast to pass flags.
src/MaaFramework.Binding.Native/MaaController/MaaGamepadController.cs	Updates gamepad controller constructor overload and native call cast to pass flags.
src/MaaFramework.Binding.Native/Extensions/DesktopWindowInfoExtensions.cs	Updates extension method parameter types/cref and propagates Win32ScreencapMethods.
docs/articles/overview-of-wrapper-and-api.md	Renames wrapper enum in the API overview table to Win32ScreencapMethods.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.