Add HDR output manual page

[allenwp]

HDR output is planned for Godot 4.7. Along with its release, we should provide an new manual page describing how to use it. This PR is my attempt at this sort of a manual page.

You can try out the HDR output PR with my demo project to get a better understanding of the concepts shared in this manual page.

Notes to reviewers

• I'm not sure if this should be under Rendering or if it should have its own section, similar to XR. I think it's probably best as just one single page, so I've put it under Rendering.

Additional text for followup PRs

In the spirit of getting this merged sooner rather than later, I've removed a couple of non-critical sections that may be added later when I or someone else have the time. Here are my draft notes for these additional sections.

Additional text drafts

First steps

This section may be added after the demo project has been merged.

First steps
-----------

Try out the `HDR output demo project <https://github.com/godotengine/godot-demo-projects/pull/1287>`_
to ensure HDR output is working with your setup.
Follow the troubleshooting steps below to resolve any issues you might have.

Optional player settings

This should be added to the list of steps to enable HDR output in your project. It should link to the demo once its been merged.

5. [Optional] Provide in-game settings for the player to adjust HDR brightness
   and maximum luminance by copying ``in_game_hdr_settings`` from the demo to
   your project.

Changing reference white luminance

**Changing reference white luminance**

HDR brightness is the reference white luminance. It can be changed depending on operating system:

(TODO: instructions for each platform)

Calibrating max luminance

This section somewhat depends on the demo project to give an example of how you can let your players calibrate their max luminance through a settings menu.

Calibrating maximum luminance
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

External HDR screens often do not provide accurate maximum luminance values, but instead provide the maximum luminance that can be provided to the internal tone mapper of the screen. For this reason, it is important to calibrate your maximum luminance on devices that use an external screen and provide in-game settings to users who may not be able to perform this calibration through their operating system. An example of this sort of HDR settings menu that you can use in your game is found as a part of the HDR output demo project.

TODO: how to calibrate on different platforms

Troubleshooting

This troubleshooting section would obviously be nice to have, and again, it depends somewhat on the demo project because this demo project should be the first thing that users try out when troubleshooting.

Troubleshooting
---------------

When running the HDR output demo project, the following debug information is displayed:

DisplayServer
TODO

RenderingDevice
TODO

Window supports HDR output
If this is false, it likely means that the screen that the game window is on does not support HDR output. If this is the case, you may need to enable HDR output for this screen through your system settings.

Windows
^^^^^^^

Prerequisites
An HDR-capable screen
HDR enabled for this screen in your system display settings
For more information, see https://support.microsoft.com/en-us/windows/hdr-settings-in-windows-2d767185-38ec-7fdc-6f97-bbc6c5ef24e6


(TODO: Mac OS, etc.)

[allenwp]

Maybe I should have a section dedicated to explaining how sRGB is used with HDR?

If I write about this, I should probably also write that Godot uses the Rec. 709 colour gamut (which is the colour gamut used by sRGB.)

[iuymatiao]

Is there a way to preview the manual in document form? I'd certainly be interested in perusing the instructions for HDR.

[allenwp]

I have an HTML build that I could save as a PDF and upload somewhere... but it would become outdated pretty quickly.

There is a small bit of markup in the file that I have added in this PR, but it's likely easiest and best to simply view the raw file that I added in this PR's changed files list.

Edit: oh, you can tap “View file” on the desktop webpage (but not the mobile app) to get something that is pretty close to the final HTML appearance:

[allenwp]

I've addressed the specific items that were mentioned in AThousandShips' review. There are still more references that need to be added and other formatting is probably needed. Also I discovered I didn't have the pre-commit hooks set up on this computer, so that's fixed now too.

Images still aren't done yet.

Most importantly, I've removed sections that need to have the demo project merged first so that this page may be added sooner rather than later and not blocked by the demo project. These sections have been moved to the "Additional text drafts" section of this PR's description text so they can be included in a followup PR.

[Calinou]

Looks good to me.

[allenwp]

I've finished my work on this new manual page and it's ready for review!

I went overboard with the class/member references, so these will likely need to be trimmed back, but I'm not sure what the conventions are for this sort of thing.

[DarkKilauea]

Left a few notes, but I'm generally happy with this as an initial version.

One thing I'd like to see is a section walking through setup for 2D games, showing how they could use tonemapping OR handle everything with output_max_linear_value as you describe below. I think 2D games are much more likely to forgo the effects pipeline so will be completely dependent on using output_max_linear_value to control their effects.

Likewise, maybe the rest of the content that seems more applicable towards 3D could be in a 3D section? Leading to an outline like:

• Getting Started
  • Basic instructions for how to turn on HDR support.
• Fundamentals
  • Describe how Godot uses EDR and the theory behind HDR output.
• Setup for 2D Games
  • How to setup if you are using effects already vs how to use output_max_linear_value on its own.
• Setup for 3D Games
  • How to setup for 3D games using World Environment primarily with output_max_linear_value for some effects.
• Technical Details
  • Luminance and screen considerations

However I'm perfectly happy with this so far, just something to consider to see if we can make this easier to ingest for a less technical reader.

[DarkKilauea]

I found a couple areas in the docs that may need updates:

• In tutorials\troubleshooting.rst:214 there is a TODO for HDR output. This entire section may need to be reworked.

.. UPDATE: Planned feature. When HDR output is implemented, remove or update
.. this paragraph.

• In classes\class_environment.rst:2127 tonemapping is described as a process that converts HDR rendering to an LDR display (and that HDR displays are not supported yet).
• In tutorials\3d\3d_rendering_limitations.rst:27, mentions that Godot renders internally in HDR and tonemaps to a low dynamic range.
• In tutorials\3d\high_dynamic_range.rst:37-43 there is a note indicating HDR output is not supported yet.
• In tutorials\3d\high_dynamic_range.rst:62 it is indicated that only sRGB displays are supported by Godot.

[allenwp]

Thanks for the review @DarkKilauea! Those comments were very helpful.

I think 2D games are much more likely to forgo the effects pipeline so will be completely dependent on using output_max_linear_value to control their effects.

I believe this will be more like 50/50 between the two approaches: I expect maybe even the majority of 2D game developers that are interested in using HDR output will be those that use 2D lighting with the WorldEnvironment for a glow effect. Conversely, it's likely that Controls will disproportionately use output_max_linear_value directly. I think an entirely separate page would be better suited for these sorts of tutorials because this one is already quite full with everything that should be understood by game developers targeting HDR output. These tutorials would be well suited to have specific demo projects like "Your first 2D game" pages of the "Getting started" section of the Godot docs.

In tutorials\troubleshooting.rst:214 there is a TODO for HDR output. This entire section may need to be reworked.

Oh, yeah, this entire section is full of outdated and incorrect information. I've removed it entirely. For those reviewing this PR, the behaviour of HDR screens making content appear washed out applies to all operating systems including Mac OS and Windows. This washed out color affects both HDR and SDR content. This behaviour is caused by the screen and not by the operating system. When presenting sRGB content to an SDR screen, the mismatching transfer function encoding and "decoding" with a 2.2 power function provides glare compensation. When presenting either HDR or SDR content on an HDR screen, glare compensation must be applied by the screen. Screens that do not provide some form of glare compensation have colours that appear washed out. You will have a hard time finding this written on the internet because most people writing about this topic have not read the historical in-depth technical literature on the subject of colour rendering on displays or even simply plugged a Mac into an external display like they would with Windows. The concept of the sRGB standard baking in veiling glare compensation into its mismatching transfer function is mentioned in Charles Poynton's book: Digital Video and HD: Algorithms and Interfaces.

In classes\class_environment.rst:2127 tonemapping is described as a process that converts HDR rendering to an LDR display (and that HDR displays are not supported yet).

This needs a separate PR; it's not a part of this repo.

In tutorials\3d\3d_rendering_limitations.rst:27, mentions that Godot renders internally in HDR and tonemaps to a low dynamic range.

Fixed.

In tutorials\3d\high_dynamic_range.rst:37-43 there is a note indicating HDR output is not supported yet.
In tutorials\3d\high_dynamic_range.rst:62 it is indicated that only sRGB displays are supported by Godot.

Fixed. More work is needed on this page, but that's outside of the scope of this PR.

Thanks for doing a search of the rest of the docs and giving me the list of places that must be updated! That was really helpful.

I've also replaced the Reinhard white comparison image with one that I feel better highlights the reason for the white parameter.

[allenwp]

I've addressed all review comments; I'll squash to a single commit once this has been approved.

[Calinou]

Looks great!

[AThousandShips]

LGTM!

[allenwp]

Thanks for the reviews and help, everyone! I've squashed the line breaks to one commit, so this is now ready for merging.

[mhilbrunner]

Amazing work, and thanks for the reviews everyone :) Merged.

[allenwp]

@AMouri Thanks for the great blog post that you shared with us on the Android HDR PR thread. I linked it in our HDR output manual page, which you can view in its final form at this URL: https://docs.godotengine.org/en/latest/tutorials/rendering/hdr_output.html

The short-and-simple recommendations in your blog post are a great resource for someone approaching the topic for the first time. I especially like how you ended with "Resist this temptation!" -- Good advice! :)

[AMouri]

@AMouri Thanks for the great blog post that you shared with us on the Android HDR PR thread. I linked it in our HDR output manual page, which you can view in its final form at this URL: https://docs.godotengine.org/en/latest/tutorials/rendering/hdr_output.html

The short-and-simple recommendations in your blog post are a great resource for someone approaching the topic for the first time. I especially like how you ended with "Resist this temptation!" -- Good advice! :)

Thanks! :)

I do also want to signal boost the preceding blog post my colleague @jreck wrote https://android-developers.googleblog.com/2025/08/what-is-hdr.html which is a great intro on some fundamentals and what HDR isn’t

[AMouri]

@AMouri Thanks for the great blog post that you shared with us on the Android HDR PR thread. I linked it in our HDR output manual page, which you can view in its final form at this URL: https://docs.godotengine.org/en/latest/tutorials/rendering/hdr_output.html
The short-and-simple recommendations in your blog post are a great resource for someone approaching the topic for the first time. I especially like how you ended with "Resist this temptation!" -- Good advice! :)

Thanks! :)

I do also want to signal boost the preceding blog post my colleague @jreck wrote https://android-developers.googleblog.com/2025/08/what-is-hdr.html which is a great intro on some fundamentals and what HDR isn’t

Btw the hdr output manual is fantastic. It’s a really good intro to EDR + tonemapping