Signatur
Beschreibung
Die Eigenschaft label von GPURenderBundle enthält eine frei wählbare Bezeichnung für ein Render-Bundle. Ein Render-Bundle ist eine vorab aufgezeichnete, wiederverwendbare Folge von Render-Befehlen. Man erzeugt es mit GPURenderBundleEncoder.finish() und spielt es mit GPURenderPassEncoder.executeBundles() in einem Render-Durchgang ab.
Die Bezeichnung hat keinen Einfluss auf das Rendern. Sie dient nur der Fehlersuche: Der Browser zeigt sie in Validierungsfehlern (GPUValidationError), in Konsolen-Warnungen und in Werkzeugen wie PIX, RenderDoc oder Xcode GPU Frame Capture an. Gerade wenn eine Anwendung viele Bundles nutzt (z. B. eins pro Szenen-Objekt oder Materialgruppe), lässt sich so schnell erkennen, welches Bundle einen Fehler verursacht hat.
Man kann das Label auf zwei Wegen setzen: beim Aufruf von finish({ label }) im Deskriptor oder später durch direkte Zuweisung an bundle.label. Wird nichts angegeben, ist der Wert ein leerer String "".
Beispiele
Label beim Abschließen des Bundle-Encoders setzen
const adapter = await navigator.gpu.requestAdapter();
const device = await adapter.requestDevice();
const format = navigator.gpu.getPreferredCanvasFormat();
const bundleEncoder = device.createRenderBundleEncoder({
label: 'Encoder: Hintergrund',
colorFormats: [format]
});
// ... hier setPipeline(), setVertexBuffer(), draw() aufrufen ...
const bundle = bundleEncoder.finish({ label: 'Bundle: Hintergrund' });
console.log(bundle.label);Label nachträglich setzen und auslesen
const bundle = bundleEncoder.finish();
console.log(JSON.stringify(bundle.label)); // noch kein Label
bundle.label = 'Bundle: Bäume (LOD 0)';
console.log(bundle.label);Aussagekräftige Labels für Fehlermeldungen
const bundles = ['Gelände', 'Gebäude', 'Fahrzeuge'].map((name) => {
const enc = device.createRenderBundleEncoder({ colorFormats: [format] });
// ... Zeichenbefehle für das jeweilige Objekt aufzeichnen ...
return enc.finish({ label: `Bundle: ${name}` });
});
device.pushErrorScope('validation');
passEncoder.executeBundles(bundles);
const error = await device.popErrorScope();
if (error) {
// Die Meldung nennt das betroffene Bundle beim Namen, z. B. "[RenderBundle \"Bundle: Gebäude\"] ..."
console.error(error.message);
}// Wichtig · Fallstricke
- Nur zur Fehlersuche: Das Label ändert nichts am Rendern. Wie genau es in Fehlermeldungen auftaucht, legt jeder Browser selbst fest.
- Das Label des
GPURenderBundleEncoderwird nicht automatisch an das Bundle weitergegeben. Das Bundle muss man infinish()oder per Zuweisung eigens benennen. - Keine vertraulichen Daten ins Label schreiben. Es kann in Konsolen-Ausgaben, Absturzberichten und Aufzeichnungen der Grafik-Werkzeuge landen.
- Kompatibilität: WebGPU steht nur in sicheren Kontexten (HTTPS) zur Verfügung und wird noch nicht überall unterstützt. Deshalb vorher mit
if (!navigator.gpu)prüfen, ob es vorhanden ist. Unter Linux und Android ist die Unterstützung teils eingeschränkt oder hinter Flags versteckt.