Migrer vers le langage de shaders de Godot

Introduction

Ce document explique les différences entre le langage de shading de Godot et GLSL et donne des conseils pratiques sur la façon de migrer des shaders d'autres sources, comme Shadertoy et The Book of Shaders, vers les shaders Godot.

Pour des informations détaillées sur le langage de shading de Godot, veuillez vous référer à la référence Langage de shading.

GLSL

Godot utilise un langage de shading basé sur le GLSL avec l'ajout de quelques fonctionnalité de qualité de vie. Par conséquent, la plupart des fonctionnalités disponibles dans GLSL sont disponibles dans la langue de shading de Godot.

Programmes de shader

Dans le GLSL, chaque shader utilise un programme distinct. Vous avez un programme pour le shader de sommet et un autre pour le shader de fragment. Dans Godot, vous avez un seul shader qui contient une fonction vertex et/ou fragment. Si vous choisissez de n'en écrire qu'une, Godot fournira l'autre.

Godot permet de partager des variables uniform et des fonctions en définissant les shaders de fragments et de sommets dans un seul fichier. Dans le GLSL, les programmes de vertex et de fragments ne peuvent pas partager de variables, sauf lorsque des varyings sont utilisées.

Attributs des sommets

Dans GLSL, vous pouvez transmettre des informations par vertex en utilisant des attributs et vous avez la possibilité d'en transmettre autant ou aussi peu que vous le souhaitez. Dans Godot, vous disposez d'un certain nombre d'attributs d'entrée, notamment VERTEX (position), COLOR, UV, UV2, NORMAL. Pour une liste complète, voir la référence du langage de shading.

gl_Position

gl_Position reçoit la position finale d'un vertex spécifié dans le shader de vertex. Il est spécifié par l'utilisateur dans l'espace de clipping. En général, dans GLSL, la position du vertex de l'espace modèle est transmise en utilisant un attribut de vertex appelé position et vous gérez manuellement la conversion de l'espace modèle en espace de clipping.

Dans Godot, VERTEX spécifie la position du sommet dans l'espace modèle au début de la fonction vertex. Godot s'occupe également de la conversion finale en espace de clipping après l'exécution de la fonction vertex définie par l'utilisateur. Si vous voulez sauter la conversion de l'espace modèle vers l'espace de vue, vous pouvez régler le render_mode sur skip_vertex_transform. Si vous voulez sauter toutes les transformations, réglez le render_mode sur skip_vertex_transform et réglez la PROJECTION_MATRIX sur mat4(1.0) afin d'annuler la transformation finale de l'espace de vue vers l'espace de clipping.

Varyings

Les varyings sont un type de variable qui peut passer du shader de sommet au shader de fragment. Dans GLSL moderne (3.0 et plus), les varyings sont définies par les mots-clés in and out. Une variable sortant du shader de sommet est définie par in and out dans le shader de sommet et in dans le shader de fragment.

Principal

Dans le GLSL, chaque programme de shader ressemble à un programme autonome de type C. Par conséquent, le point d'entrée principal est main. Si vous copiez un shader de sommet, renommez main en vertex et si vous copiez un shader de fragment, renommez main en fragment.

Constantes

Global array constants are not supported in Godot 3.x. You can fake the functionality by using a uniform initialized to the value, but you will not benefit from the increased speed from using a constant.

Macros

En raison de sa similarité avec le C, GLSL vous permet d'utiliser des macros. Généralement, le terme "#define" est utilisé pour définir des constantes ou des petites fonctions. Il n'y a pas de moyen simple de traduire les defines dans le langage de shading de Godot. Si c'est une fonction qui est définie, alors remplacez-la par une fonction, et si c'est une constante, alors remplacez-la par un uniform. Pour les autres macros (#if, #ifdef, etc.), il n'y a pas d'équivalent car elles s'exécutent pendant la phase de prétraitement de la compilation.

Variables

GLSL comporte de nombreuses variables intégrées qui sont codées en dur. Ces variables ne sont pas desuniforms, elles ne sont donc pas modifiables à partir du programme principal.

Variable

Type

Équivalent

Description

gl_FragColor

out vec4

COLOR

Couleur de sortie pour chaque pixel.

gl_FragCoord

vec4

FRAGCOORD

Pour les quads plein écran. Pour les petits quads, utilisez les UV.

gl_Position

vec4

VERTEX

Position du sommet, sortie du shader de sommet.

gl_PointSize

float

POINT_SIZE

Taille de Point primitive.

gl_PointCoord

vec2

POINT_COORD

Position sur le point lors du dessin des Point primitives.

gl_FrontFacing

bool

FRONT_FACING

Vrai si face avant de primitive.

Coordonnées

gl_FragCoord dans GLSL et FRAGCOORD en langage de shading Godot utilisent le même système de coordonnées. Si l'on utilise l'UV dans Godot, la coordonnée y sera inversée.

Précision

Dans GLSL, vous pouvez définir la précision d'un type donné (float ou int) en haut du shader avec le mot-clé precision. Dans Godot, vous pouvez définir la précision des variables individuelles selon vos besoins en plaçant les qualificatifs de précision lowp, mediump, et highp avant le type lors de la définition de la variable. Pour plus d'informations, voir la référence Shading Language.

Shadertoy

Shadertoy est un site web qui permet d'écrire facilement des shaders de fragments et de créer de la magie pure.

Shadertoy ne donne pas à l'utilisateur un contrôle total sur le shader. Il gère toutes les entrées et les uniforms et ne permet à l'utilisateur que d'écrire le shader de fragment.

Types

Shadertoy utilise la spécification webgl et a donc une version un peu différente de GLSL. Cependant, il dispose quand même de tous les types habituels, y compris constants et macros.

mainImage

Le point d’entrée d’un shader Shadertoy est sa fonction mainImage. mainImage a deux paramètres, fragColor et fragCoord, qui correspondent respectivement à COLOR et FRAGCOORD dans Godot. Ces paramètres sont traités automatiquement dans Godot, et il n’y a donc pas besoin de les inclure vous-même. Pour porter un shader dans Godot, tout ce qui se trouve dans la fonction mainImage doit être copié dans la fonction fragment.

Variables

Pour pouvoir écrire facilement les fragment shaders, Shadertoy se charge de passer de nombreuses informations utiles du programme principal au fragment shader. Certaines de ces infos n’ont pas d’équivalent dans Godot car Godot a pris la décision de ne pas les rendre accessibles par défaut. Mais Godot offre la possibilité de faire ses propres uniforms. Pour les variables dont les équivalents sont indiqués en "Provide with Uniform", les utilisateurs ont la responsabilité de créer ces uniforms eux-mêmes. Cette description donne une idée au lecteur de ce qu’il peut passer comme substitut.

Variable

Type

Équivalent

Description

fragColor

out vec4

COLOR

Couleur de sortie pour chaque pixel.

fragCoord

vec2

FRAGCOORD.xy

Pour les quads plein écran. Pour les petits quads, utilisez les UV.

iResolution

vec3

1.0 / SCREEN_PIXEL_SIZE

Peut également le passer manuellement.

iTime

float

TIME

Temps depuis le commencement du shader.

iTimeDelta

float

Fournir avec une Uniform

Temps de rendu de la trame précédente.

iFrame

float

Fournir avec une Uniform

Numéro de trame.

iChannelTime[4]

float

Fournir avec une Uniform

Temps écoulé depuis que cette texture particulière a commencé.

iMouse

vec4

Fournir avec une Uniform

Position de la souris en coordonnées de pixel.

iDate

vec4

Fournir avec une Uniform

Date actuelle, exprimée en secondes.

iChannelResolution[4]

vec3

1.0 / TEXTURE_PIXEL_SIZE

Résolution d'une texture particulière.

iChanneli

Sampler2D

TEXTURE

Godot ne fournit qu'un seul intégré ; l'utilisateur peut en faire davantage.

Coordonnées

fragCoord se comporte de la même manière que gl_FragCoord dans GLSL et FRAGCOORD dans Godot.

Le Livre des Shaders

Semblable à Shadertoy, The Book of Shaders donne accès à un shader de fragment dans le navigateur Web, avec lequel l'utilisateur peut interagir. L'utilisateur est limité à l'écriture de code de shader de fragment avec une liste définie d'uniforms transmis et sans possibilité d'ajouter des uniforms supplémentaires.

Pour plus d'aide sur le portage des shaders dans divers cadres en général, The Book of Shaders fournit une page sur l'exécution des shaders dans divers frameworks.

Types

The Book of Shaders utilise la spécification webgl, donc une version légèrement différente de GLSL. Cependant, il a toujours les types réguliers, y compris constants et macros.

Principal

Le point d'entrée d'un shader de fragment de Book of Shaders est main, comme dans GLSL. Tout ce qui est écrit dans la fonction main de Book of Shaders doit être copié dans la fonction fragment de Godot.

Variables

Le Book of Shaders se rapproche davantage du simple GLSL que Shadertoy. Il implémente également moins d'uniforms que Shadertoy.

Variable

Type

Équivalent

Description

gl_FragColor

out vec4

COLOR

Couleur de sortie pour chaque pixel.

gl_FragCoord

vec4

FRAGCOORD

Pour les quads plein écran. Pour les petits quads, utilisez les UV.

u_resolution

vec2

1.0 / SCREEN_PIXEL_SIZE

Peut également le passer manuellement.

u_time

float

TIME

Temps depuis le commencement du shader.

u_mouse

vec2

Fournir avec une Uniform

Position de la souris en coordonnées de pixel.

Coordonnées

Le Livre des Shaders utilise le même système de coordonnée que GLSL.