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.

Convertire GLSL in shader di Godot

Questo documento spiega le differenze tra il linguaggio di shading di Godot e GLSL e fornisce consigli pratici su come migrare gli shader provenienti da altre parti, come Shadertoy e The Book of Shaders, negli shader di Godot.

Per informazioni dettagliate sul linguaggio di shading di Godot, fai riferimento a Shading Language.

GLSL

Godot utilizza un linguaggio di shading basato su GLSL con l'aggiunta di alcune funzionalità che ne migliorano l'usabilità. Di conseguenza, la maggior parte delle funzionalità disponibili in GLSL sono disponibili anche nel linguaggio di shading di Godot.

Programmi di shader

In GLSL, ogni shader usa un programma separato. C'è un programma per lo shader dei vertici e uno per lo shader dei frammenti. In Godot, c'è un singolo shader che contiene una funzione per vertici e/o una fragment. Se si sceglie di scriverne una sola, Godot fornirà l'altra.

Godot permette di condividere le variabili uniformi e le funzioni definendo gli shader di frammenti e di vertici in un unico file. In GLSL, i programmi di vertici e di frammenti non possono condividere variabili, tranne quando si utilizzano i varying.

Attributi dei vertici

In GLSL, you can pass in per-vertex information using attributes and have the flexibility to pass in as much or as little as you want. In Godot, you have a set number of input attributes, including VERTEX (position), COLOR, UV, UV2, NORMAL. Each shaders' page in the shader reference section of the documentation comes with a complete list of its vertex attributes.

gl_Position

gl_Position receives the final position of a vertex specified in the vertex shader. It is specified by the user in clip space. Typically, in GLSL, the model space vertex position is passed in using a vertex attribute called position and you handle the conversion from model space to clip space manually.

In Godot, VERTEX specifica la posizione del vertice nello spazio modello all'inizio della funzione vertex. Godot gestisce anche la conversione finale nello spazio di ritaglio dopo aver eseguito la funzione vertex definita dall'utente. Per saltare la conversione dallo spazio modello allo spazio vista, bisogna impostare render_mode su skip_vertex_transform. Per saltare tutte le trasformazioni, bisogna impostare render_mode su skip_vertex_transform e PROJECTION_MATRIX su mat4(1.0) per annullare la trasformazione finale dallo spazio vista allo spazio di ritaglio.

Varying

I varying sono un tipo di variabile che si possono passare dallo shader di vertici allo shader di frammenti. Nelle versioni moderne di GLSL (a partire da 3.0), i varying sono definiti con le parole chiave in e out. Una variabile in uscita dallo shader di vertici è definita con out nello shader di vertici e con in nello shader di frammenti.

Main

In GLSL, ogni programma shader sembra un programma autonomo in stile C. Di conseguenza, il punto di entrata principale è main. Se stai copiando uno shader di vertici, rinomina main in vertex, mentre se stai copiando uno shader di frammenti, rinomina main in fragment.

Macro

Il preprocessore di shader in Godot supporta le seguenti macro:

  • #define / #undef

  • #if, #elif, #else, #endif, defined(), #ifdef, #ifndef

  • #include (solo file .gdshaderinc e con una profondità massima di 25)

  • #pragma disable_preprocessor, che disabilita il preprocessore per il resto del file

Variabili

GLSL ha molte variabili integrate che sono codificate rigidamente. Queste variabili non sono uniformi, quindi non sono modificabili dal programma principale.

Variabile

Tipo

Equivalente

Descrizione

gl_FragColor

out vec4

COLOR

Colore di output per ogni pixel.

gl_FragCoord

vec4

FRAGCOORD

Per quadrilateri a schermo intero. Per quadrilateri più piccoli, utilizzare gli UV.

gl_Position

vec4

VERTEX

Posizione del vertice, output dallo shader di vertici.

gl_PointSize

float

POINT_SIZE

Dimensione di punto primitivo.

gl_PointCoord

vec2

POINT_COORD

Position on point when drawing Point primitives.

gl_FrontFacing

bool

FRONT_FACING

True se la faccia frontale di una primitiva.

Coordinate

gl_FragCoord in GLSL e FRAGCOORD nel linguaggio di shading di Godot utilizzano lo stesso sistema di coordinate. Se si utilizzano gli UV in Godot, la coordinata y verrà capovolta.

Precisione

In GLSL, è possibile definire la precisione di un determinato tipo (float o int) all'inizio dello shader con la parola chiave precision. In Godot, è possibile impostare la precisione delle singole variabili secondo le necessita inserendo i qualificatori di precisione lowp, mediump e highp prima del tipo nella definizione della variabile. Per ulteriori informazioni, consultare il riferimento Shading Language.

Shadertoy

Shadertoy è un sito web che rende facile scrivere shader di frammenti e creare magia pura.

Shadertoy non offre all'utente il controllo totale sullo shader. Gestisce tutti gli input e le uniformi, lasciando all'utente solo la scrittura dello shader di frammenti.

Tipi

Shadertoy utilizza le specifiche WebGL, quindi esegue una versione leggermente diversa di GLSL. Nonostante ciò, ha comunque i tipi soliti, inclusi costanti e macro.

mainImage

Il punto di entrata principale di uno shader Shadertoy è la funzione mainImage. mainImage ha due parametri, fragColor e fragCoord, che corrispondono rispettivamente a COLOR e FRAGCOORD in Godot. Questi parametri sono gestiti automaticamente in Godot, quindi non è necessario includerli manualmente. Tutto ciò che all'interno della funzione mainImage deve essere copiato nella funzione fragment quando si converte in Godot.

Variabili

Per rendere facile e veloce scrivere shader di frammenti, Shadertoy gestisce automaticamente il passaggio di numerose informazioni utili dal programma principale allo shader di frammenti. Alcune di queste informazioni non hanno equivalenti in Godot, poiché Godot ha scelto di non renderle disponibili normalmente. Questo va bene, perché Godot offre la possibilità di creare le proprie uniformi. Per le variabili i cui equivalenti sono indicati come "Fornisci con uniforme", è responsabilità dell'utente creare autonomamente tale uniforme. La descrizione fornisce un suggerimento su cosa è possibile passare come sostituto.

Variabile

Tipo

Equivalente

Descrizione

fragColor

out vec4

COLOR

Colore di output per ogni pixel.

fragCoord

vec2

FRAGCOORD.xy

Per quadrilateri a schermo intero. Per quadrilateri più piccoli, utilizzare gli UV.

iResolution

vec3

1.0 / SCREEN_PIXEL_SIZE

Può anche passare manualmente.

iTime

float

TIME

Tempo trascorso dall'avvio dello shader.

iTimeDelta

float

Fornisci con uniforme

Tempo per renderizzare il frame precedente.

iFrame

float

Fornisci con uniforme

Frame number.

iChannelTime[4]

float

Fornisci con uniforme

Tempo trascorso da quando è stata cominciata quella particolare texture.

iMouse

vec4

Fornisci con uniforme

Posizione del mouse in coordinate di pixel.

iDate

vec4

Fornisci con uniforme

Data attuale, espressa in secondi.

iChannelResolution[4]

vec3

1.0 / TEXTURE_PIXEL_SIZE

Risoluzione di una particolare texture.

iChanneli

Sampler2D

TEXTURE

Godot fornisce un solo integrato; l'utente può crearne altri.

Coordinate

fragCoord si comporta allo stesso modo di gl_FragCoord in GLSL e FRAGCOORD in Godot.

The Book of Shaders

Similmente a Shadertoy, The Book of Shaders fornisce l'accesso a uno shader di frammenti nel browser web, con il quale l'utente può interagire. L'utente è limitato a scrivere codice per lo shader di frammenti attraverso un elenco predefinito di uniformi passate e senza la possibilità di aggiungerne altre.

Per ulteriore aiuto su come convertire gli shader in vari framework in generale, The Book of Shaders fornisce una pagina sull'esecuzione degli shader in vari framework.

Tipi

The Book of Shaders utilizza le specifiche WebGL, quindi esegue una versione leggermente diversa di GLSL. Tuttavia, include i tipi regolari, inclusi costanti e macro.

Main

Il punto di ingresso per uno shader di frammenti in Book of Shaders è main, proprio come in GLSL. Tutto ciò che è scritto nella funzione main in Book of Shaders si dovrebbe copiare nella funzione fragment di Godot.

Variabili

The Book of Shaders sticks closer to plain GLSL than Shadertoy does. It also implements fewer uniforms than Shadertoy.

Variabile

Tipo

Equivalente

Descrizione

gl_FragColor

out vec4

COLOR

Colore di output per ogni pixel.

gl_FragCoord

vec4

FRAGCOORD

Per quadrilateri a schermo intero. Per quadrilateri più piccoli, utilizzare gli UV.

u_resolution

vec2

1.0 / SCREEN_PIXEL_SIZE

Può anche passare manualmente.

u_time

float

TIME

Tempo trascorso dall'avvio dello shader.

u_mouse

vec2

Fornisci con uniforme

Posizione del mouse in coordinate di pixel.

Coordinate

The Book of Shaders usa lo stesso sistema di coordinate di GLSL.