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
});

Dictionary member name disagreement, both sides reported rather than resolved (fetched 2026-10-07): this page documents immediateDataRangeByteSize in the pipeline layout descriptor, while the cited WebGPU specification declares GPUSize32 immediateSize = 0. Neither side is adjudicated here.

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();

API name disagreement, both sides reported rather than resolved (fetched 2026-10-07): this page documents setImmediateData(offset, data) on render passes, compute passes and render bundle encoders, while the cited WebGPU specification defines setImmediates(rangeOffset, data, dataOffset, dataSize). Neither side is adjudicated here.

constraints

Device limit name and value disagreement, both sides reported rather than resolved (fetched 2026-10-07): this page documents the device limit maxImmediateDataRangeByteSize with at least 128 bytes guaranteed, while the cited WebGPU specification declares maxImmediateSize with a default of 64 bytes. Neither side is adjudicated here.

browser support

see also

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