react-native-skia-webgpu-video 0.1.0-beta.4 → 0.1.0

package/src/frameInterop.ts

@@ -14,6 +14,7 @@ import {
   frameByteSize,
   releaseVideoMemory,
   reserveVideoMemory,
+  videoMemoryBudget,
 } from "./memory";
 import {
   blitNv12Frame,
@@ -44,9 +45,18 @@ type FrameTexture =
 type Entry = {
   id: number;
   image: SkImage | null;
+  /** The import texture the image wraps, if any. */
+  texture?: GPUTexture | null;
   reservation: number;
   releasedSources: WeakSet<VideoFrame>;
 };
+/** A decoder buffer an import's GPU copy still reads. */
+type InFlightImport = {
+  frame: VideoFrame;
+  nativeSource: NativeVideoFrame | null;
+  /** The decoder buffer's size, still reserved in the memory budget. */
+  bytes: number;
+};
 type PendingSource = {
   owned: SkImage | null;
   reservation: number;
@@ -55,21 +65,58 @@ type PendingSource = {
   sourceReleased: boolean;
   nativeSource?: NativeVideoFrame | null;
 };
+/** A texture frames are converted into, and that their images wrap. */
+type ImportTexture = {
+  texture: GPUTexture;
+  width: number;
+  height: number;
+  format: GPUTextureFormat;
+  reservation: number;
+};
+/** The textures of a producer: its frames go into them in turn, so that the
+ * image of the previous frame stays whole while the next is written. One
+ * texture only, written in place, when the memory budget is short. */
+type ImportTarget = { textures: ImportTexture[] };
 type Cache = {
   images: Map<number, Entry>;
   stage: SkSurface | null;
   canvas: SkCanvas | null;
-  width: number;
-  height: number;
-  format: GPUTextureFormat | null;
+  /** The texture `stage` wraps: the one of the last import, owned by its
+   * producer's target or by `freeTextures`. */
   uploadTexture: GPUTexture | null;
-  uploadReservation: number;
+  targets: Map<number, ImportTarget>;
+  /** Textures of released producers, for the next producer of that size. */
+  freeTextures: ImportTexture[];
   cpuPixels: Uint8Array<ArrayBuffer> | null;
   cpuReservation: number;
   cpuBytesPerRow: number;
   pendingSources: PendingSource[];
   /** Android decoder buffers imported once, per producer. */
   yuvImports: Map<number, YuvImport[]>;
+  /** Checked GPU waits so far (see videoFrameImportWaits). */
+  checkedWaits: number;
+  /** Oldest first; at most maxInFlightImports. */
+  inFlight: InFlightImport[];
+};
+
+// Imports whose GPU copy may still be running, their decoder buffers out. Kept
+// below the YUV imports cached per producer (yuvBlit.ts), so that the one it
+// evicts, the least recently drawn, is never still being read.
+const maxInFlightImports = 2;
+
+/** Whether the memory budget affords keeping a decoder buffer of `bytes` out
+ * until the GPU is done with it: a buffer within a sixteenth of the budget
+ * (two out stay within an eighth), and room left for the decoder's next two
+ * frames, which it reserves ahead. With the default 256 MB, a 4K BGRA frame
+ * (33 MB) is waited for; two 4K NV12 ones (12 MB each) are not. */
+const affordsInFlight = (bytes: number): boolean => {
+  "worklet";
+  const budget = videoMemoryBudget();
+  return (
+    !!budget &&
+    bytes <= budget.maxBytes / 16 &&
+    budget.maxBytes - budget.currentBytes >= 2 * bytes
+  );
 };
 
 // Capture a scalar on the RN runtime instead of importing Platform inside a
@@ -86,16 +133,16 @@ const getCache = (): Cache => {
       images: new Map(),
       stage: null,
       canvas: null,
-      width: 0,
-      height: 0,
-      format: null,
       uploadTexture: null,
-      uploadReservation: 0,
+      targets: new Map(),
+      freeTextures: [],
       cpuPixels: null,
       cpuReservation: 0,
       cpuBytesPerRow: 0,
       pendingSources: [],
       yuvImports: new Map(),
+      checkedWaits: 0,
+      inFlight: [],
     };
   }
   return runtime.__rnskwgpuFrames;
@@ -121,6 +168,195 @@ const clearSurfaceView = (cache: Cache) => {
   cache.stage = null;
 };
 
+/** Waits for all the GPU work submitted so far, on the shared context. */
+const waitForGpu = (cache: Cache): void => {
+  "worklet";
+  if (cache.stage) cache.stage.flush(true);
+  else {
+    let texture = cache.uploadTexture ?? cache.freeTextures[0]?.texture;
+    if (!texture) {
+      for (const target of cache.targets.values()) {
+        texture = target.textures[0]?.texture;
+        if (texture) break;
+      }
+    }
+    // A released producer's textures may all be gone (too big to keep free)
+    // while its imports are still in flight: any Graphite surface's checked
+    // flush waits on the shared context just the same.
+    const view = texture
+      ? Skia.Surface.MakeFromGPUTexture(texture)
+      : Skia.Surface.MakeOffscreen(1, 1);
+    if (!view) throw new Error("Video import drain surface is unavailable");
+    try {
+      view.flush(true);
+    } finally {
+      view.dispose();
+    }
+  }
+  cache.checkedWaits++;
+};
+
+/** Hands the decoder buffers of the first `count` imports in flight back,
+ * once the GPU is done with them: because the GPU reported the last of these
+ * imports done (in order: the work before it is done too), or after a wait
+ * for it, made here when `count` is all of them and nobody `waited`. */
+const settleInFlightImports = (
+  cache: Cache,
+  count: number,
+  waited = false,
+): void => {
+  "worklet";
+  if (!count) return;
+  if (count === cache.inFlight.length && !waited) waitForGpu(cache);
+  for (let i = 0; i < count; i++) {
+    const entry = cache.inFlight.shift()!;
+    try {
+      entry.nativeSource?.release();
+      entry.nativeSource = null;
+      entry.frame.dispose?.();
+    } catch (error) {
+      // Like a failed release at import: only the final drain retries it.
+      cache.pendingSources.push({
+        nativeSource: entry.nativeSource,
+        owned: null,
+        reservation: 0,
+        frame: entry.frame,
+        needsDrain: false,
+        sourceReleased: false,
+      });
+      throw error;
+    }
+  }
+};
+
+// Free textures kept for the next producer, when they are small enough.
+const maxFreeImportTextures = 2;
+
+/** Work already submitted still completes on a destroyed texture; a caller
+ * that cannot tell whether everything reading it was submitted waits first. */
+const destroyImportTexture = (cache: Cache, entry: ImportTexture) => {
+  "worklet";
+  if (cache.uploadTexture === entry.texture) {
+    clearSurfaceView(cache);
+    cache.uploadTexture = null;
+  }
+  entry.texture.destroy();
+  releaseVideoMemory(entry.reservation);
+  entry.reservation = 0;
+};
+
+// A texture leaves its list only once destroyed: a failed teardown is
+// retried by the next one, its memory still accounted.
+const releaseFreeImportTextures = (cache: Cache) => {
+  "worklet";
+  while (cache.freeTextures.length) {
+    destroyImportTexture(cache, cache.freeTextures[cache.freeTextures.length - 1]!);
+    cache.freeTextures.pop();
+  }
+};
+
+/** Gives up the textures of a producer whose image is disposed. Small ones
+ * are kept for the next producer of that size (a montage goes from clip to
+ * clip), within the budget's sixteenth each, as for imports in flight. */
+const releaseImportTarget = (cache: Cache, producer: number, keep = true) => {
+  "worklet";
+  const target = cache.targets.get(producer);
+  if (!target) return;
+  const budget = videoMemoryBudget();
+  while (target.textures.length) {
+    const entry = target.textures[target.textures.length - 1]!;
+    if (
+      keep &&
+      cache.freeTextures.length < maxFreeImportTextures &&
+      !!budget &&
+      frameByteSize(entry.width, entry.height) <= budget.maxBytes / 16
+    )
+      cache.freeTextures.push(entry);
+    else destroyImportTexture(cache, entry);
+    target.textures.pop();
+  }
+  cache.targets.delete(producer);
+};
+
+/** The texture the next frame of `producer` goes into: one that its current
+ * image does not wrap, when the producer has or can afford a second one. */
+const acquireImportTexture = (
+  cache: Cache,
+  device: GPUDevice,
+  producer: number,
+  width: number,
+  height: number,
+  format: GPUTextureFormat,
+  usage: number,
+  label: string,
+): GPUTexture => {
+  "worklet";
+  let target = cache.targets.get(producer);
+  if (
+    target &&
+    target.textures.some(
+      (entry) =>
+        entry.width !== width ||
+        entry.height !== height ||
+        entry.format !== format,
+    )
+  ) {
+    // The producer changed size: its image wraps a texture given up here.
+    clearEntry(cache, producer);
+    releaseImportTarget(cache, producer, false);
+    target = undefined;
+  }
+  if (!target) {
+    target = { textures: [] };
+    cache.targets.set(producer, target);
+  }
+  const shown = cache.images.get(producer);
+  const live = shown?.image
+    ? target.textures.findIndex((entry) => entry.texture === shown.texture)
+    : -1;
+  let index = target.textures.findIndex((_, i) => i !== live);
+  if (index < 0) {
+    const free = cache.freeTextures.findIndex(
+      (entry) =>
+        entry.width === width &&
+        entry.height === height &&
+        entry.format === format,
+    );
+    const bytes = frameByteSize(width, height);
+    const budget = videoMemoryBudget();
+    if (free >= 0) {
+      target.textures.push(cache.freeTextures.splice(free, 1)[0]!);
+      index = target.textures.length - 1;
+    } else if (
+      !target.textures.length ||
+      !budget ||
+      budget.maxBytes - budget.currentBytes >= 3 * bytes
+    ) {
+      // Free textures of another size only hold memory back from here on.
+      releaseFreeImportTextures(cache);
+      const reservation = reserveVideoMemory(bytes, label);
+      let texture: GPUTexture;
+      try {
+        texture = device.createTexture({
+          size: { width, height },
+          format,
+          usage,
+          label,
+        });
+      } catch (error) {
+        releaseVideoMemory(reservation);
+        throw error;
+      }
+      target.textures.push({ texture, width, height, format, reservation });
+      index = target.textures.length - 1;
+    } else {
+      // No room for a second texture: write over the current frame.
+      index = live;
+    }
+  }
+  return target.textures[index]!.texture;
+};
+
 const clearCpuPixels = (cache: Cache) => {
   "worklet";
   cache.cpuPixels = null;
@@ -131,34 +367,44 @@ const clearCpuPixels = (cache: Cache) => {
 
 const clearStagingSurface = (cache: Cache) => {
   "worklet";
+  settleInFlightImports(cache, cache.inFlight.length);
   cache.stage?.flush(true);
   clearSurfaceView(cache);
-  cache.uploadTexture?.destroy();
+  for (const producer of [...cache.targets.keys()])
+    releaseImportTarget(cache, producer, false);
+  releaseFreeImportTextures(cache);
   cache.uploadTexture = null;
-  releaseVideoMemory(cache.uploadReservation);
-  cache.uploadReservation = 0;
   clearCpuPixels(cache);
-  cache.width = cache.height = 0;
-  cache.format = null;
 };
 
 /** Record explicit recovery work after a possibly submitted external copy.
- * Clearing scratch cannot modify an already owned snapshot. The checked fence
- * must succeed before either native lease or the texture can be released. */
+ * It clears the texture of the import that failed, whose image is dropped;
+ * with two textures, the producer's previous image is in the other one. The
+ * checked fence must succeed before either native lease or the texture can be released. */
 const drainNativeCopies = (cache: Cache): void => {
   "worklet";
   if (!cache.stage || !cache.canvas)
     throw new Error("Video import drain surface is unavailable");
   cache.canvas.drawColor(Skia.Color("#00000000"), BlendMode.Clear);
   cache.stage.flush(true);
+  cache.checkedWaits++;
+};
+
+/** The checked GPU waits this runtime's imports have made so far, and the
+ * completions the GPU reported for them. Each one covers all the GPU work
+ * submitted before it, on the shared context. */
+export const videoFrameImportWaits = (): number => {
+  "worklet";
+  return getCache().checkedWaits;
 };
 
 /** Clear a runtime's imported images after ending all its producers.
  * Do not clear a paused producer's current frame: its native source has
- * already been released, and the owned snapshot is its remaining pixels. */
+ * already been released, and its image's texture is its remaining pixels. */
 export const clearVideoFrameImages = (releaseStagingSurface = false): void => {
   "worklet";
   const cache = getCache();
+  settleInFlightImports(cache, cache.inFlight.length);
   if (cache.pendingSources.length) {
     // A failed drain retains leases; only a successful fence can release them.
     if (cache.pendingSources.some((source) => source.needsDrain)) {
@@ -202,18 +448,30 @@ export const releaseVideoFrameImage = (frame: VideoFrame): void => {
   const producer = frame.producerId ?? frame.id ?? -1;
   const cache = getCache();
   const entry = cache.images.get(producer);
-  if (entry && entry.id === (frame.id ?? -1)) clearEntry(cache, producer);
-  // Each import ends with a checked flush; after a failed one, only the
-  // drain in clearVideoFrameImages may release the decoder buffers.
-  if (!cache.pendingSources.length)
+  if (entry && entry.id === (frame.id ?? -1)) {
+    clearEntry(cache, producer);
+    releaseImportTarget(cache, producer);
+  }
+  // Every import is done once the GPU is; after a failed one, only the drain
+  // in clearVideoFrameImages may release the decoder buffers.
+  if (!cache.pendingSources.length && cache.yuvImports.has(producer)) {
+    settleInFlightImports(cache, cache.inFlight.length);
     releaseYuvImports(cache.yuvImports, producer);
+  }
   if (cache.images.size === 0) clearVideoFrameImages(true);
 };
 
-/** Returns immutable, owned pixels. WebGPU uploads Android RGBA pixels or blits
- * native buffers into one reusable texture, then snapshots a fresh Skia view.
- * Graphite-backed snapshots bypass the raster ImageProvider's image-count LRU.
- * Wait for completion before releasing sources or rewriting the scratch texture. */
+/** Returns owned pixels. WebGPU uploads Android RGBA pixels or blits native
+ * buffers into a texture of the frame's producer, which the image wraps: no
+ * copy into a snapshot, and no entry in the raster ImageProvider's LRU.
+ * Sources go back once the GPU is done with them.
+ *
+ * The image is the producer's until its next frame is imported, which
+ * disposes it. A producer has two textures and writes its frames into them in
+ * turn, so the texture of an image is only written again by the import after
+ * the one that disposed it; with a memory budget too short for a second
+ * texture, the next frame is written over it, in queue order after the draws
+ * already submitted. */
 export const imageFromVideoFrame = (frame: VideoFrame): SkImage | null => {
   "worklet";
   const cache = getCache();
@@ -222,7 +480,7 @@ export const imageFromVideoFrame = (frame: VideoFrame): SkImage | null => {
     const existing = cache.images.get(producer);
     if (existing?.id === frame.id && existing.image) {
       // Android can issue a fresh lease for the same paused picture. The
-      // snapshot already owns its pixels, so close that unused native lease.
+      // image already owns its pixels, so close that unused native lease.
       // Weak tracking avoids retaining raw buffers or closing one wrapper twice.
       if (!existing.releasedSources.has(frame)) {
         frame.dispose?.();
@@ -237,6 +495,9 @@ export const imageFromVideoFrame = (frame: VideoFrame): SkImage | null => {
   let ownsSurfaceView = false;
   let nativeSource: NativeVideoFrame | null = null;
   let sourceDrained = false;
+  let completion: Promise<undefined> | null = null;
+  let sourceBytes = 0;
+  let importTexture: GPUTexture | null = null;
   let releaseSource = true;
   let importFailed = false;
   try {
@@ -310,7 +571,7 @@ export const imageFromVideoFrame = (frame: VideoFrame): SkImage | null => {
           );
           const data = Skia.Data.fromBytes(pixels);
           try {
-            image = Skia.Image.MakeRasterImage(
+            image = Skia.Image.MakeRaster(
               {
                 width: frame.width,
                 height: frame.height,
@@ -343,49 +604,25 @@ export const imageFromVideoFrame = (frame: VideoFrame): SkImage | null => {
       }
       const format =
         uploadRgba || uploadAndroidRgba ? "rgba8unorm" : "bgra8unorm";
-      reservation = reserveVideoMemory(bytes, "owned video image");
-      if (
-        !cache.uploadTexture ||
-        cache.width !== frame.width ||
-        cache.height !== frame.height ||
-        cache.format !== format
-      ) {
-        clearStagingSurface(cache);
-        cache.uploadReservation = reserveVideoMemory(
-          bytes,
-          uploadRgba
-            ? "RGBA frame WebGPU upload texture"
-            : "native frame WebGPU upload texture",
-        );
-        try {
-          // One scratch texture per runtime. COPY_SRC lets Graphite snapshot
-          // it with a GPU blit rather than draw into another staging target.
-          cache.uploadTexture = device.createTexture({
-            size: { width: frame.width, height: frame.height },
-            format,
-            // Android AHB and CPU frames share the RGBA scratch. Include
-            // COPY_DST even for a first AHB frame, so a later CPU fallback
-            // cannot reuse a texture that forbids writeTexture.
-            usage:
-              uploadRgba || uploadAndroidRgba
-                ? rgbaVideoTextureUsage
-                : nativeVideoTextureUsage,
-            label: uploadRgba
-              ? "video RGBA frame upload"
-              : "video native frame upload",
-          });
-          cache.width = frame.width;
-          cache.height = frame.height;
-          cache.format = format;
-        } catch (error) {
-          try {
-            clearStagingSurface(cache);
-          } catch {
-            /* unfinished cleanup/accounting stays reachable */
-          }
-          throw error;
-        }
-      }
+      // The frame is converted straight into a texture of its producer, which
+      // the image wraps: no copy into a snapshot. Android AHB and CPU frames
+      // share RGBA textures, COPY_DST included even for a first AHB frame, so
+      // that a later CPU fallback can write into them.
+      clearSurfaceView(cache);
+      cache.uploadTexture = null;
+      cache.uploadTexture = acquireImportTexture(
+        cache,
+        device,
+        key,
+        frame.width,
+        frame.height,
+        format,
+        uploadRgba || uploadAndroidRgba
+          ? rgbaVideoTextureUsage
+          : nativeVideoTextureUsage,
+        uploadRgba ? "video RGBA frame" : "video native frame",
+      );
+      importTexture = cache.uploadTexture;
       if (copyRgbaPixels && texture.kind === "rgba") {
         if (
           !cache.cpuPixels ||
@@ -422,9 +659,8 @@ export const imageFromVideoFrame = (frame: VideoFrame): SkImage | null => {
         clearCpuPixels(cache);
       }
       clearSurfaceView(cache);
-      // WebGPU writes do not invalidate SkSurface's cached snapshot. A fresh
-      // surface wrapper for every frame prevents stale pixels without another
-      // GPU allocation or a write through Skia that would overwrite the input.
+      // The surface only carries the checked submissions and waits of this
+      // import, and its recovery drain; the image wraps the texture itself.
       cache.stage = Skia.Surface.MakeFromGPUTexture(cache.uploadTexture!);
       if (!cache.stage) throw new Error("Cannot wrap video upload texture");
       ownsSurfaceView = true;
@@ -509,25 +745,84 @@ export const imageFromVideoFrame = (frame: VideoFrame): SkImage | null => {
       }
       // Snapshot records an independent texture copy and submits it after
       // the external blit on the shared queue. The wrapper never draws.
-      image = cache.stage.makeImageSnapshot();
-      cache.stage.flush(true);
-      sourceDrained = true;
+      image = Skia.Image.MakeFromGPUTexture(cache.uploadTexture!);
+      // Submitted without waiting for the GPU, which held the UI thread for
+      // the work of every Skia view on the shared context: the decoder buffer
+      // is handed back once the GPU reports the copy done. A wait still
+      // bounds the buffers out, and stands in where nothing can report.
+      // NV12 and Android's YUV buffers take a byte and a half per pixel.
+      sourceBytes =
+        texture.kind === "native-buffer" &&
+        (texture.region || texture.format === "nv12")
+          ? Math.ceil(bytes * 0.375)
+          : bytes;
+      const wait =
+        typeof device.queue.onSubmittedWorkDone !== "function" ||
+        cache.inFlight.length >= maxInFlightImports ||
+        !affordsInFlight(sourceBytes);
+      cache.stage.flush(wait);
+      if (!wait) {
+        try {
+          completion = device.queue.onSubmittedWorkDone();
+        } catch {
+          // A runtime WebGPU cannot settle promises on.
+          completion = null;
+        }
+      }
+      if (wait || !completion) {
+        if (!wait) cache.stage.flush(true);
+        cache.checkedWaits++;
+        // Every import before this one is done too.
+        settleInFlightImports(cache, cache.inFlight.length, true);
+        completion = null;
+        sourceDrained = true;
+      }
     }
     if (!image) throw new Error("Cannot create a video frame image");
-    // Complete the native handoff before replacing published pixels. A failed
-    // source close must not evict a paused image or leave an unpublished cache
-    // entry behind when the caller receives an import error.
-    if (ownsSurfaceView) {
-      clearSurfaceView(cache);
+    if (completion) {
+      // The GPU copy may still read the decoder buffer: it goes back once the
+      // GPU reports the copy done, or after a wait (settleInFlightImports).
+      // The view stays for that wait.
+      const entry: InFlightImport = { frame, nativeSource, bytes: sourceBytes };
+      cache.inFlight.push(entry);
+      nativeSource = null;
+      releaseSource = false;
       ownsSurfaceView = false;
+      completion.then(
+        () => {
+          const settled = cache.inFlight.indexOf(entry) + 1;
+          // Zero: a wait handed it back already.
+          if (!settled) return;
+          cache.checkedWaits++;
+          try {
+            settleInFlightImports(cache, settled, true);
+          } catch (error) {
+            console.warn("Video frame release failed", error);
+          }
+        },
+        // Handed back by the next wait instead.
+        () => undefined,
+      );
+    } else {
+      // Complete the native handoff before replacing published pixels. A
+      // failed source close must not evict a paused image or leave an
+      // unpublished cache entry behind when the caller receives an import
+      // error.
+      if (ownsSurfaceView) {
+        clearSurfaceView(cache);
+        ownsSurfaceView = false;
+      }
+      nativeSource?.release();
+      nativeSource = null;
+      frame.dispose?.();
+      releaseSource = false;
     }
-    nativeSource?.release();
-    nativeSource = null;
-    frame.dispose?.();
-    releaseSource = false;
     clearEntry(cache, key);
     cache.images.set(key, {
-      id: frame.id ?? -1, image, reservation,
+      id: frame.id ?? -1,
+      image,
+      reservation,
+      texture: importTexture,
       releasedSources: new WeakSet([frame]),
     });
     return image;

package/src/gpu.ts

@@ -166,7 +166,7 @@ export const createVideoGpuScope = (options?: {
         resource.surface = Skia.Surface.MakeFromGPUTexture(resource.texture);
         resource.canvas = getVideoCanvas(resource.surface);
       } else if (skia === "image") {
-        resource.image = Skia.Image.MakeImageFromGPUTexture(resource.texture);
+        resource.image = Skia.Image.MakeFromGPUTexture(resource.texture);
       }
       resources.push(resource);
       return {

package/src/memory.ts

@@ -37,6 +37,12 @@ export const frameByteSize = (width: number, height: number): number => {
   return bytes;
 };
 
+/** The budget's counters, from any runtime; null without them. */
+export const videoMemoryBudget = (): VideoMemoryStats | null => {
+  "worklet";
+  return RNSkiaVideoModule.getMemoryBudgetStats?.() ?? null;
+};
+
 export const reserveVideoMemory = (bytes: number, label: string): number => {
   "worklet";
   return RNSkiaVideoModule.reserveMemory?.(bytes, label) ?? 0;

package/src/previewLifecycle.ts

@@ -5,6 +5,8 @@ import type { VideoFrame } from "./types";
 
 type PreviewResources = {
   surface?: SkSurface | null;
+  /** The preview's second buffer (see useVideoCompositionPlayer). */
+  spareSurface?: SkSurface | null;
   canvas?: SkCanvas | null;
   images?: Array<SkImage | null>;
   frames?: VideoFrame[];
@@ -36,6 +38,8 @@ export const disposePreviewResources = (resources: PreviewResources) => {
     resources.canvas = null;
     resources.surface?.dispose();
     resources.surface = null;
+    resources.spareSurface?.dispose();
+    resources.spareSurface = null;
     releaseVideoMemory(resources.reservation ?? 0);
     resources.reservation = 0;
   } catch (error) {

package/src/types.ts

@@ -157,15 +157,16 @@ export type VideoPlayer = {
  *   (12.4 MB rather than 33.2 MB in 4K), so the decoder holds more frames
  *   ahead for the same memory. On Android only 8-bit SDR tracks decoded at
  *   their own size; other tracks stay `rgba`.
- * - `rgba`: frames converted to RGB as they are decoded (iOS: by VideoToolbox,
- *   Android: by an OpenGL pass), which a GPU export samples in place.
+ * - `rgba` (deprecated): frames converted to RGB as they are decoded (iOS: by
+ *   VideoToolbox, Android: by an OpenGL pass). It no longer has an advantage:
+ *   exports run as fast in `yuv`, which renders the same colors, and a 4K60
+ *   preview keeps fewer frames on screen in `rgba`, whose frames take 4 bytes
+ *   a pixel. It still works; use `auto`.
  * - `auto`: `yuv`, on both platforms.
  *
- * Camera footage (Rec.709, or HLG tone mapped to Rec.709) renders the same
- * either way: both convert with the frame's YCbCr matrix and range. On iOS,
- * `rgba` also converts a file tagged with other primaries or another SDR
- * transfer function (Display P3, sRGB) to Rec.709; `yuv` takes its samples as
- * Rec.709, as Android does in both formats.
+ * Both convert with the frame's YCbCr matrix and range. On iOS, both convert
+ * HDR (HLG, PQ), BT.2020, Display P3 and sRGB files to Rec.709 through
+ * AVFoundation. Android takes SDR samples as Rec.709 in both formats.
  */
 export type VideoFramePixelFormat = "auto" | "yuv" | "rgba";