WebGLRenderingContext.getProgramInfoLog() — Methode · JavaScript-Referenz

Signatur

WebGLRenderingContext.prototype.getProgramInfoLog(program)

Beschreibung

Die Methode getProgramInfoLog() liefert den Protokolltext, den der Treiber beim Linken (gl.linkProgram()) oder Validieren (gl.validateProgram()) eines Shader-Programms erzeugt hat. Dort stehen typischerweise Fehlermeldungen wie nicht zueinander passende varying-Variablen zwischen Vertex- und Fragment-Shader, fehlende main()-Funktionen oder überschrittene Ressourcengrenzen (z. B. zu viele Attribute oder Uniforms).

Man verwendet sie fast immer zusammen mit gl.getProgramParameter(program, gl.LINK_STATUS): Ist der Link-Status false, gibt getProgramInfoLog() die Ursache aus. Für Fehler innerhalb eines einzelnen Shaders (Syntaxfehler beim Kompilieren) ist dagegen gl.getShaderInfoLog() zuständig.

Der Inhalt des Protokolls ist nicht standardisiert – Format und Wortlaut hängen vom Browser, vom Betriebssystem und vom Grafiktreiber ab (unter Windows oft über ANGLE/Direct3D übersetzt). Das Protokoll eignet sich daher für Debug-Ausgaben und Logging, nicht aber für maschinelles Parsen.

Die Methode ist identisch auch in WebGL2RenderingContext verfügbar.

Parameter

Name	Typ	Default	Beschreibung
$program Pflicht	WebGLProgram		Das Programmobjekt, dessen Protokoll abgefragt werden soll – erzeugt mit `gl.createProgram()`.

Rückgabewert

Typ

string | null

Beschreibung

Ein String mit den Diagnosemeldungen des letzten Link- bzw. Validierungsvorgangs. Bei Erfolg meist ein leerer String "" (manche Treiber liefern auch Warnungen). null, wenn der Kontext verloren ist (isContextLost()).

Beispiele

Link-Fehler prüfen und ausgeben

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);
  return shader;
};

// Vertex-Shader erwartet ein varying, das der Fragment-Shader anders deklariert
const vs = compile(gl.VERTEX_SHADER, `
  attribute vec4 aPos;
  varying vec3 vColor;
  void main() { vColor = vec3(1.0); gl_Position = aPos; }
`);
const fs = compile(gl.FRAGMENT_SHADER, `
  precision mediump float;
  varying vec4 vColor; // Typkonflikt!
  void main() { gl_FragColor = vColor; }
`);

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));
}

Linken fehlgeschlagen: Types of varyings do not match: 'vColor' (Wortlaut treiberabhängig)

Wiederverwendbare Hilfsfunktion mit Fehlerbehandlung

const createProgram = (gl, vertexShader, fragmentShader) => {
  const program = gl.createProgram();
  gl.attachShader(program, vertexShader);
  gl.attachShader(program, fragmentShader);
  gl.linkProgram(program);

  if (gl.getProgramParameter(program, gl.LINK_STATUS)) {
    return program;
  }

  const log = gl.getProgramInfoLog(program);
  gl.deleteProgram(program); // Ressourcen freigeben
  throw new Error(`WebGL-Programm konnte nicht gelinkt werden:\n${log}`);
};

// Nutzung
try {
  const program = createProgram(gl, vs, fs);
  gl.useProgram(program);
} catch (err) {
  console.error(err.message);
}

Programm vor dem Zeichnen validieren

// validateProgram prüft, ob das Programm im aktuellen GL-Zustand lauffähig ist
gl.validateProgram(program);

if (!gl.getProgramParameter(program, gl.VALIDATE_STATUS)) {
  console.warn('Validierung fehlgeschlagen:', gl.getProgramInfoLog(program));
} else {
  console.log('Programm gültig, Protokoll:', JSON.stringify(gl.getProgramInfoLog(program)));
}

Programm gültig, Protokoll: ""

// Wichtig · Fallstricke

Nicht Kompilier-, sondern Linkfehler: Syntaxfehler in einzelnen Shadern stehen im Protokoll von gl.getShaderInfoLog(). Prüfe zuerst COMPILE_STATUS jedes Shaders, dann LINK_STATUS des Programms.
Leeres Protokoll ≠ Erfolg: Entscheide immer anhand von getProgramParameter(program, gl.LINK_STATUS), nicht anhand der Länge des Logs – manche Treiber schreiben auch bei Erfolg Warnungen hinein, andere bei Fehlern gar nichts.
Performance: Die Abfrage von LINK_STATUS bzw. des Protokolls erzwingt eine Synchronisation mit der GPU. Bei vielen Programmen die Prüfung erst nach dem Linken aller Programme durchführen oder die Erweiterung KHR_parallel_shader_compile nutzen.
Das Format ist treiber- und plattformabhängig (ANGLE, Metal, OpenGL); nicht parsen und nicht ungefiltert Endnutzern anzeigen.
Bei verlorenem Kontext wird null zurückgegeben.
Kompatibilität: In allen modernen Browsern mit WebGL-Unterstützung verfügbar, ebenso in WebGL2RenderingContext.

Siehe auch

WebGLRenderingContext.getShaderInfoLog() WebGLRenderingContext.getProgramParameter() WebGLRenderingContext.linkProgram() WebGLRenderingContext.validateProgram() WebGLRenderingContext.createProgram() WebGLProgram