HDR output: configuration and diagnostics — documentation

Requested versus active window output, Windows/D3D12, HDR 2D, tonemapping and capability checks.

HDR output lets a display present luminance above reference white. Internal HDR rendering, glow and HDR output are separate features: detailed lighting also works on an SDR screen. Enabling Glow does not prove the window is presenting HDR.

Configure the project

Enable HDR for the intended display in the operating system. Place the window on that display.
Open Project Settings and enable Advanced Settings. Set rendering/renderer/rendering_method to forward_plus or mobile. Compatibility is unsuitable for this workflow.
On Windows, set rendering/rendering_device/driver.windows to d3d12 and restart the editor. Current source defaults to vulkan; Windows/Vulkan explicitly reports no HDR-output support. An HDR monitor does not remove that restriction. This selects the graphics driver, not display/display_server/driver.
Enable rendering/viewport/hdr_2d and display/window/hdr/request_hdr_output. The first retains extended-range 2D data; the second requests HDR for the main window. Requesting HDR automatically enables HDR 2D on the root viewport, but setting it explicitly avoids a warning and records the project’s intent.
Set Window.HdrOutputRequested for additional native windows. Enable Viewport.UseHdr2D on intermediate SubViewport instances that need extended range. Configuring the root window does not configure every intermediate render texture.
Inspect active Environment resources. Use Linear, Reinhardt or Agx for extended-range output. Filmic and Aces compress the result to SDR. Remove Glow Blend Mode = Soft Light and the Adjustments → Color Correction LUT: those operations do not preserve extended range.

On other platforms, query the window API: support depends on the display server, graphics driver and current display. Do not copy the Windows d3d12 setting to another OS. On Linux, Wayland rather than X11 matters; using Wayland alone does not establish compositor or window-surface support. On Apple platforms, check Metal and the particular device’s capabilities. Driver changes require a restart.

Check the actual mode

HdrOutputRequested is a request, not evidence that HDR is enabled. For a native window, distinguish:

Check	Meaning
`WindowIsHdrOutputSupported(id)`	Whether the current device, driver, window and display combination supports HDR output.
`WindowIsHdrOutputRequested(id)`	Whether an HDR request was accepted for this window.
`WindowIsHdrOutputEnabled(id)`	Whether output is currently enabled.
`Window.GetOutputMaxLinearValue()`	Available maximum linear level relative to reference white. Equals 1 in SDR.

Save this class as HdrStatus.cs. From a script inside the tree, call ReckfellApi.Print(HdrStatus.Describe(GetWindow()));:

C#
using System.Globalization;
using Reckfell;

public static class HdrStatus
{
    public static string Describe(Window window)
    {
        int id = window.GetWindowId();
        if (id == DisplayServer.InvalidWindowId)
            return "No native window; check the containing window.";

        return string.Format(CultureInfo.InvariantCulture,
            "supported={0}; requested={1}; enabled={2}; maxLinear={3:0.###}",
            DisplayServer.WindowIsHdrOutputSupported(id),
            DisplayServer.WindowIsHdrOutputRequested(id),
            DisplayServer.WindowIsHdrOutputEnabled(id),
            window.GetOutputMaxLinearValue());
    }
}

The current Windows/Forward+/Vulkan test reports supported=False; requested=False; enabled=False; maxLinear=1. This is the expected driver restriction. For an embedded window without a native ID, inspect the containing native window rather than passing -1 to DisplayServer.

In Game, HDR appears next to the size when the editor receives an enabled state from the running game. The parenthesized number is the maximum linear level. The window menu offers Request HDR Output when the display server and renderer support the request. Its checkmark also does not replace WindowIsHdrOutputEnabled.

Preserve lighting and detail

Reference white has linear value 1. On Windows the available maximum is the greater of 1 and the display maximum luminance divided by reference luminance. It can change when moving the window or changing display settings or brightness; use Window.OutputMaxLinearValueChanged. A value of 1 alone does not prove HDR is disabled: also check enabled.

Do not multiply scene lighting, all material emission or Glow strength by this level: the same scene would then be lit differently on different displays. Keep scene values stable and use tonemapping. Reinhardt accounts for TonemapWhite and output range, Agx for TonemapAgxWhite; Linear does not compress the scene. Adjust UI brightness and individual highlights separately from world lighting.

Diagnose an incorrect result

Symptom	Action
Renderer does not support HDR	On Windows, check D3D12 and restart. Forward+ alone is insufficient.
Requested, but enabled = false	Check OS HDR and the display containing the window; read Output warnings.
Values clip above 1	Check intermediate viewports, Filmic/Aces, Soft Light and color-correction LUTs.
Image is too bright	Check exposure, tonemapping and reference luminance; do not compensate by multiplying lights by display headroom.
No HDR in a PNG screenshot	An ordinary SDR capture does not establish physical HDR-output range. Check the API and the actual HDR display.

Current source and the diagnostic C# example were checked on Windows/Vulkan in SDR. This test does not establish real HDR-display presentation, D3D12 output, calibration or other platforms.