WebGLRenderingContext: getUniformLocation() Methode

Baseline Widely available

This feature is well established and works across many devices and browser versions. It’s been available across browsers since July 2015.

Hinweis: Diese Funktion ist in Web Workers verfügbar.

Teil der WebGL API, gibt die Methode WebGLRenderingContext getUniformLocation() den Standort einer spezifischen uniform-Variable zurück, die Teil eines bestimmten WebGLProgram ist.

Die uniform-Variable wird als ein WebGLUniformLocation-Objekt zurückgegeben, das ein undurchsichtiges Identifikationsmittel ist, das verwendet wird, um zu spezifizieren, wo sich diese uniform-Variable im Speicher der GPU befindet.

Sobald Sie den Standort der uniform-Variable haben, können Sie auf die uniform-Variable selbst mit einer der anderen uniform-Zugriffsmethoden zugreifen, indem Sie den Standort der uniform-Variable als einen der Eingänge übergeben:

getUniform()

Gibt den Wert der uniform-Variable an dem angegebenen Standort zurück.

WebGLRenderingContext.uniform[1234][fi][v]()

Setzt den Wert der uniform-Variable auf den angegebenen Wert, der eine einzelne Gleitkommazahl oder Ganzzahl sein kann, oder einen 2-4 Komponenten-Vektor, der entweder als eine Liste von Werten oder als ein Float32Array oder Int32Array angegeben ist.

WebGLRenderingContext.uniformMatrix[234][fv]()

Setzt den Wert der uniform-Variable auf die angegebene Matrix, möglicherweise mit Transposition. Der Wert wird als eine Sequenz von GLfloat-Werten oder als Float32Array repräsentiert.

Die uniform-Variable selbst wird in dem Shader-Programm unter Verwendung von GLSL deklariert.

Syntax

js
getUniformLocation(program, name)

Parameter

program

Das WebGLProgram, in dem die angegebene uniform-Variable zu lokalisieren ist.

name

Ein String, der den Namen der uniform-Variable angibt, deren Standort zurückgegeben werden soll. Der Name darf keine Leerzeichen enthalten, und Sie können diese Funktion nicht verwenden, um den Standort von uniform-Variablen zu erhalten, die mit dem reservierten String "gl_" beginnen, da diese intern in der WebGL-Schicht sind.

Die möglichen Werte entsprechen den uniform-Namen, die von getActiveUniform zurückgegeben werden. Sehen Sie sich diese Funktion für spezifische Informationen darüber an, wie deklarierte uniforms zu uniform-Standortnamen abgebildet werden.

Zusätzlich sind für als Arrays deklarierte uniforms auch folgende Namen gültig:

  • Der uniform-Name ohne den [0]-Suffix. Z.B. der Standort, der für arrayUniform zurückgegeben wird, entspricht dem für arrayUniform[0].
  • Der uniform-Name mit einem Integer-Indizierung. Z.B. der Standort, der für arrayUniform[2] zurückgegeben wird, würde direkt auf den dritten Eintrag der arrayUniform-uniform-Variable zeigen.

Rückgabewert

Ein WebGLUniformLocation-Wert, der den Standort der benannten Variable angibt, wenn sie existiert. Wenn die angegebene Variable nicht existiert, wird null zurückgegeben.

Die WebGLUniformLocation ist ein undurchsichtiger Wert, der zur eindeutigen Identifizierung des Standorts im GPU-Speicher verwendet wird, an dem sich die uniform-Variable befindet. Mit diesem Wert in der Hand können Sie andere WebGL-Methoden aufrufen, um auf den Wert der uniform-Variable zuzugreifen.

Hinweis: Der WebGLUniformLocation-Typ ist mit dem GLint-Typ kompatibel, wenn Sie den Index oder Standort eines uniform-Attributs spezifizieren.

Fehler

Die folgenden Fehler können auftreten; um nach getUniformLocation() nach Fehlern zu überprüfen, rufen Sie getError() auf.

GL_INVALID_VALUE

Der program-Parameter ist kein Wert oder Objekt, das von WebGL generiert wurde.

GL_INVALID_OPERATION

Der program-Parameter entspricht keinem von WebGL generierten GLSL-Programm oder das angegebene Programm wurde nicht erfolgreich verknüpft.

Beispiele

In diesem Beispiel, entnommen aus der animateScene()-Methode im Artikel Ein einfaches 2D-WebGL-Animationsbeispiel, werden die Standorte von drei uniforms aus dem Shader-Programm ermittelt und dann der Wert jedes der drei uniforms festgelegt.

js
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]);

Hinweis: Dieses Code-Snippet stammt aus der Funktion animateScene() in "Ein einfaches 2D-WebGL-Animationsbeispiel." Siehe diesen Artikel für das vollständige Beispiel und um die resultierende Animation in Aktion zu sehen.

Nach dem Setzen des aktuellen Shader-Programms auf shaderProgram, holt dieser Code die drei uniforms "uScalingFactor", "uGlobalColor" und "uRotationVector", indem er getUniformLocation() einmal für jede uniform aufruft.

Dann werden die Werte der drei uniforms gesetzt:

  • Die uScalingFactor-uniform — ein 2-Komponenten-Vektor — erhält die horizontalen und vertikalen Skalierungsfaktoren aus der Variable currentScale.
  • Die uniform uRotationVector wird auf den Inhalt der Variablen currentRotation gesetzt. Auch dies ist ein 2-Komponenten-Vektor.
  • Schließlich wird die uniform uGlobalColor auf die Farbe [0.1, 0.7, 0.2, 1.0] gesetzt, wobei die Komponenten in diesem 4-Komponenten-Vektor die Werte von Rot, Grün, Blau und Alpha repräsentieren.

Nachdem dies getan wurde, werden bei den nächsten Aufrufen der Shader-Funktionen ihre eigenen Variablen namens uScalingFactor, uGlobalColor und uRotationVector alle die Werte haben, die vom JavaScript-Code bereitgestellt wurden.

Spezifikationen

Specification
WebGL Specification
# 5.14.10

Browser-Kompatibilität

Siehe auch