GPUCompilationMessage.message — Eigenschaft · JavaScript-Referenz

Signatur

GPUCompilationMessage.message

Beschreibung

Die Eigenschaft message eines GPUCompilationMessage-Objekts enthält den eigentlichen Meldungstext, den die WebGPU-Implementierung beim Kompilieren eines Shader-Moduls erzeugt, z. B. „unresolved identifier 'colr'“. Solche Objekte bekommst du nicht direkt, sondern über das Array messages des GPUCompilationInfo-Objekts, das GPUShaderModule.getCompilationInfo() zurückgibt.

Gebraucht wird die Eigenschaft vor allem beim Debuggen von WGSL-Shadern: Zusammen mit type ("error", "warning" oder "info"), lineNum, linePos, offset und length lassen sich aussagekräftige Fehlerberichte erstellen, etwa für die Konsole, ein eigenes Overlay oder einen Shader-Editor im Browser.

Der Text ist nur für Menschen gedacht. Sein Wortlaut ist nicht standardisiert und kann sich zwischen Browsern, Versionen und Grafiktreibern unterscheiden. Programmlogik sollte sich daher auf type und die Positionsangaben stützen, nicht auf den Inhalt von message.

Rückgabewert

Typ

string

Beschreibung

Der menschenlesbare Text der Compiler-Meldung. Die Eigenschaft ist schreibgeschützt.

Beispiele

Compiler-Meldungen eines fehlerhaften Shaders ausgeben

const adapter = await navigator.gpu?.requestAdapter();
if (!adapter) throw new Error('WebGPU wird nicht unterstützt');
const device = await adapter.requestDevice();

// Absichtlicher Tippfehler: 'colr' statt 'color'
const code = `
@fragment
fn main() -> @location(0) vec4f {
  let color = vec4f(1.0, 0.0, 0.0, 1.0);
  return colr;
}`;

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

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

error (Zeile 5:10): unresolved value 'colr'

Nur Fehler herausfiltern und mit Codezeile melden

const reportShaderErrors = async (module, code) => {
  const { messages } = await module.getCompilationInfo();
  const errors = messages.filter((m) => m.type === 'error');
  if (errors.length === 0) return true;

  const lines = code.split('\n');
  for (const err of errors) {
    const source = lines[err.lineNum - 1] ?? '';
    console.error(
      `${err.message}\n  ${source}\n  ${' '.repeat(Math.max(err.linePos - 1, 0))}^`
    );
  }
  return false;
};

// Nutzung:
// const ok = await reportShaderErrors(module, code);

unresolved value 'colr' return colr; ^

Meldungen für eine Editor-UI aufbereiten

const toDiagnostics = async (module) => {
  const { messages } = await module.getCompilationInfo();
  return messages.map(({ type, message, lineNum, linePos, length }) => ({
    severity: type,
    text: message,
    line: lineNum,
    column: linePos,
    length
  }));
};

// const diagnostics = await toDiagnostics(module);
// console.table(diagnostics);

// Wichtig · Fallstricke

Wortlaut nicht verlässlich: Der Text von message ist implementierungsabhängig. Werte ihn nicht mit Stringvergleichen oder regulären Ausdrücken aus, sondern nutze type und die Positionseigenschaften.
Sicherheit: Die Meldung kann Ausschnitte aus dem Shader-Quelltext enthalten. Wenn du sie im DOM anzeigst, verwende textContent statt innerHTML, vor allem wenn der Shader-Code von Nutzern stammt.
Keine Meldungen heißt nicht zwingend fehlerfrei: Manche Fehler treten erst beim Erstellen der Pipeline auf (createRenderPipeline() bzw. createComputePipeline()). Solche Fehler erreichst du über device.pushErrorScope()/popErrorScope() oder GPUPipelineError.
Kompatibilität: WebGPU steht nur in sicheren Kontexten (HTTPS) zur Verfügung und wird noch nicht überall unterstützt. Prüfe vorher, ob navigator.gpu vorhanden ist. lineNum und linePos beginnen bei 1 und beziehen sich auf UTF-16-Codeeinheiten.

Siehe auch

GPUCompilationMessage GPUCompilationInfo GPUShaderModule.getCompilationInfo() GPUCompilationMessage.type GPUCompilationMessage.lineNum GPUCompilationMessage.linePos GPUDevice.createShaderModule()