React Native WebGPU

Platform Guide

Where React Native WebGPU differs from WebGPU in the browser.

React Native WebGPU implements the WebGPU API as the browser does. Where a platform forces a difference, it is surfaced rather than hidden:

Threading model

You can run WebGPU code on the main JS thread, on the UI thread, or on a dedicated worklet runtime (createWorkletRuntime, or a Vision Camera frame processor), with the same API everywhere. Running off the JS thread is powered by React Native Worklets; Reanimated is not required.

The typical pattern is to create the device on the main JS thread and hand it to a worklet, which calls installWebGPU() once to install the WebGPU globals on its runtime. device.lost and uncapturederror are only delivered on the main JS runtime, one more reason to create the device there. See Worklets for the complete guide and the thread-safety rules.

Background GPU work on iOS

iOS refuses GPU work from an app in the background, and Dawn would lose the device over it. React Native WebGPU holds that work instead, on iOS and tvOS: what is submitted while the app is in the background is kept, in order, and runs when the app comes back to the foreground. Presenting a canvas does nothing meanwhile; the canvas catches up on return. An onSubmittedWorkDone() or mapAsync() promise waiting on held work settles only once the app is back. Android and macOS do not refuse GPU work from a background app, so nothing is held there.

This is Dawn's metal_suspend_submissions_in_background toggle, enabled on every device React Native WebGPU creates. Pass it in disabledToggles (see dawnToggles) to opt out: the device is then lost over the first refused command buffer.

Holding is not free: everything submitted in the background stays in memory until the app returns, and then runs all at once. So nothing should keep submitting while the app is not active.

A render loop on the requestAnimationFrame of react-native-webgpu stops by itself, on the JS thread and on a worklet runtime of your own: no frame comes while the app is not active, and the loop goes on when the app is back.

Work that something else drives has to check for itself: a timer, a video or a camera callback, a loop on another requestAnimationFrame.

import { AppState } from "react-native";

const onVideoFrame = () => {
  if (AppState.currentState !== "active") {
    // Nothing to show: skip the frame rather than hold it.
    return;
  }
  render();
};

Loading images

This module provides a createImageBitmap function you can use with copyExternalImageToTexture. Resolve a bundled asset to a URI, fetch it, and decode the blob. In React Native createImageBitmap also accepts an ArrayBuffer as input.

const url = Image.resolveAssetSource(require("./assets/image.png")).uri;
const response = await fetch(url);
const imageBitmap = await createImageBitmap(await response.blob());

device.queue.copyExternalImageToTexture(
  { source: imageBitmap },
  { texture },
  [imageBitmap.width, imageBitmap.height],
);

See copyExternalImageToTexture on MDN. The same call also takes a native video or camera frame as its source.

High bit depth

By default a canvas is configured with an 8-bit format (bgra8unorm or rgba8unorm, the value returned by navigator.gpu.getPreferredCanvasFormat() depending on the platform). With only 256 levels per channel, subtle gradients quantize into visible bands, especially in dark tones and on OLED displays.

To configure the canvas with a higher-precision format, use getPreferredHighBitDepthCanvasFormat() (currently it will return rgba16float on iOS and rgb10a2unorm on Android):

// "rgba16float" on iOS, "rgb10a2unorm" on Android
const  = ();

.({ , , : "opaque" });

Native textures

Camera frames, video frames and buffers you render into move between WebGPU, other GPU APIs and the screen without a copy, through Dawn's shared texture memory and the spec's GPUExternalTexture. Nothing has to be requested: requestDevice() enables what it needs whenever the adapter supports it.

The Native Buffers guide explains how it fits together, and Vision Camera applies WGSL effects to live camera frames.

Pipeline cache

Every device requestDevice() creates keeps the shaders and pipelines Dawn builds in a cache on disk, in the app's cache directory, so a relaunch reuses them instead of building them again. On Android, this includes the Vulkan driver's pipeline cache, where most of the time goes. The cache is written as the app runs and when it goes to the background, and its size is bounded; the system may clear it, as it does any app cache.

To opt a device out, disable it with a Dawn toggle:

const device = await adapter.requestDevice({
  dawnToggles: { enabledToggles: ["disable_blob_cache"] },
});

A device wrapped with importDevice() is created by its own library and does not use this cache.

Importing an external device

importDevice() wraps a GPU device created by another native library into a regular GPUDevice. The device handle is passed as a BigInt, and the original owner keeps its own reference.

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

const device = importDevice(pointer);

This only works with a library that links the same Dawn build as React Native WebGPU. The main one is React Native Skia (v3 and above), which shares react-native-webgpu's Dawn.

Rendering to a native window

RNWebGPU.MakeWebGPUCanvasContextFromNativeWindow() makes a canvas context that presents to a native window other than a Canvas, for instance the input Surface of a MediaCodec encoder on Android. The window is an ANativeWindow* on Android or a CAMetalLayer* on Apple platforms, passed as a BigInt; width and height size the drawing buffer, like canvas.width and canvas.height. The context retains the window for as long as it lives, so the pointer stays valid; whatever the window belongs to (the encoder, the layer's view) is yours to keep alive while you present to it. Unlike a Canvas, nothing drives the context for you: call it from one thread at a time. On Apple platforms, configure() leaves the layer's colorspace as it is: set it yourself, on the main thread, to match the colorSpace and format you configure.

const context = RNWebGPU.MakeWebGPUCanvasContextFromNativeWindow(
  window,
  width,
  height,
);
context.configure({
  device,
  format: navigator.gpu.getPreferredCanvasFormat(),
});

// For each frame
const texture = context.getCurrentTexture();
// ...render into texture and submit...
context.present();

// Once done. On Android, this also hands the window its buffers back right
// away: a MediaCodec input surface keeps them until the surface is gone,
// which would otherwise wait for the context to be garbage collected. The
// context can be configured again.
context.unconfigure();

Each present() queues the frame to the window once the GPU is done rendering it. On Android, to give an encoder the presentation time of each frame, set it on the window right before present(), as eglPresentationTimeANDROID does with EGL: the window keeps it for the next frame queued.

See also