Motion GPU

Getting Started

Motion GPU Documentation

Framework-agnostic WebGPU core with Svelte 5, React 18/19, and Vue 3 adapters for fullscreen WGSL rendering.

@motion-core/motion-gpu ships a framework-agnostic WebGPU core plus Svelte 5, React 18/19, and Vue 3 adapters for fullscreen WGSL rendering. You get a declarative material system, a reactive frame scheduler, a composable post-processing pipeline, and GPU compute shader support — wired into a single <FragCanvas> component in all three adapters.

This documentation was generated directly from the packages/motion-gpu/src source tree, so every contract, default value, and edge-case behavior described here reflects the actual implementation.

AI documentation access

Motion GPU documentation is also available for AI tools via Context7.

Framework mental model

Understanding the frame-by-frame flow is the single most useful thing you can learn about Motion GPU:

  1. You create an immutable material with defineMaterial({ fragment, uniforms, textures, storageBuffers, ... }).
  2. FragCanvas resolves that material and derives a pipeline signature (a deterministic string from the compiled shader, uniform layout, texture config/bindings including fragmentVisible, and storage buffer definitions).
  3. If the signature changes, the WebGPU renderer is rebuilt from scratch. If it stays the same, only uniform buffers and texture bindings are updated — no recompilation.
  4. Every animation frame:
    • Scheduler tasks run in topological order (your useFrame callbacks).
    • Runtime uniforms and textures are merged with material defaults.
    • Pending storage buffer writes are flushed to the GPU.
    • Compute passes dispatch their workgroups through the render graph.
    • The base fullscreen pass renders your fragment shader.
    • Optional post-process passes execute through the render graph.
    • The final result is presented to the canvas.

Hard contracts

These are enforced at runtime and will throw immediately if violated:

Contract Enforced by
Fragment function must be fn frag(uv: vec2f) -> vec4f defineMaterial validation
ShaderPass fragment must define fn shade(inputColor: vec4f, uv: vec2f) -> vec4f ShaderPass constructor
ComputePass shader must contain @compute @workgroup_size(...) and fn compute(...) ComputePass constructor
Storage buffer size must be > 0 and a multiple of 4 defineMaterial validation
Uniform / texture / define / include / storage buffer keys must be WGSL-safe identifiers ([A-Za-z_][A-Za-z0-9_]*) Validators in uniforms.ts, textures.ts, material-preprocess.ts, storage-buffers.ts
renderMode API contract is 'always', 'on-demand', or 'manual' Scheduler types/runtime
maxDelta > 0 and profilingWindow > 0 Scheduler assertions
Render target scale, width, height must be finite and > 0 Render-target resolver
Pass slots must reference valid surfaces (canvas output-only, named slots must exist in renderTargets) Render graph planner

Defaults worth knowing

Setting Default value
FragCanvas.clearColor [0, 0, 0, 1] (opaque black)
FragCanvas.outputColorSpace 'srgb'
FragCanvas.renderMode 'always'
FragCanvas.autoRender true
FragCanvas.maxDelta 0.1 (seconds)
FragCanvas.dpr window.devicePixelRatio (or 1 during SSR)
Texture filter 'linear'
Texture address mode 'clamp-to-edge'
Texture update mode Source-dependent: HTMLVideoElement → perFrame, everything else → once
Texture flipY true
Texture generateMipmaps false

Scope and boundaries

  • This package targets fullscreen fragment workflows and GPU compute — it is not a general-purpose scene graph or 3D engine.
  • Root entrypoints (@motion-core/motion-gpu, /advanced) are framework-agnostic core APIs.
  • Framework runtimes must be consumed via adapter entrypoints (@motion-core/motion-gpu/svelte, @motion-core/motion-gpu/react, @motion-core/motion-gpu/vue).
  • Adapter runtimes work without advanced entrypoints; @motion-core/motion-gpu/svelte/advanced, @motion-core/motion-gpu/react/advanced, and @motion-core/motion-gpu/vue/advanced add namespaced user state and extended scheduler ergonomics.
  • All documentation references behaviors currently implemented in the repository, including edge cases verified by the test suite.