Up to date

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

CanvasItem 着色器

画布组件着色器用于绘制Godot中的所有二维元素. 这包括从画布组件继承的所有节点, 以及所有图形用户界面元素.

画布组件着色器比空间着色器包含更少的内置变量和功能, 但它们与顶点, 片段和光处理器功能保持相同的基本结构.

渲染模式

渲染模式	描述
blend_mix	混合混合模式（Alpha 为透明度），默认。
blend_add	叠加混合模式。
blend_sub	减法混合模式。
blend_mul	乘法混合模式。
blend_premul_alpha	预乘 Alpha 混合模式。
blend_disabled	禁用混合，值（包括 Alpha）会按原样写入。
unshaded	结果只使用反照率。材质中不会发生照明/阴影。
light_only	仅在光通过时绘制.
skip_vertex_transform	VERTEX needs to be transformed manually in vertex function.
world_vertex_coords	VERTEX is modified in world coordinates instead of local.

内置

标记为“in”的值只读。标记为“out”的值可以选择写入，不一定包含有意义的值。标记为“inout”的值提供了有意义的默认值，可以选择写入。采样器始终无法写入，不进行标记。

全局内置

全局的内置在所有地方均可用，包括自定义函数中。

内置	描述
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	`PI` 常数（`3.141592`）。圆的周长与直径的比值，即转半圈对应的弧度。
in float TAU	`TAU` 常数（`6.283185`）。等价于 `PI * 2`，即转一圈对应的弧度。
in float E	`E` 常数（`2.718281`）。欧拉数，即自然对数的底。

顶点内置

顶点数据（VERTEX）使用局部空间呈现（像素坐标，相对于 Node2D 的原点）。如果不写入，这些值就不会被修改，会原样传下去。

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;
}

其他内置程序, 如UV和COLOR, 如果没有修改, 也会传递给片段函数.

对于实例化，INSTANCE_CUSTOM变量包含实例自定义数据. 使用粒子时, 此信息通常是:

x：旋转角度，单位为弧度。
y：生命周期的阶段（0 到 1）。
z：动画帧。

内置	描述
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	实例化的实例ID.
in vec4 INSTANCE_CUSTOM	实例自定义数据.
in bool AT_LIGHT_PASS	始终为 `false`。
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)`
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	来自顶点原语的颜色.
inout float POINT_SIZE	点绘图的点大小.
in vec4 CUSTOM0	Custom value from vertex primitive.
in vec4 CUSTOM1	Custom value from vertex primitive.

片段内置

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;

内置	描述
in vec4 FRAGCOORD	Coordinate of pixel center. In screen space. `xy` specifies position in window. Origin is upper-left.
in vec2 SCREEN_PIXEL_SIZE	单个像素的大小. 等于分辨率的倒数.
in vec2 POINT_COORD	所绘制点的坐标。
sampler2D TEXTURE	默认的2D纹理.
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	始终为 `false`。
sampler2D SPECULAR_SHININESS_TEXTURE	Specular shininess texture of this object.
in vec4 SPECULAR_SHININESS	Specular shininess color, as sampled from the texture.
in vec2 UV	来自顶点功能的UV.
in vec2 SCREEN_UV	屏幕当前像素的UV坐标.
sampler2D SCREEN_TEXTURE	在 Godot 4 中移除。请改用 `sampler2D` 和 `hint_screen_texture`。
inout vec3 NORMAL	从 NORMAL_TEXTURE 中正常读取. 可写的.
sampler2D NORMAL_TEXTURE	默认 2D 法线纹理。
out vec3 NORMAL_MAP	Configures normal maps meant for 3D for use in 2D. If used, overrides NORMAL.
out float NORMAL_MAP_DEPTH	用于缩放的法线贴图深度.
inout vec2 VERTEX	屏幕空间中的像素位置。
inout vec2 SHADOW_VERTEX	与 `VERTEX` 相同，但是可以通过写入来修改阴影。
inout vec3 LIGHT_VERTEX	与 `VERTEX` 相同，但是可以通过写入来修改灯光。Z 分量代表高度。
inout vec4 COLOR	`COLOR` from the `vertex()` function multiplied by the `TEXTURE` color. Also output color value.

内置灯光

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);
}

内置	描述
in vec4 FRAGCOORD	Coordinate of pixel center. In screen space. `xy` specifies position in window. Origin is lower-left.
in vec3 NORMAL	输入法线。
in vec4 COLOR	输入颜色。这是 fragment 函数的输出。
in vec2 UV	UV，来自 vertex 函数，等价于 fragment 函数中的 UV。
sampler2D TEXTURE	CanvasItem使用的当前纹理.
in vec2 TEXTURE_PIXEL_SIZE	Normalized pixel size of TEXTURE. For a Sprite2D with a TEXTURE of size 64x32px, TEXTURE_PIXEL_SIZE = `vec2(1/64, 1/32)`
in vec2 SCREEN_UV	屏幕当前像素的UV坐标.
in vec2 POINT_COORD	点精灵的UV.
in vec4 LIGHT_COLOR	Color of Light multiplied by Light's texture.
in float LIGHT_ENERGY	灯光的能量乘数。
in vec3 LIGHT_POSITION	灯光在屏幕空间中的位置。如果使用的是 `DirectionalLight2D`，则始终为 `vec3(0,0,0)`。
in vec3 LIGHT_DIRECTION	灯光在屏幕空间中的方向。
in bool LIGHT_IS_DIRECTIONAL	如果该阶段为 `DirectionalLight2D` 则为 `true`。
in vec3 LIGHT_VERTEX	像素位置，使用屏幕空间坐标，是在 fragment 函数中修改的。
inout vec4 LIGHT	该 Light 的输出颜色。
in vec4 SPECULAR_SHININESS	镜面反射光泽度，由对象的纹理设置。
out vec4 SHADOW_MODULATE	Multiply shadows cast at this point by this color.

SDF 函数

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.

函数	描述
float texture_sdf (vec2 sdf_pos)	执行2D纹理读取。
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.