Skip to content

[WIP Prototype] Add HDR support to tonemappers #106696

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Draft
wants to merge 4 commits into
base: master
Choose a base branch
from
+2,556 −263
Draft

[WIP Prototype] Add HDR support to tonemappers #106696

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
f10c8d3
Support output to HDR monitors
DarkKilauea Feb 2, 2025
3742631
Fix multi-monitor setup where HDR monitor is not of the primary adapter.
allenwp Aug 5, 2025
9103ac7
Did a more thorough cherry pick of the AgX update PR.
allenwp May 16, 2025
043e86a
Optimized CIE-correct "black"/low-clip luminosity. I don't think it c…
allenwp Aug 5, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
7 changes: 7 additions & 0 deletions core/config/project_settings.cpp
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1602,6 +1602,13 @@ ProjectSettings::ProjectSettings() {
GLOBAL_DEF("display/window/size/minimize_disabled", false);
GLOBAL_DEF("display/window/size/maximize_disabled", false);

GLOBAL_DEF("display/window/hdr/enabled", false);
GLOBAL_DEF("display/window/hdr/prefer_high_precision", false);
GLOBAL_DEF("display/window/hdr/auto_adjust_reference_luminance", true);
GLOBAL_DEF(PropertyInfo(Variant::FLOAT, "display/window/hdr/reference_luminance", PROPERTY_HINT_RANGE, "0,2000,1,or_greater"), 200.0f); // BT.2408 recommendation of 203 nits for HDR Reference White, rounded to 200 to be a more pleasant player-facing value.
GLOBAL_DEF("display/window/hdr/auto_adjust_max_luminance", true);
GLOBAL_DEF(PropertyInfo(Variant::FLOAT, "display/window/hdr/max_luminance", PROPERTY_HINT_RANGE, "0,2000,1,or_greater"), 1000.0f);

GLOBAL_DEF(PropertyInfo(Variant::INT, "display/window/size/window_width_override", PROPERTY_HINT_RANGE, "0,7680,1,or_greater"), 0); // 8K resolution
GLOBAL_DEF(PropertyInfo(Variant::INT, "display/window/size/window_height_override", PROPERTY_HINT_RANGE, "0,4320,1,or_greater"), 0); // 8K resolution

Expand Down
184 changes: 184 additions & 0 deletions doc/classes/DisplayServer.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1731,6 +1731,27 @@
[b]Note:[/b] On macOS, this method requires the "Screen Recording" permission. If permission is not granted, this method returns a screenshot that will not include other application windows or OS elements not related to the application.
</description>
</method>
<method name="screen_get_max_full_frame_luminance" qualifiers="const">
<return type="float" />
<param index="0" name="screen" type="int" default="-1" />
<description>
Returns the maximum full screen luminance of [param screen] in nits (cd/m²).
Some displays support brighter luminance in small areas, but this is the maximum luminance that can be achieved across the entire screen.
[b]Note:[/b] Requires support for [constant FEATURE_HDR].
[b]Note:[/b] This method is intended to be informational and may not be implemented even if [constant FEATURE_HDR] is supported.
[b]Note:[/b] On Windows, this method is implemented only in builds with D3D12 enabled.
</description>
</method>
<method name="screen_get_max_luminance" qualifiers="const">
<return type="float" />
<param index="0" name="screen" type="int" default="-1" />
<description>
Returns the maximum luminance of a pixel on [param screen] in nits (cd/m²).
[b]Note:[/b] Requires support for [constant FEATURE_HDR].
[b]Note:[/b] This method is intended to be informational and may not be implemented even if [constant FEATURE_HDR] is supported.
[b]Note:[/b] On Windows, this method is implemented only in builds with D3D12 enabled.
</description>
</method>
<method name="screen_get_max_scale" qualifiers="const">
<return type="float" />
<description>
Expand All @@ -1739,6 +1760,16 @@
[b]Note:[/b] This method is implemented only on macOS.
</description>
</method>
<method name="screen_get_min_luminance" qualifiers="const">
<return type="float" />
<param index="0" name="screen" type="int" default="-1" />
<description>
Returns the minimum luminance of a pixel on [param screen] in nits (cd/m²).
[b]Note:[/b] Requires support for [constant FEATURE_HDR].
[b]Note:[/b] This method is intended to be informational and may not be implemented even if [constant FEATURE_HDR] is supported.
[b]Note:[/b] On Windows, this method is implemented only in builds with D3D12 enabled.
</description>
</method>
<method name="screen_get_orientation" qualifiers="const">
<return type="int" enum="DisplayServer.ScreenOrientation" />
<param index="0" name="screen" type="int" default="-1" />
Expand Down Expand Up @@ -1800,6 +1831,16 @@
[b]Note:[/b] This method is implemented on Android, iOS, Web, macOS, and Linux (Wayland). On other platforms, this method always returns [code]1.0[/code].
</description>
</method>
<method name="screen_get_sdr_white_level" qualifiers="const">
<return type="float" />
<param index="0" name="screen" type="int" default="-1" />
<description>
Returns the standard dynamic range (SDR) white level of [param screen] in nits (cd/m²).
This is the maximum brightness SDR content (such as UI) should be rendered at to match other applications on the display.
[b]Note:[/b] Requires support for [constant FEATURE_HDR].
[b]Note:[/b] This method is intended to be informational and may not be implemented even if [constant FEATURE_HDR] is supported.
</description>
</method>
<method name="screen_get_size" qualifiers="const">
<return type="Vector2i" />
<param index="0" name="screen" type="int" default="-1" />
Expand All @@ -1817,6 +1858,17 @@
[b]Note:[/b] This method is implemented on Linux/X11, macOS, and Windows. On other platforms, this method always returns [code]Rect2i(screen_get_position(screen), screen_get_size(screen))[/code].
</description>
</method>
<method name="screen_is_hdr_supported" qualifiers="const">
<return type="bool" />
<param index="0" name="screen" type="int" default="-1" />
<description>
Returns [code]true[/code] if the [param screen] supports HDR.
Use [method window_is_hdr_output_supported] to check if a specific window can output HDR content.
[b]Note:[/b] Requires support for [constant FEATURE_HDR].
[b]Note:[/b] This method is intended to be informational and may not be implemented even if [constant FEATURE_HDR] is supported.
[b]Note:[/b] On Windows, this method is implemented only in builds with D3D12 enabled.
</description>
</method>
<method name="screen_is_kept_on" qualifiers="const">
<return type="bool" />
<description>
Expand Down Expand Up @@ -2131,6 +2183,32 @@
Returns the current value of the given window's [param flag].
</description>
</method>
<method name="window_get_hdr_output_max_luminance" qualifiers="const">
<return type="float" />
<param index="0" name="window_id" type="int" default="0" />
<description>
Returns the maximum luminance in nits (cd/m²) set for HDR content for the window specified by [param window_id].
[b]Note:[/b] Requires support for [constant FEATURE_HDR].
</description>
</method>
<method name="window_get_hdr_output_max_value" qualifiers="const">
<return type="float" />
<param index="0" name="window_id" type="int" default="0" />
<description>
Returns the maximum value for color components that can be displayed in HDR mode for the window specified by [param window_id].
Use this to scale HDR content to max out the display's brightness, for example lasers or other bright effects.
Will return 1.0 if HDR is not enabled or not supported.
[b]Note:[/b] Requires support for [constant FEATURE_HDR].
</description>
</method>
<method name="window_get_hdr_output_reference_luminance" qualifiers="const">
<return type="float" />
<param index="0" name="window_id" type="int" default="0" />
<description>
Returns the SDR reference luminance in nits (cd/m²) set for HDR content for the window specified by [param window_id].
[b]Note:[/b] Requires support for [constant FEATURE_HDR].
</description>
</method>
<method name="window_get_max_size" qualifiers="const">
<return type="Vector2i" />
<param index="0" name="window_id" type="int" default="0" />
Expand Down Expand Up @@ -2226,6 +2304,45 @@
Returns [code]true[/code] if the window specified by [param window_id] is focused.
</description>
</method>
<method name="window_is_hdr_output_auto_adjusting_max_luminance" qualifiers="const">
<return type="bool" />
<param index="0" name="window_id" type="int" default="0" />
<description>
Returns whether the window specified by [param window_id] automatically adjusts the maximum luminance for HDR output based on the display's capabilities.
[b]Note:[/b] Requires support for [constant FEATURE_HDR].
</description>
</method>
<method name="window_is_hdr_output_auto_adjusting_reference_luminance" qualifiers="const">
<return type="bool" />
<param index="0" name="window_id" type="int" default="0" />
<description>
Returns whether the window specified by [param window_id] automatically adjusts the reference luminance for HDR output based on the display's capabilities.
[b]Note:[/b] Requires support for [constant FEATURE_HDR].
</description>
</method>
<method name="window_is_hdr_output_enabled" qualifiers="const">
<return type="bool" />
<param index="0" name="window_id" type="int" default="0" />
<description>
Returns whether HDR output is requested for the window specified by [param window_id].
[b]Note:[/b] Requires support for [constant FEATURE_HDR].
</description>
</method>
<method name="window_is_hdr_output_preferring_high_precision" qualifiers="const">
<return type="bool" />
<param index="0" name="window_id" type="int" default="0" />
<description>
Returns whether the window specified by [param window_id] prefers a high precision (16-bit per color) HDR framebuffer.
</description>
</method>
<method name="window_is_hdr_output_supported" qualifiers="const">
<return type="bool" />
<param index="0" name="window_id" type="int" default="0" />
<description>
Returns whether the window specified by [param window_id] supports HDR output.
[b]Note:[/b] Requires support for [constant FEATURE_HDR].
</description>
</method>
<method name="window_is_maximize_allowed" qualifiers="const">
<return type="bool" />
<param index="0" name="window_id" type="int" default="0" />
Expand Down Expand Up @@ -2300,6 +2417,70 @@
Enables or disables the given window's given [param flag].
</description>
</method>
<method name="window_set_hdr_output_auto_adjust_max_luminance">
<return type="void" />
<param index="0" name="enabled" type="bool" />
<param index="1" name="window_id" type="int" default="0" />
<description>
Sets whether the window specified by [param window_id] should automatically adjust the maximum luminance for HDR content based on the display's brightness.
[b]Note:[/b] Requires support for [constant FEATURE_HDR].
[b]Note:[/b] Requires support by the rendering device.
</description>
</method>
<method name="window_set_hdr_output_auto_adjust_reference_luminance">
<return type="void" />
<param index="0" name="enabled" type="bool" />
<param index="1" name="window_id" type="int" default="0" />
<description>
Sets whether the window specified by [param window_id] should automatically adjust the SDR reference luminance for HDR content based on the display's brightness.
[b]Note:[/b] Requires support for [constant FEATURE_HDR].
[b]Note:[/b] Requires support by the rendering device.
</description>
</method>
<method name="window_set_hdr_output_enabled">
<return type="void" />
<param index="0" name="enabled" type="bool" />
<param index="1" name="window_id" type="int" default="0" />
<description>
Sets whether HDR output should be enabled for the window specified by [param window_id], falling back to SDR if not supported.
Only available on platforms that support HDR output, have HDR enabled in the system settings, and have a compatible display connected.
[b]Note:[/b] Requires support for [constant FEATURE_HDR].
[b]Note:[/b] Requires support by the rendering device.
</description>
</method>
<method name="window_set_hdr_output_max_luminance">
<return type="void" />
<param index="0" name="max_luminance" type="float" />
<param index="1" name="window_id" type="int" default="0" />
<description>
Sets the maximum luminance in nits (cd/m²) for HDR content for the window specified by [param window_id].
[b]Note:[/b] Requires support for [constant FEATURE_HDR].
[b]Note:[/b] Requires support by the rendering device.
[b]Note:[/b] Will not immediately take effect while [method window_is_hdr_output_auto_adjusting_max_luminance] is [code]true[/code]. Any value set will take effect once auto-adjustment is disabled.
</description>
</method>
<method name="window_set_hdr_output_prefer_high_precision">
<return type="void" />
<param index="0" name="enabled" type="bool" />
<param index="1" name="window_id" type="int" default="0" />
<description>
Sets whether the window specified by [param window_id] prefers a high precision (16-bit per color) framebuffer.
[b]Note:[/b] Requires support for [constant FEATURE_HDR].
[b]Note:[/b] Requires support by the rendering device.
</description>
</method>
<method name="window_set_hdr_output_reference_luminance">
<return type="void" />
<param index="0" name="reference_luminance" type="float" />
<param index="1" name="window_id" type="int" default="0" />
<description>
Sets the SDR reference luminance in nits (cd/m²) for HDR content for the window specified by [param window_id].
This controls the brightness of SDR content (such as UI) when HDR is enabled.
[b]Note:[/b] Requires support for [constant FEATURE_HDR].
[b]Note:[/b] Requires support by the rendering device.
[b]Note:[/b] Will not immediately take effect while [method window_is_hdr_output_auto_adjusting_reference_luminance] is [code]true[/code]. Any value set will take effect once auto-adjustment is disabled.
</description>
</method>
<method name="window_set_ime_active">
<return type="void" />
<param index="0" name="active" type="bool" />
Expand Down Expand Up @@ -2612,6 +2793,9 @@
<constant name="FEATURE_ACCESSIBILITY_SCREEN_READER" value="34" enum="Feature">
Display server supports interaction with screen reader or Braille display. [b]Linux (X11/Wayland), macOS, Windows[/b]
</constant>
<constant name="FEATURE_HDR" value="35" enum="Feature">
Display server supports HDR output. [b]Windows[/b]
</constant>
<constant name="ROLE_UNKNOWN" value="0" enum="AccessibilityRole">
Unknown or custom role.
</constant>
Expand Down
21 changes: 15 additions & 6 deletions doc/classes/Environment.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -313,6 +313,12 @@
<member name="ssr_max_steps" type="int" setter="set_ssr_max_steps" getter="get_ssr_max_steps" default="64">
The maximum number of steps for screen-space reflections. Higher values are slower.
</member>
<member name="tonemap_black" type="float" setter="set_tonemap_black" getter="get_tonemap_black" default="0.0">
Adjusts the range of input values to the tonemapper. Values provided to the tonemapper that are below [member tonemap_black] will be hard-clipped to 0.0. This parameter can be used to ensure that the viewer will never see certain dark features, regardless of the output dynamic range or viewing environment.
</member>
<member name="tonemap_contrast" type="float" setter="set_tonemap_contrast" getter="get_tonemap_contrast" default="1.25653">
Increasing [member tonemap_contrast] will make dark values darker and bright values brighter. Produces a higher quality result than [member adjustment_contrast] without any additional performance cost, but is only available when using the [constant TONE_MAPPER_AGX] or [constant TONE_MAPPER_ADJUSTABLE] tonemapper.
</member>
<member name="tonemap_exposure" type="float" setter="set_tonemap_exposure" getter="get_tonemap_exposure" default="1.0">
Adjusts the brightness of values before they are provided to the tonemapper. Higher [member tonemap_exposure] values result in a brighter image. See also [member tonemap_white].
[b]Note:[/b] Values provided to the tonemapper will also be multiplied by [code]2.0[/code] and [code]1.8[/code] for [constant TONE_MAPPER_FILMIC] and [constant TONE_MAPPER_ACES] respectively to produce a similar apparent brightness as [constant TONE_MAPPER_LINEAR].
Expand All @@ -321,8 +327,8 @@
The tonemapping mode to use. Tonemapping is the process that "converts" HDR values to be suitable for rendering on an LDR display. (Godot doesn't support rendering on HDR displays yet.)
</member>
<member name="tonemap_white" type="float" setter="set_tonemap_white" getter="get_tonemap_white" default="1.0">
The white reference value for tonemapping, which indicates where bright white is located in the scale of values provided to the tonemapper. For photorealistic lighting, recommended values are between [code]6.0[/code] and [code]8.0[/code]. Higher values result in less blown out highlights, but may make the scene appear lower contrast. See also [member tonemap_exposure].
[b]Note:[/b] [member tonemap_white] is ignored when using [constant TONE_MAPPER_LINEAR] or [constant TONE_MAPPER_AGX].
The white reference value for tonemapping, which indicates where bright white is located in the scale of values provided to the tonemapper. For photorealistic lighting, it is recommended to set [member tonemap_white] to at least [code]6.0[/code]. Higher values result in less blown out highlights, but may make the scene appear lower contrast. See also [member tonemap_exposure].
[b]Note:[/b] [member tonemap_white] must be set to [code]2.0[/code] or lower on the Mobile rendering method to produce bright images.
</member>
<member name="volumetric_fog_albedo" type="Color" setter="set_volumetric_fog_albedo" getter="get_volumetric_fog_albedo" default="Color(1, 1, 1, 1)">
The [Color] of the volumetric fog when interacting with lights. Mist and fog have an albedo close to [code]Color(1, 1, 1, 1)[/code] while smoke has a darker albedo.
Expand Down Expand Up @@ -422,15 +428,18 @@
[b]Note:[/b] When [member tonemap_white] is left at the default value of [code]1.0[/code], [constant TONE_MAPPER_REINHARDT] produces an identical image to [constant TONE_MAPPER_LINEAR].
</constant>
<constant name="TONE_MAPPER_FILMIC" value="2" enum="ToneMapper">
Uses a film-like tonemapping curve to prevent clipping of bright values and provide better contrast than [constant TONE_MAPPER_REINHARDT]. Slightly slower than [constant TONE_MAPPER_REINHARDT].
Uses a film-like tonemapping curve to prevent clipping of bright values and provide better contrast than [constant TONE_MAPPER_REINHARDT]. Slightly slower than [constant TONE_MAPPER_REINHARDT]. This tonemapper only supports Standard Dynamic Range (SDR) output.
</constant>
<constant name="TONE_MAPPER_ACES" value="3" enum="ToneMapper">
Uses a high-contrast film-like tonemapping curve and desaturates bright values for a more realistic appearance. Slightly slower than [constant TONE_MAPPER_FILMIC].
Uses a high-contrast film-like tonemapping curve and desaturates bright values for a more realistic appearance. Slightly slower than [constant TONE_MAPPER_FILMIC]. This tonemapper only supports Standard Dynamic Range (SDR) output.
[b]Note:[/b] This tonemapping operator is called "ACES Fitted" in Godot 3.x.
</constant>
<constant name="TONE_MAPPER_AGX" value="4" enum="ToneMapper">
Uses a film-like tonemapping curve and desaturates bright values for a more realistic appearance. Better than other tonemappers at maintaining the hue of colors as they become brighter. The slowest tonemapping option.
[b]Note:[/b] [member tonemap_white] is fixed at a value of [code]16.29[/code], which makes [constant TONE_MAPPER_AGX] unsuitable for use with the Mobile rendering method.
Uses an adjustable film-like tonemapping curve and desaturates bright values for a more realistic appearance. Better than other tonemappers at maintaining the hue of colors as they become brighter. The slowest tonemapping option.
[b]Note:[/b] When using [constant TONE_MAPPER_AGX], the minimum supported [member tonemap_white] is [code]2.0[/code] and a value of [code]16.0[/code] is recommended for use with the Compatibility and Forward+ rendering methods.
</constant>
<constant name="TONE_MAPPER_ADJUSTABLE" value="5" enum="ToneMapper">
Uses a film-like tonemapping curve with an adjustable contrast. Slightly slower than [constant TONE_MAPPER_ACES] (That's my goal, anyway!).
</constant>
<constant name="GLOW_BLEND_MODE_ADDITIVE" value="0" enum="GlowBlendMode">
Additive glow blending mode. Mostly used for particles, glows (bloom), lens flare, bright sources.
Expand Down
Loading
Loading