Signatur
Beschreibung
Die Eigenschaft label des GPURenderBundleEncoder enthält eine frei wählbare Bezeichnung. Die WebGPU-Implementierung nutzt sie, um das Objekt in Fehlermeldungen (GPUValidationError, GPUOutOfMemoryError), Konsolenwarnungen und in Grafik-Debuggern (z. B. PIX, RenderDoc, Xcode GPU Frame Capture) zu benennen.
Setzen lässt sich das Label entweder bei der Erzeugung über das Deskriptor-Objekt von GPUDevice.createRenderBundleEncoder({ label: "…" }) oder später durch direktes Zuweisen an encoder.label. Ist nichts angegeben, ist der Wert ein leerer String.
Gerade bei Render-Bundles lohnt sich ein aussagekräftiges Label: Ein Bundle zeichnet Befehle einmalig auf und wird dann in vielen Render-Passes wiederverwendet. Tritt ein Validierungsfehler beim Aufzeichnen oder bei finish() auf, erkennt man am Label sofort, welcher Encoder betroffen ist.
Das Label hat keinerlei Einfluss auf das Rendering selbst – es dient ausschließlich der Diagnose.
Rückgabewert
"", wenn kein Label gesetzt wurde. Die Eigenschaft kann auch beschrieben werden.Beispiele
Label über den Deskriptor setzen und auslesen
const adapter = await navigator.gpu.requestAdapter();
const device = await adapter.requestDevice();
const bundleEncoder = device.createRenderBundleEncoder({
label: "Bundle: statische Szenerie",
colorFormats: [navigator.gpu.getPreferredCanvasFormat()],
});
console.log(bundleEncoder.label);Label nachträglich zuweisen
const bundleEncoder = device.createRenderBundleEncoder({
colorFormats: ["bgra8unorm"],
depthStencilFormat: "depth24plus",
});
console.log(JSON.stringify(bundleEncoder.label)); // noch leer
bundleEncoder.label = "Bundle: Bäume (instanziert)";
console.log(bundleEncoder.label);Label in Validierungsfehlern wiederfinden
device.pushErrorScope("validation");
const bundleEncoder = device.createRenderBundleEncoder({
label: "Bundle: HUD",
colorFormats: ["bgra8unorm"],
});
// Fehler provozieren: draw() ohne gesetzte Pipeline
bundleEncoder.draw(3);
const bundle = bundleEncoder.finish({ label: "HUD-Bundle" });
const error = await device.popErrorScope();
if (error) {
// Die Meldung enthält typischerweise das Label, z. B. [RenderBundleEncoder "Bundle: HUD"]
console.warn("WebGPU-Fehler:", error.message);
}// Wichtig · Fallstricke
- Getrennte Labels: Das Label des Encoders wird nicht automatisch auf das von
finish()erzeugteGPURenderBundleübertragen. Vergib dafür ein eigenes Label überfinish({ label: "…" }). - Format der Meldungen: Wie und ob das Label in Fehlermeldungen erscheint, legt der Browser fest. Werte keine Fehlertexte maschinell aus.
- Keine sensiblen Daten: Labels können in Konsolenausgaben, Fehlerberichten und GPU-Captures auftauchen. Schreib keine Benutzerdaten oder Geheimnisse hinein.
- Kompatibilität: WebGPU gibt es nur in sicheren Kontexten (HTTPS) und noch nicht in allen Browsern bzw. auf allen Plattformen. Prüfe vorher, ob
navigator.gpuvorhanden ist. - Labels werden bei jeder Zuweisung gespeichert, das kostet praktisch keine Leistung. Trotzdem gilt: nicht in jedem Frame neu setzen, wenn es nicht nötig ist.