tutorials/shaders/shader_reference/spatial_shader

[giscus[bot]]

tutorials/shaders/shader_reference/spatial_shader

Spatial shaders are used for shading 3D objects. They are the most complex type of shader Godot offers. Spatial shaders are highly configurable with different render modes and different rendering o...

https://docs.godotengine.org/en/stable/tutorials/shaders/shader_reference/spatial_shader.html

[BunkWire2X8]

There's an issue with the ALPHA_SCISSOR_THRESHOLD description here. It claims that "If written to, values below a certain amount of alpha are discarded.". Emphasis on "If written to" here, as the code here...

if (false) {
    ALPHA_SCISSOR_THRESHOLD = alpha_scissor_threshold;
}

...still activates the scissor threshold, despite there being nothing written to it. Same with ALPHA_HASH_SCALE, but that's less of an issue, considering that one doesn't have a description to begin with.

[metsweet999]

I spent a lot of time understanding the content related to VERTEX, NORMAL, TANGENT, BITANGENT, and POSITION. The following notes can help you save some time.

Term explanation:

• Model space/local space refers to the coordinate system based on the model itself, usually with the origin at the model's center or the mesh's (0,0,0) position. Transform operations like rotation and scaling are relative to this coordinate system. For example, the vertex coordinates of a cube in model space may range from (-1,-1,-1) to (1,1,1).
• World space is the global unified coordinate system shared by all objects, with the origin typically at the scene's (0,0,0) point. The position, rotation, and scaling of objects are relative to this global coordinate system. For instance, a cube located at (5,0,3) indicates its position in the world coordinate system.
• View space, also known as camera space, has its origin at the camera and the Z-axis pointing in the direction of view.
• Clip space, or projection space, is the coordinate space output by the vertex shader. "Frustum culling" is performed in this space. The coordinate range is from -w to w (w is the w component of homogeneous coordinates), and any geometry outside this range is automatically clipped by the GPU. It can be considered as a "waiting area for clipping."
• Normalized device coordinates (NDC) are the coordinates obtained after applying the "perspective divide" (x/w, y/w, z/w) to clip space coordinates. The coordinate range is fixed to a cube space of [-1, 1], with the lower-left corner at (-1,-1,-1) and the upper-right corner at (1,1,1). All visible 3D objects are ultimately mapped to this standard cube, which can be thought of as a "unified standard display platform."

Main related variables:

• inout vec3 VERTEX represents the vertex coordinates in local coordinates.
• inout vec3 NORMAL represents the normal in local coordinates.
• inout vec3 TANGENT represents the tangent in local coordinates.
• inout vec3 BINORMAL represents the binormal in local coordinates.
• out vec4 POSITION is used to provide NDC data in the fragment function stage.

Discussion:
By default, VERTEX stores the vertex's model-local coordinates at the end of the vertex function stage. Then, the VERTEX value is extracted for the following calculations: transformed from [model space] to [view space] using MODELVIEW_MATRIX, then to [clip space] using PROJECTION_MATRIX, and finally to [NDC] through perspective division. The calculated NDC value is assigned to the POSITION variable, while VERTEX retains its pre-calculation value. This assignment to POSITION occurs before the fragment function stage, allowing users to access POSITION in the fragment function to utilize the depth value in NDC for manual rendering order sorting and other related operations.

Note: MODELVIEW_MATRIX = MODEL_MATRIX * VIEW_MATRIX, where MODEL_MATRIX transforms model space to world space, and VIEW_MATRIX transforms world space to view space. Thus, MODELVIEW_MATRIX internally includes the transformation matrix from model space to world space.

When the world_vertex_coords mode is enabled, VERTEX is automatically transformed to world space coordinates using MODEL_MATRIX before the vertex function is executed. Between the vertex and fragment functions, the calculation process for POSITION's NDC value changes: the VERTEX value is extracted, transformed from [world space] to [view space] using VIEW_MATRIX, then to [clip space] using PROJECTION_MATRIX, and finally to [NDC] through perspective division. The VERTEX variable passed to the fragment function remains in world space coordinates.

When the skip_vertex_transform mode is enabled, the automatic transformation of VERTEX from model space to view space is disabled. The world_vertex_coords mode handles the transformation of VERTEX from model space to view space, so it may not be usable (unverified). Users need to manually calculate the VERTEX value transformed to [view space] and assign it to VERTEX before the end of the vertex function. Between the vertex and fragment functions, the calculation process for POSITION's NDC value changes: the VERTEX value is extracted, transformed to [clip space] using PROJECTION_MATRIX, and then to [NDC] through perspective division. The VERTEX variable passed to the fragment function remains in view space coordinates.

If the POSITION variable is manually written in the vertex function, Godot assumes that POSITION has already obtained the correct clip space data. Between the vertex and fragment functions, the calculation process for POSITION's NDC value is no longer based on extracting and computing the VERTEX value. Instead, it becomes: extracting the POSITION value and transforming it to [NDC] through perspective division. The VERTEX variable passed to the fragment function remains the same data as at the end of the vertex function.

[metsweet999]

The above translation of my Chinese notes was done via AI, so its accuracy isn't guaranteed. Here's the original text for your reference：“

术语解释：
· 模型空间（Model Space / Local Space）
也称为局部坐标系
以模型自身为基准的坐标系
原点通常是模型的中心点或网格的(0,0,0)位置
旋转、缩放等变换操作都是相对于这个坐标系进行的
例如：一个立方体的顶点坐标在模型空间中可能是(-1,-1,-1)到(1,1,1)
· 世界空间（World Space）
全局统一的坐标系
所有对象共享的坐标系系统
原点通常是场景的(0,0,0)点
对象的位置、旋转和缩放都是相对于这个全局坐标系
例如：一个位于(5,0,3)的立方体表示它在世界坐标系中的位置；
· 观察空间（View Space）
别名：又称"相机空间"（Camera Space）
定义：观察空间的原点是摄像机，Z轴指向拍摄方向
· 裁剪空间（Clip Space）
别名：投影空间（Projection Space）
顶点着色器输出的坐标空间
在这个空间里会进行"视锥体裁剪"（Frustum Culling）
坐标范围是-w到w（w是齐次坐标的w分量）
任何超出这个范围的几何体都会被GPU自动裁剪掉
可以理解为"准备裁剪的候场区"
· 标准化设备坐标（NDC）
裁剪空间坐标经过"透视除法"(x/w, y/w, z/w)后得到的坐标
坐标范围固定为[-1, 1]的立方体空间
左下角是(-1,-1,-1)，右上角是(1,1,1)
所有可见的3D物体最终都会被映射到这个标准立方体中
可以理解为"统一标准的展示台"

主要相关变量
inout vec3 VERTEX
局部坐标中的顶点坐标
inout vec3 NORMAL
局部坐标中的法线
inout vec3 TANGENT
局部坐标中的切线
inout vec3 BINORMAL
局部坐标中的副法线
out vec4 POSITION
用于在fragment函数阶段提供标准化设备坐标NDC数据；

论述正文
（NORMAL，TANGENT，BINORMAL，三者与下文中的VERTEX变量同理；）
——————
默认情况下，VERTEX在vertex函数阶段结束的时候储存的是顶点的模型局部坐标，之后会提取VERTEX数值进行下述计算：
从[模型空间] 用MODELVIEW_MATRIX 转化为 [观察空间] ，
然后用PROJECTION_MATRIX 转化为 [裁剪空间]，然后用透视除法 转化为 [标准化设备坐标NDC]；
计算得到的标准化设备坐标NDC数值会赋予POSITION变量，VERTEX变量内仍然是该计算之前的数值；
对POSITION变量的该赋值动作发生在fragment函数阶段之前；
这样，用户在fragment函数中就可以读取储存了标准化设备坐标NDC数值的POSITION变量，就可以使用标准化设备坐标NDC数值中的深度数值进行手动的绘制顺序的排序，以及进行其他可能的相关操作；
——————
注：
MODELVIEW_MATRIX = MODEL_MATRIX * VIEW_MATRIX
其中，
MODEL_MATRIX 将模型空间转换为世界空间； VIEW_MATRIX 将世界空间转换为观察空间；
换言之，MODELVIEW_MATRIX 内部已经包含了从模型空间到世界空间的变换矩阵；
——————
当_world_vertex_coords_模式打开，在vertex函数执行之前，VERTEX会被使用MODEL_MATRIX自动转换为世界空间坐标；
在vertex函数与fragment函数之间，对POSITION的标准化设备坐标NDC数值的计算过程不再是：
提取VERTEX数值，
从[模型空间] 用MODELVIEW_MATRIX 转化为 [观察空间] ，
然后用PROJECTION_MATRIX 转化为 [裁剪空间]，
然后用透视除法 转化为 [标准化设备坐标NDC]；
而是变为：
提取VERTEX数值，
从[世界空间] 用VIEW_MATRIX 转化为 [观察空间] ，
然后用PROJECTION_MATRIX 转化为 [裁剪空间]，
然后用透视除法 转化为 [标准化设备坐标NDC]；
传递给fragment函数的VERTEX变量仍然是世界空间的坐标数据；
——————
当打开skip_vertex_transform模式，VERTEX从模型空间到观察空间之间的自动转换会被禁止；
world_vertex_coords_模式负责VERTEX从模型空间到观察空间的转换，所以此时会无法使用（未验证）；
用户需要在vertex函数结束之前，从VERTEX的数值手动计算出该数值转化为[观察空间]后的结果并赋值给VERTEX；
之后在vertex函数与fragment函数之间，对POSITION的标准化设备坐标NDC数值的计算过程将不再是：
提取VERTEX数值，
从[模型空间] 用MODELVIEW_MATRIX 转化为 [观察空间] ，
然后用PROJECTION_MATRIX 转化为 [裁剪空间]，
然后用透视除法 转化为 [标准化设备坐标NDC]；
而是变为：
提取VERTEX数值，
用PROJECTION_MATRIX 转化为 [裁剪空间]，
然后用透视除法 转化为 [标准化设备坐标NDC]；
传递给fragment函数的VERTEX变量仍然是观察空间的坐标数据；
——————
如果在vertex函数中POSITION变量被用户手动写入，godot会认为POSITOION已经获得正确的裁剪空间数据；
在vertex函数与fragment函数之间，对POSITION的标准化设备坐标NDC数值的计算过程将不再是提取VERTEX数值进行运算，而是变为：
提取POSITION数值，
用透视除法 转化为 [标准化设备坐标NDC]；
传递给fragment函数的VERTEX变量仍然是vertex函数结束时的相同数据；
”

PS：
The notes may not be entirely accurate. Corrections are welcome.

[gitsomebit]

I found this cheet sheet recently that is very useful:
https://www.reddit.com/r/godot/comments/16p8n2k/godot_shader_cheat_sheet_i_made_because_i_always/

[Theome]

MODEL_MATRIX has the same description in Vertex built-ins and Fragment built-ins, but there is a difference: If you have a multimesh, MODEL_MATRIX in fragment() is not the model to world transform of the instance, but of something else (the node?). If you need the transform of the instance, use MODEL_MATRIX in vertex() instead.

For example, if you need the position of the model in world coordinates:

varying vec3 model_position;

void vertex() {
  // Position of the model in world coordinates.
  model_position = (MODEL_MATRIX * vec4(0.0, 0.0, 0.0, 1.0)).xyz;
}

void fragment() {
  // Use model_position here
}

[RayKoopa]

Note that there is an additional depth_test_inverted render mode as used by BaseMaterial3D, which is not documented here.

[Calinou]

This is being tracked in godotengine/godot-docs#10991. See also godotengine/godot-docs#11373 which I've opened for the BaseMaterial3D functionality.