WebGLActiveInfo.name — Eigenschaft · JavaScript-Referenz

Signatur

WebGLActiveInfo.name

Beschreibung

Die schreibgeschützte Eigenschaft name eines WebGLActiveInfo-Objekts enthält den Namen der Variable, die im gelinkten Shader-Programm tatsächlich aktiv ist. Ein solches Objekt erhältst du von gl.getActiveAttrib(), gl.getActiveUniform() oder, in WebGL 2, von gl.getTransformFeedbackVarying().

Am häufigsten brauchst du die Eigenschaft zur Introspektion: Du gehst alle aktiven Attribute bzw. Uniforms eines Programms durch (Anzahl über gl.getProgramParameter(program, gl.ACTIVE_ATTRIBUTES) bzw. gl.ACTIVE_UNIFORMS) und speicherst die Positionen automatisch in einer Tabelle. Dazu übergibst du name an gl.getAttribLocation() oder gl.getUniformLocation(). Hartcodierte Variablennamen im JavaScript-Code sind dann nicht mehr nötig.

Wichtig: Der Name wird so geliefert, wie der GLSL-Compiler ihn intern führt. Bei Uniform-Arrays hängt er [0] an (z. B. u_lights[0]). Bei Struct-Uniforms bekommt jedes Feld einen eigenen Eintrag mit Punktnotation (z. B. u_material.color). Variablen, die der Compiler wegoptimiert hat, erscheinen gar nicht.

Rückgabewert

Typ

string

Beschreibung

Der Name der aktiven Shader-Variable, z. B. a_position, u_matrix oder u_lights[0].

Beispiele

Alle aktiven Attribute eines Programms auflisten

const canvas = document.createElement('canvas');
const gl = canvas.getContext('webgl');

const vsSource = `
  attribute vec3 a_position;
  attribute vec2 a_texCoord;
  varying vec2 v_texCoord;
  void main() {
    v_texCoord = a_texCoord;
    gl_Position = vec4(a_position, 1.0);
  }`;
const fsSource = `
  precision mediump float;
  varying vec2 v_texCoord;
  void main() { gl_FragColor = vec4(v_texCoord, 0.0, 1.0); }`;

const compile = (type, src) => {
  const s = gl.createShader(type);
  gl.shaderSource(s, src);
  gl.compileShader(s);
  return s;
};

const program = gl.createProgram();
gl.attachShader(program, compile(gl.VERTEX_SHADER, vsSource));
gl.attachShader(program, compile(gl.FRAGMENT_SHADER, fsSource));
gl.linkProgram(program);

const count = gl.getProgramParameter(program, gl.ACTIVE_ATTRIBUTES);
for (let i = 0; i < count; i++) {
  const info = gl.getActiveAttrib(program, i);
  console.log(info.name, gl.getAttribLocation(program, info.name));
}

a_position 0 a_texCoord 1 (Reihenfolge und Positionen können je nach Treiber abweichen)

Uniform-Positionen automatisch in eine Tabelle schreiben

// Annahme: gl und ein gelinktes program sind vorhanden
const getUniformLocations = (gl, program) => {
  const locations = {};
  const count = gl.getProgramParameter(program, gl.ACTIVE_UNIFORMS);
  for (let i = 0; i < count; i++) {
    const { name, size, type } = gl.getActiveUniform(program, i);
    // "u_lights[0]" -> "u_lights" als Schlüssel verwenden
    const key = name.endsWith('[0]') ? name.slice(0, -3) : name;
    locations[key] = { location: gl.getUniformLocation(program, name), size, type };
  }
  return locations;
};

const uniforms = getUniformLocations(gl, program);
console.log(Object.keys(uniforms));
gl.useProgram(program);
gl.uniformMatrix4fv(uniforms.u_matrix.location, false, new Float32Array(16));

["u_matrix", "u_lights", "u_material.color"]

Transform-Feedback-Varyings in WebGL 2 prüfen

// WebGL-2-Kontext mit einem Programm, vor dem Linken konfiguriert per:
// gl.transformFeedbackVaryings(program, ['v_newPosition'], gl.SEPARATE_ATTRIBS);
const n = gl.getProgramParameter(program, gl.TRANSFORM_FEEDBACK_VARYINGS);
for (let i = 0; i < n; i++) {
  const info = gl.getTransformFeedbackVarying(program, i);
  console.log(`Varying ${i}: ${info.name} (size ${info.size})`);
}

Varying 0: v_newPosition (size 1)

// Wichtig · Fallstricke

Wegoptimierte Variablen: Deklarierte, aber nicht genutzte Attribute oder Uniforms entfernt der Compiler. Sie tauchen nicht auf, und für sie liefert getUniformLocation() null bzw. getAttribLocation() -1.
Array-Suffix: Uniform-Arrays werden als name[0] gemeldet. Für einen bestimmten Index baust du den Namen selbst zusammen, z. B. u_lights[2].
Reservierte Präfixe: Namen, die mit webgl_ oder _webgl_ beginnen, sind in WebGL reserviert. Eingebaute Variablen mit dem Präfix gl_ können in WebGL 2 unter Umständen ebenfalls erscheinen.
Reihenfolge: Die Indexreihenfolge ist nicht festgelegt und kann sich je nach Browser, GPU und Treiber unterscheiden. Verlass dich also nicht darauf, sondern ordne die Einträge immer über name zu.
Kompatibilität: Die Eigenschaft wird in allen Browsern mit WebGL 1 und WebGL 2 unterstützt und ist auch in Web Workers mit OffscreenCanvas verfügbar. Nach einem Kontextverlust (webglcontextlost) geben die Abfragemethoden null zurück. Prüfe den Wert deshalb, bevor du auf .name zugreifst.

Siehe auch

WebGLActiveInfo.size WebGLActiveInfo.type MediaDeviceInfo.label CSSFunctionRule.name IDBDatabase.name