GPUAdapter — Schnittstelle · JavaScript-Referenz

Signatur

interface GPUAdapter

Beschreibung

GPUAdapter ist in WebGPU der Einstiegspunkt zur Grafikhardware. Ein Adapter steht für eine konkrete WebGPU-Implementierung auf dem System, etwa die integrierte oder die dedizierte GPU oder einen Software-Renderer als Ausweichlösung. Man kann ihn nicht mit new erzeugen. Man bekommt ihn asynchron über navigator.gpu.requestAdapter() (im Worker über self.navigator.gpu).

Der Adapter selbst kann nicht rendern oder rechnen. Er dient dazu, die Fähigkeiten zu prüfen und anschließend ein logisches Gerät (GPUDevice) anzufordern. Wichtige Mitglieder:

features (GPUSupportedFeatures): eine Set-ähnliche Menge optionaler Features, z. B. "texture-compression-bc", "shader-f16" oder "timestamp-query".
limits (GPUSupportedLimits): die höchsten Grenzwerte, die der Adapter unterstützt, z. B. maxTextureDimension2D oder maxBufferSize.
info (GPUAdapterInfo): Angaben zu Hersteller, Architektur, Gerät und Beschreibung sowie isFallbackAdapter.
requestDevice(descriptor?): liefert ein Promise<GPUDevice> mit den angeforderten Features und Limits.

Üblicher Ablauf: Adapter anfordern, prüfen, ob die benötigten Features und Limits vorhanden sind, und dann requestDevice() mit genau diesen Anforderungen aufrufen. Standardmäßig bekommt ein Gerät nur die Standard-Limits, nicht die höchsten Werte des Adapters. Höhere Werte muss man ausdrücklich über requiredLimits anfordern.

Parameter

Name	Typ	Default	Beschreibung
$descriptor	GPUDeviceDescriptor	{}	Optionales Objekt für `requestDevice()`, die zentrale Methode des Adapters.
$descriptor.requiredFeatures	Array<string>	[]	Features, die das Gerät haben muss. Jedes davon muss in `adapter.features` enthalten sein, sonst wird das Promise mit `TypeError` abgelehnt.
$descriptor.requiredLimits	Record<string, number>	{}	Gewünschte Limits. Die Werte dürfen die Werte aus `adapter.limits` nicht überschreiten, sonst wird das Promise mit `OperationError` abgelehnt.
$descriptor.defaultQueue	GPUQueueDescriptor	{}	Beschreibung der Standard-Queue, z. B. `{ label: "Haupt-Queue" }`.
$descriptor.label	string	""	Bezeichner für das Gerät. Er erscheint in Fehlermeldungen und Debugging-Werkzeugen.

Beispiele

Adapter anfordern und Gerät erzeugen

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

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

  if (!adapter) {
    throw new Error('Kein passender GPU-Adapter gefunden.');
  }

  const device = await adapter.requestDevice({ label: 'Haupt-Gerät' });
  console.log('Gerät bereit:', device.label);
  return { adapter, device };
};

initWebGPU().catch(console.error);

Gerät bereit: Haupt-Gerät

Features und Limits prüfen und gezielt anfordern

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

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

// Höhere Limits nur anfordern, wenn der Adapter sie unterstützt
const wantedBufferSize = 1024 * 1024 * 1024; // 1 GiB
const requiredLimits = {
  maxBufferSize: Math.min(wantedBufferSize, adapter.limits.maxBufferSize),
  maxStorageBufferBindingSize: adapter.limits.maxStorageBufferBindingSize
};

const device = await adapter.requestDevice({ requiredFeatures, requiredLimits });

console.log('f16 aktiv:', device.features.has('shader-f16'));
console.log('maxBufferSize:', device.limits.maxBufferSize);

f16 aktiv: true maxBufferSize: 1073741824

Adapter-Informationen und Fallback erkennen

const adapter = await navigator.gpu.requestAdapter();
const { vendor, architecture, description, isFallbackAdapter } = adapter.info;

console.log(`Hersteller: ${vendor || 'unbekannt'}`);
console.log(`Architektur: ${architecture || 'unbekannt'}`);
console.log(`Beschreibung: ${description || '—'}`);

if (isFallbackAdapter) {
  console.warn('Software-Renderer aktiv – Qualität wird reduziert.');
}

// Alle unterstützten Features auflisten
console.log([...adapter.features].sort().join(', '));

Hersteller: nvidia Architektur: ampere Beschreibung: — depth-clip-control, float32-filterable, shader-f16, texture-compression-bc, timestamp-query

Auf Geräteverlust reagieren und neuen Adapter anfordern

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

  const device = await adapter.requestDevice();

  device.lost.then((info) => {
    console.warn(`Gerät verloren (${info.reason}): ${info.message}`);
    // Ein Adapter liefert nur einmal ein Gerät, deshalb neu anfordern
    if (info.reason !== 'destroyed') createDevice();
  });

  return device;
};

const device = await createDevice();

Siehe auch

GPUAdapterInfo GPUSampler GPUBuffer GPUDevice GPUError