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...

Output HDR

L'output HDR è una funzionalità che consente di presentare visuali ad alta gamma dinamica (HDR) su schermi compatibili con HDR. L'output HDR non deve essere confuso con il rendering interno in HDR utilizzato da Godot sia per l'output a gamma dinamica standard (SDR) sia per l'output HDR.

L'output HDR è supportato su iOS, Linux (Wayland), macOS, visionOS e Windows. Non è supportato su Android, Linux (X11) o web.

Abilitare output HDR nel proprio progetto

È possibile abilitare l'output HDR in qualsiasi progetto, nuovo o esistente, seguendo questi passaggi:

1. Assicurarsi che nessuna risorsa Environment utilizzi funzionalità esclusive per SDR:

• Tonemap Mode: Filmic o ACES

• Glow Blend Mode: Soft Light

• Adjustments: Color Correction

2. Configura l'impostazione del progetto Renderer su mobile o forward_plus.

3. Configura l'impostazione avanzata del progetto Rendering Device Driver su metal per iOS e d3d12 per Windows.

4. Configura l'impostazione avanzata del progetto Display Server Driver.linuxbsd su wayland e abilita l'impostazione dell'editor Prefer Wayland.

5. Abilita l'impostazione del progetto HDR 2D e abilita use_hdr_2d per tutti i nodi SubViewport e Window che dovrebbero supportare l'output HDR.

6. Abilita l'impostazione del progetto Request HDR Output e abilita hdr_output_requested per tutti gli altri nodi Window che dovrebbero supportare l'output HDR.

7. [Opzionale] Fornire impostazioni per l'HDR nel gioco copiando l'esempio dal progetto demo di output HDR nel proprio progetto.

Nota

Alcune di queste impostazioni potrebbero essere già configurate correttamente per l'output HDR nel progetto. Ad esempio, il driver del dispositivo di rendering di Windows è impostato su d3d12 nei progetti creati a partire da Godot 4.6, ma si dovrà cambiare se il progetto è stato creato con una versione precedente di Godot.

Utilizzare l'output HDR in Godot

Prova il progetto demo di output HDR come primo passo per usare l'output HDR in Godot. Questa demo contiene esempi dei concetti descritti in questa pagina e aiuterà a verificare che il tuo ambiente di sviluppo sia configurato correttamente per l'output HDR.

Output HDR nell'editor Godot

The Godot editor will use HDR output for its main window when the Request HDR Output project setting has been enabled. You can tell if your game is running in SDR or HDR output mode based on the text on the right side of game view toolbar: Your game is running in HDR mode when the text "HDR" appears next to the window size.

Il numero tra parentesi accanto al testo "HDR" è il valore lineare massimo di output corrente, descritto nelle sezioni seguenti. È possibile cambiare la proprietà Window.hdr_output_requested del gioco nel menu delle opzioni della finestra di gioco:

Fondamenta dell'output HDR

Godot utilizza il paradigma Extended Dynamic Range (EDR) per l'output HDR. Mentre l'output SDR permette di visualizzare colori con i loro componenti compresi tra 0.0 e 1.0, l'output HDR permette valori maggiori di 1.0. Il valore massimo visualizzabile è fornito da Window.get_output_max_linear_value() e questo metodo è valido sia per SDR sia per HDR.

Nota

Questi grafici sono presentati come immagini SDR che non contengono colori HDR. Per compensare questa limitazione, alle barre in scala di grigi lungo ciascun asse è stato applicato un effetto di bagliore per rappresentare i valori fuori dalla gamma SDR. Il "valore massimo di output" in questo grafico rappresenta il valore massimo dei componenti di colore lineare restituito da Window.get_output_max_linear_value().

Progettare per l'output HDR

Esistono due approcci principali per sfruttare al meglio l'output HDR: usare il valore lineare massimo di output e usare la mappatura dei toni.

Sebbene sia possibile usare entrambi gli approcci nello stesso progetto, la mappatura dei toni si dovrebbe usare per produrre output HDR da una Viewport che utilizza un'illuminazione che supera le capacità di uno schermo SDR, illuminazione indiretta, illuminazione globale, materiali emissivi, effetti di post-elaborazione o qualsiasi altra tecnica che utilizzi i valori dei colori nella scena.

Il valore lineare massimo di output si dovrebbe usare solo per presentare i colori direttamente sullo schermo senza mappatura dei toni e senza influenzare l'illuminazione, gli effetti di post-elaborazione o i colori circostanti. Questo rende il valore lineare massimo di output particolarmente adatto per i nodi CanvasItem o materiali non ombreggiati in una scena senza illuminazione o con un'illuminazione basilare che non supera le capacità di uno schermo SDR.

La proprietà Viewport.own_world_3d può servire per separare quali Viewport sono influenzate dalla mappatura dei toni e da altri effetti di WorldEnvironment.

Utilizzare il valore lineare massimo di output

In un gioco tradizionale con solo SDR, la presentazione più brillante di un colore è limitata dalla componente rossa, verde o blu del colore, che raggiunge un valore massimo di 1.0. Quando si usa uno schermo HDR moderno, questa limitazione non si applica più e le componenti di colore maggiori di 1.0 si possono presentare accuratamente. Godot fornisce il valore massimo delle componenti di colore presentabile dallo schermo tramite output max linear value. Questo valore si può usare sia in SDR sia in HDR, il che facilita creare un gioco per entrambe le modalità di output senza dover cambiare il comportamento in base all'attivazione dell'output HDR.

Il valore lineare massimo di output) può cambiare spesso quando il giocatore regola la luminosità del dispositivo, abilita o disabilita l'output HDR sul dispositivo o sposta la finestra di gioco tra gli schermi, quindi è importante recuperare questo valore a ogni frame o usare il segnale output_max_linear_value_changed. Il valore sarà sempre uguale a 1.0 in modalità SDR e potrebbe essere uguale a 1.0 anche quando l'output HDR è abilitato e il giocatore ha regolato lo schermo alla sua luminosità massima.

È ideale utilizzare questo valore lineare massimo di output con "evidenziazioni" ed effetti speciali che sono brevi o coinvolgono una piccola porzione dello schermo; se la maggior parte dello schermo appare a questa luminosità massima per un periodo prolungato, il gioco apparirà sgradevolmente luminoso, come se ignorasse l'impostazione di luminosità del dispositivo. Potresti anche scoprire che alcuni effetti risultano migliori se limitati a un valore lineare massimo maggiore di 1.0, ma minore del valore lineare massimo di output. Puoi leggere ulteriori informazioni su come a volte sia opportuno limitare il valore HDR massimo nel post HDR and User Interfaces del blog per sviluppatori Android.

Transforming a color to be the brightest the screen can present can be done with a script. When working with CanvasItem, it may be convenient to apply the resulting modified color to the modulate or self_modulate property with the base color of the CanvasItem set to white. The following script demonstrates this:

GDScript

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()

Il progetto demo di output HDR include versioni più avanzate di questo script ed esempi di come utilizzare questo approccio nel proprio progetto.

Utilizzare la mappatura dei toni

Per produrre output HDR senza utilizzare il valore lineare massimo di output, le tue scene avranno bisogno di valori di colore che superano quelli che uno schermo SDR può presentare, quindi è importante utilizzare un mappatore dei toni come Reinhard o AgX per gestire la visualizzazione di questi valori di scena luminosi sia sugli schermi SDR sia HDR.

Mappatura dei toni e HDR

Il ruolo principale di un mappatore dei toni è quello di ridurre la gamma dinamica di una scena naturale con una gamma dinamica molto alta di luminosità a una gamma dinamica più bassa che si possa presentare su uno schermo. I mappatori dei toni in Godot usano il valore lineare massimo di output per determinare la gamma di output che lo schermo è in grado di presentare. Ad esempio, con il mappatore dei toni Reinhard in Godot, i valori lineari di una scena compresi tra 0.0 e tonemap white sono mappati su una gamma di output compresa tra 0.0 e valore lineare massimo di output.

Con questo approccio, è possibile regolare tonemap white per assicurarsi che qualsiasi valore lineare di scena più basso di tonemap white sia visualizzato senza clipping. Ciò garantisce che i dettagli non siano persi quando si presenta l'immagine su uno schermo con una gamma dinamica più bassa rispetto alla scena originale.

Mentre questo comportamento è perfettamente stabile in SDR, dove il valore lineare massimo di output è fisso a 1.0, con HDR questo comportamento è dinamico in base alle capacità dello schermo:

Come mostrato nei grafici precedenti, il mappatore Reinhard si comporterà allo stesso modo del mappatore Linear quando il valore lineare massimo di output è uguale o superiore a tonemap white. Ciò consente di riprodurre i colori accuratamente sugli schermi HDR in grado di riprodurre i valori originali più luminosi della scena. Quando il valore lineare massimo di output è aumentato fino a superare tonemap white il bianco sarà regolato per corrispondere a questo valore lineare massimo di output.

Il mappatore dei toni AgX si comporta in modo simile a Reinhard in questo senso, ma il suo tonemap white è sempre moltiplicato per valore lineare massimo di output. Il mappatore Linear non applica alcuna mappatura dei colori; il suo tonemap white è uguale a valore lineare massimo di output in tutti gli scenari. I mappatori Filmic e ACES ignorano completamente il valore lineare massimo di output e producono sempre un'immagine nella gamma SDR.

Perché non combinare il valore lineare massimo di output con altre tecniche?

La mappatura dei toni, l'illuminazione indiretta, l'illuminazione globale e gli effetti di post-elaborazione dipendono tutti da valori di colore stabili della scena per produrre risultati coerenti e prevedibili in entrambe le modalità SDR e HDR. Se uno sviluppatore utilizza questo tipo di tecniche con una scena i cui valori di colore cambiano in base al valore lineare massimo di output, i risultati non saranno più simili per gli schermi con capacità diverse.

Ad esempio, l'intensità dell'effetto bagliore è direttamente influenzata dalla luminosità della scena. Se la luminosità della scena cambia in base al valore lineare massimo di output, anche l'intensità del bagliore cambierà: un valore lineare massimo di output maggiore produrrà un effetto bagliore più intenso, che in genere è un comportamento indesiderabile.

Absolute luminance values

Quando si utilizza l'output HDR, il valore lineare massimo di output è calcolato in base alla luminanza del bianco di riferimento e alla luminanza massima dello schermo.

Luminanza del bianco di riferimento

La luminanza del bianco di riferimento, o semplicemente luminanza di riferimento, rappresenta il valore di bianco SDR più elevato possibile. Quando un utente modifica l'impostazione della luminosità del dispositivo che produce il segnale video, come un computer desktop, un laptop o uno smartphone, sta regolando la propria luminanza di riferimento. Su uno smartphone, questa modifica può avvenire grazie alla regolazione automatica della luminosità dello schermo oppure quando l'utente la regola manualmente. Su computer desktop o portatili, esistono diversi modi per regolare la luminanza di riferimento a seconda del sistema operativo.

Questo valore è in genere compreso tra 100 e 300 nit ed è sempre rappresentato da un valore lineare massimo di output pari esattamente a 1.0. Questo valore può anche essere definito "bianco carta" o "livello di bianco SDR".

Nota

When using an external screen on Windows, the SDR content brightness HDR display setting directly controls the reference luminance value and is the primary way to adjust the brightness of the Windows desktop and Godot. When using a built-in HDR screen on Windows, changing HDR content brightness also directly controls the reference luminance, but has no effect on the brightness of the Windows desktop or Godot because a separate brightness implementation negates any effect of changes to the reference luminance.

Luminanza massima

La luminosità massima è una caratteristica degli schermi HDR. Questo valore può variare da 250 a 2.000 nit o anche di più. È comune che gli schermi esterni riportino un valore di luminosità massima più alto delle loro reali capacità, il che porta ad applicare un'evidente mappatura dei toni. Alcuni sistemi operativi per computer desktop o portatili offrono la capacità di calibrare il valore di luminosità massima usato per ciascuno schermo esterno.

Nota

When using a built-in screen on Windows, the reported maximum luminance will change as the user adjusts their laptop screen brightness while the reported reference luminance remains constant. This behavior is opposite from using an external display on Windows and adjusting the SDR content brightness HDR display setting and also opposite of other platforms.

Valore lineare massimo di output in pratica

When in HDR mode, the output max linear value will increase as the user decreases their reference luminance because more HDR headroom becomes available. Similarly, as the user increases their reference luminance, they will have less HDR headroom available and output max linear value will decrease. In some cases when using HDR mode with the highest reference luminance, output max linear value will equal 1.0, matching SDR behavior, because no HDR headroom is available.

Non tutti gli schermi sono uguali

Gli standard SDR sono stati progettati per adattarsi alle capacità degli schermi esistenti comunemente utilizzati in tutto il mondo. Gli standard HDR sono stati intenzionalmente sviluppati con l'approccio opposto: sono progettati per sfruttare le capacità di uno schermo ideale che non è ancora ampiamente disponibile.

In pratica, ciò significa che i comuni schermi HDR potrebbero eseguire internamente la loro mappatura dei toni, di gamma cromatica, o dinamica (DTM) per supportare contenuti che si estendono a una gamma cromatica e di luminanza più ampia di quella che l'hardware fisico può raggiungere. Alcuni schermi non sono in grado di presentare valori di colore molto luminosi che occupano più di una piccola porzione (dall'1% al 10%) dello schermo e, in questi casi, attenuano temporaneamente l'intera immagine o parte di essa. Queste caratteristiche possono produrre colori non rappresentativi di altri schermi, quindi è consigliabile disabilitarle, se possibile, durante lo sviluppo di un gioco con HDR. È possibile disabilitare alcune o tutte queste caratteristiche attivando la modalità HGiG sul proprio schermo o impostando la modalità dello schermo su "clip" e/o "stabile". Alcuni schermi HDR possono presentare i colori scuri o saturi diversamente rispetto ad altri; l'aspetto diverso è spesso il risultato delle tecnologie usate dallo schermo.