Attention: Here be dragons

This is the latest (unstable) version of this documentation, which may document features not available in or compatible with released stable versions of Godot.

Checking the stable version of the documentation...

Вихід HDR

Вивід HDR — це функція, яка дозволяє відображати зображення з високим динамічним діапазоном (HDR) на екранах, що підтримують HDR. Вивід HDR не слід плутати з внутрішнім рендерингом HDR, який використовується Godot як для виведення зображень зі стандартним динамічним діапазоном (SDR), так і для виведення HDR.

Вивід HDR підтримується в системах iOS, Linux (Wayland), macOS, visionOS та Windows. Він не підтримується в системах Android, Linux (X11) та у веб-версії.

Увімкнення виведення HDR у вашому проєкті

Ви можете увімкнути виведення HDR у будь-якому новому чи існуючому проєкті, виконавши такі дії:

  1. Переконайтеся, що жодні ресурси класу Environment не використовують функції, доступні лише в SDR:

  • Режим тонального маппінгу: «Кінематографічний» або ACES

  • Режим накладання «Сяйво»: «М'яке світло»

  • Налаштування: Корекція кольору

  1. Налаштуйте параметр проекту Renderer на значення mobile або forward_plus.

  2. Налаштуйте розширений параметр проекту Rendering Device Driver на значення metal для iOS та d3d12 для Windows.

  3. Встановіть для розширеного параметра проекту Display Server Driver.linuxbsd значення wayland та увімкніть параметр редактора Prefer Wayland.

  4. Увімкніть налаштування проекту HDR 2D та увімкніть use_hdr_2d для всіх SubViewports та Windows, які повинні підтримувати HDR-вивід.

  5. Увімкніть налаштування проекту Request HDR Output та активуйте hdr_output_requested для всіх інших вікон, які повинні підтримувати виведення HDR.

  6. [Необов'язково] Налаштуйте параметри HDR у грі, скопіювавши приклад із демонстраційного проєкту HDR-виводу у свій проєкт.

Примітка

Деякі з цих параметрів, можливо, вже налаштовані належним чином для виведення HDR у вашому проєкті. Наприклад, у проєктах, створених у Godot 4.6 та пізніших версіях, драйвер пристрою рендерингу Windows встановлено на d3d12, але його потрібно буде змінити, якщо проєкт було створено у старішій версії Godot.

Використання HDR-виводу в Godot

Спробуйте демо-проект з HDR-виведенням як перший крок до використання HDR-виведення в Godot. Це демо містить приклади концепцій, описаних на цій сторінці, і допоможе вам переконатися, що ваше середовище розробки правильно налаштоване для HDR-виведення.

Вивід HDR у редакторі Godot

Редактор Godot використовуватиме HDR-вивід для свого головного вікна, якщо у налаштуваннях проєкту ввімкнено параметр Request HDR Output. Ви можете визначити, чи працює ваша гра в режимі виводу SDR чи HDR, за текстом у правій частині панелі інструментів ігрового вікна: ваша гра працює в режимі HDR, коли поруч із розміром вікна з'являється текст «HDR».

../../_images/rendering_hdr_output_game_view.webp

Число в дужках поруч із написом «HDR» — це поточне максимальне лінійне значення виходу, яке описано в наступних розділах. Ви можете вмикати чи вимикати властивість гри Window.hdr_output_requested у меню налаштувань ігрового вікна:

../../_images/rendering_hdr_output_game_window_options.webp

Основи виведення HDR

Godot використовує парадигму «Розширений динамічний діапазон (EDR) <https://developer.apple.com/videos/play/wwdc2021/10161/>`__ для виведення HDR. Якщо при виведенні SDR можна відображати значення колірних компонентів у діапазоні від 0.0 до 1.0, то при виведенні HDR можливі значення, більші за 1.0. Максимальне значення, яке можна відобразити, визначається методом Window.get_output_max_linear_value(), і цей метод діє як при використанні SDR, так і при використанні HDR.

../../_images/rendering_hdr_output_fundamentals.webp

Примітка

Ці графіки представлені у вигляді зображень у форматі SDR, які не містять кольорів HDR. Щоб компенсувати це обмеження, до смуг сірого кольору вздовж кожної осі застосовано ефект світіння, який позначає значення, що виходять за межі діапазону SDR. «Максимальне вихідне значення» на цьому графіку відображає максимальне значення лінійної колірної складової, яке повертає Window.get_output_max_linear_value().

Розробка для виведення HDR

Існує два основних підходи до оптимізації виведення HDR: використання output max linear value та використання тонового маппінгу.

Хоча обидва підходи можна застосовувати в одному проєкті, тонемаппінг слід використовувати для отримання HDR-результату з Viewport, який використовує освітлення, що виходить за межі можливостей SDR-екрану, непряме освітлення, глобальне освітлення, матеріали, що випромінюють світло, ефекти постобробки або будь-які інші техніки, що використовують колірні значення сцени.

Максимальне лінійне значення виходу слід використовувати лише для відображення кольорів безпосередньо на екрані без тонового маппінгу та без впливу на освітлення, ефекти постобробки або навколишні кольори. Це робить output max linear value добре придатним для CanvasItems або незатінених матеріалів у сцені, яка не має освітлення або має базове освітлення, що не перевищує можливості екрану SDR.

Властивість Viewport.own_world_3d дозволяє визначити, на які Viewports поширюється дія тонального маппінгу та інших ефектів WorldEnvironment.

Використання максимального лінійного значення на виході

У традиційній грі, що підтримує лише SDR, максимальна яскравість кольору обмежується тим, що значення червоної, зеленої або синьої складової кольору не може перевищувати 1.0. При використанні сучасного HDR-екрану це обмеження більше не діє, і складові кольору, що перевищують 1.0, можуть відображатися точно. Godot надає максимальне значення компонента кольору, яке може відображати екран, через output max linear value. Це значення можна використовувати як у SDR, так і в HDR, що спрощує розробку гри для обох режимів виведення без необхідності змінювати поведінку залежно від того, увімкнено HDR-виведення чи ні.

Значення output max linear value може часто змінюватися, коли гравець регулює яскравість екрана, вмикає або вимикає HDR на своєму пристрої або переміщує ігрове вікно між екранами, тому важливо отримувати це значення в кожному кадрі або використовувати сигнал output max linear value changed. Це значення завжди дорівнюватиме 1.0 у режимі SDR, а також може дорівнювати 1.0, коли увімкнено HDR-вивід і гравець налаштував екран на максимальну яскравість.

Найкраще використовувати це максимальне лінійне значення виходу для «підсвічування» та спеціальних ефектів, які є короткочасними або охоплюють лише невелику частину екрана; якщо більша частина екрана буде відображатися з цією максимальною яскравістю довше, ніж протягом короткого проміжку часу, це призведе до того, що гра здаватиметься надто яскравою, нібито ігноруючи налаштування яскравості пристрою. Ви також можете помітити, що деякі ефекти виглядають найкраще, коли обмежуються максимальним лінійним значенням, яке більше за 1.0, але менше за output max linear value. Ви можете дізнатися більше про те, чому іноді бажано обмежувати максимальне значення HDR, у публікації HDR та користувацькі інтерфейси на блозі розробників Android.

Перетворити колір на найяскравіший, який може відобразити екран, можна за допомогою скрипта. При роботі з CanvasItem, може бути зручно застосувати отриманий модифікований колір до властивості modulate або self_modulate, встановивши базовий колір CanvasItem на white. Це демонструє наступний скрипт:

extends CanvasItem

# Set this to your desired color when the CanvasItem's base color is white.
@export var sdr_self_modulate: Color = Color.WHITE

# Set this to -1.0 to disable limiting the maximum color value.
@export_range(0, 20, 0.1, "or_less", "or_greater") var max_linear_value_limit: float = -1.0


func _enter_tree() -> void:
        var window: Window = get_window()
        window.output_max_linear_value_changed.connect(_on_output_max_linear_value_changed)
        _on_output_max_linear_value_changed(window.get_output_max_linear_value())


func _exit_tree() -> void:
        get_window().output_max_linear_value_changed.disconnect(_on_output_max_linear_value_changed)


func _on_output_max_linear_value_changed(output_max_linear_value: float) -> void:
        # Adjust the brightness of color to be the brightest possible, regardless
        # of SDR or HDR output, but no brighter than max_linear_value_limit.
        if max_linear_value_limit >= 0.0:
                output_max_linear_value = minf(output_max_linear_value, max_linear_value_limit)
        self_modulate = normalize_color(sdr_self_modulate, output_max_linear_value)


func normalize_color(srgb_color, output_max_linear_value = 1.0):
        # Color must be linear-encoded to use math operations.
        var linear_color = srgb_color.srgb_to_linear()
        var max_rgb_value = maxf(linear_color.r, maxf(linear_color.g, linear_color.b))
        var brightness_scale = output_max_linear_value / max_rgb_value
        linear_color *= brightness_scale
        # Undo changes to the alpha channel, which should not be modified.
        linear_color.a = srgb_color.a
        # Convert back to nonlinear sRGB encoding, which is required for Color in
        # Godot unless stated otherwise.
        return linear_color.linear_to_srgb()

Демонстраційний проект «HDR output» <https://github.com/godotengine/godot-demo-projects/tree/master/misc/hdr_output> містить вдосконалені версії цього скрипта та приклади того, як цей підхід можна застосувати у вашому проекті.

Використання тонового маппінгу

Щоб отримати HDR-вихід без використання output max linear value, ваші сцени потребуватимуть значень кольорів, які перевищують можливості екрану SDR, тому важливо використовувати тонометр, такий як Reinhard або AgX, щоб забезпечити відображення цих яскравих значень сцени як на екранах SDR, так і на екранах HDR.

Тонове відображення та HDR

Основна роль тонометра полягає в тому, щоб зменшити динамічний діапазон природної сцени з дуже високим динамічним діапазоном яскравості до меншого динамічного діапазону, який можна відобразити на екрані. Тонемапери в Godot використовують output max linear value, щоб визначити діапазон вихідних значень, який екран здатний відобразити. Наприклад, з тонемапером Reinhard в Godot, лінійні значення сцени в діапазоні від 0.0 до tonemap white відображаються у вихідному діапазоні від 0.0 до output max linear value.

../../_images/rendering_hdr_output_sdr_tonemap.webp

Завдяки такому підходу ви можете налаштувати tonemap white, щоб будь-яке лінійне значення сцени, нижче за tonemap white, відображалося без обрізання. Це гарантує, що деталі не будуть втрачені під час відображення зображення на екрані з динамічним діапазоном, меншим за динамічний діапазон вихідної сцени.

../../_images/rendering_hdr_output_tonemap_white.jpg

Хоча така поведінка є цілком стабільною в режимі SDR, де максимальне лінійне значення вихідного сигналу фіксоване на рівні 1.0, у режимі HDR вона є динамічною і залежить від можливостей екрана:

../../_images/rendering_hdr_output_hdr_tonemap.webp

Як показано на графіках вище, тональний перетворювач Reinhard буде поводитися так само, як і Linear, коли output max linear value дорівнює або перевищує tonemap white. Це дозволяє точно відтворювати кольори на HDR-екранах, здатних відтворювати оригінальні яскравіші значення сцени. Коли output max linear value збільшиться і стане вищим за tonemap white, тон-маппер «білого» буде відкориговано, щоб відповідати цьому максимальному лінійному значенню на виході.

Тонометр AgX працює аналогічно до Reinhard, але його tonemap white завжди множиться на output max linear value. Тонемаппер Linear взагалі не застосовує тонемаппінгу; його tonemap white дорівнює output max linear value у всіх сценаріях. Тонові маппери Filmic та ACES повністю ігнорують output max linear value і завжди створюють зображення в діапазоні SDR.

Чому б не поєднати метод максимального лінійного значення вихідного сигналу з іншими методами?

Тонемаппінг, непряме освітлення, глобальне освітлення та ефекти постобробки залежать від стабільних колірних значень сцени, щоб забезпечити послідовні та передбачувані результати як у режимі SDR, так і в режимі HDR. Якщо розробник застосовує такі техніки до сцени, колірні значення якої змінюються залежно від максимального лінійного значення виводу, результати на екранах з різними технічними характеристиками більше не будуть однаковими.

Наприклад, на інтенсивність ефекту світіння безпосередньо впливає яскравість сцени. Якщо яскравість сцени змінюється на основі максимального лінійного значення виходу, то інтенсивність світіння також зміниться: більше максимальне лінійне значення виходу дасть сильніший ефект світіння, що, як правило, є небажаною поведінкою.

Абсолютні значення яскравості

При використанні HDR-виходу максимальне лінійне значення виходу обчислюється на основі еталонної яскравості білого та максимальної яскравості екрана.

Еталонна яскравість білого

Еталонна яскравість білого, або просто еталонна яскравість, являє собою найяскравіше можливе значення білого в SDR. Коли користувач змінює налаштування яскравості пристрою, що генерує відеосигнал, наприклад настільного комп’ютера, ноутбука або смартфона, він просто регулює свою еталонну яскравість. На смартфоні ця зміна може відбуватися автоматично за допомогою функції автоматичного регулювання яскравості екрану, а також відбувається, коли користувач вручну налаштовує яскравість екрану. На настільних комп'ютерах або ноутбуках існують різні способи налаштування цієї еталонної яскравості залежно від операційної системи.

Зазвичай це значення становить від 100 до 300 ніт і завжди позначається як output max linear value, що дорівнює точно 1.0. Це значення також може називатися «білим кольором паперу» або «рівнем білого SDR».

Примітка

Під час використання зовнішнього екрана в Windows налаштування HDR-дисплея Яскравість HDR-контенту безпосередньо регулює базове значення яскравості та є основним способом налаштування яскравості робочого столу Windows і Godot. Під час використання вбудованого HDR-екрана в Windows зміна параметра Яскравість HDR-контенту також безпосередньо регулює базове значення яскравості, але не впливає на яскравість робочого столу Windows або Godot, оскільки окрема реалізація регулювання яскравості нівелює будь-який ефект від змін базового значення яскравості.

Максимальна яскравість

Максимальна яскравість — це характеристика HDR-екрану. Це значення може становити від 250 до 2000 ніт або навіть більше. Зовнішні екрани часто вказують значення максимальної яскравості, яке перевищує фізичні можливості екрану, що призводить до застосування екраном видимого тонового маппінгу. Деякі операційні системи для настільних комп’ютерів або ноутбуків надають можливість калібрувати значення максимальної яскравості, яке використовується для кожного зовнішнього екрану.

Примітка

Під час використання вбудованого екрана в Windows значення максимальної яскравості, що відображається, змінюється у міру регулювання користувачем яскравості екрана ноутбука, тоді як значення еталонної яскравості залишається незмінним. Така поведінка відрізняється від роботи із зовнішнім дисплеєм у Windows, де регулюється яскравість SDR-контенту у налаштуваннях HDR-дисплея, а також відрізняється від поведінки на інших платформах.

Максимальне значення лінійності на практиці

У режимі HDR значення output max linear value збільшуватиметься у міру зменшення користувачем базової яскравості, оскільки збільшується запас динамічного діапазону HDR. Аналогічно, коли користувач збільшує базову яскравість, запас динамічного діапазону HDR зменшується, і значення output max linear value також зменшується. У деяких випадках при використанні режиму HDR з найвищою еталонною яскравістю максимальне лінійне значення на виході дорівнюватиме 1.0, що відповідає поведінці SDR, оскільки запас HDR недоступний.

Не всі екрани однакові

Стандарти SDR були розроблені з урахуванням можливостей існуючих екранів, які широко використовуються в усьому світі. Стандарти HDR навпаки були розроблені з протилежним підходом: вони розраховані на використання можливостей ідеального екрану, який поки що не є широко доступним.

На практиці це означає, що звичайні HDR-екрани можуть виконувати власне внутрішнє тонове відображення, відображення колірного простору або динамічне тонове відображення (DTM) для підтримки контенту, який охоплює ширший колірний простір і діапазон яскравості, ніж це можливо для фізичного обладнання. Деякі екрани не здатні відображати дуже яскраві кольори, які займають більше ніж невелику (від 1% до 10%) частину екрану, і в такому випадку тимчасово затемнюють все зображення або його частину. Ці функції можуть створювати кольори, що не відповідають іншим екранам, тому під час розробки HDR-ігор їх краще вимкнути, якщо це можливо. Ви можете вимкнути деякі або всі ці функції, увімкнувши режим HGiG на екрані або встановивши режим екрана на «clip» та/або «stable». Деякі HDR-екрани можуть відображати темні або насичені кольори інакше, ніж інші; ця різниця у зовнішньому вигляді часто є результатом технологій екрану.