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.

CanvasItem 著色器

畫布組件著色器用於繪製Godot中的所有二維元素. 這包括從畫布組件繼承的所有節點, 以及所有圖形化使用者介面元素.

畫布元件著色器比 空間著色器 包含更少的內建變數和功能, 但它們與頂點, 片段和光處理器功能保持相同的基本結構.

算繪模式

算繪模式

說明

blend_mix

混合混合模式(Alpha 為透明度),預設。

blend_add

加法混合模式。

blend_sub

減法混合模式。

blend_mul

乘法混合模式。

blend_premul_alpha

預乘 Alpha 混合模式。

blend_disabled

禁用混合,值(包括 Alpha)會按原樣寫入。

unshaded

結果只使用反照率。材質中不會發生照明/陰影。

light_only

僅在光照通道(light pass)中進行繪製。

skip_vertex_transform

VERTEX/NORMAL/等需要在頂點函式中手動轉換.

world_vertex_coords

VERTEX/NORMAL 等是以世界座標而不是局部座標修改的。

內建變數

標記為 in 的值為唯讀。標記為 out 的值可以選擇寫入,且不一定包含合理的預設值。標記為 inout 的值則有預設值,可以選擇寫入。取樣器(sampler)無法寫入,因此未標註。

並非所有內建變數都能在所有處理函式中使用。若要在 fragment() 函式中存取頂點階段內建變數,可以利用 varying。同理,若需在 light() 函式中存取片段階段的內建變數,也請使用 varying。

全域內建變數

全域內建變數可於任何地方使用,包括自訂函式中。

內建變數

說明

in float TIME

自引擎啟動以來的全域時間,以秒為單位。它每經過 3,600 秒就會重設循環一次(這個時長可以通過 rollover 設定來修改)。它受 time_scale (時間縮放/遊戲速度)的影響,但不受暫停(pausing)的影響。如果你需要一個不受 time_scale 影響的 TIME 變數,可以新增你自己的 global shader uniform ,並在每一影格更新它。

in float PI

常數 PI (值為 3.141592 )。它是圓的周長與直徑的比值,也是轉半圈(180度)所包含的弧度數。

in float TAU

常數 TAU (值為 6.283185 )。它等同於 PI * 2 ,也就是一個完整圓周(整圈)所包含的弧度數。

in float E

常數 E (值為 2.718281 )。即歐拉數,自然對數的底數。

頂點階段內建變數

頂點資料( VERTEX )是以局部空間(像素座標, 相對於相機)呈現. 如果不寫入, 這些值將不會被修改, 並按其來時的樣子傳遞.

使用者可以禁用內建的modelview變換(以後仍然會發生投影), 並通過以下程式碼手動完成:

shader_type canvas_item;
render_mode skip_vertex_transform;

void vertex() {

    VERTEX = (MODEL_MATRIX * vec4(VERTEX, 0.0, 1.0)).xy;
}

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

在產生實體(instancing)時,INSTANCE_CUSTOM 變數包含自訂實例資料。用於粒子時內容通常如下:

  • x:旋轉角度,單位為弧度。

  • y:生命週期進度階段(0.0 ~ 1.0)。

  • z:動畫影格索引。

內建變數

說明

in mat4 MODEL_MATRIX

局部空間到世界空間的變換。世界空間是您通常在編輯器中使用的座標。

in mat4 CANVAS_MATRIX

從世界空間到畫布空間的轉換矩陣。在畫布空間中,螢幕的左上角是座標原點 (0, 0),座標範圍從 (0.0, 0.0) 一直延伸到視埠的大小。

in mat4 SCREEN_MATRIX

從畫布空間(Canvas space)到裁剪空間(Clip space)的變換。在裁剪空間中,座標的取值範圍是從 (-1.0, -1.0) 到 (1.0, 1.0).

in int INSTANCE_ID

產生實體(instancing)時的實例 ID。

in vec4 INSTANCE_CUSTOM

實例自訂資料.

in bool AT_LIGHT_PASS

總是 false.

in vec2 TEXTURE_PIXEL_SIZE

預設 2D 紋理的正規化像素尺寸。對於一個紋理尺寸為 64x32 像素的 Sprite2D 來說,TEXTURE_PIXEL_SIZE = vec2(1.0/64.0, 1.0/32.0)。

inout vec2 VERTEX

頂點, 在圖像空間.

in int VERTEX_ID

目前頂點在頂點緩衝區中的索引。

inout vec2 UV

標準化紋理座標。範圍從 0 到 1。

inout vec4 COLOR

來自頂點圖元的顏色,乘以 CanvasItem 的 modulate (調制色),再乘以 CanvasItem 的 self_modulate (自身調制色)。

inout float POINT_SIZE

點繪圖的點大小.

in vec4 CUSTOM0

來自頂點原始資料的自訂值。

in vec4 CUSTOM1

來自頂點原始資料的自訂值。

片段階段內建變數

COLOR 與 TEXTURE

內建變數 COLOR 有以下幾種用途:

  • 在 vertex() 函式中,COLOR 包含來自頂點圖元的顏色,乘以 CanvasItem 的 modulate,再乘以 CanvasItem 的 self_modulate。

  • 在 fragment() 函式中,輸入值 COLOR 為上述顏色再乘以預設 TEXTURE 的顏色(若有設定)。

  • 在 fragment() 函式中,COLOR 也是最終的輸出值。

某些節點(如 Sprite2D)預設會顯示一張材質,例如 texture。使用自訂的 fragment() 函式時,您有數種方式可以取樣該材質。

若只需讀取預設材質的內容,忽略頂點 COLOR:

void fragment() {
  COLOR = texture(TEXTURE, UV);
}

若需讀取預設材質內容並乘以頂點 COLOR:

void fragment() {
  // Equivalent to an empty fragment() function, since COLOR is also the output variable.
  COLOR = COLOR;
}

若需在 fragment() 中只讀取頂點 COLOR 而忽略主材質,必須將 COLOR 作為 varying 傳遞,然後在 fragment() 內讀取:

varying vec4 vertex_color;
void vertex() {
  vertex_color = COLOR;
}
void fragment() {
  COLOR = vertex_color;
}

NORMAL

同樣地,若在 CanvasTexture 使用法線貼圖,Godot 會預設將其值指派給內建的 NORMAL 變數。如果你使用的是 3D 專用的法線貼圖,顯示時會顛倒。要在你的著色器中使用,必須將其指派給 NORMAL_MAP 屬性,Godot 會自動轉換成 2D 專用並覆寫 NORMAL。

NORMAL_MAP = texture(NORMAL_TEXTURE, UV).rgb;

內建變數

說明

in vec4 FRAGCOORD

像素中心的座標,單位為像素。xy 指定在視埠中的位置,左上角為原點 (0, 0)。乘上 SCREEN_PIXEL_SIZE 可取得 0.0 到 1.0 的值。

in vec2 SCREEN_PIXEL_SIZE

單個像素的尺寸。等於解析度的倒數。

in vec4 REGION_RECT

精靈(Sprite)可見區域,格式為 (x, y, width, height) 。該數值會根據 Sprite2D 的 region_enabled (啟用區域)屬性發生變化。數值是正規化的;舉個例子,如果一張 1000×800 的紋理上有一個 600×400 的區域,並且帶有 100×100 的偏移量,那麼對應的數值就是 vec4(0.1, 0.125, 0.6, 0.5) 。如果 X/Y 的偏移量為負數,或者區域尺寸超過了紋理本身的尺寸,那麼數值可能會超出 0.0 到 1.0 的範圍。

in vec2 POINT_COORD

用於繪製點的座標,取值範圍在 0.0 到 1.0 之間。

sampler2D TEXTURE

預設的2D紋理.

in vec2 TEXTURE_PIXEL_SIZE

預設 2D 紋理的正規化像素尺寸。對於一個紋理尺寸為 64x32 像素的 Sprite2D 來說,TEXTURE_PIXEL_SIZE = vec2(1.0/64.0, 1.0/32.0)。

in bool AT_LIGHT_PASS

總是 false.

sampler2D SPECULAR_SHININESS_TEXTURE

該物件的鏡面光澤紋理。

in vec4 SPECULAR_SHININESS

鏡面光澤顏色,從紋理取樣。

in vec2 UV

來自 vertex() (頂點函式)的 UV 座標。對於啟用了‘區域’(region)功能的 Sprite2D 來說,使用它會取樣整張完整的紋理。如果想只取樣 Sprite2D 屬性中定義的那個區域,請改用 REGION_RECT 。

in vec2 SCREEN_UV

目前像素的螢幕 UV 座標。

sampler2D SCREEN_TEXTURE

已於 Godot 4 移除。請改用帶有 hint_screen_texture 的 sampler2D。

inout vec3 NORMAL

從 ** NORMAL_TEXTURE ** 中正常讀取. 可寫的.

輸入sampler2D NORMAL_TEXTURE

預設 2D 法線紋理。

out vec3 NORMAL_MAP

配置用於三維的法線貼圖, 以便在二維中使用. 如果使用, 則覆蓋 法線 .

out float NORMAL_MAP_DEPTH

用於縮放的法線貼圖深度.

inout vec2 VERTEX

法向量, 在視圖空間中.

inout vec2 SHADOW_VERTEX

與 VERTEX 相同,但可以寫入來改變陰影。

inout vec3 LIGHT_VERTEX

與“VERTEX”相同,但可以寫入來改變照明。 Z 分量代表高度。

inout vec4 COLOR

從頂點函式和輸出片段顏色. 如果未使用, 將設定為 紋理 顏色.

燈光階段內建變數

光處理器函式在 Godot 4.x 中的運作方式與在 Godot 3.x 中的工作方式不同。在 Godot 4.x 中,所有照明都是在常規繪製過程中完成的。換句話說,Godot 不再為每個光重新繪製物體。

光照處理器功能在 2D 中與在 3D 中工作不同。在 CanvasItem 著色器中,這個著色器會為被繪製的物件呼叫一次,然後再為每一束接觸場景中該物體的光呼叫一次。如果您不希望該物件發生任何光傳遞,請使用 render_mode unshaded。如果您只想讓光通過該物件,使用 render_mode light_only;當您只想讓被光覆蓋的物件可見時,這是非常有用的。

如果你定義了 light() 函式,即使該函式是空的,也會取代內建的光照函式。

以下是考慮 CanvasItem 法線貼圖的燈光著色器範例:

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 指定視埠中的位置。視埠的左上角是原點 (0.0, 0.0) 。視埠的右下角是 (1.0, 1.0)。

in vec3 NORMAL

輸入法線。

in vec4 COLOR

輸入顏色. 這是片段函式的輸出(如果在著色器的任何函式中沒有使用 MODULATE , 則應用最終調變).

in vec2 UV

來自頂點函式的UV, 相當於片段函式中的UV.

sampler2D TEXTURE

CanvasItem(畫布項)目前正在使用的紋理。

in vec2 TEXTURE_PIXEL_SIZE

TEXTURE 的正規化像素尺寸。例如,對於一個 紋理 尺寸為 64×32 像素的 Sprite2D,TEXTURE_PIXEL_SIZE = vec2(1.0 / 64.0, 1.0 / 32.0)。

in vec2 SCREEN_UV

目前像素的螢幕 UV 座標。

in vec2 POINT_COORD

點精靈的UV.

in vec4 LIGHT_COLOR

Light2D 的 Color 。若該光為 PointLight2D ,則將其乘以該光的 texture 。

in float LIGHT_ENERGY

Light2D 的 Energy multiplier。

in vec3 LIGHT_POSITION

燈光在螢幕空間中 Light2D 的位置。如果使用的是 DirectionalLight2D ,則始終為 (0.0, 0.0, 0.0)。

in vec3 LIGHT_DIRECTION

Light2D 在螢幕空間中的方向。

in bool LIGHT_IS_DIRECTIONAL

如果 true 代表是 DirectionalLight2D .

in vec3 LIGHT_VERTEX

world_position 可用於頂點函式或片段函式.

inout vec4 LIGHT

此 Light2D 的輸出顏色.

in vec4 SPECULAR_SHININESS

鏡面光澤度,在物件紋理中設定。

out vec4 SHADOW_MODULATE

將此時投射的陰影乘以該顏色。

函式

另外還實作了一些額外的函式,用於對自動生成的‘有向距離場(Signed Distance Field)’紋理進行取樣。這些函式可以在 CanvasItem 著色器的 fragment() 和 light() 函式中使用。只要是從這些受支援的函式中被呼叫的,自訂函式同樣可以使用它們。

帶符號的距離場是從場景中存在的 LightOccluder2D 節點產生的,並且啟用了 SDF Collision 屬性(這是預設)。有關更多信息,請參閱 2D 燈光和陰影 說明文件。

函式

說明

float texture_sdf (vec2 sdf_pos)

執行2D紋理讀取。

vec2 texture_sdf_normal (vec2 sdf_pos)

預設 2D 法線紋理。

vec2 sdf_to_screen_uv (vec2 sdf_pos)

將 SDF 轉換為螢幕 UV。

vec2 screen_uv_to_sdf (vec2 uv)

轉換螢幕UV為SDF。