Skip to content

feat(🧵): requestAnimationFrame paced by the display, on every runtime - #636

Merged
wcandillon merged 9 commits into
mainfrom
feat/frame-aligned-raf
Nov 22, 2026
Merged

wcandillon merged 9 commits into
mainfrom
feat/frame-aligned-raf

Conversation

@wcandillon

@wcandillon wcandillon commented Nov 20, 2026 •

Copy link
Copy Markdown
Owner

React Native's global requestAnimationFrame drops frames on high refresh rate displays, on every runtime a WebGPU render loop can run on:

  • Android, JS thread. rAF is setTimeout(0), and JavaTimerManager fires a timer at a vsync only if it was registered before that vsync's timestamp. A loop that requests its next frame at the end of its work has about 6 ms of a 120 Hz frame. With more work than that, it runs at exactly 60 fps.
  • iOS, JS thread. RCTDisplayLink sets no preferredFrameRateRange, so it runs at 60 Hz on ProMotion.
  • Worklet runtimes (createWorkletRuntime). rAF is a 16 ms setTimeout poll, about 48 fps.

This PR adds requestAnimationFrame and cancelAnimationFrame to react-native-webgpu, as drop-ins for the global ones, paced by the display on every runtime. It also fixes the TextureView showing only every other frame presented from the Reanimated UI runtime.

import { requestAnimationFrame } from "react-native-webgpu";

const render = (timestamp: number) => {
  draw(timestamp);
  context.present();
  requestAnimationFrame(render);
};
requestAnimationFrame(render);

Results

Cube with busy work per frame, frames presented per second. Galaxy S25 Edge (120 Hz) measured with Perfetto, iPhone 14 Pro (ProMotion) with the on-screen counter.

Runtime Work per frame Android, global Android, this PR iOS, global iOS, this PR
JS thread 0 ms 117 119 60 120
JS thread 7 ms 59 119 60 120
JS thread 10 ms 58.5 79 60 80
Worklet runtime 0 ms 49 119 45 120
Worklet runtime 7 ms 119 120
Worklet runtime 10 ms 92
UI runtime 0 ms 119 (59.5 on screen before the TextureView fix) 119 120 120

At 10 ms per frame the work can't fit in 8.3 ms. A loop that overruns its frame runs again in the frame it overran into instead of halving to 60. On the JS thread that run goes behind whatever waits there, and the run after it waits for a frame of the display: two runs every three frames, 80 fps, with React still rendering and timers still firing. A worklet runtime has nothing else to run and keeps going back to back (92 fps).

The two JS thread figures at 10 ms for this PR were measured again after the review fixes (66e2004): the on-screen counter on the S25 Edge, a bare loop without a canvas on the iPhone. Before them the loop ran at 94 and 98 fps, and kept the JS thread to itself.

How it works

  • Display source. One per process, on a thread of its own so that a busy main thread or JS thread never delays it:
    • Android: AChoreographer on a looper thread, with postFrameCallback64 looked up with dlsym (minSdk 26).
    • iOS: CADisplayLink on a run loop thread, with preferredFrameRateRange up to 120. It keeps running between requests and pauses after 8 idle frames. Pausing at every frame kept the system from running it at 120 Hz.
    • macOS has no source yet: there, as on web, these functions are the runtime's own requestAnimationFrame.
  • Scheduler (cpp/rnwgpu/AnimationFrames.{h,cpp}). Per runtime, like a browser: a frame runs the callbacks requested before it, callbacks requested during the flush go to the next frame, and all callbacks of a frame get the same timestamp (the vsync time on the clock of performance.now()). The source only ticks while something is pending, plus a few idle frames.
    • JS thread: the flush is posted through the CallInvoker.
    • Worklet runtime of your own: a request wakes the runtime with setTimeout(0), then it waits on its thread for the next frame (the rest of the current one at most) and flushes. Nothing else runs on that runtime during the wait. A native frame callback in Worklets would remove the wait; that is the upstream proposal below.
    • Reanimated UI runtime: Worklets' own requestAnimationFrame, which is already vsync-driven.
    • Catch-up: a request made while the current frame is still fresh and hasn't flushed yet runs in that frame. On the JS thread that run is posted at idle priority, behind React's updates and the app's other tasks, and it only follows a run on an animation frame. Without that, the scheduler never ran out of tasks: a normal-priority task waited up to 949 ms under a 12 ms loop, and on iOS the JS thread never went back to its run loop, where React Native finds its timers due.
    • One run per frame of the display, counted from when the run starts: a run that starts late is the run of the frame it starts in, so the next request waits for the next frame.
    • Foreground: no frame while the app is not in the foreground, with the definition React Native Skia uses (host activity paused on Android, app not active on iOS). Neither source stops on its own: an AChoreographer sends its frames to a paused app, and a CADisplayLink runs on in the background until the system suspends the app.
  • TextureView latch (Android). A TextureView hears of a new frame through a message on the main looper. A frame presented on the main thread during the Choreographer's animation callbacks only showed at the next draw. WebGPUTextureView.latchPresentedFrame() now calls onVisibilityChanged(VISIBLE) right after such a present, which is the only route to the private updateLayerAndInvalidate().

Example and docs

  • New Frame Pacing example screen. Pick the runtime (JS thread, UI, Worklet), the requestAnimationFrame (React Native or WebGPU) and the busy work per frame, and it shows the fps. The existing loops in useWebGPU and the Reanimated examples now use the new requestAnimationFrame.
  • New API page api/request-animation-frame. It also corrects the Canvas and Worklets guides, which said a loop on a worklet runtime runs at the display's rate.

Caveats

  • iPhone. More than 60 Hz still needs CADisableMinimumFrameDurationOnPhone in the app's Info.plist (documented).
  • Android small-area detection. This is platform behavior, not something in this PR. On the S25 Edge, a window whose updates cover less than about half of the screen is "small dirty" to SurfaceFlinger, which runs the whole app at 60 Hz through frame-rate override, whatever paces its frames. The Frame Pacing canvas fills the screen for this reason, and the docs mention it. The upstream mechanism is AOSP's "SF: Suppress frame rate when small area updating" and its per-package allowlist. The Samsung behavior (an explicit 60 Hz vote, applied to any app) looks like OEM tuning.
  • TextureView latch losses. A worklet loop with 7 ms of work presents 119 fps but the TextureView latches about 110. That's when presents land late in the frame; a mailbox pacing step can follow.

Upstream

This is meant as the motivating example for two upstream changes:

  • React Native: make bridgeless requestAnimationFrame a real animation-frame queue. Android: don't gate on the vsync timestamp. iOS: set preferredFrameRateRange on the JS display link.
  • Worklets: a native vsync callback for createWorkletRuntime runtimes instead of the 16 ms poll.

Test plan

  • Android, Galaxy S25 Edge: the full matrix above, with Perfetto (QueuePresentKHR per thread, SurfaceTexture latches on RenderThread)
  • iOS, iPhone 14 Pro: the matrix above with the on-screen counter
  • tsc and eslint for the package and the example
  • Review fixes, on the S25 Edge, the iPhone 14 Pro and the iOS simulator, with loops driven over CDP: wait of a normal-priority task and of a 250 ms interval under a loop that overruns, runs per frame of the display after 18 ms hitches, frames delivered while the app is away, and a reload
  • macOS example still runs (falls back to the global requestAnimationFrame)
  • CI

Adds requestAnimationFrame and cancelAnimationFrame, drop-ins for the global ones in a render loop, driven by a native display source on a thread of its own: AChoreographer on a looper thread on Android, CADisplayLink with a preferredFrameRateRange up to 120 Hz on iOS.

On the JS thread, each frame of the display runs the callbacks requested before it, through the CallInvoker. On a worklet runtime of your own, the runtime waits on its thread for the next frame, then runs them. On the Reanimated UI runtime, and where there is no source (macOS, web), it is the runtime's own requestAnimationFrame.

Like a browser's, callbacks requested during a frame's flush go to the next frame, and all callbacks of a frame get the same timestamp, on the clock of performance.now(). A loop that overruns its frame runs again in the frame it overran into.
…tureView draw

A TextureView hears of a new frame through a message on the main looper. A frame presented on the main thread during the Choreographer's animation callbacks (the Reanimated UI runtime) only showed at the next draw, so the canvas updated every other frame: 59.5 fps on a 120 Hz display. The view is now told before the draw, through onVisibilityChanged(VISIBLE), the one route to updateLayerAndInvalidate(). 119 fps on screen.
…mationFrame

The Frame Pacing screen renders a cube from the JS thread, the UI runtime or a worklet runtime, with React Native's or WebGPU's requestAnimationFrame and some busy work per frame, and shows the frames per second.
Documents the new requestAnimationFrame, and corrects the frame rate of a loop on a worklet runtime of your own: the global requestAnimationFrame polls every 16 ms there.
@wcandillon
wcandillon force-pushed the feat/frame-aligned-raf branch from bf5efdd to 8b98187 Compare November 21, 2026 19:24
The native side of requestAnimationFrame now uses the vocabulary of Skia's frame pacing (rnsurface::FrameScheduler, AnimationFrameSource), where a frame of the display that starts is an animation frame:

- VsyncSource is AnimationFrameSource (AndroidAnimationFrameSource, AppleAnimationFrameSource, PlatformContext::makeAnimationFrameSource).
- AnimationFrameScheduler is AnimationFrameDispatcher. Skia's FrameScheduler paces the presents of one view, which this is not, and rnsurface is meant to be shared between the two libraries.
- Its Frame is AnimationFrame.

No change in behavior. The source's thread is now named "RNWebGPU Frames".
Three fixes from the review of the new requestAnimationFrame, each measured on a Galaxy S25 Edge, an iPhone 14 Pro and the iOS simulator.

- A loop on the JS thread that overruns its frame no longer keeps the thread to itself. It still runs again in the frame it overran into, but that run goes behind whatever waits on the runtime (idle priority) and only follows a run on an animation frame: the run after it waits for a frame of the display. Posted as the previous run ended, every run kept the scheduler from running out of tasks: React did not render (a normal-priority task waited up to 949 ms under a 12 ms loop), and on iOS the JS thread never went back to its run loop, where React Native finds its timers due. A 10 ms loop at 120 Hz now runs at 80 fps on the JS thread (two runs every three frames), where React Native's own gives 60. A worklet runtime still runs back to back.
- One run per frame of the display, counted from when the run starts. A run posted for a frame and started in a later one (the runtime was busy) is the run of the frame it starts in, so the next request waits for the next frame instead of running a second time in the same one.
- No frame while the app is not in the foreground (AnimationFrameDispatcher::setForeground, with the definition React Native Skia uses): the host activity is paused on Android, the app is not active on iOS. Neither source stops on its own. An AChoreographer sends its frames to a paused app, and a CADisplayLink runs on in the background until the system suspends the app.

The documentation follows, and the last mentions of "vsync" in prose become "frame of the display".
The callbacks of a runtime's requestAnimationFrame are values of that runtime, and have to go while it is still there. They went with the last reference to its RuntimeAnimationFrames, which is not always the runtime's: the dispatcher holds one on its own thread for the time of a deliver(), once per frame. A runtime torn down meanwhile (a reload) left its pending callbacks to be destroyed on that thread, after the runtime, where releasing a JS value writes into freed memory.

The runtime's runtimeData is now a holder that releases the callbacks when the runtime lets go of it, which Hermes does before it takes the VM down. Whoever holds the last reference then destroys an object without any.

Checked on a Galaxy S25 Edge by holding the dispatcher's reference for 40 ms per frame and reloading with a loop running: the pending callback was destroyed on the dispatcher's thread in 2 reloads of 8 before, and in none of 12 after.
The guides showed render loops on the global requestAnimationFrame, next to the advice to use the one of react-native-webgpu:

- The first example of the Canvas guide, the one a reader copies, imports requestAnimationFrame and cancelAnimationFrame from react-native-webgpu.
- So does the loop of the video player reference, and its import is now part of the snippet.
- "Background GPU work on iOS" told a render loop to check AppState before it submits. A loop on the library's requestAnimationFrame stops by itself now, so the section says that, and keeps the check for work that something else drives: a timer, a video or a camera callback.

The foreground rule is also scoped to where it holds, in the reference and in the API comment: the JS thread and a worklet runtime of your own. On the Reanimated UI runtime, Worklets' requestAnimationFrame decides.
@wcandillon
wcandillon merged commit 06599f9 into main Nov 22, 2026
2 of 9 checks passed
@github-actions

Copy link
Copy Markdown

🎉 This PR is included in version 0.23.0 🎉

The release is available on:

Your semantic-release bot 📦🚀

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant