GPUCompilationInfo.messages — Eigenschaft · JavaScript-Referenz

Signatur

GPUCompilationInfo.messages

Beschreibung

Die schreibgeschützte Eigenschaft messages der Schnittstelle GPUCompilationInfo enthält alle Meldungen, die der WGSL-Compiler beim Erstellen eines Shadermoduls mit GPUDevice.createShaderModule() erzeugt hat. Ein GPUCompilationInfo-Objekt bekommst du über das Promise von GPUShaderModule.getCompilationInfo().

Jedes Element ist ein GPUCompilationMessage mit diesen Eigenschaften:

type: "error", "warning" oder "info"
message: der Meldungstext
lineNum, linePos: Zeile und Spalte im Quelltext (1-basiert, 0, wenn keine Position bekannt ist)
offset, length: Position und Länge des betroffenen Abschnitts im Quelltext

Du brauchst die Eigenschaft vor allem beim Entwickeln und Debuggen von Shadern. Mit ihr kannst du Compilerfehler gezielt auswerten, im Editor hervorheben oder protokollieren, bevor du eine Render- oder Compute-Pipeline aufbaust. Ist das Array leer, hat der Compiler nichts zu melden.

Rückgabewert

Typ

ReadonlyArray<GPUCompilationMessage>

Beschreibung

Ein eingefrorenes Array mit allen Compiler-Meldungen. Es ist leer, wenn es weder Fehler noch Warnungen oder Hinweise gibt.

Beispiele

Compiler-Meldungen eines Shaders ausgeben

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

// Absichtlicher Fehler: Semikolon fehlt
const code = `
@vertex
fn main() -> @builtin(position) vec4f {
  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} (Zeile ${msg.lineNum}:${msg.linePos}): ${msg.message}`);
}

error (Zeile 5:1): expected ';' for return statement

Vor dem Pipeline-Aufbau 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');
  const warnings = messages.filter((m) => m.type === 'warning');

  warnings.forEach((w) => console.warn(`WGSL-Warnung Z. ${w.lineNum}: ${w.message}`));

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

// Nutzung
const module = await compileShader(device, wgslSource);
console.log('Shader ok');

Shader ok

Fehlerstelle im Quelltext markieren

const highlightErrors = (code, messages) =>
  messages
    .filter((m) => m.type === 'error' && m.length > 0)
    .map((m) => {
      const snippet = code.slice(m.offset, m.offset + m.length);
      return `»${snippet}« → ${m.message}`;
    });

const code = 'fn f() -> i32 { return undefinedVar; }';
const module = device.createShaderModule({ code });
const { messages } = await module.getCompilationInfo();
console.log(highlightErrors(code, messages));

[ '»undefinedVar« → unresolved value \'undefinedVar\'' ]

// Wichtig · Fallstricke

Kompatibilität: WebGPU ist nur in sicheren Kontexten (HTTPS) verfügbar und wird noch nicht überall unterstützt. Prüfe vorher mit if (!navigator.gpu), ob die API vorhanden ist.
Wortlaut und Anzahl der Meldungen hängen vom Browser ab. Der Text in message ist für Menschen gedacht. Werte ihn nicht automatisch aus, sondern prüfe stattdessen type.
offset und length werden in UTF-16-Codeeinheiten gezählt und passen deshalb direkt zu String.prototype.slice().
Ein leeres messages-Array bedeutet nicht zwingend, dass die spätere Pipeline gültig ist. Fehler beim Aufbau der Pipeline, etwa ein falscher entryPoint, fängst du mit device.pushErrorScope('validation') bzw. createRenderPipelineAsync() ab.
getCompilationInfo() läuft asynchron. Rufe es in Produktivcode am besten nur im Debug-Modus auf, damit das Laden nicht unnötig länger dauert.

Siehe auch

GPUCompilationInfo GPUCompilationMessage GPUShaderModule.getCompilationInfo() GPUDevice.createShaderModule() GPUDevice.pushErrorScope() PerformanceTiming.domainLookupStart WorkerLocation.hostname