[Windows] Support output to HDR monitors

[DarkKilauea]

Implements: godotengine/godot-proposals#10817 for Windows.

Overview

This PR enables the ability for Godot to output to HDR capable displays on Windows. This allows Godot to output brighter images than allowed in SDR mode and with more vibrant colors.

HDR output is implemented using Extended Dynamic Range (EDR), which is a technique that preserves the SDR range (of 0 to 1) while extending the upper range to include brighter values, up to the maximum brightness of the display. This approach preserves the shadows and darker areas of the scene while allowing highlights to reach much brighter values.

It also allows for 2D content take advantage of HDR displays by producing brighter colors that have a value over 1.0, without having to opt into tonemapping and the effects pipeline. 2D and 3D content can also be mixed in the same scene while keeping a consistent brightness between the two, based on a shared "reference" luminance.

Testing/Sample projects:

1. https://github.com/DarkKilauea/godot-hdr-output
2. https://github.com/allenwp/godot-hdr-output-test-project
3. [WIP Draft] The HDR mega-PR #110701 This PR combined with other related PRs

Examples (converted to SDR to work on all browsers):

SDR	HDR

Examples (HDR images, may not display correctly on all browsers):

SDR	HDR

Supported Platforms:

• Windows

Supported Graphics APIs:

• D3D12
• Vulkan (not supported on Windows, but included in this PR for use with other platforms)

Supported HDR Formats:

• scRGB (Linear 16-bit color)

Supported Tonemappers:

• Linear
• Reinhard
• AgX

Features:

• Request a HDR capable swap chain for a window at runtime
• Automatic luminance adjustment for each window
• Automatic switching between HDR and SDR output as OS settings change or as the window moves between monitors
• Opt-in manual control of luminance output for each window
• Editor automatically updates to use HDR when changed in project settings

Limitations:

• Enabling HDR output on Windows requires Godot to use the D3D rendering driver.
• Only the Linear, Reinhard, and AgX tonemappers extend into the additional headroom of the display. This is due to the Flimic and ACES being designed for SDR displays. Updating them to output to an HDR range is not trivial.
• The default tone map when previewing 3D scenes has been disabled since the default of Flimic is not suitable for HDR preview, and its settings weren't a great fit for SDR scenes either.
• HDR output requires viewports to enable hdr_2d to output the additional dynamic range needed for HDR displays. Blending may look different when hdr_2d is enabled. hdr_2d will automatically be enabled for windows that turn on HDR output, which may result in a change in appearance of the scene. It's advised that applications planning to support HDR output create their content with hdr_2d enabled, even when HDR output is disabled.
• The compatibility rendering method is not supported, due to it targeting lower end devices that may not support the extensions required for OpenGL to output to HDR capable swap chains.

Follow up work:

• Support for Android: [Android] Support HDR output #101977
• Support for Wayland: [LinuxBSD] Add support for HDR output (Wayland) #102987
• Support for Apple platforms with Metal: Apple: Support output to EDR (HDR) displays #106814
• Add support for more tonemappers: [WIP Prototype] Add HDR support to tonemappers #106696 and Add white, contrast, and future HDR support to the AgX tonemapper. #106940
• Write official docs going over creating content for HDR displays and how to enable HDR output: [DRAFT] Add HDR output manual page godot-docs#11548
• Create a official demo showing how to implement HDR output: [DRAFT] Add HDR output demo godot-demo-projects#1287

Trackers:

• [TRACKER] HDR output enhancements godot-proposals#13750
• [TRACKER] HDR output issues & PRs #113959

Getting Started

Project Settings

1. Enable display/window/hdr/enabled (you may need to enable Advanced Settings first):
2. Optional (but recommended): Enable rendering/viewport/hdr_2d:
3. Adjust the environment of your 3D scenes to use Linear, Reinhard, or AgX as the tonemapper:

Runtime

1. First, we can enable HDR output on our current window (checking for HDR support is optional, but can be useful for displaying HDR settings in menus):

var window := get_window();
window.hdr_output_requested = true;

2. Adjust the environment of your 3D scenes to use Linear, Reinhard, or AgX as the tonemapper:

Help Needed

Please give this a test, either with the linked sample project or with your own projects, and give feedback. Specifically I'm looking for input on how easy this feature was to use and if you encountered any issues with your particular display, OS, or driver configuration.

Remaining Work / Issues

• Warning when enabling HDR 2D without HDR output: [Windows] Support output to HDR monitors #94496 (comment)
• Request HDR Output does not always force HDR 2D on: [Windows] Support output to HDR monitors #94496 (comment)
• [Steam Deck OLED] HDR does not match SDR brightness (likely needs to be resolved by Valve): [Windows] Support output to HDR monitors #94496 (comment)
• Better error handling for Windows emulators that don't report SDRWhiteLevel: [Windows] Support output to HDR monitors #94496 (comment)
• Update this PR description text
  • This description should mention the 3D workspace now disables tonemapping for its default Environment. This comment should be linked to provide rationale: [Windows] Support output to HDR monitors #94496 (comment)

[Calinou]

I gave this a quick test locally (on Windows 11 23H2 + NVIDIA 560.80 + LG C2 42"), it works as expected. This is encouraging to see, I've been wanting this for a while 🙂

I'll need to look into building more extensive scenes and getting tonemapped screenshots/videos out of this. 2D HDR also needs to be tested thoroughly.

Remember that JPEG XL or AVIF for images and AV1 for videos are a must for HDR, as other formats can only store SDR data. You may need to embed those in ZIP archives and ask users to preview them in a local media player, as GitHub doesn't allow uploading those formats and browsers often struggle displaying HDR correctly.

I noticed some issues for now:

• Having RTX HDR enabled will mess with the HDR that is enabled in the editor. It will continuously enable and disable itself whenever you make any input in the editor (and disable itself after being idle for a second). This is also an issue on master with HDR disabled.
  • See [4.3 Beta 3] Strange editor brightness and colors caused by RTX Dynamic Vibrance affecting the editor #94231. We should see if we can forcibly disable RTX HDR and RTX Dynamic Vibrance for the editor using a NVIDIA profile. I haven't seen options for those in NVIDIA Profile Inspector so far.
• HDR Max Luminance affects both 2D (UI) and 3D rendering. Is that intended?
• The HDR editor setting is not applied instantly when you change it, even though the demo project shows a working example of it being toggled at runtime. You can update the viewport's status based on editor settings here:

  godot/editor/editor_node.cpp

  Line 356 in ff8a278

  void EditorNode::_update_from_settings() {

• There doesn't appear to be a paperwhite setting you can use to adjust UI brightness. This is typically offered in games to prevent the UI from being too bright. Using a paperwhite value around 200 nits is common, since a lot of OLED displays cap out at that brightness level in SDR. Either way, this should be exposed in the project settings and the documentation should recommend exposing this setting to player (just like HDR peak luminance).
  • There should also be a way for unshaded materials to base themselves on paperwhite, so that Sprite3D and Label3D used for UI purposes are not overly bright in HDR. I suppose this would be a BaseMaterial3D property or a shader render mode.
    • In the interest of compatibility, we may not be able to enable this by default in Sprite3D due to VFX usage (where HDR display can be intended), but for Label3D, we may be able to safely default to this.

See the settings exposed by the Control HDR mod for an example of a best-in-class HDR implementation (related video):

control_hdr_mod_settings.mp4

Interesting, that UI seems to use the term "paperwhite" in a different way, and has a dedicated setting for the brightness of UI and HUD elements.

[DarkKilauea]

I gave this a quick test locally (on Windows 11 23H2 + NVIDIA 560.80 + LG C2 42"), it works as expected. This is encouraging to see, I've been wanting this for a while 🙂

Thanks for taking a look!

I noticed some issues for now:

* Having RTX HDR enabled will mess with the HDR that is enabled in the editor. It will continuously enable and disable itself whenever you make any input in the editor (and disable itself after being idle for a second). This is also an issue on `master` with HDR disabled.

* See [[4.3 Beta 3] Strange editor brightness and colors caused by RTX Dynamic Vibrance affecting the editor #94231](https://github.com/godotengine/godot/issues/94231). We should see if we can forcibly disable RTX HDR and RTX Dynamic Vibrance for the editor using a NVIDIA profile. I haven't seen options for those in NVIDIA Profile Inspector so far.

Odd that NVidia's RTX HDR doesn't detect the HDR color space and avoid messing with the final swap chain buffer. Auto-HDR in Windows 11 appears to avoid messing with Godot when HDR is enabled. Updating the NVidia Profile may be outside the scope of this PR and be best done with a more focused PR.

* HDR Max Luminance affects both 2D (UI) and 3D rendering. Is that intended?

For the initial draft, yes, everything is mapped using the same tonemapper. However, we should map UI elements to a different brightness to avoid them being too bright. For now, that can be worked around with dimming the brightness of any UI elements via the theme, but I would like to fix that in this PR.

* The HDR editor setting is not applied instantly when you change it, even though the demo project shows a working example of it being toggled at runtime. You can update the viewport's status based on editor settings here: https://github.com/godotengine/godot/blob/ff8a2780ee777c2456ce42368e1065774c7c4c3f/editor/editor_node.cpp#L356

I haven't looked into configuring the editor to use HDR yet. Will do after I figure out how to properly tone map UI elements, if you enable HDR on the editor now, the UI is a little unpleasant.

* There doesn't appear to be a paperwhite setting you can use to adjust UI brightness. This is typically offered in games to prevent the UI from being too bright. Using a paperwhite value around 200 nits is common, since a lot of OLED displays cap out at that brightness level in SDR. Either way, this should be exposed in the project settings and the documentation should recommend exposing this setting to player (just like HDR peak luminance).

Agreed, UI elements and other 2D elements should probably be mapped to a different brightness curve. I'll probably have to figure out where in the engine 3D and 2D elements are composited together and perform the tone mapping there.

  * There should also be a way for unshaded materials to base themselves on paperwhite, so that Sprite3D and Label3D used for UI purposes are not overly bright in HDR. I suppose this would be a BaseMaterial3D property or a shader render mode.

    * In the interest of compatibility, we may not be able to enable this by default in Sprite3D due to VFX usage (where HDR display can be intended), but for Label3D, we may be able to safely default to this.

That might be outside of the scope of this PR. I'm not sure how I would indicate that certain 3D elements need to be mapped using a different brightness curve once they are all combined into the same buffer. It would be similar to trying to avoid sRGB mapping certain rendered elements.

For now, this can be worked around by decreasing the brightness of the color of these elements.

See the settings exposed by the Control HDR mod for an example of a best-in-class HDR implementation (related video):
control_hdr_mod_settings.mp4

Interesting, that UI seems to use the term "paperwhite" in a different way, and has a dedicated setting for the brightness of UI and HUD elements.

Baldur's Gate 3 and Cyberpunk 2077 also have really nice HDR settings menus. I've been basing some of this work off their approach, though modifying contrast and brightness I'm leaving up to Environment since those effects are already there.

Thanks again for your comments! I'll add some TODO items to the description for tracking.

[Jamsers]

Can you use any Godot project to test this PR? Bistro-Demo-Tweaked and Crater-Province-Level both use physical light units, and use as close to reference values for luminosity on light sources. (i.e. the sun at noon is 100000 lux, the moon at midnight is 0.3 lux)

I'd love to help test this PR but unfortunately I don't have HDR hardware ☹️

[alvinhochun]

I recently got a monitor that supports fake HDR DisplayHDR 400 so I thought I could give this a try, but on Intel UHD 620 it prints "WARNING: HDR output requested but no HDR compatible format was found, falling back to SDR." and doesn't display in HDR. I was kind of expected this since it is using Vulkan, but I'm a bit surprised it works for you, even on windowed mode no less. I guess there is some special handling in the NVIDIA driver?

Anyway, adding HDR output to D3D12 should be trivial and I might give it a try. (No promises!)

---

Shall we also consider implementing HDR display for the compatibility renderer? I am not sure if native OpenGL can do HDR, but it is very possible to implement on Windows with the help of ANGLE and some manual setting up.

[fire]

This needs a rebase on master, but I have a https://www.dell.com/en-ca/shop/alienware-34-curved-qd-oled-gaming-monitor-aw3423dw/apd/210-bcye/monitors-monitor-accessories HDR display.

I can help test.

[DarkKilauea]

Can you use any Godot project to test this PR? Bistro-Demo-Tweaked and Crater-Province-Level both use physical light units, and use as close to reference values for luminosity on light sources. (i.e. the sun at noon is 100000 lux, the moon at midnight is 0.3 lux)

I'd love to help test this PR but unfortunately I don't have HDR hardware ☹️

You should be able to test with any scene, though keep in mind that the realistic light units will not map directly to the brightness of the display. Consumer desktop displays typically don't go much above 1000 nits on the high end, which is far too dim to simulate sunlight. Values from the scene will be mapped to a range fitting within the max luminosity set for the window.

[alvinhochun]

Here are the changes to get Rec. 2020 HDR output on D3D12: master...alvinhochun:godot:hdr-output-d3d12

[alvinhochun]

Quote

HDR (blown out a bit, looks better on an HDR display):

SDR:

The over-exposure in your screenshot is expected, but the colours are oversaturated because it is missing a colour space conversion. The colours need to be converted from BT.709 primaries to BT.2020 primaries. This is how it should look with the correct colours:

The conversion may be done with something like this:

diff --git a/servers/rendering/renderer_rd/shaders/color_space_inc.glsl b/servers/rendering/renderer_rd/shaders/color_space_inc.glsl
index 3583ee8365..76305a8a3c 100644
--- a/servers/rendering/renderer_rd/shaders/color_space_inc.glsl
+++ b/servers/rendering/renderer_rd/shaders/color_space_inc.glsl
@@ -19,6 +19,15 @@ vec3 linear_to_st2084(vec3 color, float max_luminance) {
        // max_luminance is the display's peak luminance in nits
        // we map it here to the native 10000 nits range of ST2084
        float adjustment = max_luminance * (1.0f / 10000.0f);
+       color = color * adjustment;
+
+       // Color transformation matrix values taken from DirectXTK, may need verification.
+    const mat3 from709to2020 = mat3(
+          0.6274040f, 0.0690970f, 0.0163916f,
+          0.3292820f, 0.9195400f, 0.0880132f,
+          0.0433136f, 0.0113612f, 0.8955950f
+       );
+       color = from709to2020 * color;

        // Apply ST2084 curve
        const float c1 = 0.8359375;
@@ -26,7 +35,7 @@ vec3 linear_to_st2084(vec3 color, float max_luminance) {
        const float c3 = 18.6875;
        const float m1 = 0.1593017578125;
        const float m2 = 78.84375;
-       vec3 cp = pow(abs(color.rgb * adjustment), vec3(m1));
+       vec3 cp = pow(abs(color.rgb), vec3(m1));

        return pow((c1 + c2 * cp) / (1 + c3 * cp), vec3(m2));
 }

[DarkKilauea]

This mostly looked good! Thanks for doing this!! I've pushed a commit to fix up a couple of things so that my big overhaul to tonemapping and AgX with HDR is now complete. I did another trivial rebase while I was at it, since I needed for force push anyway.

Thanks for that! Squashed in most of the changes.

I've fully removed the float hdr_linear_luminance_scale variable from D3D12 and Metal because these drivers have strictly defined values. It makes sense to keep this variable for Vulkan for its use in the Android PR, for example.

I ended up removing the change in logic here for a couple reasons:

1. It started producing warnings anytime HDR was toggled in Windows due to Windows trying to set the linear scale on D3D12. I tried fixing the error by updating the display server, but realized that requires the display server to understand what underlying renderer was being used, since Vulkan still needs to set 80 for those that want to use a custom engine that enables HDR in Vulkan, but nothing should be called for D3D12.
2. This is an internal API that should never be exposed to the user. It doesn't need the same level of error checking for misuse as public APIs. We can trust the display server implementations to do the right thing here for their platforms, given they are likely the only ones to understand what is needed. Linear scale is a display server concept, not a renderer one.

I noticed the ColorPicker needs to be enhanced to work with HDR output in addition to the other editor previews.

This is likely a quick change to enable hdr_2d here.

I believe the "Enable HDR for editor previews when HDR output is enabled" commit should be separated into its own followup PR (similar to the Android HDR PR) in order to improve the review process: This way, members who are experts in reviewing editor changes will be able to focus on editor changes, rather than needing to wade through the vast number of changes of this PR that are not related to the editor. Besides that commit, this PR has almost zero changes to the editor, and I think this is a good thing for the review process.

Yea, that makes sense, assuming we plan to actually merge the editor changes in 4.7. Without them, the editor looks strange in places with HDR on, which is not a great experience.

I requested another review since all suggestions have been completed, would love to see another approval to unblock merging.

[allenwp]

I ended up removing the change in logic here for a couple reasons

Oh, good catch; thanks for having my back. I thought I did a thorough search of references to it, but I must have overlooked a scenario.

Yea, that makes sense, assuming we plan to actually merge the editor changes in 4.7. Without them, the editor looks strange in places with HDR on, which is not a great experience.

Yep, for sure. I want to make sure this PR gets into 4.7 dev 1, so long as no issues are discovered with it. Editor enhancements can easily make it in shortly afterwards, but if they end up being in a different dev release, it's no big deal.

I requested another review since all suggestions have been completed, would love to see another approval to unblock merging.

Done! I don't know of any remaining issues with this PR. I'll keep testing on Steam Deck/Wine to verify that things don't look problematically dark with the 200 nits reference luminance...

[allenwp]

While testing, I was connecting and disconnecting monitors a fair bit and got into a situation where Godot reported this error:

ERROR: platform\windows\display_server_windows.cpp:1646 - Failed to get SDR white level for screen: 1, adapterId: 0x000000000000CDAA, id: 4352

And then stopped responding entirely to changes in SDRWhiteLevel, regardless of whether I turned "request HDR output" on or off or moved the window between displays. I took a look at the code and noticed that it was written such that it would stop attempting to read changes in SDRWhiteLevel after the first failed attempt, as suggested by @bruvzg.

I've committed and squashed a change to only stop reporting error messages instead of permanently giving up on reading SDRWhiteLevel for the display. This should resolve the issue that I had, but is different than the logic that @bruvzg suggested. Feel free to clean it up further, but the previous suggestion to block future attempts to read SDRWhiteLevel is not functional, it seems.

[DarkKilauea]

Another rebase to bring in the beta 1 bits. No other changes.

[allenwp]

I've made a draft for a new HDR output manual page along with a draft for an official HDR output demo project. Please give those a look and provide feedback! I'm sure many of us have had some thoughts about how best to instruct HDR output usage and how it can be demonstrated to new users, so I'd like to hear if I've captured the key points or have introduced anything that may only add confusion.

I've also renamed my old test project to be a "Godot HDR output porting test project ". This older test project is designed solely for implementing the HDR output feature on new platforms. The official HDR output demo project supersedes it for general demonstration purposes.

Finally, I've created trackers for HDR output-related proposals and issues & PRs. Please feel free to post on those threads whenever you create a new item that should be added to one of those trackers.

@DarkKilauea Would you mind updating the description of this PR to include some of those links if you have time? (Also, I'm not sure if your old test project is entirely suitable anymore: I notice that it has the old Rec. 2020 colour triangle, but this is entirely clipped to Rec. 709 now...) No rush, of course, and thanks as always!

[DarkKilauea]

I've made a draft for a new HDR output manual page along with a draft for an official HDR output demo project. Please give those a look and provide feedback! I'm sure many of us have had some thoughts about how best to instruct HDR output usage and how it can be demonstrated to new users, so I'd like to hear if I've captured the key points or have introduced anything that may only add confusion.

Thanks for that! I've added links to the description.

Would you mind updating the description of this PR to include some of those links if you have time? (Also, I'm not sure if your old test project is entirely suitable anymore: I notice that it has the old Rec. 2020 colour triangle, but this is entirely clipped to Rec. 709 now...) No rush, of course, and thanks as always!

Links have been updated. I also updated the screenshots and getting started guide. Thanks again for all the help!

[allenwp]

Thanks!

From the description:

Blending, glow, color correction, brightness, contrast, and saturation adjustments may look different when hdr_2d is enabled.

Most of these are no longer the case. I implemented fixes in 4.6 to correct this behaviour: now only blending is different when hdr_2d is enabled.

Also, I'm not sure that the advice in the Getting Started -> runtime is a good idea. Setting request HDR output is something that should be done independently of whether the window currently supports HDR output. I expect this approach of checking to see if the window currently supports HDR output should only be used for determining how player-facing settings are presented, which doesn't appear to be what this section of getting started is demonstrating.

[blueskythlikesclouds]

You should reuse the DXGI factory from the D3D12 rendering context driver. The IDXGIFactory2 can be upcasted to IDXGIFactory4 using QueryInterface.

[DarkKilauea]

Rebased on top of the RC 1 bits.

[DarkKilauea]

From the description:

Blending, glow, color correction, brightness, contrast, and saturation adjustments may look different when hdr_2d is enabled.

Most of these are no longer the case. I implemented fixes in 4.6 to correct this behaviour: now only blending is different when hdr_2d is enabled.

This has been fixed, thanks for pointing that out. I knew we fixed some issues, but wasn't sure as to the extent.

Also, I'm not sure that the advice in the Getting Started -> runtime is a good idea. Setting request HDR output is something that should be done independently of whether the window currently supports HDR output. I expect this approach of checking to see if the window currently supports HDR output should only be used for determining how player-facing settings are presented, which doesn't appear to be what this section of getting started is demonstrating.

That's fair, I'll update.