Skip to content

Apple: Support output to EDR (HDR) displays #106814

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 2 commits into
base: master
Choose a base branch
from
Draft

Apple: Support output to EDR (HDR) displays #106814

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
26da3d1
Support output to HDR monitors
DarkKilauea Feb 2, 2025
ec3f97b
feat: Add EDR support to Metal and macOS
stuartcarnie May 26, 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
6 changes: 6 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 @@ -1564,6 +1564,12 @@ 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/use_screen_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(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
142 changes: 142 additions & 0 deletions doc/classes/DisplayServer.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1726,6 +1726,25 @@
[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] 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] 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 @@ -1734,6 +1753,15 @@
[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] 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 @@ -1792,6 +1820,15 @@
[b]Note:[/b] This method is implemented on Android, iOS, Web, macOS, and Linux (Wayland).
</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].
</description>
</method>
<method name="screen_get_size" qualifiers="const">
<return type="Vector2i" />
<param index="0" name="screen" type="int" default="-1" />
Expand All @@ -1806,6 +1843,15 @@
Returns the portion of the screen that is not obstructed by a status bar in pixels. See also [method screen_get_size].
</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.
[b]Note:[/b] Requires support for [constant FEATURE_HDR].
[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 @@ -2116,6 +2162,22 @@
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_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 @@ -2211,6 +2273,29 @@
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 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_using_screen_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] is using the screen's luminance for 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 @@ -2283,6 +2368,60 @@
Enables or disables the given window's given [param flag]. See [enum WindowFlags] for possible values and their behavior.
</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] Ignored if [method window_is_hdr_output_using_screen_luminance] is [code]true[/code].
</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] Ignored if [method window_is_hdr_output_using_screen_luminance] is [code]true[/code].
</description>
</method>
<method name="window_set_hdr_output_use_screen_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 use the screen's luminance for HDR output.
While this is enabled, the window will ignore attempts to set luminance values.
[b]Note:[/b] Requires support for [constant FEATURE_HDR].
</description>
</method>
<method name="window_set_ime_active">
<return type="void" />
<param index="0" name="active" type="bool" />
Expand Down Expand Up @@ -2596,6 +2735,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
24 changes: 24 additions & 0 deletions doc/classes/ProjectSettings.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -937,6 +937,27 @@
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/enabled" type="bool" setter="" getter="" default="false">
If [code]true[/code], enables HDR output on supported platforms, 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.
</member>
<member name="display/window/hdr/max_luminance" type="float" setter="" getter="" default="1000.0">
Sets the maximum luminance of the display in nits (cd/m²) when HDR is enabled.
</member>
<member name="display/window/hdr/prefer_high_precision" type="bool" setter="" getter="" default="false">
If [code]true[/code], uses 16 bit per color buffers for the frame buffer when HDR is enabled.
If [code]false[/code], uses 10 bit per color buffers, with 2 bits for alpha, for the frame buffer when HDR is enabled.
This may improve color precision and reduce banding in the final image, but will use more memory and may reduce performance.
If transparent backgrounds are enabled, you may want to enable this setting to enable smooth blending of HDR content.
</member>
<member name="display/window/hdr/reference_luminance" type="float" setter="" getter="" default="200.0">
Sets the SDR reference luminance of the display in nits (cd/m²) when HDR is enabled.
This is used to scale the HDR effect to ensure sRGB content looks the same in both SDR and HDR.
</member>
<member name="display/window/hdr/use_screen_luminance" type="bool" setter="" getter="" default="true">
If [code]true[/code], uses the screen's luminance as reported by the display server to set luminance for the window.
If information is missing for the display, will fall back to luminance values set in project settings.
</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 Expand Up @@ -3340,6 +3361,9 @@
[b]Note:[/b] This setting will have no effect when using the Compatibility renderer, which always renders in low dynamic range for performance reasons.
[b]Note:[/b] This property is only read when the project starts. To toggle HDR 2D at runtime, set [member Viewport.use_hdr_2d] on the root [Viewport].
</member>
<member name="rendering/viewport/tonemap_to_window" type="bool" setter="" getter="" default="true">
If [code]true[/code], enables [member Viewport.tonemap_to_window] on the root viewport.
</member>
<member name="rendering/viewport/transparent_background" type="bool" setter="" getter="" default="false">
If [code]true[/code], enables [member Viewport.transparent_bg] on the root viewport. This allows per-pixel transparency to be effective after also enabling [member display/window/size/transparent] and [member display/window/per_pixel_transparency/allowed].
</member>
Expand Down
31 changes: 31 additions & 0 deletions doc/classes/RenderingDevice.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -758,6 +758,22 @@
Returns [code]true[/code] if implementation supports using a texture of [param format] with the given [param sampler_filter].
</description>
</method>
<method name="screen_get_color_format" qualifiers="const">
<return type="int" enum="RenderingDevice.DataFormat" />
<param index="0" name="screen" type="int" default="0" />
<description>
Returns the color format of the given screen.
[b]Note:[/b] Only the main [RenderingDevice] returned by [method RenderingServer.get_rendering_device] has a format. If called on a local [RenderingDevice], this method prints an error and returns [constant DATA_FORMAT_MAX].
</description>
</method>
<method name="screen_get_color_space" qualifiers="const">
<return type="int" enum="RenderingDevice.ColorSpace" />
<param index="0" name="screen" type="int" default="0" />
<description>
Returns the color space of the given screen.
[b]Note:[/b] Only the main [RenderingDevice] returned by [method RenderingServer.get_rendering_device] has a format. If called on a local [RenderingDevice], this method prints an error and returns [constant COLOR_SPACE_MAX].
</description>
</method>
<method name="screen_get_framebuffer_format" qualifiers="const">
<return type="int" />
<param index="0" name="screen" type="int" default="0" />
Expand Down Expand Up @@ -1903,6 +1919,18 @@
<constant name="DATA_FORMAT_MAX" value="232" enum="DataFormat">
Represents the size of the [enum DataFormat] enum.
</constant>
<constant name="COLOR_SPACE_SRGB_LINEAR" value="0" enum="ColorSpace">
Color space using Rec 709 primaries and linear gamma.
</constant>
<constant name="COLOR_SPACE_SRGB_NONLINEAR" value="1" enum="ColorSpace">
Color space using Rec 709 primaries and non-linear sRGB gamma.
</constant>
<constant name="COLOR_SPACE_HDR10_ST2084" value="2" enum="ColorSpace">
Color space using Rec 2020 primaries and the ST 2084 transfer function.
</constant>
<constant name="COLOR_SPACE_MAX" value="3" enum="ColorSpace">
Represents the size of the [enum ColorSpace] enum.
</constant>
<constant name="BARRIER_MASK_VERTEX" value="1" enum="BarrierMask" is_bitfield="true">
Vertex shader barrier mask.
</constant>
Expand Down Expand Up @@ -2489,6 +2517,9 @@
<constant name="SUPPORTS_BUFFER_DEVICE_ADDRESS" value="6" enum="Features">
Features support for buffer device address extension.
</constant>
<constant name="SUPPORTS_HDR_OUTPUT" value="7" 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
8 changes: 8 additions & 0 deletions doc/classes/RenderingServer.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4192,6 +4192,14 @@
[b]Note:[/b] When the 3D scaling mode is set to FSR 1.0, this value is used to adjust the automatic mipmap bias which is calculated internally based on the scale factor. The formula for this is [code]-log2(1.0 / scale) + mipmap_bias[/code].
</description>
</method>
<method name="viewport_set_tonemap_to_screen">
<return type="void" />
<param index="0" name="viewport" type="RID" />
<param index="1" name="enabled" type="bool" />
<description>
If [code]true[/code], the viewport will tonemap its content to the window's HDR output luminance range, if HDR output is enabled.
</description>
</method>
<method name="viewport_set_transparent_background">
<return type="void" />
<param index="0" name="viewport" type="RID" />
Expand Down
4 changes: 4 additions & 0 deletions doc/classes/Viewport.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -440,6 +440,10 @@
[b]Note:[/b] If [member scaling_3d_scale] is lower than [code]1.0[/code] (exclusive), [member texture_mipmap_bias] is used to adjust the automatic mipmap bias which is calculated internally based on the scale factor. The formula for this is [code]log2(scaling_3d_scale) + mipmap_bias[/code].
To control this property on the root viewport, set the [member ProjectSettings.rendering/textures/default_filters/texture_mipmap_bias] project setting.
</member>
<member name="tonemap_to_window" type="bool" setter="set_tonemap_to_window" getter="is_tonemapping_to_window" default="false">
If [code]true[/code], the viewport will tonemap its content to the window's HDR output luminance range, if HDR output is enabled.
This is useful for viewports that are not the root of the window, but still need their content to adjust to the capabilities of the display.
</member>
<member name="transparent_bg" type="bool" setter="set_transparent_background" getter="has_transparent_background" default="false">
If [code]true[/code], the viewport should render its background as transparent.
</member>
Expand Down
Loading
Loading