react-native-wgpu 0.5.10 → 0.5.13

package/cpp/rnwgpu/api/GPUExternalTexture.h

@@ -1,10 +1,13 @@
 #pragma once
 
+#include <memory>
 #include <string>
+#include <utility>
 
 #include "Unions.h"
 
 #include "NativeObject.h"
+#include "VideoFrame.h"
 
 #include "webgpu/webgpu_cpp.h"
 
@@ -12,16 +15,54 @@ namespace rnwgpu {
 
 namespace jsi = facebook::jsi;
 
+struct GPUExternalTextureDescriptor;
+
 class GPUExternalTexture : public NativeObject<GPUExternalTexture> {
 public:
   static constexpr const char *CLASS_NAME = "GPUExternalTexture";
 
-  explicit GPUExternalTexture(wgpu::ExternalTexture instance, std::string label)
-      : NativeObject(CLASS_NAME), _instance(instance), _label(label) {}
+  // Import a VideoFrame (via descriptor.source) as a GPUExternalTexture on
+  // `device`: imports the native surface as SharedTextureMemory, begins access,
+  // and wraps the resulting wgpu::ExternalTexture together with the resources
+  // whose lifetime it owns. The matching EndAccess runs in destroy() / the
+  // destructor. Defined in GPUExternalTexture.cpp.
+  static std::shared_ptr<GPUExternalTexture>
+  Create(wgpu::Device device,
+         std::shared_ptr<GPUExternalTextureDescriptor> descriptor);
+
+  // Construct from an already-built wgpu::ExternalTexture plus the underlying
+  // shared-memory resources we need to keep alive. The wrapper takes ownership
+  // of the SharedTextureMemory + Texture and calls EndAccess on destruction so
+  // the producer (e.g. AVPlayer) can reclaim the IOSurface.
+  GPUExternalTexture(wgpu::ExternalTexture instance,
+                     wgpu::SharedTextureMemory memory, wgpu::Texture texture,
+                     std::shared_ptr<VideoFrame> source, std::string label)
+      : NativeObject(CLASS_NAME), _instance(std::move(instance)),
+        _memory(std::move(memory)), _texture(std::move(texture)),
+        _source(std::move(source)), _label(std::move(label)) {}
+
+  ~GPUExternalTexture() override { destroy(); }
 
 public:
   std::string getBrand() { return CLASS_NAME; }
 
+  // End the shared-memory access window and release the underlying resources.
+  // Idempotent: safe to call more than once, and the destructor calls it as a
+  // garbage-collection fallback. Call it right after the queue.submit() that
+  // sampled this texture (never before): a GPUExternalTexture's access window
+  // is owned by this wrapper's lifetime, not by submit, so without an explicit
+  // destroy() the producer's surface (e.g. an AVPlayer IOSurface) stays claimed
+  // until GC runs. EndAccess is the designed post-submit call: Dawn keeps the
+  // texture alive for in-flight GPU work via the fences it returns.
+  void destroy() {
+    if (_memory && _texture) {
+      wgpu::SharedTextureMemoryEndAccessState state{};
+      (void)_memory.EndAccess(_texture, &state);
+    }
+    _texture = nullptr;
+    _memory = nullptr;
+  }
+
   std::string getLabel() { return _label; }
   void setLabel(const std::string &label) {
     _label = label;
@@ -33,12 +74,16 @@ public:
     installGetterSetter(runtime, prototype, "label",
                         &GPUExternalTexture::getLabel,
                         &GPUExternalTexture::setLabel);
+    installMethod(runtime, prototype, "destroy", &GPUExternalTexture::destroy);
   }
 
   inline const wgpu::ExternalTexture get() { return _instance; }
 
 private:
   wgpu::ExternalTexture _instance;
+  wgpu::SharedTextureMemory _memory;
+  wgpu::Texture _texture;
+  std::shared_ptr<VideoFrame> _source;
   std::string _label;
 };
 

package/cpp/rnwgpu/api/GPUFeatures.h

@@ -2,9 +2,9 @@
 
 #include <string>
 
-#include "webgpu/webgpu_cpp.h"
+#include <cstdio>
 
-#include "WGPULogger.h"
+#include "webgpu/webgpu_cpp.h"
 
 namespace rnwgpu {
 
@@ -89,9 +89,6 @@ static void convertEnumToJSUnion(wgpu::FeatureName inEnum,
   case wgpu::FeatureName::Unorm16TextureFormats:
     *outUnion = "unorm16-texture-formats";
     break;
-  case wgpu::FeatureName::Snorm16TextureFormats:
-    *outUnion = "snorm16-texture-formats";
-    break;
   case wgpu::FeatureName::MultiPlanarFormatExtendedUsages:
     *outUnion = "multi-planar-format-extended-usages";
     break;
@@ -122,18 +119,12 @@ static void convertEnumToJSUnion(wgpu::FeatureName inEnum,
   case wgpu::FeatureName::AdapterPropertiesVk:
     *outUnion = "adapter-properties-vk";
     break;
-  case wgpu::FeatureName::R8UnormStorage:
-    *outUnion = "r8unorm-storage";
-    break;
   case wgpu::FeatureName::DawnFormatCapabilities:
     *outUnion = "format-capabilities";
     break;
   case wgpu::FeatureName::DawnDrmFormatCapabilities:
     *outUnion = "drm-format-capabilities";
     break;
-  case wgpu::FeatureName::Norm16TextureFormats:
-    *outUnion = "norm16-texture-formats";
-    break;
   case wgpu::FeatureName::MultiPlanarFormatNv16:
     *outUnion = "multi-planar-format-nv16";
     break;
@@ -177,7 +168,7 @@ static void convertEnumToJSUnion(wgpu::FeatureName inEnum,
     *outUnion = "shared-fence-vk-semaphore-opaque-fd";
     break;
   case wgpu::FeatureName::SharedFenceSyncFD:
-    *outUnion = "shared-fence-vk-semaphore-sync-fd";
+    *outUnion = "shared-fence-sync-fd";
     break;
   case wgpu::FeatureName::SharedFenceVkSemaphoreZirconHandle:
     *outUnion = "shared-fence-vk-semaphore-zircon-handle";
@@ -197,6 +188,9 @@ static void convertEnumToJSUnion(wgpu::FeatureName inEnum,
   case wgpu::FeatureName::YCbCrVulkanSamplers:
     *outUnion = "ycbcr-vulkan-samplers";
     break;
+  case wgpu::FeatureName::OpaqueYCbCrAndroidForExternalTexture:
+    *outUnion = "opaque-ycbcr-android-for-external-texture";
+    break;
   case wgpu::FeatureName::ShaderModuleCompilationOptions:
     *outUnion = "shader-module-compilation-options";
     break;
@@ -204,7 +198,7 @@ static void convertEnumToJSUnion(wgpu::FeatureName inEnum,
     *outUnion = "dawn-load-resolve-texture";
     break;
   default:
-    Logger::logToConsole("Unknown feature name %d", inEnum);
+    fprintf(stderr, "Unknown feature name %d\n", static_cast<int>(inEnum));
     *outUnion = "";
   }
 }

package/cpp/rnwgpu/api/GPUShaderModule.cpp

@@ -18,7 +18,7 @@ async::AsyncTaskHandle GPUShaderModule::getCompilationInfo() {
             wgpu::CallbackMode::AllowProcessEvents,
             [result, resolve,
              reject](wgpu::CompilationInfoRequestStatus status,
-                     const wgpu::CompilationInfo *compilationInfo) mutable {
+                     const wgpu::CompilationInfo *compilationInfo) {
               if (status != wgpu::CompilationInfoRequestStatus::Success ||
                   compilationInfo == nullptr) {
                 reject("Failed to get compilation info");
@@ -39,8 +39,7 @@ async::AsyncTaskHandle GPUShaderModule::getCompilationInfo() {
                 result->_messages.push_back(std::move(message));
               }
 
-              resolve([result =
-                           std::move(result)](jsi::Runtime &runtime) mutable {
+              resolve([result](jsi::Runtime &runtime) mutable {
                 return JSIConverter<std::shared_ptr<GPUCompilationInfo>>::toJSI(
                     runtime, result);
               });

package/cpp/rnwgpu/api/GPUSharedTextureMemory.cpp

@@ -0,0 +1,80 @@
+#include "GPUSharedTextureMemory.h"
+
+#include <memory>
+#include <stdexcept>
+#include <string>
+
+#include "Convertors.h"
+
+namespace rnwgpu {
+
+std::shared_ptr<GPUTexture> GPUSharedTextureMemory::createTexture(
+    std::optional<std::shared_ptr<GPUTextureDescriptor>> descriptor) {
+  if (!descriptor.has_value() || descriptor.value() == nullptr) {
+    auto texture = _instance.CreateTexture();
+    return std::make_shared<GPUTexture>(texture, "");
+  }
+
+  wgpu::TextureDescriptor desc{};
+  Convertor conv;
+  if (!conv(desc, descriptor.value())) {
+    throw std::runtime_error(
+        "GPUSharedTextureMemory::createTexture(): Error with "
+        "GPUTextureDescriptor");
+  }
+  auto texture = _instance.CreateTexture(&desc);
+  return std::make_shared<GPUTexture>(texture,
+                                      descriptor.value()->label.value_or(""));
+}
+
+bool GPUSharedTextureMemory::beginAccess(std::shared_ptr<GPUTexture> texture,
+                                         bool initialized) {
+  if (!texture) {
+    throw std::runtime_error(
+        "GPUSharedTextureMemory::beginAccess(): texture is null");
+  }
+  wgpu::SharedTextureMemoryBeginAccessDescriptor desc{};
+  desc.initialized = initialized;
+  desc.concurrentRead = false;
+  desc.fenceCount = 0;
+  desc.fences = nullptr;
+  desc.signaledValues = nullptr;
+
+#if defined(__ANDROID__)
+  // Dawn's Vulkan backend (AHardwareBuffer) validates that the begin-access
+  // descriptor chains a SharedTextureMemoryVkImageLayoutBeginState specifying
+  // the VkImageLayout to acquire the image into. UNDEFINED (= 0) on both ends
+  // is the canonical "no prior GPU producer" pattern: Dawn performs an
+  // external-queue acquire from VK_QUEUE_FAMILY_EXTERNAL which preserves the
+  // AHB contents, then transitions to whatever layout the texture's actual
+  // usage requires.
+  wgpu::SharedTextureMemoryVkImageLayoutBeginState vkLayout{};
+  vkLayout.oldLayout = 0;
+  vkLayout.newLayout = 0;
+  desc.nextInChain = &vkLayout;
+#endif
+
+  auto status = _instance.BeginAccess(texture->get(), &desc);
+  return static_cast<bool>(status);
+}
+
+bool GPUSharedTextureMemory::endAccess(std::shared_ptr<GPUTexture> texture) {
+  if (!texture) {
+    throw std::runtime_error(
+        "GPUSharedTextureMemory::endAccess(): texture is null");
+  }
+  wgpu::SharedTextureMemoryEndAccessState state{};
+
+#if defined(__ANDROID__)
+  // Dawn's Vulkan backend writes the released old/new VkImageLayouts back into
+  // a chained SharedTextureMemoryVkImageLayoutEndState; validation requires
+  // the chain even when the caller doesn't read the values.
+  wgpu::SharedTextureMemoryVkImageLayoutEndState vkLayout{};
+  state.nextInChain = &vkLayout;
+#endif
+
+  auto status = _instance.EndAccess(texture->get(), &state);
+  return static_cast<bool>(status);
+}
+
+} // namespace rnwgpu

package/cpp/rnwgpu/api/GPUSharedTextureMemory.h

@@ -0,0 +1,71 @@
+#pragma once
+
+#include <memory>
+#include <optional>
+#include <string>
+
+#include "NativeObject.h"
+
+#include "webgpu/webgpu_cpp.h"
+
+#include "GPUTexture.h"
+#include "GPUTextureDescriptor.h"
+
+namespace rnwgpu {
+
+namespace jsi = facebook::jsi;
+
+class GPUSharedTextureMemory : public NativeObject<GPUSharedTextureMemory> {
+public:
+  static constexpr const char *CLASS_NAME = "GPUSharedTextureMemory";
+
+  explicit GPUSharedTextureMemory(wgpu::SharedTextureMemory instance,
+                                  std::string label)
+      : NativeObject(CLASS_NAME), _instance(std::move(instance)),
+        _label(std::move(label)) {}
+
+public:
+  std::string getBrand() { return CLASS_NAME; }
+
+  std::shared_ptr<GPUTexture>
+  createTexture(std::optional<std::shared_ptr<GPUTextureDescriptor>> descriptor);
+
+  // Returns true on success. Marks the shared memory as initialized so the
+  // texture's content is preserved (or not). Callers that want fence-based
+  // synchronization should pass fences via beginAccess descriptor (not yet
+  // exposed - we currently take the implicit/no-fence path that matches the
+  // most common RN use cases: still images, single-producer video frames).
+  bool beginAccess(std::shared_ptr<GPUTexture> texture, bool initialized);
+
+  // Returns true on success. Drops any fences produced by end-access (we do
+  // not yet surface them to JS).
+  bool endAccess(std::shared_ptr<GPUTexture> texture);
+
+  std::string getLabel() { return _label; }
+  void setLabel(const std::string &label) {
+    _label = label;
+    _instance.SetLabel(_label.c_str());
+  }
+
+  static void definePrototype(jsi::Runtime &runtime, jsi::Object &prototype) {
+    installGetter(runtime, prototype, "__brand",
+                  &GPUSharedTextureMemory::getBrand);
+    installMethod(runtime, prototype, "createTexture",
+                  &GPUSharedTextureMemory::createTexture);
+    installMethod(runtime, prototype, "beginAccess",
+                  &GPUSharedTextureMemory::beginAccess);
+    installMethod(runtime, prototype, "endAccess",
+                  &GPUSharedTextureMemory::endAccess);
+    installGetterSetter(runtime, prototype, "label",
+                        &GPUSharedTextureMemory::getLabel,
+                        &GPUSharedTextureMemory::setLabel);
+  }
+
+  inline const wgpu::SharedTextureMemory get() { return _instance; }
+
+private:
+  wgpu::SharedTextureMemory _instance;
+  std::string _label;
+};
+
+} // namespace rnwgpu

package/cpp/rnwgpu/api/ImageBitmap.h

@@ -26,9 +26,17 @@ public:
 
   size_t getSize() { return _imageData.data.size(); }
 
+  void close() {
+    _imageData.data.clear();
+    _imageData.data.shrink_to_fit();
+    _imageData.width = 0;
+    _imageData.height = 0;
+  }
+
   static void definePrototype(jsi::Runtime &runtime, jsi::Object &prototype) {
     installGetter(runtime, prototype, "width", &ImageBitmap::getWidth);
     installGetter(runtime, prototype, "height", &ImageBitmap::getHeight);
+    installMethod(runtime, prototype, "close", &ImageBitmap::close);
   }
 
   size_t getMemoryPressure() override { return getSize(); }

package/cpp/rnwgpu/api/RNWebGPU.h

@@ -5,11 +5,14 @@
 
 #include "NativeObject.h"
 
+#include "ArrayBuffer.h"
 #include "Canvas.h"
 #include "GPU.h"
 #include "GPUCanvasContext.h"
 #include "ImageBitmap.h"
 #include "PlatformContext.h"
+#include "VideoFrame.h"
+#include "VideoPlayer.h"
 
 #include <ReactCommon/CallInvoker.h>
 
@@ -88,47 +91,41 @@ public:
     auto callInvoker = _callInvoker;
 
     // Check if the argument is an ArrayBuffer or ArrayBufferView
-    // (TypedArray / DataView)
+    // (TypedArray / DataView). Only a real buffer source is run through the
+    // ArrayBuffer converter, which validates byteOffset/byteLength against the
+    // backing buffer and throws on an out-of-bounds (or spoofed) view. Anything
+    // else (e.g. a Blob) is left to the fall-through path below, so its errors
+    // are not misreported as bounds errors here.
     if (args[0].isObject()) {
       auto obj = args[0].getObject(runtime);
 
-      std::span<const uint8_t> data;
-
-      if (obj.isArrayBuffer(runtime)) {
-        // Plain ArrayBuffer — use the full buffer
-        const auto &ab = obj.getArrayBuffer(runtime);
-        data = {ab.data(runtime), ab.size(runtime)};
-      } else if (obj.hasProperty(runtime, "buffer")) {
-        // TypedArray or DataView — respect byteOffset/byteLength
-        auto bufferVal = obj.getProperty(runtime, "buffer");
-        if (bufferVal.isObject() &&
-            bufferVal.getObject(runtime).isArrayBuffer(runtime)) {
-          const auto &ab =
-              bufferVal.getObject(runtime).getArrayBuffer(runtime);
-          auto byteOffset = static_cast<size_t>(
-              obj.getProperty(runtime, "byteOffset").asNumber());
-          auto byteLength = static_cast<size_t>(
-              obj.getProperty(runtime, "byteLength").asNumber());
-          data = {ab.data(runtime) + byteOffset, byteLength};
-        }
+      bool isBufferSource = obj.isArrayBuffer(runtime);
+      if (!isBufferSource && obj.hasProperty(runtime, "buffer")) {
+        auto bufferProp = obj.getProperty(runtime, "buffer");
+        isBufferSource = bufferProp.isObject() &&
+                         bufferProp.getObject(runtime).isArrayBuffer(runtime);
       }
 
-      if (!data.empty()) {
-        // Copy bytes on the JS thread — the ArrayBuffer pointer is into
+      if (isBufferSource) {
+        // Bounds violations propagate out of fromJSI so the call rejects
+        // rather than reading out of bounds below.
+        auto buffer = JSIConverter<std::shared_ptr<ArrayBuffer>>::fromJSI(
+            runtime, args[0], false);
+        std::span<const uint8_t> data{buffer->data(), buffer->size()};
+
+        // Copy bytes on the JS thread: the ArrayBuffer pointer is into
         // JS-owned memory that can be GC'd
         std::vector<uint8_t> dataCopy(data.begin(), data.end());
 
         return Promise::createPromise(
             runtime,
-            [platformContext, callInvoker,
-             dataCopy = std::move(dataCopy)](
+            [platformContext, callInvoker, dataCopy = std::move(dataCopy)](
                 jsi::Runtime & /*runtime*/,
                 std::shared_ptr<Promise> promise) mutable {
               platformContext->createImageBitmapFromDataAsync(
                   dataCopy,
                   [callInvoker, promise](ImageData imageData) {
-                    auto imageBitmap =
-                        std::make_shared<ImageBitmap>(imageData);
+                    auto imageBitmap = std::make_shared<ImageBitmap>(imageData);
                     callInvoker->invokeAsync([promise, imageBitmap]() {
                       promise->resolve(
                           JSIConverter<std::shared_ptr<ImageBitmap>>::toJSI(
@@ -158,12 +155,11 @@ public:
               blobId, offset, size,
               [callInvoker, promise](ImageData imageData) {
                 auto imageBitmap = std::make_shared<ImageBitmap>(imageData);
-                callInvoker->invokeAsync(
-                    [promise, imageBitmap]() {
-                      promise->resolve(
-                          JSIConverter<std::shared_ptr<ImageBitmap>>::toJSI(
-                              promise->runtime, imageBitmap));
-                    });
+                callInvoker->invokeAsync([promise, imageBitmap]() {
+                  promise->resolve(
+                      JSIConverter<std::shared_ptr<ImageBitmap>>::toJSI(
+                          promise->runtime, imageBitmap));
+                });
               },
               [callInvoker, promise](std::string error) {
                 callInvoker->invokeAsync(
@@ -172,6 +168,38 @@ public:
         });
   }
 
+  std::shared_ptr<VideoFrame> loadVideoFrame(std::string path) {
+    auto frame = _platformContext->loadVideoFrame(path);
+    return std::make_shared<VideoFrame>(std::move(frame));
+  }
+
+  std::shared_ptr<VideoFrame> createTestVideoFrame(double width, double height) {
+    auto frame = _platformContext->createTestVideoFrame(
+        static_cast<uint32_t>(width), static_cast<uint32_t>(height));
+    return std::make_shared<VideoFrame>(std::move(frame));
+  }
+
+  // Wrap a CVPixelBufferRef / AHardwareBuffer* pointer (typed as void* via
+  // BigInt on the JS side) into one of our VideoFrames. The native side
+  // CFRetains / acquires so the caller can release immediately.
+  std::shared_ptr<VideoFrame> createVideoFrameFromNativeBuffer(void *pointer) {
+    auto handle = _platformContext->wrapNativeBuffer(pointer);
+    return std::make_shared<VideoFrame>(std::move(handle));
+  }
+
+  std::shared_ptr<VideoPlayer>
+  createVideoPlayer(std::string path, std::optional<std::string> pixelFormat) {
+    auto format = (pixelFormat && pixelFormat.value() == "nv12")
+                      ? VideoPixelFormat::NV12
+                      : VideoPixelFormat::BGRA8;
+    auto impl = _platformContext->createVideoPlayer(path, format);
+    return std::make_shared<VideoPlayer>(std::move(impl));
+  }
+
+  std::string writeTestVideoFile() {
+    return _platformContext->writeTestVideoFile();
+  }
+
   std::shared_ptr<Canvas> getNativeSurface(int contextId) {
     auto &registry = rnwgpu::SurfaceRegistry::getInstance();
     auto info = registry.getSurfaceInfo(contextId);
@@ -192,6 +220,16 @@ public:
                   &RNWebGPU::getNativeSurface);
     installMethod(runtime, prototype, "MakeWebGPUCanvasContext",
                   &RNWebGPU::MakeWebGPUCanvasContext);
+    installMethod(runtime, prototype, "loadVideoFrame",
+                  &RNWebGPU::loadVideoFrame);
+    installMethod(runtime, prototype, "createTestVideoFrame",
+                  &RNWebGPU::createTestVideoFrame);
+    installMethod(runtime, prototype, "createVideoFrameFromNativeBuffer",
+                  &RNWebGPU::createVideoFrameFromNativeBuffer);
+    installMethod(runtime, prototype, "createVideoPlayer",
+                  &RNWebGPU::createVideoPlayer);
+    installMethod(runtime, prototype, "writeTestVideoFile",
+                  &RNWebGPU::writeTestVideoFile);
   }
 
 private:

package/cpp/rnwgpu/api/RnFeatures.h

@@ -0,0 +1,53 @@
+#pragma once
+
+#include <string>
+#include <unordered_set>
+#include <vector>
+
+#include "webgpu/webgpu_cpp.h"
+
+namespace rnwgpu {
+
+// Umbrella feature name owned by react-native-wgpu. Backed by a
+// platform-specific pair of Dawn features. The prefix is intentional: this
+// string is not part of the WebGPU spec, it is our API surface for the
+// "import a native surface as a sampleable texture" capability.
+inline constexpr const char *kRnNativeTextureFeature =
+    "rnwebgpu/native-texture";
+
+// Dawn features that back the umbrella on the current platform. Empty on
+// platforms where the capability is not available, in which case the umbrella
+// behaves as a no-op (it won't appear in adapter.features and asking for it
+// in requiredFeatures expands to nothing).
+inline std::vector<wgpu::FeatureName> rnNativeTextureBackingFeatures() {
+#if defined(__APPLE__)
+  return {wgpu::FeatureName::SharedTextureMemoryIOSurface,
+          wgpu::FeatureName::SharedFenceMTLSharedEvent};
+#elif defined(__ANDROID__)
+  return {wgpu::FeatureName::SharedTextureMemoryAHardwareBuffer,
+          wgpu::FeatureName::SharedFenceSyncFD};
+#else
+  return {};
+#endif
+}
+
+// If every Dawn feature backing the umbrella is in `enabled`, add the
+// umbrella name to `out`. Used by adapter.features / device.features so JS
+// callers can see (and call .has on) the same name they pass in.
+inline void
+maybeSynthesizeRnNativeTextureFeature(
+    const std::unordered_set<wgpu::FeatureName> &enabled,
+    std::unordered_set<std::string> &out) {
+  auto backing = rnNativeTextureBackingFeatures();
+  if (backing.empty()) {
+    return;
+  }
+  for (auto f : backing) {
+    if (enabled.find(f) == enabled.end()) {
+      return;
+    }
+  }
+  out.insert(kRnNativeTextureFeature);
+}
+
+} // namespace rnwgpu

package/cpp/rnwgpu/api/VideoFrame.h

@@ -0,0 +1,76 @@
+#pragma once
+
+#include <functional>
+#include <memory>
+#include <string>
+#include <utility>
+
+#include "JSIConverter.h"
+#include "NativeObject.h"
+#include "PlatformContext.h"
+
+namespace rnwgpu {
+
+namespace jsi = facebook::jsi;
+
+// VideoFrame is a small RAII wrapper around a platform-specific native handle
+// (IOSurfaceRef-backed CVPixelBuffer on Apple, AHardwareBuffer on Android).
+// It surfaces the raw handle as a BigInt to JS so callers can hand it to
+// GPUDevice.importSharedTextureMemory, and owns a deleter so the underlying
+// object stays alive until the JS object is GC'd (or release() is called).
+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 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 `VideoFrame` for brevity; only the brand is
+  // namespaced.
+  static constexpr const char *CLASS_NAME = "NativeVideoFrame";
+
+  explicit VideoFrame(VideoFrameHandle handle)
+      : NativeObject(CLASS_NAME), _handle(std::move(handle)) {}
+
+  ~VideoFrame() override { release(); }
+
+  std::string getBrand() { return CLASS_NAME; }
+
+  // The native handle (IOSurfaceRef / AHardwareBuffer*) as a uintptr_t value.
+  // Exposed as a BigInt on the JS side.
+  void *getHandle() { return _handle.handle; }
+  uint32_t getWidth() { return _handle.width; }
+  uint32_t getHeight() { return _handle.height; }
+
+  // Pixel format as a JS-visible string: "bgra8" | "nv12".
+  std::string getPixelFormat() {
+    return _handle.pixelFormat == VideoPixelFormat::NV12 ? "nv12" : "bgra8";
+  }
+
+  // Direct access to the underlying handle, for use by importExternalTexture /
+  // importSharedTextureMemory inside the C++ layer (not exposed to JS).
+  const VideoFrameHandle &handle() const { return _handle; }
+
+  void release() {
+    if (_handle.deleter) {
+      _handle.deleter();
+      _handle.deleter = nullptr;
+    }
+    _handle.handle = nullptr;
+  }
+
+  static void definePrototype(jsi::Runtime &runtime, jsi::Object &prototype) {
+    installGetter(runtime, prototype, "__brand", &VideoFrame::getBrand);
+    installGetter(runtime, prototype, "handle", &VideoFrame::getHandle);
+    installGetter(runtime, prototype, "width", &VideoFrame::getWidth);
+    installGetter(runtime, prototype, "height", &VideoFrame::getHeight);
+    installGetter(runtime, prototype, "pixelFormat",
+                  &VideoFrame::getPixelFormat);
+    installMethod(runtime, prototype, "release", &VideoFrame::release);
+  }
+
+private:
+  VideoFrameHandle _handle;
+};
+
+} // namespace rnwgpu