GPUDeviceLostInfo — Schnittstelle · JavaScript-Referenz

Signatur

interface GPUDeviceLostInfo

Beschreibung

GPUDeviceLostInfo ist ein Interface der WebGPU-API. Instanzen davon erzeugt man nicht selbst, und es gibt keinen Konstruktor. Man bekommt sie ausschließlich als Erfüllungswert des Promise GPUDevice.lost. Dieses Promise wird erfüllt, sobald das logische Gerät nicht mehr benutzbar ist.

Ein Gerät kann aus verschiedenen Gründen verloren gehen:

Es wurde ausdrücklich mit device.destroy() zerstört.
Der Grafiktreiber ist abgestürzt oder wurde aktualisiert.
Das Betriebssystem hat die GPU zurückgesetzt (TDR).
Eine externe GPU wurde abgezogen.
Der Browser hat Ressourcen freigegeben, zum Beispiel für einen Tab im Hintergrund.

Das Interface hat zwei schreibgeschützte Eigenschaften:

reason: entweder "destroyed" (absichtlich mit destroy() zerstört) oder "unknown" (unerwarteter Verlust).
message: ein Text, den der Browser festlegt. Er dient nur der Fehlersuche. Sein Inhalt ist nicht standardisiert und kann sich jederzeit ändern.

Robuste WebGPU-Anwendungen sollten device.lost immer überwachen. Bei reason === "unknown" fordert man mit navigator.gpu.requestAdapter() einen neuen Adapter und danach ein neues Gerät an. Anschließend baut man alle GPU-Ressourcen (Buffer, Texturen, Pipelines) neu auf. Die alten Objekte lassen sich nicht wiederverwenden.

Parameter

Name	Typ	Default	Beschreibung
$reason	"destroyed" \| "unknown"		Schreibgeschützte Eigenschaft: der Grund für den Geräteverlust. `"destroyed"` bedeutet, dass `GPUDevice.destroy()` aufgerufen wurde. `"unknown"` steht für jeden anderen, unerwarteten Verlust.
$message	string		Schreibgeschützte Eigenschaft: ein Text, den der Browser festlegt, mit Details zum Verlust. Nur für Logs und Fehlersuche gedacht. Man sollte ihn nicht auswerten oder als Programmlogik verwenden.

Rückgabewert

Typ

GPUDeviceLostInfo

Beschreibung

Das Objekt ist der Erfüllungswert von GPUDevice.lost (Promise<GPUDeviceLostInfo>) und enthält reason und message.

Beispiele

Grund des Geräteverlusts protokollieren

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

device.lost.then((info) => {
  // info ist ein GPUDeviceLostInfo-Objekt
  console.warn(`WebGPU-Gerät verloren: ${info.reason}`);
  if (info.message) {
    console.warn(`Details: ${info.message}`);
  }
});

// Absichtliches Zerstören erfüllt das Promise mit reason "destroyed"
device.destroy();

WebGPU-Gerät verloren: destroyed

Automatische Wiederherstellung nach unerwartetem Verlust

let device;

const initWebGPU = async () => {
  const adapter = await navigator.gpu?.requestAdapter();
  if (!adapter) {
    console.error('WebGPU nicht verfügbar');
    return;
  }
  device = await adapter.requestDevice();

  device.lost.then(async (info) => {
    console.error(`Gerät verloren (${info.reason}): ${info.message}`);
    // Nur bei unerwartetem Verlust neu initialisieren
    if (info.reason !== 'destroyed') {
      await initWebGPU();
    }
  });

  // Hier alle Ressourcen (Buffer, Pipelines, Texturen) neu anlegen
  console.log('WebGPU bereit');
};

await initWebGPU();

WebGPU bereit

Mit async/await auf den Verlust warten

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

const watchDevice = async (dev) => {
  const { reason, message } = await dev.lost;
  document.body.dataset.gpuState = 'lost';
  console.log({ reason, message });
};

watchDevice(device);
setTimeout(() => device.destroy(), 1000);

{ reason: "destroyed", message: "..." }

// Wichtig · Fallstricke

Kein Konstruktor: Mit new GPUDeviceLostInfo() kann man keine Instanz erzeugen. Ein solcher Aufruf wirft einen TypeError.
device.lost wird nie abgelehnt. Das Promise wird nur erfüllt. Ein .catch() fängt also keinen Geräteverlust ab.
Auch requestDevice() kann ein Gerät liefern, das bereits verloren ist, zum Beispiel wenn der Adapter nicht mehr gültig ist. Den Handler für lost sollte man deshalb direkt nach der Erstellung registrieren.
Ein verlorener GPUAdapter lässt sich nicht wiederverwenden. Für die Wiederherstellung muss man immer zuerst navigator.gpu.requestAdapter() neu aufrufen.
Inhalt und Sprache von message legt jeder Browser selbst fest. Man sollte den Text nicht auswerten.
Früher gab es für reason den Wert undefined. Heute ist "unknown" standardisiert. Ältere Chrome-Versionen können abweichen.
Kompatibilität: WebGPU ist nur in sicheren Kontexten verfügbar (HTTPS, localhost). Chromium unterstützt es seit Version 113, zunächst unter Windows, macOS und ChromeOS. Safari und Firefox kamen später hinzu. Vorher sollte man die Unterstützung mit 'gpu' in navigator prüfen.

Siehe auch

GPUDevice GPUDevice.lost GPUDevice.prototype.destroy() GPUAdapter.prototype.requestDevice() GPU.prototype.requestAdapter() GPUUncapturedErrorEvent