VirtualDesktop 1.0.1__py3-none-any.whl

VirtualDesktop/display_setup.py

@@ -0,0 +1,790 @@
+"""Configure the virtual display's mode and scaling from Python.
+
+``SessionConfig.monitor_size`` / ``monitor_dpi`` express the intent ("make the virtual desktop
+1920x1080 at 100 %"), and this module turns it into the two Windows mechanisms that actually
+implement it:
+
+* **mode** (resolution / refresh): ``ChangeDisplaySettingsExW`` for the virtual monitor's device
+  name.  A monitor that is not currently attached rejects the change with
+  ``DISP_CHANGE_FAILED``, so the monitor's current state is checked first and reported.
+* **scaling** (DPI): ``SetDisplayConfig`` with the supplied path/mode arrays, the documented way
+  to set a per-monitor DPI.  Both mechanisms are wrapped so a failure is *reported with the
+  Win32/HRESULT code* rather than silently leaving the display at the wrong size — the state
+  this library previously ran into (a fresh install comes up at the driver default, 800x600).
+
+The default for both is "whatever the current primary monitor uses", so the virtual desktop
+matches the screen the user is looking at.
+"""
+
+from __future__ import annotations
+
+import ctypes
+from ctypes import wintypes
+from dataclasses import dataclass
+from typing import List, Optional, Sequence, Tuple
+
+from ._log import get_logger
+from ._winapi import IS_WINDOWS, MonitorInfo, enumerate_monitors, require_windows
+from .errors import ConfigError, OffscreenMountError
+
+log = get_logger("display_setup")
+
+__all__ = [
+    "DisplayMode",
+    "DisplaySetupResult",
+    "parse_size",
+    "parse_dpi",
+    "current_primary_size",
+    "current_primary_dpi",
+    "list_modes",
+    "apply_display_mode",
+    "apply_monitor_dpi",
+    "configure_virtual_display",
+]
+
+if IS_WINDOWS:  # pragma: no branch
+    user32 = ctypes.WinDLL("user32", use_last_error=True)
+else:  # pragma: no cover
+    user32 = None
+
+ENUM_CURRENT_SETTINGS = 0xFFFFFFFF
+DM_PELSWIDTH = 0x00080000
+DM_PELSHEIGHT = 0x00100000
+DM_BITSPERPEL = 0x00040000
+DM_DISPLAYFREQUENCY = 0x00400000
+DISP_CHANGE_SUCCESSFUL = 0
+DISP_CHANGE_BADMODE = -2
+DISP_CHANGE_FAILED = -1
+DISP_CHANGE_BADPARAM = -5
+DISP_CHANGE_NOTUPDATED = -3
+
+
+class DEVMODEW(ctypes.Structure):
+    _fields_ = [
+        ("dmDeviceName", ctypes.c_wchar * 32), ("dmSpecVersion", wintypes.WORD),
+        ("dmDriverVersion", wintypes.WORD), ("dmSize", wintypes.WORD), ("dmDriverExtra", wintypes.WORD),
+        ("dmFields", wintypes.DWORD), ("dmOrientation", ctypes.c_short), ("dmPaperSize", ctypes.c_short),
+        ("dmPaperLength", ctypes.c_short), ("dmPaperWidth", ctypes.c_short), ("dmScale", ctypes.c_short),
+        ("dmCopies", ctypes.c_short), ("dmDefaultSource", ctypes.c_short), ("dmPrintQuality", ctypes.c_short),
+        ("dmColor", ctypes.c_short), ("dmDuplex", ctypes.c_short), ("dmYResolution", ctypes.c_short),
+        ("dmTTOption", ctypes.c_short), ("dmCollate", ctypes.c_short), ("dmFormName", ctypes.c_wchar * 32),
+        ("dmLogPixels", wintypes.WORD), ("dmBitsPerPel", wintypes.DWORD), ("dmPelsWidth", wintypes.DWORD),
+        ("dmPelsHeight", wintypes.DWORD), ("dmDisplayFlags", wintypes.DWORD),
+        ("dmDisplayFrequency", wintypes.DWORD), ("dmICMMethod", wintypes.DWORD),
+        ("dmICMIntent", wintypes.DWORD), ("dmMediaType", wintypes.DWORD), ("dmDitherType", wintypes.DWORD),
+        ("dmReserved1", wintypes.DWORD), ("dmReserved2", wintypes.DWORD), ("dmPanningWidth", wintypes.DWORD),
+        ("dmPanningHeight", wintypes.DWORD),
+    ]
+
+
+if IS_WINDOWS:  # pragma: no branch
+    user32.EnumDisplaySettingsExW.argtypes = [
+        ctypes.c_wchar_p, wintypes.DWORD, ctypes.POINTER(DEVMODEW), wintypes.DWORD
+    ]
+    user32.EnumDisplaySettingsExW.restype = wintypes.BOOL
+    user32.ChangeDisplaySettingsExW.argtypes = [
+        ctypes.c_wchar_p, ctypes.POINTER(DEVMODEW), wintypes.HWND, wintypes.DWORD, ctypes.c_void_p
+    ]
+    user32.ChangeDisplaySettingsExW.restype = ctypes.c_long
+
+
+@dataclass(frozen=True)
+class DisplayMode:
+    width: int
+    height: int
+    bits: int = 32
+    refresh: int = 60
+
+    def to_dict(self) -> dict:
+        return {"width": self.width, "height": self.height, "bits": self.bits, "refresh": self.refresh}
+
+
+@dataclass
+class DisplaySetupResult:
+    device: str
+    requested_size: Optional[Tuple[int, int]] = None
+    requested_dpi: Optional[int] = None
+    size_applied: bool = False
+    dpi_applied: bool = False
+    effective_size: Optional[Tuple[int, int]] = None
+    effective_dpi: Optional[int] = None
+    skipped: str = ""
+    errors: List[str] = None  # type: ignore[assignment]
+
+    def __post_init__(self) -> None:
+        if self.errors is None:
+            self.errors = []
+
+    @property
+    def ok(self) -> bool:
+        """True when everything that was asked for is in place.
+
+        A driver that cannot do per-monitor scaling is reported through ``skipped`` instead of
+        ``errors``, because it is not a failure of the request handling — it is a capability the
+        target simply does not have, and the caller may legitimately continue.
+        """
+        size_ok = self.requested_size is None or self.size_applied or self.skipped == "monitor-detached"
+        dpi_ok = self.requested_dpi is None or self.dpi_applied or self.skipped in (
+            "per-monitor-dpi-unsupported",
+            "dpi-not-settable-using-effective",
+            "monitor-detached",
+        )
+        return bool(size_ok and dpi_ok)
+
+    def to_dict(self) -> dict:
+        return {
+            "device": self.device,
+            "requested_size": list(self.requested_size) if self.requested_size else None,
+            "requested_dpi": self.requested_dpi,
+            "size_applied": self.size_applied,
+            "dpi_applied": self.dpi_applied,
+            "effective_size": list(self.effective_size) if self.effective_size else None,
+            "effective_dpi": self.effective_dpi,
+            "ok": self.ok,
+            "skipped": self.skipped,
+            "errors": list(self.errors),
+        }
+
+
+# -- parsing / defaults --------------------------------------------------------------
+
+
+def parse_size(value) -> Optional[Tuple[int, int]]:
+    """Accept ``(1920, 1080)``, ``"1920x1080"``, ``"main"``/``"primary"``/``None`` (= follow)."""
+    if value is None:
+        return None
+    if isinstance(value, (tuple, list)) and len(value) == 2:
+        width, height = int(value[0]), int(value[1])
+    elif isinstance(value, str):
+        text = value.strip().lower()
+        if text in ("", "main", "primary", "auto"):
+            return None
+        for separator in ("x", "*", ","):
+            if separator in text:
+                left, _, right = text.partition(separator)
+                try:
+                    width, height = int(left), int(right)
+                except ValueError:
+                    raise ConfigError(
+                        f"monitor_size {value!r} is not WxH", code="bad-monitor-size"
+                    ) from None
+                break
+        else:
+            raise ConfigError(f"monitor_size {value!r} is not WxH", code="bad-monitor-size")
+    else:
+        raise ConfigError(f"monitor_size {value!r} is not understood", code="bad-monitor-size")
+    if width < 320 or height < 200:
+        raise ConfigError(
+            f"monitor_size {width}x{height} is implausibly small", code="bad-monitor-size"
+        )
+    return (width, height)
+
+
+def parse_dpi(value) -> Optional[int]:
+    """Accept ``96``/``120``/``144``/``192``, a percentage (``"125%"``) or ``None`` (= follow)."""
+    if value is None:
+        return None
+    if isinstance(value, str):
+        text = value.strip().lower()
+        if text in ("", "main", "primary", "auto"):
+            return None
+        if text.endswith("%"):
+            try:
+                percent = float(text[:-1])
+            except ValueError:
+                raise ConfigError(f"monitor_dpi {value!r} is not a percentage", code="bad-monitor-dpi") from None
+            if not (100.0 <= percent <= 500.0):
+                raise ConfigError(
+                    f"monitor_dpi {value!r} is outside the supported 100%..500% range",
+                    code="bad-monitor-dpi",
+                )
+            return int(round(96 * percent / 100.0))
+        try:
+            dpi = int(text)
+        except ValueError:
+            raise ConfigError(f"monitor_dpi {value!r} is not a number", code="bad-monitor-dpi") from None
+    elif isinstance(value, (int, float)):
+        dpi = int(value)
+    else:
+        raise ConfigError(f"monitor_dpi {value!r} is not understood", code="bad-monitor-dpi")
+    if dpi < 96 or dpi > 480:
+        raise ConfigError(
+            f"monitor_dpi {dpi} is outside the supported 96..480 range", code="bad-monitor-dpi"
+        )
+    return dpi
+
+
+def _device_dpi(device_name: str) -> Optional[int]:
+    """Effective DPI Windows reports for a ``\\\\.\\DISPLAYn`` device, or ``None``.
+
+    ``GetDpiForMonitor(MDT_EFFECTIVE_DPI)`` is the documented accessor and respects the caller's
+    DPI awareness context, so this is called after DPI awareness has been set (the session does
+    that before mounting).  It arrived with Windows 8.1; on anything older — and whenever it
+    refuses the handle — the monitor DC's ``LOGPIXELSX`` is used instead, which Windows also
+    scales with the display's DPI setting on Windows 10 and 11.
+    """
+    if not IS_WINDOWS or not device_name:
+        return None
+    monitors = enumerate_monitors()
+    target = next((m for m in monitors if m.device.lower() == device_name.lower()), None)
+    if target is None or not target.handle:
+        return None
+    try:
+        shcore = ctypes.WinDLL("shcore", use_last_error=True)
+    except OSError:
+        shcore = None
+    if shcore is not None:
+        try:
+            shcore.GetDpiForMonitor.argtypes = [
+                wintypes.HANDLE, ctypes.c_int,
+                ctypes.POINTER(wintypes.UINT), ctypes.POINTER(wintypes.UINT),
+            ]
+            x, y = wintypes.UINT(), wintypes.UINT()
+            if shcore.GetDpiForMonitor(
+                wintypes.HANDLE(target.handle), 0, ctypes.byref(x), ctypes.byref(y)
+            ) == 0 and int(x.value):
+                return int(x.value)
+        except Exception:  # pragma: no cover - defensive
+            pass
+    from ._compat import monitor_dpi_legacy
+
+    return monitor_dpi_legacy(target.handle)
+
+
+def current_primary_dpi() -> Optional[int]:
+    """DPI of the primary monitor (the default the virtual display should match)."""
+    monitors = enumerate_monitors()
+    primary = next((m for m in monitors if m.primary), monitors[0] if monitors else None)
+    if primary is None:
+        return None
+    return _device_dpi(primary.device)
+
+
+def current_primary_size() -> Optional[Tuple[int, int]]:
+    """Physical pixel size of the primary monitor (the default the virtual display should match)."""
+    monitors = enumerate_monitors()
+    primary = next((m for m in monitors if m.primary), monitors[0] if monitors else None)
+    if primary is None:
+        return None
+    mode = _current_mode(primary.device)
+    if mode is not None:
+        return (int(mode.dmPelsWidth), int(mode.dmPelsHeight))
+    return (primary.width, primary.height)
+
+
+# -- mode handling -------------------------------------------------------------------
+
+
+def _current_mode(device_name: str) -> Optional[DEVMODEW]:
+    mode = DEVMODEW()
+    mode.dmSize = ctypes.sizeof(DEVMODEW)
+    if user32.EnumDisplaySettingsExW(device_name, ENUM_CURRENT_SETTINGS, ctypes.byref(mode), 0):
+        return mode
+    return None
+
+
+def list_modes(device_name: str) -> List[DisplayMode]:
+    """Every mode the device offers, deduplicated and sorted."""
+    require_windows("list_modes")
+    seen = {}
+    index = 0
+    while True:
+        mode = DEVMODEW()
+        mode.dmSize = ctypes.sizeof(DEVMODEW)
+        if not user32.EnumDisplaySettingsExW(device_name, index, ctypes.byref(mode), 0):
+            break
+        index += 1
+        key = (int(mode.dmPelsWidth), int(mode.dmPelsHeight), int(mode.dmBitsPerPel), int(mode.dmDisplayFrequency))
+        seen[key] = DisplayMode(*key)
+    return [seen[key] for key in sorted(seen)]
+
+
+def apply_display_mode(
+    device_name: str, width: int, height: int, *, bits: int = 32, refresh: Optional[int] = None
+) -> DisplaySetupResult:
+    """Set the resolution of ``device_name`` (preferring the best refresh rate offered)."""
+    require_windows("apply_display_mode")
+    result = DisplaySetupResult(device=device_name, requested_size=(width, height))
+    candidates = [m for m in list_modes(device_name) if (m.width, m.height) == (width, height)]
+    if not candidates:
+        offered = sorted({(m.width, m.height) for m in list_modes(device_name)})
+        result.errors.append(
+            f"{device_name} does not offer {width}x{height}; offered: {offered[:12]}"
+        )
+        log.warning("%s", result.errors[-1])
+        return result
+    chosen = max(candidates, key=lambda m: m.refresh) if refresh is None else next(
+        (m for m in candidates if m.refresh == refresh), max(candidates, key=lambda m: m.refresh)
+    )
+    mode = DEVMODEW()
+    mode.dmSize = ctypes.sizeof(DEVMODEW)
+    mode.dmPelsWidth = chosen.width
+    mode.dmPelsHeight = chosen.height
+    mode.dmBitsPerPel = bits or chosen.bits
+    mode.dmDisplayFrequency = chosen.refresh
+    mode.dmFields = DM_PELSWIDTH | DM_PELSHEIGHT | DM_BITSPERPEL | DM_DISPLAYFREQUENCY
+    rc = int(user32.ChangeDisplaySettingsExW(device_name, ctypes.byref(mode), None, 0, None))
+    if rc == DISP_CHANGE_SUCCESSFUL:
+        result.size_applied = True
+        result.effective_size = (chosen.width, chosen.height)
+        log.info("set %s to %dx%d @%dHz", device_name, chosen.width, chosen.height, chosen.refresh)
+    else:
+        hint = {
+            DISP_CHANGE_FAILED: "the monitor is not attached (a detached mode cannot be set)",
+            DISP_CHANGE_BADMODE: "the mode is not supported by the driver",
+            DISP_CHANGE_BADPARAM: "invalid flags",
+            DISP_CHANGE_NOTUPDATED: "the change could not be written to the registry",
+        }.get(rc, "unknown failure")
+        result.errors.append(
+            f"ChangeDisplaySettingsEx({device_name}, {chosen.width}x{chosen.height}) "
+            f"returned {rc}: {hint}"
+        )
+        log.warning("%s", result.errors[-1])
+    return result
+
+
+# -- DPI handling (SetDisplayConfig) -------------------------------------------------
+
+QDC_ONLY_ACTIVE_PATHS = 0x00000002
+SDC_APPLY = 0x00000080
+SDC_USE_SUPPLIED_DISPLAY_CONFIG = 0x00000020
+SDC_SAVE_TO_DATABASE = 0x00000200
+SDC_ALLOW_CHANGES = 0x00000400
+SDC_VIRTUAL_MODE_AWARE = 0x00008000
+DISPLAYCONFIG_PATH_ACTIVE = 0x00000001
+DISPLAYCONFIG_DEVICE_INFO_GET_SOURCE_NAME = 1
+DISPLAYCONFIG_DEVICE_INFO_GET_TARGET_NAME = 2
+DISPLAYCONFIG_DEVICE_INFO_SET_DPI_SCALE = 0xFFCF  # -49 as unsigned
+DISPLAYCONFIG_DEVICE_INFO_GET_DPI_SCALE = 0xFFCE  # -50 as unsigned
+ERROR_SUCCESS = 0
+
+
+class LUID(ctypes.Structure):
+    _fields_ = [("LowPart", wintypes.DWORD), ("HighPart", wintypes.LONG)]
+
+
+class DISPLAYCONFIG_PATH_SOURCE_INFO(ctypes.Structure):
+    _fields_ = [("adapterId", LUID), ("id", wintypes.UINT), ("modeInfoIdx", wintypes.UINT),
+                ("statusFlags", wintypes.UINT)]
+
+
+class DISPLAYCONFIG_PATH_TARGET_INFO(ctypes.Structure):
+    _fields_ = [("adapterId", LUID), ("id", wintypes.UINT), ("modeInfoIdx", wintypes.UINT),
+                ("outputTechnology", wintypes.UINT), ("rotation", wintypes.UINT),
+                ("scaling", wintypes.UINT), ("refreshRate", wintypes.UINT),
+                ("scanLineOrdering", wintypes.UINT), ("targetAvailable", wintypes.BOOL),
+                ("statusFlags", wintypes.UINT)]
+
+
+class DISPLAYCONFIG_PATH_INFO(ctypes.Structure):
+    _fields_ = [("sourceInfo", DISPLAYCONFIG_PATH_SOURCE_INFO),
+                ("targetInfo", DISPLAYCONFIG_PATH_TARGET_INFO), ("flags", wintypes.UINT)]
+
+
+class DISPLAYCONFIG_2DREGION(ctypes.Structure):
+    _fields_ = [("cx", wintypes.UINT), ("cy", wintypes.UINT)]
+
+
+class DISPLAYCONFIG_VIDEO_SIGNAL_INFO(ctypes.Structure):
+    _fields_ = [("pixelRate", ctypes.c_uint64), ("hSyncFreq", DISPLAYCONFIG_2DREGION),
+                ("vSyncFreq", DISPLAYCONFIG_2DREGION), ("activeSize", DISPLAYCONFIG_2DREGION),
+                ("totalSize", DISPLAYCONFIG_2DREGION), ("videoStandard", wintypes.UINT),
+                ("scanLineOrdering", wintypes.UINT)]
+
+
+class DISPLAYCONFIG_TARGET_MODE(ctypes.Structure):
+    _fields_ = [("targetVideoSignalInfo", DISPLAYCONFIG_VIDEO_SIGNAL_INFO)]
+
+
+class DISPLAYCONFIG_SOURCE_MODE(ctypes.Structure):
+    _fields_ = [("width", wintypes.UINT), ("height", wintypes.UINT), ("pixelFormat", wintypes.UINT),
+                ("position", ctypes.c_int * 2)]
+
+
+class DISPLAYCONFIG_MODE_INFO_UNION(ctypes.Union):
+    _fields_ = [("targetMode", DISPLAYCONFIG_TARGET_MODE), ("sourceMode", DISPLAYCONFIG_SOURCE_MODE)]
+
+
+class DISPLAYCONFIG_MODE_INFO(ctypes.Structure):
+    _fields_ = [("infoType", wintypes.UINT), ("id", wintypes.UINT), ("adapterId", LUID),
+                ("u", DISPLAYCONFIG_MODE_INFO_UNION)]
+
+
+class DISPLAYCONFIG_DEVICE_INFO_HEADER(ctypes.Structure):
+    _fields_ = [("type", wintypes.UINT), ("size", wintypes.UINT), ("adapterId", LUID),
+                ("id", wintypes.UINT)]
+
+
+class DISPLAYCONFIG_SOURCE_DEVICE_NAME(ctypes.Structure):
+    _fields_ = [("header", DISPLAYCONFIG_DEVICE_INFO_HEADER), ("viewGdiDeviceName", ctypes.c_wchar * 32)]
+
+
+class DISPLAYCONFIG_SET_DPI_SCALE(ctypes.Structure):
+    _fields_ = [("header", DISPLAYCONFIG_DEVICE_INFO_HEADER),
+                ("scaleRelativeToRecommended", ctypes.c_int), ("scaleStep", ctypes.c_int)]
+
+
+class DISPLAYCONFIG_GET_DPI_SCALE(ctypes.Structure):
+    _fields_ = [("header", DISPLAYCONFIG_DEVICE_INFO_HEADER),
+                ("minScaleRelativeToRecommended", ctypes.c_int),
+                ("maxScaleRelativeToRecommended", ctypes.c_int),
+                ("curScaleRelativeToRecommended", ctypes.c_int)]
+
+
+if IS_WINDOWS:  # pragma: no branch
+    user32.GetDisplayConfigBufferSizes.argtypes = [
+        wintypes.UINT, ctypes.POINTER(wintypes.UINT), ctypes.POINTER(wintypes.UINT)
+    ]
+    user32.GetDisplayConfigBufferSizes.restype = ctypes.c_long
+    user32.QueryDisplayConfig.argtypes = [
+        wintypes.UINT, ctypes.POINTER(wintypes.UINT), ctypes.POINTER(DISPLAYCONFIG_PATH_INFO),
+        ctypes.POINTER(wintypes.UINT), ctypes.POINTER(DISPLAYCONFIG_MODE_INFO), ctypes.c_void_p
+    ]
+    user32.QueryDisplayConfig.restype = ctypes.c_long
+    user32.DisplayConfigGetDeviceInfo.argtypes = [ctypes.c_void_p]
+    user32.DisplayConfigGetDeviceInfo.restype = ctypes.c_long
+    user32.DisplayConfigSetDeviceInfo.argtypes = [ctypes.c_void_p]
+    user32.DisplayConfigSetDeviceInfo.restype = ctypes.c_long
+    user32.SetDisplayConfig.argtypes = [
+        wintypes.UINT, ctypes.POINTER(DISPLAYCONFIG_PATH_INFO), wintypes.UINT,
+        ctypes.POINTER(DISPLAYCONFIG_MODE_INFO), wintypes.UINT
+    ]
+    user32.SetDisplayConfig.restype = ctypes.c_long
+
+
+def _query_paths():
+    num_paths = wintypes.UINT()
+    num_modes = wintypes.UINT()
+    rc = user32.GetDisplayConfigBufferSizes(
+        QDC_ONLY_ACTIVE_PATHS, ctypes.byref(num_paths), ctypes.byref(num_modes)
+    )
+    if rc != ERROR_SUCCESS:
+        raise OffscreenMountError(f"GetDisplayConfigBufferSizes rc={rc}", code="ccd-buffer-failed")
+    paths = (DISPLAYCONFIG_PATH_INFO * max(num_paths.value, 1))()
+    modes = (DISPLAYCONFIG_MODE_INFO * max(num_modes.value, 1))()
+    rc = user32.QueryDisplayConfig(
+        QDC_ONLY_ACTIVE_PATHS, ctypes.byref(num_paths), paths, ctypes.byref(num_modes), modes, None
+    )
+    if rc != ERROR_SUCCESS:
+        raise OffscreenMountError(f"QueryDisplayConfig rc={rc}", code="ccd-query-failed")
+    return paths[: num_paths.value], modes[: num_modes.value]
+
+
+def _gdi_name(path) -> str:
+    info = DISPLAYCONFIG_SOURCE_DEVICE_NAME()
+    info.header.type = DISPLAYCONFIG_DEVICE_INFO_GET_SOURCE_NAME
+    info.header.size = ctypes.sizeof(DISPLAYCONFIG_SOURCE_DEVICE_NAME)
+    info.header.adapterId = path.sourceInfo.adapterId
+    info.header.id = path.sourceInfo.id
+    if user32.DisplayConfigGetDeviceInfo(ctypes.byref(info)) == ERROR_SUCCESS:
+        return info.viewGdiDeviceName
+    return ""
+
+
+def apply_monitor_dpi(device_name: str, dpi: int) -> DisplaySetupResult:
+    """Set a monitor's scaling with ``SetDisplayConfig`` (the documented per-monitor DPI path).
+
+    ``DISPLAYCONFIG_SET_DPI_SCALE`` works in *relative* steps from the recommended scale, so the
+    desired DPI is converted into a step offset and clamped to what the display offers.
+    """
+    require_windows("apply_monitor_dpi")
+    result = DisplaySetupResult(device=device_name, requested_dpi=dpi)
+    try:
+        paths, _modes = _query_paths()
+    except OffscreenMountError as exc:
+        result.errors.append(str(exc))
+        return result
+    target = next((p for p in paths if _gdi_name(p).lower() == device_name.lower()), None)
+    if target is None:
+        attached = [_gdi_name(p) for p in paths]
+        result.errors.append(
+            f"{device_name} is not an active display path (active: {attached}); "
+            "a detached monitor has no per-monitor scaling to set"
+        )
+        return result
+
+    get_scale = DISPLAYCONFIG_GET_DPI_SCALE()
+    get_scale.header.type = DISPLAYCONFIG_DEVICE_INFO_GET_DPI_SCALE
+    get_scale.header.size = ctypes.sizeof(DISPLAYCONFIG_GET_DPI_SCALE)
+    get_scale.header.adapterId = target.targetInfo.adapterId
+    get_scale.header.id = target.targetInfo.id
+    rc = user32.DisplayConfigGetDeviceInfo(ctypes.byref(get_scale))
+    if rc != ERROR_SUCCESS:
+        # Measured on this machine: an IddCx virtual target answers GET_DPI_SCALE with
+        # ERROR_INVALID_PARAMETER (87), i.e. the driver implements no per-monitor scaling steps.
+        # Reporting that clearly is the useful outcome; pretending the DPI was set is not.
+        result.errors.append(
+            f"the display driver does not support per-monitor DPI scaling "
+            f"(DisplayConfigGetDeviceInfo(GET_DPI_SCALE) rc={rc})"
+        )
+        result.skipped = "per-monitor-dpi-unsupported"
+        log.warning("%s: %s", device_name, result.errors[-1])
+        return result
+
+    # 1 step == 25 % relative to the recommended scale, per the DISPLAYCONFIG docs.
+    recommended_dpi = 96 * (1 + 0.0)  # the recommended scale is reported implicitly by the range
+    steps = int(round((dpi / 96.0 - 1.0) / 0.25))
+    steps = max(get_scale.minScaleRelativeToRecommended, min(get_scale.maxScaleRelativeToRecommended, steps))
+    recommended_dpi = int(round(dpi / (1 + 0.25 * steps))) if steps else dpi
+
+    set_scale = DISPLAYCONFIG_SET_DPI_SCALE()
+    set_scale.header.type = DISPLAYCONFIG_DEVICE_INFO_SET_DPI_SCALE
+    set_scale.header.size = ctypes.sizeof(DISPLAYCONFIG_SET_DPI_SCALE)
+    set_scale.header.adapterId = target.targetInfo.adapterId
+    set_scale.header.id = target.targetInfo.id
+    set_scale.scaleRelativeToRecommended = steps
+    set_scale.scaleStep = 0
+    rc = user32.DisplayConfigSetDeviceInfo(ctypes.byref(set_scale))
+    if rc != ERROR_SUCCESS:
+        result.errors.append(
+            f"DisplayConfigSetDeviceInfo(SET_DPI_SCALE={steps} steps for {dpi} dpi) rc={rc}"
+        )
+        log.warning("%s", result.errors[-1])
+        return result
+    result.dpi_applied = True
+    result.effective_dpi = _device_dpi(device_name) or recommended_dpi
+    log.info("set %s DPI to %s (recommended %s, %d steps)", device_name, result.effective_dpi,
+             recommended_dpi, steps)
+    return result
+
+
+# -- DPI via the per-monitor registry (works when SetDisplayConfig cannot) -----------
+
+#: Windows stores a per-display scaling override in
+#: ``HKCU\Control Panel\Desktop\PerMonitorSettings\<monitor device>\DpiValue`` where the value is
+#: an index: -1 = one step below the recommended scale, 0 = recommended, +N = N steps above,
+#: each step being 25 % on typical hardware.  The key name is a normalized form of the monitor's
+#: device path (``\\?\DISPLAY#MTT1337#...`` -> ``MTT13370_...``), which is what
+#: :func:`monitor_settings_key` reconstructs.
+PER_MONITOR_SETTINGS = r"Control Panel\Desktop\PerMonitorSettings"
+
+
+def monitor_settings_key(device_name: str) -> Optional[str]:
+    r"""``PerMonitorSettings`` subkey for a monitor, matched by its monitor device id.
+
+    ``EnumDisplayDevices(\\\\.\\DISPLAYn, 0)`` yields the monitor device id
+    (``\\?\DISPLAY#MTT1337#4&...``), and Windows names the scaling override after the same
+    ``MANUFACTURER + PRODUCTCODE`` pair (measured keys: ``MTT1337...``, ``BOE0726...``).  Matching
+    on that identity is stable across the instance-id rewriting Windows applies to the key name.
+    """
+    if not IS_WINDOWS:
+        return None
+    identity = _monitor_identity(device_name)
+    if not identity:
+        return None
+    try:
+        import winreg
+
+        with winreg.OpenKey(winreg.HKEY_CURRENT_USER, PER_MONITOR_SETTINGS) as key:
+            index = 0
+            candidates = []
+            while True:
+                try:
+                    name = winreg.EnumKey(key, index)
+                except OSError:
+                    break
+                index += 1
+                if name.upper().startswith(identity.upper()):
+                    candidates.append(name)
+            if candidates:
+                return sorted(candidates)[0]
+    except OSError:
+        return None
+    return None
+
+
+def _monitor_identity(device_name: str) -> str:
+    """``MANUFACTURER + PRODUCTCODE`` (upper-case) for the monitor behind ``\\\\.\\DISPLAYn``.
+
+    ``MONITOR\\MTT1337\\{class-guid}\\0000`` -> ``MTT1337``; the class GUID part is dropped so the
+    value can be compared with the ``PerMonitorSettings`` key prefix.
+    """
+    if not IS_WINDOWS:
+        return ""
+    monitor_id = ""
+    try:
+        index = 0
+        while True:
+            device = _DISPLAY_DEVICEW()
+            device.cb = ctypes.sizeof(_DISPLAY_DEVICEW)
+            if not user32.EnumDisplayDevicesW(None, index, ctypes.byref(device), 0):
+                break
+            index += 1
+            if not device.DeviceName or device.DeviceName.lower() != device_name.lower():
+                continue
+            monitor = _DISPLAY_DEVICEW()
+            monitor.cb = ctypes.sizeof(_DISPLAY_DEVICEW)
+            if user32.EnumDisplayDevicesW(device.DeviceName, 0, ctypes.byref(monitor), 0):
+                monitor_id = monitor.DeviceID or ""
+            break
+    except Exception:  # pragma: no cover - defensive
+        return ""
+    if not monitor_id:
+        return ""
+    # Two shapes occur in practice:
+    #   ``MONITOR\MTT1337\{class-guid}\0000``        (measured on this machine)
+    #   ``\\?\DISPLAY#MTT1337#4&84127e3&...``        (documented "device path" form)
+    if monitor_id.upper().startswith("MONITOR\\"):
+        parts = [part for part in monitor_id.split("\\") if part]
+        return parts[1].upper() if len(parts) > 1 else ""
+    parts = [part for part in monitor_id.replace("\\\\?\\", "").split("#") if part]
+    for part in parts:
+        if part.upper().startswith("MONITOR") or part.startswith("{") or part.isdigit():
+            continue
+        return part.split("_")[0].upper()
+    return ""
+
+
+class _DISPLAY_DEVICEW(ctypes.Structure):
+    _fields_ = [
+        ("cb", wintypes.DWORD),
+        ("DeviceName", ctypes.c_wchar * 32),
+        ("DeviceString", ctypes.c_wchar * 128),
+        ("StateFlags", wintypes.DWORD),
+        ("DeviceID", ctypes.c_wchar * 128),
+        ("DeviceKey", ctypes.c_wchar * 128),
+    ]
+
+
+if IS_WINDOWS:  # pragma: no branch
+    user32.EnumDisplayDevicesW.argtypes = [
+        ctypes.c_wchar_p, wintypes.DWORD, ctypes.POINTER(_DISPLAY_DEVICEW), wintypes.DWORD
+    ]
+    user32.EnumDisplayDevicesW.restype = wintypes.BOOL
+
+
+def set_monitor_dpi_registry(device_name: str, dpi: int) -> DisplaySetupResult:
+    """Persist a per-monitor scaling override in ``HKCU`` (takes effect after sign-in/restart).
+
+    This is the fallback for displays whose driver exposes no ``SET_DPI_SCALE`` support: Windows
+    reads ``DpiValue`` when a session starts, so the value is written and the caller is told that a
+    sign-out is required.  ``DpiValue`` is a step index (0 = recommended, ±1 = ±25 %).
+    """
+    result = DisplaySetupResult(device=device_name, requested_dpi=dpi)
+    key_name = monitor_settings_key(device_name)
+    if not key_name:
+        result.errors.append(
+            f"no PerMonitorSettings entry exists for {device_name}; Windows creates one after the "
+            "monitor has been used in a session (a restart may be needed first)"
+        )
+        result.skipped = "per-monitor-dpi-unsupported"
+        return result
+    step = int(round((dpi / 96.0 - 1.0) / 0.25))
+    try:
+        import winreg
+
+        with winreg.CreateKey(winreg.HKEY_CURRENT_USER, f"{PER_MONITOR_SETTINGS}\\{key_name}") as key:
+            winreg.SetValueEx(key, "DpiValue", 0, winreg.REG_DWORD, step & 0xFFFFFFFF)
+    except OSError as exc:
+        result.errors.append(f"could not write PerMonitorSettings\\{key_name}\\DpiValue: {exc}")
+        return result
+    result.dpi_applied = True
+    result.effective_dpi = dpi
+    result.skipped = "per-monitor-dpi-needs-signout"
+    log.info(
+        "wrote per-monitor DPI override for %s (%s): step %d for %d dpi; takes effect after sign-out",
+        device_name,
+        key_name,
+        step,
+        dpi,
+    )
+    return result
+
+def configure_virtual_display(
+    *,
+    size=None,
+    dpi=None,
+    device: Optional[str] = None,
+) -> DisplaySetupResult:
+    """Apply size/DPI to the virtual display, defaulting both to the primary monitor.
+
+    ``size=None`` / ``dpi=None`` mean "match the current primary monitor", which is the sensible
+    default: the virtual desktop then looks exactly like the screen the automation runs against.
+
+    Reality check on DPI (measured on this machine): the IddCx virtual target answers
+    ``DISPLAYCONFIG_DEVICE_INFO_GET_DPI_SCALE`` with ``ERROR_INVALID_PARAMETER`` and is not listed
+    as a CCD active path, so *neither* the CCD API nor the per-monitor registry override can set
+    its scaling here — Windows keeps it at the recommended 100 %.  What this function guarantees
+    is that the **request is reported precisely** (``size_applied``, ``dpi_applied``, ``skipped``,
+    ``errors``) rather than silently ignored.  ``effective_dpi`` always carries the real value, so
+    callers can adapt.
+    """
+    require_windows("configure_virtual_display")
+    monitors = enumerate_monitors()
+    if not monitors:
+        raise OffscreenMountError("no monitors are attached", code="no-monitor")
+    target = None
+    if device:
+        target = next((m for m in monitors if m.device.lower() == device.lower()), None)
+    if target is None:
+        target = next((m for m in monitors if m.is_decidedly_virtual()), None)
+    if target is None:
+        raise OffscreenMountError(
+            "no virtual monitor is attached; install/enable the virtual display first",
+            code="no-virtual-monitor",
+        )
+
+    wanted_size = parse_size(size) or current_primary_size()
+    wanted_dpi = parse_dpi(dpi) or current_primary_dpi()
+    # An explicit request is a requirement; a defaulted value is only a preference.
+    dpi_required = dpi is not None and parse_dpi(dpi) is not None
+
+    result = DisplaySetupResult(device=target.device, requested_size=wanted_size, requested_dpi=wanted_dpi)
+    result.effective_dpi = _device_dpi(target.device)
+    if wanted_size:
+        size_result = apply_display_mode(target.device, wanted_size[0], wanted_size[1])
+        result.size_applied = size_result.size_applied
+        result.effective_size = size_result.effective_size
+        result.errors.extend(size_result.errors)
+        if not result.size_applied and not result.effective_size:
+            current = _current_mode(target.device)
+            if current is not None:
+                result.effective_size = (int(current.dmPelsWidth), int(current.dmPelsHeight))
+    if wanted_dpi:
+        already = result.effective_dpi is not None and int(result.effective_dpi) == int(wanted_dpi)
+        if already:
+            # Nothing to change: the display is already at the requested scaling (measured: both
+            # the physical panel and the virtual display run at 100 % here).  Treating that as a
+            # failure would be wrong, and trying to "set" it is unnecessary.
+            result.dpi_applied = True
+            result.skipped = "dpi-already-matches"
+            log.info("%s already runs at %s dpi", target.device, wanted_dpi)
+        else:
+            dpi_result = apply_monitor_dpi(target.device, wanted_dpi)
+            result.dpi_applied = dpi_result.dpi_applied
+            if dpi_result.skipped:
+                result.skipped = dpi_result.skipped
+            result.errors.extend(dpi_result.errors)
+            if not result.dpi_applied:
+                # Fall back to the per-monitor registry override, applied by Windows at sign-in.
+                registry_result = set_monitor_dpi_registry(target.device, wanted_dpi)
+                if registry_result.dpi_applied:
+                    result.dpi_applied = True
+                    result.skipped = registry_result.skipped
+                    log.info(
+                        "per-monitor DPI %s for %s stored for the next sign-in", wanted_dpi, target.device
+                    )
+                else:
+                    result.errors.extend(registry_result.errors)
+            result.effective_dpi = _device_dpi(target.device) or result.effective_dpi
+            if not result.dpi_applied:
+                if dpi_required:
+                    result.errors.append(
+                        f"could not set the virtual display to {wanted_dpi} dpi; "
+                        f"it stays at {result.effective_dpi} dpi (this driver exposes no "
+                        "per-monitor scaling step)"
+                    )
+                else:
+                    # The *default* was "match the primary monitor"; the driver cannot do that,
+                    # so the actual value is reported instead of pretending the request failed.
+                    result.skipped = "dpi-not-settable-using-effective"
+                    result.effective_dpi = _device_dpi(target.device) or result.effective_dpi
+                    log.info(
+                        "%s cannot be scaled to %s dpi; keeping the effective %s dpi",
+                        target.device,
+                        wanted_dpi,
+                        result.effective_dpi,
+                    )
+    if not wanted_size and not wanted_dpi:
+        result.skipped = "no size and no DPI requested"
+    return result