Bind Groups

Recommended reading

We assume that you are familiar with the following concepts:

• WebGPU Fundamentals
• Bind Group Layouts

A bind group is a collection of resources that are bound to a shader. These resources can be buffers, textures, or samplers. It’s a way to define what resources are available to a shader and how they are accessed.

import tgpu, { d } from 'typegpu';

// Defining the layout of resources we want the shader to
// have access to.
const fooLayout = tgpu.bindGroupLayout({
  foo: { uniform: d.vec3f },
  bar: { texture: d.texture2d(d.f32) },
});

const fooBuffer = ...;
const barTexture = ...;

// Create a bind group that can fulfill the required layout.
const fooBindGroup = root.createBindGroup(fooLayout, {
  foo: fooBuffer,
  bar: barTexture,
});

In this example, we create a bind group that contains a buffer and a texture. Binding indices are determined based on the order of properties in the layout.

Tip

To access the entries in fooLayout from a shader, the corresponding WGSL code would look like this:

@group(...) @binding(0) var<uniform> foo: vec3f;
@group(...) @binding(1) var bar: texture_2d;

Where @group(...) would contain the group index given when creating the pipeline layout.

Now, during command encoding, we can assign this bind group to a shader.

// Assuming group index is 0...
pass.setBindGroup(0, root.unwrap(fooBindGroup));

Available resource types

Tip

If you already have a file with WGSL shader code, you can use the tgpu-gen CLI package to generate the equivalent TypeGPU code. To learn more about the TypeGPU Generator CLI, check the Generator CLI guide.

Each property in the layout object represents a resource as seen by a shader. We recommend keeping the names of these properties the same as the corresponding @group(...) @binding(...) ...; statements in WGSL.

const fooLayout = tgpu.bindGroupLayout({
  key0: { ... },
  key1: { ... },
  // ...
});

Uniforms

To interpret a buffer as a uniform, create a property with the value matching:

{
  uniform: d.AnyData;
}

Simple example

main.js

const fooLayout = tgpu.bindGroupLayout({
  luckyNumber: { uniform: d.f32 },
  // ...
});

Matching WGSL statement:

shader.wgsl

@group(...) @binding(0) var<uniform> luckyNumber: f32;
// ...

Storage

To get readonly/mutable access to a buffer, create a property with the value matching:

{
  storage: d.AnyData | ((n: number) => d.AnyData);

  /** @default 'readonly' */
  access?: 'readonly' | 'mutable';
}

Simple example

const fooLayout = tgpu.bindGroupLayout({
  counter: { storage: d.f32, access: 'mutable' },
  // ...
});

Matching WGSL statement:

@group(...) @binding(0) var<storage, read_write> counter: f32;
// ...

Runtime-sized example

Apart from being able to specify any data type, we can signal that the shader is generalized to work on arbitrarily sized data by passing a function.

Note

Runtime-sized arrays are only usable with storage buffers.

main.ts

const Filter = (n: number) =>
  d.struct({
    clamp: d.f32,
    values: d.arrayOf(d.f32, n),
  });

const fooLayout = tgpu.bindGroupLayout({
  factors: { storage: (n: number) => d.arrayOf(d.f32, n) },
  filter: { storage: Filter },
  // ...
});

You don’t have to write arrow functions every time, d.arrayOf(schema) is a convenient shorthand for that.

main.ts

const Filter = (n: number) =>
  d.struct({
    clamp: d.f32,
    // Unfortunately, in structs, you cannot simply write d.arrayOf(d.f32)
    values: d.arrayOf(d.f32, n),
  });

const fooLayout = tgpu.bindGroupLayout({
  factors: { storage: (n: number) => d.arrayOf(d.f32, n) },
  factors: { storage: d.arrayOf(d.f32) },
  filter: { storage: Filter },
  // ...
});

Matching WGSL code:

shader.wgsl

struct Filter {
  clamp: f32,
  values: array<f32>;
}

@group(...) @binding(0) var<storage, read> factors: array<f32>;
@group(...) @binding(1) var<storage, read> filter: Filter;
// ...

Samplers

Samplers can be made accessible to shaders with a property that matches the following:

{
  sampler: 'filtering' | 'non-filtering' | 'comparison';
}

Textures

To be able to sample a texture in a shader, create a property with the corresponding schema:

{
  texture: d.WgslTexture;
  // for example:
  // texture: d.texture2d(d.f32);
  // texture: d.textureCubeArray(d.f32);
  // texture: d.texture3d(d.i32);

  /** @default 'float' */
  sampleType?: 'float' | 'unfilterable-float'; // only for float textures
}

Storage Textures

To be able to operate on textures more directly in a shader, create a property with the corresponding schema:

{
  storageTexture: d.WgslStorageTexture;
  // for example:
  // storageTexture: d.storageTexture2d('rgba8unorm');
  // storageTexture: d.storageTextureCube('r32float', 'read-write');
  // storageTexture: d.storageTexture2dArray('rgba16float', 'read-only');
}

You can see the list of supported storage texture formats here.

External Textures

External textures provide efficient, zero-copy shader access to sources such as video frames. Declare them with d.textureExternal() and bind the GPUExternalTexture returned by WebGPU:

const videoLayout = tgpu.bindGroupLayout({
  frame: { externalTexture: d.textureExternal() },
  sampler: { sampler: 'filtering' },
});

const externalFrame = root.device.importExternalTexture({
  source: videoElement,
});

const videoGroup = root.createBindGroup(videoLayout, {
  frame: externalFrame,
  sampler: root.createSampler({ magFilter: 'linear', minFilter: 'linear' }),
});

In shader code, external textures support std.textureLoad and std.textureSampleBaseClampToEdge.

Caution

A GPUExternalTexture represents a current external-image snapshot and will expire. For animated sources such as video, import and bind the current frame as part of each frame’s rendering work instead of retaining one indefinitely.

Bind Groups

Before execution of a pipeline, any bind group that matches a given layout can be put in its place and used by the shader. To create a bind group, you can call the createBindGroup method on the root object and associate each named key with a proper resource.

const fooLayout = tgpu.bindGroupLayout({
  key0: { ... },
  key1: { ... },
  // ...
});

const fooBindGroup0 = root.createBindGroup(fooLayout, {
  key1: ...,
  key0: ...,
  // ...
});

const fooBindGroup1 = root.createBindGroup(fooLayout, {
  key0: ...,
  key1: ...,
  // ...
});

// ...

If you accidentally pass the wrong type of resource, the TypeScript compiler will catch the error at compile time.

• Uniform bindings with schema TData accept:
  • TgpuBuffer<TData> & UniformFlag - buffers of type TData with 'uniform' usage,
  • GPUBuffer - raw WebGPU buffers.
• Storage bindings with schema TData accept:
  • TgpuBuffer<TData> & StorageFlag - buffers of type TData with 'storage' usage,
  • GPUBuffer - raw WebGPU buffers.
• Texture bindings:
  • GPUTextureView - views of raw WebGPU textures.
• Storage Texture bindings:
  • GPUTextureView - views of raw WebGPU textures.
• Sampler bindings:
  • sampler === 'comparison'
    • GPUSampler - raw WebGPU samplers created with a compare function.
  • sampler === 'filtering' or sampler === 'non-filtering'
    • GPUSampler - raw WebGPU samplers created without a compare function.
• External Texture bindings:
  • GPUExternalTexture - imported with device.importExternalTexture(...).