Compute Shaders

Motion GPU supports WebGPU compute shaders through ComputePass and PingPongComputePass. Compute passes are accepted in the same passes prop as render passes, but they always dispatch in a pre-scene phase before the base fragment shader renders.

The pass constructors are framework-agnostic and available from all entrypoints.

The stable public compute API is intentionally narrow: provide WGSL source and a dispatch strategy through ComputePass or PingPongComputePass.

Overview

Compute shaders operate on storage buffers and storage textures rather than rendering pixels. They execute a user-defined WGSL kernel across a configurable grid of workgroups.

The typical workflow:

1. Declare storage buffers in defineMaterial({ storageBuffers }).
2. Create a compute pass with new ComputePass({ compute, dispatch }).
3. Pass it to FragCanvas via the passes prop.
4. Read/write storage buffers in useFrame callbacks via state.writeStorageBuffer() and state.readStorageBuffer().

Compute-only storage textures with integer formats (*uint, *sint) automatically get fragmentVisible: false because texture_2d<f32> cannot sample integer textures (setting fragmentVisible: true on these formats throws). For float-sampled storage formats, set fragmentVisible: false explicitly to avoid reserving fragment-stage sampler/texture bindings.

ComputePass

A single-dispatch compute pass that runs a WGSL compute shader.

import { ComputePass } from '@motion-core/motion-gpu';

const computePass = new ComputePass({
  compute: `
@compute @workgroup_size(64)
fn compute(@builtin(global_invocation_id) id: vec3u) {
  let i = id.x;
  particles[i] = vec4f(f32(i) * 0.01, 0.0, 0.0, 1.0);
}
`,
  dispatch: [16] // 16 workgroups × 64 threads = 1024 invocations
});

import { ComputePass } from '@motion-core/motion-gpu';

const computePass = new ComputePass({
  compute: `
@compute @workgroup_size(64)
fn compute(@builtin(global_invocation_id) id: vec3u) {
  let i = id.x;
  particles[i] = vec4f(f32(i) * 0.01, 0.0, 0.0, 1.0);
}
`,
  dispatch: [16] // 16 workgroups × 64 threads = 1024 invocations
});

Compute shader contract

The WGSL source must contain:

1. A @compute @workgroup_size(X) (or @workgroup_size(X, Y) / @workgroup_size(X, Y, Z)) attribute.
2. A function named compute — e.g., fn compute(@builtin(global_invocation_id) id: vec3u).
3. A @builtin(global_invocation_id) parameter in the compute function signature (not only elsewhere in the module).
4. Numeric @workgroup_size dimensions as integers in valid WebGPU range (1..65535 per axis).

The library extracts the workgroup size from the attribute and validates the entrypoint at construction time.

Dispatch modes

The dispatch option controls how many workgroups are launched:

// Auto dispatch — scales with canvas resolution
const autoPass = new ComputePass({
  compute: myShader,
  dispatch: 'auto'
});

// Dynamic dispatch based on frame time
const dynamicPass = new ComputePass({
  compute: myShader,
  dispatch: (ctx) => [
    Math.ceil(ctx.width / ctx.workgroupSize[0]),
    Math.ceil(ctx.height / ctx.workgroupSize[1]),
    1
  ]
});

// Auto dispatch — scales with canvas resolution
const autoPass = new ComputePass({
  compute: myShader,
  dispatch: 'auto'
});

// Dynamic dispatch based on frame time
const dynamicPass = new ComputePass({
  compute: myShader,
  dispatch: (ctx) => [
    Math.ceil(ctx.width / ctx.workgroupSize[0]),
    Math.ceil(ctx.height / ctx.workgroupSize[1]),
    1
  ]
});

ComputeDispatchContext

Runtime API

PingPongComputePass

An iterative compute pass for simulations that require multiple compute iterations per frame (fluid dynamics, reaction-diffusion, etc.).

import { PingPongComputePass } from '@motion-core/motion-gpu';

const simulation = new PingPongComputePass({
  compute: `
@compute @workgroup_size(8, 8)
fn compute(@builtin(global_invocation_id) id: vec3u) {
  // Read from buffer A, write to buffer B (alternates each iteration)
  let value = textureLoad(simA, id.xy, 0);
  let next = value + vec4f(0.01, 0.0, 0.0, 0.0);
  textureStore(simB, id.xy, next);
}
`,
  target: 'sim',       // Texture key — engine creates simA/simB bindings
  iterations: 4,       // 4 compute iterations per frame
  dispatch: 'auto'
});

import { PingPongComputePass } from '@motion-core/motion-gpu';

const simulation = new PingPongComputePass({
  compute: `
@compute @workgroup_size(8, 8)
fn compute(@builtin(global_invocation_id) id: vec3u) {
  // Read from buffer A, write to buffer B (alternates each iteration)
  let value = textureLoad(simA, id.xy, 0);
  let next = value + vec4f(0.01, 0.0, 0.0, 0.0);
  textureStore(simB, id.xy, next);
}
`,
  target: 'sim',       // Texture key — engine creates simA/simB bindings
  iterations: 4,       // 4 compute iterations per frame
  dispatch: 'auto'
});

Options

Runtime API

Bind group layout

ComputePass shaders use this bind group layout:

fragmentVisible: false affects only fragment-stage bindings (group(0) in the render pipeline). Compute storage bindings in group(2) are still generated and bound normally.

PingPongComputePass uses generated A/B texture bindings at group(2):

Storage buffers are automatically bound in alphabetical order by name. You access them by their declared name directly in WGSL:

// Declared as: storageBuffers: { particles: { size: 4096, type: 'array<vec4f>' } }
// Available in compute shader as:
@group(1) @binding(0) var<storage, read_write> particles: array<vec4f>;
// ^ The library generates this binding automatically

// Declared as: storageBuffers: { particles: { size: 4096, type: 'array<vec4f>' } }
// Available in compute shader as:
@group(1) @binding(0) var<storage, read_write> particles: array<vec4f>;
// ^ The library generates this binding automatically

Compute + fragment integration

Compute passes and render passes coexist in the same passes array. All enabled compute passes dispatch before the scene render so that storage textures and buffers are up-to-date when the fragment shader reads them:

const material = defineMaterial({
  fragment: `
fn frag(uv: vec2f) -> vec4f {
  // Read particle data from storage buffer (read-only in fragment)
  let idx = u32(uv.x * 255.0);
  let particle = particles[idx];
  return vec4f(particle.rgb, 1.0);
}
`,
  storageBuffers: {
    particles: {
      size: 1024 * 16, // 1024 vec4f particles
      type: 'array<vec4f>',
      access: 'read-write'
    }
  }
});

const simulate = new ComputePass({
  compute: `
@compute @workgroup_size(64)
fn compute(@builtin(global_invocation_id) id: vec3u) {
  let i = id.x;
  let pos = particles[i];
  particles[i] = pos + vec4f(0.0, -0.001, 0.0, 0.0);
}
`,
  dispatch: [16]
});

const material = defineMaterial({
  fragment: `
fn frag(uv: vec2f) -> vec4f {
  // Read particle data from storage buffer (read-only in fragment)
  let idx = u32(uv.x * 255.0);
  let particle = particles[idx];
  return vec4f(particle.rgb, 1.0);
}
`,
  storageBuffers: {
    particles: {
      size: 1024 * 16, // 1024 vec4f particles
      type: 'array<vec4f>',
      access: 'read-write'
    }
  }
});

const simulate = new ComputePass({
  compute: `
@compute @workgroup_size(64)
fn compute(@builtin(global_invocation_id) id: vec3u) {
  let i = id.x;
  let pos = particles[i];
  particles[i] = pos + vec4f(0.0, -0.001, 0.0, 0.0);
}
`,
  dispatch: [16]
});

The compute pass runs first, updating the particles buffer. The fragment shader then reads the updated data for visualization.

Render graph behavior

Compute passes have kind: 'compute' in the render graph plan and behave differently from render passes:

• They do not participate in slot routing (source/target/canvas).
• They do not swap ping-pong buffers.
• They execute their compute pipeline before the base scene render.
• Their relative order against other compute passes is preserved.
• Interleaving a compute pass between two render passes in the array does not create a mid-post-process compute step.
• They share the same command encoder and submit queue as render passes.
• Compute-only pipelines render the base scene directly to canvas; they do not allocate post-process ping-pong textures or run a final blit.

Disabled compute passes (enabled: false) are fully skipped.

Error handling

Compute shader compilation errors are classified as COMPUTE_COMPILATION_FAILED with severity: 'error' and recoverable: true. They go through the same error normalization pipeline as fragment shader errors.

Structured diagnostics for compute compilation failures include:

• shaderStage: 'compute'
• computeSource (original user source)
• source mapping entries with sourceLocation.kind = 'compute'

Related docs

• Storage Buffers
• Render Passes
• Defining Materials
• Passes API