Uniforms

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

Declaring uniforms

Uniforms are declared in the

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

Input forms

MotionGPU 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

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

Naming rules

All uniform identifiers must be WGSL-safe:

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

Packing behaviour

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

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

<script lang="ts">
  import { useFrame } from '@motion-core/motion-gpu';

  useFrame((state) => {
    state.setUniform('uTime', state.time);
    state.setUniform('uMouse', [mouseX, mouseY]);
  });
</script>

<script lang="ts">
  import { useFrame } from '@motion-core/motion-gpu';

  useFrame((state) => {
    state.setUniform('uTime', state.time);
    state.setUniform('uMouse', [mouseX, mouseY]);
  });
</script>

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

Validation errors