GPUCompilationInfo — Schnittstelle · JavaScript-Referenz

Signatur

interface GPUCompilationInfo

Beschreibung

GPUCompilationInfo ist das Ergebnisobjekt von GPUShaderModule.getCompilationInfo(). Es sammelt alle Meldungen, die der Compiler beim Übersetzen des WGSL-Codes erzeugt hat: Fehler, Warnungen und Hinweise. Jede Meldung zeigt als GPUCompilationMessage auf eine bestimmte Stelle im Quelltext (Zeile, Spalte, Offset und Länge).

Das Interface hat genau eine Eigenschaft, nämlich messages. Das ist ein schreibgeschütztes Array von GPUCompilationMessage-Objekten. Einen Konstruktor gibt es nicht. Instanzen bekommst du nur über das Promise von getCompilationInfo().

Einsatzgebiete:

Shader-Fehler mit genauer Position ausgeben, zum Beispiel in einem Live-Shader-Editor.
Warnungen in Entwicklungs-Builds protokollieren.
Vor dem Erzeugen einer Pipeline prüfen, ob das Modul überhaupt gültig ist.

Bei ungültigem WGSL wirft device.createShaderModule() keine Ausnahme. Das Modul wird dann intern als ungültig markiert, und der Fehler landet im Validierungsfehler-Bereich bzw. im uncapturederror-Ereignis. Mit getCompilationInfo() bekommst du die Einzelheiten in strukturierter Form.

Parameter

Name	Typ	Default	Beschreibung
$messages Pflicht	ReadonlyArray<GPUCompilationMessage>		Schreibgeschützte Eigenschaft: alle Compiler-Meldungen. Jede hat `message`, `type` (`"error"` \| `"warning"` \| `"info"`), `lineNum`, `linePos`, `offset` und `length`.

Beispiele

Compiler-Meldungen eines Shaders ausgeben

const adapter = await navigator.gpu.requestAdapter();
const device = await adapter.requestDevice();

// Absichtlicher Fehler: 'vec4f' falsch geschrieben
const code = `
@vertex
fn main() -> @builtin(position) vec4ff {
  return vec4f(0.0, 0.0, 0.0, 1.0);
}`;

const module = device.createShaderModule({ code });
const info = await module.getCompilationInfo();

for (const msg of info.messages) {
  console.log(`${msg.type} [${msg.lineNum}:${msg.linePos}] ${msg.message}`);
}

error [3:30] unresolved type 'vec4ff'

Vor dem Erzeugen der Pipeline auf Fehler prüfen

const compileShader = async (device, code) => {
  const module = device.createShaderModule({ code });
  const { messages } = await module.getCompilationInfo();

  const errors = messages.filter((m) => m.type === 'error');
  messages
    .filter((m) => m.type === 'warning')
    .forEach((w) => console.warn(`WGSL-Warnung Zeile ${w.lineNum}: ${w.message}`));

  if (errors.length > 0) {
    const details = errors
      .map((e) => `Zeile ${e.lineNum}, Spalte ${e.linePos}: ${e.message}`)
      .join('\n');
    throw new Error(`Shader-Kompilierung fehlgeschlagen:\n${details}`);
  }
  return module;
};

const adapter = await navigator.gpu.requestAdapter();
const device = await adapter.requestDevice();
try {
  const module = await compileShader(device, 'fn main( { }');
} catch (err) {
  console.error(err.message);
}

Shader-Kompilierung fehlgeschlagen: Zeile 1, Spalte 10: expected ')' for function declaration

Fehlerstelle im Quelltext markieren (Shader-Editor)

const highlightErrors = (code, info) =>
  info.messages
    .filter((m) => m.type === 'error')
    .map((m) => {
      // offset und length beziehen sich auf den Quelltext
      const snippet = code.slice(m.offset, m.offset + Math.max(m.length, 1));
      return `»${snippet}« → ${m.message}`;
    });

const adapter = await navigator.gpu.requestAdapter();
const device = await adapter.requestDevice();
const code = 'const x: i32 = 1.5;';
const module = device.createShaderModule({ code });
console.log(highlightErrors(code, await module.getCompilationInfo()));

[ '»1.5« → the type of the const declaration must match ...' ]

// Wichtig · Fallstricke

Browser-Unterstützung: WebGPU ist noch nicht überall verfügbar und läuft nur in sicheren Kontexten (HTTPS oder localhost). Prüfe deshalb vorher auf navigator.gpu. Unter Linux und Android ist die Unterstützung teils noch hinter Flags versteckt.
Text und genaue Positionen der Meldungen sind nicht standardisiert und unterscheiden sich je nach Browser (z. B. Tint in Chromium, Naga in Firefox). Werte deshalb nie den Meldungstext aus, sondern nur type und die Positionsangaben.
lineNum und linePos beginnen bei 1. offset und length zählen in UTF-16-Codeeinheiten, das passt direkt zu String.prototype.slice. Hat eine Meldung keine Position, stehen alle Werte auf 0.
createShaderModule() wirft bei Fehlern keine Ausnahme. Ohne getCompilationInfo() oder pushErrorScope('validation') tauchen Shader-Fehler erst als ungültige Pipeline auf.
getCompilationInfo() läuft asynchron und kann Zeit kosten. Rufe es in der Produktion nur bei Bedarf auf, etwa in Debug-Builds oder in Editoren.
Ältere Implementierungen hatten stattdessen GPUShaderModule.compilationInfo(). Diese Methode ist veraltet.

Siehe auch

GPUCompilationMessage GPUAdapterInfo GPUComputePipeline GPUValidationError GPUDeviceLostInfo