Motion GPU

API Reference

Passes API

Reference for ShaderPass, BlitPass, CopyPass, ComputePass, PingPongComputePass, and pass slot contracts.

Reference for post-processing and compute APIs shared by Svelte/React/Vue adapters and core entrypoints.

Entrypoints

Entrypoint Exports
@motion-core/motion-gpu/svelte ShaderPass, BlitPass, CopyPass, ComputePass, PingPongComputePass
@motion-core/motion-gpu/react ShaderPass, BlitPass, CopyPass, ComputePass, PingPongComputePass
@motion-core/motion-gpu/vue ShaderPass, BlitPass, CopyPass, ComputePass, PingPongComputePass
@motion-core/motion-gpu ShaderPass, BlitPass, CopyPass, ComputePass, PingPongComputePass

Shared pass options

Option Default Description
enabled true Whether pass participates in current frame plan
needsSwap true Swap source/target after execution
input 'source' Input slot (source, target, named target)
output 'target' (if swap) Output slot (source, target, canvas, named target)
clear false Clear output before drawing
clearColor [0, 0, 0, 1] RGBA clear color
preserve true Preserve output after pass

ShaderPass

Programmable post-process pass.

Required shader contract:

fn shade(inputColor: vec4f, uv: vec2f) -> vec4f
fn shade(inputColor: vec4f, uv: vec2f) -> vec4f

Additional option:

Option Type Description
fragment string Required WGSL shader source
filter GPUFilterMode Texture sampling mode

Runtime update API:

setFragment(nextFragment: string): void
setFragment(nextFragment: string): void

BlitPass

Fullscreen texture sample pass with configurable filter ('linear' or 'nearest').

CopyPass

Attempts direct GPU texture copy (copyTextureToTexture) and falls back to blit if conditions are not met.

Direct-copy path requires all of:

  • clear === false
  • preserve === true
  • source and output are different textures
  • neither surface is canvas
  • matching dimensions and format

ComputePass

GPU compute pass for single-dispatch workloads.

Required shader contract:

@compute @workgroup_size(X, Y?, Z?)
fn compute(@builtin(global_invocation_id) id: vec3u)
@compute @workgroup_size(X, Y?, Z?)
fn compute(@builtin(global_invocation_id) id: vec3u)

All three elements are validated at construction time: the @compute annotation, @workgroup_size(...), and @builtin(global_invocation_id) parameter.

Options

Option Type Default Description
compute string Required WGSL compute shader source
dispatch [number, number?, number?] 'auto' (ctx) => [number, number, number] 'auto' Workgroup dispatch strategy
enabled boolean true Whether pass is active

Runtime update API

setCompute(source: string): void
setDispatch(dispatch: ComputePassOptions['dispatch']): void
getCompute(): string
getWorkgroupSize(): [number, number, number]
resolveDispatch(ctx: ComputeDispatchContext): [number, number, number]
setCompute(source: string): void
setDispatch(dispatch: ComputePassOptions['dispatch']): void
getCompute(): string
getWorkgroupSize(): [number, number, number]
resolveDispatch(ctx: ComputeDispatchContext): [number, number, number]

ComputeDispatchContext

Field Type
width number
height number
time number
delta number
workgroupSize [number, number, number]

PingPongComputePass

Iterative compute pass for multi-step GPU simulations.

Options

Option Type Default Description
compute string Required WGSL compute shader source
target string Required Storage texture key from material.textures (storage: true). Storage texture targets require explicit width and height.
iterations number 1 Iterations per frame (must be >= 1)
dispatch dispatch mode 'auto' Workgroup dispatch strategy
enabled boolean true Whether pass is active

Runtime update API

getCurrentOutput(): string          // Texture key holding latest result ({target}A or {target}B)
advanceFrame(): void                // Advance internal counter (called by renderer)
setIterations(count: number): void
setCompute(source: string): void
setDispatch(dispatch): void
getTarget(): string
getIterations(): number
getCompute(): string
getWorkgroupSize(): [number, number, number]
resolveDispatch(ctx: ComputeDispatchContext): [number, number, number]
getCurrentOutput(): string          // Texture key holding latest result ({target}A or {target}B)
advanceFrame(): void                // Advance internal counter (called by renderer)
setIterations(count: number): void
setCompute(source: string): void
setDispatch(dispatch): void
getTarget(): string
getIterations(): number
getCompute(): string
getWorkgroupSize(): [number, number, number]
resolveDispatch(ctx: ComputeDispatchContext): [number, number, number]

Properties

Property Type Description
isCompute true Discriminant for render graph
isPingPong true Ping-pong identifier
enabled boolean Active state

Slot constraints

Rule Effect
needsSwap: true must be input: 'source' + output: 'target' Invalid combinations throw
canvas is output-only input: 'canvas' throws
Named targets must exist in renderTargets Unknown target names throw
Named targets must be written before read in frame plan Read-before-write throws

Compute passes do not participate in slot routing. They have no input, output, or needsSwap options.

Related docs