GPUBuffer.usage — Eigenschaft · JavaScript-Referenz

Signatur

GPUBuffer.usage

Beschreibung

Die Eigenschaft usage eines GPUBuffer gibt eine Zahl zurück, die sich aus den bitweise verknüpften GPUBufferUsage-Flags zusammensetzt. Diese Flags wurden beim Erzeugen des Puffers über GPUDevice.createBuffer() im Feld usage des Deskriptors angegeben. Sie legen fest, wofür der Puffer verwendet werden darf, z. B. als Vertex-, Index-, Uniform- oder Storage-Puffer, als Quelle bzw. Ziel von Kopiervorgängen oder zum Mappen für CPU-Lese- und Schreibzugriffe.

Verfügbare Flags sind u. a. MAP_READ (1), MAP_WRITE (2), COPY_SRC (4), COPY_DST (8), INDEX (16), VERTEX (32), UNIFORM (64), STORAGE (128), INDIRECT (256) und QUERY_RESOLVE (512). Ob ein Flag gesetzt ist, prüft man mit dem bitweisen UND-Operator: (buffer.usage & GPUBufferUsage.COPY_DST) !== 0.

Praktisch ist die Eigenschaft vor allem in generischem Code, etwa in Hilfsfunktionen, Ressourcen-Managern oder beim Debugging: Man kann vor einem Aufruf wie device.queue.writeBuffer() oder buffer.mapAsync() prüfen, ob der Puffer die nötige Nutzung erlaubt, statt einen Validierungsfehler zu riskieren.

Die Nutzung eines Puffers ist unveränderlich. Wird eine andere Nutzung benötigt, muss ein neuer Puffer erzeugt und der Inhalt gegebenenfalls per copyBufferToBuffer() übertragen werden.

Rückgabewert

Typ

number

Beschreibung

Eine Bitmaske (Ganzzahl) aus GPUBufferUsage-Flags, die exakt dem beim Erzeugen angegebenen Wert entspricht.

Beispiele

Puffer erzeugen und usage auslesen

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

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

console.log(vertexBuffer.usage);

40

Flags prüfen, bevor Daten geschrieben werden

const safeWrite = (device, buffer, data) => {
  if ((buffer.usage & GPUBufferUsage.COPY_DST) === 0) {
    throw new Error('Puffer erlaubt keine Schreibvorgänge (COPY_DST fehlt).');
  }
  device.queue.writeBuffer(buffer, 0, data);
};

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

safeWrite(device, uniformBuffer, new Float32Array([1, 0, 0, 1]));
console.log('Uniform-Daten geschrieben');

Uniform-Daten geschrieben

usage für Debug-Ausgabe in Flag-Namen umwandeln

const describeUsage = (usage) =>
  Object.entries({
    MAP_READ: GPUBufferUsage.MAP_READ,
    MAP_WRITE: GPUBufferUsage.MAP_WRITE,
    COPY_SRC: GPUBufferUsage.COPY_SRC,
    COPY_DST: GPUBufferUsage.COPY_DST,
    INDEX: GPUBufferUsage.INDEX,
    VERTEX: GPUBufferUsage.VERTEX,
    UNIFORM: GPUBufferUsage.UNIFORM,
    STORAGE: GPUBufferUsage.STORAGE,
    INDIRECT: GPUBufferUsage.INDIRECT,
    QUERY_RESOLVE: GPUBufferUsage.QUERY_RESOLVE,
  })
    .filter(([, flag]) => (usage & flag) !== 0)
    .map(([name]) => name);

const readback = device.createBuffer({
  size: 256,
  usage: GPUBufferUsage.MAP_READ | GPUBufferUsage.COPY_DST,
});

console.log(describeUsage(readback.usage));

["MAP_READ", "COPY_DST"]

// Wichtig · Fallstricke

Schreibgeschützt und unveränderlich: Eine Zuweisung an buffer.usage wird ignoriert (im Strict Mode TypeError). Die Nutzung legt man ausschließlich bei createBuffer() fest.
Kombinationsregeln: MAP_READ darf nur mit COPY_DST kombiniert werden, MAP_WRITE nur mit COPY_SRC. Andere Kombinationen erzeugen einen Validierungsfehler und einen ungültigen Puffer, sofern das Feature buffer-mapping-usage o. Ä. nicht verfügbar ist.
Bitprüfung richtig schreiben: Wegen der Operatorrangfolge immer klammern: (usage & FLAG) !== 0, nicht usage & FLAG !== 0.
Performance: Nur die wirklich benötigten Flags setzen – überflüssige Flags können den Treiber zu ungünstigerer Speicherplatzierung zwingen.
Kompatibilität: WebGPU ist nur in sicheren Kontexten verfügbar und noch nicht in allen Browsern bzw. auf allen Plattformen aktiviert. Vorher 'gpu' in navigator prüfen.

Siehe auch

GPUBuffer GPUDevice.createBuffer() GPUBuffer.size GPUBuffer.mapAsync() GPUQueue.writeBuffer() GPUBuffer.mapState GPUError.message