Signatur
Beschreibung
Die Eigenschaft label ist ein String, den du einem GPUCommandEncoder zuweisen kannst, um ihn eindeutig zu benennen. Der Browser verwendet diese Bezeichnung in Validierungsfehlern (GPUValidationError), in Konsolenwarnungen und in GPU-Debugging-Werkzeugen wie PIX, RenderDoc oder Xcode GPU Capture. So erkennst du sofort, welcher Encoder ein Problem verursacht hat.
Du kannst das Label auf zwei Wegen setzen: direkt beim Erzeugen über das Deskriptor-Feld label von GPUDevice.createCommandEncoder() oder nachträglich durch Zuweisung an encoder.label. Ohne Angabe ist der Wert ein leerer String ("").
Labels ändern das Verhalten der GPU nicht. Sie sind reine Metadaten und lohnen sich vor allem dann, wenn in einem Frame mehrere Encoder zum Einsatz kommen, etwa für Schattenpass, Hauptpass und Nachbearbeitung.
Rückgabewert
"". Die Eigenschaft ist les- und beschreibbar.Beispiele
Label beim Erzeugen setzen und auslesen
const adapter = await navigator.gpu?.requestAdapter();
if (!adapter) throw new Error('WebGPU wird nicht unterstützt');
const device = await adapter.requestDevice();
const encoder = device.createCommandEncoder({ label: 'Hauptpass-Encoder' });
console.log(encoder.label);Label nachträglich zuweisen
const adapter = await navigator.gpu.requestAdapter();
const device = await adapter.requestDevice();
const encoder = device.createCommandEncoder();
console.log(JSON.stringify(encoder.label)); // leer
encoder.label = `Frame-${performance.now().toFixed(0)}-Encoder`;
console.log(encoder.label.startsWith('Frame-'));Label in Validierungsfehlern wiederfinden
const adapter = await navigator.gpu.requestAdapter();
const device = await adapter.requestDevice();
device.pushErrorScope('validation');
const encoder = device.createCommandEncoder({ label: 'Nachbearbeitungs-Encoder' });
const pass = encoder.beginComputePass({ label: 'Blur-Pass' });
// Absichtlicher Fehler: dispatch ohne gesetzte Pipeline
pass.dispatchWorkgroups(1);
pass.end();
device.queue.submit([encoder.finish({ label: 'Nachbearbeitungs-Befehle' })]);
const error = await device.popErrorScope();
if (error) {
// Die Meldung enthält typischerweise die Labels der beteiligten Objekte
console.warn(error.message);
}// Wichtig · Fallstricke
- Kein Einfluss auf das Rendering: Labels dienen nur der Diagnose. Wie genau Fehlermeldungen formuliert sind, hängt vom Browser ab. Verlass dich also nicht auf ein bestimmtes Format.
- Label wird nicht vererbt: Das Label des Encoders geht nicht automatisch auf den
GPUCommandBufferüber, denfinish()liefert. Vergib dort bei Bedarf ein eigenes Label überfinish({ label }). - Keine sensiblen Daten: Labels können in Fehlerberichten, Absturzprotokollen und Profiling-Mitschnitten auftauchen. Schreib keine Nutzerdaten oder Geheimnisse hinein.
- Kompatibilität: WebGPU steht nur in sicheren Kontexten (HTTPS) zur Verfügung und ist noch nicht auf allen Plattformen aktiviert. Prüf die Unterstützung vorher mit
navigator.gpu. - Leistung: Häufiges Neuerzeugen von Label-Strings, etwa pro Frame per Template-String, kostet kaum etwas. In Hochlast-Schleifen kann aber ein festes Label sinnvoller sein.