WebGPU Data Input: Choosing Between Uniform and Storage Buffers

The Data Bottleneck in Compute Shaders

When designing a WebGPU compute pipeline, the primary performance bottleneck is often how data is moved from the CPU to the GPU. You must decide whether to pass your input data via a Uniform Buffer or a Storage Buffer. Choosing the wrong one can lead to immediate crashes due to buffer size limits or subtle performance degradation caused by inefficient cache utilization.

The core trade-off is between access speed for small constants and capacity for large datasets. If you attempt to pass a large array of particles through a uniform buffer, the browser will throw a validation error because uniform buffers have strict hardware-imposed size limits.

Comparison of Buffer Types

Engineering Trade-offs

When to use Uniform Buffers

Use uniforms for data that is constant across every single invocation of your shader. Examples include a projection matrix, a global time variable, or a light source position. Because GPUs use a specialized cache for uniforms, accessing this data is faster than reading from general memory. However, you must be mindful of the maxUniformBufferBindingSize limit found in device.limits.

When to use Storage Buffers

Use storage buffers for any dataset that exceeds a few kilobytes or requires modification. If your compute shader needs to update a value and save it for the next frame (like a physics simulation), a storage buffer is mandatory. Storage buffers support read_write access, allowing the GPU to write results directly back into the buffer without CPU intervention.

The Alignment Trap

Both buffer types require strict memory alignment. WebGPU follows the WGSL (WebGPU Shading Language) layout rules. For example, a vec3 in a buffer is often treated as a vec4 in terms of padding. If your JavaScript Float32Array does not account for this 16-byte alignment, your shader will read the wrong offsets, leading to corrupted visuals or incorrect calculations.

Implementation Example: Particle Position Update

In this scenario, we use a Uniform Buffer for the delta time (constant for all particles) and a Storage Buffer for the particle positions (large array, needs updating). Run this code in a browser context where a GPUDevice has already been obtained via navigator.gpu.requestAdapter() and adapter.requestDevice().

// 1. Define the Buffer Usages
const uniformBuffer = device.createBuffer({
  size: 16, // padded to 16 bytes for alignment safety
  usage: GPUBufferUsage.UNIFORM | GPUBufferUsage.COPY_DST,
});

const storageBuffer = device.createBuffer({
  size: 1000 * 16, // 1000 particles, vec3 padded to 16 bytes each
  usage: GPUBufferUsage.STORAGE | GPUBufferUsage.COPY_SRC | GPUBufferUsage.COPY_DST,
});

// 2. WGSL Shader Definition
const shaderCode = `
  struct GlobalUniforms {
    deltaTime: f32,
  };

  @group(0) @binding(0) var<uniform> globals: GlobalUniforms;
  @group(0) @binding(1) var<storage, read_write> particles: array<vec3<f32>>;

  @compute @workgroup_size(64)
  fn main(@builtin(global_invocation_id) id: vec3<u32>) {
    let index = id.x;
    if (index >= arrayLength(&particles)) { return; }
    particles[index] += vec3<f32>(0.0, 1.0, 0.0) * globals.deltaTime;
  }
`;

Note the bounds check with arrayLength: with 1000 particles and a workgroup size of 64, the dispatch launches 1024 invocations, so 24 threads would otherwise write out of bounds.

Validation and Testing

To verify your implementation is utilizing the buffers correctly, perform these checks:

• Limit Check: Log device.limits.maxUniformBufferBindingSize and device.limits.maxStorageBufferBindingSize to ensure your data fits the target hardware. These values vary by browser and GPU tier.
• Type Validation: Attempt to bind a buffer created with only GPUBufferUsage.UNIFORM to a var<storage> binding in WGSL. The browser should raise a validation error during bind group or pipeline creation, confirming type safety.
• Data Integrity: After submitting the compute pass, copy the storage buffer to a MAP_READ buffer and call buffer.mapAsync(GPUMapMode.READ) to verify the values were actually incremented by the GPU.

Limitations and Cleanup

Exact size limits and alignment behavior depend on the browser implementation and hardware tier, so always query device.limits rather than hardcoding assumptions. Since buffer creation allocates GPU memory, call buffer.destroy() when re-initializing the pipeline or resizing buffers dynamically to avoid exhausting device memory.