GPUDevice.queue — Eigenschaft · JavaScript-Referenz

Signatur

GPUDevice.queue

Beschreibung

Die Eigenschaft queue eines GPUDevice gibt das GPUQueue-Objekt zurück, über das die gesamte Arbeit an die GPU übergeben wird. Jedes Gerät hat genau eine solche Standard-Warteschlange; sie wird beim Aufruf von adapter.requestDevice() angelegt und bleibt für die gesamte Lebensdauer des Geräts dieselbe Instanz.

Typische Aufgaben über die Queue sind:

queue.submit([commandBuffer]) – fertig aufgezeichnete Befehlspuffer (aus GPUCommandEncoder.finish()) zur Ausführung übergeben.
queue.writeBuffer() – Daten von der CPU direkt in einen GPUBuffer kopieren, z. B. Uniforms oder Vertexdaten.
queue.writeTexture() und queue.copyExternalImageToTexture() – Pixeldaten bzw. Bilder, Canvas-Inhalte oder Videoframes in Texturen laden.
queue.onSubmittedWorkDone() – ein Promise erhalten, das erfüllt wird, sobald alle bisher übergebene Arbeit auf der GPU abgeschlossen ist.

Befehle werden in der Reihenfolge ausgeführt, in der sie an die Queue übergeben werden. writeBuffer()-Aufrufe sind dabei relativ zu submit()-Aufrufen geordnet: Daten, die vor einem submit() geschrieben werden, sind für die Befehle dieses Submits sichtbar.

Rückgabewert

Typ

GPUQueue

Beschreibung

Die primäre (und derzeit einzige) GPUQueue des Geräts. Der Wert ist schreibgeschützt und liefert bei jedem Zugriff dieselbe Instanz.

Beispiele

Queue abrufen und einen leeren Render-Pass übergeben

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

  const canvas = document.querySelector('canvas');
  const context = canvas.getContext('webgpu');
  const format = navigator.gpu.getPreferredCanvasFormat();
  context.configure({ device, format });

  const encoder = device.createCommandEncoder();
  const pass = encoder.beginRenderPass({
    colorAttachments: [{
      view: context.getCurrentTexture().createView(),
      clearValue: { r: 0.1, g: 0.2, b: 0.4, a: 1 },
      loadOp: 'clear',
      storeOp: 'store'
    }]
  });
  pass.end();

  // Befehlspuffer über die Queue des Geräts ausführen
  device.queue.submit([encoder.finish()]);
  console.log(device.queue instanceof GPUQueue);
};

init();

true

Uniform-Daten per writeBuffer aktualisieren

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

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

const frame = (time) => {
  // Zeit und Auflösung als vier Floats in den Puffer schreiben
  const data = new Float32Array([time / 1000, 800, 600, 0]);
  device.queue.writeBuffer(uniformBuffer, 0, data);
  // ... hier Render-Pass aufzeichnen und device.queue.submit(...) aufrufen
  requestAnimationFrame(frame);
};

requestAnimationFrame(frame);

Auf Abschluss der GPU-Arbeit warten

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

const buffer = device.createBuffer({
  size: 4 * 1024,
  usage: GPUBufferUsage.STORAGE | GPUBufferUsage.COPY_DST
});
queue.writeBuffer(buffer, 0, new Uint32Array(1024).fill(7));

const start = performance.now();
await queue.onSubmittedWorkDone();
console.log(`GPU fertig nach ${(performance.now() - start).toFixed(1)} ms`);

GPU fertig nach 0.8 ms

// Wichtig · Fallstricke

Nur eine Queue: Die WebGPU-Spezifikation sieht derzeit nur die Standard-Queue vor; mehrere Queues (z. B. separate Compute-Queues) gibt es nicht.
Fehler sind asynchron: Ungültige submit()- oder writeBuffer()-Aufrufe werfen keine Ausnahme, sondern erzeugen Validierungsfehler, die man über device.pushErrorScope()/popErrorScope() oder das Ereignis uncapturederror abfängt.
Puffer-Nutzung: Für writeBuffer() muss der Zielpuffer mit GPUBufferUsage.COPY_DST erstellt worden sein; Offset und Größe müssen Vielfache von 4 sein.
Befehlspuffer nur einmal verwendbar: Ein bereits übergebener GPUCommandBuffer wird ungültig und darf nicht erneut an submit() übergeben werden.
Geräteverlust: Nach einem Geräteverlust (device.lost) ist auch die Queue nicht mehr nutzbar – man muss ein neues Gerät anfordern und von diesem queue erneut lesen.
Kompatibilität: WebGPU ist nur in sicheren Kontexten verfügbar und wird noch nicht überall unterstützt; vorher per navigator.gpu auf Unterstützung prüfen. Auch in Web Workers verfügbar.

Siehe auch

GPUQueue GPUQueue.submit() GPUQueue.writeBuffer() GPUQueue.onSubmittedWorkDone() GPUDevice GPUAdapter.requestDevice() GPUShaderModule.label