Skip to content

Record your screen, ship a demo. Free and open-source, GPU-accelerated, no watermarks, no subscriptions. Windows, macOS, Linux. Actively maintained.

perf(preview): pull frames by the clock, not by display ticks

EtienneLescotbeddfc20341f
diff --git a/src/native/hooks/useNativeCompositorView.test.ts b/src/native/hooks/useNativeCompositorView.test.ts
index ac182aceb..7d2b0e756 100644
--- a/src/native/hooks/useNativeCompositorView.test.ts
+++ b/src/native/hooks/useNativeCompositorView.test.ts
@@ -442,4 +442,124 @@ describe("useNativeCompositorView", () => {
expect(context(ref).drawImage).not.toHaveBeenCalled();
});
});
+
+ // The display sets the rAF rate and the recording the frame rate. Counting ticks pulled 280
+ // times a second on a 280 Hz display, idle or not.
+ describe("pull cadence, by the clock rather than by ticks", () => {
+ /** rAF driven by hand, at `periodMs`: callbacks run with the timestamps a display of that
+ * rate would give them. */
+ function manualFrames() {
+ let queue: FrameRequestCallback[] = [];
+ vi.stubGlobal("requestAnimationFrame", (callback: FrameRequestCallback) => {
+ queue.push(callback);
+ return queue.length;
+ });
+ vi.stubGlobal("cancelAnimationFrame", () => undefined);
+ return async (durationMs: number, periodMs: number, start = 0) => {
+ for (let t = start; t < start + durationMs; t += periodMs) {
+ const due = queue;
+ queue = [];
+ for (const callback of due) {
+ callback(t);
+ }
+ // Let each pull's reply land before the next tick, as it would between frames.
+ for (let flush = 0; flush < 4; flush++) {
+ await Promise.resolve();
+ }
+ }
+ };
+ }
+
+ async function mountedView() {
+ mocks.createCompositorView.mockResolvedValue({ id: 7 });
+ const ref = stubCanvasRef();
+ const { result } = renderHook(() =>
+ useNativeCompositorView(ref, { sources: { screenPath: "rec.mp4" } }),
+ );
+ await waitFor(() => expect(result.current.viewId).toBe(7));
+ mocks.readCompositorFrame.mockClear();
+ }
+
+ it("pulls ~30 times a second while nothing new comes, whatever the display rate", async () => {
+ const run = manualFrames();
+ try {
+ mocks.readCompositorFrame.mockResolvedValue(null);
+ await mountedView();
+
+ await run(1000, 1000 / 280);
+
+ // One pull every 9 ticks of 3.6 ms: 32 in the second, against 280 counting ticks.
+ const pulls = mocks.readCompositorFrame.mock.calls.length;
+ expect(pulls).toBeGreaterThanOrEqual(28);
+ expect(pulls).toBeLessThanOrEqual(33);
+ } finally {
+ vi.unstubAllGlobals();
+ }
+ });
+
+ it("pulls every 8 ms or so while shared frames keep coming, and slows down once they stop", async () => {
+ const run = manualFrames();
+ try {
+ let gen = 0;
+ mocks.readCompositorFrame.mockImplementation(async () => ({
+ ...sharedMeta({ gen: ++gen }),
+ shared: true,
+ }));
+ await mountedView();
+ // The first frame marks the transport as shared, as the preload's listener does.
+ mocks.sharedListener?.(fakeVideoFrame(), sharedMeta({ gen: 1 }));
+
+ await run(1000, 1000 / 280);
+ const flowing = mocks.readCompositorFrame.mock.calls.length;
+ expect(flowing).toBeGreaterThanOrEqual(100);
+ expect(flowing).toBeLessThanOrEqual(150);
+
+ // Playback stops: nothing new comes any more. Past the flowing window the loop is
+ // back to ~30 pulls a second.
+ mocks.readCompositorFrame.mockReset();
+ mocks.readCompositorFrame.mockResolvedValue(null);
+ await run(400, 1000 / 280, 1000);
+ mocks.readCompositorFrame.mockClear();
+ await run(500, 1000 / 280, 1400);
+ expect(mocks.readCompositorFrame.mock.calls.length).toBeLessThanOrEqual(17);
+ } finally {
+ vi.unstubAllGlobals();
+ }
+ });
+
+ // Read-back frames bound the copies: the fast cadence is for shared textures only.
+ it("keeps read-back frames at ~30 pulls a second even while they keep coming", async () => {
+ const run = manualFrames();
+ vi.stubGlobal(
+ "ImageData",
+ class {
+ constructor(
+ public data: Uint8ClampedArray,
+ public width: number,
+ public height: number,
+ ) {}
+ },
+ );
+ vi.stubGlobal(
+ "createImageBitmap",
+ vi.fn(async () => ({ close: vi.fn() })),
+ );
+ try {
+ let gen = 0;
+ mocks.readCompositorFrame.mockImplementation(async () => ({
+ gen: ++gen,
+ width: 2,
+ height: 1,
+ data: new Uint8Array(8),
+ }));
+ await mountedView();
+
+ await run(1000, 1000 / 280);
+
+ expect(mocks.readCompositorFrame.mock.calls.length).toBeLessThanOrEqual(33);
+ } finally {
+ vi.unstubAllGlobals();
+ }
+ });
+ });
});
diff --git a/src/native/hooks/useNativeCompositorView.ts b/src/native/hooks/useNativeCompositorView.ts
index a138c8b92..d42fcfa89 100644
--- a/src/native/hooks/useNativeCompositorView.ts
+++ b/src/native/hooks/useNativeCompositorView.ts
@@ -11,9 +11,9 @@
* nothing is cloned, sent over IPC, or repainted. A new frame comes one of two ways:
* - as a shared GPU texture (Windows), sent to `subscribeCompositorSharedFrames`
* ahead of the reply, which then only names its generation. Nothing is copied
- * through RAM, so it is pulled every tick;
- * - as RGBA pixels (`{ gen, width, height, data }`) everywhere else, pulled every
- * other tick (~30fps) to bound the copies.
+ * through RAM, so while frames keep coming it is pulled every 8 ms;
+ * - as RGBA pixels (`{ gen, width, height, data }`) everywhere else, pulled ~30
+ * times a second to bound the copies.
* Either way the canvas drawing buffer is sized from the frame's own dims, so pixels
* and canvas can never drift apart.
*
@@ -84,10 +84,24 @@ function safelyCall(label: string, call: () => Promise<unknown>) {
}
}
-/** Read-back frames are pulled on every other animation frame (~30fps on 60 Hz): each one
- * is a GPU readback, a structured clone across IPC and a canvas upload. Shared-texture
- * frames copy nothing through RAM and are pulled every tick. */
-const PULL_LOOP_TICK_DIVISOR = 2;
+/** Least time between two pulls, by the clock rather than in animation frames: the display
+ * sets the rAF rate, the recording sets the frame rate, and the two have nothing to do with
+ * each other. Counting ticks pulled 280 times a second on a 280 Hz display, idle or not, and
+ * under-pulled read-back frames on 60 Hz, where a tick lost to a slow round trip pushed the
+ * next pull a whole tick further.
+ *
+ * While shared-texture frames keep coming, a pull every 8 ms catches each one within half a
+ * 60 fps frame. Anything else — read-back frames, each a GPU readback, a structured clone
+ * across IPC and a canvas upload, or a view with nothing new — is pulled ~30 times a second. */
+const PULL_INTERVAL_FLOWING_MS = 8;
+const PULL_INTERVAL_MS = 33;
+/** Frames still count as coming this long after the last one. A pull that lands between two
+ * frames finds nothing new, and taking that for the end of playback dropped every next
+ * pull to the slow interval: ~40 frames a second drawn out of ~60. */
+const PULL_FLOWING_WINDOW_MS = 250;
+/** rAF timestamps jitter around the display's period: without it, a 33 ms interval on a 60 Hz
+ * display would land on the third tick as often as the second. */
+const PULL_INTERVAL_SLACK_MS = 1.5;
export function useNativeCompositorView(
canvasRef: RefObject<HTMLCanvasElement>,
@@ -122,7 +136,7 @@ export function useNativeCompositorView(
let rectRafHandle = 0;
let pullRafHandle = 0;
- let pullTick = 0;
+ let lastPullAt = Number.NEGATIVE_INFINITY;
let lastRect: CompositorViewRect | null = null;
let disposed = false;
// Fresh view (source or enablement changed) → the previous view's fatal error
@@ -195,9 +209,10 @@ export function useNativeCompositorView(
// the next frame's. The generation actually on the canvas lets an older one be dropped,
// instead of bringing back its pixels and its buffer size until native sends another.
let paintedGen = 0;
- // Frames arrive as shared GPU textures (see `subscribeCompositorSharedFrames`): nothing
- // to bound, so the pull loop stops skipping ticks.
+ // Frames arrive as shared GPU textures (see `subscribeCompositorSharedFrames`), and one
+ // came lately: while both hold, the loop pulls at its fast interval.
let sharedTransport = false;
+ let lastFrameAt = Number.NEGATIVE_INFINITY;
// Whether this view's first shared frame was checked to have actually landed.
let sharedChecked = false;
@@ -251,13 +266,14 @@ export function useNativeCompositorView(
/** rAF pull loop: repaint ONLY when native reports a newer generation. A pixel packet
* is self-describing (`gen` + dims + pixels), so the canvas is sized from the packet —
* pixels and canvas can never drift out of sync. */
- const pullLoop = () => {
+ const pullLoop = (now: number) => {
pullRafHandle = requestAnimationFrame(pullLoop);
if (disposed || inFlight) {
return;
}
- pullTick = (pullTick + 1) % (sharedTransport ? 1 : PULL_LOOP_TICK_DIVISOR);
- if (pullTick !== 0) {
+ const flowing = sharedTransport && now - lastFrameAt < PULL_FLOWING_WINDOW_MS;
+ const interval = flowing ? PULL_INTERVAL_FLOWING_MS : PULL_INTERVAL_MS;
+ if (now - lastPullAt < interval - PULL_INTERVAL_SLACK_MS) {
return;
}
const id = viewIdRef.current;
@@ -269,9 +285,13 @@ export function useNativeCompositorView(
return;
}
inFlight = true;
+ lastPullAt = now;
readCompositorFrame(id, lastGen)
.then((frame) => {
inFlight = false;
+ if (frame) {
+ lastFrameAt = now;
+ }
// `null` = nothing newer than `lastGen` (idle path — no pixels
// crossed IPC) OR no frame yet. Either way, leave the canvas as-is.
if (disposed || !frame) {