GPUBuffer.size — Eigenschaft · JavaScript-Referenz

Signatur

GPUBuffer.size

Beschreibung

Die Eigenschaft size des GPUBuffer-Interfaces gibt die Länge des GPU-Puffers in Bytes zurück. Der Wert entspricht genau dem size-Feld, das beim Erzeugen über GPUDevice.createBuffer() im Deskriptor angegeben wurde, und ändert sich während der Lebensdauer des Puffers nicht.

Nützlich ist size vor allem dann, wenn ein Puffer an anderer Stelle im Code weiterverarbeitet wird als dort, wo er erzeugt wurde: etwa um einen passenden Lesepuffer (Staging-Puffer) gleicher Größe anzulegen, um bei copyBufferToBuffer() die Anzahl zu kopierender Bytes zu bestimmen, um bei mapAsync() den ganzen Bereich abzubilden oder um vor GPUQueue.writeBuffer() zu prüfen, ob die Daten überhaupt hineinpassen.

Zusammen mit GPUBuffer.usage und GPUBuffer.mapState erlaubt size eine vollständige Beschreibung eines vorhandenen Puffers, ohne dass der ursprüngliche Deskriptor mitgeführt werden muss – praktisch für Hilfsfunktionen, Debug-Ausgaben oder Speicherstatistiken.

Rückgabewert

Typ

number

Beschreibung

Eine ganze Zahl (intern GPUSize64) mit der Größe des Puffers in Bytes. Der Wert bleibt auch nach destroy() lesbar.

Beispiele

Puffergröße nach dem Erzeugen auslesen

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

const vertexBuffer = device.createBuffer({
  label: 'Vertices',
  size: 1024,
  usage: GPUBufferUsage.VERTEX | GPUBufferUsage.COPY_DST,
});

console.log(`${vertexBuffer.label}: ${vertexBuffer.size} Bytes`);

Vertices: 1024 Bytes

Staging-Puffer passender Größe anlegen und Ergebnis zurücklesen

// Liest den Inhalt eines GPU-Puffers (mit COPY_SRC) auf die CPU zurück
const readBack = async (device, srcBuffer) => {
  const staging = device.createBuffer({
    size: srcBuffer.size, // gleiche Größe wie die Quelle
    usage: GPUBufferUsage.MAP_READ | GPUBufferUsage.COPY_DST,
  });

  const encoder = device.createCommandEncoder();
  encoder.copyBufferToBuffer(srcBuffer, 0, staging, 0, srcBuffer.size);
  device.queue.submit([encoder.finish()]);

  await staging.mapAsync(GPUMapMode.READ, 0, staging.size);
  const data = new Float32Array(staging.getMappedRange().slice(0));
  staging.unmap();
  staging.destroy();
  return data;
};

const result = await readBack(device, outputBuffer);
console.log(result.length, 'Werte gelesen');

z. B. 256 Werte gelesen (bei einem 1024-Byte-Puffer)

Größe vor writeBuffer() prüfen

const safeWrite = (device, buffer, typedArray, offset = 0) => {
  if (offset + typedArray.byteLength > buffer.size) {
    throw new RangeError(
      `Daten (${typedArray.byteLength} B) passen nicht in Puffer (${buffer.size} B)`
    );
  }
  device.queue.writeBuffer(buffer, offset, typedArray);
};

const uniforms = device.createBuffer({
  size: 64,
  usage: GPUBufferUsage.UNIFORM | GPUBufferUsage.COPY_DST,
});

safeWrite(device, uniforms, new Float32Array(16)); // 64 Bytes – ok
try {
  safeWrite(device, uniforms, new Float32Array(32)); // 128 Bytes – zu groß
} catch (e) {
  console.error(e.message);
}

Daten (128 B) passen nicht in Puffer (64 B)

// Wichtig · Fallstricke

Schreibgeschützt: Eine Zuweisung an size wird ignoriert (im Strict Mode TypeError). Einen Puffer kann man nicht nachträglich vergrößern, man muss einen neuen erzeugen und den Inhalt umkopieren.
Ausrichtung: Wird mappedAtCreation: true verwendet, muss size ein Vielfaches von 4 sein. Auch copyBufferToBuffer() und writeBuffer() verlangen Größen und Offsets, die Vielfache von 4 sind. Uniform-Puffer unterliegen zusätzlich den Layout-Regeln von WGSL (z. B. 16-Byte-Ausrichtung bei vec3/Strukturen).
Grenzen: Die maximale Größe begrenzt device.limits.maxBufferSize. Gebundene Bereiche begrenzen außerdem maxUniformBufferBindingSize und maxStorageBufferBindingSize. Bei Überschreitung schlägt createBuffer() mit einem Validierungsfehler fehl.
Ungültige Puffer: Auch wenn die Erzeugung wegen eines Validierungsfehlers scheitert, liefert size den angeforderten Wert. Die Größe allein zeigt also nicht, dass der Puffer gültig ist; Fehler fängt man mit device.pushErrorScope()/popErrorScope() ab.
Kompatibilität: WebGPU steht nur in sicheren Kontexten zur Verfügung und ist noch nicht in allen Browsern bzw. auf allen Plattformen aktiviert. Vorher mit navigator.gpu prüfen. Die Eigenschaft ist auch in Web Workern verfügbar.

Siehe auch

GPUBuffer GPUBuffer.usage GPUBuffer.mapState GPUBuffer.mapAsync() GPUDevice.createBuffer() GPUQueue.writeBuffer() FontFaceSet.size