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

渲染模式

渲染模式的可视示例见《标准 3D 材质与 ORM 3D 材质》。

渲染模式	描述
blend_mix	混合混合模式（Alpha 为透明度），默认。
blend_add	叠加混合模式。
blend_sub	减法混合模式。
blend_mul	乘法混合模式。
blend_premul_alpha	Premultiplied alpha blend mode (fully transparent = add, fully opaque = mix).
depth_draw_opaque	仅绘制不透明几何体的深度（不透明）。
depth_draw_always	始终绘制深度（不透明和透明）。
depth_draw_never	不绘制深度。
depth_prepass_alpha	对透明几何体进行不透明的深度处理。
depth_test_disabled	禁用深度测试。
sss_mode_skin	Subsurface Scattering mode for skin (optimizes visuals for human skin, e.g. boosted red channel).
cull_back	剔除背面（默认）。
cull_front	剔除正面。
cull_disabled	禁用剔除（双面）。
unshaded	结果只使用反照率。材质中不会发生照明/阴影，渲染更快。
wireframe	使用线段绘制几何体（常用于排查故障）。
debug_shadow_splits	绘制方向阴影时为不同的拆分使用不同的颜色（常用于排查故障）。
diffuse_burley	漫反射使用 Burley（迪士尼 PBS）（默认值）。
diffuse_lambert	漫反射使用 Lambert 着色。
diffuse_lambert_wrap	漫反射使用 Lambert 环绕着色（受粗糙度影响）。
diffuse_toon	漫反射使用卡通着色。
specular_schlick_ggx	直接光照镜面反射高光使用 Schlick-GGX（默认）。
specular_toon	直接光照镜面反射高光使用 Toon。
specular_disabled	禁用直接光照镜面反射高光。不影响反射光（请改用 `SPECULAR = 0.0`）。
skip_vertex_transform	`VERTEX`、`NORMAL`、`TANGENT`、`BITANGENT` 等需要在 `vertex()` 函数中手动变换。
world_vertex_coords	`VERTEX`、`NORMAL`、`TANGENT`、`BITANGENT` 等在世界空间中修改，而不是模型空间。
ensure_correct_normals	Use when non-uniform scale is applied to mesh (note: currently unimplemented).
shadows_disabled	Disable computing shadows in shader. The shader will not receive shadows, but can still cast them.
ambient_light_disabled	禁用环境光和辐射度图的收益.
shadow_to_opacity	光照会改变alpha值，阴影部分是不透明的，而没有阴影的地方是透明的。对于AR中将阴影堆叠到一个照相机反馈中很有用。
vertex_lighting	Use vertex-based lighting instead of per-pixel lighting.
particle_trails	Enables the trails when used on particles geometry.
alpha_to_coverage	Alpha 抗锯齿模式，详见此处。
alpha_to_coverage_and_one	Alpha 抗锯齿模式，详见此处。
fog_disabled	Disable receiving depth-based or volumetric fog. Useful for `blend_add` materials like particles.

内置

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.

全局内置

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

内置	描述
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	圆周率常量 `PI`（`3.141592`）。圆的周长与直径的比值，转半圈的弧度值。
in float TAU	`TAU` 常数（`6.283185`）。等价于 `PI * 2`，即转一圈对应的弧度。
in float E	`E` 常数（`2.718281`）。欧拉数，即自然对数的底。
in bool OUTPUT_IS_SRGB	输出使用 sRGB 色彩空间时为 `true`（兼容渲染器中为 `true`，Forward+ 和移动渲染器中为 `false`）。
in float CLIP_SPACE_FAR	Clip space far `z` value. In the Forward+ or Mobile renderers, it's `0.0`. In the Compatibility renderer, it's `-1.0`.

顶点内置

Vertex data (VERTEX, NORMAL, TANGENT, and BITANGENT) are presented in model space (also called local space). If not written to, these values will not be modified and be passed through as they came, then transformed into view space to be used in fragment().

They can optionally be presented in world space by using the world_vertex_coords render mode.

用户可以禁用内置的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);
    BINORMAL = normalize((MODELVIEW_MATRIX * vec4(BINORMAL, 0.0)).xyz);
    TANGENT = normalize((MODELVIEW_MATRIX * vec4(TANGENT, 0.0)).xyz);
}

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

Users can override the modelview and projection transforms using the POSITION built-in. If POSITION is written to anywhere in the shader, it will always be used, so the user becomes responsible for ensuring that it always has an acceptable value. When POSITION is used, the value from VERTEX is ignored and projection does not happen. However, the value passed to the fragment shader still comes from VERTEX.

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

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

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

内置	描述
in vec2 VIEWPORT_SIZE	视口大小（单位为像素）。
in mat4 VIEW_MATRIX	世界空间到视图空间变换。
in mat4 INV_VIEW_MATRIX	视图空间到世界空间的变换。
in mat4 MAIN_CAM_INV_VIEW_MATRIX	视图空间到绘制当前视口的相机的世界空间变换。
in mat4 INV_PROJECTION_MATRIX	裁剪空间到视图空间的变换。
in vec3 NODE_POSITION_WORLD	节点的位置，使用世界空间。
in vec3 NODE_POSITION_VIEW	节点的位置，使用视图空间。
in vec3 CAMERA_POSITION_WORLD	相机的位置，使用世界空间。
in vec3 CAMERA_DIRECTION_WORLD	相机的方向，使用世界空间。
in uint CAMERA_VISIBLE_LAYERS	剔除当前渲染阶段中相机不渲染的图层。
in int INSTANCE_ID	实例化的实例 ID。
in vec4 INSTANCE_CUSTOM	实例自定义数据（主要用于粒子）。
in int VIEW_INDEX	我们正在渲染的视图。对于单视图（非多视图）或左眼视图，使用``VIEW_MONO_LEFT`` (`0`)，对于右眼视图使用``VIEW_RIGHT`` (`1`) 。
in int VIEW_MONO_LEFT	单视图或左眼视图的常量，恒为 `0`。
in int VIEW_RIGHT	右眼视图常量，恒为 `1`。
in vec3 EYE_OFFSET	正在渲染的眼睛处的偏移量，仅适用于多视图渲染。
inout vec3 VERTEX	模型空间中的顶点位置。如果使用了 `world_vertex_coords` 则使用世界空间。
in int VERTEX_ID	顶点缓冲区中当前顶点的索引。
inout vec3 NORMAL	模型空间中的法线。如果使用了 `world_vertex_coords` 则使用世界空间。
inout vec3 TANGENT	模型空间中的切线。如果使用了 `world_vertex_coords` 则使用世界空间。
inout vec3 BINORMAL	模型空间中的副法线。如果使用了 `world_vertex_coords` 则使用世界空间。
out vec4 POSITION	If written to, overrides final vertex position in clip space.
inout vec2 UV	UV主通道.
inout vec2 UV2	UV2辅助通道.
inout vec4 COLOR	顶点颜色.
out float ROUGHNESS	顶点照明的粗糙度.
inout float POINT_SIZE	点渲染的点大小.
inout mat4 MODELVIEW_MATRIX	Model/local space to view space transform (use if possible).
inout mat3 MODELVIEW_NORMAL_MATRIX
in mat4 MODEL_MATRIX	Model/local space to world space transform.
in mat3 MODEL_NORMAL_MATRIX
inout mat4 PROJECTION_MATRIX	视图空间向裁剪空间变换.
in uvec4 BONE_INDICES
in vec4 BONE_WEIGHTS
in vec4 CUSTOM0	Custom value from vertex primitive. When using extra UVs, `xy` is UV3 and `zw` is UV4.
in vec4 CUSTOM1	Custom value from vertex primitive. When using extra UVs, `xy` is UV5 and `zw` is UV6.
in vec4 CUSTOM2	Custom value from vertex primitive. When using extra UVs, `xy` is UV7 and `zw` is UV8.
in vec4 CUSTOM3	Custom value from vertex primitive.

备注

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.

备注

INV_VIEW_MATRIX is the matrix used for rendering the object in that pass, unlike MAIN_CAM_INV_VIEW_MATRIX, which is the matrix of the camera in the scene. In the shadow pass, INV_VIEW_MATRIX's view is based on the camera that is located at the position of the light.

片段内置

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

内置	描述
in vec2 VIEWPORT_SIZE	视口大小（单位为像素）。
in vec4 FRAGCOORD	Coordinate of pixel center in screen space. `xy` specifies position in window. Origin is lower left. `z` specifies fragment depth. It is also used as the output value for the fragment depth unless `DEPTH` is written to.
in bool FRONT_FACING	如果当前的面展示的是正面则为 `true`，否则为 `false`。
in vec3 VIEW	片段位置到相机位置（在视图空间中）的归一化向量，该向量对于透视相机和正交相机而言是相同的。
in vec2 UV	来自 `vertex()` 函数的 UV。
in vec2 UV2	来自 `vertex()` 函数的 UV2。
in vec4 COLOR	来自 `vertex()` 函数的 COLOR。
in vec2 POINT_COORD	使用 `POINT_SIZE` 绘制点的点坐标。
in mat4 MODEL_MATRIX	Model/local space to world space transform.
in mat3 MODEL_NORMAL_MATRIX	Model/local space to world space transform for normals. This is the same as `MODEL_MATRIX` by default unless the object is scaled non-uniformly, in which case this is set to `transpose(inverse(mat3(MODEL_MATRIX)))`.
in mat4 VIEW_MATRIX	世界空间到视图空间变换。
in mat4 INV_VIEW_MATRIX	视图空间到世界空间的变换。
in mat4 PROJECTION_MATRIX	视图空间向裁剪空间变换.
in mat4 INV_PROJECTION_MATRIX	裁剪空间到视图空间的变换。
in vec3 NODE_POSITION_WORLD	节点的位置，使用世界空间。
in vec3 NODE_POSITION_VIEW	节点的位置，使用视图空间。
in vec3 CAMERA_POSITION_WORLD	相机的位置，使用世界空间。
in vec3 CAMERA_DIRECTION_WORLD	相机的方向，使用世界空间。
in uint CAMERA_VISIBLE_LAYERS	剔除当前渲染阶段中相机不渲染的图层。
in vec3 VERTEX	Position of the fragment (pixel), in view space. It is the `VERTEX` value from `vertex()` interpolated between the face's vertices and transformed into view space. If `skip_vertex_transform` is enabled, it may not be in view space.
inout vec3 LIGHT_VERTEX	一个可写的``VERTEX``版本，可用于调整光照和阴影的效果，对其写入数据时不会改变片段的位置。
in int VIEW_INDEX	The view that we are rendering. Used to distinguish between views in multiview/stereo rendering. `VIEW_MONO_LEFT` (`0`) for Mono (not multiview) or left eye, `VIEW_RIGHT` (`1`) for right eye.
in int VIEW_MONO_LEFT	单视图或左眼视图的常量，恒为 `0`。
in int VIEW_RIGHT	右眼视图常量，恒为 `1`。
in vec3 EYE_OFFSET	正在渲染的眼睛处的偏移量，仅适用于多视图渲染。
sampler2D SCREEN_TEXTURE	在 Godot 4 中移除。请改用 `sampler2D` 和 `hint_screen_texture`。
in vec2 SCREEN_UV	屏幕当前像素的UV坐标.
sampler2D DEPTH_TEXTURE	在 Godot 4 中移除。请改用 `sampler2D` 和 `hint_depth_texture`。
out float DEPTH	Custom depth value (range of `[0.0, 1.0]`). If `DEPTH` is being written to in any shader branch, then you are responsible for setting the `DEPTH` for all other branches. Otherwise, the graphics API will leave them uninitialized.
inout vec3 NORMAL	Normal that comes from the `vertex()` function, in view space. If `skip_vertex_transform` is enabled, it may not be in view space.
inout vec3 TANGENT	Tangent that comes from the `vertex()` function, in view space. If `skip_vertex_transform` is enabled, it may not be in view space.
inout vec3 BINORMAL	Binormal that comes from the `vertex()` function, in view space. If `skip_vertex_transform` is enabled, it may not be in view space.
out vec3 NORMAL_MAP	Set normal here if reading normal from a texture instead of `NORMAL`.
out float NORMAL_MAP_DEPTH	`NORMAL_MAP` 中的深度。默认为 `1.0`。
out vec3 ALBEDO	反照率（默认为白色）。基础颜色。
out float ALPHA	Alpha (range of `[0.0, 1.0]`). If read from or written to, the material will go to the transparent pipeline.
out float ALPHA_SCISSOR_THRESHOLD	如果写入, 则丢弃低于一定量alpha的值.
out float ALPHA_HASH_SCALE	Alpha hash scale when using the alpha hash transparency mode. Defaults to `1.0`. Higher values result in more visible pixels in the dithering pattern.
out float ALPHA_ANTIALIASING_EDGE	The threshold below which alpha to coverage antialiasing should be used. Defaults to `0.0`. Requires the `alpha_to_coverage` render mode. Should be set to a value lower than `ALPHA_SCISSOR_THRESHOLD` to be effective.
out vec2 ALPHA_TEXTURE_COORDINATE	The texture coordinate to use for alpha-to-coverge antialiasing. Requires the `alpha_to_coverage` render mode. Typically set to `UV * vec2(albedo_texture_size)` where `albedo_texture_size` is the size of the albedo texture in pixels.
out float PREMUL_ALPHA_FACTOR	Premultiplied alpha factor. Only effective if `render_mode blend_premul_alpha;` is used. This should be written to when using a shaded material with premultiplied alpha blending for interaction with lighting. This is not required for unshaded materials.
out float METALLIC	金属性（范围为 `[0.0, 1.0]`）。
out float SPECULAR	Specular (not physically accurate to change). Defaults to `0.5`. `0.0` disables reflections.
out float ROUGHNESS	粗糙度（范围为 `[0.0, 1.0]`）。
out float RIM	Rim (range of `[0.0, 1.0]`). If used, Godot calculates rim lighting. Rim size depends on `ROUGHNESS`.
out float RIM_TINT	Rim Tint, range of `0.0` (white) to `1.0` (albedo). If used, Godot calculates rim lighting.
out float CLEARCOAT	Small specular blob added on top of the existing one. If used, Godot calculates clearcoat.
out float CLEARCOAT_GLOSS	Gloss of clearcoat. If used, Godot calculates clearcoat.
out float ANISOTROPY	用于根据切线空间扭曲镜面反射斑点。
out vec2 ANISOTROPY_FLOW	失真方向, 与流程图一起使用.
out float SSS_STRENGTH	Strength of subsurface scattering. If used, subsurface scattering will be applied to the object.
out vec4 SSS_TRANSMITTANCE_COLOR	Color of subsurface scattering transmittance. If used, subsurface scattering transmittance will be applied to the object.
out float SSS_TRANSMITTANCE_DEPTH	Depth of subsurface scattering transmittance. Higher values allow the effect to reach deeper into the object.
out float SSS_TRANSMITTANCE_BOOST	Boosts the subsurface scattering transmittance if set above `0.0`. This makes the effect show up even on directly lit surfaces
inout vec3 BACKLIGHT	Color of backlighting (works like direct light, but it's received even if the normal is slightly facing away from the light). If used, backlighting will be applied to the object. Can be used as a cheaper approximation of subsurface scattering.
out float AO	Strength of ambient occlusion. For use with pre-baked AO.
out float AO_LIGHT_AFFECT	How much ambient occlusion affects direct light (range of `[0.0, 1.0]`, default `0.0`).
out vec3 EMISSION	Emission color (can go over `(1.0, 1.0, 1.0)` for HDR).
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 渲染限制页面的透明排序章节。

内置灯光

Writing light processor functions is completely optional. You can skip the light() function by using the unshaded render mode. If no light function is written, Godot will use the material properties written to in the fragment() function to calculate the lighting for you (subject to the render mode).

The light() function is called for every light in every pixel. It is called within a loop for each light type.

Below is an example of a custom light() function using a Lambertian lighting model:

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

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

警告

The light() function won't be run if the vertex_lighting render mode is enabled, or if Rendering > Quality > Shading > Force Vertex Shading is enabled in the Project Settings. (It's enabled by default on mobile platforms.)

内置	描述
in vec2 VIEWPORT_SIZE	视口大小（单位为像素）。
in vec4 FRAGCOORD	屏幕空间中像素中心的坐标. `xy` 表示窗口位置, 如果不使用 `DEPTH`, 则 `z` 表示片段深度. 原点在左下角.
in mat4 MODEL_MATRIX	Model/local space to world space transform.
in mat4 INV_VIEW_MATRIX	视图空间到世界空间的变换。
in mat4 VIEW_MATRIX	世界空间到视图空间变换。
in mat4 PROJECTION_MATRIX	视图空间向裁剪空间变换.
in mat4 INV_PROJECTION_MATRIX	裁剪空间到视图空间的变换。
in vec3 NORMAL	法向量, 在视图空间中.
in vec2 SCREEN_UV	屏幕当前像素的UV坐标.
in vec2 UV	来自 `vertex()` 函数的 UV。
in vec2 UV2	来自 `vertex()` 函数的 UV2。
in vec3 VIEW	视图向量, 在视图空间中.
in vec3 LIGHT	Light vector, in view space.
in vec3 LIGHT_COLOR	Light color multiplied by light energy multiplied by `PI`. The `PI` multiplication is present because physically-based lighting models include a division by `PI`.
in float SPECULAR_AMOUNT	For OmniLight3D and SpotLight3D, `2.0` multiplied by light_specular. For DirectionalLight3D, `1.0`.
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	粗糙度.
out vec3 DIFFUSE_LIGHT	漫射光效果.
out vec3 SPECULAR_LIGHT	镜面反射光效果。
out float ALPHA	Alpha (range of `[0.0, 1.0]`). If written to, the material will go to the transparent pipeline.

备注

因为写入 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).