react-native-webgpu 0.16.1 → 0.19.0

package/android/cpp/AndroidPlatformContext.h

@@ -3,6 +3,7 @@
 #include <android/bitmap.h>
 #include <android/data_space.h>
 #include <android/hardware_buffer.h>
+#include <android/native_window.h>
 #include <dlfcn.h>
 #include <jni.h>
 
@@ -469,6 +470,13 @@ public:
         "writeTestVideoFile is not yet implemented on Android.");
   }
 
+  std::function<void(void *)> retainNativeWindow(void *window) override {
+    ANativeWindow_acquire(static_cast<ANativeWindow *>(window));
+    return [](void *nativeWindow) {
+      ANativeWindow_release(static_cast<ANativeWindow *>(nativeWindow));
+    };
+  }
+
   VideoFrameHandle wrapNativeBuffer(void *pointer) override {
     if (!pointer) {
       throw std::runtime_error("wrapNativeBuffer: pointer is null");

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/apple/ApplePlatformContext.h

@@ -48,6 +48,8 @@ public:
 
   VideoFrameHandle wrapNativeBuffer(void *pointer) override;
 
+  std::function<void(void *)> retainNativeWindow(void *window) override;
+
 private:
   ViewLookup _viewLookup;
 };

package/apple/ApplePlatformContext.mm

@@ -556,6 +556,18 @@ VideoFrameHandle ApplePlatformContext::wrapNativeBuffer(void *pointer) {
   return wrapCVPixelBuffer(static_cast<CVPixelBufferRef>(pointer));
 }
 
+std::function<void(void *)>
+ApplePlatformContext::retainNativeWindow(void *window) {
+  CFRetain(window);
+  return [](void *layer) {
+    // As MetalView's: the releaser can run on the rendering thread, and
+    // CALayer teardown belongs on the main thread.
+    dispatch_async(dispatch_get_main_queue(), ^{
+      CFRelease(layer);
+    });
+  };
+}
+
 // The NV12 variant of createTestVideoFrame: a biplanar BT.709 limited-range
 // frame, red on the left half and green on the right, whose attachments
 // declare its color space the way the decoder's frames do, so that the

package/apple/MetalLayerColorSpace.mm

@@ -3,32 +3,44 @@
 #import <QuartzCore/CAMetalLayer.h>
 #import <QuartzCore/CATransaction.h>
 
+#include "CanvasColorSpace.h"
 #include "webgpu/webgpu_cpp.h"
 
 namespace rnwgpu {
 
-// WebGPU canvas values are sRGB-encoded regardless of the texture format
-// (GPUCanvasConfiguration.colorSpace defaults to "srgb"), so the same shader
+// WebGPU canvas values are encoded with the sRGB transfer function regardless
+// of the texture format, and GPUCanvasConfiguration.colorSpace says which
+// primaries they are in: "srgb" (the default) or "display-p3". The same shader
 // output must display identically on bgra8unorm and rgba16float surfaces.
 // Core Animation interprets a float-format layer with a nil colorspace as
 // extended *linear* sRGB, which displays the same values noticeably brighter.
 // Tagging the layer as (gamma-encoded) extended sRGB matches the browser
-// behavior: identical colors, with the extra precision of float16.
+// behavior: identical colors, with the extra precision of float16. For
+// "display-p3" the layer is tagged Display P3 instead, or its extended range
+// variant on a float format, so the values reach a wide-gamut display without
+// being converted from sRGB first.
 void applyCAMetalLayerColorSpace(void *nativeSurface,
-                                 wgpu::TextureFormat format) {
+                                 wgpu::TextureFormat format,
+                                 CanvasColorSpace canvasColorSpace) {
   CALayer *layer = (__bridge CALayer *)nativeSurface;
   if (![layer isKindOfClass:[CAMetalLayer class]]) {
     return;
   }
   auto metalLayer = static_cast<CAMetalLayer *>(layer);
-  if (format == wgpu::TextureFormat::RGBA16Float) {
-    CGColorSpaceRef colorSpace =
-        CGColorSpaceCreateWithName(kCGColorSpaceExtendedSRGB);
+  const bool isFloat = format == wgpu::TextureFormat::RGBA16Float;
+  CFStringRef name = nullptr;
+  if (canvasColorSpace == CanvasColorSpace::DisplayP3) {
+    name = isFloat ? kCGColorSpaceExtendedDisplayP3 : kCGColorSpaceDisplayP3;
+  } else if (isFloat) {
+    name = kCGColorSpaceExtendedSRGB;
+  }
+  if (name != nullptr) {
+    CGColorSpaceRef colorSpace = CGColorSpaceCreateWithName(name);
     metalLayer.colorspace = colorSpace;
     CGColorSpaceRelease(colorSpace);
   } else if (metalLayer.colorspace != nil) {
     // Restore the default (no color matching) when reconfiguring back to an
-    // 8-bit format.
+    // 8-bit sRGB canvas.
     metalLayer.colorspace = nil;
   }
   // The change must be set synchronously so the first present already sees

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/CanvasColorSpace.h

@@ -0,0 +1,9 @@
+#pragma once
+
+namespace rnwgpu {
+
+// GPUCanvasConfiguration.colorSpace (PredefinedColorSpace): how the canvas's
+// values are interpreted when it is composited.
+enum class CanvasColorSpace { SRGB, DisplayP3 };
+
+} // namespace rnwgpu

package/cpp/rnwgpu/PlatformContext.h

@@ -243,6 +243,12 @@ public:
   // safely release their own reference immediately after.
   virtual VideoFrameHandle wrapNativeBuffer(void *pointer) = 0;
 
+  // Retain a native window obtained from another library, to present to it
+  // (an ANativeWindow* on Android, a CAMetalLayer* on Apple platforms), and
+  // return the releaser that balances that reference once the surface is done
+  // with it. The releaser can run on any thread.
+  virtual std::function<void(void *)> retainNativeWindow(void *window) = 0;
+
   // Write a small procedurally-generated test video to a temporary location
   // and return its absolute path. Lets the SharedTextureMemory example play
   // a real decoded video without bundling an asset.

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);
 }
@@ -170,9 +167,9 @@ void RNWebGPUManager::flushPendingSurfaceTransition(
 }
 
 RNWebGPUManager::~RNWebGPUManager() {
-  // Drop all canvas registry entries: after a reload the JS side restarts its
-  // contextId counter, and stale entries would alias new canvases onto dead
-  // surfaces.
+  // Drop the canvas registry entries of this runtime's bundle: its canvases
+  // never run their JS cleanup, and their ids are not handed out again (see
+  // SurfaceRegistry::allocateContextId).
   SurfaceRegistry::getInstance().clear();
   if (PlatformContext::current() == _platformContext) {
     PlatformContext::setCurrent(nullptr);