WebGLRenderingContext: getUniformLocation() 方法

語法

getUniformLocation(program, name)

引數

program

要從中查詢指定 uniform 變數的 WebGLProgram。

name

一個字串，指定要返回其位置的 uniform 變數的名稱。名稱中不能包含任何空格，並且不能使用此函式來獲取任何以保留字串 "gl_" 開頭的 uniform 的位置，因為那些是 WebGL 層內部使用的。

可能的值對應於 getActiveUniform 返回的 uniform 名稱；有關宣告的 uniform 如何對映到 uniform 位置名稱的詳細資訊，請參閱該函式。

此外，對於宣告為陣列的 uniform，以下名稱也有效：

• 不帶 [0] 字尾的 uniform 名稱。例如，為 arrayUniform 返回的位置等同於為 arrayUniform[0] 返回的位置。
• 帶整數索引的 uniform 名稱。例如，為 arrayUniform[2] 返回的位置將直接指向 arrayUniform uniform 的第三個條目。

返回值

一個 WebGLUniformLocation 值，指示命名變數的位置（如果存在）。如果指定的變數不存在，則返回 null。

WebGLUniformLocation 是一個不透明的值，用於唯一標識 uniform 變數在 GPU 記憶體中的位置。有了這個值，您就可以呼叫其他 WebGL 方法來訪問 uniform 變數的值。

錯誤

可能發生以下錯誤；要檢查 getUniformLocation() 返回後的錯誤，請呼叫 getError()。

GL_INVALID_VALUE

program 引數不是 WebGL 生成的值或物件。

GL_INVALID_OPERATION

program 引數不對應 WebGL 生成的 GLSL 程式，或者指定的程式尚未成功連結。

示例

在此示例中，取自文章 A basic 2D WebGL animation example 的 animateScene() 方法，它從著色程式獲取三個 uniform 的位置，然後設定每個 uniform 的值。

gl.useProgram(shaderProgram);

uScalingFactor = gl.getUniformLocation(shaderProgram, "uScalingFactor");
uGlobalColor = gl.getUniformLocation(shaderProgram, "uGlobalColor");
uRotationVector = gl.getUniformLocation(shaderProgram, "uRotationVector");

gl.uniform2fv(uScalingFactor, currentScale);
gl.uniform2fv(uRotationVector, currentRotation);
gl.uniform4fv(uGlobalColor, [0.1, 0.7, 0.2, 1.0]);

將當前著色程式設定為 shaderProgram 後，此程式碼會獲取三個 uniform "uScalingFactor"、"uGlobalColor" 和 "uRotationVector"，每次呼叫 getUniformLocation() 獲取一個 uniform。

然後設定這三個 uniform 的值

• uScalingFactor uniform — 一個 2 分量的頂點 — 從變數 currentScale 接收水平和垂直縮放因子。
• uniform uRotationVector 被設定為變數 currentRotation 的內容。這同樣是一個 2 分量的頂點。
• 最後，uniform uGlobalColor 被設定為顏色 [0.1, 0.7, 0.2, 1.0]，此 4 分量向量中的分量分別代表紅色、綠色、藍色和 alpha 的值。

完成此操作後，下一次呼叫著色函式時，它們各自名為 uScalingFactor、uGlobalColor 和 uRotationVector 的變數都將具有 JavaScript 程式碼提供的值。

規範

瀏覽器相容性

另見

• WebGLRenderingContext.getAttribLocation()
• WebGLRenderingContext.getActiveUniform()
• WebGLUniformLocation