Storage buffers

Storage buffers connect CPU data, compute shaders, and fragment shaders. Declare them in the material so Motion GPU can generate bindings and allocate GPU buffers during renderer creation.

Definition

Supported types are array<f32>, array<vec2f>, array<vec3f>, array<vec4f>, array<u32>, array<i32>, array<vec4u>, and array<vec4i>.

storageBuffers: {
	particles: {
		size: 1024 * 16,
		type: 'array<vec4f>',
		access: 'read-write'
	}
}

storageBuffers: {
	particles: {
		size: 1024 * 16,
		type: 'array<vec4f>',
		access: 'read-write'
	}
}

The material definition controls allocation and fragment visibility. Fragment bindings are always var<storage, read>. Compute access is declared separately on each pass:

const integrate = new ComputePass({
	compute,
	resources: {
		particlesIn: { buffer: 'particles', access: 'storage-read' },
		forces: { buffer: 'forces', access: 'storage-read-write' }
	}
});

const integrate = new ComputePass({
	compute,
	resources: {
		particlesIn: { buffer: 'particles', access: 'storage-read' },
		forces: { buffer: 'forces', access: 'storage-read-write' }
	}
});

The map key is the WGSL alias. It can differ from the material key. storage-read generates var<storage, read> and a graph read. storage-read-write generates var<storage, read_write>, reads the imported value, and publishes a current-frame version. A material buffer declared with access: 'read' cannot be bound as storage-read-write.

Read-only descriptors accept version: 'current' | 'initial'. Current readers run after a writer in the same compute graph; initial readers run before it. A logical buffer can have only one read-write pass per graph segment.

initialData must fit in the declared size. Its contents are cloned into the material snapshot and included in the material signature.

CPU writes

state.writeStorageBuffer('particles', data, { offset: 0 });

state.writeStorageBuffer('particles', data, { offset: 0 });

Offset and data.byteLength must be finite integer multiples of four, and the write must fit inside the buffer. Writes are queued and flushed before rendering or compute dispatch. An attempted batch is cleared even if the flush or render fails; it is not replayed automatically.

Runtime writes do not rebuild the renderer. They update the initial value imported by compute for that frame.

CPU readback

const bytes = await state.readStorageBuffer('particles');

const bytes = await state.readStorageBuffer('particles');

Readback requires an initialized renderer and returns a copied ArrayBuffer. Internally it copies into a temporary MAP_READ | COPY_DST staging buffer, maps it, copies the bytes, and destroys the staging buffer. This synchronizes GPU work with the CPU and should not be used as a per-frame feedback path.

Adding or changing the buffer declaration rebuilds the renderer. Changing a pass resource topology requires a new pass instance. Read and write operations do neither. See Compute Shaders and Hooks API.