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

Les constantes de tableaux globaux ne sont pas prises en charge dans Godot 3.2.x. Vous pouvez simuler la fonctionnalité en utilisant une uniform initialisée à la valeur, mais vous ne bénéficierez pas de l'augmentation de vitesse résultant de l'utilisation d'une constante.

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.