mirror of
https://github.com/heygen-com/hyperframes.git
synced 2026-11-18 07:50:13 +00:00
* 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>
94 lines
2.8 KiB
Plaintext
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.
|