Native Extensions

React Native WebGPU adds a handful of native extensions on top of the WebGPU spec.

importSharedTextureMemory

Imports a native buffer (IOSurface / AHardwareBuffer) for zero-copy sampling. Nothing has to be requested: requestDevice() enables the Dawn features behind native frame import whenever the adapter supports them (see Native textures).

const device = await adapter.requestDevice();

// frame from createVideoPlayer(..., "bgra8") or Vision Camera
const memory = device.importSharedTextureMemory({
  handle: frame.handle,
  label: "camera-frame",
});

const texture = memory.createTexture();

memory.beginAccess(texture, /* initialized */ true);
// sample texture in render pass…
memory.endAccess(texture);

texture.destroy();
memory.destroy();
frame.release();

Use beginAccess(texture, true) when the producer has already written pixels (typical for video/camera).

memory.destroy() releases the import right away rather than when the object is garbage collected, which can take a while on a runtime importing a frame per vsync. End the access and destroy the textures created from it first: destroying during an access is a validation error, and so is using the memory afterwards.

importSharedFence

Import native GPU sync fences for producer/consumer handoff:

// Wait for the producer's GPU work before using the texture
const fence = device.importSharedFence({ ...ready, label: "frame-ready" });
// 1n for a sync fd, the event value for an MTLSharedEvent
memory.beginAccess(texture, true, [{ fence, signaledValue: 1n }]);
// beginAccess() keeps its own reference: release the fence right away
fence.destroy();

// … render using texture …

// Each fence signals once that GPU work is done. Export it only to hand it to
// native code: the handle is a duplicate that code has to close, and there is
// no JS API to close one. With no consumer, just destroy the fence.
const { fences } = memory.endAccess(texture);
for (const { fence: done, signaledValue } of fences) {
  const { type, handle } = done.export();
  releaseFrameWhenSignaled(frame, type, handle, signaledValue);
  done.destroy();
}

destroy() releases a fence and its native handle right away rather than when the object is garbage collected. An exported handle is a duplicate, so it stays valid; using the fence afterwards is a validation error, and export() then throws.

createNativeBufferExternalTexture / createNativeBufferTexture

A decoder or a camera cycles through the same few buffers, but importExternalTexture() imports the buffer again on every frame. These two methods import a buffer once; each frame is then bracketed with beginAccess() / endAccess() on the wrapper.

// Once per buffer, keyed by the buffer: the import, the texture and the
// external texture (color conversion included).
let wrapper = wrappers.get(frame.handle);
if (!wrapper) {
  wrapper = device.createNativeBufferExternalTexture(frame, {
    label: "clip-1",
  });
  wrappers.set(frame.handle, wrapper);
}

// Per frame: wait for the producer's fence, draw, hand the fence of the
// access back.
const fences = [];
if (frame.acquireFenceFd !== null) {
  const ready = device.importSharedFence({
    type: "sync-fd",
    handle: frame.acquireFenceFd,
  });
  fences.push({ fence: ready, signaledValue: 1n });
}
wrapper.beginAccess(fences);
fences.forEach(({ fence }) => fence.destroy());
draw(wrapper.externalTexture); // ... queue.submit() ...
const done = wrapper.endAccess();
done?.fence.destroy(); // or export() it for the producer

// When the producer drops the buffer
wrapper.destroy();

beginAccess(fences?) makes the GPU wait for the fences before it reads the buffer; endAccess() returns one fence that signals once the GPU is done with it, or null. destroy() releases the import and the frame the wrapper was created from; an access left open is a validation error, and it is ended anyway so the producer gets its buffer back. The descriptor is that of importExternalTexture() without the source (colorSpace, rotation, mirrored, plus sourceColorSpace, cropOrigin and cropSize, see below); the same descriptor members apply to importExternalTexture().

createNativeBufferTexture(frame, { usage, label }) is the same wrapper over a color buffer (an RGBA AHardwareBuffer, a BGRA IOSurface) exposed as a regular GPUTexture; usage defaults to every usage the buffer allows. The external texture is sample-only, as on the web, and the only way to read a YUV frame; the texture is for a color buffer you also write to or copy from.

On Android, a buffer from another library (wrapped with createVideoFrameFromNativeBuffer) carries no color metadata: pass sourceColorSpace when you know it, or the conversion assumes what the platform reports for the buffer, BT.601 limited range by default.

dawnToggles

Non-standard Dawn device toggles at creation:

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

On Android, the ignore_imported_ahardwarebuffer_vulkan_image_size toggle is enabled by default, so native buffers import on every driver. Pass it in disabledToggles to turn it off.

implicitDeviceSynchronization

By default, requestDevice() enables Dawn's implicit-device-synchronization feature, which lets a device created on the JS thread be used from the UI thread or a dedicated worklet runtime (see Thread safety).

Set implicitDeviceSynchronization: false on the device descriptor to opt out and skip the locking. Only do this for a device that is never touched from another runtime. The flag is a non-standard extension and is ignored on the web.

const device = await adapter.requestDevice({
  implicitDeviceSynchronization: false,
});
device.features.has("implicit-device-synchronization" as GPUFeatureName); // false

The flag only controls the default injection: listing "implicit-device-synchronization" in requiredFeatures still enables the feature.

GPUExternalTexture extensions

Usage with importExternalTexture (NV12 camera/video):

const externalTexture = device.importExternalTexture({
  source: nativeVideoFrame,
});

// Read orientation metadata in bind group / shader setup
console.log(externalTexture.rotation, externalTexture.mirrored);

// After submit that sampled the texture:
externalTexture.destroy();
nativeVideoFrame.release();

On Android, a YUV frame (what the video decoder and the camera produce) needs the opaque-ycbcr-android-for-external-texture device feature. requestDevice() enables it whenever the adapter supports it; a device created by another library and wrapped with importDevice() has to request it itself, as react-native-skia's does. The same applies to copyExternalImageToTexture() with a native frame.

textureSampleBaseClampToEdge returns RGB on both platforms, as on the web: the external texture converts a YUV frame while sampling, with the color space of the frame (its YCbCr matrix, range, primaries and transfer function). A video player's frames carry it. A buffer without one (a camera frame) falls back to what the platform reports for it, then to BT.709 limited range on Apple platforms and BT.601 limited range on Android; sourceColorSpace overrides either. The spec's colorSpace member selects the color space of the result, "srgb" (the default) or "display-p3".

copyExternalImageToTexture with a native frame

queue.copyExternalImageToTexture() also accepts a NativeVideoFrame as its source, the way the web API accepts a VideoFrame. The frame is rendered into the destination on the GPU through an external texture, so YUV frames come out as RGB, and the non-spec rotation and mirrored options of importExternalTexture apply. The destination needs GPUTextureUsage.RENDER_ATTACHMENT and an rgba8unorm, bgra8unorm (or -srgb), rgba16float or rgb10a2unorm format; the frame can be released as soon as the call returns.

const texture = device.createTexture({
  size: [frame.width, frame.height],
  format: "rgba8unorm",
  usage: GPUTextureUsage.RENDER_ATTACHMENT | GPUTextureUsage.TEXTURE_BINDING,
});
device.queue.copyExternalImageToTexture(
  { source: frame, rotation },
  { texture },
  [frame.width, frame.height],
);
frame.release();

origin, flipY and the copy size work as on the web, in the upright frame: a frame rotated by 90 or 270 degrees has its width and height swapped. This is the path to hand a video or camera frame to a library that samples regular textures, such as React Native Skia; a shader of your own can sample the frame directly with importExternalTexture() and skip the copy.

createImageBitmap

createImageBitmap mirrors its Web counterpart and also accepts a Uint8Array or ArrayBuffer as input.

const bytes = await fetch(url).then((r) => r.arrayBuffer());
const bitmap = await createImageBitmap(bytes);

device.queue.copyExternalImageToTexture(
  { source: bitmap },
  { texture },
  { width: bitmap.width, height: bitmap.height },
);
bitmap.close();

getPreferredHighBitDepthCanvasFormat

Returns the canvas texture format most likely to reach the display with more than 8 bits per channel on the current platform: "rgba16float" on iOS, "rgb10a2unorm" on Android. Unlike getPreferredCanvasFormat(), this helper is not part of the WebGPU standard, so it is exported as a regular function instead of a navigator.gpu method.

const format = getPreferredHighBitDepthCanvasFormat();
context.configure({ device, format, alphaMode: "opaque" });

The values you write stay sRGB-encoded exactly like on an 8-bit canvas: this is about precision, not HDR (no extended range). See High bit depth for the platform details and banding comparison.