react-native-webgpu 0.14.1 → 0.15.0

package/android/cpp/AndroidColorSpace.h

@@ -0,0 +1,107 @@
+#pragma once
+
+#include <android/data_space.h>
+
+#include <cstdint>
+
+#include "PlatformContext.h"
+
+namespace rnwgpu {
+
+// The data spaces that predate the standard / transfer / range bit fields
+// (HAL_DATASPACE_* in system/graphics.h, "legacy" since Android 6) as the
+// field form the NDK header documents for them. Decoders still report them:
+// a Pixel 8 on Android 17 tags every H.264 frame with the legacy BT.709
+// value. The modern header no longer defines these constants.
+inline int32_t canonicalDataSpace(int32_t dataSpace) {
+  switch (dataSpace) {
+  case 0x101: // HAL_DATASPACE_JFIF
+    return STANDARD_BT601_625 | TRANSFER_SMPTE_170M | RANGE_FULL;
+  case 0x102: // HAL_DATASPACE_BT601_625
+    return STANDARD_BT601_625 | TRANSFER_SMPTE_170M | RANGE_LIMITED;
+  case 0x103: // HAL_DATASPACE_BT601_525
+    return STANDARD_BT601_525 | TRANSFER_SMPTE_170M | RANGE_LIMITED;
+  case 0x104: // HAL_DATASPACE_BT709
+    return STANDARD_BT709 | TRANSFER_SMPTE_170M | RANGE_LIMITED;
+  case 0x200: // HAL_DATASPACE_SRGB_LINEAR
+    return STANDARD_BT709 | TRANSFER_LINEAR | RANGE_FULL;
+  case 0x201: // HAL_DATASPACE_SRGB
+    return STANDARD_BT709 | TRANSFER_SRGB | RANGE_FULL;
+  default:
+    return dataSpace;
+  }
+}
+
+// The color space a frame's data space declares (android/data_space.h, the
+// value of Image.getDataSpace() or of the container's color info packed the
+// same way). The standard gives the YCbCr matrix and the primaries; the
+// transfer function and the range are what their names say. The fields a data
+// space leaves unspecified stay unset, and ADATASPACE_UNKNOWN (0) sets nothing.
+inline VideoFrameColorSpace colorSpaceFromDataSpace(int32_t dataSpace) {
+  VideoFrameColorSpace colorSpace;
+  dataSpace = canonicalDataSpace(dataSpace);
+  switch (dataSpace & STANDARD_MASK) {
+  case STANDARD_BT709:
+    colorSpace.matrix = wgpu::ColorSpaceYCbCrMatrixDawn::Rec709;
+    // BT.709 shares the sRGB primaries (Dawn's helper only knows them under
+    // that name).
+    colorSpace.primaries = wgpu::ColorSpacePrimariesDawn::SRGB;
+    break;
+  case STANDARD_BT601_625:
+  case STANDARD_BT601_625_UNADJUSTED:
+  case STANDARD_BT601_525:
+  case STANDARD_BT601_525_UNADJUSTED:
+    colorSpace.matrix = wgpu::ColorSpaceYCbCrMatrixDawn::Rec601;
+    colorSpace.primaries = wgpu::ColorSpacePrimariesDawn::Rec601;
+    break;
+  case STANDARD_BT2020:
+  case STANDARD_BT2020_CONSTANT_LUMINANCE:
+    colorSpace.matrix = wgpu::ColorSpaceYCbCrMatrixDawn::Rec2020;
+    colorSpace.primaries = wgpu::ColorSpacePrimariesDawn::Rec2020;
+    break;
+  case STANDARD_DCI_P3:
+    colorSpace.matrix = wgpu::ColorSpaceYCbCrMatrixDawn::Rec709;
+    colorSpace.primaries = wgpu::ColorSpacePrimariesDawn::DisplayP3;
+    break;
+  default:
+    break;
+  }
+  switch (dataSpace & TRANSFER_MASK) {
+  case TRANSFER_LINEAR:
+    colorSpace.transfer = wgpu::ColorSpaceTransferDawn::Identity;
+    break;
+  case TRANSFER_SRGB:
+  case TRANSFER_GAMMA2_2: // sRGB is the closest curve Dawn has
+    colorSpace.transfer = wgpu::ColorSpaceTransferDawn::SRGB;
+    break;
+  case TRANSFER_SMPTE_170M:
+    colorSpace.transfer = wgpu::ColorSpaceTransferDawn::SMPTE_170M;
+    break;
+  case TRANSFER_GAMMA2_6:
+  case TRANSFER_GAMMA2_8: // BT.1886 (gamma 2.4) is the closest
+    colorSpace.transfer = wgpu::ColorSpaceTransferDawn::BT_1886;
+    break;
+  case TRANSFER_ST2084:
+    colorSpace.transfer = wgpu::ColorSpaceTransferDawn::PQ;
+    break;
+  case TRANSFER_HLG:
+    colorSpace.transfer = wgpu::ColorSpaceTransferDawn::HLG;
+    break;
+  default:
+    break;
+  }
+  switch (dataSpace & RANGE_MASK) {
+  case RANGE_FULL:
+  case RANGE_EXTENDED:
+    colorSpace.range = wgpu::ColorSpaceYCbCrRangeDawn::Full;
+    break;
+  case RANGE_LIMITED:
+    colorSpace.range = wgpu::ColorSpaceYCbCrRangeDawn::Narrow;
+    break;
+  default:
+    break;
+  }
+  return colorSpace;
+}
+
+} // namespace rnwgpu

package/android/cpp/AndroidPlatformContext.h

@@ -1,7 +1,9 @@
 #pragma once
 
 #include <android/bitmap.h>
+#include <android/data_space.h>
 #include <android/hardware_buffer.h>
+#include <dlfcn.h>
 #include <jni.h>
 
 #include <algorithm>
@@ -9,10 +11,12 @@
 #include <memory>
 #include <string>
 #include <thread>
+#include <utility>
 #include <vector>
 
 #include "webgpu/webgpu_cpp.h"
 
+#include "AndroidColorSpace.h"
 #include "AndroidVideoPlayer.h"
 #include "PlatformContext.h"
 #include "RNWebGPUManager.h"
@@ -24,9 +28,10 @@ namespace jni = facebook::jni;
 
 // The completion callbacks of one snapshotView request, heap-allocated and
 // carried through Java as an opaque pointer (WebGPUModule.snapshotView ->
-// onViewSnapshot), which hands them back exactly once.
+// onViewSnapshot / onViewSnapshotBuffer), which hands them back exactly once.
 struct ViewSnapshotCallbacks {
-  std::function<void(ImageData)> onSuccess;
+  std::function<void(ImageData)> onPixels;
+  std::function<void(VideoFrameHandle)> onFrame;
   std::function<void(std::string)> onError;
 };
 
@@ -90,7 +95,8 @@ public:
   }
 
   void snapshotView(const ViewSnapshotRequest &request,
-                    std::function<void(ImageData)> onSuccess,
+                    std::function<void(ImageData)> onPixels,
+                    std::function<void(VideoFrameHandle)> onFrame,
                     std::function<void(std::string)> onError) override {
     if (!_module) {
       onError("drawElementImageToTexture: the WebGPU module is gone");
@@ -104,7 +110,7 @@ public:
     }
     jclass moduleClass = env->GetObjectClass(_module);
     jmethodID method =
-        env->GetMethodID(moduleClass, "snapshotView", "(IDDDDIIJ)V");
+        env->GetMethodID(moduleClass, "snapshotView", "(IDDDDIIZJ)V");
     env->DeleteLocalRef(moduleClass);
     if (!method) {
       env->ExceptionClear();
@@ -112,9 +118,9 @@ public:
       return;
     }
     // Ownership passes to Java; Java_com_webgpu_WebGPUModule_onViewSnapshot
-    // (cpp-adapter.cpp) reclaims it.
-    auto *callbacks =
-        new ViewSnapshotCallbacks{std::move(onSuccess), std::move(onError)};
+    // or onViewSnapshotBuffer (cpp-adapter.cpp) reclaims it.
+    auto *callbacks = new ViewSnapshotCallbacks{
+        std::move(onPixels), std::move(onFrame), std::move(onError)};
     env->CallVoidMethod(_module, method, static_cast<jint>(request.viewTag),
                         static_cast<jdouble>(request.sourceX),
                         static_cast<jdouble>(request.sourceY),
@@ -122,6 +128,7 @@ public:
                         static_cast<jdouble>(request.sourceHeight),
                         static_cast<jint>(request.width),
                         static_cast<jint>(request.height),
+                        static_cast<jboolean>(request.allowFrame),
                         reinterpret_cast<jlong>(callbacks));
     if (env->ExceptionCheck()) {
       env->ExceptionClear();
@@ -268,8 +275,92 @@ public:
         "device.importSharedTextureMemory.");
   }
 
-  VideoFrameHandle createTestVideoFrame(uint32_t width,
-                                        uint32_t height) override {
+  // The NV12 variant of createTestVideoFrame: a Y8Cb8Cr8_420 buffer, the YUV
+  // layout every gralloc supports, BT.709 limited range, red on the left half
+  // and green on the right. Filling it needs AHardwareBuffer_lockPlanes
+  // (API 29), resolved at run time since the library runs from API 26.
+  VideoFrameHandle createTestYuvFrame(uint32_t width, uint32_t height) {
+    using LockPlanes = int (*)(AHardwareBuffer *, uint64_t, int32_t,
+                               const ARect *, AHardwareBuffer_Planes *);
+    static const auto lockPlanes = reinterpret_cast<LockPlanes>(
+        dlsym(RTLD_DEFAULT, "AHardwareBuffer_lockPlanes"));
+    if (lockPlanes == nullptr) {
+      throw std::runtime_error(
+          "createTestVideoFrame: unsupported: a YUV test frame needs "
+          "AHardwareBuffer_lockPlanes (API 29)");
+    }
+
+    AHardwareBuffer_Desc desc = {};
+    desc.width = width;
+    desc.height = height;
+    desc.layers = 1;
+    desc.format = AHARDWAREBUFFER_FORMAT_Y8Cb8Cr8_420;
+    desc.usage = AHARDWAREBUFFER_USAGE_GPU_SAMPLED_IMAGE |
+                 AHARDWAREBUFFER_USAGE_CPU_WRITE_RARELY |
+                 AHARDWAREBUFFER_USAGE_CPU_READ_RARELY;
+    AHardwareBuffer *buffer = nullptr;
+    int err = AHardwareBuffer_allocate(&desc, &buffer);
+    if (err != 0 || !buffer) {
+      throw std::runtime_error(
+          "createTestVideoFrame: unsupported: AHardwareBuffer_allocate failed "
+          "for a Y8Cb8Cr8_420 buffer (" +
+          std::to_string(err) + ")");
+    }
+
+    AHardwareBuffer_Planes planes = {};
+    int rc = lockPlanes(buffer, AHARDWAREBUFFER_USAGE_CPU_WRITE_RARELY, -1,
+                        nullptr, &planes);
+    if (rc != 0 || planes.planeCount < 3) {
+      AHardwareBuffer_release(buffer);
+      throw std::runtime_error(
+          "createTestVideoFrame: unsupported: AHardwareBuffer_lockPlanes "
+          "failed (" +
+          std::to_string(rc) + ")");
+    }
+    // Plane 0 is Y, 1 is Cb, 2 is Cr; the chroma planes are subsampled by two
+    // on both axes and the strides say whether Cb and Cr interleave.
+    const auto &y = planes.planes[0];
+    const auto &cb = planes.planes[1];
+    const auto &cr = planes.planes[2];
+    for (uint32_t row = 0; row < height; ++row) {
+      auto *line = static_cast<uint8_t *>(y.data) + row * y.rowStride;
+      for (uint32_t col = 0; col < width; ++col) {
+        line[col * y.pixelStride] =
+            col < width / 2 ? test_yuv_frame::kRedY : test_yuv_frame::kGreenY;
+      }
+    }
+    const uint32_t chromaWidth = (width + 1) / 2;
+    const uint32_t chromaHeight = (height + 1) / 2;
+    for (uint32_t row = 0; row < chromaHeight; ++row) {
+      auto *cbLine = static_cast<uint8_t *>(cb.data) + row * cb.rowStride;
+      auto *crLine = static_cast<uint8_t *>(cr.data) + row * cr.rowStride;
+      for (uint32_t col = 0; col < chromaWidth; ++col) {
+        bool red = col < chromaWidth / 2;
+        cbLine[col * cb.pixelStride] =
+            red ? test_yuv_frame::kRedCb : test_yuv_frame::kGreenCb;
+        crLine[col * cr.pixelStride] =
+            red ? test_yuv_frame::kRedCr : test_yuv_frame::kGreenCr;
+      }
+    }
+    AHardwareBuffer_unlock(buffer, nullptr);
+
+    VideoFrameHandle handle;
+    handle.handle = static_cast<void *>(buffer);
+    handle.width = width;
+    handle.height = height;
+    handle.pixelFormat = VideoPixelFormat::NV12;
+    // What a BT.709 SDR video declares: ADATASPACE_BT709 is STANDARD_BT709 |
+    // TRANSFER_SMPTE_170M | RANGE_LIMITED.
+    handle.colorSpace = colorSpaceFromDataSpace(ADATASPACE_BT709);
+    handle.deleter = [buffer]() { AHardwareBuffer_release(buffer); };
+    return handle;
+  }
+
+  VideoFrameHandle createTestVideoFrame(uint32_t width, uint32_t height,
+                                        VideoPixelFormat format) override {
+    if (format == VideoPixelFormat::NV12) {
+      return createTestYuvFrame(width, height);
+    }
     // Dawn's Android backend already requires API 26+, so AHardwareBuffer_*
     // symbols are guaranteed to be available at link time on supported builds.
     AHardwareBuffer_Desc desc = {};

package/android/cpp/AndroidVideoPlayer.h

@@ -4,12 +4,14 @@
 #include <android/hardware_buffer_jni.h>
 #include <fbjni/fbjni.h>
 #include <jni.h>
+#include <unistd.h>
 
 #include <memory>
 #include <stdexcept>
 #include <string>
 #include <utility>
 
+#include "AndroidColorSpace.h"
 #include "PlatformContext.h"
 
 namespace rnwgpu {
@@ -94,6 +96,17 @@ public:
     _getRotation = method(env, playerClass, "getRotation", "()I");
     _getFrameRate = method(env, playerClass, "getFrameRate", "()D");
     _release = method(env, playerClass, "release", "()V");
+    _frameDataSpace =
+        method(env, playerClass, "frameDataSpace", "(Landroid/media/Image;)I");
+    _acquireFenceFd = env->GetStaticMethodID(playerClass, "acquireFenceFd",
+                                             "(Landroid/media/Image;)I");
+    if (_acquireFenceFd == nullptr) {
+      env->ExceptionClear();
+      env->DeleteLocalRef(playerClass);
+      throw std::runtime_error("VideoPlayer: method acquireFenceFd not found");
+    }
+    // The static call needs the class; keep it for the player's lifetime.
+    _playerClass = static_cast<jclass>(env->NewGlobalRef(playerClass));
     env->DeleteLocalRef(playerClass);
 
     jclass imageClass = env->FindClass("android/media/Image");
@@ -108,6 +121,7 @@ public:
     if (env->ExceptionCheck()) {
       env->ExceptionClear();
     }
+    env->DeleteGlobalRef(_playerClass);
   }
 
   VideoFrameHandle copyLatestFrame() override {
@@ -144,6 +158,28 @@ public:
           "them");
     }
 
+    // The decoder may still be writing the frame: ImageReader hands out the
+    // buffer as soon as it is queued and only waits on the producer's fence for
+    // CPU access (Image.getPlanes), not for Image.getHardwareBuffer. The GPU
+    // work that samples the frame waits on the fence instead (see
+    // GPUExternalTexture::Create). -1 when the platform cannot report it
+    // (before API 33) or the producer was already done.
+    int acquireFenceFd =
+        env->CallStaticIntMethod(_playerClass, _acquireFenceFd, image);
+    if (env->ExceptionCheck()) {
+      env->ExceptionClear();
+      acquireFenceFd = -1;
+    }
+
+    // The color space of the samples: the frame's data space (API 33) or the
+    // container's color info. What it leaves unknown is resolved at import.
+    int32_t dataSpace =
+        env->CallIntMethod(_player->get(), _frameDataSpace, image);
+    if (env->ExceptionCheck()) {
+      env->ExceptionClear();
+      dataSpace = 0;
+    }
+
     // The frame owns a reference to the buffer and keeps the Image acquired
     // until it is released; closing the Image hands the buffer back to the
     // decoder.
@@ -157,9 +193,12 @@ public:
     handle.height = desc.height;
     handle.pixelFormat = isRgbFormat(desc.format) ? VideoPixelFormat::BGRA8
                                                   : VideoPixelFormat::NV12;
+    handle.acquireFenceFd = acquireFenceFd;
+    handle.colorSpace = colorSpaceFromDataSpace(dataSpace);
     auto player = _player;
     jmethodID closeImageMethod = _closeImage;
-    handle.deleter = [player, closeImageMethod, imageRef, buffer]() {
+    handle.deleter = [player, closeImageMethod, imageRef, buffer,
+                      acquireFenceFd]() {
       JNIEnv *env = attach();
       env->CallVoidMethod(player->get(), closeImageMethod, imageRef);
       if (env->ExceptionCheck()) {
@@ -167,6 +206,9 @@ public:
       }
       env->DeleteGlobalRef(imageRef);
       AHardwareBuffer_release(buffer);
+      if (acquireFenceFd >= 0) {
+        ::close(acquireFenceFd);
+      }
     };
     return handle;
   }
@@ -284,8 +326,11 @@ private:
   }
 
   std::shared_ptr<JavaVideoPlayerRef> _player;
+  jclass _playerClass;
   jmethodID _copyLatestFrame;
   jmethodID _closeImage;
+  jmethodID _frameDataSpace;
+  jmethodID _acquireFenceFd;
   jmethodID _play;
   jmethodID _pause;
   jmethodID _getPaused;

package/android/cpp/cpp-adapter.cpp

@@ -1,3 +1,5 @@
+#include <unistd.h>
+
 #include <cstring>
 #include <memory>
 #include <string>
@@ -92,7 +94,57 @@ extern "C" JNIEXPORT void JNICALL Java_com_webgpu_WebGPUModule_onViewSnapshot(
                 rowBytes);
   }
   AndroidBitmap_unlockPixels(env, bitmap);
-  callbacks->onSuccess(std::move(image));
+  callbacks->onPixels(std::move(image));
+}
+
+// Completion of WebGPUModule.snapshotView through a hardware buffer (UI
+// thread, Android 13 and above): the buffer HardwareRenderer drew the view
+// into, and the fence that signals when the drawing is done, as a sync fd
+// this function takes ownership of. The GPU draws the buffer into the
+// destination itself (GPUQueue::drawElementImageToTexture); nothing is read
+// back through the CPU.
+extern "C" JNIEXPORT void JNICALL
+Java_com_webgpu_WebGPUModule_onViewSnapshotBuffer(JNIEnv *env,
+                                                  jobject /* this */,
+                                                  jlong callbackPointer,
+                                                  jobject hardwareBuffer,
+                                                  jint fenceFd) {
+  std::unique_ptr<rnwgpu::ViewSnapshotCallbacks> callbacks(
+      reinterpret_cast<rnwgpu::ViewSnapshotCallbacks *>(callbackPointer));
+  AHardwareBuffer *buffer =
+      hardwareBuffer != nullptr
+          ? AHardwareBuffer_fromHardwareBuffer(env, hardwareBuffer)
+          : nullptr;
+  if (!callbacks || buffer == nullptr) {
+    if (fenceFd >= 0) {
+      ::close(fenceFd);
+    }
+    if (callbacks) {
+      callbacks->onError(
+          "drawElementImageToTexture: the renderer produced no buffer");
+    }
+    return;
+  }
+  AHardwareBuffer_Desc desc{};
+  AHardwareBuffer_describe(buffer, &desc);
+  // Java closes its Image and HardwareBuffer as soon as this returns; this
+  // reference keeps the memory alive until the frame is released.
+  AHardwareBuffer_acquire(buffer);
+
+  rnwgpu::VideoFrameHandle frame;
+  frame.handle = buffer;
+  frame.width = desc.width;
+  frame.height = desc.height;
+  // An RGBA_8888 buffer: sampled as a plain color texture.
+  frame.pixelFormat = rnwgpu::VideoPixelFormat::BGRA8;
+  frame.acquireFenceFd = fenceFd;
+  frame.deleter = [buffer, fenceFd]() {
+    AHardwareBuffer_release(buffer);
+    if (fenceFd >= 0) {
+      ::close(fenceFd);
+    }
+  };
+  callbacks->onFrame(std::move(frame));
 }
 
 extern "C" JNIEXPORT void JNICALL Java_com_webgpu_WebGPUView_onSurfaceChanged(

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

@@ -0,0 +1,88 @@
+package com.webgpu;
+
+import android.hardware.SyncFence;
+import android.media.Image;
+import android.os.Build;
+import android.os.Parcel;
+import android.os.ParcelFileDescriptor;
+import android.util.Log;
+
+import androidx.annotation.NonNull;
+import androidx.annotation.RequiresApi;
+
+import java.io.IOException;
+
+/**
+ * Bridges the platform's {@link SyncFence} to the sync file descriptors Dawn imports as
+ * {@code shared-fence-sync-fd} fences.
+ *
+ * <p>A buffer handed out by an {@link android.media.ImageReader} carries an acquire fence: the
+ * producer (the video decoder, the camera, a {@link android.graphics.HardwareRenderer}) may still
+ * be writing it when the consumer acquires it. The framework waits on that fence for CPU access
+ * ({@link Image#getPlanes()}), but not for {@link Image#getHardwareBuffer()}, so a GPU consumer has
+ * to wait on it itself. Since API 33 the fence is exposed as {@link Image#getFence()}.
+ */
+final class SyncFences {
+  private static final String TAG = "WebGPUSyncFences";
+
+  private SyncFences() {}
+
+  /**
+   * The acquire fence of {@code image} as a sync file descriptor the caller owns and must close,
+   * or -1 when the frame has none (the producer was done when it was acquired, or the platform
+   * predates {@link Image#getFence()}).
+   */
+  static int acquireFenceFd(@NonNull Image image) {
+    if (Build.VERSION.SDK_INT < Build.VERSION_CODES.TIRAMISU) {
+      return -1;
+    }
+    return acquireFenceFdApi33(image);
+  }
+
+  @RequiresApi(Build.VERSION_CODES.TIRAMISU)
+  private static int acquireFenceFdApi33(@NonNull Image image) {
+    SyncFence fence;
+    try {
+      fence = image.getFence();
+    } catch (IOException | RuntimeException e) {
+      Log.w(TAG, "could not read the acquire fence of the frame: " + e.getMessage());
+      return -1;
+    }
+    try {
+      return detachFd(fence);
+    } finally {
+      // getFence() returns a duplicate; the detached descriptor is ours, this one goes.
+      fence.close();
+    }
+  }
+
+  /**
+   * The file descriptor of {@code fence}, duplicated and detached, so it stays valid after the
+   * fence is closed and must be closed by the caller. -1 for an invalid fence.
+   *
+   * <p>{@link SyncFence} has no public accessor for its descriptor. Writing the fence to a {@link
+   * Parcel} and reading it back yields one: the parcel form is a validity flag followed by the
+   * file descriptor.
+   */
+  @RequiresApi(Build.VERSION_CODES.TIRAMISU)
+  static int detachFd(@NonNull SyncFence fence) {
+    if (!fence.isValid()) {
+      return -1;
+    }
+    Parcel parcel = Parcel.obtain();
+    try {
+      fence.writeToParcel(parcel, 0);
+      parcel.setDataPosition(0);
+      if (!parcel.readBoolean()) {
+        return -1;
+      }
+      ParcelFileDescriptor descriptor = parcel.readFileDescriptor();
+      return descriptor == null ? -1 : descriptor.detachFd();
+    } catch (RuntimeException e) {
+      Log.w(TAG, "could not read the file descriptor of a SyncFence: " + e.getMessage());
+      return -1;
+    } finally {
+      parcel.recycle();
+    }
+  }
+}

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

@@ -24,7 +24,10 @@ import androidx.annotation.RequiresApi;
  * On API 29+ the view is rendered through {@link HardwareRenderer}: the
  * recording reuses the children's existing display lists, so the result is
  * exactly what the window's own renderer draws (shadows, hardware layers,
- * TextureView content). Older devices, or a failed hardware render, fall back
+ * TextureView content). The renderer draws into a GPU-sampleable buffer,
+ * which {@link #renderHardware} hands to its caller as is: the WebGPU side
+ * imports it directly when it can, and {@link #snapshot} reads it back into
+ * a bitmap otherwise. Older devices, or a failed hardware render, fall back
  * to drawing the view into a software canvas, which misses anything that is
  * only drawn hardware-accelerated. SurfaceView content is composed outside
  * the view hierarchy and is captured by neither path.
@@ -34,6 +37,11 @@ final class ViewSnapshot {
 
   private ViewSnapshot() {}
 
+  /** What a caller does with the frame the hardware renderer drew, while it is acquired. */
+  interface FrameConsumer<T> {
+    T consume(@NonNull Image image) throws Exception;
+  }
+
   /**
    * @param sourceX/Y/Width/Height the source rectangle in the view's own
    *     coordinate space, in pixels (already scaled by the display density)
@@ -77,19 +85,27 @@ final class ViewSnapshot {
     return bitmap;
   }
 
+  /**
+   * Renders the view through {@link HardwareRenderer} into a GPU-sampleable
+   * RGBA_8888 buffer of exactly width x height pixels and hands the acquired
+   * frame to {@code consumer}; the reader and the renderer are torn down when
+   * it returns, so a consumer that keeps the buffer takes its own reference
+   * first. The renderer only submits the frame: the drawing may still be in
+   * flight on the GPU when the consumer runs. {@link Image#getFence()} (API 33)
+   * tells when it is done; a CPU readback of the buffer waits for it on its
+   * own.
+   */
   @RequiresApi(Build.VERSION_CODES.Q)
-  @NonNull
-  private static Bitmap snapshotHardware(
+  static <T> T renderHardware(
       @NonNull View view,
       float sourceX,
       float sourceY,
       float sourceWidth,
       float sourceHeight,
       int width,
-      int height) {
-    // The renderer draws into an ImageReader whose buffers are GPU-sampleable
-    // (a later zero-copy path can import them directly); for now the frame is
-    // read back into a software bitmap.
+      int height,
+      @NonNull FrameConsumer<T> consumer)
+      throws Exception {
     ImageReader reader =
         ImageReader.newInstance(
             width,
@@ -135,22 +151,7 @@ final class ViewSnapshot {
       if (image == null) {
         throw new IllegalStateException("HardwareRenderer produced no image");
       }
-      HardwareBuffer buffer = image.getHardwareBuffer();
-      if (buffer == null) {
-        throw new IllegalStateException("HardwareRenderer image has no HardwareBuffer");
-      }
-      Bitmap hardware =
-          Bitmap.wrapHardwareBuffer(buffer, ColorSpace.get(ColorSpace.Named.SRGB));
-      buffer.close();
-      if (hardware == null) {
-        throw new IllegalStateException("Bitmap.wrapHardwareBuffer failed");
-      }
-      Bitmap software = hardware.copy(Bitmap.Config.ARGB_8888, false);
-      hardware.recycle();
-      if (software == null) {
-        throw new IllegalStateException("could not read back the hardware bitmap");
-      }
-      return software;
+      return consumer.consume(image);
     } finally {
       if (image != null) {
         image.close();
@@ -159,4 +160,46 @@ final class ViewSnapshot {
       reader.close();
     }
   }
+
+  @RequiresApi(Build.VERSION_CODES.Q)
+  @NonNull
+  private static Bitmap snapshotHardware(
+      @NonNull View view,
+      float sourceX,
+      float sourceY,
+      float sourceWidth,
+      float sourceHeight,
+      int width,
+      int height)
+      throws Exception {
+    return renderHardware(
+        view,
+        sourceX,
+        sourceY,
+        sourceWidth,
+        sourceHeight,
+        width,
+        height,
+        image -> {
+          HardwareBuffer buffer = image.getHardwareBuffer();
+          if (buffer == null) {
+            throw new IllegalStateException("HardwareRenderer image has no HardwareBuffer");
+          }
+          // wrapHardwareBuffer takes its own reference, so the wrapper can be
+          // closed immediately; the copy reads the pixels back into software
+          // memory, waiting for the renderer to finish drawing.
+          Bitmap hardware =
+              Bitmap.wrapHardwareBuffer(buffer, ColorSpace.get(ColorSpace.Named.SRGB));
+          buffer.close();
+          if (hardware == null) {
+            throw new IllegalStateException("Bitmap.wrapHardwareBuffer failed");
+          }
+          Bitmap software = hardware.copy(Bitmap.Config.ARGB_8888, false);
+          hardware.recycle();
+          if (software == null) {
+            throw new IllegalStateException("could not read back the hardware bitmap");
+          }
+          return software;
+        });
+  }
 }