GPUAdapter: requestDevice()-Methode

Syntax

requestDevice()
requestDevice(descriptor)

Parameter

descriptor Optional

Ein Objekt mit den folgenden Eigenschaften:

defaultQueue Optional

Ein Objekt mit Informationen für die standardmäßige GPUQueue des Geräts (wie von GPUDevice.queue zurückgegeben). Dieses Objekt hat eine einzige Eigenschaft – label –, die der Standard-Queue einen Wert für label zuweist. Wird kein Wert angegeben, ist der Standardwert ein leeres Objekt und das Label der Standard-Queue eine leere Zeichenfolge.

label Optional

Eine Zeichenfolge, die ein Label zur Identifizierung des GPUDevice bereitstellt, beispielsweise in GPUError-Meldungen oder Konsolenwarnungen.

requiredFeatures Optional

Ein Array von Zeichenfolgen, die zusätzliche Funktionen angeben, die das zurückgegebene GPUDevice unterstützen soll. Der Aufruf von requestDevice() schlägt fehl, wenn der GPUAdapter diese Funktionen nicht bereitstellen kann. Eine vollständige Liste möglicher Funktionen finden Sie unter GPUSupportedFeatures. Wird kein Wert angegeben, ist der Standardwert ein leeres Array.

requiredLimits Optional

Ein Objekt mit Eigenschaften, die die Limits angeben, die das zurückgegebene GPUDevice unterstützen soll. Der Aufruf von requestDevice() schlägt fehl, wenn der GPUAdapter diese Limits nicht bereitstellen kann. Jeder Schlüssel mit einem Wert ungleich undefined muss dem Namen eines Members von GPUSupportedLimits entsprechen.

Hinweis: Sie können beim Anfordern eines GPU-Geräts unbekannte Limits angeben, ohne dass ein Fehler auftritt. Solche Limits haben den Wert undefined. Das macht WebGPU-Code robuster: Eine Codebasis funktioniert nicht plötzlich nicht mehr, nur weil ein Limit im Adapter nicht mehr existiert.

Nicht alle Funktionen und Limits sind in jedem Browser, der WebGPU unterstützt, für WebGPU verfügbar – selbst wenn die zugrunde liegende Hardware sie unterstützt. Weitere Informationen finden Sie auf den Seiten zu features und limits.

Rückgabewert

Eine Promise, die mit einer GPUDevice-Objektinstanz erfüllt wird.

Wenn Sie requestDevice() erneut auf einem GPUAdapter aufrufen, auf dem die Methode bereits aufgerufen wurde, wird die Promise mit einem OperationError zurückgewiesen. Der zugehörige GPUAdapter wird beim Erstellen eines GPUDevice aufgebraucht.

Ausnahmen

OperationError DOMException

Die Promise wird mit einem OperationError zurückgewiesen, wenn einer der folgenden Fälle eintritt:

• Die in der Eigenschaft requiredLimits angegebenen Limits werden vom GPUAdapter nicht unterstützt, weil sie entweder keine gültigen Limits sind oder ihre Werte über den entsprechenden Werten des Adapters liegen.
• Der GPUAdapter wurde bereits durch einen früheren Aufruf von requestDevice() aufgebraucht.

TypeError

Die Promise wird mit einem TypeError zurückgewiesen, wenn die in der Eigenschaft requiredFeatures angegebenen Funktionen vom GPUAdapter nicht unterstützt werden.

Beispiele

Einfaches Beispiel

async function init() {
  if (!navigator.gpu) {
    throw Error("WebGPU not supported.");
  }

  const adapter = await navigator.gpu.requestAdapter();
  if (!adapter) {
    throw Error("Couldn't request WebGPU adapter.");
  }

  const device = await adapter.requestDevice();

  // …
}

Bestimmte Funktionen und Limits anfordern

Im folgenden Code:

1. Prüfen wir, ob für einen GPUAdapter die Funktion texture-compression-astc verfügbar ist. Falls ja, fügen wir sie dem Array requiredFeatures hinzu.
2. Fragen wir den Wert von maxBindGroups in GPUAdapter.limits ab, um festzustellen, ob er mindestens 6 beträgt. Unsere hypothetische Beispielanwendung benötigt idealerweise 6 Bind Groups. Wenn der zurückgegebene Wert >= 6 ist, fügen wir dem Objekt requiredLimits daher ein maximales Limit von 6 hinzu.
3. Fordern wir ein Gerät mit diesen Anforderungen an Funktionen und Limits sowie einem Label für defaultQueue an.

async function init() {
  if (!navigator.gpu) {
    throw Error("WebGPU not supported.");
  }

  const adapter = await navigator.gpu.requestAdapter();
  if (!adapter) {
    throw Error("Couldn't request WebGPU adapter.");
  }

  const requiredFeatures = [];

  if (adapter.features.has("texture-compression-astc")) {
    requiredFeatures.push("texture-compression-astc");
  }

  const requiredLimits = {};

  // App ideally needs 6 bind groups, so we'll try to request what the app needs
  if (adapter.limits.maxBindGroups >= 6) {
    requiredLimits.maxBindGroups = 6;
  }

  const device = await adapter.requestDevice({
    defaultQueue: {
      label: "my_queue",
    },
    requiredFeatures,
    requiredLimits,
  });

  // …
}

Spezifikationen

Browser-Kompatibilität

Siehe auch

• Die WebGPU API