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 CanvasItem

Shaders de CanvasItem são usados para desenhar todos os elementos 2D no Godot. Isso inclui todos os nós que herdam de CanvasItems e todos os elementos de GUI.

Shaders de CanvasItem contêm menos variáveis integradas e funcionalidades do que os Shaders espaciais (Spatial), mas mantêm a mesma estrutura básica com funções processadoras de vértice, fragmento e luz.

Modos de renderização

Modo de renderização	Descrição
blend_mix	Modo de mesclagem Mix (alfa é transparência), padrão.
blend_add	Modo de mesclagem Aditivo (additive).
blend_sub	Modo de mesclagem Subtrativo (subtractive).
blend_mul	Modo de mesclagem Multiplicativo (multiplicative).
blend_premul_alpha	Alfa previamente multiplicado.
blend_disabled	Desativa a mesclagem (blending), os valores (incluindo o alfa) são gravados como estão.
unshaded	O resultado é apenas o albedo. Nenhum cálculo de iluminação/sombreamento acontece no material.
light_only	Desenha apenas na passagem de luz (light pass).
skip_vertex_transform	`VERTEX` precisa ser transformado manualmente na função `vertex()`.
world_vertex_coords	`VERTEX` é modificado em coordenadas do mundo (world coordinates) em vez de locais.

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. Valores marcados como inout fornecem um valor padrão sensível e podem opcionalmente ser gravados. Samplers não podem ser gravados, portanto não são marcados.

Nem todas as funções integradas (built-ins) estão disponíveis em todas as funções de processamento. Para acessar uma função integrada de vértice a partir da função fragment(), você pode usar um varying. O mesmo se aplica para acessar funções integradas de fragmento a partir da função light().

Built-ins globais

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

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

Vertex embutidos

Os dados dos vértices (VERTEX) são apresentados no espaço local (coordenadas de pixel, relativas à origem do Node2D). Se não forem gravados, esses valores não serão modificados e serão passados adiante exatamente como vieram.

O usuário pode desativar a transformação integrada de modelo para o mundo (as transformações de mundo para a tela e de projeção ainda ocorrerão mais tarde) e fazê-la manualmente com o seguinte código:

shader_type canvas_item;
render_mode skip_vertex_transform;

void vertex() {

    VERTEX = (MODEL_MATRIX * vec4(VERTEX, 0.0, 1.0)).xy;
}

Outros elementos integrados, como UV e COLOR, também são passados para a função fragment() se não forem modificados.

Para instanciação, a variável INSTANCE_CUSTOM contém os dados personalizados da instância. Ao usar partículas, essa informação geralmente é:

x: Ângulo de rotação em radianos.
y: Fase durante o tempo de vida (0.0 a 1.0).
z: Quadro da animação.

Integrado	Descrição
in mat4 MODEL_MATRIX	Transformação do espaço local para o espaço do mundo. O espaço do mundo corresponde às coordenadas que você normalmente usa no editor.
in mat4 CANVAS_MATRIX	Transformação do espaço do mundo para o espaço da tela (canvas space). No espaço da tela, a origem fica no canto superior esquerdo da tela e as coordenadas variam de `(0.0, 0.0)` até o tamanho da viewport.
in mat4 SCREEN_MATRIX	Transformação do espaço de tela (canvas space) para o espaço de corte (clip space). No espaço de corte, as coordenadas variam de `(-1.0, -1.0)` a `(1.0, 1.0).`
in int INSTANCE_ID	ID da instância para instanciação.
in vec4 INSTANCE_CUSTOM	Dados personalizados da instância.
in bool AT_LIGHT_PASS	Sempre `false`.
in vec2 TEXTURE_PIXEL_SIZE	Tamanho de pixel normalizado da textura 2D padrão. Para um Sprite2D com uma textura de tamanho 64×32 pixels, `TEXTURE_PIXEL_SIZE` = `vec2(1.0 / 64.0, 1.0 / 32.0)`.
inout vec2 VERTEX	Posição do vértice, no espaço local.
in int VERTEX_ID	O índice do vértice atual no buffer de vértices.
inout vec2 UV	Coordenadas de textura normalizadas. Variam de `0.0` a `1.0`.
inout vec4 COLOR	Cor proveniente da primitiva do vértice multiplicada pela propriedade modulate do CanvasItem multiplicada pela propriedade self_modulate do CanvasItem.
inout float POINT_SIZE	Tamanho do ponto para desenho de pontos.
in vec4 CUSTOM0	Valor personalizado da primitiva do vértice.
in vec4 CUSTOM1	Valor personalizado da primitiva do vértice.

Fragmentos embutidos

COLOR e TEXTURE

A variável integrada COLOR é usada para algumas coisas:

Na função vertex(), COLOR contém a cor da primitiva do vértice multiplicada pela propriedade modulate do CanvasItem multiplicada pela propriedade self_modulate do CanvasItem.

Na função fragment(), o valor de entrada COLOR é esse mesmo valor multiplicado pela cor da TEXTURE padrão (se houver).

Na função fragment(), COLOR também é a saída final.

Certos nós (por exemplo, Sprite2D) exibem uma textura por padrão, por exemplo, texture. Ao usar uma função fragment() personalizada, você tem algumas opções de como amostrar essa textura.

Para ler apenas o conteúdo da textura padrão, ignorando a COLOR do vértice:

void fragment() {
  COLOR = texture(TEXTURE, UV);
}

Para ler o conteúdo da textura padrão multiplicado pela COLOR do vértice:

void fragment() {
  // Equivalent to an empty fragment() function, since COLOR is also the output variable.
  COLOR = COLOR;
}

Para ler apenas a COLOR do vértice na função fragment(), ignorando a textura principal, você deve passar COLOR como uma varying e, em seguida, lê-la na função fragment():

varying vec4 vertex_color;
void vertex() {
  vertex_color = COLOR;
}
void fragment() {
  COLOR = vertex_color;
}

NORMAL

Da mesma forma, se um mapa de normais for usado no CanvasTexture, o Godot o usará por padrão e atribuirá seu valor à variável integrada NORMAL. Se você estiver usando um mapa de normais voltado para 3D, ele aparecerá invertido. Para usá-lo em seu shader, você deve atribuí-lo à propriedade NORMAL_MAP. O Godot cuidará de convertê-lo para uso em 2D e de sobrescrever a variável NORMAL.

NORMAL_MAP = texture(NORMAL_TEXTURE, UV).rgb;

Integrado	Descrição
in vec4 FRAGCOORD	Coordenada do centro do pixel. No espaço da tela. `xy` especifica a posição na viewport. O canto superior esquerdo da viewport é a origem, `(0.0, 0.0)`. O canto inferior direito da viewport é `(1.0, 1.0)`.
in vec2 SCREEN_PIXEL_SIZE	Tamanho dos pixels individuais. Equivalente ao inverso da resolução.
in vec4 REGION_RECT	Área visível da região do sprite no formato `(x, y, largura, altura)`. Varia de acordo com a propriedade `region_enabled` do Sprite2D. Os valores são normalizados; por exemplo, uma região de 600×400 em uma textura de 1000×800 com um deslocamento (offset) de 100×100 seria `vec4(0.1, 0.125, 0.6, 0.5)`. Os valores podem exceder o intervalo de 0.0 a 1.0 se o deslocamento X/Y for negativo ou se o tamanho exceder o tamanho da textura.
in vec2 POINT_COORD	Coordenada para desenhar pontos no intervalo de 0.0 a 1.0.
sampler2D TEXTURE	Textura 2D padrão.
in vec2 TEXTURE_PIXEL_SIZE	Tamanho de pixel normalizado da textura 2D padrão. Para um Sprite2D com uma textura de tamanho 64×32 pixels, `TEXTURE_PIXEL_SIZE` = `vec2(1.0 / 64.0, 1.0 / 32.0)`.
in bool AT_LIGHT_PASS	Sempre `false`.
sampler2D SPECULAR_SHININESS_TEXTURE	Textura de brilho especular (specular shininess) deste objeto.
in vec4 SPECULAR_SHININESS	Cor do brilho especular, conforme amostrada da textura.
in vec2 UV	UV vinda da função `vertex()`. Para um Sprite2D com a região ativada (region enabled), isso amostrará a textura inteira. Use `REGION_RECT` em vez disso para amostrar apenas a região definida nas propriedades do Sprite2D.
in vec2 SCREEN_UV	Coordenada UV da tela para o pixel atual.
sampler2D SCREEN_TEXTURE	Removido no Godot 4. Use um `sampler2D` com `hint_screen_texture` em vez disso.
inout vec3 NORMAL	Normal lida de `NORMAL_TEXTURE`. Gravável.
sampler2D NORMAL_TEXTURE	Textura de normais 2D padrão.
out vec3 NORMAL_MAP	Configura mapas de normais voltados para 3D para uso em 2D. Se usado, substitui `NORMAL`.
out float NORMAL_MAP_DEPTH	Profundidade do mapa de normais para escalonamento.
inout vec2 VERTEX	Posição do pixel no espaço da tela.
inout vec2 SHADOW_VERTEX	O mesmo que `VERTEX`, mas pode ser gravado para alterar as sombras.
inout vec3 LIGHT_VERTEX	O mesmo que `VERTEX`, mas pode ser gravado para alterar a iluminação. O componente Z representa a altura.
inout vec4 COLOR	`COLOR` vinda da função `vertex()` multiplicada pela cor da `TEXTURE`. Também é o valor da cor de saída.

Built-ins de iluminação

As funções processadoras de luz funcionam de maneira diferente no Godot 4.x em comparação ao Godot 3.x. No Godot 4.x, toda a iluminação é feita durante a passagem de desenho regular. Em outras palavras, o Godot não desenha mais o objeto novamente para cada luz.

Use o modo de renderização unshaded se você não quiser que a função light() seja executada. Use o modo de renderização light_only se você quiser ver apenas o impacto da iluminação em um objeto; isso pode ser útil quando você quer que o objeto seja visível apenas onde for coberto pela luz.

Se você definir uma função light(), ela substituirá a função de luz integrada, mesmo que sua função de luz esteja vazia.

Abaixo está um exemplo de um shader de luz que leva em consideração o mapa de normais de um CanvasItem:

void light() {
  float cNdotL = max(0.0, dot(NORMAL, LIGHT_DIRECTION));
  LIGHT = vec4(LIGHT_COLOR.rgb * COLOR.rgb * LIGHT_ENERGY * cNdotL, LIGHT_COLOR.a);
}

Integrado	Descrição
in vec4 FRAGCOORD	Coordenada do centro do pixel. No espaço da tela. `xy` especifica a posição na viewport. O canto superior esquerdo da viewport é a origem, `(0.0, 0.0)`. O canto inferior direito da viewport é `(1.0, 1.0)`.
in vec3 NORMAL	Normal de entrada.
in vec4 COLOR	Cor de entrada. Esta é a saída da função `fragment()`.
in vec2 UV	UV vinda da função `vertex()`, equivalente à UV na função `fragment()`.
sampler2D TEXTURE	Textura atual em uso para o CanvasItem.
in vec2 TEXTURE_PIXEL_SIZE	Tamanho de pixel normalizado da `TEXTURE`. Para um Sprite2D com uma `TEXTURE` de tamanho 64×32 pixels, `TEXTURE_PIXEL_SIZE` = `vec2(1.0 / 64.0, 1.0 / 32.0)`.
in vec2 SCREEN_UV	Coordenada UV da tela para o pixel atual.
in vec2 POINT_COORD	UV para o Point Sprite.
in vec4 LIGHT_COLOR	Color of the Light2D. If the light is a PointLight2D, it's multiplied by the light's texture.
in float LIGHT_ENERGY	Multiplicador de energia da Light2D.
in vec3 LIGHT_POSITION	Posição da Light2D no espaço da tela. Se estiver usando uma DirectionalLight2D, isso será sempre `(0.0, 0.0, 0.0)`.
in vec3 LIGHT_DIRECTION	Direção da Light2D no espaço da tela.
in bool LIGHT_IS_DIRECTIONAL	`true` se esta passagem for uma DirectionalLight2D.
in vec3 LIGHT_VERTEX	Posição do pixel, no espaço da tela conforme modificado na função `fragment()`.
inout vec4 LIGHT	Cor de saída para este Light2D.
in vec4 SPECULAR_SHININESS	Brilho especular, conforme definido na textura do objeto.
out vec4 SHADOW_MODULATE	Multiplica as sombras projetadas neste ponto por esta cor.

Funções SDF

Existem algumas funções adicionais implementadas para amostrar uma textura de Campo de Distância Assinado gerada automaticamente. Essas funções estão disponíveis nas funções fragment() e light() dos shaders de CanvasItem. Funções personalizadas também podem usá-las, desde que sejam chamadas a partir de funções suportadas.

O campo de distância sinalizado é gerado a partir dos nós LightOccluder2D presentes na cena com a propriedade SDF Collision ativada (que é o padrão). Veja a documentação de Luzes e sombras 2D para mais informações.

Função	Descrição
float texture_sdf (vec2 sdf_pos)	Realiza uma busca na textura SDF.
vec2 texture_sdf_normal (vec2 sdf_pos)	Calcula uma normal a partir da textura SDF.
vec2 sdf_to_screen_uv (vec2 sdf_pos)	Converte um SDF para UV de tela.
vec2 screen_uv_to_sdf (vec2 uv)	Converte UV de tela para um SDF.