HDR
After this page you will know which of the three ranges to pick, what headroom each one produces, and why this feature is the most likely to break on a macOS update.
Last updated 22 August 2026
A virtual display can be created standard, high dynamic range, or in reference mode. The choice lives on the display, not on the group, because it is a property of the display the way its resolution is.
The three ranges
macOS reports how much range a display has above diffuse white as its headroom: the maximum extended dynamic range value it will accept before clipping.
| Range | Headroom | What it is |
|---|---|---|
| Standard | 1.0 | An ordinary display. Diffuse white and nothing above it. |
| High | 5.0 | What an HDR-capable panel reports, and what video and image pipelines look for. |
| Reference | 10.0 | The Pro Display XDR behaviour: the same headroom doubled, plus a reference value saying the display is calibrated to it rather than merely capable of it. |
Standard unless you ask for something else. HDR is not free: macOS composites an HDR display differently, and a display claiming headroom it is never given content for costs power for nothing.
What it is for on a machine nobody is looking at
Two real reasons, and if neither is yours, leave it standard.
Making software behave the way it will on the real panel. An application in its HDR state takes a different path from the same application in standard range. If the remote machine reports standard range, the session is not representative of the room the output will be seen in.
Delivering HDR frames to a client that can decode them. Without HDR on the display there is nothing HDR to send.
Why the app measures rather than trusts
There is no HDR switch in the private interface. There is no property called hdr, EDR,
maxEDR or dynamicRange on any of the classes involved. What there is, found by probing, is a
transfer function on the display mode and a reference flag on the descriptor.
The framework accepts every value for that transfer function without complaint, and creates a working display for each. Only one of them produces headroom. A successful call therefore proves nothing at all, and the only test that means anything is reading the headroom back afterwards.
make smoke
creating 3840x2160 virtual display, dynamic range: high
display 0x4d440001 active, unmirrored, 3840x2160
headroom 5.0 (expected 5.0)
released
smoke: okSo the smoke test asserts the headroom, not the return value. A macOS release that renumbers the values shows up as a failing smoke test rather than as a display that quietly is not HDR.
Measuring it yourself
The headroom is NSScreen’s maximum potential extended dynamic range value. One quirk worth
knowing: the process that created the display does not see it in its own NSScreen list yet, so it
has to be read from a second process. That is why the smoke test is a separate program.
| Capability | macOS | State | Why |
|---|---|---|---|
| Standard range | 14.0 and later | Available | The default. Nothing special is asked of the interface. |
| High dynamic range | Measured on 26.5 | Partial | Reachable, and confirmed by measuring the headroom rather than by a successful call. Not a documented interface, so any release may change it. |
| Reference mode | Measured on 26.5 | Partial | The reference flag does nothing on its own, and doubles the headroom to 10.0 with a matching reference value when combined with HDR. |
| Colour profile assignment | any | Unavailable | Not a feature. Displays use the system's default colour handling. |
Next
- Refresh rates for the other half of what a display advertises.
- Virtual displays for the size and scale it applies to.