GPUDeviceLostInfo.reason — Eigenschaft · JavaScript-Referenz

Signatur

GPUDeviceLostInfo.reason

Beschreibung

Die schreibgeschützte Eigenschaft reason des Interfaces GPUDeviceLostInfo gibt an, warum ein logisches WebGPU-Gerät (GPUDevice) nicht mehr nutzbar ist. Ein GPUDeviceLostInfo-Objekt bekommt man nicht direkt, sondern als Auflösungswert des Promises GPUDevice.lost. Dieses Promise wird genau einmal erfüllt, sobald das Gerät verloren geht.

Der Wert ist ein String aus der Aufzählung GPUDeviceLostReason:

"destroyed" – Das Gerät wurde absichtlich über GPUDevice.destroy() zerstört. Das ist normalerweise gewollt, und die Anwendung sollte nicht automatisch ein neues Gerät anlegen.
"unknown" – Das Gerät ging aus einem anderen Grund verloren, z. B. durch einen Treiberabsturz, einen GPU-Reset, einen Timeout (TDR), zu hohen Speicherverbrauch oder weil der Browser Ressourcen zurückgefordert hat. In diesem Fall lohnt sich meist ein Versuch, über navigator.gpu.requestAdapter() und requestDevice() neu zu initialisieren.

Mit reason sollte die Programmlogik entscheiden, was als Nächstes passiert (z. B. neu starten oder nicht). Die Eigenschaft message ist dagegen eine menschenlesbare Meldung, deren Wortlaut vom Browser abhängt. Sie eignet sich für Logs und Fehlerberichte, aber nicht für Verzweigungen im Code.

Rückgabewert

Typ

"destroyed" | "unknown"

Beschreibung

Ein String aus der Aufzählung GPUDeviceLostReason, der den Grund für den Geräteverlust angibt.

Beispiele

Geräteverlust erkennen und protokollieren

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

device.lost.then((info) => {
  console.warn(`WebGPU-Gerät verloren – Grund: ${info.reason}`);
  console.warn(`Meldung: ${info.message}`);
});

// Absichtlich zerstören, um den Handler auszulösen
device.destroy();

WebGPU-Gerät verloren – Grund: destroyed Meldung: (browserabhängiger Text)

Automatische Neuinitialisierung nur bei unerwartetem Verlust

const initWebGPU = async () => {
  const adapter = await navigator.gpu?.requestAdapter();
  if (!adapter) throw new Error('WebGPU nicht verfügbar');
  const device = await adapter.requestDevice();

  device.lost.then(async ({ reason, message }) => {
    console.error(`Gerät verloren (${reason}): ${message}`);
    // Bei absichtlichem destroy() nichts tun
    if (reason !== 'destroyed') {
      await initWebGPU(); // Pipelines, Buffer usw. neu anlegen
    }
  });

  // Hier Canvas-Kontext konfigurieren, Pipelines erstellen ...
  return device;
};

const device = await initWebGPU();

Grund per switch auswerten und Nutzer informieren

const handleDeviceLoss = (info) => {
  switch (info.reason) {
    case 'destroyed':
      return 'Rendering wurde beendet.';
    case 'unknown':
    default:
      return 'Die Grafikkarte wurde zurückgesetzt. Die Szene wird neu geladen …';
  }
};

const adapter = await navigator.gpu.requestAdapter();
const device = await adapter.requestDevice();
const info = await device.lost;
document.querySelector('#status').textContent = handleDeviceLoss(info);

// Wichtig · Fallstricke

Mit einem default-Zweig absichern: Frühere Spezifikationsstände und Browserversionen lieferten statt "unknown" auch undefined. Ein default-Zweig bzw. die Prüfung reason !== "destroyed" fängt das und mögliche künftige Werte ab.
Nicht nach message verzweigen: Der Text ist nicht standardisiert und je nach Browser und Version verschieden.
Alle Ressourcen sind ungültig: Nach einem Verlust sind Buffer, Texturen, Pipelines und Bind-Groups des alten Geräts unbrauchbar. Bei einer Neuinitialisierung müssen sie auf dem neuen Gerät neu angelegt werden. Auch der Canvas-Kontext muss mit configure() neu konfiguriert werden.
Auch ein erfülltes requestDevice() kann ein verlorenes Gerät liefern: Dann ist device.lost sofort erfüllt. Den Handler also immer direkt nach dem Erstellen registrieren.
Browserunterstützung: WebGPU gibt es nur in sicheren Kontexten (HTTPS). Unterstützt wird es in Chromium-Browsern ab Version 113 (unter Linux teils nur mit Flag), in Firefox ab 141 (zunächst nur unter Windows) und in Safari ab 26. In Web Workern ist WebGPU ebenfalls verfügbar. Vor der Nutzung mit "gpu" in navigator prüfen, ob die API vorhanden ist.

Siehe auch

GPUDeviceLostInfo GPUDeviceLostInfo.message GPUDevice.lost GPUDevice.destroy() GPUAdapter.requestDevice() GPU.requestAdapter() NotRestoredReasons.reasons