Signatur
Beschreibung
Die Eigenschaft label des Interfaces GPUDevice enthält eine frei wählbare Bezeichnung für das logische GPU-Gerät. Diese Bezeichnung hat keinen Einfluss auf das Rendering oder die Berechnung. Sie dient nur zur Fehlersuche: Browser verwenden sie in Validierungsfehlern (GPUValidationError), in Konsolenwarnungen und in GPU-Debugging-Werkzeugen, damit du erkennst, welches Objekt betroffen ist.
Du kannst das Label auf zwei Arten setzen: beim Anfordern des Geräts über den Deskriptor von GPUAdapter.requestDevice({ label: "…" }) oder später durch direkte Zuweisung an device.label. Ohne Angabe ist der Wert ein leerer String "".
Die Eigenschaft stammt aus dem Mixin GPUObjectBase. Deshalb haben praktisch alle WebGPU-Objekte eine gleichartige label-Eigenschaft, etwa GPUBuffer, GPUTexture, GPURenderPipeline oder GPUCommandEncoder. Wenn du deine Objekte einheitlich benennst, lassen sich Fehlermeldungen in größeren Anwendungen deutlich schneller zuordnen.
Rückgabewert
"". Zugewiesene Werte werden in einen String umgewandelt.Beispiele
Label beim Anfordern des Geräts setzen und auslesen
const initGPU = async () => {
if (!navigator.gpu) {
throw new Error("WebGPU wird in diesem Browser nicht unterstützt.");
}
const adapter = await navigator.gpu.requestAdapter();
if (!adapter) {
throw new Error("Kein passender GPU-Adapter gefunden.");
}
const device = await adapter.requestDevice({ label: "Haupt-Renderer" });
console.log(device.label);
return device;
};
initGPU();Label nachträglich ändern
const adapter = await navigator.gpu.requestAdapter();
const device = await adapter.requestDevice();
console.log(JSON.stringify(device.label)); // Standardwert
device.label = "Physik-Simulation (Compute)";
console.log(device.label);Label in der Fehlerbehandlung verwenden
const adapter = await navigator.gpu.requestAdapter();
const device = await adapter.requestDevice({ label: "Editor-Vorschau" });
// Nicht abgefangene Fehler mit Gerätenamen protokollieren
device.addEventListener("uncapturederror", (event) => {
console.error(`[${device.label}] ${event.error.message}`);
});
// Geräteverlust mit Label melden
device.lost.then((info) => {
console.warn(`Gerät "${device.label}" verloren: ${info.reason} – ${info.message}`);
});
// Absichtlich ungültiger Puffer (Größe nicht durch 4 teilbar bei MAP_READ | COPY_DST ist ok,
// aber MAP_READ zusammen mit MAP_WRITE ist ungültig)
device.pushErrorScope("validation");
device.createBuffer({
label: "Fehlerhafter Puffer",
size: 16,
usage: GPUBufferUsage.MAP_READ | GPUBufferUsage.MAP_WRITE
});
const error = await device.popErrorScope();
if (error) {
console.error(`Validierungsfehler auf ${device.label}:`, error.message);
}// Wichtig · Fallstricke
- Nur zur Fehlersuche: Das Label beeinflusst weder die Leistung noch das Verhalten des Geräts. Speichere darin keine Programmlogik oder vertraulichen Daten, denn es kann in Konsolenausgaben und Fehlermeldungen auftauchen.
- Format von Fehlermeldungen: Wie und ob das Label in Meldungen erscheint, legt jeder Browser selbst fest. Der genaue Wortlaut von
GPUError.messageist nicht standardisiert. Werte ihn also nicht maschinell aus. - Typumwandlung: Zugewiesene Werte werden in einen String umgewandelt.
device.label = nullergibt deshalb"null"und keinen leeren String. - Kompatibilität: WebGPU steht nur in sicheren Kontexten (HTTPS oder localhost) zur Verfügung und wird noch nicht überall unterstützt. Chromium-Browser unterstützen es ab Version 113, Safari ab Version 26. In Firefox ist es seit Version 141 unter Windows aktiviert, auf anderen Plattformen nur teilweise. Prüfe vorher mit
if (navigator.gpu), ob die Schnittstelle vorhanden ist. - Andere Objekte übernehmen das Label des Geräts nicht. Puffer, Texturen, Pipelines usw. solltest du jeweils einzeln über ihren Deskriptor benennen.