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

2D CanvasItem-Shader

CanvasItem-Shader werden verwendet, um alle 2D-Elemente in Godot zu zeichnen. Dazu gehören alle Nodes, die von CanvasItems erben, sowie alle GUI-Elemente.

CanvasItem shaders contain fewer built-in variables and functionality than Spatial shaders, but they maintain the same basic structure with vertex, fragment, and light processor functions.

Render-Modi

Rendermodus	Beschreibung
blend_mix	Mix-Blending-Modus (Alpha ist Transparenz), Default.
blend_add	Additiver Blending-Modus.
blend_sub	Subtraktiver Blending-Modus.
blend_mul	Multiplikativer Blending-Modus.
blend_premul_alpha	Vormultiplizierter Alpha-Blending-Modus.
blend_disabled	Blending deaktivieren. Werte (einschließlich Alpha) werden unverändert geschrieben.
unshaded	Das Ergebnis ist einfaches Albedo. Kein Licht/Schatten auf diesem Material.
light_only	Only draw in the light pass.
skip_vertex_transform	`VERTEX` needs to be transformed manually in the `vertex()` function.
world_vertex_coords	`VERTEX` is modified in world coordinates instead of local.

Built-ins

Values marked as in are read-only. Values marked as out can optionally be written to and will not necessarily contain sensible values. Values marked as inout provide a sensible default value, and can optionally be written to. Samplers cannot be written to so they are not marked.

Not all built-ins are available in all processing functions. To access a vertex built-in from the fragment() function, you can use a varying. The same applies for accessing fragment built-ins from the light() function.

Globale Built-ins

Globale Built-ins sind überall verfügbar, einschließlich benutzerdefinierter Funktionen.

Built-in	Beschreibung
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 affected by time_scale but not by pausing. If you need a `TIME` variable that is not affected by time scale, add your own global shader uniform and update it each frame.
in float PI	A `PI` constant (`3.141592`). The ratio of a circle's circumference to its diameter and the number of radians in a half turn.
in float TAU	A `TAU` constant (`6.283185`). Equivalent to `PI * 2` and the number of radians in a full turn.
in float E	An `E` constant (`2.718281`). Euler's number, the base of the natural logarithm.

Vertex-Built-ins

Vertex-Daten (VERTEX) werden im Local-Space dargestellt (Pixelkoordinaten, relativ zum Ursprung des Node2D). Wenn sie nicht beschrieben werden, werden diese Werte nicht verändert und werden so weitergegeben, wie sie eingegangen sind.

Der Benutzer kann die eingebaute Model-to-World-Transformation deaktivieren (die World-to-Screen-Transformation und die Projektion werden später immer noch durchgeführt) und sie manuell mit dem folgenden Code durchführen:

shader_type canvas_item;
render_mode skip_vertex_transform;

void vertex() {

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

Other built-ins, such as UV and COLOR, are also passed through to the fragment() function if not modified.

For instancing, the INSTANCE_CUSTOM variable contains the instance custom data. When using particles, this information is usually:

x: Rotationswinkel in Bogenmaß.
y: Phase during lifetime (0.0 to 1.0).
z: Animations-Frame.

Built-in	Beschreibung
in mat4 MODEL_MATRIX	Transformation vom Local Space in den World Space. World Space sind die Koordinaten, die Sie normalerweise im Editor verwenden.
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 range from `(0.0, 0.0)` to viewport size.
in mat4 SCREEN_MATRIX	Canvas space to clip space transform. In clip space coordinates range from `(-1.0, -1.0)` to `(1.0, 1.0).`
in int INSTANCE_ID	Instanz-ID zum Instanziieren.
in vec4 INSTANCE_CUSTOM	Benutzerdefinierte Daten instanzieren.
in bool AT_LIGHT_PASS	Immer `false`.
in vec2 TEXTURE_PIXEL_SIZE	Normalized pixel size of the default 2D texture. For a Sprite2D with a texture of size 64×32 pixels, `TEXTURE_PIXEL_SIZE` = `vec2(1.0 / 64.0, 1.0 / 32.0)`.
inout vec2 VERTEX	Vertex position, in local space.
in int VERTEX_ID	Der Index des aktuellen Vertex im Vertex-Puffer.
inout vec2 UV	Normalized texture coordinates. Range from `0.0` to `1.0`.
inout vec4 COLOR	Color from vertex primitive multiplied by the CanvasItem's modulate multiplied by CanvasItem's self_modulate.
inout float POINT_SIZE	Punktgröße für Punktzeichnen.
in vec4 CUSTOM0	Benutzerdefinierter Wert vom Scheitelpunktprimitiv.
in vec4 CUSTOM1	Benutzerdefinierter Wert vom Scheitelpunktprimitiv.

Fragment-Built-ins

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 NORMAL_MAP property. Godot will handle converting it for use in 2D and overwriting NORMAL.

NORMAL_MAP = texture(NORMAL_TEXTURE, UV).rgb;

Built-in	Beschreibung
in vec4 FRAGCOORD	Coordinate of pixel center. In screen space. `xy` specifies position in viewport. Upper-left of the viewport is the origin, `(0.0, 0.0)`. Bottom-right of the viewport is `(1.0, 1.0)`.
in vec2 SCREEN_PIXEL_SIZE	Size of individual pixels. Equal to the inverse of resolution.
in vec4 REGION_RECT	Visible area of the sprite region in format `(x, y, width, height)`. Varies according to Sprite2D's `region_enabled` property. Values are normalized; for example, a 600×400 region on a 1000×800 texture with a 100×100 offset would be `vec4(0.1, 0.125, 0.6, 0.5)`. Values may exceed the 0.0 to 1.0 range if the X/Y offset is negative, or if the size exceeds the texture's size.
in vec2 POINT_COORD	Coordinate for drawing points in the 0.0 to 1.0 range.
sampler2D TEXTURE	Default-2D-Textur.
in vec2 TEXTURE_PIXEL_SIZE	Normalized pixel size of the default 2D texture. For a Sprite2D with a texture of size 64×32 pixels, `TEXTURE_PIXEL_SIZE` = `vec2(1.0 / 64.0, 1.0 / 32.0)`.
in bool AT_LIGHT_PASS	Immer `false`.
sampler2D SPECULAR_SHININESS_TEXTURE	Spiegelglanztextur dieses Objekts.
in vec4 SPECULAR_SHININESS	Farbe des spiegelnden Glanzes, wie sie aus der Textur abgetastet wurde.
in vec2 UV	UV from the `vertex()` function. For a Sprite2D with region enabled, this will sample the entire texture. Use `REGION_RECT` instead to sample only the region defined in the Sprite2D's properties.
in vec2 SCREEN_UV	Screen UV coordinate for the current pixel.
sampler2D SCREEN_TEXTURE	Entfernt in Godot 4. Verwenden Sie stattdessen ein `sampler2D` mit `hint_screen_texture`.
inout vec3 NORMAL	Normal read from `NORMAL_TEXTURE`. Writable.
sampler2D NORMAL_TEXTURE	Default-2D-Normalentextur.
out vec3 NORMAL_MAP	Configures normal maps meant for 3D for use in 2D. If used, overrides `NORMAL`.
out float NORMAL_MAP_DEPTH	Normal map depth for scaling.
inout vec2 VERTEX	Pixelposition im Screen Space.
inout vec2 SHADOW_VERTEX	Dasselbe wie `VERTEX`, aber es kann geschrieben werden, um Schatten zu verändern.
inout vec3 LIGHT_VERTEX	Dasselbe wie `VERTEX`, kann aber geschrieben werden, um die Beleuchtung zu verändern. Die Z-Komponente stellt die Höhe dar.
inout vec4 COLOR	`COLOR` from the `vertex()` function multiplied by the `TEXTURE` color. Also output color value.

Licht-Built-ins

Die Lichtprozessorfunktionen arbeiten in Godot 4.x anders als in Godot 3.x. In Godot 4.x wird die gesamte Beleuchtung während des regulären Zeichenvorgangs ausgeführt. Mit anderen Worten: Godot zeichnet das Objekt nicht mehr für jedes Licht neu.

Use the unshaded render mode if you do not want the light() function to run. Use the light_only render mode 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.

Unten sehen Sie ein Beispiel für einen Licht-Shader, der die Normal Map eines CanvasItems berücksichtigt:

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

Built-in	Beschreibung
in vec4 FRAGCOORD	Coordinate of pixel center. In screen space. `xy` specifies position in viewport. Upper-left of the viewport is the origin, `(0.0, 0.0)`. Bottom-right of the viewport is `(1.0, 1.0)`.
in vec3 NORMAL	Input normal.
in vec4 COLOR	Input color. This is the output of the `fragment()` function.
in vec2 UV	UV from the `vertex()` function, equivalent to the UV in the `fragment()` function.
sampler2D TEXTURE	Current texture in use for the CanvasItem.
in vec2 TEXTURE_PIXEL_SIZE	Normalized pixel size of `TEXTURE`. For a Sprite2D with a `TEXTURE` of size 64×32 pixels, `TEXTURE_PIXEL_SIZE` = `vec2(1.0 / 64.0, 1.0 / 32.0)`.
in vec2 SCREEN_UV	Screen UV coordinate for the current pixel.
in vec2 POINT_COORD	UV für Punkt-Sprite.
in vec4 LIGHT_COLOR	Color of the Light2D. If the light is a PointLight2D, multiplied by the light's texture.
in float LIGHT_ENERGY	Energy multiplier of the Light2D.
in vec3 LIGHT_POSITION	Position of the Light2D in screen space. If using a DirectionalLight2D this is always `(0.0, 0.0, 0.0)`.
in vec3 LIGHT_DIRECTION	Direction of the Light2D in screen space.
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 Light2D.
in vec4 SPECULAR_SHININESS	Spiegelnder Glanz, wie in der Textur des Objekts festgelegt.
out vec4 SHADOW_MODULATE	Multipliziert den Schattenwurf an diesem Punkt mit dieser Farbe.

SDF-Funktionen

There are a few additional functions implemented to sample an automatically generated Signed Distance Field texture. These functions are available in the fragment() and light() functions of CanvasItem shaders. Custom functions may also use them as long as they are called from supported functions.

Das Signed Distance Field wird von LightOccluder2D Nodes generiert, die in der Szene vorhanden sind und bei denen die SDF Collision-Property aktiviert ist (was der Default ist). Siehe die 2D Lichter und Schatten-Dokumentation für weitere Informationen.

Funktion	Beschreibung
float texture_sdf (vec2 sdf_pos)	Führt eine SDF-Textursuche durch.
vec2 texture_sdf_normal (vec2 sdf_pos)	Berechnet eine Normale aus der SDF-Textur.
vec2 sdf_to_screen_uv (vec2 sdf_pos)	Konvertiert ein SDF in ein Bildschirm-UV.
vec2 screen_uv_to_sdf (vec2 uv)	Konvertiert Bildschirm-UV in ein SDF.