GPUComputePipeline.getBindGroupLayout() — Methode · JavaScript-Referenz

Signatur

GPUComputePipeline.prototype.getBindGroupLayout(index)

Beschreibung

Die Methode getBindGroupLayout() der Schnittstelle GPUComputePipeline liefert ein GPUBindGroupLayout-Objekt. Es beschreibt, welche Ressourcen (Puffer, Texturen, Sampler) an einem bestimmten Bind-Group-Index erwartet werden, also an der Stelle, die im WGSL-Shader mit @group(n) angesprochen wird.

Am meisten bringt die Methode, wenn die Pipeline mit layout: "auto" erstellt wurde. Dann leitet WebGPU das Layout selbst aus dem Shader-Code ab, und nur mit getBindGroupLayout() kommt man an die erzeugten Layouts heran. Das zurückgegebene Layout übergibt man dann an GPUDevice.createBindGroup().

Wurde die Pipeline mit einem expliziten GPUPipelineLayout erstellt, gibt die Methode ein Layout zurück, das dem an diesem Index angegebenen GPUBindGroupLayout entspricht. In dem Fall kann man meist gleich das eigene Layout-Objekt verwenden.

Parameter

Name	Typ	Default	Beschreibung
$index Pflicht	number		Index der Bind Group (entspricht `@group(index)` im WGSL-Shader). Muss kleiner sein als `GPUSupportedLimits.maxBindGroups` (mindestens 4).

Rückgabewert

Typ

GPUBindGroupLayout

Beschreibung

Das Layout-Objekt für den angegebenen Index. Ist der Index ungültig, wird ein Validierungsfehler ausgelöst und ein ungültiges Layout-Objekt zurückgegeben.

Beispiele

Bind Group für eine Pipeline mit layout: "auto" erstellen

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

const module = device.createShaderModule({
  code: `
    @group(0) @binding(0) var<storage, read_write> daten: array<f32>;

    @compute @workgroup_size(64)
    fn main(@builtin(global_invocation_id) id: vec3u) {
      if (id.x < arrayLength(&daten)) {
        daten[id.x] = daten[id.x] * 2.0;
      }
    }
  `
});

const pipeline = device.createComputePipeline({
  layout: 'auto',
  compute: { module, entryPoint: 'main' }
});

const buffer = device.createBuffer({
  size: 1024 * 4,
  usage: GPUBufferUsage.STORAGE | GPUBufferUsage.COPY_SRC | GPUBufferUsage.COPY_DST
});

// Automatisch erzeugtes Layout für @group(0) abfragen
const bindGroup = device.createBindGroup({
  layout: pipeline.getBindGroupLayout(0),
  entries: [{ binding: 0, resource: { buffer } }]
});

console.log(bindGroup instanceof GPUBindGroup);

true

Pipeline mit Bind Group ausführen

// Setzt voraus: device, pipeline, bindGroup aus dem vorigen Beispiel
const encoder = device.createCommandEncoder();
const pass = encoder.beginComputePass();
pass.setPipeline(pipeline);
pass.setBindGroup(0, bindGroup);
pass.dispatchWorkgroups(Math.ceil(1024 / 64));
pass.end();

device.queue.submit([encoder.finish()]);
await device.queue.onSubmittedWorkDone();
console.log('Compute-Pass fertig');

Compute-Pass fertig

Ungültigen Index über Fehler-Scope erkennen

device.pushErrorScope('validation');

// Index 7 liegt über maxBindGroups (Standard: 4)
const layout = pipeline.getBindGroupLayout(7);

const fehler = await device.popErrorScope();
if (fehler) {
  console.warn('Validierungsfehler:', fehler.message);
}

Validierungsfehler: ... (genaue Meldung je nach Browser)

// Wichtig · Fallstricke

Kein Exception-Wurf: Bei einem ungültigen Index löst die Methode keine JavaScript-Exception aus. Sie erzeugt einen WebGPU-Validierungsfehler, den man mit pushErrorScope()/popErrorScope() oder über das Ereignis uncapturederror abfängt.
Automatische Layouts lassen sich nicht teilen: Ein Layout, das über layout: "auto" entsteht, passt nur zu genau der Pipeline, von der es stammt. Eine Bind Group dazu kann man nicht mit einer anderen Pipeline verwenden, auch wenn der Shader gleich aussieht. Wer Bind Groups zwischen Pipelines teilen will, braucht ein explizites GPUPipelineLayout.
Nicht verwendete Bindings fallen weg: Der Compiler kann Bindings entfernen, die im Einstiegspunkt nicht genutzt werden. Dann fehlen sie im automatischen Layout, und createBindGroup() scheitert, wenn man sie trotzdem übergibt.
Bei jedem Aufruf kann ein neues Objekt zurückkommen. Man sollte also nicht mit === vergleichen, sondern das Ergebnis lieber zwischenspeichern.
Kompatibilität: WebGPU gibt es nur in sicheren Kontexten und noch nicht in allen Browsern. Vorher mit if (!navigator.gpu) prüfen, ob die API vorhanden ist.

Siehe auch

GPUComputePipeline GPURenderPipeline.getBindGroupLayout() GPUBindGroupLayout GPUDevice.createBindGroup() GPUDevice.createComputePipeline() GPUDevice.createPipelineLayout()