Skip to content

Add Threading guide and make RNWebGPU available on worklet runtimes - #510

Open
wcandillon wants to merge 2 commits into
mainfrom
claude/friendly-galileo-p55un1
Open

wcandillon wants to merge 2 commits into
mainfrom
claude/friendly-galileo-p55un1

Conversation

@wcandillon

Copy link
Copy Markdown
Owner

Summary

This PR adds comprehensive documentation on threading and WebGPU runtime selection, while also making the RNWebGPU global available on worklet runtimes via installWebGPU().

Key Changes

Documentation:

  • Added new Threading guide covering:
    • The three runtimes (JS thread, UI runtime, dedicated worklet runtime) and their tradeoffs
    • Rules for safe cross-runtime WebGPU usage
    • Complete example of a render loop on a worklet that stops on unmount
    • Thread safety and implicit device synchronization details
    • Guidance on which runtime to pick for different scenarios
  • Updated Native API to reference the new Threading guide
  • Updated Worklets integration page with links to Threading
  • Updated installWebGPU API docs to mention RNWebGPU installation
  • Updated Vision Camera integration with threading context
  • Updated example code comments in AsyncBuffer.tsx to clarify the recommended pattern

Implementation:

  • Modified installWebGPU() to install the RNWebGPU global on worklet runtimes, not just navigator.gpu
  • Updated provideGPUForInstall() to accept the full RNWebGPU object instead of just the gpu property
  • Updated the holder object in install.ts to track both RNWebGPU and gpu
  • Updated main/index.tsx to pass the entire RNWebGPU object to provideGPUForInstall()

Notable Details

The RNWebGPU global provides native helper functions like createVideoFrameFromNativeBuffer that are needed on worklet runtimes. By making it available through installWebGPU(), worklets can now access these helpers without workarounds. The implementation uses the existing Worklets serializer mechanism to pass the native object by reference across runtimes.

https://claude.ai/code/session_01SKomALwiaZvnhAS2rDt1kN

Add a Threading page under Getting Started that explains the three
runtimes (JS thread, UI runtime, dedicated worklet runtime), which one to
pick, what must stay on the JS thread, how WebGPU objects cross into
worklets, where promises settle, a complete worklet render loop that
stops on unmount, and the thread-safety model. The Native APIs, Worklets,
installWebGPU and related pages now defer to it instead of repeating the
implicit-device-synchronization explanation.

installWebGPU() now also installs the RNWebGPU global on the calling
worklet runtime, so native helpers such as createVideoFrameFromNativeBuffer
work from a frame processor as documented on the Vision Camera page.

Also reword the React Three Fiber threading note, and fix the stale
AsyncBuffer example comment about where async results settle.
@wcandillon

Copy link
Copy Markdown
Owner Author

@copilot resolve the merge conflicts in this pull request

…eo-p55un1

# Conflicts:
#	apps/docs/content/api/install-webgpu.mdx

Co-authored-by: wcandillon <306134+wcandillon@users.noreply.github.com>

Copilot AI commented Oct 8, 2026

Copy link
Copy Markdown

@copilot resolve the merge conflicts in this pull request

Resolved the conflict and merged main in commit 17035ab. Both the Worklets navigator-version warning and the device-event guidance are preserved.

This branch has not been deployed

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

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants