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

Shaders de céu (Sky shaders)

Shaders de céu (sky shaders) são um tipo especial de shader usado para desenhar fundos de céu e para atualizar mapas cúbicos de radiância (radiance cubemaps) que são usados para iluminação baseada em imagem (IBL). Shaders de céu possuem apenas uma função de processamento, a função sky().

Existem três locais onde o shader de céu é usado.

Primeiro, o shader de céu é usado para desenhar o céu quando você seleciona usar um Sky como plano de fundo na sua cena.
Segundo, o shader de céu é usado para atualizar o mapa cúbico de radiância ao usar o Sky para cor ambiente ou reflexos.
Terceiro, o shader de céu é usado para desenhar as passagens secundárias de menor resolução (subpasses) que podem ser usadas no plano de fundo de alta resolução ou na passagem do mapa cúbico.

No total, isso significa que o shader de céu pode ser executado até seis vezes por quadro; no entanto, na prática, será muito menos do que isso porque o mapa cúbico de radiância não precisa ser atualizado a cada quadro, e nem todas as passagens secundárias serão usadas. Você pode alterar o comportamento do shader com base de onde ele é chamado, verificando os booleanos AT_*_PASS. Por exemplo:

shader_type sky;

void sky() {
    if (AT_CUBEMAP_PASS) {
        // Sets the radiance cubemap to a nice shade of blue instead of doing
        // expensive sky calculations
        COLOR = vec3(0.2, 0.6, 1.0);
    } else {
        // Do expensive sky calculations for background sky only
        COLOR = get_sky_color(EYEDIR);
    }
}

Ao usar o shader de céu para desenhar um plano de fundo, o shader será chamado para todos os fragmentos não ocluídos na tela. No entanto, para as passagens secundárias do plano de fundo, o shader será chamado para cada pixel da passagem secundária.

Ao usar o shader de céu para atualizar o mapa cúbico de radiância, o shader de céu será chamado para cada pixel no mapa cúbico. Por outro lado, o shader só será chamado quando o mapa cúbico de radiância precisar ser atualizado. O mapa cúbico de radiância precisa ser atualizado quando qualquer um dos parâmetros do shader for atualizado. Por exemplo, se TIME for usado no shader, o mapa cúbico de radiância será atualizado a cada quadro. A lista de alterações a seguir força uma atualização do mapa cúbico de radiância:

TIME é usado.
POSITION é usado e a posição da câmera muda.
Se quaisquer propriedades LIGHTX_* forem usadas e qualquer DirectionalLight3D mudar.
If qualquer uniform for alterado no shader.
Se a tela for redimensionada e qualquer uma das passagens secundárias for usada.

Tente evitar a atualização desnecessária do mapa cúbico de radiância. Se você realmente precisar atualizar o mapa cúbico de radiância a cada quadro, certifique-se de que o seu Modo de processo do Sky esteja definido como PROCESS_MODE_REALTIME.

Observe que o modo de processo afeta apenas a renderização do mapa cúbico de radiância. O céu visível é sempre renderizado chamando o fragment shader para cada pixel. Com fragment shaders complexos, isso pode resultar em uma alta sobrecarga de renderização. Se o céu for estático (as condições listadas acima forem atendidas) ou mudar lentamente, executar o fragment shader completo a cada quadro não é necessário. Isso pode ser evitado renderizando o céu completo no mapa cúbico de radiância e lendo a partir deste mapa cúbico ao renderizar o céu visível. Com um céu completamente estático, isso significa que ele precisa ser renderizado apenas uma vez.

O código a seguir renderiza o céu completo no mapa cúbico de radiância e lê desse mapa cúbico para exibir o céu visível:

shader_type sky;

void sky() {
    if (AT_CUBEMAP_PASS) {
        vec3 dir = EYEDIR;

        vec4 col = vec4(0.0);

        // Complex color calculation

        COLOR = col.xyz;
        ALPHA = 1.0;
    } else {
        COLOR = texture(RADIANCE, EYEDIR).rgb;
    }
}

Dessa forma, os cálculos complexos acontecem apenas na passagem do mapa cúbico, que pode ser otimizada definindo o modo de processo do céu e o tamanho da radiância para obter o equilíbrio desejado entre desempenho e fidelidade visual.

Modos de renderização

As passagens secundárias (subpasses) permitem que você faça cálculos mais caros em uma resolução mais baixa para acelerar seus shaders. Por exemplo, o código a seguir renderiza nuvens em uma resolução mais baixa do que o resto do céu:

shader_type sky;
render_mode use_half_res_pass;

void sky() {
    if (AT_HALF_RES_PASS) {
        // Run cloud calculation for 1/4 of the pixels
        vec4 color = generate_clouds(EYEDIR);
        COLOR = color.rgb;
        ALPHA = color.a;
    } else {
        // At full resolution pass, blend sky and clouds together
        vec3 color = generate_sky(EYEDIR);
        COLOR = color + HALF_RES_COLOR.rgb * HALF_RES_COLOR.a;
    }
}

Modo de renderização	Descrição
use_half_res_pass	Permite que o shader grave e acesse a passagem de meia resolução (half resolution pass).
use_quarter_res_pass	Permite que o shader grave e acesse a passagem de um quarto de resolução (quarter resolution pass).
disable_fog	Se usado, a névoa (fog) não afetará o céu.

Embutidos

Valores marcados como in são somente leitura. Valores marcados como out podem opcionalmente ser gravados e não conterão necessariamente valores sensíveis. Samplers não podem ser gravados, portanto não são marcados.

Built-ins globais

As funções integradas globais estão disponíveis em todos os lugares, incluindo em funções personalizadas.

Existem 4 luzes LIGHTX, acessadas como LIGHT0, LIGHT1, LIGHT2 e LIGHT3.

Integrado	Descrição
in float TIME	Tempo global desde que o motor foi iniciado, em segundos. Ele se repete a cada `3.600` segundos (o que pode ser alterado com a configuração rollover). É afetado pelo time_scale, mas não pelo congelamento (pausa). Se você precisar de uma variável `TIME` que não seja afetada pela escala de tempo, adicione seu próprio uniform global de shader e atualize-o a cada quadro.
in vec3 POSITION	Posição da câmera, no espaço do mundo.
samplerCube RADIANCE	Mapa cúbico de radiância (radiance cubemap). Só pode ser lido durante a passagem de plano de fundo (background pass). Verifique `!AT_CUBEMAP_PASS` antes de usar.
in bool AT_HALF_RES_PASS	`true` ao renderizar para a passagem de meia resolução.
in bool AT_QUARTER_RES_PASS	`true` ao renderizar para a passagem de um quarto de resolução.
in bool AT_CUBEMAP_PASS	`true` ao renderizar para o mapa cúbico de radiância.
in bool LIGHTX_ENABLED	`true` se `LIGHTX` estiver visível e na cena. Se `false`, outras propriedades de luz podem conter lixo.
in float LIGHTX_ENERGY	Multiplicador de energia para `LIGHTX`.
in vec3 LIGHTX_DIRECTION	Direção para a qual `LIGHTX` está voltada.
in vec3 LIGHTX_COLOR	Cor da `LIGHTX`.
in float LIGHTX_SIZE	Diâmetro angular de `LIGHTX` no céu. Expresso em radianos. Para referência, o sol visto da terra tem cerca de 0,0087 radianos (0,5 graus).
in float PI	Uma constante `PI` (`3.141592`). A razão entre a circunferência de um círculo e seu diâmetro e o número de radianos em uma meia volta.
in float TAU	Uma constante `TAU` (`6.283185`). Equivalente a `PI * 2` e o número de radianos em uma volta completa.
in float E	Uma constante `E` (`2.718281`). O número de Euler, a base do logaritmo natural.

Nativos de céu

Integrado	Descrição
in vec3 EYEDIR	Direção normalizada do pixel atual. Use isto como sua direção básica para efeitos procedimentais.
in vec2 SCREEN_UV	Coordenada UV da tela para o pixel atual. Usada para mapear uma textura para a tela cheia.
in vec2 SKY_COORDS	UV da esfera. Usada para mapear uma textura de panorama para o céu.
in vec4 HALF_RES_COLOR	Valor de cor do pixel correspondente a partir da passagem de meia resolução. Usa filtro linear.
in vec4 QUARTER_RES_COLOR	Valor de cor do pixel correspondente a partir da passagem de um quarto de resolução. Usa filtro linear.
out vec3 COLOR	Cor de saída.
out float ALPHA	Valor alfa de saída, só pode ser usado em passagens secundárias (subpasses).
out vec4 FOG