[Amost-]

What and why

The calibration follow-up from my test comment on seedds#1176 (seedds#1176 (comment)). The paper white and the peak that the status query answers (DM_HDR_PAPER_WHITE, DM_HDR_PEAK) had no launcher setting, though they are what a console's HDR calibration sets. Ocarina of Time shows that they matter: it declares min(peak, 3.5 × paper white), so the paper white is what lifts its highlights.

• HDR paper white (120–400 nits, default 203) and HDR peak (400–1600, default 1000): rows under HDR output, drawn while it is on, mapped to the existing switches. At the defaults the answers are unchanged. HDR output gets a one-line description and level=basic, so the two rows show with it.
• Automatic peak (Mac): DM_HDR_PEAK=auto answers the paper white × the window's screen's current EDR headroom (maximumExtendedDynamicRangeColorComponentValue, read beside the potential headroom the front end already polls four times a second). Rounded to 10 nits, never below the paper white, at most 16 bits, logged when it changes (at most once a second). iOS would need UIScreen.currentEDRHeadroom (not done), so the row offers Automatic on the Mac only.

Docs: docs/settings.md (the two rows), docs/env_switches.tsv (both switches are now player), a bullet in the HDR entry of docs/reference/rendering.md, and Ocarina of Time's HDR note.

Checked

• Tests: t_present_hdr 34/34, with 7 new checks for the peak (a number; auto at headroom 3.5, 16, 1, 0.5, NaN and 1000; auto on a screen without EDR). test_settings.py 5/5, including a new test that the rows are Switch 2 only, sub-settings of HDR output, with Automatic on the Mac only. test_docs passes. test_env_switches fails only on DM_NVN_BC_ALIAS and three switches quoted only in the docs, the same as on ec134cc without this change. The host builds (make -C dm/host GAME=0400486024DEC000 dmhost), and the clang-tidy ratchet on the four changed C/ObjC files is 0 above and 0 below the baseline.
• Games run: Ocarina of Time (0400486024DEC000, v131072), with this change on the build from my comment (host/vi: HDR output for Switch 2 games on screens that can show EDR seedds/nxnative#1176 cherry-picked onto main 88c7e03 with Scale decoded NDVE movies on Metal and skip matched reconstruction seedds/nxnative#1331, Ocarina of Time (Switch 2): GPU-written texture ranges fix the terrain holes; opt-in texture release saves ~2.3 GB; a page on playing it seedds/nxnative#1447, Restore six Ocarina foliage libraries with Ampere CAS and record M3 Pro validation seedds/nxnative#1462 and Ocarina of Time: prewarm native mesh pipelines before attacks and enemies appear seedds/nxnative#1368). That covers the four relaunches in the comment's table, plus Automatic with the window in front. It followed the brightness slider both ways (3250, 2470, 650, 1360, 2300 nits), and the game declared its range again during play (0..710 → 0..650 → 0..710). A host built from this exact branch was not played.
• Devices and OS: MacBook Pro M2 Pro, built-in Liquid Retina XDR (potential headroom 16), macOS 27.2. Screens with less headroom, where Automatic should matter more, and iOS are untested.
• regress.py not run: only the HDR status answer and the settings rows change, and only with HDR output on.

Front ends

Front-ends: new: DM_HDR_PEAK=auto reads the weak front_hdr_headroom() (the window's screen's current EDR headroom; front_mac.m defines it). A front end without it answers the paper white for auto.

Docs

• The finding is in Ocarina of Time's game note and the rendering.md HDR entry (no Symptom line changed, so the symptom index stays as it is; test_docs passes)
• No game files, keys or data extracted from a game in the change

This merges cleanly with #2 except in Ocarina of Time's README, where both add a bullet at the end of the HDR output section: keep both. Happy to rebase after #2 lands.

🤖 Generated with Claude Code

[maxdavidson]

Thanks for the launcher rows and the Automatic peak, and for the measurements on the M2 Pro. Your work is in seedds#1176, in its single commit, with you as a co-author. That pull request is now one squashed commit on current main, so this one can't be merged here, and I'm closing it.

What changed on top of it, from measurements on a MacBook Pro M4 Pro's XDR screen and an LG C3 TV (macOS 27.2):

1. Automatic is 100 nits times the headroom, not the paper white times it. An extended-range screen capture shows macOS displaying a PQ layer at EDR = nits / 100, so 100 x headroom is the highest level the screen shows unchanged; the paper white times it was always above that, and Core Animation compressed the whole picture. The answer moves in steps of about 6 % and only once a step has held for a second, because the headroom ramps from about 1.2 when the layer appears.
2. Automatic is the default peak, and 100 nits the default paper white, on the Mac and iOS (iOS now reads UIScreen.currentEDRHeadroom). Switching while the game ran, Mario Kart World at 100 had SDR's base brightness with brighter highlights; at 203 the whole picture was brighter. 100 is now the row's first option; 203 and the others stay.
3. No HDR10 metadata on the layer by default. In fullscreen a layer with metadata of any range showed rectangles of older frames under GPU load, also in a standalone app; without it, none. A fixed peak above the screen's is rolled off in the present shader instead.

Your headroom readings (16 at low brightness, 3.2 at full) are in the reference entry, credited to this PR. If the M2 Pro shows something different with the new defaults, a follow-up is welcome.