react-native-wgpu 0.5.10 → 0.5.13

package/src/Canvas.tsx

@@ -9,21 +9,6 @@ function generateContextId() {
   return CONTEXT_COUNTER++;
 }
 
-declare global {
-  var RNWebGPU: {
-    gpu: GPU;
-    fabric: boolean;
-    getNativeSurface: (contextId: number) => NativeCanvas;
-    MakeWebGPUCanvasContext: (
-      contextId: number,
-      width: number,
-      height: number,
-    ) => RNCanvasContext;
-    DecodeToUTF8: (buffer: NodeJS.ArrayBufferView | ArrayBuffer) => string;
-    createImageBitmap: typeof createImageBitmap;
-  };
-}
-
 type SurfacePointer = bigint;
 
 export interface NativeCanvas {

package/src/index.tsx

@@ -1,8 +1,25 @@
 /// <reference types="@webgpu/types" />
-
-import type { NativeCanvas, RNCanvasContext } from "./types";
+import type {
+  GPUDawnTogglesDescriptor,
+  GPUSharedTextureMemory,
+  GPUSharedTextureMemoryDescriptor,
+  NativeCanvas,
+  RNCanvasContext,
+  VideoPlayer,
+  NativeVideoFrame,
+  NativeVideoPixelFormat,
+} from "./types";
 
 export * from "./main";
+export type {
+  NativeVideoFrame,
+  VideoPlayer,
+  NativeVideoPixelFormat,
+  CreateVideoPlayerOptions,
+  GPUSharedTextureMemory,
+  GPUSharedTextureMemoryDescriptor,
+  GPUDawnTogglesDescriptor,
+} from "./types";
 
 declare global {
   interface Navigator {
@@ -22,8 +39,51 @@ declare global {
     ) => RNCanvasContext;
     DecodeToUTF8: (buffer: NodeJS.ArrayBufferView | ArrayBuffer) => string;
     createImageBitmap: typeof createImageBitmap;
+    loadVideoFrame: (path: string) => NativeVideoFrame;
+    createTestVideoFrame: (width: number, height: number) => NativeVideoFrame;
+    // Wrap a NativeBuffer.pointer (CVPixelBufferRef on iOS / AHardwareBuffer*
+    // on Android) into a NativeVideoFrame. Matches the shape used by libraries
+    // that emit NativeBuffer (e.g. react-native-vision-camera).
+    createVideoFrameFromNativeBuffer: (pointer: bigint) => NativeVideoFrame;
+    createVideoPlayer: (
+      path: string,
+      pixelFormat?: NativeVideoPixelFormat,
+    ) => VideoPlayer;
+    writeTestVideoFile: () => string;
   };
 
+  interface GPUDevice {
+    importSharedTextureMemory(
+      descriptor: GPUSharedTextureMemoryDescriptor,
+    ): GPUSharedTextureMemory;
+  }
+
+  // Non-standard, Dawn-only. Lets callers set Dawn device-stage toggles at
+  // device creation: adapter.requestDevice({ dawnToggles: { ... } }).
+  interface GPUDeviceDescriptor {
+    dawnToggles?: GPUDawnTogglesDescriptor;
+  }
+  // Non-spec extension: camera frames arrive in the sensor's native
+  // orientation, which differs between iOS and Android. `rotation` (degrees,
+  // one of 0/90/180/270) and `mirrored` (horizontal flip) are baked into the
+  // sampling transform by Dawn, so the shader sees an upright frame. Maps
+  // directly onto VisionCamera's `frame.orientation` / `frame.isMirrored`.
+  interface GPUExternalTextureDescriptor {
+    rotation?: 0 | 90 | 180 | 270;
+    mirrored?: boolean;
+  }
+
+  // Non-spec extension: a GPUExternalTexture imported from a native surface
+  // holds an open shared-memory access window on that surface until this
+  // wrapper is destroyed. Call destroy() right after the queue.submit() that
+  // sampled it (never before) to release the surface back to its producer
+  // immediately, instead of waiting for garbage collection. Forgetting to call
+  // it is not fatal (GC still cleans up), but it can starve a producer's buffer
+  // pool (e.g. a camera/video player) and pile up GPU resources.
+  interface GPUExternalTexture {
+    destroy(): void;
+  }
+
   // Extend createImageBitmap to accept ArrayBuffer/TypedArray (encoded image bytes)
   function createImageBitmap(
     image: ArrayBuffer | ArrayBufferView,

package/src/types.ts

@@ -16,5 +16,87 @@ export interface CanvasRef {
   getContextId: () => number;
   getContext(contextName: "webgpu"): RNCanvasContext | null;
   getNativeSurface: () => NativeCanvas;
-  whenReady: (callback: () => void) => void;
+}
+
+// Pixel layout of a NativeVideoFrame. NOT the WebCodecs `VideoPixelFormat`
+// enum — these are the two native surface layouts we support, lower-cased to
+// avoid being mistaken for the spec values ("NV12", "BGRA", …).
+export type NativeVideoPixelFormat = "bgra8" | "nv12";
+
+// A native, GPU-shareable handle to a single video frame.
+//
+// NOT the WebCodecs `VideoFrame`: there is no `close()`/`format`/`timestamp`,
+// the surface is referenced by a raw native pointer, and disposal is
+// `release()`. Named with a `Native` prefix so it doesn't shadow the global
+// WebCodecs type or imply spec semantics it doesn't have.
+//
+//   - handle is the raw pointer (IOSurfaceRef on Apple, AHardwareBuffer* on
+//     Android) encoded as a BigInt. Pass it to
+//     GPUDevice.importSharedTextureMemory.
+//   - pixelFormat describes the surface layout: 'bgra8' for a sampled
+//     GPUTexture; 'nv12' (biplanar Y + CbCr) for the importExternalTexture
+//     path.
+//   - release() drops the underlying backing object (a CVPixelBuffer on Apple).
+//     The frame is also released when the JS wrapper is garbage-collected; call
+//     release() eagerly when you know you're done.
+export interface NativeVideoFrame {
+  readonly handle: bigint;
+  readonly width: number;
+  readonly height: number;
+  readonly pixelFormat: NativeVideoPixelFormat;
+  release(): void;
+}
+
+// A handle to a decoded video stream. Poll copyLatestFrame() each render tick
+// to obtain the most recently decoded frame as an IOSurface/AHardwareBuffer
+// (returns null between frames so callers can skip the import work).
+export interface VideoPlayer {
+  copyLatestFrame(): NativeVideoFrame | null;
+  play(): void;
+  pause(): void;
+  release(): void;
+}
+
+export interface CreateVideoPlayerOptions {
+  // 'bgra8' (default): emit a single-plane BGRA surface, suitable for
+  // SharedTextureMemory and a regular sampled GPUTexture.
+  // 'nv12': emit biplanar Y + CbCr surfaces, suitable for
+  // GPUDevice.importExternalTexture.
+  pixelFormat?: NativeVideoPixelFormat;
+}
+
+export interface GPUSharedTextureMemoryDescriptor {
+  // Raw native handle (IOSurfaceRef on Apple, AHardwareBuffer* on Android),
+  // encoded as a BigInt. The caller is responsible for keeping the underlying
+  // object alive for as long as the shared memory (and any textures derived
+  // from it) are in use. Using NativeVideoFrame.handle handles this
+  // automatically.
+  handle: bigint;
+  label?: string;
+}
+
+// Non-standard, Dawn-only device toggles. Mirrors Dawn's DawnTogglesDescriptor
+// and is chained onto the native device descriptor at requestDevice time.
+// Pass it via the (augmented) GPUDeviceDescriptor: adapter.requestDevice({
+// dawnToggles: { enabledToggles: ["dump_shaders"] } }). Toggle names are open
+// strings (see Dawn's Toggles.cpp); these flags are Dawn-specific and
+// non-portable.
+export interface GPUDawnTogglesDescriptor {
+  enabledToggles?: string[];
+  disabledToggles?: string[];
+}
+
+// A piece of shared GPU memory backed by a native surface. Use createTexture()
+// to obtain a regular GPUTexture that aliases the surface's pixels. The
+// returned texture must be bracketed by beginAccess/endAccess around any
+// command-buffer submission that uses it.
+export interface GPUSharedTextureMemory {
+  readonly __brand: "GPUSharedTextureMemory";
+  label: string;
+  createTexture(descriptor?: GPUTextureDescriptor): GPUTexture;
+  // `initialized` declares whether the surface already holds meaningful pixels
+  // (true for an incoming video/camera frame, false if the next pass will fully
+  // overwrite it).
+  beginAccess(texture: GPUTexture, initialized: boolean): boolean;
+  endAccess(texture: GPUTexture): boolean;
 }