Up to date

This page is up to date for Godot 4.3. If you still find outdated information, please open an issue.

CanvasItem shaders

Les shaders de type CanvasItem sont utilisés pour dessiner tous les éléments 2D dans Godot. Ceux-ci incluent tous les nœuds qui héritent de CanvasItems, et tous les éléments d'interface graphique.

Les shaders de type CanvasItem contiennent moins de variables et fonctionnalités intégrées que les shaders spatiaux, mais ils conservent la même structure de base avec les fonctions vertex, fragment, et light processor.

Mode de rendu

Mode de rendu	Description
blend_mix	Mode de fusion par mélange (alpha est la transparence), par défaut.
blend_add	Mode de fusion additif.
blend_sub	Mode de fusion substractif.
blend_mul	Mode de fusion multiplicatif.
blend_premul_alpha	Mode de mélange alpha pré-multiplié.
blend_disabled	Désactive le mélange, les valeurs (y compris l'alpha) sont écrites telles quelles.
unshaded	Le résultat est juste l'albedo. Pas d'éclairage/d'ombres n'a lieu dans le matériau.
light_only	Ne dessinez que lors des passes de lumière.
skip_vertex_transform	VERTEX needs to be transformed manually in vertex function.
world_vertex_coords	VERTEX is modified in world coordinates instead of local.

Variables intégrées

Les valeurs marquées comme "in" sont en lecture seule. Les valeurs marquées comme "out" sont pour l'écriture facultative et ne contiendront pas nécessairement de valeurs sensibles. Les valeurs marquées comme "inout" fournissent une valeur par défaut sensible et peuvent éventuellement être réécrites. Les échantillonneurs ne sont pas soumis à l'écriture et ne sont pas marqués.

Variables intégrées Globales

Les modules intégrés globaux sont disponibles partout, y compris dans les fonctions personnalisées.

Intégré	Description
in float TIME	Global time since the engine has started, in seconds. It repeats after every 3,600 seconds (which can be changed with the rollover setting). It's not affected by time_scale or pausing. If you need a `TIME` variable that can be scaled or paused, add your own global shader uniform and update it each frame.
in float PI	A `PI` constant (`3.141592`). A ration of circle's circumference to its diameter and amount of radians in half turn.
in float TAU	A `TAU` constant (`6.283185`). An equivalent of `PI * 2` and amount of radians in full turn.
in float E	An `E` constant (`2.718281`). Euler's number and a base of the natural logarithm.

Variables intégrées de sommet

Vertex data (VERTEX) is presented in local space (pixel coordinates, relative to the Node2D's origin). If not written to, these values will not be modified and be passed through as they came.

The user can disable the built-in model to world transform (world to screen and projection will still happen later) and do it manually with the following code:

shader_type canvas_item;
render_mode skip_vertex_transform;

void vertex() {

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

D'autres types intégrées, comme UV et COLOR, sont aussi passé tel quel à la fonction fragment s'ils ne sont pas modifiés.

Pour l'instanciation, la variable INSTANCE_CUSTOM contient les données personnalisées de l'instance. Pour des particules, cette information est habituellement :

x : Angle de rotation en radians.
y : Phase pendant la durée de vie (0 à 1).
z : Trame d'animation.

Intégré	Description
in mat4 MODEL_MATRIX	Local space to world space transform. World space is the coordinates you normally use in the editor.
in mat4 CANVAS_MATRIX	World space to canvas space transform. In canvas space the origin is the upper-left corner of the screen and coordinates ranging from (0, 0) to viewport size.
in mat4 SCREEN_MATRIX	Canvas space to clip space. In clip space coordinates ranging from (-1, -1) to (1, 1).
in int INSTANCE_ID	Identifiant de l'instance pour l'instanciation.
in vec4 INSTANCE_CUSTOM	Données personnalisées de l'instance.
in bool AT_LIGHT_PASS	Toujours `false`.
in vec2 TEXTURE_PIXEL_SIZE	Taille de pixel normalisée de la texture 2D par défaut. Pour un Sprite2D d'une résolution de 64x32px, TEXTURE_PIXEL_SIZE = `vec2(1/64, 1/32)`
inout vec2 VERTEX	Vertex, in local space.
in int VERTEX_ID	The index of the current vertex in the vertex buffer.
inout vec2 UV	Normalized texture coordinates. Range from 0 to 1.
inout vec4 COLOR	Couleur du sommet primitif.
inout float POINT_SIZE	Taille des points pour le dessin de point.
in vec4 CUSTOM0	Custom value from vertex primitive.
in vec4 CUSTOM1	Custom value from vertex primitive.

Variables intégrées de fragment

COLOR and TEXTURE

The built-in variable COLOR is used for a few things:

In the vertex() function, COLOR contains the color from the vertex primitive multiplied by the CanvasItem's modulate multiplied by the CanvasItem's self_modulate.

In the fragment() function, the input value COLOR is that same value multiplied by the color from the default TEXTURE (if present).

In the fragment() function, COLOR is also the final output.

Certain nodes (for example, Sprite2D) display a texture by default, for example texture. When using a custom fragment() function, you have a few options on how to sample this texture.

To read only the contents of the default texture, ignoring the vertex COLOR:

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

To read the contents of the default texture multiplied by vertex COLOR:

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

To read only the vertex COLOR in fragment(), ignoring the main texture, you must pass COLOR as a varying, then read it in fragment():

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

NORMAL

Similarly, if a normal map is used in the CanvasTexture, Godot uses it by default and assigns its value to the built-in NORMAL variable. If you are using a normal map meant for use in 3D, it will appear inverted. In order to use it in your shader, you must assign it to the NORMALMAP property. Godot will handle converting it for use in 2D and overwriting NORMAL.

NORMALMAP = texture(NORMAL_TEXTURE, UV).rgb;

Intégré	Description
in vec4 FRAGCOORD	Coordinate of pixel center. In screen space. `xy` specifies position in window. Origin is upper-left.
in vec2 SCREEN_PIXEL_SIZE	Taille des pixels individuels. Égal à l'inverse de la résolution.
in vec2 POINT_COORD	Coordonnées pour dessiner les points.
sampler2D TEXTURE	Texture 2D par défault.
in vec2 TEXTURE_PIXEL_SIZE	Normalized pixel size of default 2D texture. For a Sprite2D with a texture of size 64x32px, `TEXTURE_PIXEL_SIZE` = `vec2(1/64, 1/32)`
in bool AT_LIGHT_PASS	Toujours `false`.
sampler2D SPECULAR_SHININESS_TEXTURE	Texture de brillance spéculaire pour cet objet.
in vec4 SPECULAR_SHININESS	Specular shininess color, as sampled from the texture.
in vec2 UV	UV de la fonction vertex.
in vec2 SCREEN_UV	Coordonnées UV de l'écran pour le pixel actuel.
sampler2D SCREEN_TEXTURE	Removed in Godot 4. Use a `sampler2D` with `hint_screen_texture` instead.
inout vec3 NORMAL	Normale lue à partir de NORMAL_TEXTURE. Accessible en écriture.
sampler2D NORMAL_TEXTURE	Texture 2D des normales par défaut.
out vec3 NORMAL_MAP	Configures normal maps meant for 3D for use in 2D. If used, overrides NORMAL.
out float NORMAL_MAP_DEPTH	Profondeur d'une Normalmap pour la mise à l'échelle.
inout vec2 VERTEX	Pixel position in screen space.
inout vec2 SHADOW_VERTEX	Same as `VERTEX` but can be written to alter shadows.
inout vec3 LIGHT_VERTEX	Same as `VERTEX` but can be written to alter lighting. Z component represents height.
inout vec4 COLOR	`COLOR` from the `vertex()` function multiplied by the `TEXTURE` color. Also output color value.

Variables intégrées de lumière

Light processor functions work differently in Godot 4.x than they did in Godot 3.x. In Godot 4.x all lighting is done during the regular draw pass. In other words, Godot no longer draws the object again for each light.

Use render_mode unshaded if you do not want the light processor function to run. Use render_mode light_only if you only want to see the impact of lighting on an object; this can be useful when you only want the object visible where it is covered by light.

If you define a light function it will replace the built in light function, even if your light function is empty.

Below is an example of a light shader that takes a CanvasItem's normal map into account:

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

Intégré	Description
in vec4 FRAGCOORD	Coordinate of pixel center. In screen space. `xy` specifies position in window. Origin is lower-left.
in vec3 NORMAL	Entrée de la Normale.
in vec4 COLOR	Input Color. This is the output of the fragment function.
in vec2 UV	UV de la fonction vertex, équivalent à l'UV dans la fonction de fragment.
sampler2D TEXTURE	Texture actuelle utilisée pour le CanvasItem.
in vec2 TEXTURE_PIXEL_SIZE	Taille de pixel normalisée de la TEXTURE. Pour un Sprite2D avec une TEXTURE d'une résolution de 64x32px, TEXTURE_PIXEL_SIZE = `vec2(1/64, 1/32)`
in vec2 SCREEN_UV	Coordonnées UV de l'écran pour le pixel actuel.
in vec2 POINT_COORD	UV pour Point Sprite.
in vec4 LIGHT_COLOR	Color of Light multiplied by Light's texture.
in float LIGHT_ENERGY	Multiplicateur d'énergie de la Light.
in vec3 LIGHT_POSITION	Position of Light in screen space. If using a `DirectionalLight2D` this is always `vec3(0,0,0)`.
in vec3 LIGHT_DIRECTION	Direction de la lumière dans le repère de l'écran.
in bool LIGHT_IS_DIRECTIONAL	`true` if this pass is a `DirectionalLight2D`.
in vec3 LIGHT_VERTEX	Pixel position, in screen space as modified in the fragment function.
inout vec4 LIGHT	Output color for this Light.
in vec4 SPECULAR_SHININESS	Specular shininess, as set in the object's texture.
out vec4 SHADOW_MODULATE	Multiply shadows cast at this point by this color.

SDF functions

There are a few additional functions implemented to sample an automatically generated Signed Distance Field texture. These functions available for Fragment and Light functions of CanvasItem shaders.

The signed distance field is generated from LightOccluder2D nodes present in the scene with the SDF Collision property enabled (which is the default). See the 2D lights and shadows documentation for more information.

Fonction	Description
float texture_sdf (vec2 sdf_pos)	Effectue une recherche de texture SDF.
vec2 texture_sdf_normal (vec2 sdf_pos)	Calculates a normal from the SDF texture.
vec2 sdf_to_screen_uv (vec2 sdf_pos)	Converts an SDF to screen UV.
vec2 screen_uv_to_sdf (vec2 uv)	Converts screen UV to an SDF.