GPU.requestAdapter() — Methode · JavaScript-Referenz

Signatur

GPU.prototype.requestAdapter(options)

Beschreibung

requestAdapter() ist der Einstiegspunkt in jede WebGPU-Anwendung. Über navigator.gpu (im Hauptthread) bzw. self.navigator.gpu (in Workern) erreichbar, liefert die Methode einen GPUAdapter. Er steht für eine konkrete GPU-Implementierung des Systems, etwa eine integrierte oder eine dedizierte Grafikkarte.

Der Adapter selbst dient noch nicht zum Rendern oder Rechnen. Er gibt Auskunft über unterstützte Features (adapter.features), Limits (adapter.limits) und Hardware-Informationen (adapter.info). Erst mit adapter.requestDevice() bekommt man ein GPUDevice, über das Puffer, Texturen, Pipelines und Befehle angelegt werden.

Über das optionale options-Objekt gibt man dem Browser Hinweise, welcher Adapter bevorzugt wird. Das kann ein stromsparender oder ein leistungsstarker Adapter sein, oder ein Fallback-Adapter per Software-Rendering. Der Browser darf diese Hinweise ignorieren. Wenn kein passender Adapter verfügbar ist, wird das Promise mit null erfüllt und nicht abgelehnt. Diesen Fall muss man daher immer ausdrücklich prüfen.

Parameter

Name	Typ	Default	Beschreibung
$options	GPURequestAdapterOptions	{}	Optionales Objekt mit Hinweisen für die Auswahl des Adapters.
$options.powerPreference	"low-power" \| "high-performance"	undefined	Gewünschtes Leistungsprofil. `"low-power"` bevorzugt meist die integrierte GPU und schont damit den Akku. `"high-performance"` bevorzugt meist die dedizierte GPU. Der Wert ist nur ein Hinweis.
$options.forceFallbackAdapter	boolean	false	Bei `true` wird ein Fallback-Adapter zurückgegeben, z. B. ein Software-Renderer mit geringerer Leistung. Ist keiner verfügbar, ergibt das `null`.
$options.featureLevel	"core" \| "compatibility"	"core"	Experimentell. Mit `"compatibility"` wird ein Adapter mit eingeschränktem Funktionsumfang für ältere Hardware angefordert. Das wird noch nicht überall unterstützt.
$options.xrCompatible	boolean	false	Experimentell. Fordert einen Adapter an, der sich für WebXR-Sitzungen eignet.

Rückgabewert

Typ

Promise<GPUAdapter | null>

Beschreibung

Ein Promise, das mit einem GPUAdapter erfüllt wird, oder mit null, wenn kein passender Adapter verfügbar ist.

Beispiele

WebGPU initialisieren mit Prüfung auf Unterstützung

const initWebGPU = async () => {
  if (!navigator.gpu) {
    throw new Error('WebGPU wird von diesem Browser nicht unterstützt.');
  }

  const adapter = await navigator.gpu.requestAdapter();
  if (!adapter) {
    throw new Error('Kein passender GPU-Adapter gefunden.');
  }

  const device = await adapter.requestDevice();
  console.log('GPUDevice bereit:', device);
  return device;
};

initWebGPU().catch((err) => console.error(err.message));

GPUDevice bereit: GPUDevice {...}

Leistungsstarke GPU bevorzugen und Adapter-Infos auslesen

const adapter = await navigator.gpu?.requestAdapter({
  powerPreference: 'high-performance'
});

if (adapter) {
  const { vendor, architecture } = adapter.info;
  console.log(`Hersteller: ${vendor}, Architektur: ${architecture}`);
  console.log('Max. Texturgröße 2D:', adapter.limits.maxTextureDimension2D);
  console.log('Unterstützt shader-f16:', adapter.features.has('shader-f16'));
}

Hersteller: nvidia, Architektur: ampere Max. Texturgröße 2D: 16384 Unterstützt shader-f16: true

Fallback-Adapter als Rückfallebene nutzen

const getAdapter = async () => {
  // Zuerst regulären Hardware-Adapter versuchen
  let adapter = await navigator.gpu.requestAdapter();
  if (!adapter) {
    // Danach auf Software-Implementierung ausweichen
    adapter = await navigator.gpu.requestAdapter({ forceFallbackAdapter: true });
  }
  return adapter;
};

const adapter = await getAdapter();
console.log(adapter ? 'Adapter gefunden' : 'Keine WebGPU-Ausführung möglich');

Adapter gefunden

Optionale Features beim Gerät anfordern

const adapter = await navigator.gpu.requestAdapter();
if (!adapter) throw new Error('Kein Adapter');

const requiredFeatures = [];
if (adapter.features.has('timestamp-query')) {
  requiredFeatures.push('timestamp-query');
}

const device = await adapter.requestDevice({ requiredFeatures });
console.log([...device.features]);

["timestamp-query"] (je nach Hardware)

// Wichtig · Fallstricke

Auf null prüfen: Das Promise wird nicht abgelehnt, wenn kein Adapter verfügbar ist, sondern mit null erfüllt. Ein try/catch allein reicht daher nicht.
Sicherer Kontext: navigator.gpu gibt es nur über HTTPS oder localhost. Sonst ist es undefined. Mit optionaler Verkettung prüfen: navigator.gpu?.requestAdapter().
Browser-Unterstützung: Chrome und Edge unterstützen WebGPU ab Version 113 (Windows, macOS, ChromeOS; Android ab 121). Safari unterstützt es ab Version 26, Firefox ab 141 zunächst unter Windows. Unter Linux ist die Unterstützung teils nur über ein Flag verfügbar. Eine Erkennung des Funktionsumfangs ist Pflicht, am besten mit Rückfall auf WebGL.
Hinweise statt Garantien: powerPreference kann ignoriert werden, z. B. auf Systemen mit nur einer GPU oder durch Browser-Richtlinien.
Adapter veraltet: Ein Adapter kann ungültig werden, etwa nach einem GPU-Reset oder beim Wechsel der Grafikkarte. Dann schlägt requestDevice() fehl oder liefert ein sofort verlorenes Gerät. Nach device.lost sollte man deshalb einen neuen Adapter anfordern. Einen Adapter nicht wiederverwenden, wenn er bereits ein Gerät erzeugt hat.
Datenschutz: Die Werte in adapter.info sind je nach Browser absichtlich unvollständig, damit sie nicht zum Fingerprinting dienen können.

Siehe auch

GPU GPUAdapter GPUAdapter.requestDevice() GPUDevice GPU.getPreferredCanvasFormat() Navigator.gpu GPUAdapter.requestAdapterInfo()