Skip to content

[WIP Draft] The HDR mega-PR #110701

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

Closed
allenwp wants to merge 8 commits into from
Closed

[WIP Draft] The HDR mega-PR #110701

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
8 commits
Select commit Hold shift + click to select a range
c89c546
Support output to HDR monitors
DarkKilauea Feb 2, 2025
5fad257
Disabled "tonemap" feature in editor preview environment by default t…
allenwp Oct 3, 2025
ec4e6f0
Removed comment that is always unnecessarily conflicting with my AgX PR.
allenwp Oct 23, 2025
b1d0c53
Add `agx_white` and `agx_contrast` parameters to the AgX tonemapper.
allenwp May 29, 2025
c0f811d
Fixes to AgX PR cherry pick.
allenwp Oct 23, 2025
d76334f
HDR output for linuxbsd (wayland)
ArchercatNEO Feb 17, 2025
c12f325
Use RenderingContextDriverVulkan to conditionally disable metadata
ArchercatNEO Oct 3, 2025
a29b998
Further optimized Reinhard tonemapper for Forward+/Mobile
allenwp Oct 23, 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
2 changes: 2 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 @@ -1643,6 +1643,8 @@ ProjectSettings::ProjectSettings() {
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

GLOBAL_DEF("display/window/hdr/request_hdr_output", false);

GLOBAL_DEF("display/window/energy_saving/keep_screen_on", true);
GLOBAL_DEF("animation/warnings/check_invalid_track_paths", true);
GLOBAL_DEF("animation/warnings/check_angle_interpolation_type_conflicting", true);
Expand Down
117 changes: 117 additions & 0 deletions doc/classes/DisplayServer.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2131,6 +2131,44 @@
Returns the current value of the given window's [param flag].
</description>
</method>
<method name="window_get_hdr_output_current_max_luminance" qualifiers="const">
<return type="float" />
<param index="0" name="window_id" type="int" default="0" />
<description>
Returns the current maximum luminance in nits (cd/m²) for HDR content for the window specified by [param window_id].
If max luminance is being auto adjusted based on the display's capabilities, this will return that value.
Otherwise, it will return the value set by [method window_set_hdr_output_max_luminance].
[b]Note:[/b] Requires support for [constant FEATURE_HDR].
</description>
</method>
<method name="window_get_hdr_output_current_reference_luminance" qualifiers="const">
<return type="float" />
<param index="0" name="window_id" type="int" default="0" />
<description>
Returns the current reference luminance in nits (cd/m²) for HDR content for the window specified by [param window_id].
If reference luminance is being auto adjusted based on the display's capabilities, this will return that value.
Otherwise, it will return the value set by [method window_set_hdr_output_reference_luminance].
[b]Note:[/b] Requires support for [constant FEATURE_HDR].
</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].
Negative values indicate that the value is being auto adjusted based on the display's capabilities.
[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].
Negative values indicate that the value is being auto adjusted based on the display's capabilities.
[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 @@ -2161,6 +2199,16 @@
[b]Note:[/b] This method is implemented on Android, Linux (X11/Wayland), macOS, and Windows.
</description>
</method>
<method name="window_get_output_max_value" qualifiers="const">
<return type="float" />
<param index="0" name="window_id" type="int" default="0" />
<description>
Returns the maximum value for linear 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] You will need to convert sRGB colors to linear before multiplying by this value to get accurate results.
</description>
</method>
<method name="window_get_popup_safe_rect" qualifiers="const">
<return type="Rect2i" />
<param index="0" name="window" type="int" />
Expand Down Expand Up @@ -2226,6 +2274,32 @@
Returns [code]true[/code] if the window specified by [param window_id] is focused.
</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 currently enabled for the window specified by [param window_id].
This value may change dynamically based on system settings, display capabilities, and which display the window is currently on.
[b]Note:[/b] Requires support for [constant FEATURE_HDR].
</description>
</method>
<method name="window_is_hdr_output_requested" 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_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.
This depends on the platform, display capabilities, system settings, and the display the window is currently on.
[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 @@ -2261,6 +2335,18 @@
Makes the window specified by [param window_id] request attention, which is materialized by the window title and taskbar entry blinking until the window is focused. This usually has no visible effect if the window is currently focused. The exact behavior varies depending on the operating system.
</description>
</method>
<method name="window_request_hdr_output">
<return type="void" />
<param index="0" name="enable" type="bool" />
<param index="1" name="window_id" type="int" default="0" />
<description>
Sets whether HDR output should be requested for the window specified by [param window_id], falling back to SDR if not supported, and automatically switching between HDR and SDR as the window moves between displays, display capabilities change, or system settings are modified.
Only available on platforms that support HDR output, have HDR enabled in the system settings, and have a compatible display connected.
[b]Note:[/b] Some integrated GPUs have poor support for HDR output, even when they claim to support it. If you experience issues, try disabling this setting.
[b]Note:[/b] Requires support for [constant FEATURE_HDR].
[b]Note:[/b] Requires support by the rendering device.
</description>
</method>
<method name="window_set_color">
<return type="void" />
<param index="0" name="color" type="Color" />
Expand Down Expand Up @@ -2308,6 +2394,34 @@
Enables or disables the given window's given [param flag].
</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].
Set to a negative value to automatically use the display's maximum capability.
By default, this is set to [code]-1[/code].
This controls the maximum brightness of bright elements in HDR content, typically by scaling down highlights within the scene.
[b]Note:[/b] Requires support for [constant FEATURE_HDR].
[b]Note:[/b] Requires support by the rendering device.
[b]Note:[/b] On some platforms, setting a custom max luminance is not supported and will always be auto adjusted based on the display's capabilities.
</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].
Set to a negative value to automatically adjust to the reference level set by the OS or window manager.
By default, this is set to [code]-1[/code].
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] On some platforms, setting a custom reference luminance is not supported and will always be auto adjusted based on the display's capabilities.
</description>
</method>
<method name="window_set_ime_active">
<return type="void" />
<param index="0" name="active" type="bool" />
Expand Down Expand Up @@ -2620,6 +2734,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, Linux (Wayland)[/b]
</constant>
<constant name="ROLE_UNKNOWN" value="0" enum="AccessibilityRole">
Unknown or custom role.
</constant>
Expand Down
16 changes: 12 additions & 4 deletions doc/classes/Environment.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -315,6 +315,13 @@
<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_agx_contrast" type="float" setter="set_tonemap_agx_contrast" getter="get_tonemap_agx_contrast" default="1.25">
Increasing [member tonemap_agx_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] tonemapper.
</member>
<member name="tonemap_agx_white" type="float" setter="set_tonemap_agx_white" getter="get_tonemap_agx_white" default="16.29">
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. [member tonemap_agx_white] is the same as [member tonemap_white], but is only effective with the [constant TONE_MAPPER_AGX] tonemapper. See also [member tonemap_exposure].
[b]Note:[/b] A value of [code]2.0[/code] will always be used when using the Mobile renderer with [member Viewport.use_hdr_2d] disabled and [member tonemap_agx_white] will be ignored.
</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 @@ -323,8 +330,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. [member tonemap_agx_white] will be used instead when using the [constant TONE_MAPPER_AGX] tonemapper. See also [member tonemap_exposure].
[b]Note:[/b] [member tonemap_white] must be set to [code]2.0[/code] or lower on the Mobile renderer 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 @@ -425,14 +432,15 @@
</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].
[b]Note:[/b] This tonemapper does not support HDR output and clips output to the [code]0.0-1.0[/code] range. A different tonemapper should be used when rendering to an HDR display.
</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].
[b]Note:[/b] This tonemapping operator is called "ACES Fitted" in Godot 3.x.
[b]Note:[/b] This tonemapper does not support HDR output and clips output to the [code]0.0-1.0[/code] range. A different tonemapper should be used when rendering to an HDR display.
</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.
</constant>
<constant name="GLOW_BLEND_MODE_ADDITIVE" value="0" enum="GlowBlendMode">
Adds the glow effect to the scene.
Expand Down
5 changes: 5 additions & 0 deletions doc/classes/ProjectSettings.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -952,6 +952,11 @@
The default screen orientation to use on mobile devices. See [enum DisplayServer.ScreenOrientation] for possible values.
[b]Note:[/b] When set to a portrait orientation, this project setting does not flip the project resolution's width and height automatically. Instead, you have to set [member display/window/size/viewport_width] and [member display/window/size/viewport_height] accordingly.
</member>
<member name="display/window/hdr/request_hdr_output" type="bool" setter="" getter="" default="false">
If [code]true[/code], requests HDR output for the main window and editor, falling back to SDR if not supported, and automatically switching between HDR and SDR as the window moves between displays, display capabilities change, or system settings are modified.
Only available on platforms that support HDR output, have HDR enabled in the system settings, and have a compatible display connected.
[b]Note:[/b] Some integrated GPUs have poor support for HDR output, even when they claim to support it. If you experience issues, try disabling this setting.
</member>
<member name="display/window/ios/allow_high_refresh_rate" type="bool" setter="" getter="" default="true">
If [code]true[/code], iOS devices that support high refresh rate/"ProMotion" will be allowed to render at up to 120 frames per second.
</member>
Expand Down
3 changes: 3 additions & 0 deletions doc/classes/RenderingDevice.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2504,6 +2504,9 @@
<constant name="SUPPORTS_IMAGE_ATOMIC_32_BIT" value="7" enum="Features">
Support for 32-bit image atomic operations.
</constant>
<constant name="SUPPORTS_HDR_OUTPUT" value="9" enum="Features">
Features support for high dynamic range (HDR) output.
</constant>
<constant name="LIMIT_MAX_BOUND_UNIFORM_SETS" value="0" enum="Limit">
Maximum number of uniform sets that can be bound at a given time.
</constant>
Expand Down
13 changes: 11 additions & 2 deletions doc/classes/RenderingServer.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1523,6 +1523,14 @@
Sets the variables to be used with the "tonemap" post-process effect. See [Environment] for more details.
</description>
</method>
<method name="environment_set_tonemap_agx_contrast">
<return type="void" />
<param index="0" name="env" type="RID" />
<param index="1" name="agx_contrast" type="float" />
<description>
See [member Environment.tonemap_agx_contrast] for more details.
</description>
</method>
<method name="environment_set_volumetric_fog">
<return type="void" />
<param index="0" name="env" type="RID" />
Expand Down Expand Up @@ -5494,14 +5502,15 @@
</constant>
<constant name="ENV_TONE_MAPPER_FILMIC" value="2" enum="EnvironmentToneMapper">
Uses a film-like tonemapping curve to prevent clipping of bright values and provide better contrast than [constant ENV_TONE_MAPPER_REINHARD]. Slightly slower than [constant ENV_TONE_MAPPER_REINHARD].
[b]Note:[/b] This tonemapper does not support HDR output and clips output to the [code]0.0-1.0[/code] range. A different tonemapper should be used when rendering to an HDR display.
</constant>
<constant name="ENV_TONE_MAPPER_ACES" value="3" enum="EnvironmentToneMapper">
Uses a high-contrast film-like tonemapping curve and desaturates bright values for a more realistic appearance. Slightly slower than [constant ENV_TONE_MAPPER_FILMIC].
[b]Note:[/b] This tonemapping operator is called "ACES Fitted" in Godot 3.x.
[b]Note:[/b] This tonemapper does not support HDR output and clips output to the [code]0.0-1.0[/code] range. A different tonemapper should be used when rendering to an HDR display.
</constant>
<constant name="ENV_TONE_MAPPER_AGX" value="4" enum="EnvironmentToneMapper">
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 Environment.tonemap_white] is fixed at a value of [code]16.29[/code], which makes [constant ENV_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.
</constant>
<constant name="ENV_SSR_ROUGHNESS_QUALITY_DISABLED" value="0" enum="EnvironmentSSRRoughnessQuality">
Lowest quality of roughness filter for screen-space reflections. Rough materials will not have blurrier screen-space reflections compared to smooth (non-rough) materials. This is the fastest option.
Expand Down
Loading
Loading