GPUAdapter.requestDevice() — Methode · JavaScript-Referenz

Signatur

GPUAdapter.prototype.requestDevice(descriptor)

Beschreibung

requestDevice() ist der zweite Schritt beim Einrichten von WebGPU: Zuerst liefert navigator.gpu.requestAdapter() einen GPUAdapter, der eine physische GPU bzw. einen Treiber-Zugang darstellt. Danach erzeugt requestDevice() daraus ein logisches Gerät (GPUDevice). Über dieses Gerät legst du alle GPU-Ressourcen an (createBuffer(), createTexture(), createRenderPipeline() …) und schickst Befehle über device.queue ab.

Über das optionale Deskriptor-Objekt forderst du optionale Features (z. B. "texture-compression-bc", "shader-f16", "timestamp-query") und höhere Limits (z. B. maxBufferSize, maxStorageBufferBindingSize) an. Ohne Angabe bekommst du nur die Standard-Limits, die WebGPU überall garantiert. Du kannst nur anfordern, was der Adapter in adapter.features und adapter.limits tatsächlich anbietet – sonst wird das Promise mit einem TypeError bzw. OperationError abgewiesen.

Ein Adapter kann nur einmal ein Gerät liefern. Danach gilt er als „verbraucht“; weitere Aufrufe liefern ein Gerät, das sofort verloren ist. Wenn das Gerät später verloren geht (Treiber-Absturz, device.destroy(), GPU-Wechsel), musst du einen neuen Adapter anfordern. Das Promise device.lost meldet diesen Fall.

Parameter

Name	Typ	Default	Beschreibung
$descriptor	GPUDeviceDescriptor	{}	Optionales Konfigurationsobjekt mit den unten genannten Eigenschaften.
$descriptor.requiredFeatures	Iterable<GPUFeatureName>	[]	Features, die das Gerät unbedingt haben soll, z. B. `["shader-f16"]`. Jeder Eintrag muss in `adapter.features` enthalten sein, sonst wird ein `TypeError` ausgelöst.
$descriptor.requiredLimits	Record<string, number>	{}	Gewünschte Limits, z. B. `{ maxBufferSize: 1 << 30 }`. Die Werte dürfen die Werte in `adapter.limits` nicht überschreiten, sonst wird das Promise mit einem `OperationError` abgewiesen.
$descriptor.defaultQueue	GPUQueueDescriptor	{}	Deskriptor für die Standard-Queue; derzeit praktisch nur `label`.
$descriptor.label	string	""	Name des Geräts zur Fehlersuche; taucht in Fehlermeldungen und Debug-Werkzeugen auf.

Rückgabewert

Typ

Promise<GPUDevice>

Beschreibung

Ein Promise, das mit einem GPUDevice erfüllt wird. Es wird mit TypeError abgewiesen, wenn ein nicht unterstütztes Feature angefordert wird, und mit OperationError, wenn ein Limit zu hoch ist oder ein unbekannter Limit-Name angegeben wird. Ist der Adapter schon verbraucht, wird zwar ein Gerät geliefert, das aber sofort verloren ist.

Beispiele

Grundlegende Initialisierung mit Fehlerbehandlung

const initWebGPU = async () => {
  if (!navigator.gpu) {
    throw new Error('WebGPU wird von diesem Browser nicht unterstützt.');
  }
  const adapter = await navigator.gpu.requestAdapter();
  if (!adapter) {
    throw new Error('Kein passender GPU-Adapter gefunden.');
  }
  const device = await adapter.requestDevice({ label: 'Haupt-Gerät' });
  console.log('Gerät bereit:', device.label);
  return device;
};

const device = await initWebGPU();

Gerät bereit: Haupt-Gerät

Optionale Features und höhere Limits nur bei Verfügbarkeit anfordern

const adapter = await navigator.gpu.requestAdapter({ powerPreference: 'high-performance' });

// Nur Features anfordern, die der Adapter wirklich kann
const wanted = ['shader-f16', 'timestamp-query'];
const requiredFeatures = wanted.filter((f) => adapter.features.has(f));

// 1 GiB Puffer wünschen, aber nie mehr als der Adapter erlaubt
const requiredLimits = {
  maxBufferSize: Math.min(1024 ** 3, adapter.limits.maxBufferSize),
  maxStorageBufferBindingSize: adapter.limits.maxStorageBufferBindingSize,
};

const device = await adapter.requestDevice({ requiredFeatures, requiredLimits });

console.log('Features:', [...device.features]);
console.log('maxBufferSize:', device.limits.maxBufferSize);

Features: ['shader-f16', 'timestamp-query'] maxBufferSize: 1073741824

Geräteverlust erkennen und neu initialisieren

const startRenderer = async () => {
  const adapter = await navigator.gpu.requestAdapter();
  const device = await adapter.requestDevice();

  // Unerwartete Validierungsfehler protokollieren
  device.addEventListener('uncapturederror', (event) => {
    console.error('WebGPU-Fehler:', event.error.message);
  });

  device.lost.then((info) => {
    console.warn(`Gerät verloren (${info.reason}): ${info.message}`);
    // Bei 'destroyed' wurde bewusst device.destroy() aufgerufen
    if (info.reason !== 'destroyed') {
      startRenderer(); // neuer Adapter + neues Gerät
    }
  });

  return device;
};

await startRenderer();

// Wichtig · Fallstricke

Adapter nur einmal verwendbar: Nach einem erfolgreichen requestDevice() ist der Adapter verbraucht. Nach einem Geräteverlust immer mit navigator.gpu.requestAdapter() neu beginnen, statt den alten Adapter wiederzuverwenden.
Nicht blind anfordern: Features und Limits vorher mit adapter.features.has() und adapter.limits prüfen – sonst schlägt das Promise mit TypeError/OperationError fehl.
Nicht mehr anfordern als nötig: Wer hohe Limits verlangt, schränkt die Zahl der Geräte ein, auf denen die Anwendung läuft. Außerdem lassen sich Nutzer über die angebotenen Features leichter wiedererkennen (Fingerprinting).
Fehler kommen oft nicht als Ausnahme: Validierungsfehler späterer Aufrufe landen im Event uncapturederror bzw. in pushErrorScope()/popErrorScope(), nicht im catch-Block.
Kompatibilität: WebGPU steht nur in sicheren Kontexten (HTTPS, localhost) und in neueren Browsern bereit. Chrome/Edge ab 113 (Linux/Android teilweise später), Safari ab 26, Firefox ab 141 zunächst nur unter Windows. Immer auf navigator.gpu prüfen und eine Alternative (z. B. WebGL) vorsehen. Auch in Web Workern verfügbar.

Siehe auch

GPUAdapter.requestAdapterInfo() Bluetooth.requestDevice() HID.requestDevice() USB.requestDevice() Window.requestResize()