Skip to content

Commit fa9acbd

Browse files
fix(core): a multi-worker or chunked render lands every frame where an in-order render does (#6707)
* fix(core): a multi-worker or chunked render lands every frame where an in-order render does * fix(core): replay only where tweens overlap, and from any off-grid scene time * fix(core): a film with paused scenes replays only where its tweens overlap
1 parent 11312b3 commit fa9acbd

3 files changed

Lines changed: 233 additions & 2 deletions

File tree

Lines changed: 94 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,94 @@
1+
import gsap from "gsap";
2+
import { describe, expect, it } from "vitest";
3+
import { seekGsapTimeline } from "./gsap";
4+
import type { RuntimeTimelineLike } from "../types";
5+
6+
const FPS = 60;
7+
const FRAMES = 150;
8+
9+
// A zoom punch still running when a cut sets the zoom and a slower move starts from wherever the zoom is.
10+
function overlappingZoom() {
11+
const params = { z: 1 };
12+
const timeline = gsap.timeline({ paused: true });
13+
timeline.to(params, { z: 1.45, duration: 0.3, ease: "power4.out" }, 0.573);
14+
timeline.set(params, { z: 1.04 }, 0.8);
15+
timeline.to(params, { z: 1.12, duration: 1.39, ease: "power1.in" }, 0.869);
16+
return { params, timeline: timeline as unknown as RuntimeTimelineLike };
17+
}
18+
19+
/** The zoom at each frame a renderer captures, in order; a scene's clock starts at `hostStart`. */
20+
function capture(frames: number[], hostStart = 0, seekFirst?: number): Map<number, number> {
21+
const { params, timeline } = overlappingZoom();
22+
const zoom = new Map<number, number>();
23+
if (seekFirst !== undefined) seekGsapTimeline(timeline, seekFirst, true, undefined, FPS);
24+
for (const frame of frames) {
25+
seekGsapTimeline(timeline, frame / FPS - hostStart, true, undefined, FPS);
26+
zoom.set(frame, params.z);
27+
}
28+
return zoom;
29+
}
30+
31+
const range = (from: number, to: number, step = 1) =>
32+
Array.from({ length: Math.ceil((to - from) / step) }, (_, i) => from + i * step);
33+
34+
describe("a render that captures frames out of order", () => {
35+
const inOrder = capture(range(0, FRAMES));
36+
37+
it("gives every frame the same value when 8 workers each capture every 8th frame", () => {
38+
for (let worker = 0; worker < 8; worker++) {
39+
for (const [frame, z] of capture(range(worker, FRAMES, 8))) {
40+
expect([frame, z]).toEqual([frame, inOrder.get(frame)]);
41+
}
42+
}
43+
});
44+
45+
it("gives every frame the same value when a chunk starts inside the overlap", () => {
46+
for (const [frame, z] of capture(range(53, FRAMES))) {
47+
expect([frame, z]).toEqual([frame, inOrder.get(frame)]);
48+
}
49+
});
50+
51+
it("gives every frame the same value in a scene whose host starts between two frames", () => {
52+
const hostStart = 0.0125;
53+
const sceneInOrder = capture(range(1, FRAMES), hostStart);
54+
for (let worker = 0; worker < 8; worker++) {
55+
for (const [frame, z] of capture(range(worker + 1, FRAMES, 8), hostStart)) {
56+
expect(z).toBeCloseTo(sceneInOrder.get(frame)!, 9);
57+
}
58+
}
59+
});
60+
61+
it("gives every frame the same value when a scene held at 0 jumps to a chunk start between two frames", () => {
62+
const hostStart = 0.0125;
63+
const sceneInOrder = capture(range(1, FRAMES), hostStart);
64+
for (const [frame, z] of capture(range(53, FRAMES), hostStart, 0)) {
65+
expect(z).toBeCloseTo(sceneInOrder.get(frame)!, 9);
66+
}
67+
});
68+
69+
it("replays no frame when no two tweens write the same property at once", () => {
70+
const rendersOfTwoSeeks = (fps?: number) => {
71+
const [a, b, c, d] = [{ x: 0 }, { x: 0 }, { x: 0 }, { x: 0 }];
72+
const timeline = gsap.timeline({ paused: true });
73+
timeline
74+
.to(a, { x: 1, duration: 2 }, 0)
75+
.to(b, { x: 1, duration: 2 }, 0)
76+
.to(a, { x: 2, duration: 1 }, 2);
77+
const pausedScene = gsap
78+
.timeline()
79+
.to(c, { x: 1, duration: 1 })
80+
.to(c, { x: 2, duration: 1 }, 0.5);
81+
timeline.add(pausedScene, 0.3);
82+
pausedScene.pause();
83+
timeline.add(gsap.timeline({ repeat: 3, yoyo: true }).to(d, { x: 1, duration: 0.5 }), 0);
84+
const film = timeline as unknown as RuntimeTimelineLike;
85+
let renders = 0;
86+
const totalTime = film.totalTime!.bind(film);
87+
film.totalTime = (...args) => (args.length ? (renders++, totalTime(...args)) : totalTime());
88+
seekGsapTimeline(film, 0, true, undefined, fps);
89+
seekGsapTimeline(film, 170 / FPS, true, undefined, fps);
90+
return [renders, a.x, b.x, c.x, d.x];
91+
};
92+
expect(rendersOfTwoSeeks(FPS)).toEqual(rendersOfTwoSeeks());
93+
});
94+
});

‎packages/core/src/runtime/adapters/gsap.ts‎

Lines changed: 136 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -86,16 +86,151 @@ function gsapNeverRendered(timeline: RuntimeTimelineLike): boolean {
8686
return rendered !== undefined && !rendered._initted;
8787
}
8888

89+
const lastRenderSeek = new WeakMap<object, number>();
90+
const sharedPropertySpans = new WeakMap<object, { version: string; spans: [number, number][] }>();
91+
const NOT_PROPERTIES = new Set([
92+
"duration",
93+
"ease",
94+
"delay",
95+
"repeat",
96+
"repeatDelay",
97+
"yoyo",
98+
"yoyoEase",
99+
"repeatRefresh",
100+
"stagger",
101+
"overwrite",
102+
"immediateRender",
103+
"lazy",
104+
"id",
105+
"paused",
106+
"reversed",
107+
"callbackScope",
108+
"runBackwards",
109+
"data",
110+
"inherit",
111+
"defaults",
112+
]);
113+
const EVERY_PROPERTY = new Set(["keyframes", "startAt", "transform"]);
114+
const SAME_PROPERTY: Record<string, string> = {
115+
scaleX: "scale",
116+
scaleY: "scale",
117+
autoAlpha: "opacity",
118+
rotate: "rotation",
119+
};
120+
121+
type PlacedTween = GsapPlaced & {
122+
vars?: Record<string, unknown>;
123+
targets?: () => object[];
124+
};
125+
type PropertyWrite = { start: number; end: number; properties: Set<string> | null };
126+
127+
function propertiesWritten(vars: Record<string, unknown>): Set<string> | null {
128+
const properties = new Set<string>();
129+
for (const key of Object.keys(vars)) {
130+
if (EVERY_PROPERTY.has(key)) return null;
131+
if (!key.startsWith("on") && !NOT_PROPERTIES.has(key))
132+
properties.add(SAME_PROPERTY[key] ?? key);
133+
}
134+
return properties;
135+
}
136+
137+
function spanOnParent(
138+
[start, length]: [number, number],
139+
parent: GsapPlaced,
140+
): [number, number] | null {
141+
const speed = Number(parent._ts);
142+
if (!speed) return null;
143+
const [from, span] =
144+
parent._repeat || speed < 0
145+
? [0, Number(parent.totalDuration?.() ?? Infinity)]
146+
: [start, length];
147+
return [Number(parent._start) + from / Math.abs(speed), span / Math.abs(speed)];
148+
}
149+
150+
function writeOf(tween: PlacedTween, timeline: RuntimeTimelineLike): PropertyWrite | null {
151+
let span: [number, number] | null = [Number(tween._start), Number(tween.totalDuration?.() ?? 0)];
152+
for (let parent = tween.parent; span && parent && parent !== timeline; parent = parent.parent) {
153+
span = spanOnParent(span, parent);
154+
}
155+
return (
156+
span && {
157+
start: span[0],
158+
end: span[0] + span[1],
159+
properties: propertiesWritten(tween.vars ?? {}),
160+
}
161+
);
162+
}
163+
164+
function spansWhereTweensShareAProperty(timeline: RuntimeTimelineLike): [number, number][] {
165+
const writes = new Map<object, PropertyWrite[]>();
166+
for (const child of timeline.getChildren?.(true, true, false) ?? []) {
167+
const tween = child as PlacedTween;
168+
const write = writeOf(tween, timeline);
169+
if (!write) continue;
170+
for (const target of tween.targets?.() ?? [])
171+
writes.set(target, [...(writes.get(target) ?? []), write]);
172+
}
173+
return [...writes.values()].flatMap(overlapsOnOneTarget);
174+
}
175+
176+
function sharesAProperty(a: PropertyWrite, b: PropertyWrite): boolean {
177+
return !a.properties || !b.properties || [...a.properties].some((p) => b.properties!.has(p));
178+
}
179+
180+
function overlapsOnOneTarget(writes: PropertyWrite[]): [number, number][] {
181+
const spans: [number, number][] = [];
182+
writes.sort((x, y) => x.start - y.start);
183+
writes.forEach((first, i) => {
184+
for (const second of writes.slice(i + 1)) {
185+
if (second.start >= first.end) break;
186+
if (sharesAProperty(first, second))
187+
spans.push([second.start, Math.min(first.end, second.end)]);
188+
}
189+
});
190+
return spans;
191+
}
192+
193+
function framesSkippedSinceLastSeek(
194+
timeline: RuntimeTimelineLike,
195+
t: number,
196+
fps: number,
197+
version = "",
198+
): number[] {
199+
const last = lastRenderSeek.get(timeline);
200+
lastRenderSeek.set(timeline, t);
201+
const skipped =
202+
last === undefined ? Math.floor(t * fps + 1e-6) : Math.ceil((t - last) * fps - 1e-6) - 1;
203+
if (skipped < 1) return [];
204+
let cached = sharedPropertySpans.get(timeline);
205+
if (cached?.version !== version) {
206+
cached = { version, spans: spansWhereTweensShareAProperty(timeline) };
207+
sharedPropertySpans.set(timeline, cached);
208+
}
209+
const replay = new Set<number>();
210+
for (const [from, to] of cached.spans) {
211+
const nearest = Math.max(1, Math.ceil((t - to) * fps - 1e-6) - 1);
212+
const farthest = Math.min(skipped, Math.floor((t - from) * fps + 1e-6) + 1);
213+
for (let back = nearest; back <= farthest; back++) replay.add(back);
214+
}
215+
return [...replay].sort((x, y) => y - x).map((back) => t - back / fps);
216+
}
217+
89218
export function seekGsapTimeline(
90219
timeline: RuntimeTimelineLike,
91220
t: number,
92221
suppressEvents: boolean,
93222
structure?: GsapStructureKey,
223+
renderFps?: number,
94224
): boolean {
95225
if (typeof timeline.totalTime !== "function") {
96226
if (typeof timeline.seek === "function") timeline.seek(t, suppressEvents);
97227
return false;
98228
}
229+
if (renderFps) {
230+
for (const time of framesSkippedSinceLastSeek(timeline, t, renderFps, structure?.version)) {
231+
timeline.totalTime(time, suppressEvents);
232+
}
233+
}
99234
const from = Number(timeline.totalTime());
100235
timeline.totalTime(t, suppressEvents);
101236
if (t < from && structure) reapplyStepsInAuthoredOrder(timeline, structure, t);
@@ -175,6 +310,7 @@ type GsapPlaced = {
175310
_repeat?: number;
176311
parent?: GsapPlaced | null;
177312
getChildren?: unknown;
313+
totalDuration?: () => number;
178314
};
179315

180316
function startOnOwner(child: GsapPlaced, owner: object): number | null {

‎packages/core/src/runtime/init.ts‎

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -549,6 +549,7 @@ export function initSandboxRuntimeModular(): void {
549549
ensureAudioGroupInertStyle(document);
550550
ensureColorGroupInertStyle(document);
551551
const exportRenderFps = resolveExportRenderFps();
552+
const renderFps = exportRenderFps.fps ?? undefined;
552553
state.canonicalFps = exportRenderFps.fps ?? compositionFps() ?? state.canonicalFps;
553554
setRuntimeProtocolFps(state.canonicalFps);
554555
if (window.__HF_EXPORT_RENDER_SEEK_CONFIG) {
@@ -5084,7 +5085,7 @@ export function initSandboxRuntimeModular(): void {
50845085
const suppressEvents = options?.suppressEvents === true;
50855086
// Guarded: a partial timeline without pause() must still get its seek.
50865087
pauseTimelineIfPossible(timeline);
5087-
seekGsapTimeline(timeline, timeSeconds, suppressEvents, gsapStructureOf(timeline));
5088+
seekGsapTimeline(timeline, timeSeconds, suppressEvents, gsapStructureOf(timeline), renderFps);
50885089
} catch (err) {
50895090
// The scene's own callback threw. A warning, not a script error: it must not turn a
50905091
// timed-out timeline wait into a script failure.
@@ -5315,7 +5316,7 @@ export function initSandboxRuntimeModular(): void {
53155316
try {
53165317
if (typeof tl.totalTime === "function") {
53175318
const structure = gsapStructureOf(tl);
5318-
const redrawn = seekGsapTimeline(tl, tlSeekTime, suppressEvents, structure);
5319+
const redrawn = seekGsapTimeline(tl, tlSeekTime, suppressEvents, structure, renderFps);
53195320
if (!redrawn && !suppressEvents && !hasZeroDurationCallbackTween(tl, structure)) {
53205321
// The first seek is the only eventful one; the re-render only refreshes styles.
53215322
rerenderGsapTimelineAt(

0 commit comments

Comments
 (0)