react-native-webgpu 0.13.1 → 0.14.1

package/cpp/rnwgpu/WebGPURuntime.cpp

@@ -0,0 +1,91 @@
+#include "WebGPURuntime.h"
+
+#include <dlfcn.h>
+
+#include <iterator>
+
+namespace rnwgpu {
+
+namespace {
+
+wgpu::Instance createInstance() {
+  // If a Graphite build of react-native-skia is loaded in this
+  // process, adopt its wgpu::Instance instead of creating our own, so
+  // Graphite's device and every JS-created device live on one instance. That
+  // makes pointer-based handoff (RNWebGPU.importDevice of Skia's device)
+  // sound: the async pump serves the shared instance, so callbacks on
+  // imported devices settle. Discovered at runtime via dlsym so there is no
+  // build-time coupling and native-module init order does not matter. Both
+  // packages must link the same single Dawn copy (they vendor the same
+  // artifact) for the handle to be meaningful.
+  using GetInstanceFn = WGPUInstance (*)();
+  if (auto getSkiaInstance = reinterpret_cast<GetInstanceFn>(
+          dlsym(RTLD_DEFAULT, "rnskia_getWGPUInstance"))) {
+    if (WGPUInstance external = getSkiaInstance()) {
+      wgpuInstanceAddRef(external);
+      return wgpu::Instance::Acquire(external);
+    }
+  }
+
+  static const auto kTimedWaitAny = wgpu::InstanceFeatureName::TimedWaitAny;
+  wgpu::InstanceDescriptor instanceDesc{.requiredFeatureCount = 1,
+                                        .requiredFeatures = &kTimedWaitAny};
+
+  wgpu::InstanceLimits limits{.timedWaitAnyMaxCount = 64};
+  instanceDesc.requiredLimits = &limits;
+
+  // Expose Dawn's experimental adapter features. Several features needed by
+  // our Android external-texture path (YCbCrVulkanSamplers,
+  // OpaqueYCbCrAndroidForExternalTexture) are tagged Experimental in Dawn's
+  // feature table and are otherwise filtered out of adapter.features by
+  // PhysicalDeviceBase::GetSupportedFeatures. The allow_unsafe_apis toggle
+  // disables that filter so the features become visible;
+  // expose_wgsl_experimental_features is the parallel toggle for WGSL language
+  // features.
+  //
+  // Trade-off: these are instance-level Dawn toggles, so they apply to every
+  // adapter/device created from this instance, not just the external-texture
+  // path. There is no finer-grained, per-feature mechanism to surface these.
+  // The exposure is acceptable because the toggle only *un-hides* experimental
+  // features in adapter.features; it does not enable any of them. Nothing
+  // experimental becomes active unless application code explicitly lists that
+  // feature in requiredFeatures at device creation, so the default behavior of
+  // a device that asks for no experimental features is unchanged.
+  static const char *const kEnabledToggles[] = {
+      "allow_unsafe_apis",
+      "expose_wgsl_experimental_features",
+  };
+  wgpu::DawnTogglesDescriptor toggles;
+  toggles.enabledToggleCount = std::size(kEnabledToggles);
+  toggles.enabledToggles = kEnabledToggles;
+  instanceDesc.nextInChain = &toggles;
+
+  return wgpu::CreateInstance(&instanceDesc);
+}
+
+} // namespace
+
+WebGPURuntime &WebGPURuntime::shared() {
+  static auto *runtime = new WebGPURuntime();
+  return *runtime;
+}
+
+wgpu::Instance WebGPURuntime::instance() {
+  std::call_once(_instanceOnce, [this] { _instance = createInstance(); });
+  return _instance;
+}
+
+wgpu::Surface WebGPURuntime::makeSurface(void *nativeSurface) {
+#if defined(__ANDROID__)
+  wgpu::SurfaceSourceAndroidNativeWindow source;
+  source.window = nativeSurface;
+#else
+  wgpu::SurfaceSourceMetalLayer source;
+  source.layer = nativeSurface;
+#endif
+  wgpu::SurfaceDescriptor descriptor;
+  descriptor.nextInChain = &source;
+  return instance().CreateSurface(&descriptor);
+}
+
+} // namespace rnwgpu

package/cpp/rnwgpu/WebGPURuntime.h

@@ -0,0 +1,36 @@
+#pragma once
+
+#include <mutex>
+
+#include "webgpu/webgpu_cpp.h"
+
+namespace rnwgpu {
+
+// Process-lifetime GPU state shared by every React instance, JS runtime and
+// thread. It holds nothing tied to one React instance (no jsi::Runtime,
+// CallInvoker or BlobModule): those stay with the per-instance module.
+// Intentionally never destroyed, so there is no static-destruction ordering to
+// get wrong and it outlives a React reload.
+class WebGPURuntime {
+public:
+  static WebGPURuntime &shared();
+
+  // The process-wide instance: Skia Graphite's when that is loaded, otherwise
+  // our own. Created on first use. Safe to call from any thread.
+  wgpu::Instance instance();
+
+  // Creates a surface on the shared instance for a CAMetalLayer (Apple) or an
+  // ANativeWindow (Android). Safe to call from any thread.
+  wgpu::Surface makeSurface(void *nativeSurface);
+
+  WebGPURuntime(const WebGPURuntime &) = delete;
+  WebGPURuntime &operator=(const WebGPURuntime &) = delete;
+
+private:
+  WebGPURuntime() = default;
+
+  std::once_flag _instanceOnce;
+  wgpu::Instance _instance;
+};
+
+} // namespace rnwgpu

package/cpp/rnwgpu/api/Convertors.h

@@ -10,6 +10,7 @@
 
 #include "webgpu/webgpu_cpp.h"
 
+#include "EnforceRange.h"
 #include "GPUBindGroupDescriptor.h"
 #include "GPUBindGroupEntry.h"
 #include "GPUBindGroupLayoutDescriptor.h"
@@ -161,11 +162,19 @@ public:
     return true;
   }
 
+  // JS numbers destined for an integer field are WebIDL [EnforceRange]
+  // integers in WebGPU, so an out-of-range value is a TypeError rather than a
+  // silent wrap (and an undefined cast). Flags are enums here and keep the
+  // plain cast, as GPUFlagsConstant is not [EnforceRange].
   template <typename T>
   [[nodiscard]] typename std::enable_if<
       (std::is_arithmetic<T>::value || std::is_enum<T>::value), bool>::type
   Convert(T &out, const double &in) {
-    out = static_cast<T>(in);
+    if constexpr (std::is_integral_v<T> && !std::is_same_v<T, bool>) {
+      out = enforceRange<T>(in);
+    } else {
+      out = static_cast<T>(in);
+    }
     return true;
   }
 

package/cpp/rnwgpu/api/DestroyedError.h

@@ -0,0 +1,26 @@
+#pragma once
+
+#include <string>
+
+#include "webgpu/webgpu_cpp.h"
+
+namespace rnwgpu {
+
+// 'GPUSharedFence "label"', or just the class name when unlabeled.
+inline std::string describeDestroyed(const char *className,
+                                     const std::string &label) {
+  return label.empty() ? std::string(className)
+                       : std::string(className) + " \"" + label + "\"";
+}
+
+// Reports a use of a destroyed object the way Dawn reports an invalid one: a
+// validation error, caught by error scopes or else delivered to the device's
+// uncapturederror event.
+inline void reportDestroyedUse(wgpu::Device &device, const char *className,
+                               const std::string &label, const char *method) {
+  auto message = "Destroyed " + describeDestroyed(className, label) +
+                 " used in " + method + "().";
+  device.InjectError(wgpu::ErrorType::Validation, message.c_str());
+}
+
+} // namespace rnwgpu

package/cpp/rnwgpu/api/GPU.cpp

@@ -1,7 +1,5 @@
 #include "GPU.h"
 
-#include <dlfcn.h>
-
 #include <cstdio>
 #include <memory>
 #include <string>
@@ -11,65 +9,13 @@
 
 #include "Convertors.h"
 #include "JSIConverter.h"
+#include "WebGPURuntime.h"
 #include "rnwgpu/async/RuntimeContext.h"
 
 namespace rnwgpu {
 
-GPU::GPU(jsi::Runtime & /*runtime*/) : NativeObject(CLASS_NAME) {
-  // If a Graphite build of react-native-skia is loaded in this
-  // process, adopt its wgpu::Instance instead of creating our own, so
-  // Graphite's device and every JS-created device live on one instance. That
-  // makes pointer-based handoff (RNWebGPU.importDevice of Skia's device)
-  // sound: the async pump serves the shared instance, so callbacks on
-  // imported devices settle. Discovered at runtime via dlsym so there is no
-  // build-time coupling and native-module init order does not matter. Both
-  // packages must link the same single Dawn copy (they vendor the same
-  // artifact) for the handle to be meaningful.
-  using GetInstanceFn = WGPUInstance (*)();
-  if (auto getSkiaInstance = reinterpret_cast<GetInstanceFn>(
-          dlsym(RTLD_DEFAULT, "rnskia_getWGPUInstance"))) {
-    if (WGPUInstance external = getSkiaInstance()) {
-      wgpuInstanceAddRef(external);
-      _instance = wgpu::Instance::Acquire(external);
-      return;
-    }
-  }
-
-  static const auto kTimedWaitAny = wgpu::InstanceFeatureName::TimedWaitAny;
-  wgpu::InstanceDescriptor instanceDesc{.requiredFeatureCount = 1,
-                                        .requiredFeatures = &kTimedWaitAny};
-
-  wgpu::InstanceLimits limits{.timedWaitAnyMaxCount = 64};
-  instanceDesc.requiredLimits = &limits;
-
-  // Expose Dawn's experimental adapter features. Several features needed by
-  // our Android external-texture path (YCbCrVulkanSamplers,
-  // OpaqueYCbCrAndroidForExternalTexture) are tagged Experimental in Dawn's
-  // feature table and are otherwise filtered out of adapter.features by
-  // PhysicalDeviceBase::GetSupportedFeatures. The allow_unsafe_apis toggle
-  // disables that filter so the features become visible;
-  // expose_wgsl_experimental_features is the parallel toggle for WGSL language
-  // features.
-  //
-  // Trade-off: these are instance-level Dawn toggles, so they apply to every
-  // adapter/device created from this instance, not just the external-texture
-  // path. There is no finer-grained, per-feature mechanism to surface these.
-  // The exposure is acceptable because the toggle only *un-hides* experimental
-  // features in adapter.features; it does not enable any of them. Nothing
-  // experimental becomes active unless application code explicitly lists that
-  // feature in requiredFeatures at device creation, so the default behavior of
-  // a device that asks for no experimental features is unchanged.
-  static const char *const kEnabledToggles[] = {
-      "allow_unsafe_apis",
-      "expose_wgsl_experimental_features",
-  };
-  wgpu::DawnTogglesDescriptor toggles;
-  toggles.enabledToggleCount = std::size(kEnabledToggles);
-  toggles.enabledToggles = kEnabledToggles;
-  instanceDesc.nextInChain = &toggles;
-
-  _instance = wgpu::CreateInstance(&instanceDesc);
-}
+GPU::GPU(jsi::Runtime & /*runtime*/)
+    : NativeObject(CLASS_NAME), _instance(WebGPURuntime::shared().instance()) {}
 
 async::AsyncTaskHandle GPU::requestAdapter(
     jsi::Runtime &runtime,

package/cpp/rnwgpu/api/GPUDevice.cpp

@@ -345,14 +345,21 @@ std::shared_ptr<GPUSharedTextureMemory> GPUDevice::importSharedTextureMemory(
 #endif
 
   auto memory = _instance.ImportSharedTextureMemory(&desc);
-  if (memory == nullptr) {
-    throw std::runtime_error("GPUDevice::importSharedTextureMemory(): "
-                             "ImportSharedTextureMemory returned null - is the "
-                             "'shared-texture-memory-iosurface' (Apple) or "
-                             "'shared-texture-memory-ahardware-buffer' "
-                             "(Android) feature enabled on the device?");
-  }
-  return std::make_shared<GPUSharedTextureMemory>(std::move(memory),
+  // Dawn reports a failed import (feature missing, unusable handle) as a
+  // validation error and returns an error object rather than null, with no
+  // format in its properties: the format getter of any texture created from
+  // it would throw. Fail the import instead.
+  wgpu::SharedTextureMemoryProperties properties{};
+  if (memory == nullptr ||
+      memory.GetProperties(&properties) != wgpu::Status::Success ||
+      properties.format == wgpu::TextureFormat::Undefined) {
+    throw std::runtime_error(
+        "GPUDevice::importSharedTextureMemory(): the import failed - is the "
+        "'shared-texture-memory-iosurface' (Apple) or "
+        "'shared-texture-memory-ahardware-buffer' (Android) feature enabled "
+        "on the device, and the handle a usable IOSurface / AHardwareBuffer?");
+  }
+  return std::make_shared<GPUSharedTextureMemory>(_instance, std::move(memory),
                                                   std::move(label));
 }
 
@@ -402,7 +409,8 @@ std::shared_ptr<GPUSharedFence> GPUDevice::importSharedFence(
         "GPUDevice::importSharedFence(): ImportSharedFence returned null - is "
         "the matching 'shared-fence-*' feature enabled on the device?");
   }
-  return std::make_shared<GPUSharedFence>(std::move(fence), std::move(label));
+  return std::make_shared<GPUSharedFence>(_instance, std::move(fence),
+                                          std::move(label));
 }
 
 async::AsyncTaskHandle GPUDevice::createComputePipelineAsync(

package/cpp/rnwgpu/api/GPUError.h

@@ -24,6 +24,21 @@ public:
     installGetter(runtime, prototype, "message", &GPUError::getMessage);
   }
 
+  // GPUValidationError, GPUOutOfMemoryError and GPUInternalError extend
+  // GPUError in the spec: chain their prototype to GPUError.prototype so
+  // `error instanceof GPUError` holds.
+  static void inheritPrototype(jsi::Runtime &runtime, jsi::Object &prototype) {
+    installPrototype(runtime);
+    auto *parent = getCachedPrototype(runtime);
+    if (parent == nullptr) {
+      return;
+    }
+    auto objectCtor = runtime.global().getPropertyAsObject(runtime, "Object");
+    auto setPrototypeOf =
+        objectCtor.getPropertyAsFunction(runtime, "setPrototypeOf");
+    setPrototypeOf.call(runtime, prototype, *parent);
+  }
+
 protected:
   // Protected constructor for subclasses
   GPUError(const char *className, std::string message)

package/cpp/rnwgpu/api/GPUInternalError.h

@@ -2,6 +2,7 @@
 
 #include <string>
 
+#include "GPUError.h"
 #include "NativeObject.h"
 
 namespace rnwgpu {
@@ -20,6 +21,7 @@ public:
   std::string getMessage() { return _message; }
 
   static void definePrototype(jsi::Runtime &runtime, jsi::Object &prototype) {
+    GPUError::inheritPrototype(runtime, prototype);
     installGetter(runtime, prototype, "__brand", &GPUInternalError::getBrand);
     installGetter(runtime, prototype, "message", &GPUInternalError::getMessage);
   }

package/cpp/rnwgpu/api/GPUOutOfMemoryError.h

@@ -2,6 +2,7 @@
 
 #include <string>
 
+#include "GPUError.h"
 #include "NativeObject.h"
 
 namespace rnwgpu {
@@ -20,6 +21,7 @@ public:
   std::string getMessage() { return _message; }
 
   static void definePrototype(jsi::Runtime &runtime, jsi::Object &prototype) {
+    GPUError::inheritPrototype(runtime, prototype);
     installGetter(runtime, prototype, "__brand",
                   &GPUOutOfMemoryError::getBrand);
     installGetter(runtime, prototype, "message",

package/cpp/rnwgpu/api/GPUQueue.cpp

@@ -9,6 +9,7 @@
 #include <vector>
 
 #include "Convertors.h"
+#include "EnforceRange.h"
 #include "ImageBitmap.h"
 #include "PlatformContext.h"
 
@@ -126,15 +127,9 @@ void GPUQueue::copyVideoFrameToTexture(
     throw std::runtime_error(
         "copyExternalImageToTexture: a native frame is a single 2D image");
   }
-  constexpr double kMaxCoordinate =
-      static_cast<double>(std::numeric_limits<uint32_t>::max());
-  auto coordinate = [&](double value, const char *name) {
-    if (!(value >= 0) || value > kMaxCoordinate) {
-      throw std::runtime_error(std::string("copyExternalImageToTexture: ") +
-                               name +
-                               " must be a non-negative integer coordinate");
-    }
-    return static_cast<uint32_t>(value);
+  // GPUOrigin2D coordinates are [EnforceRange] unsigned long.
+  auto coordinate = [](double value, const char * /*name*/) {
+    return enforceRange<uint32_t>(value);
   };
   const double rotation = source.rotation.value_or(0);
   if (rotation != 0 && rotation != 90 && rotation != 180 && rotation != 270) {
@@ -208,18 +203,9 @@ void GPUQueue::copyExternalImageToTexture(
   }
 
   const auto origin = source->origin.value_or(nullptr);
-  // GPUOrigin2D coordinates are [EnforceRange] unsigned long: negative,
-  // NaN, or out-of-range doubles must be rejected here because casting
-  // them to an unsigned integer is undefined behavior.
-  constexpr double kMaxOrigin =
-      static_cast<double>(std::numeric_limits<uint32_t>::max());
-  if (origin && (!(origin->x >= 0) || !(origin->y >= 0) ||
-                 origin->x > kMaxOrigin || origin->y > kMaxOrigin)) {
-    throw std::runtime_error(
-        "The source origin must be a non-negative integer coordinate.");
-  }
-  const size_t sourceOriginX = origin ? static_cast<size_t>(origin->x) : 0;
-  const size_t sourceOriginY = origin ? static_cast<size_t>(origin->y) : 0;
+  // GPUOrigin2D coordinates are [EnforceRange] unsigned long.
+  const size_t sourceOriginX = origin ? enforceRange<uint32_t>(origin->x) : 0;
+  const size_t sourceOriginY = origin ? enforceRange<uint32_t>(origin->y) : 0;
   if (sourceOriginX > source->source->getWidth() ||
       sz.width > source->source->getWidth() - sourceOriginX ||
       sourceOriginY > source->source->getHeight() ||

package/cpp/rnwgpu/api/GPUSharedFence.cpp

@@ -3,6 +3,8 @@
 #include <cstdint>
 #include <string>
 
+#include "DestroyedError.h"
+
 #if defined(__ANDROID__)
 #include <fcntl.h>
 #endif
@@ -32,10 +34,30 @@ std::string sharedFenceTypeToString(wgpu::SharedFenceType type) {
   }
 }
 
+// Dawn reports a fence it can't export (an invalid one) as a validation error
+// and leaves the type at 0. Fail the call too, like a destroyed fence does,
+// rather than returning a record with no type and no handle.
+void throwIfNotExported(jsi::Runtime &runtime,
+                        const wgpu::SharedFenceExportInfo &info) {
+  if (info.type == wgpu::SharedFenceType(0)) {
+    throw jsi::JSError(runtime, "GPUSharedFence::export() failed");
+  }
+}
+
 } // namespace
 
+void GPUSharedFence::injectDestroyedError(const char *method) {
+  reportDestroyedUse(_device, CLASS_NAME, _label, method);
+}
+
 jsi::Value GPUSharedFence::exportInfo(jsi::Runtime &runtime, const jsi::Value &,
                                       const jsi::Value *, size_t) {
+  // Fails like an export Dawn rejects: a validation error, then the throw.
+  if (!_instance) {
+    injectDestroyedError("export");
+    throw jsi::JSError(runtime,
+                       "GPUSharedFence::export(): the fence was destroyed");
+  }
   wgpu::SharedFenceExportInfo info{};
   uint64_t handle = 0;
 
@@ -44,25 +66,30 @@ jsi::Value GPUSharedFence::exportInfo(jsi::Runtime &runtime, const jsi::Value &,
   wgpu::SharedFenceMTLSharedEventExportInfo mtlInfo{};
   info.nextInChain = &mtlInfo;
   _instance.ExportInfo(&info);
+  throwIfNotExported(runtime, info);
   handle = reinterpret_cast<uint64_t>(mtlInfo.sharedEvent);
 #elif defined(__ANDROID__)
-  // Android: the handle is an OS file descriptor (sync_fd). Dawn's ExportInfo returns a BORROWED fd — it is
-  // owned by the SharedFence and closed when the fence is destroyed. This exported handle is documented as
-  // caller-owned (the caller must close() it), so dup() it. Without the dup the same fd is closed twice —
-  // once by the caller and once by Dawn on fence destruction — tripping Android's fdsan (double-close abort).
+  // Android: the handle is an OS file descriptor (sync_fd). Dawn's ExportInfo
+  // returns a BORROWED fd — it is owned by the SharedFence and closed when the
+  // fence is destroyed. This exported handle is documented as caller-owned (the
+  // caller must close() it), so dup() it. Without the dup the same fd is closed
+  // twice — once by the caller and once by Dawn on fence destruction — tripping
+  // Android's fdsan (double-close abort).
   wgpu::SharedFenceSyncFDExportInfo fdInfo{};
   info.nextInChain = &fdInfo;
   _instance.ExportInfo(&info);
-  int exportedFd =
-      fdInfo.handle >= 0 ? ::fcntl(fdInfo.handle, F_DUPFD_CLOEXEC, 0) : fdInfo.handle;
+  throwIfNotExported(runtime, info);
+  int exportedFd = fdInfo.handle >= 0
+                       ? ::fcntl(fdInfo.handle, F_DUPFD_CLOEXEC, 0)
+                       : fdInfo.handle;
   handle = static_cast<uint64_t>(static_cast<uint32_t>(exportedFd));
 #else
-// react-native-webgpu only targets Apple (Metal) and Android (Vulkan). On any
-// other platform there is no native handle convention to expose, so fail loudly
-// rather than handing back a meaningless handle of 0.
-throw jsi::JSError(runtime,
-                    "GPUSharedFence::export(): unsupported platform (only "
-                    "Apple/Metal and Android/Vulkan are supported)");
+  // react-native-webgpu only targets Apple (Metal) and Android (Vulkan). On any
+  // other platform there is no native handle convention to expose, so fail
+  // loudly rather than handing back a meaningless handle of 0.
+  throw jsi::JSError(runtime,
+                     "GPUSharedFence::export(): unsupported platform (only "
+                     "Apple/Metal and Android/Vulkan are supported)");
 #endif
 
   jsi::Object result(runtime);

package/cpp/rnwgpu/api/GPUSharedFence.h

@@ -17,9 +17,10 @@ class GPUSharedFence : public NativeObject<GPUSharedFence> {
 public:
   static constexpr const char *CLASS_NAME = "GPUSharedFence";
 
-  explicit GPUSharedFence(wgpu::SharedFence instance, std::string label)
-      : NativeObject(CLASS_NAME), _instance(std::move(instance)),
-        _label(std::move(label)) {}
+  explicit GPUSharedFence(wgpu::Device device, wgpu::SharedFence instance,
+                          std::string label)
+      : NativeObject(CLASS_NAME), _device(std::move(device)),
+        _instance(std::move(instance)), _label(std::move(label)) {}
 
 public:
   std::string getBrand() { return CLASS_NAME; }
@@ -33,19 +34,35 @@ public:
   std::string getLabel() { return _label; }
   void setLabel(const std::string &label) {
     _label = label;
-    _instance.SetLabel(_label.c_str());
+    if (_instance) {
+      _instance.SetLabel(_label.c_str());
+    }
   }
 
+  // Releases the fence now (closing its sync fd on Android) rather than when
+  // the JS object is garbage collected, which a runtime making fences every
+  // frame may not do for a while. Dawn keeps its own reference as long as it
+  // needs the fence (a beginAccess wait). A later use is a validation error
+  // and a throw.
+  void destroy() { _instance = nullptr; }
+
   static void definePrototype(jsi::Runtime &runtime, jsi::Object &prototype) {
     installGetter(runtime, prototype, "__brand", &GPUSharedFence::getBrand);
     installMethod(runtime, prototype, "export", &GPUSharedFence::exportInfo);
+    installMethod(runtime, prototype, "destroy", &GPUSharedFence::destroy);
     installGetterSetter(runtime, prototype, "label", &GPUSharedFence::getLabel,
                         &GPUSharedFence::setLabel);
   }
 
   inline wgpu::SharedFence get() { return _instance; }
 
+  // Reports a use of the destroyed fence the way Dawn reports an invalid
+  // object: a validation error, caught by error scopes or else delivered to
+  // the device's uncapturederror event.
+  void injectDestroyedError(const char *method);
+
 private:
+  wgpu::Device _device;
   wgpu::SharedFence _instance;
   std::string _label;
 };