react-native-webgpu 0.16.0 → 0.17.0

package/src/Canvas.tsx

@@ -12,47 +12,196 @@ function generateContextId() {
   return CONTEXT_COUNTER++;
 }
 
-export type AndroidSurfaceType =
-  "SurfaceView" | "TextureView" | "HardwareBufferView";
+/** The Android view a canvas draws into, see {@link AndroidCanvasProps}. */
+export type AndroidBackingView =
+  "TextureView" | "SurfaceView" | "HardwareBufferView";
 
-export interface AndroidCanvasProps {
+/** The options of a canvas backed by a `TextureView`, the default. */
+export interface AndroidTextureViewProps {
   /**
-   * Backing view. Defaults to `SurfaceView` when the canvas is opaque and to
-   * `TextureView` otherwise; both composite correctly in React Native
-   * stacking order without further flags. `HardwareBufferView` (Android 10+,
-   * a plain View that draws each frame's AHardwareBuffer inline with no extra
-   * copy) is opt-in and experimental; on older devices it uses `TextureView`.
+   * A `TextureView`: a regular view, composited like any other (parent
+   * transforms, clipping, alpha and z-order apply), at the price of an extra
+   * texture copy and typically a frame of latency. The default.
    */
-  surfaceType?: AndroidSurfaceType;
+  backingView?: "TextureView";
   /**
-   * SurfaceView only: composite above every React Native view in the window,
-   * ignoring `zIndex`. Ignored for TextureView. Defaults to false.
+   * Declares that the canvas covers every pixel of its bounds, so the UI
+   * toolkit skips blending the view. Defaults to false. Applied in place.
+   */
+  opaque?: boolean;
+}
+
+/** The options of a canvas backed by a `SurfaceView`. */
+export interface AndroidSurfaceViewProps {
+  /**
+   * A `SurfaceView`: each frame goes to the system compositor as its own
+   * layer, the fastest path, with no extra copy. It is not view content:
+   * parent transforms, clipping, rounded corners and z-order with sibling
+   * views do not apply to it.
+   */
+  backingView: "SurfaceView";
+  /**
+   * Declares that the canvas covers every pixel of its bounds, so the
+   * compositor skips blending the layer and can show it through a hardware
+   * overlay. Defaults to true: a translucent `SurfaceView` blends against
+   * what is below the window, usually black, rather than the React Native
+   * views beneath it (pair it with `zOrderOnTop`). Applied in place.
+   */
+  opaque?: boolean;
+  /**
+   * Composite above every React Native view in the window, ignoring
+   * `zIndex`. Defaults to false. Applied in place on Android 11 and later;
+   * read once, at mount, before that.
    */
   zOrderOnTop?: boolean;
+  /**
+   * Composite above the other `SurfaceView`s below the window (video players,
+   * other canvases), while staying below the window itself. Defaults to
+   * false; `zOrderOnTop` takes precedence. Applied in place on Android 11 and
+   * later; read once, at mount, before that.
+   */
+  zOrderMediaOverlay?: boolean;
+}
+
+/** The options of a canvas backed by a `HardwareBufferView`. */
+export interface AndroidHardwareBufferViewProps {
+  /**
+   * A plain view drawing each frame's `AHardwareBuffer` inline: composited
+   * like a `TextureView`, without its extra copy. Opt-in and experimental,
+   * on Android 10 and later; below that the canvas uses a `TextureView`,
+   * with a warning in development. Always composites with alpha.
+   */
+  backingView: "HardwareBufferView";
 }
 
+/**
+ * Android-only rendering options: the native view behind the canvas and its
+ * options. The view is created when the canvas mounts and kept: a change of
+ * `backingView` is ignored, with a warning in development; remount the canvas
+ * (with a `key`) to change it. `opaque` applies in place, and so do the
+ * z-order options on Android 11 and later. Ignored on iOS and web.
+ */
+export type AndroidCanvasProps =
+  | AndroidTextureViewProps
+  | AndroidSurfaceViewProps
+  | AndroidHardwareBufferViewProps;
+
 export interface CanvasProps extends ViewProps {
   /**
-   * Defaults to true. Set to false to alpha-composite the canvas over the
-   * views behind it (pair it with `alphaMode: "premultiplied"` and an alpha-0
-   * clear color). Android and web only; on iOS `alphaMode` alone controls it.
+   * Android-only rendering options: the native view behind the canvas and its
+   * options, see {@link AndroidCanvasProps}. Ignored on iOS and web.
    */
-  opaque?: boolean;
-  /** Android-only rendering options. Ignored on iOS and web. */
   android?: AndroidCanvasProps;
   ref?: React.Ref<CanvasRef>;
 }
 
+// The union read as one bag of options; which of them apply to the view is
+// decided below, as it is on the native side.
+type AndroidOptions = Partial<{
+  backingView: AndroidBackingView;
+  opaque: boolean;
+  zOrderOnTop: boolean;
+  zOrderMediaOverlay: boolean;
+}>;
+
+const options = (android?: AndroidCanvasProps): AndroidOptions =>
+  (android ?? {}) as AndroidOptions;
+
 // Anything else reaching the native component would hit the generated
 // string-enum parser, which aborts on unknown values.
-const resolveSurfaceType = (
-  surfaceType: AndroidSurfaceType | undefined,
-): "auto" | AndroidSurfaceType =>
-  surfaceType === "SurfaceView" ||
-  surfaceType === "TextureView" ||
-  surfaceType === "HardwareBufferView"
-    ? surfaceType
-    : "auto";
+const resolveBackingView = (
+  android?: AndroidCanvasProps,
+): AndroidBackingView => {
+  const { backingView } = options(android);
+  return backingView === "SurfaceView" || backingView === "HardwareBufferView"
+    ? backingView
+    : "TextureView";
+};
+
+// Whether the canvas composites as opaque, see BackingViewKind.resolveOpaque():
+// a SurfaceView is opaque unless asked otherwise, a TextureView is translucent
+// unless asked otherwise, and a HardwareBufferView always composites with
+// alpha.
+const resolveOpaque = (android?: AndroidCanvasProps): boolean => {
+  const { opaque } = options(android);
+  switch (resolveBackingView(android)) {
+    case "SurfaceView":
+      return opaque !== false;
+    case "TextureView":
+      return opaque === true;
+    case "HardwareBufferView":
+      return false;
+  }
+};
+
+// The native props the `android` prop resolves to.
+const androidNativeProps = (android?: AndroidCanvasProps) => {
+  const backingView = resolveBackingView(android);
+  const { zOrderOnTop, zOrderMediaOverlay } = options(android);
+  const surfaceView = backingView === "SurfaceView";
+  return {
+    androidBackingView: backingView,
+    androidOpaque: resolveOpaque(android),
+    androidZOrderOnTop: surfaceView && !!zOrderOnTop,
+    androidZOrderMediaOverlay: surfaceView && !!zOrderMediaOverlay,
+  };
+};
+
+const warnIgnoredChange = (prop: string) =>
+  console.warn(
+    `Ignoring a change of ${prop} on a mounted canvas: the backing view is ` +
+      "chosen when the canvas mounts. Remount the canvas (give it a new key) " +
+      "to change it.",
+  );
+
+// Warns, in development on Android, about an option a mounting canvas asks
+// for that the native view cannot honour, and about a change of these props
+// that the native view ignores: the backing view is created from them when
+// the canvas mounts (see WebGPUView.java, whose setters these rules mirror).
+// The native side only says so in logcat, which is not where a JS developer
+// looks.
+const useBackingViewWarning = (android?: AndroidCanvasProps) => {
+  const mount = useRef(android);
+  const prev = useRef(android);
+  useEffect(() => {
+    if (
+      __DEV__ &&
+      Platform.OS === "android" &&
+      resolveBackingView(mount.current) === "HardwareBufferView" &&
+      Number(Platform.Version) < 29
+    ) {
+      console.warn(
+        "android.backingView: HardwareBufferView needs Android 10, the " +
+          "canvas uses a TextureView.",
+      );
+    }
+  }, []);
+  useEffect(() => {
+    if (__DEV__ && Platform.OS === "android") {
+      const { current: before } = prev;
+      if (resolveBackingView(before) !== resolveBackingView(android)) {
+        warnIgnoredChange("android.backingView");
+      }
+      // Only a SurfaceView has a z-order of its own, which Android 11 and
+      // later changes in place.
+      const zOrderAtMount =
+        resolveBackingView(mount.current) === "SurfaceView" &&
+        Number(Platform.Version) < 30;
+      const was = options(before);
+      const is = options(android);
+      if (zOrderAtMount && !!was.zOrderOnTop !== !!is.zOrderOnTop) {
+        warnIgnoredChange("android.zOrderOnTop");
+      }
+      if (
+        zOrderAtMount &&
+        !!was.zOrderMediaOverlay !== !!is.zOrderMediaOverlay
+      ) {
+        warnIgnoredChange("android.zOrderMediaOverlay");
+      }
+    }
+    prev.current = android;
+  });
+};
 
 // A view measured relative to itself gets its layout size, without the
 // transforms getBoundingClientRect() includes; measureLayout() calls back
@@ -72,14 +221,10 @@ const measureLayout = (view: View) => {
   return size;
 };
 
-export const Canvas = ({
-  opaque = true,
-  android,
-  ref,
-  ...props
-}: CanvasProps) => {
+export const Canvas = ({ android, ref, ...props }: CanvasProps) => {
   const viewRef = useRef<View>(null);
   const [contextId, _] = useState(() => generateContextId());
+  useBackingViewWarning(android);
   // Retire the native registry entry for this contextId on unmount. When a
   // native surface is still attached, this is a no-op and the native view's
   // own teardown retires the entry instead — which keeps StrictMode's
@@ -123,9 +268,7 @@ export const Canvas = ({
       <WebGPUNativeView
         style={{ flex: 1 }}
         contextId={contextId}
-        opaque={opaque}
-        androidSurfaceType={resolveSurfaceType(android?.surfaceType)}
-        androidZOrderOnTop={!!android?.zOrderOnTop}
+        {...androidNativeProps(android)}
       />
     </View>
   );

package/src/WebGPUViewNativeComponent.ts

@@ -7,12 +7,14 @@ import type { ViewProps } from "react-native";
 
 export interface NativeProps extends ViewProps {
   contextId: Int32;
-  opaque?: WithDefault<boolean, true>;
-  androidSurfaceType?: WithDefault<
-    "auto" | "SurfaceView" | "TextureView" | "HardwareBufferView",
-    "auto"
+  // The `android` prop, resolved (see Canvas.tsx)
+  androidBackingView?: WithDefault<
+    "TextureView" | "SurfaceView" | "HardwareBufferView",
+    "TextureView"
   >;
+  androidOpaque?: WithDefault<boolean, false>;
   androidZOrderOnTop?: WithDefault<boolean, false>;
+  androidZOrderMediaOverlay?: WithDefault<boolean, false>;
 }
 
 // eslint-disable-next-line import/no-default-export

package/src/WebGPUViewNativeComponent.web.ts

@@ -7,9 +7,11 @@ import { contextIdToId } from "./utils";
 
 export interface NativeProps extends ViewProps {
   contextId: Int32;
-  opaque?: boolean;
-  androidSurfaceType?: "auto" | "SurfaceView" | "TextureView";
+  // The `android` prop, resolved: Android-only, never reaches the DOM
+  androidBackingView?: "TextureView" | "SurfaceView" | "HardwareBufferView";
+  androidOpaque?: boolean;
   androidZOrderOnTop?: boolean;
+  androidZOrderMediaOverlay?: boolean;
 }
 
 // eslint-disable-next-line import/no-default-export
@@ -19,9 +21,10 @@ export default function WebGPUViewNativeComponent(
   const {
     contextId,
     style,
-    opaque = true,
-    androidSurfaceType: _androidSurfaceType,
+    androidBackingView: _androidBackingView,
+    androidOpaque: _androidOpaque,
     androidZOrderOnTop: _androidZOrderOnTop,
+    androidZOrderMediaOverlay: _androidZOrderMediaOverlay,
     ...rest
   } = props;
 
@@ -34,7 +37,6 @@ export default function WebGPUViewNativeComponent(
     style: {
       ...styles.view,
       ...styles.flex1,
-      ...(opaque ? { backgroundColor: "white" } : {}),
       ...(typeof style === "object" ? style : {}),
     },
   });

package/src/external/reanimated/registerWebGPUForReanimated.ts

@@ -10,6 +10,10 @@ interface WebGPUWorkletHelpers {
   // WebGPU prototype are rejected, and no JS property is ever read.
   isNativeObject: (value: unknown) => boolean;
   box: (value: object) => BoxedWebGPUObject;
+  // Installs the constructor of every WebGPU class on the calling runtime,
+  // skipping the ones already there. installWebGPU() calls it so `instanceof`
+  // works on worklet runtimes.
+  installConstructors: () => void;
 }
 
 interface BoxedWebGPUObject {

package/src/index.tsx

@@ -159,9 +159,9 @@ declare global {
   // What is captured is what the platform renders for the view hierarchy
   // (iOS: UIView.drawViewHierarchyInRect; Android API 29+: HardwareRenderer
   // over the views' display lists, older: View.draw into a software canvas).
-  // On Android, SurfaceView content (a WebGPU Canvas with the default
-  // "SurfaceView" surfaceType, video players) is not part of the hierarchy and
-  // comes out blank; use `android={{ surfaceType: "TextureView" }}` for a
+  // On Android, SurfaceView content (a WebGPU Canvas with
+  // `android={{ backingView: "SurfaceView" }}`, video players) is not part of
+  // the hierarchy and comes out blank; keep the default TextureView for a
   // canvas that must be captured.
   interface GPUQueue {
     drawElementImageToTexture(

package/src/install.ts

@@ -29,14 +29,25 @@ const constants = {
 const gpu: GPU | undefined =
   typeof RNWebGPU === "undefined" ? undefined : RNWebGPU.gpu;
 
+// The native half of the worklet serializer (see registerWebGPUForReanimated),
+// read from the main runtime like `gpu` above and captured into the worklet
+// closure: worklets hands a HostObject to every runtime by reference, so it is
+// callable on the target runtime without installing anything there. Its
+// installConstructors() installs the WebGPU class constructors on the runtime
+// that calls it. Undefined on web and node, where the native module is not
+// installed.
+const helpers = globalThis.__webgpuWorkletHelpers;
+
 /**
  * Install WebGPU on the runtime that calls it.
  *
  * The native module sets up WebGPU on the main JS runtime, but worklet
  * runtimes (Reanimated UI, dedicated worklet runtimes, Vision Camera frame
- * processors) start without it: `navigator.gpu` and the flag constants
+ * processors) start without it: `navigator.gpu`, the flag constants
  * (`GPUBufferUsage`, `GPUTextureUsage`, `GPUShaderStage`, `GPUColorWrite`,
- * `GPUMapMode`) are all `undefined` there.
+ * `GPUMapMode`) and the class constructors (`GPUBuffer`, `GPUTexture`,
+ * `GPURenderBundleEncoder`, ...) are all `undefined` there. Without the
+ * constructors, `instanceof` against a WebGPU class throws a ReferenceError.
  *
  * Call `installWebGPU()` once at the top of a worklet to make them available:
  *
@@ -65,12 +76,13 @@ const gpu: GPU | undefined =
  *   Observe those on a device created on the main JS thread.
  *
  * Everything is captured into the worklet by closure: the constants like a
- * shader string would be, and the GPU object through the Worklets custom
+ * shader string would be, the GPU object through the Worklets custom
  * serializer, which installs the native prototypes on the target runtime when
- * it crosses. Promises returned by `requestAdapter`/`requestDevice` settle on
- * the calling runtime (each runtime gets its own async pump). Calling it on a
- * runtime that already has the globals (e.g. the main JS runtime) is a safe
- * no-op.
+ * it crosses, and the native helper that installs the class constructors,
+ * which worklets hands to every runtime by reference. Promises returned by
+ * `requestAdapter`/`requestDevice` settle on the calling runtime (each
+ * runtime gets its own async pump). Calling it on a runtime that already has
+ * the globals (e.g. the main JS runtime) is a safe no-op.
  */
 export const installWebGPU = () => {
   "worklet";
@@ -88,4 +100,11 @@ export const installWebGPU = () => {
       nav.gpu = gpu;
     }
   }
+  // The class constructors, so `instanceof` works against any WebGPU class on
+  // this runtime (three.js checks `pass instanceof GPURenderBundleEncoder` on
+  // every render, for instance). Unboxing an object installs only its own
+  // class; this installs the rest and skips the ones already there.
+  if (helpers !== undefined) {
+    helpers.installConstructors();
+  }
 };

package/src/mock.ts

@@ -82,8 +82,11 @@ const NOT_AVAILABLE_UNDER_JEST =
   "is not available under Jest - react-native-webgpu has no native implementation in tests (see react-native-webgpu/jestSetup.js)";
 
 export type {
+  AndroidBackingView,
   AndroidCanvasProps,
-  AndroidSurfaceType,
+  AndroidHardwareBufferViewProps,
+  AndroidSurfaceViewProps,
+  AndroidTextureViewProps,
   CanvasProps,
   CanvasRef,
   NativeCanvas,
@@ -91,12 +94,7 @@ export type {
 } from "./Canvas";
 
 // Strip the same props the real Canvas keeps off its outer View.
-export const Canvas = ({
-  opaque: _opaque,
-  android: _android,
-  ref,
-  ...props
-}: CanvasProps) => {
+export const Canvas = ({ android: _android, ref, ...props }: CanvasProps) => {
   React.useImperativeHandle(ref, () => ({
     getContextId: () => -1,
     getContext: (_contextName: "webgpu"): RNCanvasContext | null => null,

package/src/types.ts

@@ -21,7 +21,7 @@ export type RNCanvasContext = GPUCanvasContext & {
    *
    * Call this after `queue.submit()` on every runtime: the main JS runtime, the
    * Reanimated UI runtime, and dedicated worklet runtimes (e.g.
-   * `createWorkletRuntime` / `runOnRuntime`, or a Vision Camera frame
+   * `createWorkletRuntime` / `scheduleOnRuntime`, or a Vision Camera frame
    * processor). It runs synchronously on the calling thread, so the frame is
    * presented from whichever thread did the rendering.
    */