[maxdavidson]

What and why

A Switch 2 game asks vi::QueryDisplayHdrStatus for the display's HDR state. The host answered SDR, so the game never made its HDR10 window (RGB10A2, PQ in BT.2020). With this change, on the Mac and iOS:

• The status query answers HDR while the window's screen can show EDR, and SDR elsewhere, where the game draws its own SDR picture. The game asks every frame, so moving the window switches it. The HDR row (DM_HDR) is on by default.
• The layer is RGB10A2 in BT.2100 PQ, and the game's HDR10 window goes into it as it is.
• The paper white is 100 nits by default. macOS shows a PQ layer at EDR = nits / 100, so 100 is the screen's own white: the game's normal picture matches SDR and the headroom is left to its highlights. 203 is offered and brightens the whole picture.
• The peak is automatic by default: 100 nits times the screen's current headroom, the brightest level the screen shows unchanged, so the game tone-maps into it.
• No HDR10 metadata on the layer by default (DM_HDR_META=1 adds it). With a range above the screen's headroom Core Animation compresses the whole picture, mid-tones included. In fullscreen, a layer with metadata of any range shows rectangles of older frames under GPU load, a macOS fault. A fixed peak above the screen's is rolled off in the present instead.
• MetalFX writes the drawable only when nothing is converted. MetalFX upscaling may write the drawable itself and skip the present pass; it does so only for an HDR10 source shown as stored with no roll-off, so the HDR conversions (HDR10 to SDR, an SDR or float source to PQ, the roll-off) still run.

The reference entries are in docs/reference/rendering.md (HDR output), and each game's findings are in its note. Built on beecrepaldi-afk's PQ layer, b1tdr3amer24's present after the GPU, and Amost's paper white and peak rows; they are co-authors of the commit.

Checked

• Tests: make -C dm/gfx/tests GAME=0400486024DEC000: t_present_hdr (53 checks), t_present_alloc, t_present_rescue --metal, t_present_snap (all six modes), t_present_crop; test_docs, test_settings, test_env_switches; dm/ios/tools/compile_check.py (263 files).
• Games run, with title ID and version: Ocarina of Time 0400486024DEC000 v131072, Mario Kart World 0400C3F00006E000 v0, Donkey Kong Bananza 040074A01BF12000 v458752. Compared: the windows each game makes and the ranges it declares, its pixels read back off-screen against the peak it was told, the paper white 100 and 203 against SDR by eye while the game ran, fullscreen with and without metadata, and a window moved between an HDR and an SDR screen.
• Devices and OS: MacBook Pro M4 Pro, macOS 26.7 and 27.2: its built-in XDR screen, an external HDR TV in macOS HDR mode and an SDR monitor. iPhone 17 Pro, iOS 27.2.1: Mario Kart World, by eye.
• Not checked: Donkey Kong Bananza played with the defaults, on the Mac or iOS; lint_c.py tidy and lint_python.py locally (CI runs them).
• Tests rerun on main with its MetalFX scaler ordering: the present tests above, t_dlss_mfx (32 checks), t_upscaler_mfx (12).
• regress.py check --runs 2 against main (DM_HDR unset, so the SDR path; Mac with an M1 Pro, macOS 27.2.1). Shaders identical in all five games (no MSL changed, none newly failing), no new red lines:
  • Super Mario Odyssey 0100000000010000: CHANGED, one screenshot moved within the baseline's noise (13.7 against 53.7); 59.5 fps both, recorded in validated.tsv.
  • Donkey Kong Bananza 040074A01BF12000: PASS, 59.6–59.7 fps both, 21,225 pipelines built (a provisional boot route, not committed; a build with derived shader tables, so not recorded).
  • Breath of the Wild 01007EF00011E000: fps flagged 36.3 → 32.4, within the baseline's own spread (36.3 and 31.4 against 32.0 and 32.4; p50 33.3 ms in all four).
  • Mario Kart World 0400C3F00006E000: fps flagged 57.2 → 50.6, within the baseline's own spread (57.2 and 33.9 against 50.2 and 50.6; the race differs every run).
  • Ocarina of Time 0400486024DEC000: not comparable, the baseline's pipeline prebuild reached its 1,200 s limit with a cold archive and the game did not start.
  • Odyssey, Breath of the Wild and Mario Kart World ran from stand-in saves (an empty one, a played save, a new build's), not their routes' reference saves.
• Not checked: a game with MetalFX upscaling and HDR on together.

Front ends

Front-ends: new: HDR output for Switch 2 games (DM_HDR, DM_HDR_PAPER_WHITE, DM_HDR_PEAK rows): the front end makes the HDR layer RGB10A2 in kCGColorSpaceITUR_2100_PQ with wantsExtendedDynamicRangeContent (front_mac.m, front_ios.m)
Front-ends: new: the HDR row defaults to on; the host's own default, DM_HDR unset, stays SDR, so a front end that does not pass the row's value starts the game in SDR
Front-ends: new: front_hdr_screen() (the window's screen can show EDR) and front_hdr_headroom() (its current EDR headroom) are weak hooks in hle_vi.c; without front_hdr_headroom the automatic peak answers 1000 and nothing is rolled off
Front-ends: new: a front end calls dm_hdr_layer_meta_set() with whether it gave the layer HDR10 metadata, and receives the game's declared range through front_hdr_content_range() for that metadata

Docs

• The finding is in its game note or its docs/reference/<subsystem>.md entry, and python3 dm/tools/docs_symptoms.py was run (the symptom index)
• No game files, keys or data extracted from a game in the change or the attachments

🤖 Generated with Claude Code

[Amost-]

Tested this branch on a screen with EDR headroom, which the description lists as untested.

Setup: MacBook Pro M2 Pro, built-in Liquid Retina XDR (potential headroom 16, about 1600 nits), macOS 27.2. Ocarina of Time (0400486024DEC000, v131072), the branch cherry-picked onto main 88c7e03 with #1331, #1447, #1462 and #1368.

Result: it works. Status answers HDR, format 1. The game switches its window from 0x25 to 0x3d and declares 0..203 / 0..710 nits; the PQ layer gets the HDR10 metadata. The title holds 60 fps with no new red line, and HDR looks right by eye. t_present_hdr 27/27.

How the game uses the two numbers (one relaunch each):

Host answer	Declared extended range
defaults (peak 1000, paper white 203)	0..710
DM_HDR_PEAK=1600	0..710
DM_HDR_PEAK=400	0..400
DM_HDR_PAPER_WHITE=300	0..1000

Ocarina declares min(peak, 3.5 × paper white). The paper white is what lifts its highlights; the default peak never limits it.

Testing gotcha: a window behind other windows reads a current headroom of 1.2 whatever it declares. In front, the same window reads 16 at low brightness and 3.2 at full brightness (1600 / 500 nits).

Calibration proposal, working locally on top of this branch (about 100 lines with tests and docs; happy to open a PR or share the patch):

1. Launcher rows under HDR output, drawn while it is on: HDR paper white (120–400 nits, default 203) and HDR peak (400–1600, default 1000), mapped to the existing switches. At the defaults the answers are unchanged.
2. Automatic peak (Mac): DM_HDR_PEAK=auto answers paper white × the screen's current EDR headroom, read beside the potential headroom the front end already polls. Rounded to 10 nits, never below the paper white, logged on change. With the window in front it followed the brightness slider both ways, and the game re-declared its range during play (0..710 → 0..650 → 0..710). On this panel the effect is small, at most 710 → 650 at full brightness; it should matter more on screens with less headroom (untested). iOS would need the same accessor from UIScreen.currentEDRHeadroom (not done).

Minor: the MetalFX present scaler running on PQ codes looked over-sharpened next to Standard (bilinear) with the 3D at full resolution. Subjective.

[b1tdr3amer24]

Found and worked around a fullscreen HDR flicker with this PR's PQ layer, in case it helps others.

Symptom: MacBook Pro M4 Pro, macOS 27.2, Ocarina of Time (v131072, oot2 fork + this PR), DM_HDR=1, fullscreen. When nothing covers the game's layer, big rectangles of older frames flicker on screen. Nothing covering it means the menu bar is hidden and no frame-rate counter is on. The intro movie looks like frames out of order. With the menu bar shown, or any view over the layer, it stops. SDR is clean. The host's own frame timing is clean throughout. It happens with ProMotion and at a fixed 60 Hz.

Reproduced outside the game: a ~300-line standalone Cocoa app reproduces it:

• CAMetalLayer, RGB10A2 with kCGColorSpaceITUR_2100_PQ and HDR10MetadataWithMinLuminance:0 maxLuminance:710 opticalOutputScale:100
• CAMetalDisplayLink at 60 Hz, frame latency 2
• the Metal 4 present as the host does it: waitForDrawable, commit, signalDrawable, present
• drawable sized to the view in pixels, and about 12 ms of GPU work per frame (a 1080p offscreen picture scaled into the drawable)

Without the GPU load, or with a drawable smaller than the screen, it did not reproduce.

What removed it (one change at a time):

• a classic presentDrawable: on an MTLCommandQueue
• an MTLCommandQueue that waits on a shared event and presents
• no EDR metadata
• an SDR layer
• an NSView over the layer
• calling present only after the command buffer's commit feedback reports completion

What did not: the RGBA16Float layer (DM_HDR_LAYER=float), which shows its own garbage blocks, like the M5 note in this PR. Frame latency 1, and the link on its own thread or the main thread, made no difference either.

On-screen times: presentedTime steps stayed 16.7 ms in every mode. In the flickering mode frames landed one refresh after the link's target; in the clean modes they landed on target.

Workaround: in present_now, present from the display command buffer's feedback handler, once both signalDrawable and GPU completion have happened. It is on by default for an extended-range layer, switch DM_PRESENT_AFTER_GPU=0/1. Since then there has been no flicker in fullscreen HDR at 60 Hz and with ProMotion. This looks like a macOS bug in Metal 4's drawable signalling for EDR layers that macOS shows directly, without compositing. Happy to share the test program or the commit.

[maxdavidson]

@Amost- and @b1tdr3amer24, please open up PRs toward this branch in https://github.com/maxdavidson/nxnative/tree/feat/switch2-hdr-output

[Amost-]

@Amost- and @b1tdr3amer24, please open up PRs toward this branch in https://github.com/maxdavidson/nxnative/tree/feat/switch2-hdr-output

hello, done

[Know-It-All-Brother]

This is needed to fix fullscreen HDR output on my Vizio 4k TV. Otherwise I have magenta aritficating near the top of the screen unless the menu bar is shown.

[Know-It-All-Brother]

Tested this on an M5 Max (macOS 27.0.1) with Ocarina of Time 0400486024DEC000 v131072, on an LG UltraFine with no EDR (potential headroom 1.00), using DM_HDR=2.

• It works. The status answers HDR, format 1. The game switches its window from 0x25 to 0x3d and declares 0..203 / 0..710 nits, the same as @Amost- saw. The PQ layer gets the metadata, and the picture looks fine in a window and in fullscreen. There's no new red line over the 200 s smoke route.
• In fullscreen the present after the GPU turned on as expected. On this fixed 60 Hz screen, every frame landed a refresh late. With DM_PRESENT_SHOWN=1, display-link target to on screen was p50 16.66 ms in fullscreen, against -0.02 ms in the window, over one 300-frame window. So at a fixed 60 Hz it's a frame of lag all the time, not just when the game drops below 60.
• This conflicts with main now, only in the Ocarina of Time README (I kept both sides). I merged main 7ffa63cc here: https://github.com/Know-It-All-Brother/nxnative/tree/hdr-output-main. t_present_hdr passes 27/27, t_present_crop 112/112 and t_present_alloc 13/13, and the Mac host builds.

I'm also suggesting tagging the SDR layer sRGB below. Right now it's untagged, so macOS shows it in the screen's own colour space. I haven't confirmed yet that it fixes the magenta band on my TV with HDR off.

[Know-It-All-Brother]

Tag the SDR layer as sRGB, which is what the game's SDR picture is. Untagged, macOS takes it as the screen's colour space. The HDR block below still sets its own colour space.

Suggested change

	g_layer.pixelFormat = MTLPixelFormatBGRA8Unorm;
	g_layer.pixelFormat = MTLPixelFormatBGRA8Unorm;
	{ CGColorSpaceRef srgb = CGColorSpaceCreateWithName(kCGColorSpaceSRGB); g_layer.colorspace = srgb; CGColorSpaceRelease(srgb); }

[maxdavidson]

I've left this line as it is: setting pixelFormat to BGRA8Unorm already tags the layer sRGB on macOS 27.2. A fresh CAMetalLayer has no color space, and after the pixel format is set it reads kCGColorSpaceSRGB. An extended-range screen capture (an LG C3 in macOS HDR mode, windowed) gives the same colors for this layer and an explicitly sRGB-tagged one: sRGB red reads 0.8223 0.0332 0.0171 in both. So the explicit tag wouldn't change the picture here.

If the magenta band still shows with HDR off on 27.0.1, could you log what g_layer.colorspace reads on your setup? If it comes back NULL there, the explicit tag is worth adding, and I'll take this suggestion.

— posted by Claude (Opus 5.5) on behalf of maxdavidson

[maxdavidson]

Thanks for testing on the M5 Max and the TVs, and for the timing.

The sRGB tag: setting a CAMetalLayer's pixelFormat to BGRA8Unorm already tags it sRGB on macOS 27.2: a fresh layer has no colour space, and after the pixel format is set it reads kCGColorSpaceSRGB. An extended-range screen capture in linear Display P3 (an LG C3 in macOS HDR mode, in a window) gives the same colours for the current SDR layer and an explicitly sRGB-tagged one, sRGB red reading 0.8223 0.0332 0.0171 in both, and the HDR layer's SDR encoding within 0.3 %, so the suggestion wouldn't change anything there. If the magenta band persists with HDR off on 27.0.1, could you check what g_layer.colorspace reads on your setup?

The frame a refresh late in fullscreen: the branch no longer puts HDR10 metadata on the layer by default. The rectangles came with the metadata, of any range, also in a standalone app, and without it there are none, so the present keeps Apple's order, which landed on time in our measurements; the present after the GPU now runs only in fullscreen with DM_HDR_META=1.

Defaults now: HDR output on (automatic: only on a screen that can show EDR), paper white 100, the peak automatic (100 nits times the screen's current headroom), on the Mac and iOS. On a screen without EDR the SDR picture goes out at the screen's white whatever the paper white.

Could you retest fullscreen HDR on the Vizio with the new build? The magenta artifacts near the top you saw without the menu bar are what I'd most like to know about: our fullscreen measurements were on a MacBook and an LG C3, not on your TV.