[Proposal] Buffer Views and dynamic offsets

[reczkok]

Covers #1612 (dynamic and static offsets for buffers in pipelines) and #2236 (binding sub-regions, writeAt)

Buffer views

TgpuBufferView<TData>: a typed window into a region of a buffer, usable everywhere a buffer is, implementation based on existing memoryLayoutOf infrastructure (or raw byte escape-hatch)

// offset derived from the buffer's schema, validated
const thirdBoid = sceneBuffer.view(Boid, (s) => s.boids[2]);

// caller responsible for the layout claim
const chunk = pool.view(d.arrayOf(Vertex, 100), { offsetBytes: 800 });

• The sub-schema is stated explicitly, validated against the accessor (if present)
• Views inherit the parent's usage flags, at the type level and at runtime

IO

Views carry the full IO surface (write, patch, read, clear, copyFrom), scoped to the region. Region writes are nothing new, patch on the parent buffer already works. The actual additions:

• read() on a region, today reads are whole-buffer only (arguably the most useful one)
• clear() / copyFrom() on a region
• a view is a self-contained handle, a subsystem can own its slot without knowing the parent schema

const boid = sceneBuffer.view(Boid, (s) => s.boids[42]);
const snapshot = await boid.read(); // one boid
boid.clear();

Binding

Bind group entry wherever buffers are accepted, emits { buffer, offset, size } (today we always emit { buffer }). Same for .as('uniform' | 'readonly' | 'mutable') fixed usages.

const layout = tgpu.bindGroupLayout({
  particles: { storage: d.arrayOf(Particle) },
});

const pool = root.createBuffer(d.arrayOf(Particle, MAX_PARTICLES)).$usage('storage');
const active = pool.view(d.arrayOf(Particle, activeCount)); // prefix view, offset 0

const bindGroup = root.createBindGroup(layout, { particles: active });

Count change = new view + new bind group, the allocation stays. No destroy/recreate/re-upload

Vertex and index buffers

setVertexBuffer / setIndexBuffer / pipeline .with(vertexLayout, ...) / withIndexBuffer take views, extra offset/size args are view-relative. firstVertex/baseVertex already do most of the things this enables and better. Views enable some more advanced usage, like when regions of one allocation differ in format:

// one allocation, ranges suballocated per mesh, formats differ per range
const pool = root.createBuffer(d.arrayOf(d.u32, POOL_WORDS)).$usage('vertex', 'index');

const vertices = pool.view(d.arrayOf(MeshVertex, mesh.vertexCount), {
  offsetBytes: mesh.vertexBase,
});
const indices = pool.view(d.arrayOf(d.u16, mesh.indexCount), {
  offsetBytes: mesh.indexBase,
});

pipeline.with(vertexLayout, vertices).withIndexBuffer(indices).drawIndexed(mesh.indexCount);

Interop

root.unwrap(view) returns a GPUBufferBinding

Caveats:

• no view-of-view (although very addable in the future if we want)
• runtime-sized views are very funky conceptually, something to discuss if we want to support
• uniform/storage bind offsets must be multiples of the device's min*BufferOffsetAlignment. 256 is only the guaranteed max, my phone reports 32. Vertex/index views need 4b, IO doesn't care. We don't really need to validate any of it, WebGPU does

Dynamic offsets

Layout opt-in mirrors WebGPU naming:

const layout = tgpu.bindGroupLayout({
  camera: { uniform: Camera },
  transform: { uniform: Transform, hasDynamicOffset: true },
});

Offsets are a named record, converted to WebGPU's positional array by binding order internally. Keys are enforced exactly at the type level, and the parameter is required iff the layout has dynamic entries (spec requires the exact count at every setBindGroup, so a dynamic bind group can never be set without offsets):

pass.setBindGroup(bindGroup, { transform: 256 * i });
pipeline.with(bindGroup, { transform: 256 * i });

unwrap(layout) emits hasDynamicOffset and, for dynamic entries, minBindingSize from the schema, so out-of-range offsets fail at setBindGroup instead of draw.

Example: 256-stride slot arena (stride falls out of the schema), one slot-sized view, one bind group, offsets pick the slot per draw:

const TransformSlot = d.struct({ transform: d.size(256, Transform) });
const arena = root.createBuffer(d.arrayOf(TransformSlot, OBJECT_COUNT)).$usage('uniform');

const bindGroup = root.createBindGroup(layout, {
  camera: cameraBuffer,
  transform: arena.view(Transform, (slots) => slots[0].transform),
});

objects.forEach((object, i) => {
  pass.setVertexBuffer(vertexLayout, object.vertices);
  pass.setBindGroup(bindGroup, { transform: 256 * i });
  pass.draw(object.vertexCount);
});

Note the arena buffer itself never typechecks against the Transform entry, the slot-sized view is what makes it legal

Limitations:

• default budgets are tight: 8 dynamic uniform and 4 dynamic storage buffers per pipeline layout
• hasDynamicOffset: false is not a thing, the property is true or absent

[iwoplaza]

Because buffer views are something else in WebGPU, maybe the API should be .subBuffer()?

[iwoplaza]

Let's warn if the offset doesn't comply with the device's requirements during binding, so that we can skip that check in production