Uniforms

Uniforms are the primary mechanism for passing dynamic values from your JavaScript/TypeScript runtime code into WGSL shaders. This page covers declaration, type inference, memory layout, and runtime updates.

Examples below use the same runtime uniform APIs across Svelte, React, and Vue.

Declaring uniforms

Uniforms are declared in the uniforms field of defineMaterial:

const material = defineMaterial({
  fragment: `
fn frag(uv: vec2f) -> vec4f {
  let t = sin(motiongpuUniforms.uTime * 3.0);
  let color = mix(motiongpuUniforms.uColorA, motiongpuUniforms.uColorB, t * 0.5 + 0.5);
  return vec4f(color, 1.0);
}
`,
  uniforms: {
    uTime: 0,
    uColorA: [1.0, 0.2, 0.3],
    uColorB: { type: 'vec3f', value: [0.2, 0.5, 1.0] }
  }
});

const material = defineMaterial({
  fragment: `
fn frag(uv: vec2f) -> vec4f {
  let t = sin(motiongpuUniforms.uTime * 3.0);
  let color = mix(motiongpuUniforms.uColorA, motiongpuUniforms.uColorB, t * 0.5 + 0.5);
  return vec4f(color, 1.0);
}
`,
  uniforms: {
    uTime: 0,
    uColorA: [1.0, 0.2, 0.3],
    uColorB: { type: 'vec3f', value: [0.2, 0.5, 1.0] }
  }
});

Each uniform becomes a field on the motiongpuUniforms struct. The library generates the binding struct and uniform buffer automatically.

Input forms

Motion GPU accepts two styles of uniform declaration:

Shorthand (value only)

The type is inferred from the value shape:

uniforms: {
  uTime: 0,                    // f32
  uMouse: [0.5, 0.5],          // vec2f
  uColor: [1.0, 0.5, 0.0],    // vec3f
  uTint: [1.0, 1.0, 1.0, 0.8] // vec4f
}

uniforms: {
  uTime: 0,                    // f32
  uMouse: [0.5, 0.5],          // vec2f
  uColor: [1.0, 0.5, 0.0],    // vec3f
  uTint: [1.0, 1.0, 1.0, 0.8] // vec4f
}

Explicit (type + value)

For clarity or for mat4x4f, use the explicit form:

uniforms: {
  uTime: { type: 'f32', value: 0 },
  uModelMatrix: {
    type: 'mat4x4f',
    value: [
      1, 0, 0, 0,
      0, 1, 0, 0,
      0, 0, 1, 0,
      0, 0, 0, 1
    ]
  }
}

uniforms: {
  uTime: { type: 'f32', value: 0 },
  uModelMatrix: {
    type: 'mat4x4f',
    value: [
      1, 0, 0, 0,
      0, 1, 0, 0,
      0, 0, 1, 0,
      0, 0, 0, 1
    ]
  }
}

The mat4x4f type must use explicit form — it cannot be inferred from an array length of 16.

Naming rules

All uniform identifiers must be WGSL-safe: [A-Za-z_][A-Za-z0-9_]*.

Invalid names throw at material definition time. Common conventions:

• uTime, uMouse, uColor — prefix with u for user uniforms
• motiongpuFrame.* — built-in frame uniforms (do not declare these in defineMaterial)

WGSL alignment and packing

Uniforms are packed into a single Float32Array buffer following WGSL std140-like alignment rules:

Packing behavior

1. Uniform entries are sorted alphabetically by name.
2. Each entry is placed at the next offset that satisfies its alignment requirement.
3. The total buffer size is rounded up to 16 bytes (minimum 16 bytes).

Example layout for { uA: f32, uB: vec3f, uC: vec2f } (sorted: uA, uB, uC):

Offset 0:  uA   (f32)    — 4 bytes
Offset 4:  [padding]     — 12 bytes (vec3f needs 16-byte alignment)
Offset 16: uB   (vec3f)  — 12 bytes
Offset 28: [padding]     — 4 bytes (vec2f needs 8-byte alignment, next valid is 32)
Offset 32: uC   (vec2f)  — 8 bytes
Total: 40 bytes → rounded to 48 (16-byte multiple)

Offset 0:  uA   (f32)    — 4 bytes
Offset 4:  [padding]     — 12 bytes (vec3f needs 16-byte alignment)
Offset 16: uB   (vec3f)  — 12 bytes
Offset 28: [padding]     — 4 bytes (vec2f needs 8-byte alignment, next valid is 32)
Offset 32: uC   (vec2f)  — 8 bytes
Total: 40 bytes → rounded to 48 (16-byte multiple)

You generally don’t need to think about this — it’s handled automatically. The material signature is based on uniform names and types (order does not matter because layout is sorted).

Runtime updates with setUniform

Inside a useFrame callback, use state.setUniform(name, value) to update a uniform’s value for the current frame:

Important rules

• Name must exist in the material’s uniforms map. Setting an unknown name throws.
• Value shape must match the declared type. Passing [1, 2] to an f32 uniform throws.
• Updates are merged — material defaults are used for any uniform not set during the frame.
• Dirty tracking — only changed ranges are written to the GPU buffer, minimizing upload overhead.

Built-in frame uniforms

The renderer provides a built-in motiongpuFrame uniform buffer. You do not declare it in defineMaterial:

Validation errors