Signatur
Beschreibung
Die Eigenschaft message der Schnittstelle GPUDeviceLostInfo enthält einen Text, der beschreibt, warum ein WebGPU-Gerät (GPUDevice) verloren gegangen ist. An das GPUDeviceLostInfo-Objekt kommt man über das Promise GPUDevice.lost: Es wird erfüllt, sobald das Gerät nicht mehr nutzbar ist.
Ein Gerät kann aus verschiedenen Gründen verloren gehen: Der Code ruft ausdrücklich device.destroy() auf, der Grafiktreiber stürzt ab oder wird aktualisiert, das System setzt die GPU nach einem Timeout zurück (TDR), eine externe GPU wird abgesteckt oder der Browser gibt Ressourcen frei. Die Eigenschaft message liefert dazu Details. Die maschinenlesbare Einordnung übernimmt dagegen reason.
Wichtig: Inhalt und Formulierung von message hängen vom Browser ab und sind nicht standardisiert. Sie können sich zwischen Versionen ändern und sind oft leer. Die Nachricht eignet sich zum Protokollieren, für Fehlerberichte und für Entwickler-Konsolen. Für Programmlogik (z. B. „Gerät neu anfordern oder nicht?“) sollte man immer reason auswerten.
Rückgabewert
Beispiele
Geräteverlust protokollieren
const initGPU = async () => {
if (!navigator.gpu) throw new Error('WebGPU wird nicht unterstützt.');
const adapter = await navigator.gpu.requestAdapter();
if (!adapter) throw new Error('Kein GPU-Adapter gefunden.');
const device = await adapter.requestDevice();
device.lost.then((info) => {
console.error(`WebGPU-Gerät verloren (reason: ${info.reason}): ${info.message}`);
});
return device;
};
const device = await initGPU();
device.destroy(); // löst den Geräteverlust bewusst ausAutomatisch neu initialisieren – message nur für das Protokoll
const startRenderer = async () => {
const adapter = await navigator.gpu?.requestAdapter();
if (!adapter) {
console.warn('WebGPU nicht verfügbar.');
return;
}
const device = await adapter.requestDevice();
device.lost.then(async ({ reason, message }) => {
// Entscheidung anhand von reason, NICHT anhand von message
if (reason === 'destroyed') {
console.info('Gerät absichtlich zerstört.');
return;
}
console.warn('Unerwarteter Geräteverlust:', message || '(keine Details)');
await startRenderer(); // Neuen Adapter + neues Gerät anfordern
});
// ... Pipelines, Puffer und Texturen hier anlegen ...
return device;
};
await startRenderer();Fehlerbericht an einen Server senden
const reportDeviceLoss = (info) => {
const payload = {
reason: info.reason,
message: info.message.slice(0, 500), // Länge begrenzen
userAgent: navigator.userAgent,
time: new Date().toISOString(),
};
navigator.sendBeacon('/api/gpu-errors', JSON.stringify(payload));
};
const adapter = await navigator.gpu.requestAdapter();
const device = await adapter.requestDevice();
device.lost.then(reportDeviceLoss);// Wichtig · Fallstricke
- Nicht auswerten: Der Text ist nicht standardisiert und kann je nach Browser, Version, Betriebssystem oder Treiber anders lauten oder leer sein. Code wie
if (info.message.includes('...'))ist fehleranfällig. Nutzen Sie stattdesseninfo.reason("destroyed"oder"unknown"). - Lost-Handler früh registrieren: Hängen Sie den Handler direkt nach
requestDevice()andevice.lost. Das Promise wird nur einmal erfüllt; ein verlorenes Gerät lässt sich nicht wiederbeleben. Man muss über einen neuen Adapter ein neues Gerät anfordern und alle Ressourcen neu anlegen. - Auch requestDevice() kann ein bereits verlorenes Gerät liefern, etwa wenn der Adapter schon verbraucht ist. Dann wird
lostsofort erfüllt, undmessageenthält oft den Grund. - Datenschutz: Die Nachricht kann Details zu Treiber oder Hardware enthalten. Zeigen Sie sie Endnutzern nicht ungefiltert an und kürzen Sie sie vor dem Senden an einen Server.
- Kompatibilität: WebGPU ist nur in sicheren Kontexten (HTTPS) verfügbar und noch nicht in allen Browsern bzw. auf allen Plattformen aktiviert. Prüfen Sie vorher mit
if (navigator.gpu). Auch in Web Workern verfügbar.