GPUDevice.popErrorScope() — Methode · JavaScript-Referenz

Signatur

GPUDevice.prototype.popErrorScope()

Beschreibung

Mit popErrorScope() schließt du einen Fehlerbereich, den du vorher mit GPUDevice.pushErrorScope() geöffnet hast. Alle WebGPU-Aufrufe zwischen pushErrorScope() und popErrorScope() werden überwacht. Tritt dabei ein Fehler auf, dessen Typ zum Filter des Bereichs passt ("validation", "out-of-memory" oder "internal"), wird er im Bereich festgehalten und nicht als uncapturederror-Ereignis weitergereicht.

Die Methode gibt ein Promise zurück. Es wird mit dem ersten erfassten Fehler (GPUValidationError, GPUOutOfMemoryError oder GPUInternalError) erfüllt, oder mit null, wenn kein passender Fehler aufgetreten ist. Weil die GPU asynchron arbeitet, steht das Ergebnis erst fest, wenn alle Operationen im Bereich von der Implementierung geprüft wurden.

Fehlerbereiche lassen sich verschachteln und bilden einen Stapel (LIFO). Ein Fehler landet im innersten Bereich mit passendem Filter. Passt kein Bereich, wird er an den nächstäußeren weitergegeben und am Ende als uncapturederror auf dem GPUDevice ausgelöst. Typische Einsatzfälle sind die Prüfung einzelner Ressourcen-Erstellungen (z. B. Shader-Module, Pipelines, große Puffer), das Abfangen von Speicherknappheit und gezieltes Debugging.

Rückgabewert

Typ

Promise<GPUError | null>

Beschreibung

Ein Promise, das mit dem ersten erfassten GPUError (bzw. einer Unterklasse wie GPUValidationError, GPUOutOfMemoryError oder GPUInternalError) oder mit null erfüllt wird, falls kein Fehler aufgetreten ist. Ist der Stapel leer, wird das Promise mit einer OperationError-DOMException abgelehnt.

Beispiele

Validierungsfehler beim Erstellen eines Shader-Moduls abfangen

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

device.pushErrorScope('validation');

// Absichtlich fehlerhafter WGSL-Code
const module = device.createShaderModule({
  code: '@vertex fn main() -> @builtin(position) vec4f { return 1.0; }'
});

const error = await device.popErrorScope();
if (error) {
  console.error('Shader ungültig:', error.message);
} else {
  console.log('Shader-Modul erfolgreich erstellt');
}

Shader ungültig: ... (implementierungsabhängige Fehlermeldung)

Speicherknappheit bei großen Puffern erkennen

const createBufferSafely = async (device, size) => {
  device.pushErrorScope('out-of-memory');
  const buffer = device.createBuffer({
    size,
    usage: GPUBufferUsage.STORAGE | GPUBufferUsage.COPY_DST
  });
  const error = await device.popErrorScope();
  if (error) {
    buffer.destroy();
    console.warn(`Kein Speicher für ${size} Bytes:`, error.message);
    return null;
  }
  return buffer;
};

const adapter = await navigator.gpu.requestAdapter();
const device = await adapter.requestDevice();
const buf = await createBufferSafely(device, 256 * 1024 * 1024);
console.log(buf ? 'Puffer angelegt' : 'Fallback auf kleinere Auflösung');

Puffer angelegt

Verschachtelte Fehlerbereiche

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

device.pushErrorScope('validation');     // äußerer Bereich
device.pushErrorScope('out-of-memory');  // innerer Bereich

// Ungültige Größe: Validierungsfehler, kein OOM-Fehler
device.createBuffer({ size: 4, usage: 0 });

const oomError = await device.popErrorScope();        // innerer
const validationError = await device.popErrorScope(); // äußerer

console.log('OOM:', oomError);
console.log('Validierung:', validationError?.constructor.name);

OOM: null Validierung: GPUValidationError

// Wichtig · Fallstricke

Leerer Stapel: Ein popErrorScope() ohne vorheriges pushErrorScope() führt dazu, dass das Promise mit einer OperationError abgelehnt wird. Sorge daher für paarweise Aufrufe, am besten in einer Hilfsfunktion.
Nur der erste Fehler: Pro Bereich wird nur der erste passende Fehler geliefert. Weitere Fehler im selben Bereich gehen verloren. Setze Bereiche also eng um die zu prüfenden Aufrufe.
Verlorenes Gerät: Nach einem Geräteverlust (device.lost) wird das Promise mit null erfüllt. Fehler werden dann nicht mehr gemeldet.
Performance: Das Warten auf das Promise kann eine Synchronisation mit dem GPU-Prozess erzwingen. Setze viele Fehlerbereiche in Render-Schleifen nicht dauerhaft ein, sondern vor allem beim Erstellen von Ressourcen oder beim Debuggen.
Nicht erfasste Fehler landen im Ereignis uncapturederror. Registriere dafür zusätzlich einen globalen Handler.
Kompatibilität: WebGPU ist nur in sicheren Kontexten (HTTPS) verfügbar und wird noch nicht überall unterstützt. Prüfe vorher mit if (!navigator.gpu). Firefox unterstützt WebGPU bisher nur teilweise bzw. je nach Plattform.

Siehe auch

GPUDevice.pushErrorScope() GPUDevice GPUError GPUValidationError GPUOutOfMemoryError GPUInternalError GPUDevice.lost