GPUQuerySet.type — Eigenschaft · JavaScript-Referenz

Signatur

GPUQuerySet.type

Beschreibung

Die schreibgeschützte Eigenschaft type eines GPUQuerySet gibt den Abfragetyp zurück, der beim Erzeugen mit GPUDevice.createQuerySet() im Deskriptor festgelegt wurde. Der Wert lässt sich danach nicht mehr ändern.

Es gibt zwei mögliche Werte:

"occlusion" – Verdeckungsabfragen. Sie zählen, ob beim Zeichnen innerhalb eines Render-Pass Fragmente den Tiefen- und Stencil-Test bestehen. Das Ergebnis ist ungleich 0, wenn mindestens ein Sample sichtbar war. Solche Abfragen werden über occlusionQuerySet im Render-Pass-Deskriptor sowie mit beginOcclusionQuery()/endOcclusionQuery() genutzt.
"timestamp" – Zeitstempel-Abfragen. Sie schreiben GPU-Zeitstempel in Nanosekunden, typischerweise über timestampWrites am Anfang und Ende eines Render- oder Compute-Pass. Dafür muss das Gerät mit dem Feature "timestamp-query" angefordert worden sein.

Die Eigenschaft ist nützlich, wenn generischer Code (z. B. ein Profiler oder ein Debug-Werkzeug) mehrere Query-Sets bekommt und je nach Typ anders auswerten muss. Zusammen mit GPUQuerySet.count ergibt sich außerdem die Größe des Puffers, der für resolveQuerySet() gebraucht wird (8 Byte pro Abfrage).

Rückgabewert

Typ

"occlusion" | "timestamp"

Beschreibung

Ein String aus der Aufzählung GPUQueryType, der den beim Erzeugen festgelegten Abfragetyp angibt.

Beispiele

Typ eines Occlusion-Query-Sets auslesen

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

const querySet = device.createQuerySet({
  label: 'Sichtbarkeitstest',
  type: 'occlusion',
  count: 32,
});

console.log(querySet.type);  // Abfragetyp
console.log(querySet.count); // Anzahl der Abfragen

occlusion 32

Timestamp-Queries nur bei vorhandenem Feature anlegen

const adapter = await navigator.gpu.requestAdapter();
const canTimestamp = adapter.features.has('timestamp-query');

const device = await adapter.requestDevice({
  requiredFeatures: canTimestamp ? ['timestamp-query'] : [],
});

if (canTimestamp) {
  const timings = device.createQuerySet({ type: 'timestamp', count: 2 });
  console.log(`Query-Set vom Typ "${timings.type}" angelegt`);
} else {
  console.log('Zeitstempel-Abfragen werden nicht unterstützt');
}

Query-Set vom Typ "timestamp" angelegt

Generische Auswertung je nach Typ

// Wertet einen bereits gemappten Ergebnis-Puffer abhängig vom Query-Typ aus
const describeResults = (querySet, data /* BigUint64Array */) => {
  switch (querySet.type) {
    case 'occlusion': {
      const visible = [...data].filter((v) => v > 0n).length;
      return `${visible} von ${querySet.count} Objekten sichtbar`;
    }
    case 'timestamp': {
      const ns = data[1] - data[0];
      return `GPU-Dauer: ${(Number(ns) / 1e6).toFixed(3)} ms`;
    }
    default:
      return `Unbekannter Typ: ${querySet.type}`;
  }
};

// Beispielaufruf mit simulierten Daten
const fakeSet = { type: 'timestamp', count: 2 };
console.log(describeResults(fakeSet, new BigUint64Array([1000000n, 3500000n])));

GPU-Dauer: 2.500 ms

// Wichtig · Fallstricke

Schreibgeschützt: Wenn man type etwas zuweist, passiert nichts (im Strict Mode gibt es einen TypeError). Für einen anderen Typ muss ein neues Query-Set erzeugt werden.
Feature-Pflicht: createQuerySet({ type: 'timestamp' }) ohne aktiviertes Feature "timestamp-query" erzeugt einen Validierungsfehler. Man bekommt dann ein ungültiges Objekt, und die Methoden, die es nutzen, schlagen fehl.
Datenschutz: Browser können die Genauigkeit von Zeitstempeln absichtlich verringern (z. B. auf 100 µs gerundet), um Timing-Angriffe zu erschweren. Die Werte eignen sich deshalb nur für grobes Profiling.
Ein Occlusion-Query-Set kann nur als occlusionQuerySet eines Render-Pass verwendet werden, nicht in Compute-Passes.
Kompatibilität: WebGPU gibt es nur in sicheren Kontexten (HTTPS). Chromium-Browser unterstützen es seit Version 113, Firefox und Safari erst in neueren Versionen und teilweise nur auf bestimmten Plattformen. Vorher mit 'gpu' in navigator prüfen.

Siehe auch

GPUQuerySet GPUQuerySet.count GPUQuerySet.destroy() GPUDevice.createQuerySet() GPUCommandEncoder.resolveQuerySet() GPURenderPassEncoder.beginOcclusionQuery() GPUQuerySet.label