Up to date

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

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	次表面散射
cull_back	剔除背面（預設）。
cull_front	剔除正面。
cull_disabled	禁用剔除（雙面）。
unshaded	結果只使用反照率。材質中不會發生照明/陰影。
線框	幾何圖形使用線條進行繪製。
diffuse_burley	Burley (Disney PBS) for diffuse (default).
diffuse_lambert	Lambert shading for diffuse.
diffuse_lambert_wrap	漫反射使用 Lambert 環繞（受粗糙度影響）。
diffuse_toon	漫反射使用卡通著色。
specular_schlick_ggx	鏡面反射使用 Schlick-GGX（預設）。
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	使用基於頂點的照明。
粒子：	在粒子幾何體上使用時啟用軌跡。
alpha_to_coverage	core/set.h
alpha_to_coverage_and_one	core/set.h
fog_disabled	停用接收基於深度或體積的霧氣。對於 Blend_add 材質（例如粒子）很有用。

內建

標記為 "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	An `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);
    BINORMAL = normalize((MODELVIEW_MATRIX * vec4(BINORMAL, 0.0)).xyz);
    TANGENT = normalize((MODELVIEW_MATRIX * vec4(TANGENT, 0.0)).xyz);
}

其他的內建函式, 如UV, UV2和COLOR, 如果沒有修改, 也會傳遞給fragment片段函式.

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.

對於產生實體，INSTANCE_CUSTOM變數包含實例自訂資料. 使用粒子時, 此資訊通常是:

x：旋轉角度，單位為弧度。
y：生命週期的階段（0 到 1）。
z：動畫影格。

這允許你輕鬆地將著色器調整為使用預設粒子材質的粒子系統. 在編寫自訂粒子著色器時, 可以根據需要使用這個值.

內建	說明
in vec2 VIEWPORT_SIZE	視口大小（單位為像素）。
in mat4 VIEW_MATRIX	世界空間向視圖空間轉變。
in mat4 INV_VIEW_MATRIX	視圖空間向世界空間變換.
in mat4 MAIN_CAM_INV_VIEW_MATRIX	View space to world space transform of camera used to draw the current viewport.
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	Cull layers of the camera rendering the current pass.
in bool OUTPUT_IS_SRGB	當計算發生在sRGB色彩空間時為 `true` (GLES2為 `true` ,GLES3為 `false` ).
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	局部座標中的頂點.
in int VERTEX_ID	頂點緩衝區中目前頂點的索引。
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
in mat4 MODEL_MATRIX	模型空間到世界空間變換.
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 結合了 WORLD_MATRIX 和 INV_CAMERA_MATRIX，更適合可能會造成浮點數問題的場合。例如，如果物件距離世界原點非常遠，那麼使用單獨的 WORLD_MATRIX 和 INV_CAMERA_MATRIX 可能就會遇到浮點數問題。

備註

INV_VIEW_MATRIX is the matrix used for rendering the object in that pass, not like 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` if current face is front facing.
in vec3 VIEW	Normalized vector from fragment position to camera (in view space). This is the same for both perspective and orthogonal cameras.
in vec2 UV	來自頂點功能的UV.
in vec2 UV2	來自頂點功能的UV2.
in vec4 COLOR	來自頂點功能的顏色.
in vec2 POINT_COORD	用POINT_SIZE繪製的點座標.
in bool OUTPUT_IS_SRGB	當計算發生在sRGB色彩空間時為 `true` (GLES2為 `true` ,GLES3為 `false` ).
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	節點的位置，使用世界空間。
in vec3 NODE_POSITION_VIEW	節點的位置，使用視圖空間。
in vec3 CAMERA_POSITION_WORLD	相機的位置，使用世界空間。
in vec3 CAMERA_DIRECTION_WORLD	相機的方向，使用世界空間。
in uint CAMERA_VISIBLE_LAYERS	Cull layers of the camera rendering the current pass.
in vec3 VERTEX	來自頂點函式的頂點(預設情況下, 在視圖空間中).
inout vec3 LIGHT_VERTEX	A writable version of `VERTEX` that can be used to alter light and shadows. Writing to this will not change the position of the fragment.
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	正在算繪的眼睛的位置偏移。僅適用於多視圖算繪。
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	自訂深度值 (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); 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
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	如果寫入，則根據 FOG.a 將最終像素顏色與 FOG.rgb 混合。
out vec4 RADIANCE	如果寫入，則將環境貼圖輻射度與基於 RADIANCE.a 的 RADIANCE.rgb 混合。
out vec4 IRRADIANCE	如果寫入，則將環境貼圖 IRRADIANCE 與基於 IRRADIANCE.a 的 IRRADIANCE.rgb 混合。

備註

因為寫入 ALPHA 而經過透明管線的著色器可能受到透明排序問題的影響。更多資訊及解決方法請閱讀:ref:3D 算繪限制頁面的透明排序章節 <doc_3d_rendering_limitations_transparency_sorting>。

內建燈光

編寫光處理器功能是完全可選的。您可以通過設定 render_mode 為 unshaded 來跳過光照函式。如果沒有寫入光照函式，Godot 將使用片段函式中寫入的材質屬性來為您計算光照（取決於 render_mode）。

每個像素中的每個光都呼叫光照函式. 在每個光型別的迴圈中被呼叫.

下面是一個使用蘭伯特光照模型的自訂光函式的例子:

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

如果你想把這些光照加在一起，請使用 += 運算子將光線新增到 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	光的顏色乘以「能量 * PI」。存在“PI”乘法是因為基於物理的光照模型包含除以“PI”。
in float SPECULAR_AMOUNT	2.0 * `OmniLight3D` 和 `SpotLight3D` 的 `light_specular` 屬性。 1.0 用於「DirectionalLight3D」。
in bool LIGHT_IS_DIRECTIONAL	如果 `true` 代表光照通道.
in float ATTENUATION	基於距離或陰影的衰減.
in vec3 ALBEDO	基礎反射.
in vec3 BACKLIGHT
in float METALLIC	Metallic(金屬)。
in float ROUGHNESS	粗糙度.
in bool OUTPUT_IS_SRGB	當計算發生在sRGB色彩空間時為 `true` (GLES2為 `true` ,GLES3為 `false` ).
out vec3 DIFFUSE_LIGHT	漫射光效果.
out vec3 SPECULAR_LIGHT	鏡面反射光效果。
out float ALPHA	Alpha (0..1);如果寫入, 材質將進入透明管道.

備註

因為寫入 ALPHA 而經過透明管線的著色器可能受到透明排序問題的影響。更多資訊及解決方法請閱讀:ref:3D 算繪限制頁面的透明排序章節 <doc_3d_rendering_limitations_transparency_sorting>。

透明材質也不能投射陰影或出現在「hint_screen_texture」和「hint_depth_texture」制服中。這反過來又防止這些材質出現在螢幕空間反射或折射中。 SDFGI 銳反射在透明材料上不可見（在透明材料上僅可見粗糙反射）。