GPUOutOfMemoryError — Schnittstelle · JavaScript-Referenz

Signatur

interface GPUOutOfMemoryError extends GPUError

Beschreibung

GPUOutOfMemoryError gehört zur WebGPU-API und leitet von GPUError ab. Ein solcher Fehler zeigt an, dass eine angeforderte Operation, meist das Anlegen einer Ressource mit createBuffer() oder createTexture(), mangels freien Speichers fehlgeschlagen ist. Der Fehler wird nicht als Ausnahme geworfen. Stattdessen macht ihn die WebGPU-Fehlerbehandlung asynchron sichtbar.

Es gibt zwei Wege, an diesen Fehler zu kommen:

Über einen Fehler-Scope: device.pushErrorScope("out-of-memory") vor der Operation und danach await device.popErrorScope(). Die Methode liefert ein GPUOutOfMemoryError-Objekt oder null.
Über das Ereignis uncapturederror am GPUDevice. Es erhält alle Fehler, die kein Scope abgefangen hat. Das Fehlerobjekt steckt in event.error.

Anders als ein Validierungsfehler (GPUValidationError) ist ein Speicherüberlauf oft behebbar. Die Anwendung kann nicht mehr benötigte Ressourcen mit destroy() freigeben, kleinere Texturen oder Puffer anfordern und es dann erneut versuchen. Einen neuen Fehler kann man auch selbst anlegen, mit new GPUOutOfMemoryError(message). Das ist vor allem für Tests und Polyfills nützlich.

Die Schnittstelle bringt keine eigenen Eigenschaften mit. Sie erbt nur message (string) von GPUError. Der Text der Meldung dient Menschen zur Fehlersuche. Er ist nicht standardisiert und sollte deshalb nicht automatisch ausgewertet werden.

Parameter

Name	Typ	Default	Beschreibung
$message Pflicht	string		Nur für den Konstruktor `new GPUOutOfMemoryError(message)`: eine Meldung, die den Fehler für Menschen verständlich beschreibt. Sie ist danach über die geerbte Eigenschaft `message` lesbar.

Rückgabewert

Typ

GPUOutOfMemoryError

Beschreibung

Der Konstruktor liefert eine neue Instanz. Im Normalfall erzeugt aber der Browser die Instanz und gibt sie über GPUDevice.popErrorScope() oder GPUUncapturedErrorEvent.error zurück.

Beispiele

Speicherüberlauf beim Anlegen eines Puffers mit einem Fehler-Scope abfangen

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

device.pushErrorScope('out-of-memory');

const buffer = device.createBuffer({
  size: 1024 * 1024 * 1024, // 1 GiB
  usage: GPUBufferUsage.STORAGE
});

const error = await device.popErrorScope();
if (error instanceof GPUOutOfMemoryError) {
  console.warn('Nicht genug GPU-Speicher:', error.message);
  buffer.destroy();
} else {
  console.log('Puffer erfolgreich angelegt');
}

Puffer erfolgreich angelegt // oder bei Speichermangel: // Nicht genug GPU-Speicher: <browserabhängige Meldung>

Textur anlegen und bei Speichermangel die Auflösung verringern

async function createTextureWithFallback(device, width, height) {
  while (width >= 256 && height >= 256) {
    device.pushErrorScope('out-of-memory');
    const texture = device.createTexture({
      size: [width, height],
      format: 'rgba8unorm',
      usage: GPUTextureUsage.TEXTURE_BINDING | GPUTextureUsage.RENDER_ATTACHMENT
    });
    const error = await device.popErrorScope();
    if (!error) return texture;

    texture.destroy();
    console.warn(`OOM bei ${width}x${height}, versuche kleinere Größe`);
    width = Math.floor(width / 2);
    height = Math.floor(height / 2);
  }
  throw new Error('Textur konnte nicht angelegt werden');
}

const adapter = await navigator.gpu.requestAdapter();
const device = await adapter.requestDevice();
const tex = await createTextureWithFallback(device, 8192, 8192);
console.log(tex.width, tex.height);

8192 8192

Nicht abgefangene Fehler global protokollieren

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

device.addEventListener('uncapturederror', (event) => {
  const { error } = event;
  if (error instanceof GPUOutOfMemoryError) {
    console.error('[GPU OOM]', error.message);
  } else if (error instanceof GPUValidationError) {
    console.error('[GPU Validierung]', error.message);
  }
});

// Konstruktor, z. B. für Tests
const testError = new GPUOutOfMemoryError('Testfehler');
console.log(testError instanceof GPUError, testError.message);

true Testfehler

// Wichtig · Fallstricke

Keine Ausnahme: createBuffer() und ähnliche Methoden werfen bei Speichermangel nichts. Sie geben ein Objekt zurück, das als ungültig markiert ist. Ein try/catch um den Aufruf fängt den Fehler deshalb nicht. Dafür braucht man einen Fehler-Scope oder das Ereignis uncapturederror.
Filter beachten: pushErrorScope('out-of-memory') fängt nur Speicherüberläufe ab. Validierungsfehler wandern trotzdem zum nächsten äußeren Scope oder zu uncapturederror. Jedes pushErrorScope() braucht ein passendes popErrorScope(). Fehlt es, liefert popErrorScope() ein abgelehntes Promise mit einer OperationError.
Performance: popErrorScope() ist asynchron und wartet auf die GPU. Fehler-Scopes gehören nicht in Schleifen, die jeden Frame laufen, sondern an Stellen, an denen Ressourcen angelegt werden.
Nicht verwechseln mit einem verlorenen Gerät: Ist das Gerät verloren, meldet sich das über device.lost und nicht über diese Fehlerklasse.
Kompatibilität: WebGPU steht nur in sicheren Kontexten (HTTPS) und nicht in allen Browsern bzw. auf allen Plattformen zur Verfügung. Deshalb vorher prüfen, ob navigator.gpu existiert. Der Text von message ist je nach Implementierung verschieden.

Siehe auch

GPUInternalError GPUPipelineError GPUValidationError GPUError QuotaExceededError