Motion GPU

API Reference

API Reference

Complete reference of all public exports from the motion-gpu packages.

Reference of public exports from

@motion-core/motion-gpu
and
@motion-core/motion-gpu/advanced
.

Package metadata

Field Value
Package name
@motion-core/motion-gpu
Current version
0.1.0
Module type ESM
Peer dependency
svelte ^5

Root exports (
@motion-core/motion-gpu
)

Export Kind Summary
FragCanvas
 Svelte component Main runtime orchestrator. See FragCanvas Reference.
defineMaterial
 function Validates and freezes material definitions. See Defining Materials.
BlitPass
 class Fullscreen texture sample pass. See Render Passes.
CopyPass
 class Copy pass with direct-copy optimisation + blit fallback. See Render Passes.
ShaderPass
 class Programmable post-process pass. See Render Passes.
useMotionGPU
 hook Reads runtime context. See Hooks and Context.
useFrame
 hook Registers scheduler tasks. See Frame Scheduler.
useTexture
 hook Loads URL textures reactively. See Loading Textures.

Advanced exports (
@motion-core/motion-gpu/advanced
)

Re-exports everything from root, plus:

Export Kind Summary
applySchedulerPreset
 function Applies named scheduler timing preset with optional overrides.
captureSchedulerDebugSnapshot
 function Returns aggregate scheduler debug payload (
schedule
, timings, profiling snapshot).
useMotionGPUUserContext
 hook Namespaced shared runtime user state. See User Context.
setMotionGPUUserContext
 function Writes namespaced user context values with explicit conflict strategy.
SchedulerPreset
 type Preset name union:
'performance'
'balanced'
'debug'
.
SchedulerPresetConfig
 type Resolved diagnostics/profiling settings after preset apply.
ApplySchedulerPresetOptions
 type Optional override fields for preset application.
SchedulerDebugSnapshot
 type Snapshot shape returned by
captureSchedulerDebugSnapshot
.
MotionGPUUserContext
 type Writable user context store type.
MotionGPUUserNamespace
 type Namespace key type (
string
symbol
).
SetMotionGPUUserContextOptions
 type Conflict strategy options.
FrameProfilingSnapshot
 type Rolling profiling data shape.
FrameRunTimings
 type Single-frame timing data shape.
FrameScheduleSnapshot
 type Schedule inspection result shape.
FrameStage
 type Stage metadata.
FrameStageCallback
 type Stage wrapper callback type.
FrameKey
 type Stable task/stage key type.
FrameTask
 type Registered task metadata.
FrameTaskInvalidation
 type Task invalidation policy.
FrameTaskInvalidationToken
 type Invalidation token type.
RenderPassContext
 type Context passed to render passes.
RenderTarget
 type Runtime render target handle.
UniformLayout
 type Resolved uniform buffer layout.
UniformLayoutEntry
 type Single uniform layout entry.

defineMaterial(input)
signature

Input:
FragMaterialInput

Field Type Required
fragment
string
 Yes
uniforms
UniformMap
 No
textures
TextureDefinitionMap
 No
defines
MaterialDefines
 No
includes
MaterialIncludes
 No

Output:
FragMaterial

Immutable, validated, with frozen top-level maps. Contains:

  • fragment
    — original WGSL source (validated, not preprocessed)
  • uniforms
    — normalized uniform map
  • textures
    — normalized texture definition map
  • defines
    — normalized defines
  • includes
    — normalized includes

signature
and preprocessed fragment source are internal
resolveMaterial(...)
outputs, not fields on public
FragMaterial
.

useFrame
signatures

useFrame(callback: (state: FrameState) => void, options?: UseFrameOptions)
useFrame(key: FrameKey, callback: (state: FrameState) => void, options?: UseFrameOptions)
useFrame(callback: (state: FrameState) => void, options?: UseFrameOptions)
useFrame(key: FrameKey, callback: (state: FrameState) => void, options?: UseFrameOptions)

UseFrameOptions

Field Type Default
autoStart
boolean
true
autoInvalidate
boolean
true
invalidation
FrameTaskInvalidation
 Implicit
stage
FrameKey
FrameStage
 Main stage
before
 task ref or list
undefined
after
 task ref or list
undefined
running
() => boolean
undefined

Dependency validation is strict: cyclic graphs and missing

before
/
after
references throw.

Return:
UseFrameResult

Field Type
task
{ key: FrameKey; stage: FrameKey }
start
() => void
stop
() => void
started
Readable<boolean>

FrameState
(useFrame callback parameter)

Field Type
time
number
delta
number
canvas
HTMLCanvasElement
renderMode
RenderMode
autoRender
boolean
setUniform
(name: string, value: UniformValue) => void
setTexture
(name: string, value: TextureValue) => void
invalidate
(token?: FrameInvalidationToken) => void
advance
() => void

useMotionGPU()
return:
MotionGPUContext

Field Type
canvas
HTMLCanvasElement
undefined
size
CurrentReadable<{ width: number; height: number }>
dpr
CurrentWritable<number>
maxDelta
CurrentWritable<number>
renderMode
CurrentWritable<RenderMode>
autoRender
CurrentWritable<boolean>
user
CurrentWritable<Record<string
symbol, unknown>>
invalidate
() => void
advance
() => void
scheduler
 Scheduler API

applySchedulerPreset
signature

applySchedulerPreset(
  scheduler: MotionGPUScheduler,
  preset: SchedulerPreset,
  options?: ApplySchedulerPresetOptions
): SchedulerPresetConfig
applySchedulerPreset(
  scheduler: MotionGPUScheduler,
  preset: SchedulerPreset,
  options?: ApplySchedulerPresetOptions
): SchedulerPresetConfig

SchedulerPreset

'performance' | 'balanced' | 'debug'
'performance' | 'balanced' | 'debug'

ApplySchedulerPresetOptions

Field Type Notes
diagnosticsEnabled
boolean
 Must match
profilingEnabled
in the current runtime
profilingEnabled
boolean
 Must match
diagnosticsEnabled
in the current runtime
profilingWindow
number
 Finite,
> 0
, rounded down to integer

SchedulerPresetConfig

Field Type
diagnosticsEnabled
boolean
profilingEnabled
boolean
profilingWindow
number

captureSchedulerDebugSnapshot
signature

captureSchedulerDebugSnapshot(
  scheduler: MotionGPUScheduler
): SchedulerDebugSnapshot
captureSchedulerDebugSnapshot(
  scheduler: MotionGPUScheduler
): SchedulerDebugSnapshot

SchedulerDebugSnapshot

Field Type
diagnosticsEnabled
boolean
profilingEnabled
boolean
profilingWindow
number
schedule
FrameScheduleSnapshot
lastRunTimings
FrameRunTimings
null
profilingSnapshot
FrameProfilingSnapshot
null

useTexture(urlInput, options?)
signature

URL input

Form Type
Static
string[]
Dynamic
() => string[]

TextureLoadOptions

Field Type Default
colorSpace
'srgb'
'linear'
'srgb'
requestInit
RequestInit
undefined
decode
TextureDecodeOptions
 Auto
signal
AbortSignal
undefined
update
TextureUpdateMode
undefined
flipY
boolean
undefined
premultipliedAlpha
boolean
undefined
generateMipmaps
boolean
undefined

Return:
UseTextureResult

Field Type
textures
CurrentReadable<LoadedTexture[]
null>
loading
CurrentReadable<boolean>
error
CurrentReadable<Error
null>
reload
() => Promise<void>

useMotionGPUUserContext
signatures

useMotionGPUUserContext(): CurrentReadable<Record<MotionGPUUserNamespace, unknown>>
useMotionGPUUserContext<T>(namespace: MotionGPUUserNamespace): CurrentReadable<T | undefined>
useMotionGPUUserContext(): CurrentReadable<Record<MotionGPUUserNamespace, unknown>>
useMotionGPUUserContext<T>(namespace: MotionGPUUserNamespace): CurrentReadable<T | undefined>

setMotionGPUUserContext
signature

setMotionGPUUserContext<T>(
  namespace: MotionGPUUserNamespace,
  value: T | (() => T),
  options?: SetMotionGPUUserContextOptions
): T | undefined
setMotionGPUUserContext<T>(
  namespace: MotionGPUUserNamespace,
  value: T | (() => T),
  options?: SetMotionGPUUserContextOptions
): T | undefined

SetMotionGPUUserContextOptions

Field Values Default
existing
'skip'
'replace'
'merge'
'skip'

Core type groups

Uniforms

Type Description
UniformType
'f32'
'vec2f'
'vec3f'
'vec4f'
'mat4x4f'
UniformValue
number
[number, number]
[number, number, number]
[number, number, number, number]
TypedUniform<...>
UniformMat4Value
number[]
Float32Array
UniformMap
Record<string, UniformValue>
UniformLayout
{ entries: UniformLayoutEntry[]; byName: Record<string, UniformLayoutEntry>; byteLength: number }

Textures

Type Description
TextureValue
TextureData
TextureSource
null
TextureDefinition
 Sampler config, update mode, colour space, etc.
TextureDefinitionMap
Record<string, TextureDefinition>
TextureUpdateMode
'once'
'onInvalidate'
'perFrame'

Passes

Type Description
RenderPass
 Interface with
render(context)
,
setSize(w, h)
,
dispose()
RenderPassFlags
 Optional
clear
,
clearColor
,
preserve
flags
RenderPassInputSlot
'source'
'target'
<targetName>
RenderPassOutputSlot
'source'
'target'
'canvas'
<targetName>
RenderPassContext
 Context object passed to
render()
RenderTargetDefinition
{ width?, height?, scale?, format? }
RenderTargetDefinitionMap
Record<string, { width?, height?, scale?, format? }>

Pass-slot constraints:

  • needsSwap: true
    requires
    input: 'source'
    and
    output: 'target'
    .
  • canvas
    is output-only.
  • <targetName>
    must be declared in
    renderTargets
    .

Scheduler

Type Description
RenderMode
'always'
'on-demand'
'manual'
FrameState
 Callback parameter with timing, canvas, and runtime API
FrameKey
string
symbol
FrameInvalidationToken
string
number
symbol
UseFrameResult
 Return type of
useFrame
(
task
,
start
,
stop
,
started
)
FrameRunTimings
 Single-frame measurement
FrameProfilingSnapshot
 Rolling stats (
last
,
avg
,
min
,
max
,
count
)
FrameTimingStats
 Timing stat tuple (
last
,
avg
,
min
,
max
,
count
)
SchedulerPreset
'performance'
'balanced'
'debug'
SchedulerPresetConfig
 Resolved diagnostics/profiling/window values
ApplySchedulerPresetOptions
 Optional diagnostics/profiling/window overrides
SchedulerDebugSnapshot
 Aggregate debug payload from
captureSchedulerDebugSnapshot

Additional exported types

Type Description
OutputColorSpace
'srgb'
'linear'
TextureMap
 Runtime texture map (
Record<string, TextureValue>
)
TextureUrlInput
string[]
(() => string[])
MaterialDefineValue
boolean
number
TypedMaterialDefineValue
TypedMaterialDefineValue
 Typed define literal (
bool
/
f32
/
i32
/
u32
)