react-native-webgpu 0.16.1 → 0.17.0

package/android/src/main/java/com/webgpu/BackingViewKind.java

@@ -0,0 +1,38 @@
+package com.webgpu;
+
+import androidx.annotation.Nullable;
+
+/**
+ * The Android view a WebGPUView draws into, see WebGPUView.updateView(), and
+ * the rules the props resolve by. The JS side (Canvas.tsx) mirrors them to
+ * warn in development.
+ */
+enum BackingViewKind {
+  SURFACE_VIEW,
+  TEXTURE_VIEW,
+  HARDWARE_BUFFER_VIEW;
+
+  /**
+   * The kind the androidBackingView prop names; a TextureView by default. A
+   * HardwareBufferView (a plain View drawing AHardwareBuffers inline) needs
+   * Android 10: below it, the request falls back to a TextureView, which
+   * composites the same way, and the JS side warns about it in development.
+   */
+  static BackingViewKind fromBackingView(@Nullable String backingView, boolean hardwareBufferSupported) {
+    if ("SurfaceView".equals(backingView)) {
+      return SURFACE_VIEW;
+    }
+    if ("HardwareBufferView".equals(backingView) && hardwareBufferSupported) {
+      return HARDWARE_BUFFER_VIEW;
+    }
+    return TEXTURE_VIEW;
+  }
+
+  /**
+   * Whether the canvas composites as opaque: what the prop asks for, except
+   * that a HardwareBufferView always composites with alpha.
+   */
+  static boolean resolveOpaque(BackingViewKind kind, boolean opaque) {
+    return opaque && kind != HARDWARE_BUFFER_VIEW;
+  }
+}

package/android/src/main/java/com/webgpu/WebGPUSurfaceView.java

@@ -13,10 +13,12 @@ public class WebGPUSurfaceView extends SurfaceView implements SurfaceHolder.Call
 
   WebGPUAPI mApi;
 
-  public WebGPUSurfaceView(Context context, WebGPUAPI api, boolean zOrderOnTop, boolean opaque) {
+  public WebGPUSurfaceView(Context context, WebGPUAPI api, boolean zOrderOnTop,
+      boolean zOrderMediaOverlay, boolean opaque) {
     super(context);
     mApi = api;
-    setZOrderOnTop(zOrderOnTop);
+    // Both are read when the surface is created.
+    setZOrder(zOrderOnTop, zOrderMediaOverlay);
     setOpaque(opaque);
     getHolder().addCallback(this);
   }
@@ -27,6 +29,21 @@ public class WebGPUSurfaceView extends SurfaceView implements SurfaceHolder.Call
     getHolder().setFormat(opaque ? PixelFormat.OPAQUE : PixelFormat.TRANSLUCENT);
   }
 
+  // The sublayer the surface is composited at, relative to the window: above
+  // it (on top), or below it, above the other SurfaceViews there (media
+  // overlay) or among them (the default). setZOrderOnTop(false) resets the
+  // request to the default, so it goes first. Before Android 11 the request
+  // is read when the surface is created; from Android 11 on, SurfaceView
+  // applies a changed request with the window's next frame (its pre-draw
+  // listener runs updateSurface()), which invalidate() schedules.
+  public void setZOrder(boolean onTop, boolean mediaOverlay) {
+    setZOrderOnTop(onTop);
+    if (!onTop) {
+      setZOrderMediaOverlay(mediaOverlay);
+    }
+    invalidate();
+  }
+
   @Override
   protected void onDetachedFromWindow() {
     super.onDetachedFromWindow();

package/android/src/main/java/com/webgpu/WebGPUView.java

@@ -6,31 +6,36 @@ import android.util.Log;
 import android.view.Surface;
 import android.view.View;
 
+import androidx.annotation.Nullable;
+
 import com.facebook.proguard.annotations.DoNotStrip;
 import com.facebook.react.uimanager.ThemedReactContext;
 import com.facebook.react.views.view.ReactViewGroup;
 
+/**
+ * The Android view behind <Canvas>. It is backed by a TextureView, a
+ * SurfaceView or a HardwareBufferView, named by the androidBackingView prop
+ * and created once, from the props of the first transaction, for the life of
+ * the view (see updateView()).
+ */
 public class WebGPUView extends ReactViewGroup implements WebGPUAPI {
   private static final String TAG = "WebGPUView";
 
-  // Backing view kinds, see updateView().
-  private static final int KIND_SURFACE_VIEW = 0;
-  private static final int KIND_TEXTURE_VIEW = 1;
-  private static final int KIND_HARDWARE_BUFFER_VIEW = 2;
-
   private int mContextId;
-  // Props. opaque is applied in place, and so is zOrderOnTop where Android
-  // allows it (see setZOrderOnTop); surfaceType is read once, when the
+  // Props. opaque is applied in place, and so are the z-order props where
+  // Android allows it (see takesZOrder); backingView is read once, when the
   // backing view is created (see updateView()).
-  private boolean mOpaque = true;
-  private String mSurfaceType = "auto";
+  private BackingViewKind mBackingView = BackingViewKind.TEXTURE_VIEW;
+  private boolean mOpaque = false;
   private boolean mZOrderOnTop = false;
+  private boolean mZOrderMediaOverlay = false;
   private WebGPUModule mModule;
   // The backing view, created by the first prop transaction and kept, with
-  // the kind it was created with. The kind is -1 until then: it is what
+  // the kind it was created with. The kind is null until then: it is what
   // tells a mounted canvas apart.
   private View mView = null;
-  private int mKind = -1;
+  @Nullable
+  private BackingViewKind mKind = null;
   // Only a SurfaceView votes: a TextureView or HardwareBufferView is
   // composited into the window, which votes for it.
   private final SurfaceFrameRateVote mFrameRateVote = new SurfaceFrameRateVote(
@@ -58,11 +63,7 @@ public class WebGPUView extends ReactViewGroup implements WebGPUAPI {
     mContextId = contextId;
   }
 
-  public void setOpaque(boolean value) {
-    mOpaque = value;
-  }
-
-  // The backing view is chosen from the props of the first transaction and
+  // The backing view is created from the props of the first transaction and
   // kept (see updateView()). React calls a setter again only when its prop
   // changed, so a call on a mounted canvas is a change: the setters below
   // apply it in place where the view can take it, else they ignore it and
@@ -70,98 +71,99 @@ public class WebGPUView extends ReactViewGroup implements WebGPUAPI {
   // new key). The JS side warns about the same changes in development (see
   // Canvas.tsx), mirroring these rules.
 
-  public void setSurfaceType(String value) {
-    if (mKind != -1) {
-      warnIgnoredOnceMounted("android.surfaceType");
+  public void setBackingView(@Nullable String value) {
+    if (mKind != null) {
+      warnIgnoredOnceMounted("android.backingView");
       return;
     }
-    mSurfaceType = value;
+    boolean hardwareBufferSupported = Build.VERSION.SDK_INT >= Build.VERSION_CODES.Q;
+    mBackingView = BackingViewKind.fromBackingView(value, hardwareBufferSupported);
+  }
+
+  public void setOpaque(boolean value) {
+    mOpaque = value;
   }
 
   public void setZOrderOnTop(boolean value) {
-    if (mKind == -1) {
+    if (takesZOrder("android.zOrderOnTop")) {
       mZOrderOnTop = value;
-      return;
-    }
-    // Only a SurfaceView has a z-order of its own: elsewhere the prop never
-    // applied, and the change is moot.
-    if (mKind != KIND_SURFACE_VIEW) {
-      return;
-    }
-    if (!zOrderChangesInPlace()) {
-      warnIgnoredOnceMounted("android.zOrderOnTop");
-      return;
+      applyZOrder();
     }
-    mZOrderOnTop = value;
-    ((WebGPUSurfaceView) mView).setZOrderOnTop(value);
   }
 
-  private void warnIgnoredOnceMounted(String prop) {
-    Log.w(TAG, "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.");
+  public void setZOrderMediaOverlay(boolean value) {
+    if (takesZOrder("android.zOrderMediaOverlay")) {
+      mZOrderMediaOverlay = value;
+      applyZOrder();
+    }
   }
 
-  // SurfaceView.setZOrderOnTop() moves a live surface since Android 11, for
-  // an app targeting it; before that, the surface reads it when it is
-  // created (see updateView()).
-  private boolean zOrderChangesInPlace() {
-    return Build.VERSION.SDK_INT >= Build.VERSION_CODES.R
+  // Whether a z-order prop is taken. Before the backing view exists it is
+  // read when the view is created. After that only a SurfaceView has a
+  // z-order of its own (elsewhere the prop never applied, and the change is
+  // moot), and SurfaceView moves a live surface since Android 11, for an app
+  // targeting it; before that, the surface reads it when it is created.
+  private boolean takesZOrder(String prop) {
+    if (mKind == null) {
+      return true;
+    }
+    if (mKind != BackingViewKind.SURFACE_VIEW) {
+      return false;
+    }
+    boolean inPlace = Build.VERSION.SDK_INT >= Build.VERSION_CODES.R
         && getContext().getApplicationInfo().targetSdkVersion >= Build.VERSION_CODES.R;
+    if (!inPlace) {
+      warnIgnoredOnceMounted(prop);
+    }
+    return inPlace;
   }
 
-  // Resolve the backing view from the props. "auto" picks SurfaceView for an
-  // opaque canvas and TextureView for a non-opaque one. WebGPUHardwareBufferView
-  // (a plain View drawing AHardwareBuffers inline, API 29+) is opt-in via
-  // surfaceType until it gets a runtime fallback to TextureView when the
-  // AHardwareBuffer import fails on a device; below API 29 the request itself
-  // falls back to TextureView.
-  private int resolveKind() {
-    if ("SurfaceView".equals(mSurfaceType)) {
-      return KIND_SURFACE_VIEW;
-    }
-    if ("TextureView".equals(mSurfaceType)) {
-      return KIND_TEXTURE_VIEW;
+  private void applyZOrder() {
+    if (mKind == BackingViewKind.SURFACE_VIEW) {
+      ((WebGPUSurfaceView) mView).setZOrder(mZOrderOnTop, mZOrderMediaOverlay);
     }
-    if ("HardwareBufferView".equals(mSurfaceType)) {
-      boolean hardwareBufferSupported = Build.VERSION.SDK_INT >= Build.VERSION_CODES.Q;
-      return hardwareBufferSupported ? KIND_HARDWARE_BUFFER_VIEW : KIND_TEXTURE_VIEW;
-    }
-    return mOpaque ? KIND_SURFACE_VIEW : KIND_TEXTURE_VIEW;
+  }
+
+  private void warnIgnoredOnceMounted(String prop) {
+    Log.w(TAG, "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.");
   }
 
   // Apply the complete prop transaction once, after contextId and all rendering
   // options have arrived. The first one creates the backing view, which is
   // then kept: a SurfaceView must know its z-order before it attaches (before
-  // Android 11), and replacing a backing view on screen hands the canvas from
-  // one view to another, which no release of Android does without a frame of
-  // nothing, or of black, in between (the two views are composited by
-  // different frames). A canvas that needs another backing view is remounted
-  // instead. Later transactions apply the opacity in place (the setters decide
+  // Android 11), and keeping a canvas on screen while its backing view is
+  // replaced takes hold-and-retire logic specific to each Android release (see
+  // PR #563, and react-native-skia's #4189 and #4192), which this view does
+  // not carry. A canvas that needs another backing view is remounted instead,
+  // and is off screen for a frame or two until the new view draws its first
+  // frame. Later transactions apply the opacity in place (the setters decide
   // what else is taken); WebGPUHardwareBufferView always composites with
   // alpha, so there it is a no-op.
   public void updateView() {
-    if (mKind != -1) {
-      if (mKind == KIND_TEXTURE_VIEW) {
-        ((WebGPUTextureView) mView).setOpaque(mOpaque);
-      } else if (mKind == KIND_SURFACE_VIEW) {
-        ((WebGPUSurfaceView) mView).setOpaque(mOpaque);
+    if (mKind != null) {
+      boolean opaque = BackingViewKind.resolveOpaque(mKind, mOpaque);
+      if (mKind == BackingViewKind.TEXTURE_VIEW) {
+        ((WebGPUTextureView) mView).setOpaque(opaque);
+      } else if (mKind == BackingViewKind.SURFACE_VIEW) {
+        ((WebGPUSurfaceView) mView).setOpaque(opaque);
       }
       return;
     }
-    int kind = resolveKind();
-    boolean zOrderOnTop = kind == KIND_SURFACE_VIEW && mZOrderOnTop;
+    BackingViewKind kind = mBackingView;
     mKind = kind;
+    boolean opaque = BackingViewKind.resolveOpaque(kind, mOpaque);
     Context ctx = getContext();
     switch (kind) {
-      case KIND_HARDWARE_BUFFER_VIEW:
+      case HARDWARE_BUFFER_VIEW:
         mView = new WebGPUHardwareBufferView(ctx, this);
         break;
-      case KIND_TEXTURE_VIEW:
-        mView = new WebGPUTextureView(ctx, this, mOpaque);
+      case TEXTURE_VIEW:
+        mView = new WebGPUTextureView(ctx, this, opaque);
         break;
       default:
-        mView = new WebGPUSurfaceView(ctx, this, zOrderOnTop, mOpaque);
+        mView = new WebGPUSurfaceView(ctx, this, mZOrderOnTop, mZOrderMediaOverlay, opaque);
         break;
     }
     addView(mView);
@@ -188,7 +190,7 @@ public class WebGPUView extends ReactViewGroup implements WebGPUAPI {
     float density = getResources().getDisplayMetrics().density;
     float width = getWidth() / density;
     float height = getHeight() / density;
-    boolean votesFrameRate = mKind == KIND_SURFACE_VIEW;
+    boolean votesFrameRate = mKind == BackingViewKind.SURFACE_VIEW;
     if (votesFrameRate) {
       mFrameRateVote.attach(surface);
     }

package/android/src/main/java/com/webgpu/WebGPUViewManager.java

@@ -1,6 +1,7 @@
 package com.webgpu;
 
 import androidx.annotation.NonNull;
+import androidx.annotation.Nullable;
 
 import com.facebook.react.module.annotations.ReactModule;
 import com.facebook.react.uimanager.ThemedReactContext;
@@ -30,15 +31,15 @@ public class WebGPUViewManager extends WebGPUViewManagerSpec<WebGPUView> {
   }
 
   @Override
-  @ReactProp(name = "opaque", defaultBoolean = true)
-  public void setOpaque(WebGPUView view, boolean value) {
-    view.setOpaque(value);
+  @ReactProp(name = "androidBackingView")
+  public void setAndroidBackingView(WebGPUView view, @Nullable String value) {
+    view.setBackingView(value);
   }
 
   @Override
-  @ReactProp(name = "androidSurfaceType")
-  public void setAndroidSurfaceType(WebGPUView view, String value) {
-    view.setSurfaceType(value);
+  @ReactProp(name = "androidOpaque")
+  public void setAndroidOpaque(WebGPUView view, boolean value) {
+    view.setOpaque(value);
   }
 
   @Override
@@ -47,6 +48,12 @@ public class WebGPUViewManager extends WebGPUViewManagerSpec<WebGPUView> {
     view.setZOrderOnTop(value);
   }
 
+  @Override
+  @ReactProp(name = "androidZOrderMediaOverlay")
+  public void setAndroidZOrderMediaOverlay(WebGPUView view, boolean value) {
+    view.setZOrderMediaOverlay(value);
+  }
+
   @Override
   protected void onAfterUpdateTransaction(@NonNull WebGPUView view) {
     super.onAfterUpdateTransaction(view);

package/cpp/jsi/NativeObject.h

@@ -328,6 +328,11 @@ public:
       return; // Already installed on this runtime
     }
 
+    // Every wrapper is made by create(), which installs the prototype first,
+    // so the class is registered before any of its objects can be boxed,
+    // whether or not its constructor is ever installed as a global.
+    registerReconstructor();
+
     // Create prototype object
     jsi::Object prototype(runtime);
 
@@ -411,40 +416,10 @@ public:
    * Idempotent per runtime: once the global exists there, later calls return
    * without touching it, so the constructor object keeps its identity.
    *
-   * Also registers this class with NativeObjectRegistry so that
-   * BoxedWebGPUObject::unbox() can rebuild its objects on secondary runtimes.
+   * Not needed for objects to cross runtimes: installPrototype() registers
+   * the class with NativeObjectRegistry.
    */
   static void installConstructor(jsi::Runtime &runtime) {
-    // Register the reconstructor used by BoxedWebGPUObject::unbox() to
-    // rebuild this object (prototype + native state) on another runtime.
-    static std::once_flag registryFlag;
-    std::call_once(registryFlag, []() {
-      NativeObjectRegistry::getInstance().registerClass(
-          Derived::CLASS_NAME,
-          [](jsi::Runtime &rt,
-             std::shared_ptr<jsi::NativeState> state) -> jsi::Value {
-            auto instance = std::dynamic_pointer_cast<Derived>(state);
-            if (instance == nullptr) {
-              throw jsi::JSError(rt, "Invalid boxed native object state");
-            }
-            // The constructor makes `instanceof` work on this runtime too
-            // (a no-op once it is installed there).
-            Derived::installConstructor(rt);
-            // Unboxing hands back the wrapper cached for the target runtime,
-            // creating it on first use. Keep the runtime the object was
-            // originally created on: async native code (GPUDevice error/lost
-            // events, GPUAdapter::requestDevice) delivers into the creation
-            // runtime, and rebinding it to a worklet runtime would invoke
-            // main-runtime jsi::Functions on the wrong runtime and thread.
-            auto *originalRuntime = instance->getCreationRuntime();
-            auto value = Derived::create(rt, instance);
-            if (originalRuntime != nullptr) {
-              instance->setCreationRuntime(originalRuntime);
-            }
-            return value;
-          });
-    });
-
     installPrototype(runtime);
 
     // Once per runtime. installWebGPU() runs this at the top of every worklet
@@ -481,6 +456,41 @@ public:
     runtime.global().setProperty(runtime, Derived::CLASS_NAME, std::move(ctor));
   }
 
+  /**
+   * Registers the reconstructor BoxedWebGPUObject::unbox() uses to rebuild
+   * this class's objects (prototype + native state) on another runtime.
+   * Once per process: the registry outlives every runtime.
+   */
+  static void registerReconstructor() {
+    static std::once_flag registryFlag;
+    std::call_once(registryFlag, []() {
+      NativeObjectRegistry::getInstance().registerClass(
+          Derived::CLASS_NAME,
+          [](jsi::Runtime &rt,
+             std::shared_ptr<jsi::NativeState> state) -> jsi::Value {
+            auto instance = std::dynamic_pointer_cast<Derived>(state);
+            if (instance == nullptr) {
+              throw jsi::JSError(rt, "Invalid boxed native object state");
+            }
+            // The constructor makes `instanceof` work on this runtime too
+            // (a no-op once it is installed there).
+            Derived::installConstructor(rt);
+            // Unboxing hands back the wrapper cached for the target runtime,
+            // creating it on first use. Keep the runtime the object was
+            // originally created on: async native code (GPUDevice error/lost
+            // events, GPUAdapter::requestDevice) delivers into the creation
+            // runtime, and rebinding it to a worklet runtime would invoke
+            // main-runtime jsi::Functions on the wrong runtime and thread.
+            auto *originalRuntime = instance->getCreationRuntime();
+            auto value = Derived::create(rt, instance);
+            if (originalRuntime != nullptr) {
+              instance->setCreationRuntime(originalRuntime);
+            }
+            return value;
+          });
+    });
+  }
+
   /**
    * Returns the JS wrapper of `instance` on `runtime`, creating it on first
    * use.

package/cpp/rnwgpu/RNWebGPUManager.cpp

@@ -41,6 +41,7 @@
 #include "GPUTextureView.h"
 #include "GPUUncapturedErrorEvent.h"
 #include "GPUValidationError.h"
+#include "ImageBitmap.h"
 #include "VideoFrame.h"
 #include "VideoPlayer.h"
 
@@ -78,11 +79,6 @@ RNWebGPUManager::RNWebGPUManager(
       std::make_shared<RNWebGPU>(gpu, _platformContext, _jsCallInvoker);
   _gpu = gpu->get();
 
-  // RNWebGPU needs its brand registered in NativeObjectRegistry so the boxing
-  // path can install the prototype on worklet runtimes. installConstructor
-  // does that registration but also sets globalThis.RNWebGPU = ctor, so we
-  // call it FIRST and then overwrite the global with the actual instance.
-  RNWebGPU::installConstructor(*_jsRuntime);
   _jsRuntime->global().setProperty(*_jsRuntime, "RNWebGPU",
                                    RNWebGPU::create(*_jsRuntime, rnWebGPU));
 
@@ -144,6 +140,7 @@ void RNWebGPUManager::installConstructors(jsi::Runtime &runtime) {
   GPUSupportedLimits::installConstructor(runtime);
   GPUTexture::installConstructor(runtime);
   GPUTextureView::installConstructor(runtime);
+  ImageBitmap::installConstructor(runtime);
   VideoFrame::installConstructor(runtime);
   VideoPlayer::installConstructor(runtime);
 }

package/cpp/rnwgpu/api/GPUFeatures.h

@@ -104,6 +104,7 @@ namespace rnwgpu {
   V(AdapterPropertiesWGPU, "adapter-properties-wgpu")                          \
   V(SharedBufferMemoryFromWindowsHandle,                                       \
     "shared-buffer-memory-from-windows-handle")                                \
+  V(SharedBufferMemoryHostPointer, "shared-buffer-memory-host-pointer")        \
   V(SharedTextureMemoryD3D12Resource, "shared-texture-memory-d3d12-resource")  \
   V(ChromiumExperimentalSamplingResourceTable,                                 \
     "chromium-experimental-sampling-resource-table")                           \

package/cpp/rnwgpu/api/VideoFrame.h

@@ -21,8 +21,8 @@ namespace jsi = facebook::jsi;
 class VideoFrame : public NativeObject<VideoFrame> {
 public:
   // JS-facing brand. installConstructor() exposes this as
-  // globalThis[CLASS_NAME] and keys the NativeObjectRegistry / worklet
-  // serializer off it, so it must NOT be "VideoFrame": that would install our
+  // globalThis[CLASS_NAME], and the NativeObjectRegistry / worklet serializer
+  // are keyed off it, so it must NOT be "VideoFrame": that would install our
   // constructor over the WebCodecs `VideoFrame` global and shadow it at
   // runtime. "NativeVideoFrame" matches the public TypeScript type (see
   // src/types.ts) and keeps the two namespaces distinct. The C++ class stays