GPUShaderModule.label — Eigenschaft · JavaScript-Referenz

Signatur

GPUShaderModule.label

Beschreibung

Die Eigenschaft label gehört zum Mixin GPUObjectBase und steht daher auch bei GPUShaderModule zur Verfügung. Sie enthält einen frei wählbaren String, mit dem der Browser das Shader-Modul in Fehlermeldungen, Validierungswarnungen und Werkzeugen wie Chrome DevTools, PIX oder RenderDoc benennt.

Das Label lässt sich auf zwei Wegen setzen: beim Erzeugen über die Option label im Deskriptor von GPUDevice.createShaderModule() oder später durch direkte Zuweisung an shaderModule.label. Ist kein Label gesetzt, ist der Wert ein leerer String "".

Gerade bei Shadern lohnen sich aussagekräftige Labels. WGSL-Kompilierfehler und Pipeline-Validierungsfehler geben dann den Namen des Moduls aus, zum Beispiel „[ShaderModule "Beleuchtung-Fragment"]“. Bei vielen Modulen findet man so schnell die Stelle, an der ein Fehler entstanden ist.

Rückgabewert

Typ

string

Beschreibung

Das aktuelle Label des Shader-Moduls. Wurde keines gesetzt, ist es ein leerer String. Die Eigenschaft lässt sich auch beschreiben.

Beispiele

Label beim Erzeugen des Shader-Moduls setzen

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

const shaderModule = device.createShaderModule({
  label: 'Dreieck-Shader',
  code: /* wgsl */ `
    @vertex fn vs(@builtin(vertex_index) i: u32) -> @builtin(position) vec4f {
      let pos = array(vec2f(0.0, 0.5), vec2f(-0.5, -0.5), vec2f(0.5, -0.5));
      return vec4f(pos[i], 0.0, 1.0);
    }
    @fragment fn fs() -> @location(0) vec4f {
      return vec4f(1.0, 0.4, 0.0, 1.0);
    }
  `,
});

console.log(shaderModule.label);

Dreieck-Shader

Label nachträglich ändern

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

const module = device.createShaderModule({
  code: '@compute @workgroup_size(64) fn main() {}',
});

console.log(JSON.stringify(module.label)); // noch nicht gesetzt
module.label = 'Partikel-Compute';
console.log(module.label);

"" Partikel-Compute

Kompilierfehler mit Label zuordnen

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

const module = device.createShaderModule({
  label: 'Kaputter-Fragment-Shader',
  code: '@fragment fn fs() -> @location(0) vec4f { return vec3f(1.0); }',
});

const info = await module.getCompilationInfo();
for (const msg of info.messages) {
  console.warn(`[${module.label}] ${msg.type} in Zeile ${msg.lineNum}: ${msg.message}`);
}

[Kaputter-Fragment-Shader] error in Zeile 1: return statement type must match its function return type ...

// Wichtig · Fallstricke

Das Label dient nur der Fehlersuche und ändert nichts am Verhalten des Moduls. Man kann es gefahrlos jederzeit ändern.
Keine vertraulichen Daten ins Label schreiben. Es kann in Konsolenausgaben, Fehlerberichten und Absturzprotokollen des Browsers auftauchen.
Das genaue Format von Fehlermeldungen mit Label legt jeder Browser selbst fest. Ein Programm sollte diese Texte daher nicht auswerten.
WebGPU gibt es nur in sicheren Kontexten (HTTPS). Die Unterstützung ist noch lückenhaft: In Firefox und Safari ist sie erst seit Kurzem da, teils nur auf bestimmten Plattformen. Deshalb vorher navigator.gpu prüfen.
Das Label wird nicht automatisch an Pipelines weitergegeben, die das Modul nutzen. Für Pipelines ein eigenes label vergeben.

Siehe auch

GPUShaderModule GPUDevice.createShaderModule() GPUShaderModule.getCompilationInfo() GPUError GPUDevice.pushErrorScope() GPURenderPipeline.label GPUQueue.label