GPUQuerySet.count — Eigenschaft · JavaScript-Referenz

Signatur

GPUQuerySet.count

Beschreibung

Die schreibgeschützte Eigenschaft count der Schnittstelle GPUQuerySet gibt die Anzahl der Abfrage-Slots zurück, die beim Erzeugen des Sets über GPUDevice.createQuerySet() im Deskriptor-Feld count festgelegt wurde. Der Wert ändert sich über die gesamte Lebensdauer des Objekts nicht.

Nützlich ist count vor allem dann, wenn Code ein Query-Set nicht selbst erzeugt hat, es aber weiterverarbeiten muss, etwa in einer Hilfsfunktion, die Abfrageergebnisse auflöst. Mit count lassen sich die passende Puffergröße für GPUCommandEncoder.resolveQuerySet() berechnen (jedes Ergebnis ist ein 64-Bit-Wert, also count * 8 Bytes) und gültige Indizes für writeTimestamp, timestampWrites oder beginOcclusionQuery() prüfen.

Gültige Abfrage-Indizes liegen im Bereich 0 bis count - 1. Ein Zugriff außerhalb dieses Bereichs erzeugt einen Validierungsfehler auf dem GPU-Gerät, aber keine JavaScript-Ausnahme.

Rückgabewert

Typ

number

Beschreibung

Eine ganze Zahl (GPUSize32), die die Anzahl der Abfragen im Set angibt. Das Maximum liegt bei 4096.

Beispiele

Query-Set erzeugen und count auslesen

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

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

console.log(occlusionSet.type);  // Typ des Sets
console.log(occlusionSet.count); // Anzahl der Abfragen

occlusion 32

Passenden Resolve-Puffer aus count berechnen

// Hilfsfunktion: löst alle Abfragen eines beliebigen Sets in einen Puffer auf
const resolveAll = (device, encoder, querySet) => {
  const byteSize = querySet.count * 8; // 8 Bytes (64 Bit) pro Ergebnis
  const resolveBuffer = device.createBuffer({
    size: byteSize,
    usage: GPUBufferUsage.QUERY_RESOLVE | GPUBufferUsage.COPY_SRC
  });
  encoder.resolveQuerySet(querySet, 0, querySet.count, resolveBuffer, 0);
  return resolveBuffer;
};

const adapter = await navigator.gpu.requestAdapter();
const device = await adapter.requestDevice();
const querySet = device.createQuerySet({ type: 'occlusion', count: 4 });
const encoder = device.createCommandEncoder();
const buffer = resolveAll(device, encoder, querySet);
console.log(buffer.size);

32

Zeitstempel-Indizes vor der Nutzung prüfen

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

const timestamps = device.createQuerySet({ type: 'timestamp', count: 2 });

const makeTimestampWrites = (querySet, begin, end) => {
  if (end >= querySet.count) {
    throw new RangeError(`Index ${end} außerhalb von 0..${querySet.count - 1}`);
  }
  return { querySet, beginningOfPassWriteIndex: begin, endOfPassWriteIndex: end };
};

const encoder = device.createCommandEncoder();
const pass = encoder.beginComputePass({
  timestampWrites: makeTimestampWrites(timestamps, 0, 1)
});
pass.end();
device.queue.submit([encoder.finish()]);
console.log('Zeitstempel-Slots:', timestamps.count);

Zeitstempel-Slots: 2

// Wichtig · Fallstricke

Schreibgeschützt: Zuweisungen an count werden im nicht-strikten Modus stillschweigend ignoriert und lösen im strikten Modus einen TypeError aus. Für eine andere Größe musst du ein neues Set mit createQuerySet() anlegen.
Nach destroy(): count liefert weiterhin den ursprünglichen Wert, obwohl das Set nicht mehr verwendet werden kann.
Grenzen: count darf beim Erzeugen höchstens 4096 sein. Ein größerer Wert führt zu einem Validierungsfehler, und das Set wird ungültig.
Puffer-Ausrichtung: Bei resolveQuerySet() muss der Ziel-Offset ein Vielfaches von 256 sein. Die Puffergröße muss mindestens offset + queryCount * 8 Bytes betragen.
Kompatibilität: WebGPU steht nur in sicheren Kontexten zur Verfügung und wird noch nicht von allen Browsern und Plattformen unterstützt. Prüfe die Unterstützung vorher mit navigator.gpu. Zeitstempel-Abfragen benötigen zusätzlich das Feature timestamp-query.

Siehe auch

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