VirtualDesktop 1.0.1__py3-none-any.whl

VirtualDesktop/capture.py

@@ -0,0 +1,671 @@
+"""Capture engine: ``PrintWindow`` + ``PW_RENDERFULLCONTENT`` with real fallbacks.
+
+Offscreen capture is not one API call, it is a decision tree, because no single Win32
+method works on every window class:
+
+===============  =====================================================================
+method           behaviour
+===============  =====================================================================
+printwindow      ``PrintWindow(hwnd, dc, PW_RENDERFULLCONTENT)``. Best result for most
+                 Win32/WPF windows, *including completely offscreen ones* (the window
+                 paints itself into our DC). Fails or returns black for some
+                 DirectComposition/DirectX surfaces.
+printwindow_plain ``PW_RENDERFULLCONTENT`` was added in Windows 8.1; older systems or
+                 non-composited windows need the plain variant.
+wm_print         ``WM_PRINT``/``WM_PRINTCLIENT`` via ``SendMessageTimeout``. Slow, but it
+                 works on a few legacy controls that ignore ``PrintWindow``.
+bitblt           ``BitBlt(SRCCOPY)`` from the window DC. Content-accurate for GDI windows
+                 **only while the window is actually rendered**, so it is the last resort
+                 for offscreen mounts.
+===============  =====================================================================
+
+Every result is validated (see :func:`analyze_image`): a uniform, all-black or all-white
+frame is treated as a *failure*, not as a screenshot, and the engine moves on to the next
+method.  That check is what turns "sometimes I get a black PNG" into a deterministic
+fallback chain.
+"""
+
+from __future__ import annotations
+
+import ctypes
+import time
+from ctypes import wintypes
+from dataclasses import dataclass, field
+from typing import Callable, Dict, Iterable, List, Optional, Sequence, Tuple
+
+from ._log import get_logger
+from ._winapi import (
+    IS_WINDOWS,
+    dpi_awareness_scope,
+    is_owned_window,
+    require_windows,
+)
+from .errors import CaptureError
+
+log = get_logger("capture")
+
+__all__ = [
+    "DEFAULT_METHODS",
+    "Frame",
+    "ImageAnalysis",
+    "analyze_image",
+    "CaptureEngine",
+]
+
+DEFAULT_METHODS: Tuple[str, ...] = ("printwindow", "printwindow_plain", "wm_print", "bitblt")
+
+if IS_WINDOWS:  # pragma: no branch
+    user32 = ctypes.WinDLL("user32", use_last_error=True)
+    gdi32 = ctypes.WinDLL("gdi32", use_last_error=True)
+    try:
+        dwmapi = ctypes.WinDLL("dwmapi", use_last_error=True)
+    except OSError:  # pragma: no cover
+        dwmapi = None
+else:  # pragma: no cover
+    user32 = gdi32 = dwmapi = None
+
+PW_CLIENTONLY = 0x00000001
+PW_RENDERFULLCONTENT = 0x00000002
+BI_RGB = 0
+DIB_RGB_COLORS = 0
+SRCCOPY = 0x00CC0020
+CAPTUREBLT = 0x40000000
+WM_PRINT = 0x0317
+WM_PRINTCLIENT = 0x0318
+PRF_CLIENT = 0x00000004
+PRF_CHILDREN = 0x00000010
+PRF_ERASEBKGND = 0x00000008
+PRF_NONCLIENT = 0x00000002
+SMTO_ABORTIFHUNG = 0x0002
+_GA_PARENT = 1
+
+
+class _RECT(ctypes.Structure):
+    _fields_ = [
+        ("left", wintypes.LONG),
+        ("top", wintypes.LONG),
+        ("right", wintypes.LONG),
+        ("bottom", wintypes.LONG),
+    ]
+
+
+class _POINT(ctypes.Structure):
+    _fields_ = [("x", wintypes.LONG), ("y", wintypes.LONG)]
+
+
+class _BITMAPINFOHEADER(ctypes.Structure):
+    _fields_ = [
+        ("biSize", wintypes.DWORD),
+        ("biWidth", wintypes.LONG),
+        ("biHeight", wintypes.LONG),
+        ("biPlanes", wintypes.WORD),
+        ("biBitCount", wintypes.WORD),
+        ("biCompression", wintypes.DWORD),
+        ("biSizeImage", wintypes.DWORD),
+        ("biXPelsPerMeter", wintypes.LONG),
+        ("biYPelsPerMeter", wintypes.LONG),
+        ("biClrUsed", wintypes.DWORD),
+        ("biClrImportant", wintypes.DWORD),
+    ]
+
+
+if IS_WINDOWS:  # pragma: no branch
+    user32.PrintWindow.argtypes = [wintypes.HWND, wintypes.HDC, wintypes.UINT]
+    user32.PrintWindow.restype = wintypes.BOOL
+    user32.GetWindowDC.argtypes = [wintypes.HWND]
+    user32.GetWindowDC.restype = wintypes.HDC
+    user32.GetDC.argtypes = [wintypes.HWND]
+    user32.GetDC.restype = wintypes.HDC
+    user32.ReleaseDC.argtypes = [wintypes.HWND, wintypes.HDC]
+    user32.ReleaseDC.restype = ctypes.c_int
+    user32.GetClientRect.argtypes = [wintypes.HWND, ctypes.POINTER(_RECT)]
+    user32.GetClientRect.restype = wintypes.BOOL
+    user32.GetWindowRect.argtypes = [wintypes.HWND, ctypes.POINTER(_RECT)]
+    user32.GetWindowRect.restype = wintypes.BOOL
+    user32.ClientToScreen.argtypes = [wintypes.HWND, ctypes.POINTER(_POINT)]
+    user32.ClientToScreen.restype = wintypes.BOOL
+    user32.IsWindow.argtypes = [wintypes.HWND]
+    user32.IsWindow.restype = wintypes.BOOL
+    user32.IsWindowVisible.argtypes = [wintypes.HWND]
+    user32.IsWindowVisible.restype = wintypes.BOOL
+    user32.IsIconic.argtypes = [wintypes.HWND]
+    user32.IsIconic.restype = wintypes.BOOL
+    user32.SendMessageTimeoutW.argtypes = [
+        wintypes.HWND,
+        wintypes.UINT,
+        wintypes.WPARAM,
+        wintypes.LPARAM,
+        wintypes.UINT,
+        wintypes.UINT,
+        ctypes.POINTER(ctypes.c_void_p),
+    ]
+    user32.SendMessageTimeoutW.restype = wintypes.LPARAM
+    gdi32.CreateCompatibleDC.argtypes = [wintypes.HDC]
+    gdi32.CreateCompatibleDC.restype = wintypes.HDC
+    gdi32.CreateCompatibleBitmap.argtypes = [wintypes.HDC, ctypes.c_int, ctypes.c_int]
+    gdi32.CreateCompatibleBitmap.restype = wintypes.HBITMAP
+    gdi32.CreateDIBSection.argtypes = [
+        wintypes.HDC,
+        ctypes.POINTER(_BITMAPINFOHEADER),
+        wintypes.UINT,
+        ctypes.POINTER(ctypes.c_void_p),
+        wintypes.HANDLE,
+        wintypes.DWORD,
+    ]
+    gdi32.CreateDIBSection.restype = wintypes.HBITMAP
+    gdi32.SelectObject.argtypes = [wintypes.HDC, wintypes.HGDIOBJ]
+    gdi32.SelectObject.restype = wintypes.HGDIOBJ
+    gdi32.DeleteObject.argtypes = [wintypes.HGDIOBJ]
+    gdi32.DeleteObject.restype = wintypes.BOOL
+    gdi32.DeleteDC.argtypes = [wintypes.HDC]
+    gdi32.DeleteDC.restype = wintypes.BOOL
+    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
+    gdi32.GetDIBits.argtypes = [
+        wintypes.HDC,
+        wintypes.HBITMAP,
+        wintypes.UINT,
+        wintypes.UINT,
+        ctypes.c_void_p,
+        ctypes.POINTER(_BITMAPINFOHEADER),
+        wintypes.UINT,
+    ]
+    gdi32.GetDIBits.restype = ctypes.c_int
+
+
+@dataclass
+class ImageAnalysis:
+    """Cheap statistical validation of a captured frame."""
+
+    width: int = 0
+    height: int = 0
+    variance: float = 0.0
+    mean: float = 0.0
+    max_value: int = 0
+    dominant_ratio: float = 0.0
+    uniform: bool = False
+    blank: bool = False
+    reason: str = ""
+
+    @property
+    def usable(self) -> bool:
+        return not self.blank
+
+    def to_dict(self) -> dict:
+        return {
+            "width": self.width,
+            "height": self.height,
+            "variance": round(self.variance, 4),
+            "mean": round(self.mean, 3),
+            "max_value": self.max_value,
+            "dominant_ratio": round(self.dominant_ratio, 4),
+            "uniform": self.uniform,
+            "blank": self.blank,
+            "reason": self.reason,
+        }
+
+
+def analyze_image(
+    image,
+    *,
+    variance_threshold: float = 0.05,
+    dominant_threshold: float = 0.999,
+    min_max_value: int = 10,
+) -> ImageAnalysis:
+    """Decide whether a frame carries real content.
+
+    Three failure signatures are checked, because no single one is sufficient:
+
+    * **near-black frame** -- ``max(pixel) < min_max_value``. This is the cheap, very reliable
+      check used by production WeChat automation (``np.array(img).max() > 10``): any real
+      window contains at least one bright pixel, a failed ``PrintWindow`` does not.
+    * **uniform surface** -- variance below ``variance_threshold``: nothing was painted at all
+      (covers all-white as well as a solid theme colour).
+    * **single colour** -- one colour covering at least ``dominant_threshold`` of the pixels
+      *and* still lacking structure (variance < 1.0). The variance guard keeps a mostly-white
+      window with a little text acceptable.
+    """
+    try:
+        from PIL import Image, ImageStat
+    except ImportError as exc:  # pragma: no cover - Pillow is a hard dependency
+        raise CaptureError(
+            f"Pillow is required for capture validation: {exc}", code="missing-pillow"
+        ) from exc
+
+    analysis = ImageAnalysis(width=image.width, height=image.height)
+    if image.width == 0 or image.height == 0:
+        analysis.blank = True
+        analysis.reason = "empty-geometry"
+        return analysis
+    greyscale = image.convert("L")
+    stats = ImageStat.Stat(greyscale)
+    analysis.mean = float(stats.mean[0])
+    analysis.variance = float(stats.var[0])
+    try:
+        analysis.max_value = int(stats.extrema[0][1])
+    except Exception:  # pragma: no cover - defensive
+        analysis.max_value = 255
+    try:
+        channels = image.split()[:3]
+        peak = 0
+        total = 0
+        for channel in channels:
+            histogram = channel.histogram()
+            peak = max(peak, max(histogram))
+            total = max(total, sum(histogram))
+        analysis.dominant_ratio = (peak / total) if total else 0.0
+    except Exception:  # pragma: no cover - defensive
+        analysis.dominant_ratio = 0.0
+
+    if analysis.variance < variance_threshold:
+        analysis.uniform = True
+        analysis.blank = True
+        analysis.reason = f"uniform(variance={analysis.variance:.4f})"
+        return analysis
+    if analysis.max_value < min_max_value:
+        # Cheap, very reliable failure signature used by production WeChat automation
+        # (``np.array(img).max() > 10``): a real window always contains a bright pixel.
+        analysis.blank = True
+        analysis.reason = f"near-black(max={analysis.max_value})"
+        return analysis
+    if analysis.dominant_ratio >= dominant_threshold and analysis.variance < 1.0:
+        # A single colour across (almost) the whole frame with no structure.
+        analysis.blank = True
+        analysis.reason = f"single-colour({analysis.dominant_ratio:.4f})"
+        return analysis
+    return analysis
+
+
+@dataclass
+class Frame:
+    """A captured frame plus everything needed to explain how it was produced."""
+
+    image: object  # PIL.Image.Image (kept untyped to avoid a hard import at module load)
+    hwnd: int = 0
+    method: str = ""
+    region: Tuple[int, int, int, int] = (0, 0, 0, 0)
+    client_only: bool = True
+    dpi_aware: bool = False
+    attempts: List[dict] = field(default_factory=list)
+    analysis: Optional[ImageAnalysis] = None
+    duration: float = 0.0
+
+    @property
+    def size(self) -> Tuple[int, int]:
+        return (self.image.width, self.image.height)  # type: ignore[attr-defined]
+
+    def save(self, path, **kwargs) -> str:
+        """Save the frame (PNG by default) and return the written path."""
+        target = str(path)
+        self.image.save(target, **kwargs)  # type: ignore[attr-defined]
+        return target
+
+    def to_dict(self) -> dict:
+        return {
+            "hwnd": self.hwnd,
+            "method": self.method,
+            "region": list(self.region),
+            "client_only": self.client_only,
+            "dpi_aware": self.dpi_aware,
+            "size": list(self.size),
+            "attempts": list(self.attempts),
+            "analysis": self.analysis.to_dict() if self.analysis else None,
+            "duration": round(self.duration, 4),
+        }
+
+
+def _virtual_screen() -> Tuple[int, int, int, int]:
+    SM_XVIRTUALSCREEN, SM_YVIRTUALSCREEN, SM_CXVIRTUALSCREEN, SM_CYVIRTUALSCREEN = 76, 77, 78, 79
+    return (
+        user32.GetSystemMetrics(SM_XVIRTUALSCREEN),
+        user32.GetSystemMetrics(SM_YVIRTUALSCREEN),
+        user32.GetSystemMetrics(SM_CXVIRTUALSCREEN),
+        user32.GetSystemMetrics(SM_CYVIRTUALSCREEN),
+    )
+
+
+class _MemoryBitmap:
+    """A top-down 32-bit DIB section plus its DC; always released."""
+
+    def __init__(self, width: int, height: int):
+        self.width = int(width)
+        self.height = int(height)
+        self._screen_dc = user32.GetDC(None)
+        if not self._screen_dc:
+            raise CaptureError(
+                f"GetDC(NULL) failed with Win32 error {ctypes.get_last_error()}",
+                code="getdc-failed",
+            )
+        self.dc = gdi32.CreateCompatibleDC(self._screen_dc)
+        if not self.dc:
+            user32.ReleaseDC(None, self._screen_dc)
+            raise CaptureError("CreateCompatibleDC failed", code="createdc-failed")
+        header = _BITMAPINFOHEADER()
+        header.biSize = ctypes.sizeof(_BITMAPINFOHEADER)
+        header.biWidth = self.width
+        header.biHeight = -self.height  # negative => top-down rows
+        header.biPlanes = 1
+        header.biBitCount = 32
+        header.biCompression = BI_RGB
+        self.bits = ctypes.c_void_p()
+        self._header = header
+        self.bitmap = gdi32.CreateDIBSection(
+            self.dc, ctypes.byref(header), DIB_RGB_COLORS, ctypes.byref(self.bits), None, 0
+        )
+        if not self.bitmap:
+            self.close()
+            raise CaptureError("CreateDIBSection failed", code="createdib-failed")
+        self._previous = gdi32.SelectObject(self.dc, self.bitmap)
+
+    def buffer(self) -> ctypes.Array:
+        size = self.width * self.height * 4
+        return ctypes.cast(self.bits, ctypes.POINTER(ctypes.c_char * size)).contents
+
+    def to_image(self):
+        from PIL import Image
+
+        data = bytes(self.buffer())
+        return Image.frombuffer("RGB", (self.width, self.height), data, "raw", "BGRX", 0, 1)
+
+    def close(self) -> None:
+        if getattr(self, "bitmap", None):
+            if getattr(self, "_previous", None):
+                gdi32.SelectObject(self.dc, self._previous)
+                self._previous = None
+            gdi32.DeleteObject(self.bitmap)
+            self.bitmap = None
+        if getattr(self, "dc", None):
+            gdi32.DeleteDC(self.dc)
+            self.dc = None
+        if getattr(self, "_screen_dc", None):
+            user32.ReleaseDC(None, self._screen_dc)
+            self._screen_dc = None
+
+    def __enter__(self) -> "_MemoryBitmap":
+        return self
+
+    def __exit__(self, exc_type, exc, tb) -> None:
+        self.close()
+
+
+class CaptureEngine:
+    """Runs the capture decision tree and returns the first *usable* frame."""
+
+    def __init__(
+        self,
+        *,
+        methods: Sequence[str] = DEFAULT_METHODS,
+        client_only: bool = True,
+        validate: bool = True,
+        variance_threshold: float = 0.05,
+        dominant_threshold: float = 0.999,
+        timeout: float = 5.0,
+        allow_blank_fallback: bool = True,
+    ) -> None:
+        unknown = [m for m in methods if m not in DEFAULT_METHODS]
+        if unknown:
+            raise CaptureError(
+                f"unknown capture method(s): {', '.join(unknown)}",
+                code="unknown-method",
+                hint=f"Available methods: {', '.join(DEFAULT_METHODS)}",
+            )
+        self.methods = tuple(methods)
+        self.client_only = client_only
+        self.validate = validate
+        self.variance_threshold = variance_threshold
+        self.dominant_threshold = dominant_threshold
+        self.timeout = timeout
+        self.allow_blank_fallback = allow_blank_fallback
+        self._dpi_entered = False
+
+    # -- public API ------------------------------------------------------------------
+    def capture(
+        self,
+        hwnd: int,
+        *,
+        client_only: Optional[bool] = None,
+        methods: Optional[Sequence[str]] = None,
+        region: Optional[Tuple[int, int, int, int]] = None,
+        require_content: Optional[bool] = None,
+        save_to: Optional[str] = None,
+    ) -> Frame:
+        """Capture ``hwnd``.
+
+        ``region`` (left, top, right, bottom in *client* coordinates) crops the result,
+        which is what OCR pipelines usually want.  ``save_to`` writes the frame to disk
+        (PNG by default) before returning it.
+        """
+        require_windows("CaptureEngine.capture")
+        if not user32.IsWindow(hwnd):
+            raise CaptureError(
+                f"0x{hwnd:X} is not a window (it may have been closed)", code="invalid-hwnd"
+            )
+        use_client = self.client_only if client_only is None else client_only
+        chain = tuple(methods or self.methods)
+        must_have_content = self.validate if require_content is None else require_content
+        started = time.monotonic()
+        attempts: List[dict] = []
+        blank_frame: Optional[Frame] = None
+
+        self.ensure_dpi_aware()
+        for method in chain:
+            try:
+                image, used_region = self._invoke(method, hwnd, use_client)
+            except CaptureError as exc:
+                attempts.append(
+                    {"method": method, "ok": False, "error": str(exc), "code": exc.code}
+                )
+                log.debug("capture method %s failed: %s", method, exc)
+                continue
+            analysis = (
+                analyze_image(
+                    image,
+                    variance_threshold=self.variance_threshold,
+                    dominant_threshold=self.dominant_threshold,
+                )
+                if self.validate
+                else None
+            )
+            attempts.append(
+                {
+                    "method": method,
+                    "ok": True,
+                    "analysis": analysis.to_dict() if analysis else None,
+                }
+            )
+            frame = Frame(
+                image=image,
+                hwnd=hwnd,
+                method=method,
+                region=used_region,
+                client_only=use_client,
+                dpi_aware=self._dpi_entered,
+                attempts=attempts,
+                analysis=analysis,
+                duration=time.monotonic() - started,
+            )
+            if analysis is None or analysis.usable:
+                if region is not None:
+                    frame.image = self._crop(image, used_region, region)
+                if save_to:
+                    frame.save(save_to)
+                return frame
+            log.info(
+                "capture method %s produced a %s frame; trying the next method",
+                method,
+                analysis.reason,
+            )
+            if blank_frame is None:
+                blank_frame = frame
+
+        if blank_frame is not None and self.allow_blank_fallback and not must_have_content:
+            log.warning("returning a blank frame because require_content=False")
+            return blank_frame
+        raise CaptureError(
+            "every capture method failed or produced a blank frame for 0x%X" % hwnd,
+            code="capture-blank",
+            details={
+                "attempts": attempts,
+                "methods": list(chain),
+                "client_only": use_client,
+            },
+            hint="Hardware-accelerated or DRM-protected windows cannot be captured offscreen. "
+            "Try methods=('bitblt',) with the window visible on the virtual display.",
+        )
+
+    def ensure_dpi_aware(self, awareness: str = "per_monitor_v2") -> bool:
+        """Set DPI awareness once per process (never restored: other code benefits too)."""
+        if getattr(self, "_dpi_entered", False):
+            return True
+        if not IS_WINDOWS:
+            return False
+        scope = dpi_awareness_scope(awareness, restore=False)
+        scope.__enter__()
+        self._dpi_entered = scope.applied is not None or scope.previous is not None
+        log.debug("DPI awareness set to %s", awareness)
+        return self._dpi_entered
+
+    # -- internals -------------------------------------------------------------------
+    def _target_rect(self, hwnd: int, client_only: bool) -> Tuple[int, int, int, int, Tuple[int, int]]:
+        """Return ``(left, top, width, height, (client_w, client_h))``."""
+        window = _RECT()
+        if not user32.GetWindowRect(hwnd, ctypes.byref(window)):
+            raise CaptureError("GetWindowRect failed", code="geometry-failed")
+        if client_only:
+            client = _RECT()
+            origin = _POINT(0, 0)
+            if user32.GetClientRect(hwnd, ctypes.byref(client)) and user32.ClientToScreen(
+                hwnd, ctypes.byref(origin)
+            ):
+                width = int(client.right - client.left)
+                height = int(client.bottom - client.top)
+                if width > 0 and height > 0:
+                    return int(origin.x), int(origin.y), width, height, (width, height)
+        width = int(window.right - window.left)
+        height = int(window.bottom - window.top)
+        if width <= 0 or height <= 0:
+            raise CaptureError(
+                f"window 0x{hwnd:X} has a degenerate geometry {width}x{height}",
+                code="degenerate-geometry",
+            )
+        return int(window.left), int(window.top), width, height, (width, height)
+
+    def _invoke(self, method: str, hwnd: int, client_only: bool):
+        left, top, width, height, _ = self._target_rect(hwnd, client_only)
+        region = (left, top, left + width, top + height)
+        if method == "printwindow":
+            return self._print_window(hwnd, width, height, client_only, PW_RENDERFULLCONTENT), region
+        if method == "printwindow_plain":
+            return self._print_window(hwnd, width, height, client_only, 0), region
+        if method == "wm_print":
+            return self._wm_print(hwnd, width, height, client_only), region
+        if method == "bitblt":
+            return self._bitblt(hwnd, left, top, width, height, client_only), region
+        raise CaptureError(f"unknown method {method!r}", code="unknown-method")
+
+    def _print_window(self, hwnd: int, width: int, height: int, client_only: bool, flags: int):
+        """``PrintWindow`` into a top-down DIB.
+
+        Validated against the approach used by production WeChat automation
+        (``Luofeng-Cloud/WeChat-AI-AutoReply``, ``grab_wechat_window``): ``GetWindowDC`` +
+        ``CreateCompatibleDC`` + ``CreateCompatibleBitmap(w, h)`` + ``PrintWindow(hwnd, dc, 2)``
+        with a plain-``PrintWindow`` fallback, then ``GetDIBits`` into a BGRA buffer.  Using a
+        **screen** DC for the compatible DC and a DIB section (this implementation) is
+        equivalent; the differences that matter are elsewhere and are handled by the caller:
+        the bitmap must be the *window's* rectangle (not the monitor's), and the result must be
+        rejected when it is effectively empty (a max pixel value near zero).
+        """
+        with _MemoryBitmap(width, height) as bitmap:
+            flag = flags | (PW_CLIENTONLY if client_only and not flags else 0)
+            ctypes.set_last_error(0)
+            result = user32.PrintWindow(hwnd, bitmap.dc, flag)
+            if not result:
+                error = ctypes.get_last_error()
+                # A FALSE return is not always fatal: some windows paint anyway. Only
+                # treat a *blank* result as failure, which the caller already checks.
+                log.debug("PrintWindow(flags=%s) returned 0 (Win32 error %s)", flag, error)
+            return bitmap.to_image()
+
+    def _wm_print(self, hwnd: int, width: int, height: int, client_only: bool):
+        with _MemoryBitmap(width, height) as bitmap:
+            flags = PRF_CLIENT | PRF_CHILDREN | PRF_ERASEBKGND
+            if not client_only:
+                flags |= PRF_NONCLIENT
+            message = WM_PRINTCLIENT if client_only else WM_PRINT
+            result = ctypes.c_void_p()
+            ok = user32.SendMessageTimeoutW(
+                hwnd, message, int(bitmap.dc), flags, SMTO_ABORTIFHUNG, int(self.timeout * 1000), ctypes.byref(result)
+            )
+            if not ok:
+                raise CaptureError(
+                    f"WM_PRINT timed out or was refused (Win32 error {ctypes.get_last_error()})",
+                    code="wm-print-failed",
+                )
+            return bitmap.to_image()
+
+    def _bitblt(self, hwnd: int, left: int, top: int, width: int, height: int, client_only: bool):
+        with _MemoryBitmap(width, height) as bitmap:
+            source = user32.GetDC(hwnd) if client_only else user32.GetWindowDC(hwnd)
+            if not source:
+                raise CaptureError("GetDC(hwnd) failed", code="getdc-failed")
+            try:
+                ok = gdi32.BitBlt(
+                    bitmap.dc, 0, 0, width, height, source, 0, 0, SRCCOPY | CAPTUREBLT
+                )
+            finally:
+                user32.ReleaseDC(hwnd, source)
+            if not ok:
+                raise CaptureError(
+                    f"BitBlt from the window DC failed (Win32 error {ctypes.get_last_error()})",
+                    code="bitblt-failed",
+                )
+            return bitmap.to_image()
+
+    @staticmethod
+    def _crop(image, used_region, region):
+        """Crop ``region`` (absolute client coordinates) out of the captured frame."""
+        offset_x = region[0] - used_region[0]
+        offset_y = region[1] - used_region[1]
+        box = (
+            max(offset_x, 0),
+            max(offset_y, 0),
+            min(offset_x + (region[2] - region[0]), image.width),
+            min(offset_y + (region[3] - region[1]), image.height),
+        )
+        if box[2] <= box[0] or box[3] <= box[1]:
+            raise CaptureError(
+                f"requested region {region} lies outside the captured area {used_region}",
+                code="region-outside",
+            )
+        return image.crop(box)
+
+    # -- diagnostics -----------------------------------------------------------------
+    def probe(self, hwnd: int, *, client_only: Optional[bool] = None) -> dict:
+        """Run every method and report per-method outcomes (used by ``check --window``)."""
+        results = []
+        use_client = self.client_only if client_only is None else client_only
+        for method in self.methods:
+            entry: Dict[str, object] = {"method": method}
+            try:
+                frame = self.capture(
+                    hwnd, client_only=use_client, methods=[method], require_content=True
+                )
+                entry["ok"] = True
+                entry["size"] = list(frame.size)
+                entry["analysis"] = frame.analysis.to_dict() if frame.analysis else None
+            except CaptureError as exc:
+                entry["ok"] = False
+                entry["error"] = str(exc)
+                entry["code"] = exc.code
+            results.append(entry)
+        return {"hwnd": hwnd, "client_only": use_client, "methods": results}