VirtualDesktop 1.3.0__tar.gz → 1.3.1__tar.gz

{virtualdesktop-1.3.0 → virtualdesktop-1.3.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: VirtualDesktop
-Version: 1.3.0
+Version: 1.3.1
 Summary: Multi-window virtual-display workspaces on Windows: one pip install bootstraps the virtual display driver, hosts programs on a virtual or private desktop, keeps them off the physical screens, and hands out real window handles for automation and PrintWindow capture.
 Author: VirtualDesktop contributors
 License: MIT License
@@ -86,7 +86,7 @@ uv add VirtualDesktop             # uv（写入 pyproject.toml 并锁定）
 | 一句话 | 另开一个桌面，窗口与你的桌面完全隔离 | 多一块屏幕，窗口仍在你的桌面上、只是画在看不见的地方 |
 | 隔离强度 | **强**：独立窗口命名空间，外部进程看不到、碰不到 | **弱**：窗口是普通窗口，任何程序都能找到并操作它 |
 | 需要权限 | **零**：不需要驱动、不弹 UAC | 装一次驱动，弹**一次 UAC** |
-| 能截图吗 | **不能** | **能** |
+| 能截图吗 | **不能**（窗口截图、桌面截图都不行） | **能**（两种都行） |
 | 外部自动化库能用吗 | **不能**（要在桌面内跑代理） | **能**（pywinauto / UIA / pyautogui 直接用） |
 | 适合 | 多实例并行、强隔离、不要截图 | UI 自动化、截图 OCR、无人值守抓界面 |
 
@@ -177,6 +177,18 @@ with VirtualWorkspace("lab") as space, space.agent() as agent:
 `exec` 是逃生舱：里面的代码能 `import VirtualDesktop`、能用 `list_windows()`、`CaptureEngine`，
 也能用你自己装的任何库。代理本身只依赖 ctypes，不需要额外安装。
 
+### 私有桌面不能截图
+
+两种截图都不行，且原因不同：
+
+| 类型 | 结果 | 原因 |
+|---|---|---|
+| 程序窗口截图 | **不能** | 该桌面的窗口从不被系统合成，没有像素可读 |
+| 桌面截图 | **不能** | 拿不到该桌面的屏幕 DC（`BitBlt` 返回拒绝访问） |
+
+`agent.screenshot()` 会**明确报错**（`code="capture-needs-shared-workspace"`）而不是产出空白图。
+要读状态用 `agent.info()` / `agent.text()`；要像素请改用虚拟显示器。
+
 ## 能力边界
 
 私有桌面的窗口**不在交互桌面上**，所以按输入机制分，能做的事如下：
@@ -185,17 +197,18 @@ with VirtualWorkspace("lab") as space, space.agent() as agent:
 |---|---|---|
 | 找到窗口、读标题 / 类名 / 矩形 | 能 | 读窗口属性，跨桌面可用 |
 | 枚举子控件、读控件文字 | 能 | 同上 |
+| 用外部进程的 pywinauto 连上并读属性 | **能** | 拿得到句柄就能读 |
 | 点击控件（`BM_CLICK` 等窗口消息） | **能** | 消息直接投递给窗口，不需要指针 |
 | 送入字符（`WM_CHAR` 消息） | **能** | 同上 |
-| **截图** | **不能** | 桌面从不被系统合成，没有像素可读 |
+| **程序窗口截图** | **不能** | 桌面从不被系统合成，窗口没有像素 |
+| **桌面截图** | **不能** | 拿不到该桌面的屏幕 DC（`BitBlt` 返回拒绝访问） |
 | 移动真实鼠标来点击 | **不能** | 该桌面不是活动桌面，没有指针 |
 | 滚轮（真实滚轮事件） | **不能** | 同"移动真实鼠标" |
 | 发送真实键盘输入（`SendInput`） | **不能** | 键盘只发给活动桌面 |
 | `pywinauto` 的 `click_input()` / `type_keys()` | **不能** | 依赖真实输入与前台焦点 |
-| 用外部进程的 pywinauto 直接连上它 | **不能** | 跨桌面拿不到窗口 |
 
-要点：**能用消息驱动的都能用，需要真实输入设备的都不能用**。需要截图或需要真实鼠标/滚轮的应用，
-请改用下面的虚拟显示器方案。
+要点：**能用消息驱动的都能用，需要真实输入设备的都不能用，两种截图都不能用**。需要截图或需要
+真实鼠标/滚轮的应用，请改用下面的虚拟显示器方案。
 
 ---
 
@@ -288,7 +301,17 @@ VirtualWorkspace(VirtualWorkspace.SHARED, monitor="primary")           # 主屏
 
 ## 截图
 
-`capture()` 依次尝试多种后端直到拿到**有内容**的帧，默认顺序：
+要分清两种，它们走**完全不同的通路**，能力也不同：
+
+| 类型 | 拍什么 | 走哪条路 | 怎么调 |
+|---|---|---|---|
+| **程序窗口截图** | 某一个窗口自己的像素 | `PrintWindow(hwnd)` | `CaptureEngine.capture(hwnd)` / `space.capture(hwnd)` |
+| **桌面截图** | 整块屏幕（含其上所有窗口） | `ImageGrab` / `BitBlt` 屏幕 DC | `capture_all_screens()` / `capture_monitor()` / `space.capture_desktop()` |
+
+### 程序窗口截图
+
+按句柄拍，窗口在屏幕外也能拍，是抓单个程序界面最可靠的方式。`capture()` 依次尝试多种后端直到
+拿到**有内容**的帧，默认顺序：
 
 `printwindow`（`PW_RENDERFULLCONTENT`）→ `printwindow_plain` → `wm_print` → `bitblt`
 
@@ -303,6 +326,39 @@ frame = engine.capture(hwnd, require_content=True)
 print(frame.method, frame.size)
 ```
 
+```python
+with VirtualWorkspace(VirtualWorkspace.SHARED) as space:
+    entry = space.launch(["charmap.exe"])
+    space.capture(entry.hwnd, save_to="window.png")
+```
+
+### 桌面截图
+
+拍的是**屏幕**，不是某个窗口。`virtual_screen_rect()` 是整张虚拟桌面（含所有显示器，处理好负坐标），
+`capture_monitor()` 是单块显示器。在虚拟显示器模式下，`space.capture_desktop()` 等价于
+`capture_monitor(space.monitor)`。
+
+```python
+from VirtualDesktop import CaptureEngine
+from VirtualDesktop.desktop_capture import capture_all_screens, capture_monitor
+
+CaptureEngine().ensure_dpi_aware()      # 拍摄前必须做，见下方警告
+
+whole = capture_all_screens()           # 整张虚拟桌面
+whole.image.save("desktop.png")
+print(whole.rect, whole.size, whole.method)
+
+one = capture_monitor(device="\\\\.\\DISPLAY2")   # 只拍某一块屏
+```
+
+> **拍摄前先确保 DPI 感知。** 矩形由 `GetSystemMetrics` / `EnumDisplayMonitors` 计算，它们对
+> **不感知 DPI** 的进程返回的是**缩放后的逻辑值**；而像素抓取返回的是**物理像素**。两者不一致时
+> 会**静默裁掉**画面右下角（125% 缩放下 1920×1080 的屏只拿到 1536×864，少 384×216 像素，且不报错）。
+> 先调一次 `CaptureEngine().ensure_dpi_aware()` 即可，`VirtualWorkspace` 内部已自动处理。
+
+> **桌面截图只有虚拟显示器模式可用。** offscreen 模式下窗口被移到所有显示器**之外**，桌面截图按
+> 定义拍不到它们；而私有桌面根本没有可拍的屏幕 DC。
+
 ## 用自动化库控制窗口
 
 窗口是普通窗口，直接从你的进程用即可：
@@ -358,7 +414,8 @@ print(current_primary_size())                            # (1920, 1080)
 | 枚举子控件、读控件文字 | 能 | 能 |
 | 点击控件（窗口消息） | 能 | 能 |
 | 送入字符（窗口消息） | 能 | 能 |
-| **截图** | **能** | **能** |
+| **程序窗口截图** | **能** | **能** |
+| **桌面截图** | **能**（拍到窗口） | **不能**（窗口在所有显示器之外） |
 | 外部 pywinauto / UIA 直接连上 | 能 | 能 |
 | 移动真实鼠标来点击 | 能 | **不能**（窗口在屏幕之外） |
 | 滚轮 | 能 | **不能** |
@@ -410,7 +467,10 @@ VIRTUALDESKTOP_LOG_FILE=<path>
 | `SetThreadDesktop ... error 170` | 当前线程已有窗口，无法再绑定桌面 | 在创建窗口之前 `bind_thread()`，或用 `agent()` |
 | 安装后没出现新的虚拟屏 | 驱动已注册但显示器未启用 | 设备管理器启用；`report.requires_reboot` 为真时重启 |
 | 驱动下载失败或极慢 | github.com 不可达 | 设 `VIRTUALDESKTOP_GITHUB_MIRRORS`，或预置离线缓存 |
-| 截图是黑帧 | 应用为硬件加速 / 受保护内容 | 系统限制；换 `bitblt` 试试，或确认窗口有内容 |
+| 窗口截图是黑帧 | 应用为硬件加速 / 受保护内容 | 系统限制；换 `bitblt` 试试，或确认窗口有内容 |
+| 桌面截图少了右下角 | 进程不感知 DPI，矩形按逻辑坐标算 | 先调 `CaptureEngine().ensure_dpi_aware()` |
+| 桌面截图拍不到工作区窗口 | 用了 `offscreen`，窗口在所有显示器之外 | 改用 `hide_mode="virtual_screen"` |
+| `capture_desktop()` 报"workspace is not open" | offscreen 模式下没有绑定显示器 | 改用 `capture_all_screens()`，或用 `virtual_screen` |
 | 真实鼠标点击无效 | 窗口在屏幕之外，或拿不到前台焦点 | 用 `virtual_screen`，或改用消息驱动 |
 | 某程序在私有桌面上找不到窗口 | 控制台类（cmd）等窗口不参与常规枚举 | 换程序，或用 `agent.exec()` 在桌面内直接操作 |
 
@@ -420,8 +480,9 @@ VIRTUALDESKTOP_LOG_FILE=<path>
 
 ## 已知限制
 
-- **私有桌面不能截图**：它的窗口没有被系统合成，没有任何后端能读到像素；`agent.screenshot()`
-  会明确报错。
+- **私有桌面不能截图**：程序窗口截图和桌面截图都不行。窗口没有被系统合成、没有像素可读；
+  而该桌面的屏幕 DC 也拿不到（`BitBlt` 返回拒绝访问）。用 `agent.info()` / `agent.text()` 读状态，
+  需要像素请改用虚拟显示器。
 - **私有桌面不能用真实鼠标 / 滚轮 / 真实键盘**：那里没有活动指针和键盘焦点；消息驱动可用。
 - **窗口无法在私有桌面之间搬运**：Windows 不允许跨桌面移动窗口。
 - 部分应用（UWP、硬件叠加层、DRM 受保护内容）任何离屏方式都抓不到——系统限制。

{virtualdesktop-1.3.0 → virtualdesktop-1.3.1}/README.md

@@ -30,7 +30,7 @@ uv add VirtualDesktop             # uv（写入 pyproject.toml 并锁定）
 | 一句话 | 另开一个桌面，窗口与你的桌面完全隔离 | 多一块屏幕，窗口仍在你的桌面上、只是画在看不见的地方 |
 | 隔离强度 | **强**：独立窗口命名空间，外部进程看不到、碰不到 | **弱**：窗口是普通窗口，任何程序都能找到并操作它 |
 | 需要权限 | **零**：不需要驱动、不弹 UAC | 装一次驱动，弹**一次 UAC** |
-| 能截图吗 | **不能** | **能** |
+| 能截图吗 | **不能**（窗口截图、桌面截图都不行） | **能**（两种都行） |
 | 外部自动化库能用吗 | **不能**（要在桌面内跑代理） | **能**（pywinauto / UIA / pyautogui 直接用） |
 | 适合 | 多实例并行、强隔离、不要截图 | UI 自动化、截图 OCR、无人值守抓界面 |
 
@@ -121,6 +121,18 @@ with VirtualWorkspace("lab") as space, space.agent() as agent:
 `exec` 是逃生舱：里面的代码能 `import VirtualDesktop`、能用 `list_windows()`、`CaptureEngine`，
 也能用你自己装的任何库。代理本身只依赖 ctypes，不需要额外安装。
 
+### 私有桌面不能截图
+
+两种截图都不行，且原因不同：
+
+| 类型 | 结果 | 原因 |
+|---|---|---|
+| 程序窗口截图 | **不能** | 该桌面的窗口从不被系统合成，没有像素可读 |
+| 桌面截图 | **不能** | 拿不到该桌面的屏幕 DC（`BitBlt` 返回拒绝访问） |
+
+`agent.screenshot()` 会**明确报错**（`code="capture-needs-shared-workspace"`）而不是产出空白图。
+要读状态用 `agent.info()` / `agent.text()`；要像素请改用虚拟显示器。
+
 ## 能力边界
 
 私有桌面的窗口**不在交互桌面上**，所以按输入机制分，能做的事如下：
@@ -129,17 +141,18 @@ with VirtualWorkspace("lab") as space, space.agent() as agent:
 |---|---|---|
 | 找到窗口、读标题 / 类名 / 矩形 | 能 | 读窗口属性，跨桌面可用 |
 | 枚举子控件、读控件文字 | 能 | 同上 |
+| 用外部进程的 pywinauto 连上并读属性 | **能** | 拿得到句柄就能读 |
 | 点击控件（`BM_CLICK` 等窗口消息） | **能** | 消息直接投递给窗口，不需要指针 |
 | 送入字符（`WM_CHAR` 消息） | **能** | 同上 |
-| **截图** | **不能** | 桌面从不被系统合成，没有像素可读 |
+| **程序窗口截图** | **不能** | 桌面从不被系统合成，窗口没有像素 |
+| **桌面截图** | **不能** | 拿不到该桌面的屏幕 DC（`BitBlt` 返回拒绝访问） |
 | 移动真实鼠标来点击 | **不能** | 该桌面不是活动桌面，没有指针 |
 | 滚轮（真实滚轮事件） | **不能** | 同"移动真实鼠标" |
 | 发送真实键盘输入（`SendInput`） | **不能** | 键盘只发给活动桌面 |
 | `pywinauto` 的 `click_input()` / `type_keys()` | **不能** | 依赖真实输入与前台焦点 |
-| 用外部进程的 pywinauto 直接连上它 | **不能** | 跨桌面拿不到窗口 |
 
-要点：**能用消息驱动的都能用，需要真实输入设备的都不能用**。需要截图或需要真实鼠标/滚轮的应用，
-请改用下面的虚拟显示器方案。
+要点：**能用消息驱动的都能用，需要真实输入设备的都不能用，两种截图都不能用**。需要截图或需要
+真实鼠标/滚轮的应用，请改用下面的虚拟显示器方案。
 
 ---
 
@@ -232,7 +245,17 @@ VirtualWorkspace(VirtualWorkspace.SHARED, monitor="primary")           # 主屏
 
 ## 截图
 
-`capture()` 依次尝试多种后端直到拿到**有内容**的帧，默认顺序：
+要分清两种，它们走**完全不同的通路**，能力也不同：
+
+| 类型 | 拍什么 | 走哪条路 | 怎么调 |
+|---|---|---|---|
+| **程序窗口截图** | 某一个窗口自己的像素 | `PrintWindow(hwnd)` | `CaptureEngine.capture(hwnd)` / `space.capture(hwnd)` |
+| **桌面截图** | 整块屏幕（含其上所有窗口） | `ImageGrab` / `BitBlt` 屏幕 DC | `capture_all_screens()` / `capture_monitor()` / `space.capture_desktop()` |
+
+### 程序窗口截图
+
+按句柄拍，窗口在屏幕外也能拍，是抓单个程序界面最可靠的方式。`capture()` 依次尝试多种后端直到
+拿到**有内容**的帧，默认顺序：
 
 `printwindow`（`PW_RENDERFULLCONTENT`）→ `printwindow_plain` → `wm_print` → `bitblt`
 
@@ -247,6 +270,39 @@ frame = engine.capture(hwnd, require_content=True)
 print(frame.method, frame.size)
 ```
 
+```python
+with VirtualWorkspace(VirtualWorkspace.SHARED) as space:
+    entry = space.launch(["charmap.exe"])
+    space.capture(entry.hwnd, save_to="window.png")
+```
+
+### 桌面截图
+
+拍的是**屏幕**，不是某个窗口。`virtual_screen_rect()` 是整张虚拟桌面（含所有显示器，处理好负坐标），
+`capture_monitor()` 是单块显示器。在虚拟显示器模式下，`space.capture_desktop()` 等价于
+`capture_monitor(space.monitor)`。
+
+```python
+from VirtualDesktop import CaptureEngine
+from VirtualDesktop.desktop_capture import capture_all_screens, capture_monitor
+
+CaptureEngine().ensure_dpi_aware()      # 拍摄前必须做，见下方警告
+
+whole = capture_all_screens()           # 整张虚拟桌面
+whole.image.save("desktop.png")
+print(whole.rect, whole.size, whole.method)
+
+one = capture_monitor(device="\\\\.\\DISPLAY2")   # 只拍某一块屏
+```
+
+> **拍摄前先确保 DPI 感知。** 矩形由 `GetSystemMetrics` / `EnumDisplayMonitors` 计算，它们对
+> **不感知 DPI** 的进程返回的是**缩放后的逻辑值**；而像素抓取返回的是**物理像素**。两者不一致时
+> 会**静默裁掉**画面右下角（125% 缩放下 1920×1080 的屏只拿到 1536×864，少 384×216 像素，且不报错）。
+> 先调一次 `CaptureEngine().ensure_dpi_aware()` 即可，`VirtualWorkspace` 内部已自动处理。
+
+> **桌面截图只有虚拟显示器模式可用。** offscreen 模式下窗口被移到所有显示器**之外**，桌面截图按
+> 定义拍不到它们；而私有桌面根本没有可拍的屏幕 DC。
+
 ## 用自动化库控制窗口
 
 窗口是普通窗口，直接从你的进程用即可：
@@ -302,7 +358,8 @@ print(current_primary_size())                            # (1920, 1080)
 | 枚举子控件、读控件文字 | 能 | 能 |
 | 点击控件（窗口消息） | 能 | 能 |
 | 送入字符（窗口消息） | 能 | 能 |
-| **截图** | **能** | **能** |
+| **程序窗口截图** | **能** | **能** |
+| **桌面截图** | **能**（拍到窗口） | **不能**（窗口在所有显示器之外） |
 | 外部 pywinauto / UIA 直接连上 | 能 | 能 |
 | 移动真实鼠标来点击 | 能 | **不能**（窗口在屏幕之外） |
 | 滚轮 | 能 | **不能** |
@@ -354,7 +411,10 @@ VIRTUALDESKTOP_LOG_FILE=<path>
 | `SetThreadDesktop ... error 170` | 当前线程已有窗口，无法再绑定桌面 | 在创建窗口之前 `bind_thread()`，或用 `agent()` |
 | 安装后没出现新的虚拟屏 | 驱动已注册但显示器未启用 | 设备管理器启用；`report.requires_reboot` 为真时重启 |
 | 驱动下载失败或极慢 | github.com 不可达 | 设 `VIRTUALDESKTOP_GITHUB_MIRRORS`，或预置离线缓存 |
-| 截图是黑帧 | 应用为硬件加速 / 受保护内容 | 系统限制；换 `bitblt` 试试，或确认窗口有内容 |
+| 窗口截图是黑帧 | 应用为硬件加速 / 受保护内容 | 系统限制；换 `bitblt` 试试，或确认窗口有内容 |
+| 桌面截图少了右下角 | 进程不感知 DPI，矩形按逻辑坐标算 | 先调 `CaptureEngine().ensure_dpi_aware()` |
+| 桌面截图拍不到工作区窗口 | 用了 `offscreen`，窗口在所有显示器之外 | 改用 `hide_mode="virtual_screen"` |
+| `capture_desktop()` 报"workspace is not open" | offscreen 模式下没有绑定显示器 | 改用 `capture_all_screens()`，或用 `virtual_screen` |
 | 真实鼠标点击无效 | 窗口在屏幕之外，或拿不到前台焦点 | 用 `virtual_screen`，或改用消息驱动 |
 | 某程序在私有桌面上找不到窗口 | 控制台类（cmd）等窗口不参与常规枚举 | 换程序，或用 `agent.exec()` 在桌面内直接操作 |
 
@@ -364,8 +424,9 @@ VIRTUALDESKTOP_LOG_FILE=<path>
 
 ## 已知限制
 
-- **私有桌面不能截图**：它的窗口没有被系统合成，没有任何后端能读到像素；`agent.screenshot()`
-  会明确报错。
+- **私有桌面不能截图**：程序窗口截图和桌面截图都不行。窗口没有被系统合成、没有像素可读；
+  而该桌面的屏幕 DC 也拿不到（`BitBlt` 返回拒绝访问）。用 `agent.info()` / `agent.text()` 读状态，
+  需要像素请改用虚拟显示器。
 - **私有桌面不能用真实鼠标 / 滚轮 / 真实键盘**：那里没有活动指针和键盘焦点；消息驱动可用。
 - **窗口无法在私有桌面之间搬运**：Windows 不允许跨桌面移动窗口。
 - 部分应用（UWP、硬件叠加层、DRM 受保护内容）任何离屏方式都抓不到——系统限制。

{virtualdesktop-1.3.0 → virtualdesktop-1.3.1}/VirtualDesktop/__init__.py

@@ -63,7 +63,7 @@ from .workspace import SHARED, VirtualWorkspace, WorkspaceWindow
 from .agent import AgentProcess, AgentSession
 from .display_setup import configure_virtual_display, current_primary_dpi, current_primary_size
 
-__version__ = "1.3.0"
+__version__ = "1.3.1"
 
 __all__ = [
     "__version__",

{virtualdesktop-1.3.0 → virtualdesktop-1.3.1}/VirtualDesktop.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: VirtualDesktop
-Version: 1.3.0
+Version: 1.3.1
 Summary: Multi-window virtual-display workspaces on Windows: one pip install bootstraps the virtual display driver, hosts programs on a virtual or private desktop, keeps them off the physical screens, and hands out real window handles for automation and PrintWindow capture.
 Author: VirtualDesktop contributors
 License: MIT License
@@ -86,7 +86,7 @@ uv add VirtualDesktop             # uv（写入 pyproject.toml 并锁定）
 | 一句话 | 另开一个桌面，窗口与你的桌面完全隔离 | 多一块屏幕，窗口仍在你的桌面上、只是画在看不见的地方 |
 | 隔离强度 | **强**：独立窗口命名空间，外部进程看不到、碰不到 | **弱**：窗口是普通窗口，任何程序都能找到并操作它 |
 | 需要权限 | **零**：不需要驱动、不弹 UAC | 装一次驱动，弹**一次 UAC** |
-| 能截图吗 | **不能** | **能** |
+| 能截图吗 | **不能**（窗口截图、桌面截图都不行） | **能**（两种都行） |
 | 外部自动化库能用吗 | **不能**（要在桌面内跑代理） | **能**（pywinauto / UIA / pyautogui 直接用） |
 | 适合 | 多实例并行、强隔离、不要截图 | UI 自动化、截图 OCR、无人值守抓界面 |
 
@@ -177,6 +177,18 @@ with VirtualWorkspace("lab") as space, space.agent() as agent:
 `exec` 是逃生舱：里面的代码能 `import VirtualDesktop`、能用 `list_windows()`、`CaptureEngine`，
 也能用你自己装的任何库。代理本身只依赖 ctypes，不需要额外安装。
 
+### 私有桌面不能截图
+
+两种截图都不行，且原因不同：
+
+| 类型 | 结果 | 原因 |
+|---|---|---|
+| 程序窗口截图 | **不能** | 该桌面的窗口从不被系统合成，没有像素可读 |
+| 桌面截图 | **不能** | 拿不到该桌面的屏幕 DC（`BitBlt` 返回拒绝访问） |
+
+`agent.screenshot()` 会**明确报错**（`code="capture-needs-shared-workspace"`）而不是产出空白图。
+要读状态用 `agent.info()` / `agent.text()`；要像素请改用虚拟显示器。
+
 ## 能力边界
 
 私有桌面的窗口**不在交互桌面上**，所以按输入机制分，能做的事如下：
@@ -185,17 +197,18 @@ with VirtualWorkspace("lab") as space, space.agent() as agent:
 |---|---|---|
 | 找到窗口、读标题 / 类名 / 矩形 | 能 | 读窗口属性，跨桌面可用 |
 | 枚举子控件、读控件文字 | 能 | 同上 |
+| 用外部进程的 pywinauto 连上并读属性 | **能** | 拿得到句柄就能读 |
 | 点击控件（`BM_CLICK` 等窗口消息） | **能** | 消息直接投递给窗口，不需要指针 |
 | 送入字符（`WM_CHAR` 消息） | **能** | 同上 |
-| **截图** | **不能** | 桌面从不被系统合成，没有像素可读 |
+| **程序窗口截图** | **不能** | 桌面从不被系统合成，窗口没有像素 |
+| **桌面截图** | **不能** | 拿不到该桌面的屏幕 DC（`BitBlt` 返回拒绝访问） |
 | 移动真实鼠标来点击 | **不能** | 该桌面不是活动桌面，没有指针 |
 | 滚轮（真实滚轮事件） | **不能** | 同"移动真实鼠标" |
 | 发送真实键盘输入（`SendInput`） | **不能** | 键盘只发给活动桌面 |
 | `pywinauto` 的 `click_input()` / `type_keys()` | **不能** | 依赖真实输入与前台焦点 |
-| 用外部进程的 pywinauto 直接连上它 | **不能** | 跨桌面拿不到窗口 |
 
-要点：**能用消息驱动的都能用，需要真实输入设备的都不能用**。需要截图或需要真实鼠标/滚轮的应用，
-请改用下面的虚拟显示器方案。
+要点：**能用消息驱动的都能用，需要真实输入设备的都不能用，两种截图都不能用**。需要截图或需要
+真实鼠标/滚轮的应用，请改用下面的虚拟显示器方案。
 
 ---
 
@@ -288,7 +301,17 @@ VirtualWorkspace(VirtualWorkspace.SHARED, monitor="primary")           # 主屏
 
 ## 截图
 
-`capture()` 依次尝试多种后端直到拿到**有内容**的帧，默认顺序：
+要分清两种，它们走**完全不同的通路**，能力也不同：
+
+| 类型 | 拍什么 | 走哪条路 | 怎么调 |
+|---|---|---|---|
+| **程序窗口截图** | 某一个窗口自己的像素 | `PrintWindow(hwnd)` | `CaptureEngine.capture(hwnd)` / `space.capture(hwnd)` |
+| **桌面截图** | 整块屏幕（含其上所有窗口） | `ImageGrab` / `BitBlt` 屏幕 DC | `capture_all_screens()` / `capture_monitor()` / `space.capture_desktop()` |
+
+### 程序窗口截图
+
+按句柄拍，窗口在屏幕外也能拍，是抓单个程序界面最可靠的方式。`capture()` 依次尝试多种后端直到
+拿到**有内容**的帧，默认顺序：
 
 `printwindow`（`PW_RENDERFULLCONTENT`）→ `printwindow_plain` → `wm_print` → `bitblt`
 
@@ -303,6 +326,39 @@ frame = engine.capture(hwnd, require_content=True)
 print(frame.method, frame.size)
 ```
 
+```python
+with VirtualWorkspace(VirtualWorkspace.SHARED) as space:
+    entry = space.launch(["charmap.exe"])
+    space.capture(entry.hwnd, save_to="window.png")
+```
+
+### 桌面截图
+
+拍的是**屏幕**，不是某个窗口。`virtual_screen_rect()` 是整张虚拟桌面（含所有显示器，处理好负坐标），
+`capture_monitor()` 是单块显示器。在虚拟显示器模式下，`space.capture_desktop()` 等价于
+`capture_monitor(space.monitor)`。
+
+```python
+from VirtualDesktop import CaptureEngine
+from VirtualDesktop.desktop_capture import capture_all_screens, capture_monitor
+
+CaptureEngine().ensure_dpi_aware()      # 拍摄前必须做，见下方警告
+
+whole = capture_all_screens()           # 整张虚拟桌面
+whole.image.save("desktop.png")
+print(whole.rect, whole.size, whole.method)
+
+one = capture_monitor(device="\\\\.\\DISPLAY2")   # 只拍某一块屏
+```
+
+> **拍摄前先确保 DPI 感知。** 矩形由 `GetSystemMetrics` / `EnumDisplayMonitors` 计算，它们对
+> **不感知 DPI** 的进程返回的是**缩放后的逻辑值**；而像素抓取返回的是**物理像素**。两者不一致时
+> 会**静默裁掉**画面右下角（125% 缩放下 1920×1080 的屏只拿到 1536×864，少 384×216 像素，且不报错）。
+> 先调一次 `CaptureEngine().ensure_dpi_aware()` 即可，`VirtualWorkspace` 内部已自动处理。
+
+> **桌面截图只有虚拟显示器模式可用。** offscreen 模式下窗口被移到所有显示器**之外**，桌面截图按
+> 定义拍不到它们；而私有桌面根本没有可拍的屏幕 DC。
+
 ## 用自动化库控制窗口
 
 窗口是普通窗口，直接从你的进程用即可：
@@ -358,7 +414,8 @@ print(current_primary_size())                            # (1920, 1080)
 | 枚举子控件、读控件文字 | 能 | 能 |
 | 点击控件（窗口消息） | 能 | 能 |
 | 送入字符（窗口消息） | 能 | 能 |
-| **截图** | **能** | **能** |
+| **程序窗口截图** | **能** | **能** |
+| **桌面截图** | **能**（拍到窗口） | **不能**（窗口在所有显示器之外） |
 | 外部 pywinauto / UIA 直接连上 | 能 | 能 |
 | 移动真实鼠标来点击 | 能 | **不能**（窗口在屏幕之外） |
 | 滚轮 | 能 | **不能** |
@@ -410,7 +467,10 @@ VIRTUALDESKTOP_LOG_FILE=<path>
 | `SetThreadDesktop ... error 170` | 当前线程已有窗口，无法再绑定桌面 | 在创建窗口之前 `bind_thread()`，或用 `agent()` |
 | 安装后没出现新的虚拟屏 | 驱动已注册但显示器未启用 | 设备管理器启用；`report.requires_reboot` 为真时重启 |
 | 驱动下载失败或极慢 | github.com 不可达 | 设 `VIRTUALDESKTOP_GITHUB_MIRRORS`，或预置离线缓存 |
-| 截图是黑帧 | 应用为硬件加速 / 受保护内容 | 系统限制；换 `bitblt` 试试，或确认窗口有内容 |
+| 窗口截图是黑帧 | 应用为硬件加速 / 受保护内容 | 系统限制；换 `bitblt` 试试，或确认窗口有内容 |
+| 桌面截图少了右下角 | 进程不感知 DPI，矩形按逻辑坐标算 | 先调 `CaptureEngine().ensure_dpi_aware()` |
+| 桌面截图拍不到工作区窗口 | 用了 `offscreen`，窗口在所有显示器之外 | 改用 `hide_mode="virtual_screen"` |
+| `capture_desktop()` 报"workspace is not open" | offscreen 模式下没有绑定显示器 | 改用 `capture_all_screens()`，或用 `virtual_screen` |
 | 真实鼠标点击无效 | 窗口在屏幕之外，或拿不到前台焦点 | 用 `virtual_screen`，或改用消息驱动 |
 | 某程序在私有桌面上找不到窗口 | 控制台类（cmd）等窗口不参与常规枚举 | 换程序，或用 `agent.exec()` 在桌面内直接操作 |
 
@@ -420,8 +480,9 @@ VIRTUALDESKTOP_LOG_FILE=<path>
 
 ## 已知限制
 
-- **私有桌面不能截图**：它的窗口没有被系统合成，没有任何后端能读到像素；`agent.screenshot()`
-  会明确报错。
+- **私有桌面不能截图**：程序窗口截图和桌面截图都不行。窗口没有被系统合成、没有像素可读；
+  而该桌面的屏幕 DC 也拿不到（`BitBlt` 返回拒绝访问）。用 `agent.info()` / `agent.text()` 读状态，
+  需要像素请改用虚拟显示器。
 - **私有桌面不能用真实鼠标 / 滚轮 / 真实键盘**：那里没有活动指针和键盘焦点；消息驱动可用。
 - **窗口无法在私有桌面之间搬运**：Windows 不允许跨桌面移动窗口。
 - 部分应用（UWP、硬件叠加层、DRM 受保护内容）任何离屏方式都抓不到——系统限制。

{virtualdesktop-1.3.0 → virtualdesktop-1.3.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "VirtualDesktop"
-version = "1.3.0"
+version = "1.3.1"
 description = "Multi-window virtual-display workspaces on Windows: one pip install bootstraps the virtual display driver, hosts programs on a virtual or private desktop, keeps them off the physical screens, and hands out real window handles for automation and PrintWindow capture."
 readme = "README.md"
 requires-python = ">=3.9"