Correct way with $usage and storage buffers

[Aystein]

Problem:
I tried to use a storage buffer (something like @group(0) @binding(0) var<storage, read> testBuffer) in my vertex shader. I created the buffer using

root.createBuffer...

This resulted in the binding not being created, when I added the buffer via $uses({ testBuffer: ... }) of the vertex function.

However, I tried to use root.createReadonly..., which worked fine and created the correct bindings. Is this intended behavior, and therefore I just missused the API before?

[iwoplaza]

Good question! Storage buffers themselves cannot be directly used in shaders, you need additional context of how it's going to be used: readonly/mutable.

You can do so one of two ways:

Bind group layout

Define a bind group layout with the data required by the shader, shader uses values from the layout, and the buffer is provided in a bind group

const layout = tgpu.bindGroupLayout({
  foo: { storage: d.f32, access: 'mutable' /* or 'readonly', depending on what you require */ },
});

// #1 use
tgpu.resolve({
  template: `
    fn main() {
      layout.$.foo = 1f;
    }`,
  externals: { layout },
}) ;

// #2 use
const baz = tgpu.fn([])`() {
  layout.$.foo = 1f;
}
`.$uses({ layout });

// #3 use
function baz() {
  'use gpu';
  layout.$.foo = 1;
}

// Then later...
const fooBuffer = root.createBuffer(d.f32).$usage('storage');
const group = root.createBindGroup(layout, { foo: fooBuffer });
// ...

Fixed usage

"Fix" a specific buffer to be used in a shader. This limits you from swapping what foo points to between shader invocations, but if the buffer you access doesn't change (which is often), then this is a simpler approach.

const fooBuffer = root.createBuffer(d.f32).$usage('storage');
const fooMutable = fooBuffer.as('mutable');
// or: const fooReadonly = fooBuffer.as('readonly');

// #1 use
tgpu.resolve({
  template: `
    fn main() {
      fooMutable.$ = 1f;
    }`,
  externals: { layout },
}) ;

// #2 use
const baz = tgpu.fn([])`() {
  fooMutable.$ = 1f;
}
`.$uses({ layout });

// #3 use
function baz() {
  'use gpu';
  fooMutable.$ = 1;
}

The API you encountered is a shorthand version of creating a buffer and then retrieving a single "usage" out of it. Normally buffers can be used in multiple ways, but it's common for a buffer to only be a "uniform" buffer, or a "mutable storage" buffer, which is where this shorthand API comes in handy.

const fooBuffer = root.createBuffer(d.f32).$usage('storage');
const fooMutable = root.createMutable(d.f32);
// or: const fooReadonly = root.createReadonly(d.f32);

// #1 use
tgpu.resolve({
  template: `
    fn main() {
      fooMutable.$ = 1f;
    }`,
  externals: { layout },
}) ;

// #2 use
const baz = tgpu.fn([])`() {
  fooMutable.$ = 1f;
}
`.$uses({ layout });

// #3 use
function baz() {
  'use gpu';
  fooMutable.$ = 1;
}

I would be happy to guide you through more of how these buffers can be used, but I would benefit from knowing more of which approach to shader building you're choosing. ('#1 use', '#2 use', '#3 use' or something else entirely).

More docs to reference:

• https://typegpu.com/fundamentals/bind-groups/#storage
• https://typegpu.com/fundamentals/buffers/#binding-buffers

[Aystein]

Thanks for your reploy, that explains a lot.

I am mainly using #2. My buffer is always used as storage buffer for particles, so I guess your last example makes most sense for me