Signatur
Beschreibung
Die Eigenschaft label von GPUCommandBuffer enthält einen frei wählbaren Text, mit dem sich ein bestimmter Befehlspuffer erkennen lässt. Der Browser verwendet diesen Namen in Meldungen von GPUError, in Konsolenwarnungen, in Validierungsfehlern und in GPU-Debugging-Werkzeugen wie PIX, RenderDoc oder Xcode GPU Capture.
Man kann das Label auf zwei Arten setzen: direkt beim Abschließen der Aufzeichnung über den Deskriptor von GPUCommandEncoder.finish({ label }) oder nachträglich durch eine Zuweisung an commandBuffer.label. Ohne Angabe ist der Wert ein leerer String "".
Wenn mehrere Befehlspuffer pro Frame erzeugt werden, zum Beispiel für einen Schatten-Pass, den Haupt-Render-Pass und die Nachbearbeitung, helfen eindeutige Labels sehr: Scheitert GPUQueue.submit() an einer Validierung, zeigt die Fehlermeldung, welcher Puffer betroffen ist.
Rückgabewert
"".Beispiele
Label über den finish()-Deskriptor setzen
const adapter = await navigator.gpu.requestAdapter();
const device = await adapter.requestDevice();
const encoder = device.createCommandEncoder({ label: 'frame-encoder' });
// ... Render- oder Compute-Passes aufzeichnen ...
const commandBuffer = encoder.finish({ label: 'frame-command-buffer' });
console.log(commandBuffer.label);
device.queue.submit([commandBuffer]);Label nachträglich zuweisen und auslesen
const device = await (await navigator.gpu.requestAdapter()).requestDevice();
const commandBuffer = device.createCommandEncoder().finish();
console.log(JSON.stringify(commandBuffer.label)); // Standardwert
commandBuffer.label = 'postprocessing-pass';
console.log(commandBuffer.label);Labels in Fehlermeldungen zur Fehlersuche nutzen
const device = await (await navigator.gpu.requestAdapter()).requestDevice();
device.pushErrorScope('validation');
const encoder = device.createCommandEncoder({ label: 'shadow-encoder' });
const cb = encoder.finish({ label: `shadow-pass #${performance.now().toFixed(0)}` });
device.queue.submit([cb]);
// Ein zweites Absenden desselben Puffers ist ungültig
device.queue.submit([cb]);
const error = await device.popErrorScope();
if (error) {
// Die Meldung enthält typischerweise das Label, z. B. [CommandBuffer "shadow-pass #..."]
console.warn(error.message);
}// Wichtig · Fallstricke
- Nur zur Fehlersuche: Das Label hat keinen Einfluss darauf, wie Befehle ausgeführt werden. Wie und ob es in Meldungen erscheint, hängt vom Browser ab.
- Einmal verwendbar: Ein
GPUCommandBufferkann nur ein einziges Mal abgesendet werden. Das Label bleibt danach lesbar, aber der Puffer lässt sich nicht erneut verwenden. - Keine sensiblen Daten: Labels können in Konsolenausgaben und Debugging-Werkzeugen erscheinen. Speichere dort also keine vertraulichen Informationen.
- Kompatibilität: WebGPU steht nur in sicheren Kontexten (HTTPS) zur Verfügung und ist noch nicht in allen Browsern bzw. auf allen Plattformen aktiviert. Prüfe vorher mit
if (!navigator.gpu) { … }, ob es verfügbar ist. - Die Eigenschaft stammt aus dem Mixin
GPUObjectBaseund funktioniert bei allen WebGPU-Objekten gleich, etwa beiGPUBuffer,GPUTextureoderGPUCommandEncoder.