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

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/NORMAL/等需要在顶点函数中手动转换.

内置¶

标记为 "in" 的值是只读的. 标记为 "out" 的值是可以选择写入的, 不一定包含合理的值. 标记为 "inout" 的值提供一个合理的默认值, 并且可以选择写入. 采样器不是写入的对象, 它们没有被标记.

全局内置¶

全局内置的功能随处可见, 包括自定义功能.

内置	描述
in float TIME	Global time since the engine has started, in seconds (always positive). It's subject to the rollover setting (which is 3,600 seconds by default). It's not affected by time_scale or pausing, but you can define a global shader uniform to add a "scaled" `TIME` variable if desired.
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	A `E` constant (`2.718281`). Euler's number and a base of the natural logarithm.

顶点内置¶

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

其他内置程序, 如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 vec4 INSTANCE_CUSTOM	实例自定义数据.
in bool AT_LIGHT_PASS	Always `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	顶点, 在图像空间.
inout vec2 UV	Normalized texture coordinates. Range from 0 to 1.
inout vec4 COLOR	来自顶点原语的颜色.
inout float POINT_SIZE	点绘图的点大小.

片段内置¶

Certain Nodes (for example, Sprite2Ds) display a texture by default. However, when a custom fragment function is attached to these nodes, the texture lookup needs to be done manually. Godot does not provide the texture color in the COLOR built-in variable; to read the texture color for such nodes, use:

COLOR = texture(TEXTURE, UV);

这与内置法线贴图的行为不同. 如果附加了法线贴图,Godot默认使用它, 并将其值分配给内置的 NORMAL 变量. 如果你使用的是用于3D的法线贴图, 它将出现倒置. 为了在你的着色器中使用它, 必须把它分配给 NORMALMAP 属性.Godot会将其转换为2D使用, 并覆盖 NORMAL .

NORMALMAP = texture(NORMAL_TEXTURE, UV).rgb;

内置	描述
in vec4 FRAGCOORD	像素中心的坐标。在屏幕空间中，`xy` 表示窗口中的位置，如果没有用 `DEPTH`，则 `z` 表示片段深度。原点位于左下角。
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	Always `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	Removed in Godot 4. Use a `sampler2D` with `hint_screen_texture` instead.
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	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	从顶点函数和输出片段颜色. 如果未使用, 将设置为纹理颜色.

内置灯光¶

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.

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	像素中心的坐标。在屏幕空间中，`xy` 表示窗口中的位置，如果没有用 `DEPTH`，则 `z` 表示片段深度。原点位于左下角。
in vec3 NORMAL	Input Normal.
in vec4 COLOR	Input Color. This is the output of the fragment function with final modulation applied.
in vec2 UV	来自顶点函数的UV, 相当于片段函数中的UV.
sampler2D TEXTURE	CanvasItem使用的当前纹理.
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 vec2 SCREEN_UV	屏幕当前像素的UV坐标.
in vec2 POINT_COORD	点精灵的UV.
in vec4 LIGHT_COLOR	光的颜色.
in float LIGHT_ENERGY	Energy multiplier of 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 of Light 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	值从浅色纹理和输出颜色. 可以修改. 如果不使用, 则忽略光照函数.
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.

函数	描述
float texture_sdf (vec2 sdf_pos)	Performs an SDF texture lookup.
vec2 texture_sdf_normal (vec2 sdf_pos)	Performs an SDF normal texture lookup.
vec2 sdf_to_screen_uv (vec2 sdf_pos)	Converts a SDF to screen UV.
vec2 screen_uv_to_sdf (vec2 uv)	Converts screen UV to a SDF.