React Native WebGPU

Native Buffer

NativeBuffer, createNativeBuffer and NativeBufferView, the view that displays a native buffer.

A native buffer is an AHardwareBuffer on Android and an IOSurface on Apple platforms. See the Native Buffers guide for how buffers, devices, fences and views fit together.

NativeBuffer

A NativeBuffer holds a native buffer and keeps it alive until release() is called, or until the object is garbage collected. It does not belong to any GPU device: a device imports it to sample it or to render into it.

Prop

Type

handle is the raw pointer of the buffer (an IOSurfaceRef or an AHardwareBuffer*) as a BigInt, which importSharedTextureMemory({ handle }) takes.

acquireFenceFd is, on Android, the sync fd the decoder or the camera signals once it has written the buffer, and null elsewhere. importExternalTexture(), copyExternalImageToTexture() and NativeBufferView wait for it on their own; with importSharedTextureMemory(), pass it to beginAccess() through importSharedFence({ type: "sync-fd", handle }). The frame owns the fd: import it before release(), and never close it.

A frame from a video player or a camera comes from a pool: release it as soon as the GPU work that reads it has been submitted, or the producer runs out of buffers.

createNativeBuffer

createNativeBuffer(width: number, height: number, options?: CreateNativeBufferOptions): NativeBuffer

Allocates an empty color buffer to render into, for instance to display it in a NativeBufferView. Import it with device.importSharedTextureMemory({ source: frame }) and render into memory.createTexture(); see Rendering into a buffer. The width and height are integers from 1 to 16384.

Prop

Type

createNativeBufferFromPointer

createNativeBufferFromPointer(pointer: bigint): NativeBuffer

Wraps a buffer produced by another library (a CVPixelBufferRef on Apple platforms, an AHardwareBuffer* on Android, for instance VisionCamera's frame.getNativeBuffer().pointer) into a NativeBuffer that holds a reference of its own until released. It runs on the JS thread; on a worklet runtime, such as a frame processor, call RNWebGPU.createNativeBufferFromPointer(pointer) instead (see Vision Camera).

createTestVideoFrame(width, height) allocates a frame filled with a test pattern, for tests and examples that need a frame without a camera or a video.

NativeBufferView

const  = <NativeBufferViewRef>(null);
const { ,  } = ();

<
  ={}
  ="contain"
  ={}
  ={{ : 1 }}
/>;

Displays a native buffer with no swap chain, no canvas context and no GPU device on the display side. It is meant for content that is drawn once or updated now and then; animated content belongs in a Canvas. The view never allocates buffers: it reports its size, and you present the buffers you render through its ref.

PropDescription
refA NativeBufferViewRef to present buffers with.
onPixelSizeChangeCalled with { width, height }, the size of the view in physical pixels, on mount and on every size change. Render at that size for a sharp, 1:1 display.
resizeModeHow a buffer whose size differs from the view's is fitted, "stretch" by default. See Resize modes.
...ViewPropsThe props of a React Native View.

NativeBufferViewRef

Prop

Type

present(frame, done) takes what GPUSharedTextureMemory.endAccess() returned for the work that wrote the buffer, and shows the buffer once all its fences have signaled. The view takes its own reference on the buffer and on the fences, so they can be released right after the call.

Do not write a buffer again once it is presented: render the next update into a new buffer. Frames from a pool (a video player, a camera) have to be copied into a buffer from createNativeBuffer() first, since their producer writes a later frame into the buffer once the frame is released; see Never write a displayed buffer.

On a worklet runtime, present with the RNWebGPU global and the view's id:

RNWebGPU.presentNativeBuffer(viewId, frame, memory.endAccess(texture));

Resize modes

A buffer of exactly the view's size is shown 1:1 in every mode. The mode applies while the size of the buffer differs, for instance until the producer catches up with a resize.

ModeDescription
"stretch"Scaled to the bounds, ignoring the aspect ratio. The default.
"contain"Scaled to fit inside the bounds, keeping the aspect ratio.
"cover"Scaled to fill the bounds, keeping the aspect ratio; the excess is cropped.
"topLeft"Not scaled; anchored at the top left corner and cropped.

useNativeBufferSize

useNativeBufferSize(debounceMs?: number): {
  size: NativeBufferPixelSize | null;
  onPixelSizeChange: (size: NativeBufferPixelSize) => void;
}

Tracks the pixel size of a NativeBufferView and settles resizes. The first size is reported right away; later ones once the view has kept the same size for debounceMs (150 by default). During an animated resize, the view scales what it already shows meanwhile. Pass onPixelSizeChange to the view and render a buffer of size whenever it changes.

Platform notes

  • On Android 8 and 9, the view copies the pixels of each buffer through the CPU. From Android 10 on, it shows the buffer without a copy.
  • An rgba16float buffer is shown with more precision, not extended range: values outside [0, 1] are clamped.