WEBGL_debug_shaders.getTranslatedShaderSource() — Methode · JavaScript-Referenz

Signatur

WEBGL_debug_shaders.getTranslatedShaderSource(shader)

Beschreibung

Browser reichen WebGL-Shader nicht unverändert an den Grafiktreiber weiter. Ein Übersetzer (meist ANGLE) prüft den GLSL-ES-Code, ergänzt Sicherheitsprüfungen und wandelt ihn in die Sprache der Plattform um, etwa HLSL unter Direct3D, Desktop-GLSL oder Metal Shading Language. getTranslatedShaderSource() aus der Erweiterung WEBGL_debug_shaders gibt genau diesen übersetzten Quelltext zurück.

Das ist vor allem beim Debuggen nützlich: bei Fehlern, die nur auf bestimmten GPUs oder Treibern auftreten, bei Unterschieden in Genauigkeit oder Leistung, und wenn man verstehen will, wie Schleifen, Arrayzugriffe oder Präzisionsangaben umgeschrieben wurden.

Die Erweiterung holt man mit gl.getExtension('WEBGL_debug_shaders'). Der übergebene Shader muss vorher mit gl.shaderSource() und gl.compileShader() kompiliert worden sein. Sonst ist das Ergebnis ein leerer String.

Parameter

Name	Typ	Default	Beschreibung
$shader Pflicht	WebGLShader		Ein Shader-Objekt, das mit `gl.createShader()` erzeugt und mit `gl.compileShader()` kompiliert wurde.

Rückgabewert

Typ

string

Beschreibung

Der übersetzte, plattformspezifische Shader-Quelltext. Ein leerer String, wenn der Shader nicht (erfolgreich) kompiliert wurde oder der Browser den Quelltext nicht herausgibt.

Beispiele

Übersetzten Fragment-Shader ausgeben

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

const source = `
precision mediump float;
void main() {
  gl_FragColor = vec4(1.0, 0.0, 0.0, 1.0);
}`;

const shader = gl.createShader(gl.FRAGMENT_SHADER);
gl.shaderSource(shader, source);
gl.compileShader(shader);

if (!gl.getShaderParameter(shader, gl.COMPILE_STATUS)) {
  console.error(gl.getShaderInfoLog(shader));
} else if (ext) {
  console.log(ext.getTranslatedShaderSource(shader));
} else {
  console.warn('WEBGL_debug_shaders nicht verfügbar');
}

// z. B. unter Windows/ANGLE (gekürzt): // float4 gl_Color[1] = ... // void gl_main() { gl_Color[0] = float4(1.0, 0.0, 0.0, 1.0); }

Hilfsfunktion: Shader kompilieren und Übersetzung protokollieren

const compileWithDebug = (gl, type, src) => {
  const shader = gl.createShader(type);
  gl.shaderSource(shader, src);
  gl.compileShader(shader);

  if (!gl.getShaderParameter(shader, gl.COMPILE_STATUS)) {
    const log = gl.getShaderInfoLog(shader);
    gl.deleteShader(shader);
    throw new Error(`Shader-Fehler: ${log}`);
  }

  const ext = gl.getExtension('WEBGL_debug_shaders');
  if (ext) {
    const translated = ext.getTranslatedShaderSource(shader);
    console.groupCollapsed(`Übersetzter Shader (${translated.length} Zeichen)`);
    console.log(translated || '(leer – vom Browser verborgen)');
    console.groupEnd();
  }
  return shader;
};

const gl = document.createElement('canvas').getContext('webgl2');
const vs = compileWithDebug(gl, gl.VERTEX_SHADER, `#version 300 es
in vec4 position;
void main() { gl_Position = position; }`);

Übersetzter Shader (… Zeichen)

Kombination mit WEBGL_debug_renderer_info für Fehlerberichte

const gl = document.createElement('canvas').getContext('webgl');
const dbgShaders = gl.getExtension('WEBGL_debug_shaders');
const dbgRenderer = gl.getExtension('WEBGL_debug_renderer_info');

const shader = gl.createShader(gl.VERTEX_SHADER);
gl.shaderSource(shader, 'attribute vec4 p; void main(){ gl_Position = p; }');
gl.compileShader(shader);

const report = {
  renderer: dbgRenderer
    ? gl.getParameter(dbgRenderer.UNMASKED_RENDERER_WEBGL)
    : gl.getParameter(gl.RENDERER),
  translated: dbgShaders?.getTranslatedShaderSource(shader) ?? null,
};
console.log(report);

{ renderer: 'ANGLE (NVIDIA, ...)', translated: '...' }

// Wichtig · Fallstricke

Verfügbarkeit: Die Erweiterung gibt es nicht überall. Firefox bietet sie Webseiten nur mit Einschränkungen an (teils nur mit privilegiertem Zugriff oder über about:config), weil der übersetzte Code Rückschlüsse auf GPU und Treiber erlaubt. Prüfen Sie daher immer, ob getExtension() null liefert.
Datenschutz: Der übersetzte Code hängt von der Plattform ab und kann zum Fingerprinting beitragen. Nutzen Sie ihn nur zum Debuggen und schicken Sie ihn nicht ohne Einwilligung an einen Server.
Nicht stabil: Die Ausgabe unterscheidet sich je nach Browser, Betriebssystem, ANGLE-Version und Treiber. Sie ist nicht dafür gedacht, sie zu parsen oder wiederzuverwenden. Verlassen Sie sich im Programm nie auf ihren Inhalt.
Vor dem Kompilieren oder nach einem fehlgeschlagenen Kompilieren ist der Rückgabewert ein leerer String. Fehlermeldungen liefert gl.getShaderInfoLog().
Nach einem Verlust des WebGL-Kontexts (webglcontextlost) müssen Sie die Erweiterung neu abfragen.

Siehe auch

WebGLRenderingContext.getExtension() WebGLRenderingContext.compileShader() WebGLRenderingContext.getShaderInfoLog() WebGLRenderingContext.getShaderSource() WebGLShader