GPUPipelineError.reason — Eigenschaft · JavaScript-Referenz

Signatur

GPUPipelineError.reason

Beschreibung

Die Eigenschaft reason einer GPUPipelineError-Instanz nennt die Fehlerkategorie, wenn das Promise von GPUDevice.createRenderPipelineAsync() oder GPUDevice.createComputePipelineAsync() abgelehnt wird. Anders als message ist der Wert für Programmcode gedacht: Er ist ein fester Aufzählungswert und hängt weder von der Sprache noch vom Browser ab.

Mögliche Werte:

"validation": Der Pipeline-Deskriptor ist ungültig, zum Beispiel wegen eines fehlenden Einstiegspunkts, eines unpassenden Bind-Group-Layouts, inkompatibler Vertex-Formate oder eines fehlerhaften Shader-Moduls. Das ist ein Programmierfehler, den ein erneuter Versuch nicht behebt.
"internal": Die Erstellung ist aus einem Grund gescheitert, der nichts mit der Validierung zu tun hat. Beispiele sind erschöpfte Ressourcen oder Grenzen der Treiber- bzw. Shader-Compilierung. Der Deskriptor kann dabei durchaus gültig sein.

Mit reason kann eine Anwendung gezielt reagieren. Bei "validation" protokolliert sie den Fehler und korrigiert den Code. Bei "internal" weicht sie auf eine einfachere Pipeline aus, etwa mit weniger aufwändigen Shadern, oder meldet dem Nutzer ein Hardwareproblem.

Rückgabewert

Typ

"validation" | "internal"

Beschreibung

Ein schreibgeschützter String aus der Aufzählung GPUPipelineErrorReason. Er wird beim Erzeugen des Fehlers über options.reason festgelegt.

Beispiele

Fehlergrund beim asynchronen Erstellen einer Compute-Pipeline auswerten

const adapter = await navigator.gpu?.requestAdapter();
if (!adapter) throw new Error('WebGPU nicht verfügbar');
const device = await adapter.requestDevice();

// Absichtlich falscher Einstiegspunkt, um einen Validierungsfehler auszulösen
const module = device.createShaderModule({
  code: `@compute @workgroup_size(64) fn main() {}`
});

try {
  await device.createComputePipelineAsync({
    layout: 'auto',
    compute: { module, entryPoint: 'gibtEsNicht' }
  });
} catch (err) {
  if (err instanceof GPUPipelineError) {
    console.log('Grund:', err.reason);
    console.log('Meldung:', err.message);
  } else {
    throw err;
  }
}

Grund: validation Meldung: (browserabhängiger Text, z. B. Hinweis auf den fehlenden Einstiegspunkt)

Ausweichen auf eine einfachere Render-Pipeline bei internem Fehler

const createPipelineWithFallback = async (device, fullDescriptor, simpleDescriptor) => {
  try {
    return await device.createRenderPipelineAsync(fullDescriptor);
  } catch (err) {
    if (!(err instanceof GPUPipelineError)) throw err;

    switch (err.reason) {
      case 'validation':
        // Programmierfehler: Wiederholen bringt nichts
        console.error('Ungültiger Pipeline-Deskriptor:', err.message);
        throw err;
      case 'internal':
        // z. B. Ressourcen erschöpft: vereinfachte Variante versuchen
        console.warn('Interner Fehler, nutze vereinfachte Shader:', err.message);
        return device.createRenderPipelineAsync(simpleDescriptor);
    }
  }
};

GPUPipelineError selbst erzeugen (z. B. für Tests)

const err = new GPUPipelineError('Shader-Compilierung abgebrochen', {
  reason: 'internal'
});

console.log(err.reason);                  // "internal"
console.log(err.name);                    // "GPUPipelineError"
console.log(err instanceof DOMException); // true

// Schreibgeschützt: Zuweisung wird ignoriert
err.reason = 'validation';
console.log(err.reason);

internal GPUPipelineError true internal

// Wichtig · Fallstricke

Nur bei den asynchronen Varianten: Die synchronen Methoden createRenderPipeline() und createComputePipeline() werfen keinen GPUPipelineError. Sie liefern eine ungültige Pipeline und melden den Fehler über Fehler-Scopes (pushErrorScope()/popErrorScope()) oder über das Ereignis uncapturederror als GPUValidationError.
message nicht auswerten: Der Text von message ist je nach Browser und Version verschieden. Programmlogik sollte sich ausschließlich auf reason stützen.
Andere Ablehnungsgründe: Ist das Gerät verloren (device.lost), kann das Promise auch anders abgelehnt werden. Prüfe deshalb vorher mit instanceof GPUPipelineError, bevor du auf reason zugreifst.
Der Konstruktor verlangt options.reason. Fehlt die Angabe oder ist der Wert ungültig, wird ein TypeError geworfen.
Kompatibilität: WebGPU ist nur in sicheren Kontexten (HTTPS) verfügbar. Die Unterstützung ist noch nicht in allen Browsern und auf allen Plattformen vollständig, daher vorher mit navigator.gpu prüfen. In Node.js gibt es WebGPU nur über Zusatzpakete (z. B. Dawn-Bindings).

Siehe auch

GPUPipelineError GPUDevice.createRenderPipelineAsync() GPUDevice.createComputePipelineAsync() GPUValidationError DOMException GPUPipelineLayout.label