GPUQuerySet.label — Eigenschaft · JavaScript-Referenz

Signatur

GPUQuerySet.label

Beschreibung

Die Eigenschaft label des Interfaces GPUQuerySet enthält einen frei wählbaren String, der das Query-Set kennzeichnet. Der Browser verwendet dieses Label in Validierungsfehlern (GPUValidationError), in Konsolenwarnungen und in GPU-Debugging-Werkzeugen. So erkennst du sofort, welches Query-Set ein Problem verursacht hat.

Ein Label kannst du auf zwei Wegen setzen: beim Erzeugen über die Deskriptor-Option label von GPUDevice.createQuerySet() oder nachträglich durch direkte Zuweisung an querySet.label. Wurde kein Label angegeben, ist der Wert ein leerer String "".

Besonders nützlich sind Labels bei Timestamp- und Occlusion-Queries. Anwendungen legen davon oft mehrere an, zum Beispiel eines pro Render-Pass oder pro Frame. Mit aussagekräftigen Namen wie "Frame-Timing" oder "Occlusion: Hauptszene" lassen sich Fehler deutlich schneller finden.

Parameter

Name	Typ	Default	Beschreibung
$label	string	""	Neuer Wert beim Schreiben. Wird auch über `descriptor.label` in `GPUDevice.createQuerySet()` gesetzt. Nicht-String-Werte werden in einen String umgewandelt.

Rückgabewert

Typ

string

Beschreibung

Das aktuelle Label des Query-Sets oder ein leerer String, wenn keines gesetzt wurde.

Beispiele

Label beim Erzeugen setzen und auslesen

const adapter = await navigator.gpu?.requestAdapter();
if (!adapter) throw new Error('WebGPU nicht verfügbar');
const device = await adapter.requestDevice();

const occlusionSet = device.createQuerySet({
  label: 'Occlusion: Hauptszene',
  type: 'occlusion',
  count: 32
});

console.log(occlusionSet.label);

Occlusion: Hauptszene

Label nachträglich zuweisen

const adapter = await navigator.gpu.requestAdapter();
const device = await adapter.requestDevice();

const querySet = device.createQuerySet({ type: 'occlusion', count: 8 });
console.log(JSON.stringify(querySet.label)); // noch leer

querySet.label = 'Occlusion: Schatten-Pass';
console.log(querySet.label);

"" Occlusion: Schatten-Pass

Label in Validierungsfehlern wiederfinden

const adapter = await navigator.gpu.requestAdapter();
const device = await adapter.requestDevice();

device.pushErrorScope('validation');

// Ungültig: count überschreitet das Limit von 4096
const badSet = device.createQuerySet({
  label: 'Kaputtes Query-Set',
  type: 'occlusion',
  count: 5000
});

const error = await device.popErrorScope();
if (error) {
  // Die Meldung enthält in der Regel das Label, z. B. [QuerySet "Kaputtes Query-Set"]
  console.warn(`Fehler bei "${badSet.label}":`, error.message);
}

Fehler bei "Kaputtes Query-Set": ... (browserabhängige Meldung)

Timestamp-Query-Set pro Frame benennen

const adapter = await navigator.gpu.requestAdapter();
if (!adapter.features.has('timestamp-query')) {
  throw new Error('timestamp-query wird nicht unterstützt');
}
const device = await adapter.requestDevice({
  requiredFeatures: ['timestamp-query']
});

const timingSets = Array.from({ length: 3 }, (_, i) =>
  device.createQuerySet({
    label: `Frame-Timing #${i}`,
    type: 'timestamp',
    count: 2
  })
);

console.log(timingSets.map((s) => s.label));

["Frame-Timing #0", "Frame-Timing #1", "Frame-Timing #2"]

// Wichtig · Fallstricke

Nur fürs Debugging: Das Label hat keinen Einfluss auf das Verhalten oder die Leistung des Query-Sets. Wie und ob es in Fehlermeldungen erscheint, hängt vom Browser ab.
Das Label bleibt auch nach querySet.destroy() lesbar. Daran erkennst du aber nicht, ob das Query-Set noch gültig ist.
Schreib keine sensiblen Daten ins Label, etwa Benutzernamen oder Tokens. Es kann in Logs, Fehlerberichten oder Entwicklerwerkzeugen auftauchen.
Kompatibilität: WebGPU steht nur in sicheren Kontexten (HTTPS) bereit, und die Browserunterstützung ist noch nicht vollständig. Prüf deshalb vorher, ob es navigator.gpu gibt. Timestamp-Queries brauchen zusätzlich das optionale Feature "timestamp-query".
Alle WebGPU-Objekte (GPUBuffer, GPUTexture, GPUCommandEncoder usw.) haben dieselbe label-Eigenschaft. Einheitliche Namenskonventionen machen das Debuggen spürbar leichter.

Siehe auch

GPUQuerySet GPUDevice.createQuerySet() GPUQuerySet.type GPUQuerySet.count GPUQuerySet.destroy() GPUDevice.pushErrorScope() GPUError