HDR-вывод: настройка и диагностика — документация

Запрос и фактический режим окна, Windows/D3D12, HDR 2D, tonemapping и проверка ограничений.

HDR-вывод позволяет экрану показывать значения яркости выше опорного белого. Внутренний HDR-рендеринг, свечение и HDR-вывод — разные вещи: красивое освещение работает и на SDR-экране. Включённый Glow не доказывает, что окно выводит HDR.

Настроить проект

Включите HDR для нужного дисплея в операционной системе. Окно должно находиться на этом дисплее.
В Project Settings включите Advanced Settings. Задайте rendering/renderer/rendering_method: forward_plus или mobile. Compatibility для этого сценария не подходит.
В Windows задайте rendering/rendering_device/driver.windows = d3d12 и перезапустите редактор. В текущих исходниках значение по умолчанию — vulkan; Windows/Vulkan явно сообщает об отсутствии поддержки HDR-вывода. Наличие HDR-монитора этого ограничения не снимает. Это выбор графического драйвера, а не display/display_server/driver.
Включите rendering/viewport/hdr_2d и display/window/hdr/request_hdr_output. Первая настройка сохраняет расширенный диапазон 2D, вторая запрашивает HDR для основного окна. При запросе HDR корневой viewport автоматически получает HDR 2D, но явная настройка устраняет предупреждение и делает намерение проекта понятным.
Для дополнительных нативных окон задайте Window.HdrOutputRequested. Для промежуточных SubViewport, которым нужен расширенный диапазон, включите Viewport.UseHdr2D. Одна настройка корневого окна не настраивает все текстуры промежуточного рендера.
Проверьте активные ресурсы Environment. Для расширенного диапазона используйте Linear, Reinhardt или Agx. Filmic и Aces сжимают результат в SDR. Уберите Glow Blend Mode = Soft Light и LUT в Adjustments → Color Correction: эти операции не сохраняют расширенный диапазон.

На других платформах проверяйте поддержку через API окна: она зависит от display server, графического драйвера и текущего экрана. Не переносите Windows-настройку d3d12 на другую ОС. Для Linux важен выбор Wayland вместо X11; наличие Wayland само по себе ещё не подтверждает поддержку композитором и поверхностью окна. На Apple-платформах проверяйте Metal и поддержку конкретного устройства. Изменение драйвера требует перезапуска.

Проверить фактический режим

HdrOutputRequested — запрос. Это не доказательство включения HDR. Для нативного окна различайте:

Проверка	Что показывает
`WindowIsHdrOutputSupported(id)`	Поддерживает ли текущая комбинация устройства, драйвера, окна и экрана HDR-вывод.
`WindowIsHdrOutputRequested(id)`	Был ли принят запрос HDR для окна.
`WindowIsHdrOutputEnabled(id)`	Включён ли вывод сейчас.
`Window.GetOutputMaxLinearValue()`	Доступный верхний линейный уровень относительно опорного белого. В SDR равен 1.

Сохраните следующий класс в HdrStatus.cs. Из скрипта внутри дерева вызовите 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());
    }
}

В тесте текущего Windows/Forward+/Vulkan результат — supported=False; requested=False; enabled=False; maxLinear=1. Это ожидаемое ограничение этого драйвера. Для встроенного окна без нативного ID проверяйте содержащее нативное окно, а не передавайте -1 в DisplayServer.

В Game рядом с размером появляется HDR, когда редактор получает включённое состояние запущенной игры. Число в скобках — верхний линейный уровень. Меню окна показывает Request HDR Output, когда display server и renderer поддерживают запрос. Его галочка также не заменяет проверку WindowIsHdrOutputEnabled.

Сохранить освещение и детали

Опорный белый имеет линейное значение 1. На Windows доступный верхний уровень вычисляется как максимум из 1 и отношения максимальной яркости экрана к опорной. Значение может измениться при переносе окна, изменении настроек дисплея или яркости; используйте Window.OutputMaxLinearValueChanged. Значение 1 само по себе не доказывает, что HDR выключен: проверяйте также enabled.

Не умножайте освещение сцены, эмиссию всех материалов и силу Glow на этот уровень: иначе одна сцена будет освещена по-разному на разных экранах. Сохраняйте значения сцены и используйте tonemapping. Reinhardt учитывает TonemapWhite и доступный выходной диапазон, Agx — TonemapAgxWhite; Linear не сжимает сцену. Яркость UI и отдельных бликов настраивайте отдельно от освещения мира.

Если результат неправильный

Симптом	Действие
Renderer не поддерживает HDR	В Windows проверьте D3D12 и перезапуск. Forward+ сам по себе недостаточен.
Запрос есть, enabled = false	Проверьте HDR в ОС и экран, на котором находится окно; прочитайте предупреждения Output.
Значения обрезаются выше 1	Проверьте промежуточные viewport, Filmic/Aces, Soft Light и color-correction LUT.
Картинка слишком яркая	Проверьте экспозицию, tonemapping и опорную яркость; не компенсируйте проблему умножением света на возможности монитора.
Нет HDR на скриншоте PNG	Обычный SDR-снимок не подтверждает диапазон физического HDR-вывода. Сверяйте API и сам HDR-дисплей.

Проверены текущие исходники и диагностический C#-пример на Windows/Vulkan в SDR. Реальный HDR-монитор, D3D12-вывод, калибровка и другие платформы этим тестом не подтверждены.