GPUError — Schnittstelle · JavaScript-Referenz

Signatur

interface GPUError

Beschreibung

GPUError ist die gemeinsame Basis aller WebGPU-Fehlerobjekte. Die meisten WebGPU-Aufrufe wie createBuffer(), createRenderPipeline() oder queue.submit() werfen bei Fehlern keine Ausnahme, denn die GPU arbeitet asynchron. Die Fehler werden stattdessen später gemeldet: entweder als Ergebnis von GPUDevice.popErrorScope() oder als error-Eigenschaft eines GPUUncapturedErrorEvent.

Man erzeugt GPUError nicht selbst. Die Fehler, die man tatsächlich erhält, sind Instanzen dieser Unterklassen:

GPUValidationError: ein Aufruf hat die Validierungsregeln verletzt, z. B. durch ungültige Deskriptoren, falsche Usage-Flags oder einen fehlerhaften Shader.
GPUOutOfMemoryError: es war nicht genug Speicher für die angeforderte Ressource vorhanden.
GPUInternalError: ein Fehler in der Implementierung, obwohl die Validierung bestanden wurde, z. B. weil Systemgrenzen überschritten wurden.

Das Interface hat nur eine Eigenschaft: message (string, schreibgeschützt). Sie enthält eine lesbare Beschreibung des Fehlers, die sich zum Debuggen eignet. Den Fehlertyp prüft man mit instanceof gegen die jeweilige Unterklasse.

Rückgabewert

Typ

GPUError

Beschreibung

Wird nicht direkt erzeugt. Man erhält eine Instanz von GPUValidationError, GPUOutOfMemoryError oder GPUInternalError, jeweils mit der Eigenschaft message: string.

Beispiele

Validierungsfehler mit einem Fehler-Scope abfangen

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

device.pushErrorScope('validation');

// Ungültig: MAP_READ darf nur zusammen mit COPY_DST verwendet werden
const buffer = device.createBuffer({
  size: 256,
  usage: GPUBufferUsage.MAP_READ | GPUBufferUsage.STORAGE,
});

const error = await device.popErrorScope();
if (error) {
  console.log(error instanceof GPUError);           // true
  console.log(error instanceof GPUValidationError); // true
  console.log(`Validierungsfehler: ${error.message}`);
}

true true Validierungsfehler: ... (Text je nach Browser)

Fehler zentral über das uncapturederror-Ereignis protokollieren

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

const describe = (err) => {
  if (err instanceof GPUValidationError) return 'Validierung';
  if (err instanceof GPUOutOfMemoryError) return 'Kein Speicher';
  if (err instanceof GPUInternalError) return 'Intern';
  return 'Unbekannt';
};

device.addEventListener('uncapturederror', (event) => {
  const { error } = event; // GPUError-Unterklasse
  console.error(`[WebGPU/${describe(error)}] ${error.message}`);
});

// Alternativ über die on-Eigenschaft:
// device.onuncapturederror = (event) => console.error(event.error.message);

// Fehlerhafter Shader-Code löst das Ereignis aus
device.createShaderModule({ code: 'das ist kein WGSL' });

[WebGPU/Validierung] ... (Parserfehler im WGSL-Code)

Speichermangel beim Anlegen großer Ressourcen behandeln

const createLargeTexture = async (device, size) => {
  device.pushErrorScope('out-of-memory');
  const texture = device.createTexture({
    size: [size, size],
    format: 'rgba8unorm',
    usage: GPUTextureUsage.TEXTURE_BINDING,
  });
  const error = await device.popErrorScope();
  if (error) {
    console.warn(`Speichermangel bei ${size}px: ${error.message}`);
    texture.destroy();
    return size > 1024 ? createLargeTexture(device, size / 2) : null;
  }
  return texture;
};

const adapter = await navigator.gpu.requestAdapter();
const device = await adapter.requestDevice();
const tex = await createLargeTexture(device, 8192);
console.log(tex ? `Textur: ${tex.width}px` : 'Keine Textur möglich');

Textur: 8192px

// Wichtig · Fallstricke

Keine Ausnahmen: WebGPU-Aufrufe melden Fehler asynchron. Ein try/catch um createBuffer() fängt keine Validierungsfehler ab. Dafür braucht man pushErrorScope()/popErrorScope() oder das uncapturederror-Ereignis.
Filter der Scopes: Ein Scope fängt nur den Fehlertyp ab, mit dem er angelegt wurde ('validation', 'out-of-memory' oder 'internal'). Andere Fehler landen im nächsten äußeren Scope oder als uncapturederror. Wenn mehrere Fehler auftreten, liefert ein Scope nur den ersten.
Kein stabiler Text: Der Inhalt von message ist nicht standardisiert und unterscheidet sich je nach Browser. Er taugt zum Protokollieren, aber nicht für Programmlogik. Den Fehlertyp prüft man immer mit instanceof.
Geräteverlust: Geht das Gerät verloren, wird kein GPUError gemeldet. Das signalisiert stattdessen das Promise GPUDevice.lost, das zu einem GPUDeviceLostInfo aufgelöst wird.
Kompatibilität: WebGPU steht nur in sicheren Kontexten (HTTPS) zur Verfügung und ist noch nicht in allen Browsern aktiviert. Vor der Nutzung sollte man 'gpu' in navigator prüfen. In Workern ist die API ebenfalls verfügbar.

Siehe auch

DOMError RTCError GPU GPUBuffer GPUDevice