WebGLRenderingContext.getProgramParameter() — Methode · JavaScript-Referenz

Signatur

WebGLRenderingContext.prototype.getProgramParameter(program, pname)

Beschreibung

Mit getProgramParameter() fragst du den Zustand eines Shader-Programms ab, das mit createProgram() erzeugt wurde. Am häufigsten wird die Methode direkt nach linkProgram() mit gl.LINK_STATUS aufgerufen, um zu prüfen, ob Vertex- und Fragment-Shader erfolgreich zu einem ausführbaren Programm verbunden wurden.

Welcher Wert zurückkommt, hängt vom Parameter pname ab:

gl.DELETE_STATUS – boolean: Ist das Programm zum Löschen markiert?
gl.LINK_STATUS – boolean: War der letzte Link-Vorgang erfolgreich?
gl.VALIDATE_STATUS – boolean: Ergebnis des letzten validateProgram()-Aufrufs.
gl.ATTACHED_SHADERS – number: Anzahl angehängter Shader.
gl.ACTIVE_ATTRIBUTES – number: Anzahl aktiver Attribut-Variablen.
gl.ACTIVE_UNIFORMS – number: Anzahl aktiver Uniform-Variablen.

In WebGL 2 (WebGL2RenderingContext) kommen weitere Konstanten hinzu: gl.TRANSFORM_FEEDBACK_BUFFER_MODE, gl.TRANSFORM_FEEDBACK_VARYINGS und gl.ACTIVE_UNIFORM_BLOCKS.

Die Zähler ACTIVE_ATTRIBUTES und ACTIVE_UNIFORMS sind nützlich, um zusammen mit getActiveAttrib() bzw. getActiveUniform() alle Shader-Variablen automatisch zu ermitteln – etwa für generische Material- oder Shader-Systeme.

Parameter

Name	Typ	Default	Beschreibung
$program Pflicht	WebGLProgram		Das Programm-Objekt, dessen Informationen abgefragt werden sollen.
$pname Pflicht	GLenum (number)		Konstante für die gewünschte Information, z. B. `gl.LINK_STATUS`, `gl.DELETE_STATUS`, `gl.VALIDATE_STATUS`, `gl.ATTACHED_SHADERS`, `gl.ACTIVE_ATTRIBUTES` oder `gl.ACTIVE_UNIFORMS`.

Rückgabewert

Typ

boolean | number | null

Beschreibung

Je nach pname ein boolean (Status-Abfragen) oder ein number (Zähler bzw. Modus-Konstante). Bei ungültigem pname oder verlorenem Kontext wird null zurückgegeben.

Beispiele

Link-Status nach linkProgram() prüfen

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

const compile = (type, source) => {
  const shader = gl.createShader(type);
  gl.shaderSource(shader, source);
  gl.compileShader(shader);
  if (!gl.getShaderParameter(shader, gl.COMPILE_STATUS)) {
    throw new Error(gl.getShaderInfoLog(shader));
  }
  return shader;
};

const vs = compile(gl.VERTEX_SHADER, `
  attribute vec2 aPosition;
  void main() { gl_Position = vec4(aPosition, 0.0, 1.0); }
`);
const fs = compile(gl.FRAGMENT_SHADER, `
  precision mediump float;
  uniform vec4 uColor;
  void main() { gl_FragColor = uColor; }
`);

const program = gl.createProgram();
gl.attachShader(program, vs);
gl.attachShader(program, fs);
gl.linkProgram(program);

if (!gl.getProgramParameter(program, gl.LINK_STATUS)) {
  console.error('Linken fehlgeschlagen:', gl.getProgramInfoLog(program));
  gl.deleteProgram(program);
} else {
  console.log('Programm erfolgreich gelinkt');
}

Programm erfolgreich gelinkt

Aktive Attribute und Uniforms auflisten

// setzt 'gl' und ein gelinktes 'program' aus dem ersten Beispiel voraus
const attribCount = gl.getProgramParameter(program, gl.ACTIVE_ATTRIBUTES);
const uniformCount = gl.getProgramParameter(program, gl.ACTIVE_UNIFORMS);

const attributes = Array.from({ length: attribCount }, (_, i) => {
  const info = gl.getActiveAttrib(program, i);
  return { name: info.name, location: gl.getAttribLocation(program, info.name) };
});

const uniforms = Array.from({ length: uniformCount }, (_, i) => {
  const info = gl.getActiveUniform(program, i);
  return { name: info.name, location: gl.getUniformLocation(program, info.name) };
});

console.log(attributes.map((a) => a.name));
console.log(uniforms.map((u) => u.name));

["aPosition"] ["uColor"]

Validierung und angehängte Shader abfragen

// setzt 'gl' und 'program' voraus
gl.validateProgram(program);

const info = {
  valid: gl.getProgramParameter(program, gl.VALIDATE_STATUS),
  attachedShaders: gl.getProgramParameter(program, gl.ATTACHED_SHADERS),
  markedForDeletion: gl.getProgramParameter(program, gl.DELETE_STATUS)
};

console.log(info);

{ valid: true, attachedShaders: 2, markedForDeletion: false }

// Wichtig · Fallstricke

Nicht nach jedem Frame aufrufen: getProgramParameter() kann eine Synchronisation mit der GPU erzwingen und die Render-Pipeline ausbremsen. Frag den Status einmal nach dem Linken ab und speichere Attribut-/Uniform-Positionen zwischen.
Parallele Shader-Kompilierung: Mit der Erweiterung KHR_parallel_shader_compile kannst du vorher ext.COMPLETION_STATUS_KHR abfragen, ohne den Haupt-Thread zu blockieren. Erst wenn das true liefert, LINK_STATUS prüfen.
Schlägt das Linken fehl, liefert getProgramInfoLog() die eigentliche Fehlermeldung – LINK_STATUS sagt dir nur, dass etwas schiefging.
Der Compiler entfernt ungenutzte Variablen. Deshalb zählen ACTIVE_ATTRIBUTES/ACTIVE_UNIFORMS nur Variablen, die tatsächlich verwendet werden.
Uniform-Arrays erscheinen als ein Eintrag mit dem Suffix [0] im Namen (z. B. uLights[0]).
Ein ungültiger pname erzeugt den Fehler gl.INVALID_ENUM (abrufbar mit getError()), und die Methode gibt null zurück. Das passiert zum Beispiel, wenn du WebGL-2-Konstanten in einem WebGL-1-Kontext verwendest.
Nach einem Kontextverlust (webglcontextlost) liefert die Methode null.
Kompatibilität: In allen modernen Browsern verfügbar, auch in Web Workern über OffscreenCanvas.

Siehe auch

WebGLRenderingContext.linkProgram() WebGLRenderingContext.getProgramInfoLog() WebGLRenderingContext.getShaderParameter() WebGLRenderingContext.validateProgram() WebGLRenderingContext.getActiveUniform() WebGLRenderingContext.getActiveAttrib() WebGLProgram