GPURenderPipeline.getBindGroupLayout() — Methode · JavaScript-Referenz

Signatur

GPURenderPipeline.prototype.getBindGroupLayout(index)

Beschreibung

Die Methode getBindGroupLayout() der Schnittstelle GPURenderPipeline liefert das GPUBindGroupLayout-Objekt, das zum Bind-Group-Index index der Pipeline gehört. Der Index entspricht dem Wert von @group(n) in den WGSL-Shadern der Pipeline.

Am nützlichsten ist die Methode bei Pipelines, die mit layout: "auto" erzeugt wurden. Dann leitet WebGPU die Bind-Group-Layouts selbst aus den Shadern ab. Mit getBindGroupLayout() kommst du an diese automatisch erzeugten Layouts heran und kannst passende GPUBindGroup-Objekte über device.createBindGroup() anlegen, ohne die Layouts von Hand zu beschreiben.

Wurde die Pipeline dagegen mit einem eigenen GPUPipelineLayout erstellt, gibt die Methode ein Layout zurück, das dem dort übergebenen Layout entspricht. Meist ist es dann einfacher, direkt die eigenen GPUBindGroupLayout-Objekte zu verwenden.

Parameter

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

Rückgabewert

Typ

GPUBindGroupLayout

Beschreibung

Das Bind-Group-Layout der Pipeline für den angegebenen Index. Bei einem ungültigen Index wird ein ungültiges Objekt zurückgegeben und ein Validierungsfehler ausgelöst.

Beispiele

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

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

const module = device.createShaderModule({
  code: `
    struct Uniforms { color: vec4f };
    @group(0) @binding(0) var<uniform> u: Uniforms;

    @vertex fn vs(@builtin(vertex_index) i: u32) -> @builtin(position) vec4f {
      let pos = array(vec2f(0.0, 0.5), vec2f(-0.5, -0.5), vec2f(0.5, -0.5));
      return vec4f(pos[i], 0.0, 1.0);
    }
    @fragment fn fs() -> @location(0) vec4f { return u.color; }
  `
});

const pipeline = device.createRenderPipeline({
  layout: 'auto',
  vertex: { module, entryPoint: 'vs' },
  fragment: { module, entryPoint: 'fs', targets: [{ format }] }
});

const uniformBuffer = device.createBuffer({
  size: 16,
  usage: GPUBufferUsage.UNIFORM | GPUBufferUsage.COPY_DST
});
device.queue.writeBuffer(uniformBuffer, 0, new Float32Array([1, 0.5, 0, 1]));

// Automatisch abgeleitetes Layout von @group(0) holen
const bindGroup = device.createBindGroup({
  layout: pipeline.getBindGroupLayout(0),
  entries: [{ binding: 0, resource: { buffer: uniformBuffer } }]
});

console.log(bindGroup instanceof GPUBindGroup);

true

Bind Group im Render-Pass verwenden

// Fortsetzung: pipeline, bindGroup, device, format wie oben
const canvas = document.querySelector('canvas');
const context = canvas.getContext('webgpu');
context.configure({ device, format });

const encoder = device.createCommandEncoder();
const pass = encoder.beginRenderPass({
  colorAttachments: [{
    view: context.getCurrentTexture().createView(),
    loadOp: 'clear',
    storeOp: 'store',
    clearValue: { r: 0, g: 0, b: 0, a: 1 }
  }]
});
pass.setPipeline(pipeline);
pass.setBindGroup(0, bindGroup); // Index muss zu getBindGroupLayout(0) passen
pass.draw(3);
pass.end();
device.queue.submit([encoder.finish()]);

Ungültigen Index per Fehler-Scope erkennen

device.pushErrorScope('validation');
const layout = pipeline.getBindGroupLayout(device.limits.maxBindGroups); // zu groß
const error = await device.popErrorScope();

if (error) {
  console.warn('Ungültiger Bind-Group-Index:', error.message);
}

Ungültiger Bind-Group-Index: ...

// Wichtig · Fallstricke

Automatische Layouts sind pipeline-spezifisch: Ein Layout aus getBindGroupLayout() einer "auto"-Pipeline ist nicht mit einer anderen Pipeline kompatibel, selbst wenn die Shader gleich sind. Willst du Bind Groups über mehrere Pipelines hinweg teilen, lege eigene Layouts mit device.createBindGroupLayout() und createPipelineLayout() an.
Unbenutzte Bindings fallen weg: Bei layout: "auto" kommen nur Ressourcen ins Layout, die der Einstiegspunkt tatsächlich verwendet. Deklarierte, aber nicht genutzte Variablen fehlen darin, und ein Eintrag dafür in createBindGroup() führt zu einem Validierungsfehler.
Jeder Aufruf gibt ein neues GPUBindGroupLayout-Objekt zurück, das aber gleichwertig ist. Das Ergebnis zu zwischenzuspeichern ist trotzdem sinnvoll.
Ist index größer oder gleich maxBindGroups, wird kein TypeError geworfen. Stattdessen gibt es einen Validierungsfehler auf dem Gerät. Den kannst du mit pushErrorScope() abfangen oder mit dem Ereignis uncapturederror verfolgen.
Kompatibilität: WebGPU gibt es nur in sicheren Kontexten und noch nicht in allen Browsern bzw. auf allen Plattformen. Prüfe vorher mit navigator.gpu, ob die API verfügbar ist. Dieselbe Methode gibt es auch bei GPUComputePipeline.

Siehe auch

GPURenderPipeline GPUBindGroupLayout GPUDevice.createBindGroup() GPUDevice.createRenderPipeline() GPUComputePipeline.getBindGroupLayout() GPURenderPassEncoder.setBindGroup()