Signatur
Beschreibung
Die Eigenschaft label stammt aus dem Mixin GPUObjectBase und enthält eine frei wählbare Bezeichnung für einen Render-Pass-Encoder. Der Browser übernimmt diesen Text in GPUError-Meldungen, in Validierungswarnungen der Konsole und oft auch in GPU-Debuggern wie PIX, RenderDoc oder Xcode. So lässt sich schnell erkennen, welcher Render-Pass ein Problem verursacht hat.
Am einfachsten setzt man das Label direkt beim Anlegen über die Eigenschaft label im Deskriptor-Objekt von GPUCommandEncoder.beginRenderPass(). Man kann es aber auch später jederzeit lesen oder überschreiben, indem man passEncoder.label einen neuen Wert zuweist.
Gerade bei Anwendungen mit mehreren Durchläufen (Shadow-Pass, G-Buffer, Post-Processing, UI) lohnen sich aussagekräftige Labels: Validierungsfehler wie „Invalid RenderPassEncoder "Shadow-Pass"“ sind dann sofort einer Stelle im Code zuzuordnen. Auf die Darstellung oder die Leistung wirkt sich das Label nicht aus.
Beispiele
Label beim Anlegen über den Deskriptor setzen
const adapter = await navigator.gpu.requestAdapter();
const device = await adapter.requestDevice();
const context = document.querySelector('canvas').getContext('webgpu');
context.configure({ device, format: navigator.gpu.getPreferredCanvasFormat() });
const commandEncoder = device.createCommandEncoder({ label: 'Frame-Encoder' });
const passEncoder = commandEncoder.beginRenderPass({
label: 'Haupt-Render-Pass',
colorAttachments: [{
view: context.getCurrentTexture().createView(),
clearValue: { r: 0, g: 0, b: 0.2, a: 1 },
loadOp: 'clear',
storeOp: 'store'
}]
});
console.log(passEncoder.label);
passEncoder.end();
device.queue.submit([commandEncoder.finish()]);Label nachträglich lesen und ändern
const passEncoder = commandEncoder.beginRenderPass(renderPassDescriptor);
console.log(`Vorher: "${passEncoder.label}"`);
passEncoder.label = 'Post-Processing-Pass';
console.log(`Nachher: "${passEncoder.label}"`);
passEncoder.end();Labels für die Fehlersuche mit Error-Scopes nutzen
device.pushErrorScope('validation');
const pass = commandEncoder.beginRenderPass({
...renderPassDescriptor,
label: 'Schatten-Pass'
});
// Fehler provozieren: Zeichnen ohne gesetzte Pipeline
pass.draw(3);
pass.end();
device.queue.submit([commandEncoder.finish()]);
const error = await device.popErrorScope();
if (error) {
// Die Meldung enthält das Label, z. B. [RenderPassEncoder "Schatten-Pass"]
console.warn(error.message);
}// Wichtig · Fallstricke
- Nur zur Fehlersuche: Das Label ändert weder die Darstellung noch das Verhalten. Keine sensiblen Daten hineinschreiben, denn es kann in Logs und Crash-Berichten landen.
- Den Wortlaut der Fehlermeldungen legt der Browser fest und er ist nicht standardisiert. Man sollte ihn also nicht automatisiert auswerten.
- Nicht-String-Werte werden bei der Zuweisung in einen String umgewandelt (z. B.
42→"42"). - Das Label kann auch nach
end()noch gelesen werden. Ein Encoder, der schon beendet ist, lässt sich aber nicht mehr verwenden. - Kompatibilität: WebGPU steht nur in sicheren Kontexten zur Verfügung und wird noch nicht überall unterstützt. Am besten vorher mit
if (!navigator.gpu)prüfen, ob es verfügbar ist.