Repository navigation
feat(🧵): requestAnimationFrame paced by the display, on every runtime - #636
Merged
Merged
Conversation
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
force-pushed
the
feat/frame-aligned-raf
branch
from
November 21, 2026 19:24
bf5efdd to
8b98187
Compare
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".
This was referenced Nov 22, 2026
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.
|
🎉 This PR is included in version 0.23.0 🎉 The release is available on:
Your semantic-release bot 📦🚀 |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
React Native's global
requestAnimationFramedrops frames on high refresh rate displays, on every runtime a WebGPU render loop can run on:setTimeout(0), andJavaTimerManagerfires 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.RCTDisplayLinksets nopreferredFrameRateRange, so it runs at 60 Hz on ProMotion.createWorkletRuntime). rAF is a 16 mssetTimeoutpoll, about 48 fps.This PR adds
requestAnimationFrameandcancelAnimationFrametoreact-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.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.
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
AChoreographeron a looper thread, withpostFrameCallback64looked up withdlsym(minSdk 26).CADisplayLinkon a run loop thread, withpreferredFrameRateRangeup 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.requestAnimationFrame.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 ofperformance.now()). The source only ticks while something is pending, plus a few idle frames.CallInvoker.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.requestAnimationFrame, which is already vsync-driven.AChoreographersends its frames to a paused app, and aCADisplayLinkruns on in the background until the system suspends the app.WebGPUTextureView.latchPresentedFrame()now callsonVisibilityChanged(VISIBLE)right after such a present, which is the only route to the privateupdateLayerAndInvalidate().Example and docs
requestAnimationFrame(React Native or WebGPU) and the busy work per frame, and it shows the fps. The existing loops inuseWebGPUand the Reanimated examples now use the newrequestAnimationFrame.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
CADisableMinimumFrameDurationOnPhonein the app'sInfo.plist(documented).Upstream
This is meant as the motivating example for two upstream changes:
requestAnimationFramea real animation-frame queue. Android: don't gate on the vsync timestamp. iOS: setpreferredFrameRateRangeon the JS display link.createWorkletRuntimeruntimes instead of the 16 ms poll.Test plan
QueuePresentKHRper thread,SurfaceTexturelatches on RenderThread)tscandeslintfor the package and the examplerequestAnimationFrame)