WebGL2 使用前的 GLSL ES 3.00 函數宣告：真正的規則和常見陷阱

為什麼你的 WebGL2 著色器突然無法編譯

您剛剛將 WebGL1 程式碼移植到 WebGL2，突然您的片段著色器拒絕編譯。錯誤訊息指向未定義的函數，但您知道該函數存在。如果您來自 GLSL ES 1.00，則可能會遇到 3.00 版本中新增的「使用前函數宣告」要求。這不是驅動程式或 WebGL 實作中的錯誤，而是語言規範中的故意更改。

在 GLSL ES 1.00 中，可以在著色器來源中的任何位置定義函數，並且編譯器將解析它們，無論順序為何。 GLSL ES 3.00 是 WebGL2 的著色語言，要求每個函數必須在首次呼叫之前宣告或定義。此規則適用於所有使用者定義的函數，並且在遷移過程中讓許多開發人員措手不及。

確切的規則：宣告或定義必須在呼叫之前

GLSL ES 3.00 規格很明確：「函數宣告（原型）必須在定義或呼叫函數之前出現在著色器中。」這表示您有兩個選擇：

選項 A：在任何呼叫之前定義函數

筆記型電腦螢幕的特寫，顯示將 GLSL ES 1.00 遷移到 3.00 的清單，其中已勾選函數聲明步驟。

// Valid: definition comes before use
vec4 computeColor(vec3 normal, vec3 lightDir) {
    float diff = max(dot(normal, lightDir), 0.0);
    return vec4(diff, diff, diff, 1.0);
}

void main() {
    vec3 n = normalize(vNormal);
    gl_FragColor = computeColor(n, uLightDir);
}

Option B: Provide a function prototype before any call, then define later

// 有效：原型在使用前，定義在任何地方
vec4computeColor（vec3正常，vec3lightDir）；

無效主（）{
    vec3 n = 歸一化(vNormal);
    gl_FragColor = 計算顏色(n, uLightDir);
}

vec4computeColor（vec3正常，vec3lightDir）{
    浮動差異=最大（點（法線，lightDir），0.0）;
    返回 vec4(diff, diff, diff, 1.0);
}

The prototype must match the definition exactly—same return type, same parameter types (and names in the prototype are optional but recommended for clarity).

A Concrete Scenario: Porting a Lighting Shader

Let's walk through a realistic case. You have a WebGL1 shader that computes Blinn-Phong lighting with several helper functions:

開發人員在 VS Code 中編輯 GLSL 著色器文件，終端顯示由於聲明順序而導致未定義函數的編譯錯誤。

// GLSL ES 1.00 (WebGL1) - works fine
// No declaration needed
vec3 computeHalfway(vec3 lightDir, vec3 viewDir) {
    return normalize(lightDir + viewDir);
}

float computeSpecular(vec3 normal, vec3 halfway) {
    return pow(max(dot(normal, halfway), 0.0), 64.0);
}

void main() {
    vec3 halfway = computeHalfway(uLightDir, uViewDir);
    float spec = computeSpecular(vNormal, halfway);
    // ...
}

You change the #版本 to 300 es and update other syntax (like texture() instead of [textPROT_0004]]texture() instead of [texture21] T_0007]]main() but defined after main(). In 1.00 this was fine; in 3.00 it's an error.

Fix: Either move all function definitions before main(), or add prototypes at the top. The prototype approach is cleaner for larger shaders:

#version 300 es
precision highp float;

// Prototypes first
vec3 computeHalfway(vec3 lightDir, vec3 viewDir);
float computeSpecular(vec3 normal, vec3 halfway);

void main() {
    // ... now safe
}

// Definitions later
vec3 computeHalfway(...) { ... }
float computeSpecular(...) { ... }

大多數開發人員陷入困境的地方

當您具有相互遞歸或複雜的依賴關係鏈時，最常見的故障就會發生。例如：

// This will cause a compile error regardless of order
float foo(float x) { return bar(x) + 1.0; }
float bar(float x) { return foo(x - 1.0); }

GLSL ES 3.00 不支援相互遞歸函數的前向聲明，因為無法同時滿足兩個函數的「使用前聲明」要求。該語言一般不支援遞歸（儘管某些實作可能允許有限的遞歸，但規範在 3.00 中禁止它）。所以如果需要互相遞歸，就必須重構你的演算法。

另一個常見錯誤：當原型是在原始程式碼中第一次呼叫之後定義的時，在其原型之前使用函數。此規則適用於來源文字中的順序，而不適用於任何邏輯順序。如果您無意中將原型放置在條件區塊內或在第一次呼叫之後，編譯器將拒絕它。

比較：GLSL ES 1.00 與 3.00 宣告規則

方面	GLSL ES 1.00	GLSL ES 3.00
函數呼叫順序	來源中的任意順序	宣告/定義必須先於呼叫
需要原型嗎？	沒有	是的，如果使用後定義
遞歸支援	禁止	禁止（同）
典型錯誤	暫無訂單	“未定義的函數”或“沒有匹配的重載”

僅此差異就是許多著色器在升級到 WebGL2 時出現故障的原因。一旦您了解了規則，修復就很簡單，但如果您使用舊的教程或程式碼片段，則修復並不明顯。

實用路徑：著色器遷移清單

如果您要將程式碼庫從 WebGL1 移轉到 WebGL2，請參閱以下逐步清單，以避免宣告順序問題：

更改版本指令：將每個著色器頂部的 #version 100 替換為 #version 300 es。
辨識輔助函數：列出所有不屬於 main() 的使用者定義函數。
重新排序或新增原型：決定是否將定義移動到 main() 之前（對於小型著色器來說很容易）或在頂部添加原型（對於較大的檔案更好）。
使用一致的命名：原型參數名稱不需要與定義匹配，但為了避免混淆，請保持相同。
編譯和測試：使用 gl.getShaderInfoLog() 捕獲任何剩餘的訂單問題。
檢查遞歸：如果您有任何函數呼叫另一個函數，而另一個函數又呼叫第一個函數，請重構以刪除循環。

失敗場景：忽略規則時會發生什麼

您可能會想要按原樣保留現有程式碼並希望驅動程式能夠處理它。通常會發生以下情況：

WebGL2 上下文建立成功，因為版本指令已被識別。
頂點著色器編譯良好（也許您沒有函數或它們已經按順序排列）。
片段著色器編譯失敗並出現神秘錯誤。瀏覽器的 WebGL 錯誤訊息並不總是有幫助 — 即使您稍後定義了一個名為 foo 的函數，您也可能會看到「ERROR: 0:10: 'foo' : nomatching重載函數找到」。
著色器程式連結失敗，您的 3D 場景不會渲染任何內容。

這種無聲故障在生產中尤其危險，因為錯誤僅在 JavaScript 控制台中可見，如果不檢查編譯狀態，場景將顯示為黑色或遺失。

這對您的工作流程意味著什麼

理解這條規則不僅對於修復錯誤至關重要，而且對於編寫乾淨、可維護的著色器程式碼也至關重要。使用前聲明設計使 GLSL 與 C 和 C++ 等語言保持一致，其中原型是標準做法。它迫使您明確函數簽名，這使您的程式碼更易於閱讀和重構。

對於從 WebGL1 過渡到 WebGL2 的開發人員來說，聲明順序差異是最常見的障礙之一。然而，一旦你將其內在化，移植著色器就變成了例行公事。