WebGPU: Immediates

at a glance

why it exists

In a typical WebGPU draw loop, per-draw parameters — object index, material index, transform matrix — are updated every call. The standard pattern is to write these into a GPU buffer and set a bind group pointing to it. For data that changes every draw, this creates significant overhead: buffer writes, bind group updates, and descriptor validation on the critical path.

GPU hardware has long supported a concept sometimes called "push constants" (Vulkan) or "root constants" (D3D12): a small block of bytes that travel directly with a pipeline draw command, bypassing buffer and bind group machinery. WebGPU Immediates exposes this mechanism to web applications, enabling a common high-performance GPU programming pattern without workarounds.

the API

pipeline layout: declare immediate data range

When creating a pipeline layout, declare the size (in bytes) of the immediate data block the pipeline will use:

const layout = device.createPipelineLayout({
  bindGroupLayouts: [ /* ... */ ],
  immediateDataRangeByteSize: 16,  // 16 bytes = 4 × float32
});

WGSL shader: read from immediate address space

In the shader, declare a variable in the new immediate address space. The type must be a host-shareable struct:

struct DrawParams {
  object_index: u32,
  material_index: u32,
  time: f32,
  _padding: f32,
}

var<immediate> params: DrawParams;

@vertex fn vs_main(@builtin(vertex_index) vi: u32) -> @builtin(position) vec4f {
  let obj = objects[params.object_index];
  /* ... */
}

JavaScript: set data per draw

setImmediateData(offset, data) is available on GPURenderPassEncoder, GPUComputePassEncoder, and GPURenderBundleEncoder:

const passEncoder = commandEncoder.beginRenderPass(/* ... */);
passEncoder.setPipeline(pipeline);

// Per-object loop: update immediates before each draw, no bind group change
for (const [i, obj] of objects.entries()) {
  const data = new Uint32Array([i, obj.materialIndex, 0, 0]);
  passEncoder.setImmediateData(0, data);
  passEncoder.draw(obj.vertexCount);
}

passEncoder.end();

constraints

browser support

see also

• WebGPU specification
• gpuweb/gpuweb issue #5118 — Immediates proposal
• MDN: WebGPU API
• chromestatus.com — WebGPU: Immediates (5199437611794432)