Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions CLAUDE.md
Original file line number Diff line number Diff line change
Expand Up @@ -18,6 +18,7 @@ are frozen history cited from code, not kept in step with it.
- `build.bat installer`: NSIS setup (needs `winget install NSIS.NSIS`), then `tools\installer_check.ps1`.
- `pwsh -File tools\release.ps1`: release installer into `dist\` (what CI runs).
- UI tests: `npx playwright test` in `ui/` (run when anything under `ui/` changes).
- `tools\testenv\run.ps1` falls back to a virtual primary when the TV is off; `matrix.ps1` proves other screen setups. See `tools\testenv\README.md`.
- `pwsh -File tools\check_copyright.ps1`: CI gate; every new source file needs the copyright/SPDX header. See 11.

## Stack and map
Expand Down
8 changes: 8 additions & 0 deletions docs/architecture/11-build-test-release.md
Original file line number Diff line number Diff line change
Expand Up @@ -115,6 +115,14 @@ upstream notices), generated files (`flyout_palettes.h`, `themes.css`, `themes.j
file goes in the script's exclusion lists. The binaries carry the same notice as `LegalCopyright`
(`src/wind.rc`, `src/tray_app/wind_tray.rc`, `installer/wind.nsi`).

## Testing on other displays

The proving ground can run on virtual screens (Virtual Display Driver), so it works with the TV off and
across resolutions, refresh rates, scales and a second monitor. `run.ps1 -Display` picks the screen and
`matrix.ps1` runs a list of setups. The screen is made primary because the transform engine only
magnifies the primary (`src/engine/engine_pick.h`). Virtual runs are health-only unless the setup has its own
baseline; the TV stays the reference for smoothness and latency. See `tools/testenv/README.md`.

## Local UIAccess deploy

UIAccess is needed for the input-transform publish (transform on the desktop), binds over
Expand Down
61 changes: 61 additions & 0 deletions tools/testenv/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -92,13 +92,72 @@ Rules and limits:
- External spec JSON (ZoomText etc.): name, exe, procNames, zoomInVks/zoomOutVks (the chord),
startWaitMs. The external program is left running afterwards (it was likely there first).

## Displays: TV, virtual screens and the matrix

The suite needs a live display: with the TV off or asleep, DWM drops to about 13 Hz and every
timing is noise. `run.ps1 -Display` decides what to do about it:

| `-Display` | What happens |
|---|---|
| `auto` (default) | TV on: run on it as always. TV off or asleep: a virtual screen becomes primary for the run, if the driver is installed; otherwise the old abort (exit 4) |
| `virtual` | Always a virtual primary. Set it with `-DisplayMode WxH@Hz,scale` (default `3840x2160@120,100`) and `-VirtualCount 2` for a second screen |
| `tv` | Never switch |

pwsh -File tools\testenv\matrix.ps1 # rapid across 6 setups, about 8 min
pwsh -File tools\testenv\matrix.ps1 -Only 1080p,dual
pwsh -File tools\testenv\display.ps1 -List
pwsh -File tools\testenv\display.ps1 -Restore # after a crashed run

The virtual screen must be primary because the transform engine magnifies the primary monitor only.
The layout is saved to `results/display-layout.json` before any change and restored after each run.
If the TV is still off at that point, the virtual screen stays and the snapshot is kept: run `-Restore`
when the TV is back. Virtual monitors are detached from the desktop between runs.

**Idle state (#571).** The virtual screen stays plugged in, so Windows falls back to it whenever the TV
is switched off. Idle, it matches the TV: 3840x2160, 144 Hz (60 Hz if the driver does not offer 144),
225 % scale and one monitor. Windows then keeps the same logical desktop (1707x960), so windows keep
their size. Tests may change it while they run. `Restore-DisplayLayout` (the end of every `run.ps1`
virtual run, also on failure and on the pending path), `matrix.ps1` and `display.ps1 -Restore` put it back.
The values live in `$script:VirtualIdle` in `display.ps1`.

pwsh -File tools\testenv\display.ps1 -Idle -DryRun # what would change; changes nothing
pwsh -File tools\testenv\display.ps1 -Idle # apply it now
pwsh -File tools\testenv\display.ps1 -SelfTest # checks of the idle-state logic

Mode and scale can only be set while the virtual screen is on the desktop. Windows stores the scale
relative to the screen's recommended scale at that resolution (`DpiValue` under
`HKCU\Control Panel\Desktop\PerMonitorSettings\MTT1337...`), so the function sets it through the same
call as Settings and never writes that value by hand. Windows also remembers the mode it last used for
the "virtual screen only" layout. Run `-Idle` once while the TV is off (or let a nightly run end on the
pending path) to replace an old 1366x768 entry.

Setup, once per PC, as admin: `winget install VirtualDrivers.Virtual-Display-Driver`, then `devcon install`
of the package's `SignedDrivers\x86\VDD\MttVDD.inf` with hardware id `Root\MttVDD`. Create
`C:\VirtualDisplayDriver\vdd_settings.xml` first, with `<friendlyname>` set to the GPU Wind renders on,
and list the modes the matrix uses. List **3840x2160 first** with `<refresh_rate>144</refresh_rate>`:
the driver offers the first `<resolution>` as the preferred mode, which Windows uses when it falls back
to a screen it has no saved mode for. Keep 144 among the `<g_refresh_rate>` values, which the driver
adds to every resolution. The driver reads the file when it loads, so a change applies at the next
reload (a count change through the pipe, a reboot, or disabling and enabling the device).
Monitors appear with `MTT1337` in their device path.

What a virtual run proves: Wind starts, picks the right engine, zooms, stays within the cap and leaves
no stranded state on that resolution, refresh rate, scale and monitor count. It does not prove
smoothness or latency, so **virtual screens are health-only**: the absolute timing limits are calibrated
on the 144 Hz TV and do not apply. Nor is HDR covered. While the TV is on and attached as a secondary, DWM
still composes at its rate, so `hz` in the results is the screen's mode, not the pace measured.

## Baselines and CI

`baselines.json` stores per-scenario PASS numbers from the dev machine (`-UpdateBaseline`). `-CI`
compares with tolerance (1.6x + slack) and exits nonzero on regression. Absolute floors
(dtP99 > 25 ms, jitP95 > 25 px, backSteps in a non-rezoom scenario) catch catastrophes even
without a baseline.

The top-level numbers are the TV's. Each virtual screen keeps its own under
`profiles.<WxH@Hz,scale>`, so a virtual run is never judged against TV numbers; one without a baseline is
health-only until `-UpdateBaseline`. Record them with the TV off, so the screen paces itself.

GitHub-hosted runners cannot run this (no real GPU/display for Desktop Duplication or the
Magnification API), so the push-to-main story is local: `hooks/pre-push.sample` (reminder
gate) and `register_nightly.ps1` (scheduled full run on the dev machine).
Expand All @@ -108,6 +167,8 @@ gate) and `register_nightly.ps1` (scheduled full run on the dev machine).
| File | What it is |
|---|---|
| `run.ps1` | Orchestrator: suites (rapid, quick, full, soak, stress), scenarios, health checks, verdicts, JSON |
| `display.ps1` | Virtual screens: attach, make primary, set mode and scale, snapshot and restore the layout |
| `matrix.ps1` | Runs one suite across a list of virtual display setups, with one summary table |
| `bench.ps1` | Cross-magnifier benchmark: scoreboard and `results/catalog.csv` history |
| `lib.ps1` | Shared interop (injection, tones, Wind lifecycle, backdrops) and telemetry analysis |
| `backdrop.ps1` | One backdrop window per child process |
Expand Down
Loading
Loading