capturekit 0.1.0__py3-none-any.whl

capturekit/_backends/windows/_com.py

@@ -0,0 +1,350 @@
+"""Minimal COM support on top of ctypes.
+
+* :class:`ComPtr` calls interface methods by vtable index (indices are listed
+  in ``.claude/skills/windows-capture-backend/reference/vtables.md``).
+* :class:`ComObject` implements COM interfaces in Python (event delegates,
+  completion handlers).
+"""
+
+from __future__ import annotations
+
+import collections
+import ctypes
+import logging
+import sys
+import threading
+import uuid
+from collections.abc import Callable, Sequence
+from ctypes import POINTER, Structure, byref, c_long, c_ubyte, c_ulong, c_ushort, c_void_p
+from typing import Any, ClassVar
+
+from ...errors import NativeError
+
+log = logging.getLogger("capturekit.windows")
+
+if sys.platform != "win32":  # pragma: no cover - guarded by _platform
+    raise ImportError("capturekit._backends.windows requires Windows")
+
+WINFUNCTYPE = ctypes.WINFUNCTYPE
+
+S_OK = 0
+S_FALSE = 1
+E_NOINTERFACE = -2147467262  # 0x80004002
+E_POINTER = -2147467261  # 0x80004003
+E_FAIL = -2147467259  # 0x80004005
+RPC_E_CHANGED_MODE = -2147417850  # 0x80010106
+
+
+class GUID(Structure):
+    _fields_ = [
+        ("Data1", c_ulong),
+        ("Data2", c_ushort),
+        ("Data3", c_ushort),
+        ("Data4", c_ubyte * 8),
+    ]
+
+    @classmethod
+    def from_str(cls, text: str) -> GUID:
+        return cls.from_buffer_copy(uuid.UUID(text).bytes_le)
+
+    def to_uuid(self) -> uuid.UUID:
+        return uuid.UUID(bytes_le=bytes(self))
+
+    def __eq__(self, other: object) -> bool:
+        return isinstance(other, GUID) and bytes(self) == bytes(other)
+
+    def __hash__(self) -> int:
+        return hash(bytes(self))
+
+    def __repr__(self) -> str:
+        return f"GUID('{self.to_uuid()}')"
+
+
+IID_IUnknown = GUID.from_str("00000000-0000-0000-C000-000000000046")
+IID_IAgileObject = GUID.from_str("94ea2b94-e9cc-49e0-c0ff-ee64ca8f5b90")
+IID_IInspectable = GUID.from_str("AF86E2E0-B12D-4c6a-9C5A-D7AA65101E90")
+
+
+def hr_u32(hr: int) -> int:
+    return hr & 0xFFFFFFFF
+
+
+def check_hr(hr: int, what: str) -> None:
+    if hr < 0:
+        raise NativeError(what, hr)
+
+
+_proto_cache: dict[tuple[Any, tuple[Any, ...]], Any] = {}
+
+
+def _prototype(restype: Any, argtypes: tuple[Any, ...]) -> Any:
+    key = (restype, argtypes)
+    proto = _proto_cache.get(key)
+    if proto is None:
+        proto = WINFUNCTYPE(restype, c_void_p, *argtypes)
+        _proto_cache[key] = proto
+    return proto
+
+
+class ComPtr:
+    """Owning reference to a COM interface pointer.
+
+    Release is explicit (``release()`` / context manager). ``__del__`` is a
+    safety net only; correct code releases deterministically on the owning
+    thread.
+    """
+
+    __slots__ = ("_ptr", "name")
+
+    def __init__(self, ptr: int | None, name: str = "") -> None:
+        if not ptr:
+            raise NativeError(f"null {name or 'COM'} pointer")
+        self._ptr: int | None = int(ptr)
+        self.name = name
+
+    @property
+    def ptr(self) -> int:
+        if self._ptr is None:
+            raise NativeError(f"use of released {self.name or 'COM'} pointer")
+        return self._ptr
+
+    @property
+    def as_param(self) -> c_void_p:
+        return c_void_p(self.ptr)
+
+    def method(self, index: int, restype: Any, argtypes: Sequence[Any]) -> Any:
+        ptr = self.ptr
+        vtbl = c_void_p.from_address(ptr).value
+        assert vtbl is not None
+        fn_addr = c_void_p.from_address(vtbl + index * ctypes.sizeof(c_void_p)).value
+        return _prototype(restype, tuple(argtypes))(fn_addr)
+
+    def call(self, index: int, restype: Any, argtypes: Sequence[Any], *args: Any) -> Any:
+        return self.method(index, restype, argtypes)(self.ptr, *args)
+
+    def hcall(self, index: int, argtypes: Sequence[Any], *args: Any, what: str = "") -> int:
+        """Call a method returning HRESULT; raise on failure, return the HRESULT."""
+        hr: int = self.method(index, c_long, argtypes)(self.ptr, *args)
+        if hr < 0:
+            raise NativeError(what or f"{self.name}[{index}]", hr)
+        return hr
+
+    def out_ptr(
+        self, index: int, argtypes: Sequence[Any], *args: Any, what: str = "", name: str = ""
+    ) -> ComPtr:
+        """Call a method whose last parameter is ``void**`` and wrap the result."""
+        out = c_void_p()
+        self.hcall(index, (*argtypes, c_void_p), *args, byref(out), what=what)
+        return ComPtr(out.value, name or what)
+
+    def query(self, iid: GUID, name: str = "") -> ComPtr:
+        out = c_void_p()
+        hr = self.call(0, c_long, (c_void_p, c_void_p), byref(iid), byref(out))
+        check_hr(hr, f"QueryInterface({name or iid!r})")
+        return ComPtr(out.value, name)
+
+    def try_query(self, iid: GUID, name: str = "") -> ComPtr | None:
+        out = c_void_p()
+        hr = self.call(0, c_long, (c_void_p, c_void_p), byref(iid), byref(out))
+        if hr < 0 or not out.value:
+            return None
+        return ComPtr(out.value, name)
+
+    def add_ref(self) -> ComPtr:
+        self.call(1, c_ulong, ())
+        return ComPtr(self.ptr, self.name)
+
+    def release(self) -> None:
+        if self._ptr is not None:
+            ptr, self._ptr = self._ptr, None
+            vtbl = c_void_p.from_address(ptr).value
+            assert vtbl is not None
+            fn = c_void_p.from_address(vtbl + 2 * ctypes.sizeof(c_void_p)).value
+            _prototype(c_ulong, ())(fn)(ptr)
+
+    def __enter__(self) -> ComPtr:
+        return self
+
+    def __exit__(self, *exc: object) -> None:
+        self.release()
+
+    def __del__(self) -> None:
+        if self._ptr is not None and not sys.is_finalizing():
+            try:
+                self.release()
+            except Exception:  # pragma: no cover - last-resort cleanup
+                pass
+
+    def __repr__(self) -> str:
+        return f"<ComPtr {self.name} {self._ptr and hex(self._ptr)}>"
+
+
+def release_all(*ptrs: ComPtr | None) -> None:
+    for p in ptrs:
+        if p is not None:
+            p.release()
+
+
+class _ComObjectStruct(Structure):
+    _fields_ = [("lpVtbl", c_void_p)]
+
+
+class ComObject:
+    """Base class for COM objects implemented in Python.
+
+    Subclasses set ``_iids_`` (interfaces they implement besides IUnknown /
+    IAgileObject) and ``_methods_``: a list of ``(name, restype, argtypes)``
+    for the vtable slots after IUnknown, each implemented as a Python method
+    taking the raw arguments (without ``this``).
+
+    The object keeps itself alive while its COM refcount is > 0, so native
+    code can never call into freed memory. Exceptions raised by methods are
+    logged and converted to ``E_FAIL``.
+    """
+
+    _iids_: ClassVar[Sequence[GUID]] = ()
+    _methods_: ClassVar[Sequence[tuple[str, Any, Sequence[Any]]]] = ()
+    _alive: ClassVar[set[ComObject]] = set()
+    _alive_lock: ClassVar[threading.Lock] = threading.Lock()
+    _graveyard: ClassVar[collections.deque[ComObject]] = collections.deque(maxlen=256)
+
+    def __init__(self, extra_iids: Sequence[GUID] = ()) -> None:
+        self._refs = 1
+        self._ref_lock = threading.Lock()
+        qi = WINFUNCTYPE(c_long, c_void_p, POINTER(GUID), POINTER(c_void_p))(self._qi)
+        addref = WINFUNCTYPE(c_ulong, c_void_p)(self._addref)
+        release = WINFUNCTYPE(c_ulong, c_void_p)(self._release)
+        funcs: list[Any] = [qi, addref, release]
+        for name, restype, argtypes in self._methods_:
+            impl = getattr(self, name)
+            funcs.append(WINFUNCTYPE(restype, c_void_p, *argtypes)(self._guard(impl, restype)))
+        self._funcs = funcs  # keep callbacks alive
+        self._vtbl = (c_void_p * len(funcs))(*[ctypes.cast(f, c_void_p) for f in funcs])
+        self._struct = _ComObjectStruct(ctypes.cast(self._vtbl, c_void_p))
+        self._supported = {bytes(IID_IUnknown), bytes(IID_IAgileObject)} | {
+            bytes(i) for i in (*self._iids_, *extra_iids)
+        }
+        with ComObject._alive_lock:
+            ComObject._alive.add(self)
+
+    @property
+    def ptr(self) -> int:
+        return ctypes.addressof(self._struct)
+
+    def _guard(self, fn: Callable[..., Any], restype: Any) -> Callable[..., Any]:
+        def wrapper(_this: int, *args: Any) -> Any:
+            try:
+                res = fn(*args)
+                return S_OK if res is None and restype is c_long else res
+            except Exception:
+                log.exception("exception in COM callback %s", fn.__name__)
+                return E_FAIL if restype is c_long else 0
+
+        return wrapper
+
+    def _qi(self, _this: int, riid: Any, ppv: Any) -> int:
+        if not ppv:
+            return E_POINTER
+        if bytes(riid.contents) in self._supported:
+            ppv[0] = self.ptr
+            self._addref(_this)
+            return S_OK
+        ppv[0] = None
+        return E_NOINTERFACE
+
+    def _addref(self, _this: int) -> int:
+        with self._ref_lock:
+            self._refs += 1
+            return self._refs
+
+    def _release(self, _this: int) -> int:
+        with self._ref_lock:
+            self._refs -= 1
+            refs = self._refs
+        if refs == 0:
+            with ComObject._alive_lock:
+                ComObject._alive.discard(self)
+                # Do not free now: this method may be running inside our own
+                # ctypes thunk (native Release call); freeing the thunk before
+                # it returns crashes the process. Keep dead objects in a
+                # bounded graveyard so they die long after their last call.
+                ComObject._graveyard.append(self)
+        return refs
+
+    def release(self) -> None:
+        """Drop the Python-side initial reference."""
+        self._release(0)
+
+
+# --- COM apartment ---------------------------------------------------------
+
+_ole32 = ctypes.WinDLL("ole32", use_last_error=True)
+_ole32.CoInitializeEx.argtypes = (c_void_p, ctypes.c_uint)
+_ole32.CoInitializeEx.restype = c_long
+_ole32.CoUninitialize.argtypes = ()
+_ole32.CoUninitialize.restype = None
+_ole32.CoCreateInstance.argtypes = (c_void_p, c_void_p, ctypes.c_uint, c_void_p, c_void_p)
+_ole32.CoCreateInstance.restype = c_long
+_ole32.CoTaskMemFree.argtypes = (c_void_p,)
+_ole32.CoTaskMemFree.restype = None
+_ole32.PropVariantClear.argtypes = (c_void_p,)
+_ole32.PropVariantClear.restype = c_long
+
+_ole32.CoIncrementMTAUsage.argtypes = (c_void_p,)
+_ole32.CoIncrementMTAUsage.restype = c_long
+
+COINIT_MULTITHREADED = 0x0
+CLSCTX_ALL = 0x17
+
+_mta_cookie = c_void_p()
+_mta_lock = threading.Lock()
+
+
+def ensure_mta_usage() -> None:
+    """Keep the process MTA alive for the rest of the process lifetime.
+
+    Without this, the last MTA thread's CoUninitialize/RoUninitialize tears
+    down the MTA and may unload WinRT capture DLLs while thread-pool
+    callbacks are still pending (reproduced: access violation shortly after
+    closing a WGC session whose window had been destroyed). The cookie is
+    intentionally never released.
+    """
+    with _mta_lock:
+        if not _mta_cookie.value:
+            check_hr(_ole32.CoIncrementMTAUsage(byref(_mta_cookie)), "CoIncrementMTAUsage")
+
+
+class ComApartment:
+    """Context manager: join the MTA on this thread for the duration."""
+
+    def __enter__(self) -> ComApartment:
+        ensure_mta_usage()
+        hr = _ole32.CoInitializeEx(None, COINIT_MULTITHREADED)
+        # S_FALSE = already initialised (balanced by CoUninitialize too).
+        # RPC_E_CHANGED_MODE = caller's thread is STA: usable, but don't uninit.
+        self._uninit = hr >= 0
+        if hr < 0 and hr != RPC_E_CHANGED_MODE:
+            check_hr(hr, "CoInitializeEx")
+        return self
+
+    def __exit__(self, *exc: object) -> None:
+        if self._uninit:
+            _ole32.CoUninitialize()
+
+
+def co_create_instance(clsid: GUID, iid: GUID, name: str = "") -> ComPtr:
+    out = c_void_p()
+    check_hr(
+        _ole32.CoCreateInstance(byref(clsid), None, CLSCTX_ALL, byref(iid), byref(out)),
+        f"CoCreateInstance({name})",
+    )
+    return ComPtr(out.value, name)
+
+
+def co_task_mem_free(ptr: int | None) -> None:
+    if ptr:
+        _ole32.CoTaskMemFree(ptr)
+
+
+def prop_variant_clear(pv: Any) -> None:
+    _ole32.PropVariantClear(byref(pv))

capturekit/_backends/windows/_d3d11.py

@@ -0,0 +1,307 @@
+"""Direct3D 11 / DXGI bindings used by the capture backends."""
+
+from __future__ import annotations
+
+import ctypes
+from ctypes import POINTER, Structure, byref, c_int, c_long, c_uint, c_void_p
+from ctypes import wintypes as wt
+
+import numpy as np
+import numpy.typing as npt
+
+from ...errors import NativeError
+from ._com import GUID, ComPtr, check_hr
+
+_d3d11 = ctypes.WinDLL("d3d11")
+_dxgi = ctypes.WinDLL("dxgi")
+
+_d3d11.D3D11CreateDevice.argtypes = (
+    c_void_p, c_int, c_void_p, c_uint, c_void_p, c_uint, c_uint,
+    POINTER(c_void_p), POINTER(c_int), POINTER(c_void_p),
+)  # fmt: skip
+_d3d11.D3D11CreateDevice.restype = c_long
+_d3d11.CreateDirect3D11DeviceFromDXGIDevice.argtypes = (c_void_p, POINTER(c_void_p))
+_d3d11.CreateDirect3D11DeviceFromDXGIDevice.restype = c_long
+_dxgi.CreateDXGIFactory1.argtypes = (c_void_p, POINTER(c_void_p))
+_dxgi.CreateDXGIFactory1.restype = c_long
+
+IID_IDXGIFactory1 = GUID.from_str("770aae78-f26f-4dba-a829-253c83d1b387")
+IID_IDXGIDevice = GUID.from_str("54ec77fa-1377-44e6-8c32-88fd5f44c84c")
+IID_IDXGIOutput1 = GUID.from_str("00cddea8-939b-4b83-a340-a685226666cc")
+IID_ID3D11Texture2D = GUID.from_str("6f15aaf2-d208-4e89-9ab4-489535d34f9c")
+IID_ID3D10Multithread = GUID.from_str("9B7E4E00-342C-4106-A19F-4F2704F689F0")
+
+D3D_DRIVER_TYPE_UNKNOWN = 0
+D3D_DRIVER_TYPE_HARDWARE = 1
+D3D11_CREATE_DEVICE_BGRA_SUPPORT = 0x20
+D3D11_SDK_VERSION = 7
+DXGI_FORMAT_B8G8R8A8_UNORM = 87
+D3D11_USAGE_STAGING = 3
+D3D11_CPU_ACCESS_READ = 0x20000
+D3D11_MAP_READ = 1
+
+# ID3D11Device
+_DEV_CreateTexture2D = 5
+_DEV_GetImmediateContext = 40
+# ID3D11DeviceContext
+_CTX_Map = 14
+_CTX_Unmap = 15
+_CTX_CopySubresourceRegion = 46
+_CTX_Flush = 111
+# ID3D11Texture2D
+_TEX_GetDesc = 10
+# ID3D10Multithread
+_MT_SetMultithreadProtected = 5
+
+
+class D3D11_TEXTURE2D_DESC(Structure):
+    _fields_ = [
+        ("Width", c_uint),
+        ("Height", c_uint),
+        ("MipLevels", c_uint),
+        ("ArraySize", c_uint),
+        ("Format", c_uint),
+        ("SampleCount", c_uint),
+        ("SampleQuality", c_uint),
+        ("Usage", c_uint),
+        ("BindFlags", c_uint),
+        ("CPUAccessFlags", c_uint),
+        ("MiscFlags", c_uint),
+    ]
+
+
+class D3D11_MAPPED_SUBRESOURCE(Structure):
+    _fields_ = [("pData", c_void_p), ("RowPitch", c_uint), ("DepthPitch", c_uint)]
+
+
+class D3D11_BOX(Structure):
+    _fields_ = [
+        ("left", c_uint),
+        ("top", c_uint),
+        ("front", c_uint),
+        ("right", c_uint),
+        ("bottom", c_uint),
+        ("back", c_uint),
+    ]
+
+
+class LUID(Structure):
+    _fields_ = [("LowPart", wt.DWORD), ("HighPart", wt.LONG)]
+
+
+class DXGI_ADAPTER_DESC1(Structure):
+    _fields_ = [
+        ("Description", wt.WCHAR * 128),
+        ("VendorId", c_uint),
+        ("DeviceId", c_uint),
+        ("SubSysId", c_uint),
+        ("Revision", c_uint),
+        ("DedicatedVideoMemory", ctypes.c_size_t),
+        ("DedicatedSystemMemory", ctypes.c_size_t),
+        ("SharedSystemMemory", ctypes.c_size_t),
+        ("AdapterLuid", LUID),
+        ("Flags", c_uint),
+    ]
+
+
+class DXGI_OUTPUT_DESC(Structure):
+    _fields_ = [
+        ("DeviceName", wt.WCHAR * 32),
+        ("DesktopCoordinates", wt.RECT),
+        ("AttachedToDesktop", wt.BOOL),
+        ("Rotation", c_uint),
+        ("Monitor", wt.HMONITOR),
+    ]
+
+
+def create_device(adapter: ComPtr | None = None) -> tuple[ComPtr, ComPtr]:
+    """Create a BGRA-capable D3D11 device and its immediate context.
+
+    With ``adapter`` the device is created on that adapter (required for DXGI
+    duplication of outputs owned by it).
+    """
+    dev, ctx = c_void_p(), c_void_p()
+    level = c_int()
+    hr = _d3d11.D3D11CreateDevice(
+        adapter.as_param if adapter else None,
+        D3D_DRIVER_TYPE_UNKNOWN if adapter else D3D_DRIVER_TYPE_HARDWARE,
+        None,
+        D3D11_CREATE_DEVICE_BGRA_SUPPORT,
+        None,
+        0,
+        D3D11_SDK_VERSION,
+        byref(dev),
+        byref(level),
+        byref(ctx),
+    )
+    check_hr(hr, "D3D11CreateDevice")
+    device = ComPtr(dev.value, "ID3D11Device")
+    context = ComPtr(ctx.value, "ID3D11DeviceContext")
+    mt = device.try_query(IID_ID3D10Multithread, "ID3D10Multithread")
+    if mt is not None:
+        # WGC's free-threaded frame pool uses the device from its own thread.
+        mt.call(_MT_SetMultithreadProtected, c_int, (c_int,), 1)
+        mt.release()
+    return device, context
+
+
+def create_winrt_device(device: ComPtr) -> ComPtr:
+    """Wrap a D3D11 device as WinRT ``IDirect3DDevice`` (IInspectable)."""
+    with device.query(IID_IDXGIDevice, "IDXGIDevice") as dxgi_dev:
+        out = c_void_p()
+        check_hr(
+            _d3d11.CreateDirect3D11DeviceFromDXGIDevice(dxgi_dev.as_param, byref(out)),
+            "CreateDirect3D11DeviceFromDXGIDevice",
+        )
+    return ComPtr(out.value, "IDirect3DDevice")
+
+
+def create_dxgi_factory() -> ComPtr:
+    out = c_void_p()
+    check_hr(_dxgi.CreateDXGIFactory1(byref(IID_IDXGIFactory1), byref(out)), "CreateDXGIFactory1")
+    return ComPtr(out.value, "IDXGIFactory1")
+
+
+DXGI_ERROR_NOT_FOUND = -2005270526  # 0x887A0002
+
+
+def enum_outputs() -> list[tuple[ComPtr, ComPtr, DXGI_OUTPUT_DESC, DXGI_ADAPTER_DESC1]]:
+    """All (adapter, output, output_desc, adapter_desc) attached to the desktop.
+
+    Caller owns (and must release) the returned ComPtrs.
+    """
+    result = []
+    with create_dxgi_factory() as factory:
+        a = 0
+        while True:
+            out = c_void_p()
+            hr = factory.call(12, c_long, (c_uint, c_void_p), a, byref(out))  # EnumAdapters1
+            if hr == DXGI_ERROR_NOT_FOUND:
+                break
+            check_hr(hr, "EnumAdapters1")
+            adapter = ComPtr(out.value, "IDXGIAdapter1")
+            adesc = DXGI_ADAPTER_DESC1()
+            adapter.hcall(10, (c_void_p,), byref(adesc), what="GetDesc1")
+            o = 0
+            while True:
+                oout = c_void_p()
+                hr = adapter.call(7, c_long, (c_uint, c_void_p), o, byref(oout))  # EnumOutputs
+                if hr == DXGI_ERROR_NOT_FOUND:
+                    break
+                check_hr(hr, "EnumOutputs")
+                output = ComPtr(oout.value, "IDXGIOutput")
+                odesc = DXGI_OUTPUT_DESC()
+                output.hcall(7, (c_void_p,), byref(odesc), what="IDXGIOutput::GetDesc")
+                if odesc.AttachedToDesktop:
+                    result.append((adapter.add_ref(), output, odesc, adesc))
+                else:
+                    output.release()
+                o += 1
+            adapter.release()
+            a += 1
+    return result
+
+
+def texture_desc(texture: ComPtr) -> D3D11_TEXTURE2D_DESC:
+    desc = D3D11_TEXTURE2D_DESC()
+    texture.call(_TEX_GetDesc, None, (c_void_p,), byref(desc))
+    return desc
+
+
+class StagingReader:
+    """GPU→CPU readback of a sub-rectangle through a CPU-readable texture.
+
+    Only the requested box is copied on the GPU; the CPU side performs exactly
+    one row-pitch-aware copy into the destination numpy array.
+    """
+
+    def __init__(self, device: ComPtr, context: ComPtr) -> None:
+        self._device = device
+        self._context = context
+        self._staging: ComPtr | None = None
+        self._size = (0, 0)
+        self._format = DXGI_FORMAT_B8G8R8A8_UNORM
+
+    def _ensure(self, width: int, height: int, fmt: int) -> ComPtr:
+        if self._staging is not None and self._size == (width, height) and self._format == fmt:
+            return self._staging
+        if self._staging is not None:
+            self._staging.release()
+            self._staging = None
+        desc = D3D11_TEXTURE2D_DESC(
+            Width=width,
+            Height=height,
+            MipLevels=1,
+            ArraySize=1,
+            Format=fmt,
+            SampleCount=1,
+            SampleQuality=0,
+            Usage=D3D11_USAGE_STAGING,
+            BindFlags=0,
+            CPUAccessFlags=D3D11_CPU_ACCESS_READ,
+            MiscFlags=0,
+        )
+        self._staging = self._device.out_ptr(
+            _DEV_CreateTexture2D,
+            (c_void_p, c_void_p),
+            byref(desc),
+            None,
+            what="CreateTexture2D(staging)",
+            name="staging",
+        )
+        self._size = (width, height)
+        self._format = fmt
+        return self._staging
+
+    def copy_box(
+        self,
+        src_texture: ComPtr,
+        x: int,
+        y: int,
+        width: int,
+        height: int,
+        fmt: int = DXGI_FORMAT_B8G8R8A8_UNORM,
+    ) -> None:
+        """Queue a GPU copy of ``src[x:x+w, y:y+h]`` into the staging texture."""
+        staging = self._ensure(width, height, fmt)
+        box = D3D11_BOX(x, y, 0, x + width, y + height, 1)
+        self._context.call(
+            _CTX_CopySubresourceRegion,
+            None,
+            (c_void_p, c_uint, c_uint, c_uint, c_uint, c_void_p, c_uint, c_void_p),
+            staging.as_param, 0, 0, 0, 0, src_texture.as_param, 0, byref(box),
+        )  # fmt: skip
+
+    def read_into(self, out: npt.NDArray[np.uint8], dst_x: int = 0, dst_y: int = 0) -> None:
+        """Map the staging texture and copy it into ``out[dst_y:, dst_x:]``.
+
+        The copied area is clipped to ``out``; Map blocks until the GPU copy
+        has completed.
+        """
+        if self._staging is None:
+            raise NativeError("read_into before copy_box")
+        w, h = self._size
+        mapped = D3D11_MAPPED_SUBRESOURCE()
+        self._context.hcall(
+            _CTX_Map, (c_void_p, c_uint, c_uint, c_uint, c_void_p),
+            self._staging.as_param, 0, D3D11_MAP_READ, 0, byref(mapped), what="Map(staging)",
+        )  # fmt: skip
+        try:
+            pitch = int(mapped.RowPitch)
+            if not mapped.pData or pitch < w * 4:
+                raise NativeError(f"invalid mapped staging texture (pitch={pitch}, w={w})")
+            cw = max(0, min(w, out.shape[1] - dst_x))
+            ch = max(0, min(h, out.shape[0] - dst_y))
+            if cw and ch:
+                raw = (ctypes.c_ubyte * (pitch * (ch - 1) + cw * 4)).from_address(mapped.pData)
+                src = np.lib.stride_tricks.as_strided(
+                    np.frombuffer(raw, dtype=np.uint8), shape=(ch, cw, 4), strides=(pitch, 4, 1)
+                )
+                out[dst_y : dst_y + ch, dst_x : dst_x + cw] = src
+        finally:
+            self._context.call(_CTX_Unmap, None, (c_void_p, c_uint), self._staging.as_param, 0)
+
+    def release(self) -> None:
+        if self._staging is not None:
+            self._staging.release()
+            self._staging = None