WebGLRenderingContext: getActiveUniform()-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.

Die WebGLRenderingContext.getActiveUniform()-Methode der WebGL API gibt ein WebGLActiveInfo-Objekt zurück, das die Größe, den Typ und den Namen eines Uniform-Attributs enthält. Sie wird üblicherweise verwendet, wenn unbekannte Uniforms entweder zur Fehlersuche oder zur Erstellung generischer Bibliotheken abgefragt werden.

Syntax

js
getActiveUniform(program, index)

Parameter

program

Ein WebGLProgram, das das WebGL-Shader-Programm angibt, aus dem die Informationen der Uniform-Variable abgerufen werden sollen.

index

Ein GLuint, der den Index des abzurufenden Uniform-Attributs angibt. Dieser Wert ist ein Index von 0 bis N - 1, wie er durch gl.getProgramParameter(program, gl.ACTIVE_UNIFORMS) zurückgegeben wird.

Rückgabewert

Ein WebGLActiveInfo-Objekt, das das Uniform beschreibt.

Das type-Attribut des Rückgabewerts wird einer der folgenden sein:

  • gl.FLOAT

  • gl.FLOAT_VEC2

  • gl.FLOAT_VEC3

  • gl.FLOAT_VEC4

  • gl.INT

  • gl.INT_VEC2

  • gl.INT_VEC3

  • gl.INT_VEC4

  • gl.BOOL

  • gl.BOOL_VEC2

  • gl.BOOL_VEC3

  • gl.BOOL_VEC4

  • gl.FLOAT_MAT2

  • gl.FLOAT_MAT3

  • gl.FLOAT_MAT4

  • gl.SAMPLER_2D

  • gl.SAMPLER_CUBE

  • Bei Verwendung eines WebGL 2-Kontexts sind zusätzlich folgende Werte möglich:

    • gl.UNSIGNED_INT
    • gl.UNSIGNED_INT_VEC2
    • gl.UNSIGNED_INT_VEC3
    • gl.UNSIGNED_INT_VEC4
    • gl.FLOAT_MAT2x3
    • gl.FLOAT_MAT2x4
    • gl.FLOAT_MAT3x2
    • gl.FLOAT_MAT3x4
    • gl.FLOAT_MAT4x2
    • gl.FLOAT_MAT4x3
    • gl.SAMPLER_3D
    • gl.SAMPLER_2D_SHADOW
    • gl.SAMPLER_2D_ARRAY
    • gl.SAMPLER_2D_ARRAY_SHADOW
    • gl.SAMPLER_CUBE_SHADOW
    • gl.INT_SAMPLER_2D
    • gl.INT_SAMPLER_3D
    • gl.INT_SAMPLER_CUBE
    • gl.INT_SAMPLER_2D_ARRAY
    • gl.UNSIGNED_INT_SAMPLER_2D
    • gl.UNSIGNED_INT_SAMPLER_3D
    • gl.UNSIGNED_INT_SAMPLER_CUBE
    • gl.UNSIGNED_INT_SAMPLER_2D_ARRAY

Wenn gl.linkProgram aufgerufen wird, erstellt WebGL eine Liste aktiver Uniforms. Dies sind mögliche Werte des name-Attributs von Rückgabewerten von getActiveUniform. WebGL generiert ein oder mehrere Einträge in der Liste, abhängig vom deklarierten Typ der Uniform im Shader:

  • Einzelner Basistyp: Ein Eintrag mit dem Namen der Uniform. Z.B. uniform vec4 a; wird zu a.

  • Array von Basistypen: Ein Eintrag mit dem Namen der Uniform, gefolgt von [0]. Z.B. uniform vec4 b[]; wird zu b[0].

  • Strukturtyp: Ein Eintrag für jedes Mitglied der Struktur. Z.B. uniform struct { float foo; vec4 bar; } c; wird zu c.foo und c.bar.

  • Arrays von Strukturen oder Arrays: Jeder Eintrag des Arrays erzeugt seine eigenen Einträge. Z.B. uniform struct { float foo; vec4 bar; } d[2]; wird zu:

    • d[0].foo
    • d[0].bar
    • d[1].foo
    • d[1].bar
  • Uniform-Blöcke: Ein Eintrag für jedes Mitglied. Wenn der Uniform-Block einen Instanznamen hat, wird dieser vorangestellt. Z.B. uniform Block { float foo; }; wird zu foo, und uniform Block { float bar; } e; wird zu e.bar.

Das size-Attribut des Rückgabewerts entspricht der Länge des Arrays für Uniforms, die als Arrays deklariert sind. Andernfalls ist es 1 (dies schließt Schnittstellenblöcke ein, die mit Arrays instanziiert werden).

Ausnahmen

  • gl.INVALID_VALUE wird erzeugt, wenn das Programm WebGLProgram ungültig ist (nicht verknüpft, gelöscht usw.).
  • gl.INVALID_VALUE wird erzeugt, wenn der Index nicht im Bereich [0, gl.getProgramParameter(program, gl.ACTIVE_UNIFORMS) - 1] liegt.

Beispiele

js
const numUniforms = gl.getProgramParameter(program, gl.ACTIVE_UNIFORMS);
for (let i = 0; i < numUniforms; ++i) {
  const info = gl.getActiveUniform(program, i);
  console.log("name:", info.name, "type:", info.type, "size:", info.size);
}

Spezifikationen

Specification
WebGL Specification
# 5.14.10

Browser-Kompatibilität

Report problems with this compatibility data on GitHub
desktopmobile
Chrome
Edge
Firefox
Opera
Safari
Chrome Android
Firefox for Android
Opera Android
Safari on iOS
Samsung Internet
WebView Android
WebView on iOS
getActiveUniform

Legend

Tip: you can click/tap on a cell for more information.

Full support
Full support

Siehe auch