VFX

Creates VFX instance and start playing immediately. When the user prefers reduced motion, it renders nothing: elements stay plain HTML and transitions cut to the new content.

The output canvas VFX renders into.

Current virtual animation time in seconds (the value behind the time uniform).

Playback rate of the animation clock.

1 is realtime, 0 pauses (frames still render), and negative values run time backwards. Can be changed at any time.

Note: deltaTime follows this rate, so it goes negative while rewinding. Time-only effects handle that fine; effects that integrate motion over deltaTime (particles, fluid, datamosh) are not designed to run backwards and may behave unexpectedly.

Register an element to track the position and render visual effects in the area.

Register an element using html-in-canvas API. Wraps the element in a <canvas layoutsubtree content="drawable"> and captures via drawElementImage. Falls back to add() if html-in-canvas is not supported.

Animate an element from its old content to its new content with a shader. The element is wrapped only while a run is in flight, unless keepWrapped is set.

const t = vfx.addTransition(main, { duration: 0.6 });
await t.run(() => renderNextPage());

Capture an element as a texture without drawing it. Any effect of this VFX instance can read the texture. Resolves after the first capture is in the texture.

<img>, <video> and <canvas> are uploaded as they are. Other elements are captured with html-in-canvas when the browser supports it (like VFX.addHTML), or else with one DOM snapshot (like VFX.add). Call update() on the snapshot after the element changes.

const page = await vfx.capture(article, { hide: true });
await vfx.add(minimap, {
    effect: myEffect,
    uniforms: { page: page.texture },
});
// Later:
page.dispose();

The texture works on the effect path (effect) only, and only in this VFX instance.

Rejects when the element already has a capture in this instance, when addHTML or a transition wraps it, when add has it (unless it is an <img>, <video> or <canvas> captured without hide), or when the first capture fails. add rejects a captured element under the same rule. When the user prefers reduced motion, it resolves to a handle that leaves the element alone and samples as transparent.

Destroy VFX and stop rendering.

Start rendering VFX.

Remove the element from VFX and stop rendering the shader.

Render the whole scene once, manually. This is useful when you want to control the rendering timings manually by combining with autoplay: false.

Pin the animation clock to an absolute time in seconds.

The next render() uses the value verbatim, so setTime(t); render() produces a deterministic frame — handy for scrubbing a timeline or capturing stable snapshots (e.g. visual regression tests):

const vfx = new VFX({ autoplay: false });
await vfx.add(img, { effect });
vfx.setTime(1.5);
vfx.render();

Note: this drives deltaTime too, so a jump produces one large deltaTime on the next frame. Time-only effects are unaffected, but effects that integrate motion over deltaTime (particles, fluid, datamosh) may jump — pause first (timeScale = 0) when scrubbing them.

Stop rendering VFX. You can restart rendering by calling VFX.play() later.

Update the texture for the given element.

For an HTMLImageElement, reloads its currently selected image URL — call this after changing img.src or when responsive image selection changes. Videos refresh automatically (no-op). Otherwise re-snapshots the element's DOM subtree. For html-in-canvas elements, resolves once the new capture is in the texture, or after a short timeout.

Useful for elements whose contents change (input, textarea, or an <img> whose selected source swaps).

Replace the effect chain on an already-registered effect-path element in-place. Effects whose reference is unchanged keep their init state and GPU resources; only added/removed effects run init / dispose. The element's source texture is preserved.

Useful for live UIs that reorder or toggle effects without paying the cost of vfx.remove + vfx.add (which reloads the source).

Create a VFX instance if WebGL is available, or return null.