remotedesktop 0.13.0__tar.gz → 0.14.0__tar.gz

{remotedesktop-0.13.0 → remotedesktop-0.14.0}/CLAUDE.md

@@ -39,7 +39,7 @@ Managed with `uv` (hatchling build backend, src layout):
 - The client-side remote desktop view is a widget, `ViewerWidget` in `src/remotedesktop/viewer.py`, hosted as `ClientWindow`'s central widget. Screen display and keyboard/mouse/clipboard forwarding belong in this widget, not in the window.
 - **Autodiscovery** (`src/remotedesktop/discovery.py`) is a stdlib-only UDP probe/response protocol, deliberately not mDNS: the client broadcasts a JSON probe to `DISCOVERY_PORT` (48653) and servers reply with `{name, port}`; datagrams with the wrong magic/version/type are dropped. The server runs a `DiscoveryResponder` thread while its window is open; the client's `DiscoveryPanel` (dock in `ClientWindow`) calls the blocking `discover_servers()` on a worker thread and delivers results to the GUI via a queued signal. `DEFAULT_CONNECT_PORT` (48654) is reserved for the future desktop connection.
 - Discovery tests run over loopback with ephemeral ports (`bind_host`/`discovery_port`/`broadcast_hosts` parameters exist for this), so they never touch the real LAN or fixed ports.
-- **Screen sharing** (`sharing.py` + `protocol.py` + `frames.py`) runs entirely on the Qt event loop — no threads or locks. `MessageStream` frames messages over a QTcpSocket (4-byte length + kind byte; JSON control messages, full frames, or inter-frame deltas; malformed input aborts the socket). `ShareServer` owns one QTimer that grabs the primary screen at full resolution via `_capture()` (a seam tests override to drive deterministic frame content) and fans out to all clients, skipping clients whose send buffer is backlogged; the timer only runs while clients are connected. **Frame transfer is lossless and inter-frame compressed** (`frames.py`): consecutive captures are diffed in 64-row bands (memoryview compares), and only changed bands ship as PNG in a delta payload the client patches onto its previous frame; an unchanged screen sends nothing. Full PNG keyframes go to clients that just joined, just recovered from a send backlog, or requested one (a `{"type": "keyframe"}` message — sent when a delta fails to apply, so desync self-heals). The capability is negotiated via `"delta": true` in the client hello; clients without it (0.5.0) get full JPEG frames every tick because they force-decode frames as JPEG — never send them PNG. Each variant (legacy JPEG / keyframe PNG / delta) is encoded at most once per tick and shared across clients. `ShareClient` decodes/patches to QImage for the viewer, which displays it scaled with a cached `SmoothTransformation` copy (full resolution is always delivered; scaling happens client-side only).
+- **Screen sharing** (`sharing.py` + `protocol.py` + `frames.py`) runs entirely on the Qt event loop — no threads or locks. `MessageStream` frames messages over a QTcpSocket (4-byte length + kind byte; JSON control messages, full frames, or inter-frame deltas; malformed input aborts the socket). `ShareServer` owns one QTimer that grabs the primary screen at full resolution via `_capture()` (a seam tests override to drive deterministic frame content) and fans out to all clients, skipping clients whose send buffer is backlogged; the timer only runs while clients are connected. Capture is DXGI desktop duplication (`dxgi.py`, hand-rolled ctypes COM — ~10 ms per changed 4K frame, ~0 when idle, and "unchanged" is signalled by returning the same QImage object so the diff is skipped) with automatic fallback to `QScreen.grabWindow` (~96 ms) whenever duplication is unavailable or lost (secure desktop, RDP, display-mode change, CI); unit tests fake the duplication (`FakeDuplication` in `tests/test_dxgi.py`) and the real-hardware test skips where DXGI is unavailable. **Frame transfer is lossless and inter-frame compressed** (`frames.py`): consecutive captures are diffed in 64-row bands (memoryview compares), and only changed bands ship as PNG in a delta payload the client patches onto its previous frame; an unchanged screen sends nothing. Full PNG keyframes go to clients that just joined, just recovered from a send backlog, or requested one (a `{"type": "keyframe"}` message — sent when a delta fails to apply, so desync self-heals). The capability is negotiated via `"delta": true` in the client hello; clients without it (0.5.0) get full JPEG frames every tick because they force-decode frames as JPEG — never send them PNG. Each variant (legacy JPEG / keyframe PNG / delta) is encoded at most once per tick and shared across clients. `ShareClient` decodes/patches to QImage for the viewer, which displays it scaled with a cached `SmoothTransformation` copy (full resolution is always delivered; scaling happens client-side only).
 - **All persistence is one SQLite database** (`db.py`): `db.connect(path)` opens the DB and ensures every table (`settings`, `paired_clients`, `known_servers`, and the inventory tables). The file lives at `config.default_db_path()` — `platformdirs.user_data_dir("remotedesktop")` (`%LOCALAPPDATA%\remotedesktop\remotedesktop.db` on Windows). **Use `platformdirs` for any new data location; don't hardcode `%APPDATA%`.** Every store (`Settings`, `PairedClients`, `KnownServers`, `ConnectionInventory`) takes a `sqlite3.Connection`; the GUIs open one connection per window and share it. Both window classes take a `connection=` keyword so tests inject a temp-file DB and never touch the real one (see `tests/test_client_window.py` / `test_server_window.py`). Tests pass `db.connect(tmp_path/"x.db")` (or omit for in-memory), and use **separate DB files for the server and client** since they model different machines.
 - **Trust model plumbing** (`config.py`): the client has a stable UUID identity (`load_client_identity`, in the `settings` table) and the server maps each approved client-id to a token (`PairedClients`). `ShareServer` takes an `approve_client(client_id, name) -> bool` callback; `ServerWindow` implements it as a modal QMessageBox. Tests inject stores backed by a temp DB and explicit identities so they never touch real data or prompt.
 - **Status/debug logging is a feature**: `ShareServer`, `ShareClient`, and `DiscoveryPanel` emit human-readable `status` signals for every connection phase, and both windows show them in a timestamped "Connection log" pane. When adding connection behavior, emit a status message for each new phase or failure path — there's a test asserting the server's phase messages. Everything the panes show is also written to a rotating debug log file (`logs.py`; `logs.init_logging("client"/"server")` is called only by each app's `main()`, under `platformdirs.user_log_dir("remotedesktop")` — `%LOCALAPPDATA%\remotedesktop\Logs\{client,server}.log` on Windows). Lower-level detail (socket state changes, protocol aborts, frame-drop/backlog, discovery datagram drops) goes straight to `logging.getLogger("remotedesktop.*")` at debug/warning level — silent failure paths should log there even when a status message would be too noisy. Library code and tests never call `init_logging`; without a handler those loggers are no-ops.

{remotedesktop-0.13.0 → remotedesktop-0.14.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: remotedesktop
-Version: 0.13.0
+Version: 0.14.0
 Summary: Remote desktop client/server for Windows computers on the same LAN, with autodiscovery. Provides screen, keyboard, mouse, and clipboard sharing without RDP or Microsoft authentication.
 Author-email: James Abel <j@abel.co>
 License-Expression: MIT

{remotedesktop-0.13.0 → remotedesktop-0.14.0}/src/remotedesktop/__init__.py

@@ -1,3 +1,3 @@
 """Remote desktop client/server for Windows computers on the same LAN."""
 
-__version__ = "0.13.0"
+__version__ = "0.14.0"

remotedesktop-0.14.0/src/remotedesktop/dxgi.py

@@ -0,0 +1,334 @@
+"""Fast screen capture via DXGI Desktop Duplication (Windows), with ctypes.
+
+QScreen.grabWindow costs ~96 ms per 4K frame (GDI BitBlt + conversion) and
+runs on the GUI thread every capture tick, capping the effective frame rate
+near 10 fps and delaying everything else on the event loop. The DXGI
+duplication API instead hands us the desktop as a GPU texture only when
+something actually changed: a grab is a GPU copy plus one CPU memcpy
+(~10 ms at 4K), and an unchanged screen costs ~nothing.
+
+`DesktopDuplication.create()` returns None wherever duplication is not
+available (non-Windows, no interactive desktop, RDP sessions, rotated
+displays) — the caller falls back to grabWindow. `grab()` returns the
+current desktop as a QImage; when nothing changed since the last grab it
+returns the *same QImage object* (callers can use an identity check to skip
+diffing). It returns None when the duplication was lost (secure desktop,
+display-mode change) — the caller should close() and re-create() later.
+
+All COM calls are hand-rolled vtable dispatch; only the handful of methods
+used here are declared, by their fixed vtable slots.
+"""
+
+import ctypes
+import logging
+import sys
+from ctypes import wintypes
+
+from PySide6.QtGui import QImage
+
+_log = logging.getLogger("remotedesktop.dxgi")
+
+_UINT = ctypes.c_uint
+_HRESULT = ctypes.c_int32  # signed, checked manually (HRESULT restype would raise)
+
+
+def _signed(code: int) -> int:
+    return ctypes.c_int32(code).value
+
+
+DXGI_ERROR_WAIT_TIMEOUT = _signed(0x887A0027)
+DXGI_ERROR_ACCESS_LOST = _signed(0x887A0026)
+
+_D3D_DRIVER_TYPE_HARDWARE = 1
+_D3D11_SDK_VERSION = 7
+_D3D11_USAGE_STAGING = 3
+_D3D11_CPU_ACCESS_READ = 0x20000
+_D3D11_MAP_READ = 1
+_DXGI_MODE_ROTATION_UNSPECIFIED = 0
+_DXGI_MODE_ROTATION_IDENTITY = 1
+
+
+class _GUID(ctypes.Structure):
+    _fields_ = [
+        ("Data1", ctypes.c_uint32),
+        ("Data2", ctypes.c_uint16),
+        ("Data3", ctypes.c_uint16),
+        ("Data4", ctypes.c_ubyte * 8),
+    ]
+
+    @classmethod
+    def of(cls, d1, d2, d3, *d4):
+        return cls(d1, d2, d3, (ctypes.c_ubyte * 8)(*d4))
+
+
+_IID_IDXGIDevice = _GUID.of(0x54EC77FA, 0x1377, 0x44E6, 0x8C, 0x32, 0x88, 0xFD, 0x5F, 0x44, 0xC8, 0x4C)
+_IID_IDXGIOutput1 = _GUID.of(0x00CDDEA8, 0x939B, 0x4B83, 0xA3, 0x40, 0xA6, 0x85, 0x22, 0x66, 0x66, 0xCC)
+_IID_ID3D11Texture2D = _GUID.of(0x6F15AAF2, 0xD208, 0x4E89, 0x9A, 0xB4, 0x48, 0x95, 0x35, 0xD3, 0x4F, 0x9C)
+
+
+class _DXGI_OUTPUT_DESC(ctypes.Structure):
+    _fields_ = [
+        ("DeviceName", ctypes.c_wchar * 32),
+        ("DesktopCoordinates", wintypes.RECT),
+        ("AttachedToDesktop", wintypes.BOOL),
+        ("Rotation", _UINT),
+        ("Monitor", ctypes.c_void_p),
+    ]
+
+
+class _DXGI_OUTDUPL_POINTER_POSITION(ctypes.Structure):
+    _fields_ = [("Position", wintypes.POINT), ("Visible", wintypes.BOOL)]
+
+
+class _DXGI_OUTDUPL_FRAME_INFO(ctypes.Structure):
+    _fields_ = [
+        ("LastPresentTime", ctypes.c_int64),
+        ("LastMouseUpdateTime", ctypes.c_int64),
+        ("AccumulatedFrames", _UINT),
+        ("RectsCoalesced", wintypes.BOOL),
+        ("ProtectedContentMaskedOut", wintypes.BOOL),
+        ("PointerPosition", _DXGI_OUTDUPL_POINTER_POSITION),
+        ("TotalMetadataBufferSize", _UINT),
+        ("PointerShapeBufferSize", _UINT),
+    ]
+
+
+class _DXGI_SAMPLE_DESC(ctypes.Structure):
+    _fields_ = [("Count", _UINT), ("Quality", _UINT)]
+
+
+class _D3D11_TEXTURE2D_DESC(ctypes.Structure):
+    _fields_ = [
+        ("Width", _UINT),
+        ("Height", _UINT),
+        ("MipLevels", _UINT),
+        ("ArraySize", _UINT),
+        ("Format", _UINT),
+        ("SampleDesc", _DXGI_SAMPLE_DESC),
+        ("Usage", _UINT),
+        ("BindFlags", _UINT),
+        ("CPUAccessFlags", _UINT),
+        ("MiscFlags", _UINT),
+    ]
+
+
+class _D3D11_MAPPED_SUBRESOURCE(ctypes.Structure):
+    _fields_ = [("pData", ctypes.c_void_p), ("RowPitch", _UINT), ("DepthPitch", _UINT)]
+
+
+def _method(com_ptr, slot: int, *argtypes, restype=_HRESULT):
+    """Bind vtable slot `slot` of a COM interface pointer as a callable."""
+    vtable = ctypes.cast(com_ptr, ctypes.POINTER(ctypes.POINTER(ctypes.c_void_p))).contents
+    proto = ctypes.WINFUNCTYPE(restype, ctypes.c_void_p, *argtypes)
+    return proto(vtable[slot])
+
+
+def _release(com_ptr) -> None:
+    if com_ptr:
+        _method(com_ptr, 2, restype=ctypes.c_ulong)(com_ptr)  # IUnknown::Release
+
+
+def _query_interface(com_ptr, iid: _GUID):
+    out = ctypes.c_void_p()
+    hr = _method(com_ptr, 0, ctypes.POINTER(_GUID), ctypes.POINTER(ctypes.c_void_p))(
+        com_ptr, ctypes.byref(iid), ctypes.byref(out)
+    )
+    if hr < 0:
+        raise OSError(f"QueryInterface failed: {hr:#x}")
+    return out
+
+
+# Vtable slots (fixed by the header declaration order):
+# IDXGIObject: 0-2 IUnknown, 3-5 private data, 6 GetParent.
+_SLOT_GETPARENT = 6
+# IDXGIDevice: 7 GetAdapter.
+_SLOT_DEVICE_GETADAPTER = 7
+# IDXGIAdapter: 7 EnumOutputs.
+_SLOT_ADAPTER_ENUMOUTPUTS = 7
+# IDXGIOutput: 7 GetDesc (then 8-18); IDXGIOutput1 adds 19-21, 22 DuplicateOutput.
+_SLOT_OUTPUT_GETDESC = 7
+_SLOT_OUTPUT1_DUPLICATEOUTPUT = 22
+# IDXGIOutputDuplication: 8 AcquireNextFrame, 14 ReleaseFrame.
+_SLOT_DUPL_ACQUIRENEXTFRAME = 8
+_SLOT_DUPL_RELEASEFRAME = 14
+# ID3D11Device: 5 CreateTexture2D.
+_SLOT_D3D_CREATETEXTURE2D = 5
+# ID3D11DeviceContext (after 0-6 ID3D11DeviceChild): 14 Map, 15 Unmap, 47 CopyResource.
+_SLOT_CTX_MAP = 14
+_SLOT_CTX_UNMAP = 15
+_SLOT_CTX_COPYRESOURCE = 47
+# ID3D11Texture2D: 10 GetDesc (0-2 IUnknown, 3-6 DeviceChild, 7-9 Resource).
+_SLOT_TEX_GETDESC = 10
+
+
+class DesktopDuplication:
+    """One duplicated output (the primary monitor), grabbed on demand."""
+
+    def __init__(self, device, context, duplication, staging, width: int, height: int) -> None:
+        self._device = device
+        self._context = context
+        self._duplication = duplication
+        self._staging = staging
+        self._width = width
+        self._height = height
+        self._last_image: QImage | None = None
+
+    @classmethod
+    def create(cls) -> "DesktopDuplication | None":
+        if sys.platform != "win32":
+            return None
+        device = context = dxgi_device = adapter = output = duplication = None
+        try:
+            d3d11 = ctypes.windll.d3d11
+            device = ctypes.c_void_p()
+            context = ctypes.c_void_p()
+            hr = d3d11.D3D11CreateDevice(
+                None, _D3D_DRIVER_TYPE_HARDWARE, None, 0, None, 0,
+                _D3D11_SDK_VERSION, ctypes.byref(device), None, ctypes.byref(context),
+            )
+            if hr < 0:
+                raise OSError(f"D3D11CreateDevice failed: {hr:#x}")
+            dxgi_device = _query_interface(device, _IID_IDXGIDevice)
+            adapter = ctypes.c_void_p()
+            hr = _method(dxgi_device, _SLOT_DEVICE_GETADAPTER, ctypes.POINTER(ctypes.c_void_p))(
+                dxgi_device, ctypes.byref(adapter)
+            )
+            if hr < 0:
+                raise OSError(f"GetAdapter failed: {hr:#x}")
+            output, desc = cls._primary_output(adapter)
+            if desc.Rotation not in (_DXGI_MODE_ROTATION_UNSPECIFIED, _DXGI_MODE_ROTATION_IDENTITY):
+                raise OSError(f"display rotation {desc.Rotation} not supported")
+            output1 = _query_interface(output, _IID_IDXGIOutput1)
+            try:
+                duplication = ctypes.c_void_p()
+                hr = _method(
+                    output1, _SLOT_OUTPUT1_DUPLICATEOUTPUT,
+                    ctypes.c_void_p, ctypes.POINTER(ctypes.c_void_p),
+                )(output1, device, ctypes.byref(duplication))
+                if hr < 0:
+                    raise OSError(f"DuplicateOutput failed: {hr:#x}")
+            finally:
+                _release(output1)
+            width = desc.DesktopCoordinates.right - desc.DesktopCoordinates.left
+            height = desc.DesktopCoordinates.bottom - desc.DesktopCoordinates.top
+            staging = cls._create_staging(device, width, height)
+            _log.info("DXGI desktop duplication active (%dx%d)", width, height)
+            return cls(device, context, duplication, staging, width, height)
+        except OSError as error:
+            _log.info("DXGI desktop duplication unavailable (%s) — using grabWindow", error)
+            for com_ptr in (duplication, output, adapter, dxgi_device, context, device):
+                _release(com_ptr)
+            return None
+
+    @staticmethod
+    def _primary_output(adapter):
+        """The output whose desktop rect starts at (0, 0) — the primary —
+        or the first attached output if none does."""
+        first = None
+        index = 0
+        while True:
+            output = ctypes.c_void_p()
+            hr = _method(
+                adapter, _SLOT_ADAPTER_ENUMOUTPUTS, _UINT, ctypes.POINTER(ctypes.c_void_p)
+            )(adapter, index, ctypes.byref(output))
+            if hr < 0 or not output:
+                break
+            desc = _DXGI_OUTPUT_DESC()
+            hr = _method(output, _SLOT_OUTPUT_GETDESC, ctypes.POINTER(_DXGI_OUTPUT_DESC))(
+                output, ctypes.byref(desc)
+            )
+            if hr >= 0 and desc.AttachedToDesktop:
+                if desc.DesktopCoordinates.left == 0 and desc.DesktopCoordinates.top == 0:
+                    if first is not None:
+                        _release(first[0])
+                    return output, desc
+                if first is None:
+                    first = (output, desc)
+                    index += 1
+                    continue
+            _release(output)
+            index += 1
+        if first is None:
+            raise OSError("no attached DXGI output")
+        return first
+
+    @staticmethod
+    def _create_staging(device, width: int, height: int):
+        desc = _D3D11_TEXTURE2D_DESC()
+        desc.Width = width
+        desc.Height = height
+        desc.MipLevels = 1
+        desc.ArraySize = 1
+        desc.Format = 87  # DXGI_FORMAT_B8G8R8A8_UNORM: the duplication format
+        desc.SampleDesc.Count = 1
+        desc.Usage = _D3D11_USAGE_STAGING
+        desc.CPUAccessFlags = _D3D11_CPU_ACCESS_READ
+        staging = ctypes.c_void_p()
+        hr = _method(
+            device, _SLOT_D3D_CREATETEXTURE2D,
+            ctypes.POINTER(_D3D11_TEXTURE2D_DESC), ctypes.c_void_p,
+            ctypes.POINTER(ctypes.c_void_p),
+        )(device, ctypes.byref(desc), None, ctypes.byref(staging))
+        if hr < 0:
+            raise OSError(f"CreateTexture2D (staging) failed: {hr:#x}")
+        return staging
+
+    def grab(self) -> QImage | None:
+        """The current desktop; the previous QImage object if unchanged;
+        None if the duplication is lost (close() and re-create() later)."""
+        frame_info = _DXGI_OUTDUPL_FRAME_INFO()
+        resource = ctypes.c_void_p()
+        hr = _method(
+            self._duplication, _SLOT_DUPL_ACQUIRENEXTFRAME,
+            _UINT, ctypes.POINTER(_DXGI_OUTDUPL_FRAME_INFO), ctypes.POINTER(ctypes.c_void_p),
+        )(self._duplication, 0, ctypes.byref(frame_info), ctypes.byref(resource))
+        if hr == DXGI_ERROR_WAIT_TIMEOUT:
+            # Nothing changed since the last acquired frame.
+            return self._last_image if self._last_image is not None else None
+        if hr < 0:
+            if hr != DXGI_ERROR_ACCESS_LOST:
+                _log.warning("AcquireNextFrame failed: %#x — dropping DXGI capture", hr & 0xFFFFFFFF)
+            return None
+        try:
+            texture = _query_interface(resource, _IID_ID3D11Texture2D)
+            try:
+                _method(
+                    self._context, _SLOT_CTX_COPYRESOURCE,
+                    ctypes.c_void_p, ctypes.c_void_p, restype=None,
+                )(self._context, self._staging, texture)
+            finally:
+                _release(texture)
+        except OSError:
+            _release(resource)
+            _method(self._duplication, _SLOT_DUPL_RELEASEFRAME)(self._duplication)
+            return None
+        _release(resource)
+        _method(self._duplication, _SLOT_DUPL_RELEASEFRAME)(self._duplication)
+
+        mapped = _D3D11_MAPPED_SUBRESOURCE()
+        hr = _method(
+            self._context, _SLOT_CTX_MAP,
+            ctypes.c_void_p, _UINT, _UINT, _UINT, ctypes.POINTER(_D3D11_MAPPED_SUBRESOURCE),
+        )(self._context, self._staging, 0, _D3D11_MAP_READ, 0, ctypes.byref(mapped))
+        if hr < 0 or not mapped.pData:
+            _log.warning("Map (staging) failed: %#x — dropping DXGI capture", hr & 0xFFFFFFFF)
+            return None
+        try:
+            buffer = (ctypes.c_char * (mapped.RowPitch * self._height)).from_address(mapped.pData)
+            # .copy() both detaches from the mapped memory and tightens the
+            # row stride — the one CPU memcpy of the whole path.
+            image = QImage(
+                buffer, self._width, self._height, mapped.RowPitch, QImage.Format.Format_RGB32
+            ).copy()
+        finally:
+            _method(self._context, _SLOT_CTX_UNMAP, ctypes.c_void_p, _UINT, restype=None)(
+                self._context, self._staging, 0
+            )
+        self._last_image = image
+        return image
+
+    def close(self) -> None:
+        for attribute in ("_staging", "_duplication", "_context", "_device"):
+            _release(getattr(self, attribute))
+            setattr(self, attribute, None)
+        self._last_image = None

{remotedesktop-0.13.0 → remotedesktop-0.14.0}/src/remotedesktop/sharing.py

@@ -16,6 +16,7 @@ GUIs can show a debug log.
 import hmac
 import logging
 import socket as socket_module
+import time
 from collections.abc import Callable
 from typing import cast
 
@@ -38,7 +39,7 @@ from remotedesktop.config import (
     load_client_identity,
 )
 from remotedesktop.discovery import DEFAULT_CONNECT_PORT
-from remotedesktop import frames
+from remotedesktop import dxgi, frames
 from remotedesktop.input_injection import InputInjector
 from remotedesktop.performance import PerformanceMonitor
 from remotedesktop.protocol import MAX_PAYLOAD, PROTOCOL_VERSION, MessageStream
@@ -129,6 +130,12 @@ class ShareServer(QObject):
         self._delta_capable: set[MessageStream] = set()
         self._needs_keyframe: set[MessageStream] = set()
         self._previous_frame: QImage | None = None
+        # DXGI desktop duplication (~10 ms per changed 4K frame, ~0 when the
+        # screen is idle, vs ~96 ms for grabWindow). Created lazily on the
+        # first capture; None with a retry deadline while unavailable or
+        # lost (secure desktop, display-mode change) — grabWindow fills in.
+        self._dxgi: dxgi.DesktopDuplication | None = None
+        self._dxgi_retry_at = 0.0
 
         cert, key = credentials if credentials is not None else tls.ephemeral_credentials()
         self._server = QSslServer(self)
@@ -178,6 +185,9 @@ class ShareServer(QObject):
         self._delta_capable.clear()
         self._needs_keyframe.clear()
         self._previous_frame = None
+        if self._dxgi is not None:
+            self._dxgi.close()
+            self._dxgi = None
         if had_clients:
             self.clientCountChanged.emit(0)
         if self._performance is not None:
@@ -490,13 +500,40 @@ class ShareServer(QObject):
 
     def _capture(self) -> QImage | None:
         """Grab the primary screen at full resolution (tests override this
-        to drive deterministic frame content)."""
+        to drive deterministic frame content).
+
+        DXGI desktop duplication when it works — returning the *same QImage
+        object* as last time when the screen is unchanged — otherwise
+        grabWindow."""
+        image = self._capture_dxgi()
+        if image is not None:
+            return image
         screen = QGuiApplication.primaryScreen()
         if screen is None:
             return None
         image = screen.grabWindow(0).toImage()
         return None if image.isNull() else image
 
+    def _capture_dxgi(self) -> QImage | None:
+        now = time.monotonic()
+        if self._dxgi is None:
+            if now < self._dxgi_retry_at:
+                return None
+            self._dxgi = dxgi.DesktopDuplication.create()
+            if self._dxgi is None:
+                # Not available on this system/session; check again rarely.
+                self._dxgi_retry_at = now + 60.0
+                return None
+        image = self._dxgi.grab()
+        if image is None:
+            # Lost (secure desktop, display-mode change) or no frame yet;
+            # grabWindow covers the gap and we retry shortly.
+            self._dxgi.close()
+            self._dxgi = None
+            self._dxgi_retry_at = now + 2.0
+            _log.info("DXGI capture unavailable — using grabWindow until it recovers")
+        return image
+
     def _broadcast_frame(self) -> None:
         if not self._streams:
             return
@@ -504,13 +541,18 @@ class ShareServer(QObject):
         if image is None:
             self.status.emit("Screen capture failed (null image)")
             return
-        # bands is None when there is no comparable previous capture (first
-        # frame, or the resolution changed): everyone gets a full frame.
-        bands = (
-            frames.changed_bands(self._previous_frame, image)
-            if self._previous_frame is not None
-            else None
-        )
+        if image is self._previous_frame:
+            # DXGI reported no change since the last tick: skip the diff.
+            bands: list[tuple[int, int]] | None = []
+        else:
+            # bands is None when there is no comparable previous capture
+            # (first frame, or the resolution changed): everyone gets a
+            # full frame.
+            bands = (
+                frames.changed_bands(self._previous_frame, image)
+                if self._previous_frame is not None
+                else None
+            )
         self._previous_frame = image
         # Encode each variant at most once per tick, shared by all takers.
         legacy_jpeg: bytes | None = None

remotedesktop-0.14.0/tests/test_dxgi.py

@@ -0,0 +1,78 @@
+"""DXGI desktop-duplication capture and its grabWindow fallback in ShareServer.
+
+The real-hardware test skips wherever duplication is unavailable (headless
+CI runners, RDP sessions); the ShareServer wiring is tested with fakes so
+no real duplication is ever created there.
+"""
+
+import pytest
+from PySide6.QtGui import QGuiApplication, QImage
+
+from remotedesktop import dxgi
+
+from test_sharing import make_server
+
+
+def test_real_desktop_duplication_matches_screen_size(qapp):
+    duplication = dxgi.DesktopDuplication.create()
+    if duplication is None:
+        pytest.skip("DXGI desktop duplication unavailable in this session")
+    try:
+        image = duplication.grab()
+        if image is None:
+            pytest.skip("duplication lost before the first frame")
+        screen = QGuiApplication.primaryScreen()
+        expected = screen.size() * screen.devicePixelRatio()
+        assert (image.width(), image.height()) == (
+            round(expected.width()),
+            round(expected.height()),
+        )
+        # A second grab either reports "unchanged" (same object), delivers a
+        # new frame, or the duplication was lost — never anything else.
+        again = duplication.grab()
+        assert again is None or isinstance(again, QImage)
+    finally:
+        duplication.close()
+
+
+class FakeDuplication:
+    def __init__(self, images):
+        self.images = list(images)
+        self.closed = False
+
+    def grab(self):
+        return self.images.pop(0) if self.images else None
+
+    def close(self):
+        self.closed = True
+
+
+def test_capture_uses_dxgi_and_repeats_unchanged_frames(qapp, credentials, tmp_path, monkeypatch):
+    server = make_server(credentials, tmp_path, approve=lambda *_: True)
+    frame = QImage(4, 4, QImage.Format.Format_RGB32)
+    fake = FakeDuplication([frame, frame])
+    monkeypatch.setattr(dxgi.DesktopDuplication, "create", staticmethod(lambda: fake))
+    try:
+        assert server._capture() is frame
+        assert server._capture() is frame  # unchanged screen: same object again
+    finally:
+        server.close()
+    assert fake.closed  # server.close() releases the duplication
+
+
+def test_capture_dxgi_backs_off_after_loss(qapp, credentials, tmp_path, monkeypatch):
+    server = make_server(credentials, tmp_path, approve=lambda *_: True)
+    fake = FakeDuplication([])  # first grab returns None: lost immediately
+    created = []
+    monkeypatch.setattr(
+        dxgi.DesktopDuplication,
+        "create",
+        staticmethod(lambda: created.append(True) or fake),
+    )
+    try:
+        assert server._capture_dxgi() is None  # created, then lost -> closed
+        assert fake.closed
+        assert server._capture_dxgi() is None  # within the retry cooldown...
+        assert len(created) == 1  # ...so no re-create attempt yet
+    finally:
+        server.close()