GPUAdapterInfo.subgroupMaxSize — Eigenschaft · JavaScript-Referenz

Signatur

GPUAdapterInfo.subgroupMaxSize

Beschreibung

Die schreibgeschützte Eigenschaft subgroupMaxSize des GPUAdapterInfo-Objekts gibt an, wie viele Shader-Aufrufe (Invocations) eine Subgruppe auf dem jeweiligen Adapter höchstens umfassen kann. Eine Subgruppe ist eine Gruppe von Aufrufen, die auf der GPU gemeinsam im Gleichschritt laufen (bei NVIDIA „Warp“, bei AMD „Wavefront“). Innerhalb einer Subgruppe können Aufrufe über WGSL-Funktionen wie subgroupAdd(), subgroupBroadcast() oder subgroupShuffle() ohne gemeinsamen Workgroup-Speicher und ohne Barrieren Daten austauschen.

Der Wert ist immer eine Zweierpotenz. Zusammen mit subgroupMinSize beschreibt er den Bereich, in dem die tatsächliche Subgruppen-Größe liegt; welche Größe ein Shader zur Laufzeit wirklich bekommt, liest er über das eingebaute WGSL-Attribut @builtin(subgroup_size) aus. Auf manchen GPUs (z. B. Intel oder AMD RDNA) kann die Größe je nach Pipeline variieren, daher dürfen Shader sich nie auf einen festen Wert verlassen.

Man nutzt subgroupMaxSize typischerweise, um Workgroup-Größen und Puffer für Reduktionen (Summen, Präfixsummen, Histogramme) passend zu dimensionieren – etwa, um genug Platz für Zwischenergebnisse pro Subgruppe zu reservieren (workgroupSize / subgroupMinSize Einträge) oder um zu prüfen, ob ein Algorithmus mit einer bestimmten Subgruppen-Breite überhaupt sinnvoll ist.

Das GPUAdapterInfo-Objekt erhält man synchron über GPUAdapter.info oder nach der Geräteerstellung über GPUDevice.adapterInfo. Subgruppen-Operationen im Shader setzen voraus, dass das Feature "subgroups" beim Aufruf von requestDevice() angefordert wurde.

Rückgabewert

Typ

number

Beschreibung

Eine ganze Zahl (Zweierpotenz, gemäß Spezifikation im Bereich 4 bis 128) mit der maximalen Subgruppen-Größe des Adapters. Beispielwerte: 32 (NVIDIA), 64 (AMD GCN/RDNA), 32 (Intel), 32 (Apple).

Beispiele

Subgruppen-Bereich des Adapters auslesen

const adapter = await navigator.gpu?.requestAdapter();
if (!adapter) throw new Error('WebGPU wird nicht unterstützt');

const { subgroupMinSize, subgroupMaxSize, vendor } = adapter.info;
console.log(`Hersteller: ${vendor}`);
console.log(`Subgruppen-Größe: ${subgroupMinSize}–${subgroupMaxSize}`);

Hersteller: nvidia Subgruppen-Größe: 32–32

Gerät mit Subgruppen-Feature anfordern und Shader nutzen

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

if (!adapter.features.has('subgroups')) {
  console.warn('Subgruppen nicht verfügbar – Fallback auf Workgroup-Speicher');
} else {
  const device = await adapter.requestDevice({ requiredFeatures: ['subgroups'] });
  console.log('Max. Subgruppe:', device.adapterInfo.subgroupMaxSize);

  const module = device.createShaderModule({
    code: /* wgsl */ `
      enable subgroups;
      @group(0) @binding(0) var<storage, read_write> data: array<f32>;

      @compute @workgroup_size(64)
      fn main(@builtin(global_invocation_id) id: vec3u,
              @builtin(subgroup_invocation_id) lane: u32) {
        // Summe aller Werte innerhalb der Subgruppe
        let sum = subgroupAdd(data[id.x]);
        if (lane == 0u) { data[id.x] = sum; }
      }
    `,
  });
  console.log('Shader-Modul erstellt:', module);
}

Max. Subgruppe: 32 Shader-Modul erstellt: GPUShaderModule {…}

Puffer für Subgruppen-Zwischenergebnisse dimensionieren

const adapter = await navigator.gpu.requestAdapter();
const { subgroupMinSize, subgroupMaxSize } = adapter.info;

const workgroupSize = 256;
// Worst Case: kleinste Subgruppen ergeben die meisten Teilergebnisse
const maxPartials = Math.ceil(workgroupSize / subgroupMinSize);
// Mindestens eine volle Subgruppe muss in die Workgroup passen
const fits = workgroupSize >= subgroupMaxSize;

console.log({ maxPartials, fits });

{ maxPartials: 8, fits: true }

// Wichtig · Fallstricke

Kompatibilität: Die Eigenschaft ist neu und experimentell. Sie ist in Chromium-Browsern (ab Version 134) verfügbar; Firefox und Safari unterstützen sie noch nicht bzw. nur teilweise. Vorher mit 'subgroupMaxSize' in adapter.info prüfen.
Der Wert ist nur ein Rahmen: Die tatsächliche Größe kann je nach Pipeline zwischen subgroupMinSize und subgroupMaxSize schwanken. Im Shader immer @builtin(subgroup_size) verwenden statt eines festen Werts.
Die Eigenschaft auszulesen reicht nicht, um Subgruppen-Funktionen nutzen zu können: Das Feature "subgroups" muss in requiredFeatures angefordert und im WGSL-Code mit enable subgroups; aktiviert werden.
Wie andere Adapter-Informationen kann der Wert zum Fingerprinting beitragen; Browser dürfen ihn deshalb verallgemeinern.
WebGPU steht nur in sicheren Kontexten (HTTPS) zur Verfügung.

Siehe auch

GPUAdapterInfo GPUAdapterInfo.subgroupMinSize GPUAdapter.info GPUDevice.adapterInfo GPUAdapter.requestDevice() GPUAdapter.features GPUAdapterInfo.isFallbackAdapter