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 render-pass options

ShaderPass, BlitPass, and CopyPass share these post-scene render-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.

Compute passes are renderer-managed pre-scene workloads. The public extension point is the WGSL source plus dispatch strategy passed to ComputePass or PingPongComputePass.

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 pre-scene compute planning
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, and they always dispatch before the base scene render. Render pass order is preserved only within the post-scene render-pass group.

Related docs