Files
hyperframes/docs/concepts/frame-adapters.mdx
T
James RussoandClaude Opus 5.5 d452a6fad4 feat(registry): add path-traced-3d example with raster preview and path-traced export (#7219)
* feat(registry): add path-traced-3d example with raster preview and path-traced export

An opt-in Three.js starter: previews with raster rendering and exports with
three-gpu-pathtracer, from one scene file. three 0.180.0, three-gpu-pathtracer
0.0.24 and three-mesh-bvh 0.9.5 ship as one local, pinned ES module with their
licences and a rebuild recipe, so renders make no network requests and 2D
projects never load the tracer.

Setup is one buildReady promise that awaits library readiness promises only
and ends with a throwaway frame and a one-pixel readback. Frames are drawn in
the hf-seek listener through waitUntil, each time from zero with a fixed
sample count. Math.random is seeded while the scene and tracer are built,
because object ids order light sampling and the tracer's noise textures come
from it.

Adds a skill reference and a docs guide for the setup and seek contract, the
frozen clock, why scheduler.yield() waits hang, and sample/bounce cost.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>

* fix(registry): list path-traced-3d in CLI docs and tighten its notes

Add the example's section to the CLI examples doc, which docs.test.ts
requires for every registry example. Throw if the tracer reports compiling
but exposes no compile promise, instead of spinning renderSample(). Say that
three's object uuids set the tracer's sort order, that later-created objects
need the seed too, and that Date and performance.now read the current seek
time during a render rather than staying at 0.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
2026-11-05 06:40:37 +00:00

94 lines
2.8 KiB
Plaintext

---
title: "Frame adapters"
description: "Connect a seekable animation timeline to a custom HyperFrames host."
---
<Info>
The exported `FrameAdapter` interface is experimental v0 API. Its signatures
may change before v1.
</Info>
A frame adapter answers one question: what state should an animation have at frame N?
Most composition authors do not implement this interface. HyperFrames already seeks registered GSAP, CSS, Anime.js, Lottie, Three.js, Web Animations, and TypeGPU animation through its browser runtime. Use the [GSAP guide](/guides/gsap-animation) for the normal authoring path. For a Three.js scene with a raster preview and a path-traced export, start from the [path-traced 3D example](/guides/path-tracing).
Use `FrameAdapter` when you are building a custom host around a seekable animation object.
Rendering never plays the animation. It asks for one frame, waits, captures it,
then asks for the next — so the same frame always comes out the same.
```mermaid
sequenceDiagram
participant R as Renderer
participant A as Frame adapter
participant T as Your timeline
R->>A: getDurationFrames()
A-->>R: 120
loop every frame, in any order
R->>A: seekFrame(90)
A->>T: jump to 3.0s and settle
T-->>A: state at 3.0s
A-->>R: ready
R->>R: capture the pixels
end
R->>A: destroy()
```
## Interface
```ts
import type { FrameAdapter, FrameAdapterContext } from "@hyperframes/core";
type FrameAdapter = {
id: string;
init?: (context: FrameAdapterContext) => Promise<void> | void;
getDurationFrames: () => number;
seekFrame: (frame: number) => Promise<void> | void;
destroy?: () => Promise<void> | void;
};
```
The context contains the composition ID, frame rate, dimensions, and optional root element.
## Adapt a GSAP timeline
`@hyperframes/core` includes a helper for a GSAP-like timeline:
```ts
import { createGSAPFrameAdapter } from "@hyperframes/core";
const adapter = createGSAPFrameAdapter({
id: "intro",
fps: 30,
timeline,
});
await adapter.init?.({
compositionId: "intro",
fps: 30,
width: 1920,
height: 1080,
});
await adapter.seekFrame(90); // three seconds
```
The helper pauses the timeline, derives its frame length, and converts each frame request to seconds.
## Contract
A custom adapter must:
- return a finite, non-negative frame count;
- support forward, backward, and random seeks;
- return the same state when the same frame is requested again;
- avoid wall-clock timers and unseeded randomness;
- finish asynchronous work before the frame is captured;
- release listeners and other resources in `destroy()`.
The host still owns the capture and encoding pipeline. The adapter owns only the animation state.
## Continue
Read [Deterministic rendering](/concepts/determinism) for the timing rules or [`@hyperframes/core`](/packages/core) for the package exports.