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

Shader CanvasItem

Gli shader di tipo CanvasItem servono per disegnare tutti gli elementi 2D in Godot. Questi includono tutti i nodi che ereditano dai CanvasItem, nonché tutti gli elementi dell'interfaccia utente grafica.

Gli shader CanvasItem contengono meno variabili integrate e funzionalità rispetto agli shader Spatial, ma mantengono la stessa struttura di base con funzioni processori di vertici, frammenti e luci.

Modalità di rendering

Modalità di rendering	Descrizione
blend_mix	Modalità di fusione mista (alfa è la trasparenza), predefinita.
blend_add	Modalità di fusione additiva.
blend_sub	Modalità di fusione sottrattiva.
blend_mul	Modalità di fusione moltiplicativa.
blend_premul_alpha	Modalità di fusione alfa premoltiplicato.
blend_disabled	Disabilita la fusione, i valori (incluso l'alfa) sono scritti così come sono.
unshaded	Il risultato è solo l'albedo. Il materiale non riceve né luci né ombre.
light_only	Disegna solo nel passaggio di luce.
skip_vertex_transform	`VERTEX` deve essere trasformato manualmente nella funzione `vertex()`.
world_vertex_coords	`VERTICE` è modificato in coordinate mondiali anziché locali.

Variabili integrate

I valori marcati come in sono di sola lettura. I valori marcati come out sono scrivibili facoltativamente e non contengono necessariamente valori sensati. I valori marcati come inout forniscono un valore predefinito sensato e sono scrivibili facoltativamente. I campionatori non sono scrivibili, quindi non sono marcati.

Non tutte le variabili integrate sono disponibili in tutte le funzioni di elaborazione. Per accedere a una variabile integrata di vertice dalla funzione fragment(), è possibile utilizzare un varying. Lo stesso vale per accedere alle variabili integrate di frammento dalla funzione light().

Variabili integrate globali

Le variabili integrate globali sono disponibili ovunque, comprese le funzioni personalizzate.

Integrato	Descrizione
in float TIME	Tempo globale dall'avvio del motore, in secondi. Si ripete ogni `3.600` secondi (che si può cambiare con l'impostazione rollover). È influenzato da time_scale ma non dalla pausa. Se è necessaria una variabile `TIME` che non sia influenzata dalla scala temporale, aggiungere il proprio uniforme di shader globale e aggiornarlo a ogni frame.
in float PI	Una costante `PI` (`3.141592`). Il rapporto tra la circonferenza di un cerchio e il suo diametro, e il numero di radianti in mezzo giro.
in float TAU	Una costante `TAU` (`6.283185`). Equivalente a `PI * 2` e al numero di radianti in un giro completo.
in float E	Una costante `E` (`2.718281`). Numero di Eulero, la base del logaritmo naturale.

Variabili integrate di vertice

I dati dei vertici (VERTEX) sono presentati nello spazio locale (coordinate in pixel, relative all'origine del Node2D). Se non vengono scritti, questi valori non saranno modificati e saranno trasmessi così come sono arrivati.

L'utente può disattivare la trasformazione integrata da modello a mondo (la trasformazione da mondo a schermo e proiezione avverrà comunque in seguito) e farlo manualmente con il seguente codice:

shader_type canvas_item;
render_mode skip_vertex_transform;

void vertex() {

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

Anche altre variabili integrate, come UV e COLOR, vengono passate alla funzione fragment() se non vengono modificate.

Per l'istanzazione, la variabile INSTANCE_CUSTOM contiene i dati personalizzati dell'istanza. Quando si utilizzano particelle, queste informazioni sono solitamente:

x: Angolo di rotazione in radianti.
y: Fase durante il ciclo di vita (da 0.0 a 1.0).
z: Fotogramma di animazione.

Integrato	Descrizione
in mat4 MODEL_MATRIX	Trasformazione da spazio locale a spazio mondiale. Lo spazio mondiale corrisponde alle coordinate che normalmente si usano nell'editor.
in mat4 CANVAS_MATRIX	Trasformazione da spazio mondiale a spazio del canvas. Nello spazio del canvas, l'origine è l'angolo in alto a sinistra dello schermo e le coordinate vanno da `(0.0, 0.0)` alle dimensioni della viewport.
in mat4 SCREEN_MATRIX	Spazio del canvas in spazio di clip. Nello spazio di clip, le coordinate vanno da `(-1.0, -1.0)` a `(1.0, 1.0).`
in int INSTANCE_ID	ID di istanza per l'istanziazione.
in vec4 INSTANCE_CUSTOM	Dati personalizzati dell'istanza.
in bool AT_LIGHT_PASS	Sempre `false`.
in vec2 TEXTURE_PIXEL_SIZE	Dimensioni normalizzate dei pixel della texture 2D predefinita. Per uno Sprite2D con una texture di 64×32 pixel, `TEXTURE_PIXEL_SIZE` = `vec2(1.0 / 64.0, 1.0 / 32.0)`.
inout vec2 VERTEX	Posizione del vertice, nello spazio locale.
in int VERTEX_ID	L'indice del vertice attuale nel buffer dei vertici.
inout vec2 UV	Coordinate normalizzate della texture. Intervallo da `0.0` a `1.0`.
inout vec4 COLOR	Colore derivante dalla primitiva del vertice moltiplicato per modulate di CanvasItem moltiplicato per self_modulate di CanvasItem.
inout float POINT_SIZE	Dimensione dei punti per il disegno di punti.
in vec4 CUSTOM0	Valore personalizzato dalla primitiva del vertice.
in vec4 CUSTOM1	Valore personalizzato dalla primitiva del vertice.

Variabili integrate di frammento

COLOR e TEXTURE

La variabile integrata COLOR è utilizzata per un po' di cose:

Nella funzione vertex(), COLOR contiene il colore della primitiva di vertice moltiplicato per la modulazione del CanvasItem moltiplicato per modulazione a se stesso del CanvasItem.

Nella funzione fragment(), il valore di input COLOR è quello stesso valore moltiplicato per il colore dalla TEXTURE predefinita (se presente).

Nella funzione fragment(), COLOR è anche l'output finale.

Alcuni nodi (ad esempio, Sprite2D) visualizzano una texture predefinita, ad esempio texture. Quando si utilizza una funzione fragment() personalizzata, sono disponibili alcune opzioni su come campionare questa texture.

Per leggere solo il contenuto della texture predefinita, ignorando il COLOR del vertice:

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

Per leggere il contenuto della texture predefinita moltiplicato per il COLOR del vertice:

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

Per leggere solo il COLOR del vertice in fragment(), ignorando la texture principale, è necessario passare COLOR come varying, e poi leggerlo in fragment():

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

NORMAL

Similmente, se si utilizza una mappa normale nel CanvasTexture, Godot la usa come predefinita e ne assegna il valore alla variabile integrata NORMAL. Se si utilizza una mappa normale progettata per l'uso in 3D, apparirà invertita. Per utilizzarla nello shader, è necessario assegnarla alla proprietà NORMAL_MAP. Godot si occuperà di convertirla per l'uso in 2D e sovrascrivere NORMAL.

NORMAL_MAP = texture(NORMAL_TEXTURE, UV).rgb;

Integrato	Descrizione
in vec4 FRAGCOORD	Coordinate del centro pixel. Nello spazio dello schermo. `xy` specifica la posizione nella viewport. In alto a sinistra della viewport si trova l'origine, `(0.0, 0.0)`. In basso a destra della viewport si trova `(1.0, 1.0)`.
in vec2 SCREEN_PIXEL_SIZE	Dimensioni dei singoli pixel. Equivale all'inverso della risoluzione.
in vec4 REGION_RECT	Area visibile della regione dello sprite nel formato `(x, y, larghezza, altezza)`. Varia in base alla proprietà `region_enabled` di Sprite2D. I valori sono normalizzati; ad esempio, una regione 600×400 su una texture 1000×800 con un offset di 100×100 sarebbe `vec4(0.1, 0.125, 0.6, 0.5)`. I valori possono superare l'intervallo da 0.0 a 1.0 se l'offset X/Y è negativo o se le dimensioni superano le dimensioni della texture.
in vec2 POINT_COORD	Coordinate per disegnare punti nell'intervallo da 0.0 a 1.0.
sampler2D TEXTURE	Texture 2D predefinita.
in vec2 TEXTURE_PIXEL_SIZE	Dimensioni normalizzate dei pixel della texture 2D predefinita. Per uno Sprite2D con una texture di 64×32 pixel, `TEXTURE_PIXEL_SIZE` = `vec2(1.0 / 64.0, 1.0 / 32.0)`.
in bool AT_LIGHT_PASS	Sempre `false`.
sampler2D SPECULAR_SHININESS_TEXTURE	Texture di lucidità speculare di questo oggetto.
in vec4 SPECULAR_SHININESS	Colore di lucidità speculare, come campionato dalla texture.
in vec2 UV	UV dalla funzione `vertex()`. Per Sprite2D con una regione abilitata, questa campiona l'intera texture. Utilizzare invece `REGION_RECT` per campionare solo la regione definita nelle proprietà di Sprite2D.
in vec2 SCREEN_UV	Coordinate UV dello schermo per il pixel attuale.
sampler2D SCREEN_TEXTURE	Rimosso in Godot 4. Utilizzare invece un `sampler2D` con `hint_screen_texture`.
inout vec3 NORMAL	Lettura normale da `NORMAL_TEXTURE`. Scrivibile.
sampler2D NORMAL_TEXTURE	Texture 2D di normali predefinita.
out vec3 NORMAL_MAP	Configura le mappe di normali pensate per il 3D per l'uso in 2D. Se utilizzato, sovrascrive `NORMAL`.
out float NORMAL_MAP_DEPTH	Profondità della mappa di normali per il ridimensionamento.
inout vec2 VERTEX	Posizione del pixel nello spazio dello schermo.
inout vec2 SHADOW_VERTEX	Uguale a `VERTEX` ma ci si può scrivere per modificare le ombre.
inout vec3 LIGHT_VERTEX	Uguale a `VERTEX`, ma può essere scritto per modificare l'illuminazione. La componente Z rappresenta l'altezza.
inout vec4 COLOR	`COLOR` dalla funzione `vertex()` moltiplicato per il colore della `TEXTURE`. È anche l'output del valore del colore.

Variabili integrate di luce

Le funzioni processori di luce funzionano in modo diverso in Godot 4.x rispetto a Godot 3.x. In Godot 4.x tutta l'illuminazione viene eseguita durante la fase regolare di disegno. In altre parole, Godot non ridisegna più l'oggetto per ogni luce.

Utilizza la modalità di rendering unshaded se non è necessario che la funzione light() sia eseguita. Utilizza la modalità di rendering light_only se è necessario solo vedere l'impatto dell'illuminazione su un oggetto; ciò può essere utile quando si desidera che l'oggetto sia visibile solo dove è coperto dalla luce.

Se si definisce una funzione light(), questa sostituirà la funzione integrata di luce, anche se la funzione definita è vuota.

Di seguito vi è un esempio di uno shader di luce che tiene conto della mappa di normali di un 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);
}

Integrato	Descrizione
in vec4 FRAGCOORD	Coordinate del centro pixel. Nello spazio dello schermo. `xy` specifica la posizione nella viewport. In alto a sinistra della viewport si trova l'origine, `(0.0, 0.0)`. In basso a destra della viewport si trova `(1.0, 1.0)`.
in vec3 NORMAL	Normale in ingresso.
in vec4 COLOR	Colore di input. Questo è l'output della funzione `fragment()`.
in vec2 UV	UV dalla funzione `vertex()`, equivalente all'UV nella funzione `fragment()`.
sampler2D TEXTURE	Texture attualmente in uso per il CanvasItem.
in vec2 TEXTURE_PIXEL_SIZE	Dimensioni normalizzate dei pixel di `TEXTURE`. Per uno Sprite2D con una `TEXTURE` di 64×32 pixel, `TEXTURE_PIXEL_SIZE` = `vec2(1.0 / 64.0, 1.0 / 32.0)`.
in vec2 SCREEN_UV	Coordinate UV dello schermo per il pixel attuale.
in vec2 POINT_COORD	UV for Point Sprite.
in vec4 LIGHT_COLOR	Il colore del Light2D. Se la luce è una PointLight2D, è moltiplicato per la texture della luce.
in float LIGHT_ENERGY	Moltiplicatore di energia del Light2D.
in vec3 LIGHT_POSITION	Posizione del Light2D nello spazio dello schermo. Se si utilizza DirectionalLight2D, questa posizione è sempre `(0.0, 0.0, 0.0)`.
in vec3 LIGHT_DIRECTION	Direzione della Light2D nello spazio dello schermo.
in bool LIGHT_IS_DIRECTIONAL	`true` se questo passaggio è una DirectionalLight2D.
in vec3 LIGHT_VERTEX	Posizione del pixel nello spazio dello schermo, come modificata nella funzione `fragment()`.
inout vec4 LIGHT	Colore in uscita per questo Light2D.
in vec4 SPECULAR_SHININESS	Lucentezza speculare, come impostata nella texture dell'oggetto.
out vec4 SHADOW_MODULATE	Moltiplica le ombre proiettate in questo punto per questo colore.

Funzioni SDF

Sono implementate alcune funzioni aggiuntive per campionare una texture con SDF generato automaticamente. Queste funzioni sono disponibili per le funzioni fragment() e light() degli shader di CanvasItem. Anche le funzioni personalizzate possono utilizzarle, purché siano chiamate dalle funzioni supportate.

Il signed distance field viene generato dai nodi LightOccluder2D presenti nella scena con la proprietà Collisione SDF abilitata (il che è predefinito). Consultare la documentazione di Luci e ombre 2D per ulteriori informazioni.

Funzione	Descrizione
float texture_sdf (vec2 sdf_pos)	Effettua una ricerca di texture SDF.
vec2 texture_sdf_normal (vec2 sdf_pos)	Calcola una normale dalla texture SDF.
vec2 sdf_to_screen_uv (vec2 sdf_pos)	Converte un SDF in UV dello schermo.
vec2 screen_uv_to_sdf (vec2 uv)	Converte UV dello schermo in un SDF.