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...
Saída HDR
A saída HDR é um recurso que permite a apresentação de visuais de Alto Alcance Dinâmico (HDR) em telas compatíveis com HDR. A saída HDR não deve ser confundida com a renderização HDR interna que é usada pelo Godot tanto para os modos de saída de Alcance Dinâmico Padrão (SDR) quanto de saída HDR.
A saída HDR é suportada no iOS, Linux (Wayland), macOS, visionOS e Windows. Ela não é suportada no Android, Linux (X11) ou web.
Nota
Both Windows 10 and 11 support HDR output, but only Windows 11 provides an app that can be used to configure the screen’s maximum luminance that is used by the Godot editor.
On Linux, GNOME versions prior to 50 have a bug that prevents HDR output from working on Wayland. If you are using an older version of GNOME, you will need to upgrade to version 50 or later to use HDR output on Wayland.
Habilitando a saída HDR no seu projeto
Você pode ativar a saída HDR em qualquer projeto novo ou existente usando estes passos:
Certifique-se de que nenhum recurso de Environment use recursos exclusivos de SDR:
Modo de Mapeamento de Tons (Tonemap Mode): Filmic ou ACES
Modo de Mesclagem do Glow: Soft Light (Luz Suave)
Ajustes (Adjustments): Correção de Cor (Color Correction)
Configure a configuração de projeto Renderer para
mobileouforward_plus.Configure a configuração de projeto avançada Rendering Device Driver para
metalno iOS ed3d12no Windows.Configure a configuração de projeto avançada Display Server Driver.linuxbsd para
waylande ative a configuração do editor Prefer Wayland.Ative a configuração de projeto HDR 2D e habilite use_hdr_2d para todos os SubViewports e Windows que devem suportar saída HDR.
Ative a configuração de projeto Request HDR Output e habilite hdr_output_requested para todas as outras Windows que devem suportar saída HDR.
[Opcional] Forneça configurações de HDR no jogo copiando o exemplo do projeto de demonstração de saída HDR para o seu projeto.
Nota
Algumas dessas configurações já podem estar configuradas corretamente para saída HDR em seu projeto. Por exemplo, o Driver do Dispositivo de Renderização do Windows é definido como d3d12 em projetos criados no Godot 4.6 em diante, mas precisará ser alterado se o projeto tiver sido criado com uma versão mais antiga do Godot.
Usando a saída HDR no Godot
Experimente o projeto de demonstração de saída HDR como um primeiro passo para usar a saída HDR no Godot. Esta demonstração contém exemplos dos conceitos descritos nesta página e ajudará você a garantir que seu ambiente de desenvolvimento esteja configurado corretamente para saída HDR.
Saída HDR no editor do Godot
O editor do Godot usará a saída HDR para sua janela principal quando a configuração de projeto Request HDR Output tiver sido ativada. Você pode saber se seu jogo está rodando no modo de saída SDR ou HDR com base no texto no lado direito da barra de ferramentas de visualização do jogo: Seu jogo está rodando no modo HDR quando o texto "HDR" aparece ao lado do tamanho da janela.
O número entre parênteses ao lado do texto "HDR" é o valor linear máximo de saída atual, que é descrito nas seções seguintes. Você pode alternar a propriedade Window.hdr_output_requested do jogo no menu de opções da janela do jogo:
Fundamentos da saída HDR
O Godot usa o paradigma de Alcance Dinâmico Estendido (EDR) para a saída HDR. Enquanto a saída SDR permite que valores de componentes de cor entre 0.0 e 1.0 sejam exibidos, a saída HDR permite valores maiores que 1.0. O valor máximo que pode ser exibido é fornecido por Window.get_output_max_linear_value() e este método é válido ao usar SDR ou HDR.
Nota
Esses gráficos são apresentados como imagens SDR que não contêm nenhuma cor HDR. To compensar essa limitação, as barras em escala de cinza ao longo de cada eixo têm um efeito de glow (brilho) aplicado para representar valores que estão fora do alcance SDR. O "valor máximo de saída" neste gráfico representa o valor do componente de cor linear máximo retornado por Window.get_output_max_linear_value().
Projetando para saída HDR
Existem duas abordagens principais para aproveitar ao máximo a saída HDR: usar o valor linear máximo de saída e usar o mapeamento de tons (tonemapping).
Embora ambas as abordagens possam ser usadas no mesmo projeto, o mapeamento de tons deve ser usado para produzir saída HDR a partir de um Viewport que utiliza iluminação que excede as capacidades de uma tela SDR, iluminação indireta, iluminação global, materiais emissivos, efeitos de pós-processamento ou quaisquer outras técnicas que façam uso dos valores de cores na cena.
O valor linear máximo de saída deve ser usado apenas para apresentar cores diretamente na tela sem mapeamento de tons e sem influenciar a iluminação, os efeitos de pós-processamento ou as cores ao redor. Isso torna o valor linear máximo de saída bem adequado para CanvasItems ou materiais sem sombreamento (unshaded) em uma cena que não possui iluminação ou possui iluminação básica que, de outra forma, não excede as capacidades de uma tela SDR.
A propriedade Viewport.own_world_3d pode ser usada para separar quais Viewports são afetados pelo mapeamento de tons e outros efeitos de WorldEnvironment.
Usando o valor linear máximo de saída
Em um jogo tradicional apenas em SDR, a apresentação mais brilhante de uma cor é limitada por um dos componentes vermelho, verde ou azul da cor atingindo um máximo de 1.0. Ao usar uma tela HDR moderna, essa limitação não se aplica mais e os componentes de cor acima de 1.0 podem ser apresentados com precisão. O Godot fornece o valor máximo do componente de cor que pode ser apresentado pela tela através do valor linear máximo de saída. Esse valor pode ser usado tanto em SDR quanto em HDR, o que facilita a criação do seu jogo para ambos os modos de saída sem a necessidade de alterar o comportamento com base no fato de a saída HDR estar ou não ativada.
O valor linear máximo de saída pode mudar frequentemente à medida que o jogador ajusta o brilho do dispositivo, ativa ou desativa a saída HDR no dispositivo, ou move a janela do jogo entre telas, por isso é importante recuperar esse valor a cada quadro ou usar o sinal output max linear value changed. O valor sempre será igual a 1.0 no modo SDR e também pode ser igual a 1.0 quando a saída HDR estiver ativada e o jogador tiver ajustado a tela para o brilho máximo.
É melhor usar este valor linear máximo de saída com "destaques" (highlights) e efeitos especiais que sejam breves ou envolvam uma pequena parte da tela; se a maior parte da tela for apresentada com esse brilho máximo por mais do que um curto período, fará com que o jogo pareça desconfortavelmente brilhante, como se estivesse ignorando a configuração de brilho do dispositivo. Você também pode achar que alguns efeitos ficam melhores quando limitados a um valor linear máximo que seja maior que 1.0, mas menor que o valor linear máximo de saída. Você pode ler mais sobre como às vezes é desejável limitar o valor máximo de HDR na postagem HDR and User Interfaces do Android Developers Blog.
Transformar uma cor para ser a mais brilhante que a tela pode apresentar pode ser feito com um script. Ao trabalhar com CanvasItem, pode ser conveniente aplicar a cor modificada resultante à propriedade modulate ou self_modulate com a cor base do CanvasItem definida como white. O script a seguir demonstra isso:
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()
O projeto de demonstração de saída HDR inclui versões mais avançadas deste script e exemplos de como essa abordagem pode ser usada em seu projeto.
Usando Mapeamento de Tons (Tonemapping)
Para produzir saída HDR sem usar o valor linear máximo de saída, suas cenas precisarão de valores de cores que excedam o que uma tela SDR pode apresentar, por isso é importante usar um mapeador de tons (tonemapper) como Reinhard ou AgX para lidar com a exibição desses valores brilhantes da cena tanto em telas SDR quanto HDR.
Mapeamento de tons e HDR
O papel principal de um mapeador de tons é reduzir o alcance dinâmico de uma cena natural com um alcance dinâmico de brilho muito alto para um alcance dinâmico menor que possa ser apresentado em uma tela. Os mapeadores de tons no Godot usam o valor linear máximo de saída para determinar o alcance de saída que a tela é capaz de apresentar. Por exemplo, com o mapeador de tons Reinhard no Godot, os valores lineares da cena na faixa de 0.0 a tonemap white são mapeados para uma faixa de saída de 0.0 ao valor linear máximo de saída.
Com essa abordagem, você pode ajustar o tonemap white para ter certeza de que qualquer valor linear de cena abaixo de tonemap white será exibido sem cortes (clipping). Isso garante que os detalhes não sejam perdidos ao apresentar a imagem em uma tela com um alcance dinâmico menor do que a cena original.
Embora esse comportamento seja perfeitamente estável em SDR, onde o valor linear máximo de saída é fixado em 1.0, esse comportamento é dinâmico com o HDR baseado nas capacidades da tela:
Como mostrado nos gráficos acima, o mapeador de tons Reinhard se comportará da mesma forma que o mapeador de tons Linear quando o valor linear máximo de saída for igual ou superior ao tonemap white. Isso permite uma reprodução de cores precisa em telas HDR que são capazes de reproduzir os valores originais mais brilhantes da cena. Quando o valor linear máximo de saída aumentar para ser maior que o tonemap white, o tonemap white será ajustado para corresponder a esse valor linear máximo de saída.
O mapeador de tons AgX se comporta de maneira semelhante ao Reinhard nesse aspecto, mas seu tonemap white é sempre multiplicado pelo valor linear máximo de saída. O mapeador de tons Linear não aplica nenhum mapeamento de tons; seu tonemap white é igual ao valor linear máximo de saída em todos os cenários. Os mapeadores de tons Filmic e ACES ignoram o valor linear máximo de saída inteiramente e sempre produzem uma imagem na faixa SDR.
Por que não misturar o valor linear máximo de saída com outras técnicas?
O mapeamento de tons, iluminação indireta, iluminação global e efeitos de pós-processamento dependem de valores de cores de cena estáveis para produzir resultados consistentes e previsíveis nos modos SDR e HDR. Se um desenvolvedor usar esses tipos de técnicas com uma cena que possui valores de cores que mudam com base no valor linear máximo de saída, os resultados não serão mais semelhantes para telas com capacidades diferentes.
Por exemplo, a intensidade do efeito de glow é diretamente influenciada pelo brilho da cena. Se o brilho da cena mudar com base no valor linear máximo de saída, então a intensidade do glow mudará também: um valor linear máximo de saída maior produzirá um efeito de glow mais forte, o que geralmente é um comportamento indesejável.
Valores absolutos de luminância
Ao usar a saída HDR, o valor linear máximo de saída é calculado com base na luminância de branco de referência e na luminância máxima da tela.
Luminância do branco de referência
A luminância do branco de referência, ou luminância de referência para abreviar, representa o valor de branco SDR mais brilhante possível. Quando um usuário altera a configuração de brilho do dispositivo que está produzindo o sinal de vídeo, como um computador de mesa, laptop ou smartphone, ele está simplesmente ajustando sua luminância de referência. Em um smartphone, essa alteração pode acontecer automaticamente por meio do recurso de brilho automático da tela do smartphone e também acontece quando o usuário ajusta manualmente o brilho da tela. Em computadores de mesa ou laptops, existem diferentes maneiras de ajustar essa luminância de referência, dependendo do sistema operacional.
Esse valor geralmente fica em torno de 100 a 300 nits e é sempre representado por um valor linear máximo de saída de exatamente 1.0. Esse valor também pode ser chamado de "paper white" (branco papel) ou "SDR white level" (nível de branco SDR).
Nota
Ao usar uma tela externa no Windows, a configuração de exibição HDR SDR content brightness (brilho do conteúdo SDR) controla diretamente o valor da luminância de referência e é a principal maneira de ajustar o brilho do desktop do Windows e do Godot. Ao usar uma tela HDR integrada no Windows, alterar o SDR content brightness também controla diretamente a luminância de referência, mas não tem efeito no brilho do desktop do Windows ou do Godot porque uma implementação de brilho separada anula qualquer efeito de alterações na luminância de referência.
Luminância máxima
A luminância máxima é uma propriedade de uma tela HDR. Esse valor pode estar em qualquer lugar de 250 a 2.000 nits ou além. É comum que telas externas relatem um valor de luminância máxima superior às capacidades físicas da tela, o que resulta em um mapeamento de tons visível aplicado pela tela. Alguns sistemas operacionais de desktop ou laptop fornecem uma maneira de calibrar o valor de luminância máxima que é usado para cada tela externa.
Nota
Ao usar uma tela integrada no Windows, a luminância máxima relatada mudará à medida que o usuário ajusta o brilho da tela do laptop, enquanto a luminância de referência relatada permanece constante. Esse comportamento é o oposto do uso de uma tela externa no Windows e do ajuste da configuração de exibição HDR SDR content brightness, e também o oposto de outras plataformas.
Valor linear máximo de saída na prática
Quando no modo HDR, o valor linear máximo de saída aumentará à medida que o usuário diminuir sua luminância de referência, porque mais margem (headroom) HDR fica disponível. Da mesma forma, à medida que o usuário aumenta sua luminância de referência, ele terá menos margem HDR disponível e o valor linear máximo de saída diminuirá. Em alguns casos, ao usar o modo HDR com a luminância de referência mais alta, o valor linear máximo de saída será igual a 1.0, correspondendo ao comportamento SDR, porque nenhuma margem HDR está disponível.
Nem todas as telas são iguais
Os padrões SDR foram projetados para corresponder às capacidades das telas existentes que eram comumente usadas em todo o mundo. Os padrões HDR foram intencionalmente escritos com a abordagem oposta: eles foram projetados para utilizar as capacidades de uma tela ideal que ainda não está amplamente disponível.
Na prática, isso significa que telas HDR comuns podem realizar seu próprio mapeamento de tons interno, mapeamento de gama ou mapeamento de tons dinâmico (DTM) para suportar conteúdo que se estende a uma gama e faixa de luminância mais amplas do que o hardware físico pode alcançar. Algumas telas não são capazes de apresentar valores de cores muito brilhantes que preencham mais do que uma pequena parte (1% a 10%) da tela e escurecerão a imagem inteira ou parte dela temporariamente quando isso acontecer. Esses recursos podem produzir cores que não são representativas de outras telas, por isso é melhor desativá-los, se possível, ao desenvolver seu jogo em HDR. Você pode desativar alguns ou todos esses recursos ativando o modo HGiG em sua tela ou definindo o modo da tela para "clip" (recortar) e/ou "stable" (estável). Algumas telas HDR podem apresentar cores escuras ou saturadas de forma diferente de outras; essa diferença na aparência costuma ser o resultado das tecnologias de tela.