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

Spatial 着色器¶

空间着色器用于为三维对象着色. 它们是Godot提供的最复杂的着色器类型. 空间着色器是高度可配置的, 具有不同的渲染模式和不同的渲染选项(例如: 次表面散射, 透射, 环境遮挡, 边缘照明等). 用户可以选择编辑顶点, 片段, 和光照处理器功能, 以影响如何绘制对象.

渲染模式¶

渲染模式	描述
blend_mix	混合混合模式（Alpha 为透明度），默认。
blend_add	叠加混合模式。
blend_sub	减法混合模式。
blend_mul	乘法混合模式。
depth_draw_opaque	仅绘制不透明几何体的深度（不透明）。
depth_draw_always	始终绘制深度（不透明和透明）。
depth_draw_never	不绘制深度。
depth_prepass_alpha	对透明几何体进行不透明的深度处理。
depth_test_disabled	禁用深度测试。
sss_mode_skin	Subsurface Scattering mode for skin.
cull_back	剔除背面（默认）。
cull_front	剔除正面。
cull_disabled	禁用剔除（双面）。
unshaded	结果只使用反照率。材质中不会发生照明/阴影。
wireframe	Geometry draws using lines.
diffuse_lambert	漫反射使用 Lambert 着色（默认）。
diffuse_lambert_wrap	漫反射使用 Lambert 环绕（受粗糙度影响）。
diffuse_burley	漫反射使用 Burley（迪士尼 PBS）。
diffuse_toon	漫反射使用卡通着色。
specular_schlick_ggx	镜面反射使用 Schlick-GGX（默认）。
specular_blinn	镜面反射使用 Blinn（兼容）。
specular_phong	镜面反射使用 Phong（兼容）。
specular_toon	镜面反射使用 Toon。
specular_disabled	禁用镜面反射。
skip_vertex_transform	VERTEX/NORMAL 等需要在顶点函数中手动进行转换。
world_vertex_coords	VERTEX/NORMAL 等是以世界坐标而不是局部坐标修改的。
ensure_correct_normals	当对网格应用非均匀尺度时。
shadows_disabled	在着色器中禁用阴影计算。
ambient_light_disabled	禁用环境光和辐射度图的收益.
shadow_to_opacity	光照会改变alpha值, 阴影部分是不透明的, 而没有阴影的地方是透明的. 对于AR中将阴影堆叠到一个照相机反馈中很有用.
vertex_lighting	使用基于顶点的照明。
particle_trails	Enables the trails when used on particles geometry.
alpha_to_coverage	Alpha antialiasing mode, see here for more.
alpha_to_coverage_and_one	Alpha antialiasing mode, see here for more.
fog_disabled	Disable receiving depth-based or volumetric fog. Useful for blend_add materials like particles.

内置¶

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

全局内置¶

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

内置	描述
in float TIME	全球时间, 以秒为单位.
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, NORMAL, TANGENT, BITANGENT) 是在本地模型空间中呈现. 如果不写入, 这些值将不会被修改, 并按其原来的样子传递.

通过使用 world_vertex_coords 渲染模式, 它们可以选择性地在世界空间中呈现.

用户可以禁用内置的modelview变换(以后仍会发生投影), 并通过以下代码手动完成:

shader_type spatial;
render_mode skip_vertex_transform;

void vertex() {
    VERTEX = (MODELVIEW_MATRIX * vec4(VERTEX, 1.0)).xyz;
    NORMAL = normalize((MODELVIEW_MATRIX * vec4(NORMAL, 0.0)).xyz);
    // same as above for binormal and tangent, if normal mapping is used
}

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

用户可以使用内置的 POSITION 覆盖模型视图矩阵和投影转换。当使用 POSITION 时，将忽略 VERTEX 中的值，不会发生投影。然而，传递给片段着色器的值仍然来自于 VERTEX。

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

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

这允许你轻松地将着色器调整为使用默认粒子材质的粒子系统. 在编写自定义粒子着色器时, 可以根据需要使用这个值.

内置	描述
in vec2 VIEWPORT_SIZE	视口大小（单位为像素）。
in mat4 VIEW_MATRIX	世界空间向视图空间转变。
in mat4 INV_VIEW_MATRIX	视图空间向世界空间变换.
in mat4 INV_PROJECTION_MATRIX	裁剪空间向视图空间变换。
in vec3 NODE_POSITION_WORLD	Node world space position.
in vec3 NODE_POSITION_VIEW	Node view space position.
in vec3 CAMERA_POSITION_WORLD	Camera world space position.
in vec3 CAMERA_DIRECTION_WORLD	Camera world space direction.
in bool OUTPUT_IS_SRGB	`true` when output is in sRGB color space (this is `true` in the Compatibility renderer, `false` in Forward+ and Forward Mobile).
in int INSTANCE_ID	实例化的实例ID.
in vec4 INSTANCE_CUSTOM	实例自定义数据（主要用于粒子）。
in int VIEW_INDEX	The view that we are rendering. `VIEW_MONO_LEFT` (`0`) for Mono (not multiview) or left eye, `VIEW_RIGHT` (`1`) for right eye.
in int VIEW_MONO_LEFT	Constant for Mono or left eye, always `0`.
in int VIEW_RIGHT	Constant for right eye, always `1`.
in vec3 EYE_OFFSET	Position offset for the eye being rendered. Only applicable for multiview rendering.
inout vec3 VERTEX	局部坐标中的顶点.
in int VERTEX_ID	The index of the current vertex in the vertex buffer.
inout vec3 NORMAL	局部坐标法线.
inout vec3 TANGENT	局部坐标切线.
inout vec3 BINORMAL	局部坐标次法线.
out vec4 POSITION	如果写入, 则覆盖最终顶点位置.
inout vec2 UV	UV主通道.
inout vec2 UV2	UV2辅助通道.
inout vec4 COLOR	顶点颜色.
out float ROUGHNESS	顶点照明的粗糙度.
inout float POINT_SIZE	点渲染的点大小.
inout mat4 MODELVIEW_MATRIX	模型空间向视图空间变换(如果可用).
inout mat3 MODELVIEW_NORMAL_MATRIX
inout mat4 MODEL_MATRIX	模型空间到世界空间变换.
inout mat3 MODEL_NORMAL_MATRIX
inout mat4 PROJECTION_MATRIX	视图空间向裁剪空间变换.
inout uvec4 BONE_INDICES
inout vec4 BONE_WEIGHTS
in vec4 CUSTOM0
in vec4 CUSTOM1
in vec4 CUSTOM2
in vec4 CUSTOM3

备注

MODELVIEW_MATRIX combines both the MODEL_MATRIX and VIEW_MATRIX and is better suited when floating point issues may arise. For example, if the object is very far away from the world origin, you may run into floating point issues when using the separated MODEL_MATRIX and VIEW_MATRIX.

片段内置¶

Godot片段处理器函数的默认用法是设置对象的材质属性, 并让内置渲染器处理最终的阴影. 但是, 你无需使用所有这些属性, 如果你不写入它们,Godot将优化掉相应的功能.

内置	描述
in vec2 VIEWPORT_SIZE	视口大小（单位为像素）。
in vec4 FRAGCOORD	屏幕空间中像素中心的坐标. `xy` 表示窗口位置, 如果不使用 `DEPTH`, 则 `z` 表示片段深度. 原点在左下角.
in bool FRONT_FACING	`true` if current face if front face.
in vec3 VIEW	Normalized vector from fragment position to camera (in view space).
in vec2 UV	来自顶点功能的UV.
in vec2 UV2	来自顶点功能的UV2.
in vec4 COLOR	来自顶点功能的颜色.
in vec2 POINT_COORD	用POINT_SIZE绘制的点坐标.
in bool OUTPUT_IS_SRGB	`true` when output is in sRGB color space (this is `true` in the Compatibility renderer, `false` in Forward+ and Forward Mobile).
in mat4 MODEL_MATRIX	模型空间到世界空间变换.
in mat3 MODEL_NORMAL_MATRIX
in mat4 VIEW_MATRIX	世界空间向视图空间转变。
in mat4 INV_VIEW_MATRIX	视图空间向世界空间变换.
in mat4 PROJECTION_MATRIX	视图空间向裁剪空间变换.
in mat4 INV_PROJECTION_MATRIX	裁剪空间向视图空间变换。
in vec3 NODE_POSITION_WORLD	Node position, in world space.
in vec3 NODE_POSITION_VIEW	Node position, in view space.
in vec3 CAMERA_POSITION_WORLD	Camera position, in world space.
in vec3 CAMERA_DIRECTION_WORLD	Camera direction, in world space.
in vec3 VERTEX	来自顶点函数的顶点(默认情况下, 在视图空间中).
in int VIEW_INDEX	The view that we are rendering. `VIEW_MONO_LEFT` (`0`) for Mono (not multiview) or left eye, `VIEW_RIGHT` (`1`) for right eye.
in int VIEW_MONO_LEFT	Constant for Mono or left eye, always `0`.
in int VIEW_RIGHT	Constant for right eye, always `1`.
in vec3 EYE_OFFSET	Position offset for the eye being rendered. Only applicable for multiview rendering.
sampler2D SCREEN_TEXTURE	Removed in Godot 4. Use a `sampler2D` with `hint_screen_texture` instead.
in vec2 SCREEN_UV	屏幕当前像素的UV坐标.
sampler2D DEPTH_TEXTURE	Removed in Godot 4. Use a `sampler2D` with `hint_depth_texture` instead.
out float DEPTH	自定义深度值 (0..1)。如果在着色器的任何分支中写入了 `DEPTH`，那么你就需要负责在所有其他分支中设置 `DEPTH`。否则图形 API 不会对其进行初始化。
inout vec3 NORMAL	来自于顶点函数的法向量(默认情况下, 在视图空间中).
inout vec3 TANGENT	来自顶点函数的切线.
inout vec3 BINORMAL	来自顶点函数的Binormal.
out vec3 NORMAL_MAP	如果从纹理中读取法线而不是NORMAL, 在这里设置normal.
out float NORMAL_MAP_DEPTH	从变量上方深度. 默认为1.0.
out vec3 ALBEDO	反射(默认为白色).
out float ALPHA	Alpha (0..1);如果写入, 材质将进入透明管道.
out float ALPHA_SCISSOR_THRESHOLD	如果写入, 则丢弃低于一定量alpha的值.
out float ALPHA_HASH_SCALE
out float ALPHA_ANTIALIASING_EDGE
out vec2 ALPHA_TEXTURE_COORDINATE
out float METALLIC	金属性（0..1）。
out float SPECULAR	镜面反射。默认为 0.5，最好不要修改，除非你想改变 IOR。
out float ROUGHNESS	粗糙度(0..1).
out float RIM	边缘(0-1区间). 如果使用,Godot计算边缘照明.
out float RIM_TINT	边缘色调, 从0(白色)到1(反射). 如果使用,Godot会计算边缘光照.
out float CLEARCOAT	小幅增加镜面反射斑点。如果使用，Godot 将计算清漆涂层。
out float CLEARCOAT_GLOSS	清漆涂层的光泽度. 如果使用,Godot计算清漆涂层.
out float ANISOTROPY	用于根据切线空间扭曲镜面反射斑点。
out vec2 ANISOTROPY_FLOW	失真方向, 与流程图一起使用.
out float SSS_STRENGTH	次表面散射强度. 如果使用, 物体将应用次表面散射.
out vec4 SSS_TRANSMITTANCE_COLOR
out float SSS_TRANSMITTANCE_DEPTH
out float SSS_TRANSMITTANCE_BOOST
inout vec3 BACKLIGHT
out float AO	环境遮挡. 与预焙环境遮挡一起使用.
out float AO_LIGHT_AFFECT	环境遮挡对灯光的影响程度(取值在0到1之间. 默认为0).
out vec3 EMISSION	发射颜色(HDR可以超过1,1,1).
out vec4 FOG	If written to, blends final pixel color with FOG.rgb based on FOG.a.
out vec4 RADIANCE	If written to, blends environment map radiance with RADIANCE.rgb based on RADIANCE.a.
out vec4 IRRADIANCE	If written to, blends environment map IRRADIANCE with IRRADIANCE.rgb based on IRRADIANCE.a.

备注

因为写入 ALPHA 而经过透明管线的着色器可能受到透明排序问题的影响。更多信息及解决方法请阅读3D 渲染限制页面的透明排序章节。

内置灯光¶

编写光处理器功能是完全可选的。您可以通过设置 render_mode 为 unshaded 来跳过光照函数。如果没有写入光照函数，Godot 将使用片段函数中写入的材质属性来为您计算光照（取决于 render_mode）。

要写一个光照函数，要给 DIFFUSE_LIGHT 或 SPECULAR_LIGHT 指定一些东西。不指定任何东西意味着不处理光照。

每个像素中的每个光都调用光照函数. 在每个光类型的循环中被调用.

下面是一个使用兰伯特光照模型的自定义光函数的例子:

void light() {
    DIFFUSE_LIGHT += clamp(dot(NORMAL, LIGHT), 0.0, 1.0) * ATTENUATION * ALBEDO;
}

如果你想把这些光照加在一起，请使用 += 运算符将光线添加到 DIFFUSE_LIGHT 函数中，不要覆盖它。

警告

如果启用了 vertex_lighting 渲染模式, 或者在项目设置中启用了 Rendering渲染>Quality质量>Shading着色>强制顶点着色 , 则不会运行 light() 函数.(在移动平台上默认启用.)

内置	描述
in vec2 VIEWPORT_SIZE	视口大小（单位为像素）。
in vec4 FRAGCOORD	屏幕空间中像素中心的坐标. `xy` 表示窗口位置, 如果不使用 `DEPTH`, 则 `z` 表示片段深度. 原点在左下角.
in mat4 MODEL_MATRIX	模型空间到世界空间变换.
in mat4 INV_VIEW_MATRIX	视图空间向世界空间变换.
in mat4 VIEW_MATRIX	世界空间向视图空间转变。
in mat4 PROJECTION_MATRIX	视图空间向裁剪空间变换.
in mat4 INV_PROJECTION_MATRIX	裁剪空间向视图空间变换。
in vec3 NORMAL	法向量, 在视图空间中.
in vec2 UV	来自顶点功能的UV.
in vec2 UV2	来自顶点功能的UV2.
in vec3 VIEW	视图向量, 在视图空间中.
in vec3 LIGHT	灯光向量, 在视图空间中.
in vec3 LIGHT_COLOR	Color of light multiplied by `energy * PI`. The `PI` multiplication is present because physically-based lighting models include a division by `PI`.
in float SPECULAR_AMOUNT	2.0 * `light_specular` property for `OmniLight3D` and `SpotLight3D`. 1.0 for `DirectionalLight3D`.
in bool LIGHT_IS_DIRECTIONAL	`true` if this pass is a `DirectionalLight3D`.
in float ATTENUATION	基于距离或阴影的衰减.
in vec3 ALBEDO	基础反射.
in vec3 BACKLIGHT
in float METALLIC	Metallic.
in float ROUGHNESS	粗糙度.
in bool OUTPUT_IS_SRGB	`true` when output is in sRGB color space (this is `true` in the Compatibility renderer, `false` in Forward+ and Forward Mobile).
out vec3 DIFFUSE_LIGHT	漫射光效果.
out vec3 SPECULAR_LIGHT	镜面反射光效果。
out float ALPHA	Alpha (0..1);如果写入, 材质将进入透明管道.

备注

因为写入 ALPHA 而经过透明管线的着色器可能受到透明排序问题的影响。更多信息及解决方法请阅读3D 渲染限制页面的透明排序章节。

Transparent materials also cannot cast shadows or appear in hint_screen_texture and hint_depth_texture uniforms. This in turn prevents those materials from appearing in screen-space reflections or refraction. SDFGI sharp reflections are not visible on transparent materials (only rough reflections are visible on transparent materials).