VirtualDesktop 1.0.1__py3-none-any.whl

VirtualDesktop/config.py

@@ -0,0 +1,255 @@
+"""Configuration objects and environment-variable defaults.
+
+Two explicitly separated concerns, because they have different lifetimes:
+
+* :class:`DriverConfig` 鈥?machine-scoped, expensive, privileged (installing a driver).
+* :class:`SessionConfig`  鈥?per-session, cheap, unprivileged (mounting a window).
+
+Every field can be supplied in code *or* through an ``VIRTUALDESKTOP_*`` environment
+variable, which is what makes the library usable from scheduled tasks, CI jobs and
+container-like wrappers where editing code is not an option.
+"""
+
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass, field, replace
+from typing import Any, Dict, List, Optional, Sequence, Tuple
+
+from .errors import ConfigError
+from .manifest import Manifest, load_manifest
+from .window import HIDE_MODES
+
+__all__ = [
+    "DriverConfig",
+    "SessionConfig",
+    "env",
+    "env_bool",
+    "env_float",
+    "env_int",
+    "env_list",
+    "DRIVER_POLICIES",
+]
+
+DRIVER_POLICIES = ("auto", "never", "always")
+_TRUTHY = {"1", "true", "yes", "on", "y", "t"}
+_FALSY = {"0", "false", "no", "off", "n", "f"}
+
+
+def env(name: str, default: Optional[str] = None) -> Optional[str]:
+    value = os.environ.get(f"VIRTUALDESKTOP_{name}")
+    return default if value is None or value == "" else value
+
+
+def env_bool(name: str, default: bool = False) -> bool:
+    value = env(name)
+    if value is None:
+        return default
+    lowered = value.strip().lower()
+    if lowered in _TRUTHY:
+        return True
+    if lowered in _FALSY:
+        return False
+    raise ConfigError(
+        f"VIRTUALDESKTOP_{name}={value!r} is not a boolean", code="bad-env-value"
+    )
+
+
+def env_int(name: str, default: int) -> int:
+    value = env(name)
+    if value is None:
+        return default
+    try:
+        return int(value)
+    except ValueError:
+        raise ConfigError(
+            f"VIRTUALDESKTOP_{name}={value!r} is not an integer", code="bad-env-value"
+        ) from None
+
+
+def env_float(name: str, default: float) -> float:
+    value = env(name)
+    if value is None:
+        return default
+    try:
+        return float(value)
+    except ValueError:
+        raise ConfigError(
+            f"VIRTUALDESKTOP_{name}={value!r} is not a number", code="bad-env-value"
+        ) from None
+
+
+def env_list(name: str, default: Sequence[str] = ()) -> Tuple[str, ...]:
+    """Parse a comma-separated environment variable into a tuple of stripped items.
+
+    Empty items are dropped, so ``VIRTUALDESKTOP_MONITOR_TAGS="a, ,b"`` yields ``("a", "b")``
+    and an unset variable yields ``default``.  Note the value of the *variable* is split —
+    calling ``env(...).split`` would split the function object and raise ``AttributeError``.
+    """
+    value = env(name)
+    if value is None:
+        return tuple(default)
+    return tuple(item.strip() for item in value.split(",") if item.strip())
+
+
+#: Internal alias kept short for the dataclass field factories.
+_split_env = env_list
+
+
+@dataclass
+class DriverConfig:
+    """Everything the bootstrap needs; machine-scoped and privileged."""
+
+    #: ``auto``   - install on demand during ``mount()`` (default, one UAC prompt once)
+    #: ``never``  - never install; raise a clear error when the device is missing
+    #: ``always`` - re-run the install flow on every ``ensure()`` (upgrade / repair)
+    policy: str = field(default_factory=lambda: env("DRIVER_POLICY", "auto") or "auto")
+    strategy: str = field(default_factory=lambda: env("DRIVER_STRATEGY", "auto") or "auto")
+    driver: Optional[str] = field(default_factory=lambda: env("DRIVER"))
+    cache_dir: Optional[str] = field(default_factory=lambda: env("CACHE_DIR"))
+    manifest_path: Optional[str] = field(default_factory=lambda: env("MANIFEST"))
+    signature_policy: str = field(
+        default_factory=lambda: env("SIGNATURE_POLICY", "warn") or "warn"
+    )
+    allow_scoop: bool = field(default_factory=lambda: env_bool("ALLOW_SCOOP", False))
+    install_timeout: float = field(default_factory=lambda: env_float("INSTALL_TIMEOUT", 600.0))
+    download_timeout: float = field(default_factory=lambda: env_float("DOWNLOAD_TIMEOUT", 300.0))
+    #: Extra substrings that identify the virtual monitor (forks/custom EDIDs).
+    monitor_tags: Tuple[str, ...] = field(
+        default_factory=lambda: _split_env("MONITOR_TAGS")
+    )
+    #: Optional path to a custom ``vdd_settings.xml`` copied next to the INF.
+    settings_file: Optional[str] = field(default_factory=lambda: env("DRIVER_SETTINGS"))
+
+    def __post_init__(self) -> None:
+        if self.policy not in DRIVER_POLICIES:
+            raise ConfigError(
+                f"driver policy {self.policy!r} must be one of {', '.join(DRIVER_POLICIES)}",
+                code="bad-driver-policy",
+            )
+        self.monitor_tags = tuple(self.monitor_tags)
+
+    def manifest(self) -> Manifest:
+        return load_manifest(self.manifest_path)
+
+    def installer(self, **overrides: Any):
+        """Build a :class:`~VirtualDesktop.driver.DriverInstaller` from this config."""
+        from .driver import DriverInstaller
+
+        kwargs: Dict[str, Any] = {
+            "manifest": self.manifest(),
+            "cache_dir": self.cache_dir,
+            "driver": self.driver,
+            "strategy": self.strategy,
+            "signature_policy": self.signature_policy,
+            "allow_scoop": self.allow_scoop,
+            "install_timeout": self.install_timeout,
+            "download_timeout": self.download_timeout,
+            "monitor_tags": self.monitor_tags,
+        }
+        kwargs.update(overrides)
+        return DriverInstaller(**kwargs)
+
+
+@dataclass
+class SessionConfig:
+    """Per-session behaviour: which monitor, which window, how to capture."""
+
+    #: ``auto`` | ``virtual`` | ``primary`` | ``DISPLAY2`` | ``\\\\.\\DISPLAY2`` | ``1``
+    monitor: str = field(default_factory=lambda: env("MONITOR", "auto") or "auto")
+    #: ``auto`` (marker match) | ``virtual`` | ``primary`` | explicit monitor name.
+    monitor_markers: Tuple[str, ...] = field(
+        default_factory=lambda: env_list("MONITOR_MARKERS", ("MttVDD", "IDD", "Virtual"))
+    )
+    #: Window selection.
+    target_window_title: Optional[str] = None
+    window_class: Optional[str] = field(default_factory=lambda: env("WINDOW_CLASS"))
+    process_name: Optional[str] = field(default_factory=lambda: env("WINDOW_PROCESS"))
+    window_pid: Optional[int] = None
+    title_mode: str = field(default_factory=lambda: env("TITLE_MODE", "auto") or "auto")
+    match_case: bool = field(default_factory=lambda: env_bool("MATCH_CASE", False))
+    window_timeout: float = field(default_factory=lambda: env_float("WINDOW_TIMEOUT", 10.0))
+    #: Hide taskbar button + Alt+Tab entry while mounted.
+    hide_taskbar_trace: bool = field(default_factory=lambda: env_bool("HIDE_TASKBAR_TRACE", True))
+    #: Bind the calling thread to ``WinSta0\Default`` before doing anything else.
+    bind_desktop: bool = field(default_factory=lambda: env_bool("BIND_DESKTOP", True))
+    #: How the window is hidden:
+    #: ``virtual_screen`` (default) - move it onto the virtual display;
+    #: ``offscreen``                - park it outside every monitor (no driver needed);
+    #: ``auto``                     - try ``virtual_screen``, fall back to ``offscreen``.
+    hide_mode: str = field(default_factory=lambda: (env("HIDE_MODE", "virtual_screen") or "virtual_screen").strip().lower())
+    #: Padding (pixels) applied inside the virtual monitor rect.
+    padding: int = field(default_factory=lambda: env_int("PADDING", 0))
+    #: Move the window without resizing it.  Safer for custom-rendered apps: WeChat's
+    #: login window ignores a resize and snaps back to the physical panel's size.
+    keep_window_size: bool = field(default_factory=lambda: env_bool("KEEP_WINDOW_SIZE", False))
+    #: Capture defaults.
+    capture_client_only: bool = field(default_factory=lambda: env_bool("CAPTURE_CLIENT_ONLY", True))
+    capture_methods: Optional[Tuple[str, ...]] = field(
+        default_factory=lambda: env_list("CAPTURE_METHODS") or None
+    )
+    capture_validate: bool = field(default_factory=lambda: env_bool("CAPTURE_VALIDATE", True))
+    capture_variance_threshold: float = field(
+        default_factory=lambda: env_float("CAPTURE_VARIANCE", 0.05)
+    )
+    capture_dominant_threshold: float = field(
+        default_factory=lambda: env_float("CAPTURE_DOMINANT", 0.999)
+    )
+    #: Restore the window automatically when the context manager exits.
+    restore_on_exit: bool = field(default_factory=lambda: env_bool("RESTORE_ON_EXIT", True))
+
+    def __post_init__(self) -> None:
+        valid = ("auto", "virtual", "primary", "any")
+        lowered = (self.monitor or "auto").strip().lower()
+        if lowered not in valid and not (
+            lowered.isdigit() or lowered.startswith("\\\\.\\") or lowered.startswith("display")
+        ):
+            raise ConfigError(
+                f"monitor selector {self.monitor!r} is not understood",
+                code="bad-monitor-selector",
+                hint="Use auto, virtual, primary, a DISPLAY name, or a 1-based index.",
+            )
+        if (self.hide_mode or "virtual_screen").strip().lower() not in HIDE_MODES:
+            raise ConfigError(
+                f"hide_mode {self.hide_mode!r} is not one of {', '.join(HIDE_MODES)}",
+                code="bad-hide-mode",
+                hint="virtual_screen = move onto the virtual display, offscreen = park outside "
+                "every monitor, auto = try the first then fall back.",
+            )
+        if self.title_mode not in ("auto", "exact", "substring", "regex"):
+            raise ConfigError(
+                f"title_mode {self.title_mode!r} must be auto, exact, substring or regex",
+                code="bad-title-mode",
+            )
+        if self.capture_methods is not None:
+            self.capture_methods = tuple(self.capture_methods)
+
+    def with_title(self, title: Optional[str]) -> "SessionConfig":
+        return replace(self, target_window_title=title)
+
+
+def capture_engine_from(config: SessionConfig, **overrides: Any):
+    """Build a :class:`~VirtualDesktop.capture.CaptureEngine` from a session config."""
+    from .capture import CaptureEngine
+
+    kwargs: Dict[str, Any] = {
+        "client_only": config.capture_client_only,
+        "validate": config.capture_validate,
+        "variance_threshold": config.capture_variance_threshold,
+        "dominant_threshold": config.capture_dominant_threshold,
+    }
+    if config.capture_methods:
+        kwargs["methods"] = config.capture_methods
+    kwargs.update(overrides)
+    return CaptureEngine(**kwargs)
+
+
+def mounter_from(config: SessionConfig, **overrides: Any):
+    from .window import WindowMounter
+
+    kwargs: Dict[str, Any] = {
+        "hide_taskbar_trace": config.hide_taskbar_trace,
+        "keep_size": config.keep_window_size,
+    }
+    kwargs.update(overrides)
+    return WindowMounter(**kwargs)

VirtualDesktop/desktop.py

@@ -0,0 +1,231 @@
+"""Desktop binding (:func:`ensure_default_desktop`).
+
+Windows gives every process a *window station* (``WinSta0`` for interactive sessions) and
+a *desktop* inside it (``Default``, ``Winlogon``, ``Screensaver``).  Windows live on a
+desktop, and a process can only see/enumerate windows that live on **its own** desktop.
+
+Processes started interactively normally inherit ``WinSta0\\Default`` already, so this
+module is a *guard*, not a requirement.  It matters when the library runs under Task
+Scheduler, a service wrapper, or a custom launcher: there, the thread may end up on
+``WinSta0\\Default`` only by luck.
+
+The call is best-effort by design.  ``SetThreadDesktop`` fails with
+``ERROR_BUSY`` (170) when the calling thread has already created windows or installed
+hooks — a condition that is *not* recoverable in-place and must never abort a session,
+because being unable to re-bind usually means we are already where we want to be.
+"""
+
+from __future__ import annotations
+
+import ctypes
+from ctypes import wintypes
+from dataclasses import dataclass
+from typing import Optional
+
+from ._log import get_logger
+from ._winapi import IS_WINDOWS, require_windows
+from .errors import DesktopBindError
+
+log = get_logger("desktop")
+
+__all__ = ["DesktopBinding", "ensure_default_desktop", "current_desktop_name"]
+
+if IS_WINDOWS:  # pragma: no branch
+    user32 = ctypes.WinDLL("user32", use_last_error=True)
+else:  # pragma: no cover
+    user32 = None
+
+DESKTOP_READOBJECTS = 0x0001
+DESKTOP_CREATEWINDOW = 0x0002
+DESKTOP_ENUMERATE = 0x0040
+DESKTOP_WRITEOBJECTS = 0x0080
+DESKTOP_SWITCHDESKTOP = 0x0100
+DESKTOP_READ_CONTROL = 0x00020000
+_GENERIC_DESKTOP_RIGHTS = (
+    DESKTOP_READOBJECTS
+    | DESKTOP_CREATEWINDOW
+    | DESKTOP_ENUMERATE
+    | DESKTOP_WRITEOBJECTS
+    | DESKTOP_SWITCHDESKTOP
+    | DESKTOP_READ_CONTROL
+)
+_ERROR_BUSY = 170
+_ERROR_ACCESS_DENIED = 5
+_ERROR_INVALID_HANDLE = 6
+_ERROR_INSUFFICIENT_BUFFER = 122
+
+
+@dataclass
+class DesktopBinding:
+    """Outcome of :func:`ensure_default_desktop`."""
+
+    bound: bool = False
+    already_on_default: bool = False
+    desktop_name: str = ""
+    skipped_reason: str = ""
+    handle: int = 0
+    error_code: int = 0
+
+    def to_dict(self) -> dict:
+        return {
+            "bound": self.bound,
+            "already_on_default": self.already_on_default,
+            "desktop_name": self.desktop_name,
+            "skipped_reason": self.skipped_reason,
+            "handle": self.handle,
+            "error_code": self.error_code,
+        }
+
+
+if IS_WINDOWS:  # pragma: no branch
+    user32.OpenInputDesktop.argtypes = [wintypes.DWORD, wintypes.BOOL, wintypes.DWORD]
+    user32.OpenInputDesktop.restype = wintypes.HANDLE
+    user32.GetThreadDesktop.argtypes = [wintypes.DWORD]
+    user32.GetThreadDesktop.restype = wintypes.HANDLE
+    user32.SetThreadDesktop.argtypes = [wintypes.HANDLE]
+    user32.SetThreadDesktop.restype = wintypes.BOOL
+    user32.CloseDesktop.argtypes = [wintypes.HANDLE]
+    user32.CloseDesktop.restype = wintypes.BOOL
+    user32.GetUserObjectInformationW.argtypes = [
+        wintypes.HANDLE,
+        ctypes.c_int,
+        ctypes.c_void_p,
+        wintypes.DWORD,
+        ctypes.POINTER(wintypes.DWORD),
+    ]
+    user32.GetUserObjectInformationW.restype = wintypes.BOOL
+
+_UOI_NAME = 2
+
+
+def _desktop_name(handle: int) -> str:
+    """Query ``UOI_NAME``. Two-step sizing is mandatory here.
+
+    Passing ``NULL`` for the buffer does **not** return the required size for
+    ``GetUserObjectInformation`` (it fails with ``ERROR_INSUFFICIENT_BUFFER`` and leaves
+    the size variable untouched), so a single oversized call with a retry is used instead.
+    """
+    if not IS_WINDOWS or not handle:
+        return ""
+    for capacity in (64, 512):
+        needed = wintypes.DWORD()
+        buffer = ctypes.create_unicode_buffer(capacity)
+        ok = user32.GetUserObjectInformationW(
+            handle,
+            _UOI_NAME,
+            ctypes.cast(buffer, ctypes.c_void_p),
+            capacity * ctypes.sizeof(ctypes.c_wchar),
+            ctypes.byref(needed),
+        )
+        if ok:
+            return buffer.value
+        if ctypes.get_last_error() != _ERROR_INSUFFICIENT_BUFFER:
+            return ""
+    return ""
+
+
+def current_desktop_name() -> str:
+    """Name of the desktop the calling thread is attached to (``""`` when unknown)."""
+    if not IS_WINDOWS:
+        return ""
+    handle = user32.GetThreadDesktop(_current_thread_id())
+    if not handle:
+        return ""
+    return _desktop_name(handle)
+
+
+def _current_thread_id() -> int:
+    kernel32 = ctypes.WinDLL("kernel32", use_last_error=True)
+    return int(kernel32.GetCurrentThreadId())
+
+
+def ensure_default_desktop(
+    *,
+    name: str = "Default",
+    strict: bool = False,
+    close_handle_on_exit: bool = False,
+) -> DesktopBinding:
+    """Make sure the calling thread is bound to ``WinSta0\\<name>``.
+
+    Returns a :class:`DesktopBinding` describing what happened.  With ``strict=True`` a
+    failure raises :class:`DesktopBindError` instead of being reported.
+    """
+    binding = DesktopBinding()
+    if not IS_WINDOWS:
+        binding.skipped_reason = "not-windows"
+        return binding
+
+    current = user32.GetThreadDesktop(_current_thread_id())
+    current_name = _desktop_name(current) if current else ""
+    binding.desktop_name = current_name or name
+    if current_name.lower() == name.lower():
+        binding.already_on_default = True
+        binding.bound = True
+        binding.skipped_reason = "already-bound"
+        log.debug("thread is already bound to the %r desktop", current_name)
+        return binding
+
+    handle = user32.OpenDesktopW(name, 0, False, _GENERIC_DESKTOP_RIGHTS)
+    if not handle:
+        # Fall back to the documented OpenInputDesktop path when OpenDesktop is refused.
+        handle = user32.OpenInputDesktop(0, False, _GENERIC_DESKTOP_RIGHTS)
+    if not handle:
+        error = ctypes.get_last_error()
+        binding.error_code = error
+        binding.skipped_reason = f"open-desktop-failed:{error}"
+        message = (
+            f"could not open the {name!r} desktop (Win32 error {error}); the invocation "
+            "desktop was left unchanged"
+        )
+        if strict:
+            raise DesktopBindError(
+                message,
+                details={"win32_error": error},
+                hint="Run the process in the interactive session (it usually already has access).",
+            )
+        log.warning(message)
+        return binding
+
+    binding.handle = int(handle)
+    if not user32.SetThreadDesktop(handle):
+        error = ctypes.get_last_error()
+        binding.error_code = error
+        binding.skipped_reason = f"set-thread-desktop-failed:{error}"
+        message = (
+            f"SetThreadDesktop({name!r}) failed with Win32 error {error}. "
+            "This is expected when the thread already owns windows or hooks."
+        )
+        if error == _ERROR_BUSY:
+            log.info("%s Continuing on the current desktop, which is the normal outcome.", message)
+            binding.bound = True
+            binding.skipped_reason = "thread-busy-continuing"
+        else:
+            if strict:
+                raise DesktopBindError(
+                    message,
+                    details={"win32_error": error},
+                    hint="Bind the desktop before creating any window or installing hooks.",
+                )
+            log.warning(message)
+        if not close_handle_on_exit:
+            user32.CloseDesktop(handle)
+            binding.handle = 0
+        return binding
+
+    binding.bound = True
+    binding.desktop_name = name
+    log.info("bound the calling thread to the %r desktop", name)
+    if not close_handle_on_exit:
+        user32.CloseDesktop(handle)
+        binding.handle = 0
+    return binding
+
+
+if IS_WINDOWS:  # pragma: no branch
+    user32.OpenDesktopW.argtypes = [
+        ctypes.c_wchar_p,
+        wintypes.DWORD,
+        wintypes.BOOL,
+        wintypes.DWORD,
+    ]
+    user32.OpenDesktopW.restype = wintypes.HANDLE

VirtualDesktop/desktop_capture.py

@@ -0,0 +1,159 @@
+"""Grab a whole monitor (by its device name) or the whole virtual desktop, in physical pixels.
+
+``PIL.ImageGrab.grab(bbox=...)`` is the reliable path for a *virtual* monitor: its rectangle can
+sit entirely outside the primary screen (the virtual display lives at x=1920 here), and
+``ImageGrab`` with ``all_screens=True`` covers the whole virtual desktop.  ``BitBlt`` from the
+desktop DC is used as a fallback and to capture an arbitrary rectangle.
+"""
+
+from __future__ import annotations
+
+import ctypes
+from ctypes import wintypes
+from dataclasses import dataclass
+from typing import Optional, Tuple
+
+from ._log import get_logger
+from ._winapi import IS_WINDOWS, MonitorInfo, enumerate_monitors, require_windows
+from .capture import _MemoryBitmap
+from .errors import CaptureError
+
+log = get_logger("desktop_capture")
+
+__all__ = ["DesktopCaptureResult", "capture_rect", "capture_monitor", "capture_all_screens"]
+
+if IS_WINDOWS:  # pragma: no branch
+    user32 = ctypes.WinDLL("user32", use_last_error=True)
+    gdi32 = ctypes.WinDLL("gdi32", use_last_error=True)
+else:  # pragma: no cover
+    user32 = gdi32 = None
+
+SRCCOPY = 0x00CC0020
+CAPTUREBLT = 0x40000000
+SM_XVIRTUALSCREEN, SM_YVIRTUALSCREEN, SM_CXVIRTUALSCREEN, SM_CYVIRTUALSCREEN = 76, 77, 78, 79
+
+if IS_WINDOWS:  # pragma: no branch
+    # Explicit prototypes: without them ctypes treats the DC handle returned by ``GetDC`` as a
+    # plain ``int`` and ``BitBlt`` raises "int too long to convert" on 64-bit builds (measured).
+    user32.GetDC.argtypes = [wintypes.HWND]
+    user32.GetDC.restype = wintypes.HDC
+    user32.ReleaseDC.argtypes = [wintypes.HWND, wintypes.HDC]
+    user32.ReleaseDC.restype = ctypes.c_int
+    user32.GetSystemMetrics.argtypes = [ctypes.c_int]
+    user32.GetSystemMetrics.restype = ctypes.c_int
+    gdi32.BitBlt.argtypes = [
+        wintypes.HDC, ctypes.c_int, ctypes.c_int, ctypes.c_int, ctypes.c_int,
+        wintypes.HDC, ctypes.c_int, ctypes.c_int, wintypes.DWORD,
+    ]
+    gdi32.BitBlt.restype = wintypes.BOOL
+
+
+@dataclass
+class DesktopCaptureResult:
+    image: object
+    rect: Tuple[int, int, int, int]
+    method: str
+
+    @property
+    def size(self) -> Tuple[int, int]:
+        return (self.image.width, self.image.height)  # type: ignore[attr-defined]
+
+    def save(self, path) -> str:
+        target = str(path)
+        self.image.save(target)  # type: ignore[attr-defined]
+        return target
+
+    def to_dict(self) -> dict:
+        return {"rect": list(self.rect), "size": list(self.size), "method": self.method}
+
+
+def virtual_desktop_rect() -> Tuple[int, int, int, int]:
+    """Bounding rectangle of the whole desktop, including negative-coordinate monitors.
+
+    Uses the library-wide canonical accessor so this rectangle always agrees with the monitor
+    rectangles used elsewhere.  ``GetSystemMetrics`` alone disagrees with
+    ``EnumDisplayMonitors`` by the monitor scale factor for a DPI-unaware caller on Windows 10
+    and 11 — and a rectangle that disagrees with the one used to *take* the shot produces a
+    silently offset crop.
+    """
+    require_windows("virtual_desktop_rect")
+    from ._winapi import virtual_screen_rect
+
+    return virtual_screen_rect()
+
+
+def _grab_rect_pil(rect: Tuple[int, int, int, int]):
+    from PIL import ImageGrab
+
+    left, top, right, bottom = rect
+    if right <= left or bottom <= top:
+        raise CaptureError(f"degenerate rectangle {rect}", code="degenerate-rect")
+    # ImageGrab works in physical pixels when the caller is DPI aware, which it must be.
+    return ImageGrab.grab(bbox=(left, top, right, bottom), all_screens=True).convert("RGB")
+
+
+def _grab_rect_bitblt(rect: Tuple[int, int, int, int]):
+    left, top, right, bottom = rect
+    width, height = right - left, bottom - top
+    if width <= 0 or height <= 0:
+        raise CaptureError(f"degenerate rectangle {rect}", code="degenerate-rect")
+    bitmap = _MemoryBitmap(width, height)
+    try:
+        screen = user32.GetDC(None)
+        if not screen:
+            raise CaptureError("GetDC(NULL) failed", code="getdc-failed")
+        try:
+            ok = gdi32.BitBlt(bitmap.dc, 0, 0, width, height, screen, left, top, SRCCOPY | CAPTUREBLT)
+        finally:
+            user32.ReleaseDC(None, screen)
+        if not ok:
+            raise CaptureError(
+                f"BitBlt of {rect} failed (Win32 error {ctypes.get_last_error()})", code="bitblt-failed"
+            )
+        return bitmap.to_image()
+    finally:
+        bitmap.close()
+
+
+def capture_rect(rect: Tuple[int, int, int, int], *, prefer: str = "pil") -> DesktopCaptureResult:
+    """Capture an arbitrary screen rectangle, with a working fallback for each method."""
+    require_windows("capture_rect")
+    errors = []
+    order = ("pil", "bitblt") if prefer == "pil" else ("bitblt", "pil")
+    for method in order:
+        try:
+            image = _grab_rect_pil(rect) if method == "pil" else _grab_rect_bitblt(rect)
+            log.debug("captured %s with %s -> %s", rect, method, image.size)
+            return DesktopCaptureResult(image=image, rect=tuple(rect), method=method)
+        except Exception as exc:  # noqa: BLE001 - try the next backend
+            errors.append(f"{method}: {exc}")
+            log.debug("capture backend %s failed for %s: %s", method, rect, exc)
+    raise CaptureError(
+        f"could not capture {rect}: {'; '.join(errors)}",
+        code="desktop-capture-failed",
+        hint="The rectangle may lie outside every monitor, or DPI awareness is not set.",
+    )
+
+
+def capture_monitor(
+    monitor: Optional[MonitorInfo] = None, *, device: Optional[str] = None, prefer: str = "pil"
+) -> DesktopCaptureResult:
+    """Capture one monitor (the virtual display by default) using its own rectangle."""
+    monitors = enumerate_monitors()
+    if monitor is None:
+        if device:
+            monitor = next((m for m in monitors if m.device.lower() == device.lower()), None)
+            if monitor is None:
+                raise CaptureError(f"no monitor named {device!r}", code="monitor-not-found")
+        else:
+            monitor = next((m for m in monitors if m.is_decidedly_virtual()), None) or (
+                monitors[0] if monitors else None
+            )
+    if monitor is None:
+        raise CaptureError("no monitors are attached", code="no-monitor")
+    return capture_rect(tuple(monitor.monitor), prefer=prefer)
+
+
+def capture_all_screens(*, prefer: str = "pil") -> DesktopCaptureResult:
+    """Capture the whole virtual desktop (every monitor, including the virtual one)."""
+    return capture_rect(virtual_desktop_rect(), prefer=prefer)