@fishjam-cloud/react-native-custom-video-source 0.29.0

package/README.md

@@ -0,0 +1,70 @@
+# `@fishjam-cloud/react-native-custom-video-source`
+
+Publish your own video frames to Fishjam from **any** frame source. This is the generic layer
+under [`@fishjam-cloud/react-native-vision-camera-source`](../react-native-vision-camera-source) —
+use that package if your source is [VisionCamera](https://react-native-vision-camera.com); use this
+one directly for any other source (a native ML pipeline, a compositor, your own renderer).
+
+There are two modes, picked by **how you produce frames**:
+
+- **Forwarding** — you already have finished native buffers. `useManagedForwardTrack()` creates and
+  owns the track; hand each buffer pointer to `forwardFrame` from `@fishjam-cloud/react-native-webrtc`.
+- **Render-target (pooled)** — you render the frames yourself. `useManagedPooledTrack()` allocates a
+  surface pool; draw into it and hand each frame back with `pushFrame`. The
+  [`/webgpu`](#webgpu-camera-toolkit) entry point provides a WebGPU camera-rendering toolkit for this
+  mode.
+
+Each hook owns the track's async lifecycle — creation, the published `stream`, and teardown — so you
+only feed frames. Must be used under `FishjamProvider` from `@fishjam-cloud/react-native-client`.
+
+## Prerequisites
+
+- `@fishjam-cloud/react-native-webrtc` and `@fishjam-cloud/react-native-client` (with your app wrapped
+  in `FishjamProvider`)
+- New Architecture (custom video tracks require it)
+- For the `/webgpu` entry only: `react-native-webgpu` ≥ 0.5.15, plus `unplugin-typegpu` in your app's
+  Babel config (the shaders are authored in [TypeGPU](https://docs.swmansion.com/TypeGPU/)), and
+  **iOS 17+** for the Metal external-texture camera-import path.
+
+## Forward finished buffers
+
+```tsx
+import { useManagedForwardTrack } from '@fishjam-cloud/react-native-custom-video-source';
+import { forwardFrame } from '@fishjam-cloud/react-native-webrtc';
+import { useCustomSource } from '@fishjam-cloud/react-native-client';
+
+const { track, stream } = useManagedForwardTrack(/* enabled */ true);
+// publish `stream` (e.g. via useCustomSource), then per frame:
+forwardFrame(track, { nativeBuffer /* bigint CVPixelBufferRef / AHardwareBuffer* */ });
+```
+
+## Render your own frames
+
+```tsx
+import { useManagedPooledTrack } from '@fishjam-cloud/react-native-custom-video-source';
+import { pushFrame } from '@fishjam-cloud/react-native-webrtc';
+
+const { track, bufferDescriptors } = useManagedPooledTrack(true, 720, 1280, /* poolSize */ 3);
+// import bufferDescriptors[i].surfaceHandle into your GPU, render into slot i, then:
+pushFrame(track, { bufferIndex: i, timestampNs });
+```
+
+## WebGPU camera toolkit
+
+`@fishjam-cloud/react-native-custom-video-source/webgpu` samples the live camera and helps you render
+into the pooled surfaces:
+
+- `createCameraShaderBindings` / `sampleCamera` — sample the camera from your own shaders, YUV decode
+  handled per platform
+- `createCameraPassthroughPipeline` / `encodeCameraPassthrough` — a ready-made camera→output pass
+- `useCameraWebGpuDevice` — the shared, camera-import-capable `GPUDevice`
+- `computeAspectFillCrop` / `computeSquareCrop` / `packFrameCropParams` — crop + orientation helpers
+
+> Verify camera + WebGPU behavior on **physical devices** — the iOS Simulator cannot import the
+> camera's YUV textures.
+
+## Development
+
+Part of the [web-client-sdk](https://github.com/fishjam-cloud/web-client-sdk) monorepo. `yarn build`
+compiles `src/` to `dist/` with `react-native-builder-bob` (Babel + `unplugin-typegpu` for the TGSL
+shaders, `tsc` for type definitions).

package/dist/module/index.js

@@ -0,0 +1,22 @@
+/**
+ * Publish your own video frames to Fishjam.
+ *
+ * Source-lifecycle hooks that create a custom video track, publish it, and clean it up — you
+ * supply the frames from any source. Two modes, picked by how you produce frames:
+ *
+ * - {@link useManagedForwardTrack} — you already have finished native buffers (a camera, a native
+ *   ML pipeline, a compositor); forward each buffer pointer with `forwardFrame` from
+ *   `@fishjam-cloud/react-native-webrtc`.
+ * - {@link useManagedPooledTrack} — you render the frames yourself; allocate a surface pool, draw
+ *   into it, and hand each frame back with `pushFrame`. The `@fishjam-cloud/react-native-custom-video-source/webgpu`
+ *   entry point provides a WebGPU camera-rendering toolkit for this mode.
+ *
+ * For a ready-made VisionCamera integration on top of this, use
+ * `@fishjam-cloud/react-native-vision-camera-source`.
+ *
+ * @packageDocumentation
+ */
+
+export { useManagedForwardTrack } from './internal/useManagedForwardTrack';
+export { useManagedPooledTrack } from './internal/useManagedPooledTrack';
+//# sourceMappingURL=index.js.map

package/dist/module/index.js.map

@@ -0,0 +1 @@
+{"version":3,"names":["useManagedForwardTrack","useManagedPooledTrack"],"sources":["index.ts"],"sourcesContent":["/**\n * Publish your own video frames to Fishjam.\n *\n * Source-lifecycle hooks that create a custom video track, publish it, and clean it up — you\n * supply the frames from any source. Two modes, picked by how you produce frames:\n *\n * - {@link useManagedForwardTrack} — you already have finished native buffers (a camera, a native\n *   ML pipeline, a compositor); forward each buffer pointer with `forwardFrame` from\n *   `@fishjam-cloud/react-native-webrtc`.\n * - {@link useManagedPooledTrack} — you render the frames yourself; allocate a surface pool, draw\n *   into it, and hand each frame back with `pushFrame`. The `@fishjam-cloud/react-native-custom-video-source/webgpu`\n *   entry point provides a WebGPU camera-rendering toolkit for this mode.\n *\n * For a ready-made VisionCamera integration on top of this, use\n * `@fishjam-cloud/react-native-vision-camera-source`.\n *\n * @packageDocumentation\n */\n\nexport { type ManagedForwardTrack, useManagedForwardTrack } from './internal/useManagedForwardTrack';\nexport {\n  type ManagedPooledTrack,\n  useManagedPooledTrack,\n  type WorkletBufferDescriptor,\n} from './internal/useManagedPooledTrack';\n"],"mappings":"AAAA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;;AAEA,SAAmCA,sBAAsB,QAAQ,mCAAmC;AACpG,SAEEC,qBAAqB,QAEhB,kCAAkC","ignoreList":[]}

package/dist/module/internal/stopStreamTracks.js

@@ -0,0 +1,9 @@
+/** Stops every track of `stream`, downgrading failures to a warning tagged with `ownerLabel`. */
+export function stopStreamTracks(stream, ownerLabel) {
+  try {
+    stream.getTracks().forEach(mediaTrack => mediaTrack.stop());
+  } catch (cause) {
+    console.warn(`${ownerLabel}: stopping tracks failed`, cause);
+  }
+}
+//# sourceMappingURL=stopStreamTracks.js.map

package/dist/module/internal/stopStreamTracks.js.map

@@ -0,0 +1 @@
+{"version":3,"names":["stopStreamTracks","stream","ownerLabel","getTracks","forEach","mediaTrack","stop","cause","console","warn"],"sources":["stopStreamTracks.ts"],"sourcesContent":["import type { MediaStream } from '@fishjam-cloud/react-native-webrtc';\n\n/** Stops every track of `stream`, downgrading failures to a warning tagged with `ownerLabel`. */\nexport function stopStreamTracks(stream: MediaStream, ownerLabel: string): void {\n  try {\n    stream.getTracks().forEach((mediaTrack) => mediaTrack.stop());\n  } catch (cause) {\n    console.warn(`${ownerLabel}: stopping tracks failed`, cause);\n  }\n}\n"],"mappings":"AAEA;AACA,OAAO,SAASA,gBAAgBA,CAACC,MAAmB,EAAEC,UAAkB,EAAQ;EAC9E,IAAI;IACFD,MAAM,CAACE,SAAS,CAAC,CAAC,CAACC,OAAO,CAAEC,UAAU,IAAKA,UAAU,CAACC,IAAI,CAAC,CAAC,CAAC;EAC/D,CAAC,CAAC,OAAOC,KAAK,EAAE;IACdC,OAAO,CAACC,IAAI,CAAC,GAAGP,UAAU,0BAA0B,EAAEK,KAAK,CAAC;EAC9D;AACF","ignoreList":[]}

package/dist/module/internal/toError.js

@@ -0,0 +1,5 @@
+/** Coerce an unknown thrown value into an Error, leaving real Errors untouched. */
+export function toError(cause) {
+  return cause instanceof Error ? cause : new Error(String(cause));
+}
+//# sourceMappingURL=toError.js.map

package/dist/module/internal/toError.js.map

@@ -0,0 +1 @@
+{"version":3,"names":["toError","cause","Error","String"],"sources":["toError.ts"],"sourcesContent":["/** Coerce an unknown thrown value into an Error, leaving real Errors untouched. */\nexport function toError(cause: unknown): Error {\n  return cause instanceof Error ? cause : new Error(String(cause));\n}\n"],"mappings":"AAAA;AACA,OAAO,SAASA,OAAOA,CAACC,KAAc,EAAS;EAC7C,OAAOA,KAAK,YAAYC,KAAK,GAAGD,KAAK,GAAG,IAAIC,KAAK,CAACC,MAAM,CAACF,KAAK,CAAC,CAAC;AAClE","ignoreList":[]}

package/dist/module/internal/useManagedForwardTrack.js

@@ -0,0 +1,63 @@
+import { createCustomVideoTrack } from '@fishjam-cloud/react-native-webrtc';
+import { useEffect, useState } from 'react';
+import { stopStreamTracks } from './stopStreamTracks';
+import { toError } from './toError';
+
+/**
+ * State of a forwarding custom video track managed by {@link useManagedForwardTrack}.
+ * While the track is being created (or after an error) `track` and `stream` are `null`.
+ */
+
+const INITIAL_STATE = {
+  track: null,
+  stream: null,
+  error: null
+};
+
+/**
+ * Owns the async lifecycle of a forwarding custom video track: creates it while `enabled`,
+ * exposes the handle + stream once ready, and stops the tracks on disable/unmount (also when
+ * creation resolves after the owner already unmounted).
+ */
+export function useManagedForwardTrack(enabled) {
+  const [managedTrack, setManagedTrack] = useState(INITIAL_STATE);
+  useEffect(() => {
+    // The disabled case needs no work: the previous run's cleanup already reset the state.
+    if (!enabled) {
+      return;
+    }
+    // Creation is async, so the effect may be torn down before it resolves. `disposed` records
+    // that; `created` holds the result once it exists so cleanup can stop it exactly once.
+    let disposed = false;
+    let created = null;
+    createCustomVideoTrack().then(result => {
+      if (disposed) {
+        // Torn down while creating — throw the just-built track away.
+        stopStreamTracks(result.stream, 'useManagedForwardTrack');
+        return;
+      }
+      created = result;
+      setManagedTrack({
+        track: result.track,
+        stream: result.stream,
+        error: null
+      });
+    }).catch(cause => {
+      if (!disposed) {
+        setManagedTrack({
+          ...INITIAL_STATE,
+          error: toError(cause)
+        });
+      }
+    });
+    return () => {
+      disposed = true;
+      if (created != null) {
+        stopStreamTracks(created.stream, 'useManagedForwardTrack');
+      }
+      setManagedTrack(INITIAL_STATE);
+    };
+  }, [enabled]);
+  return managedTrack;
+}
+//# sourceMappingURL=useManagedForwardTrack.js.map

package/dist/module/internal/useManagedForwardTrack.js.map

@@ -0,0 +1 @@
+{"version":3,"names":["createCustomVideoTrack","useEffect","useState","stopStreamTracks","toError","INITIAL_STATE","track","stream","error","useManagedForwardTrack","enabled","managedTrack","setManagedTrack","disposed","created","then","result","catch","cause"],"sources":["useManagedForwardTrack.ts"],"sourcesContent":["import {\n  createCustomVideoTrack,\n  type CustomVideoTrackResult,\n  type ForwardTrack,\n  type MediaStream,\n} from '@fishjam-cloud/react-native-webrtc';\nimport { useEffect, useState } from 'react';\n\nimport { stopStreamTracks } from './stopStreamTracks';\nimport { toError } from './toError';\n\n/**\n * State of a forwarding custom video track managed by {@link useManagedForwardTrack}.\n * While the track is being created (or after an error) `track` and `stream` are `null`.\n */\nexport interface ManagedForwardTrack {\n  track: ForwardTrack | null;\n  stream: MediaStream | null;\n  error: Error | null;\n}\n\nconst INITIAL_STATE: ManagedForwardTrack = { track: null, stream: null, error: null };\n\n/**\n * Owns the async lifecycle of a forwarding custom video track: creates it while `enabled`,\n * exposes the handle + stream once ready, and stops the tracks on disable/unmount (also when\n * creation resolves after the owner already unmounted).\n */\nexport function useManagedForwardTrack(enabled: boolean): ManagedForwardTrack {\n  const [managedTrack, setManagedTrack] = useState<ManagedForwardTrack>(INITIAL_STATE);\n\n  useEffect(() => {\n    // The disabled case needs no work: the previous run's cleanup already reset the state.\n    if (!enabled) {\n      return;\n    }\n    // Creation is async, so the effect may be torn down before it resolves. `disposed` records\n    // that; `created` holds the result once it exists so cleanup can stop it exactly once.\n    let disposed = false;\n    let created: CustomVideoTrackResult<ForwardTrack> | null = null;\n\n    createCustomVideoTrack()\n      .then((result) => {\n        if (disposed) {\n          // Torn down while creating — throw the just-built track away.\n          stopStreamTracks(result.stream, 'useManagedForwardTrack');\n          return;\n        }\n        created = result;\n        setManagedTrack({ track: result.track, stream: result.stream, error: null });\n      })\n      .catch((cause: unknown) => {\n        if (!disposed) {\n          setManagedTrack({ ...INITIAL_STATE, error: toError(cause) });\n        }\n      });\n\n    return () => {\n      disposed = true;\n      if (created != null) {\n        stopStreamTracks(created.stream, 'useManagedForwardTrack');\n      }\n      setManagedTrack(INITIAL_STATE);\n    };\n  }, [enabled]);\n\n  return managedTrack;\n}\n"],"mappings":"AAAA,SACEA,sBAAsB,QAIjB,oCAAoC;AAC3C,SAASC,SAAS,EAAEC,QAAQ,QAAQ,OAAO;AAE3C,SAASC,gBAAgB,QAAQ,oBAAoB;AACrD,SAASC,OAAO,QAAQ,WAAW;;AAEnC;AACA;AACA;AACA;;AAOA,MAAMC,aAAkC,GAAG;EAAEC,KAAK,EAAE,IAAI;EAAEC,MAAM,EAAE,IAAI;EAAEC,KAAK,EAAE;AAAK,CAAC;;AAErF;AACA;AACA;AACA;AACA;AACA,OAAO,SAASC,sBAAsBA,CAACC,OAAgB,EAAuB;EAC5E,MAAM,CAACC,YAAY,EAAEC,eAAe,CAAC,GAAGV,QAAQ,CAAsBG,aAAa,CAAC;EAEpFJ,SAAS,CAAC,MAAM;IACd;IACA,IAAI,CAACS,OAAO,EAAE;MACZ;IACF;IACA;IACA;IACA,IAAIG,QAAQ,GAAG,KAAK;IACpB,IAAIC,OAAoD,GAAG,IAAI;IAE/Dd,sBAAsB,CAAC,CAAC,CACrBe,IAAI,CAAEC,MAAM,IAAK;MAChB,IAAIH,QAAQ,EAAE;QACZ;QACAV,gBAAgB,CAACa,MAAM,CAACT,MAAM,EAAE,wBAAwB,CAAC;QACzD;MACF;MACAO,OAAO,GAAGE,MAAM;MAChBJ,eAAe,CAAC;QAAEN,KAAK,EAAEU,MAAM,CAACV,KAAK;QAAEC,MAAM,EAAES,MAAM,CAACT,MAAM;QAAEC,KAAK,EAAE;MAAK,CAAC,CAAC;IAC9E,CAAC,CAAC,CACDS,KAAK,CAAEC,KAAc,IAAK;MACzB,IAAI,CAACL,QAAQ,EAAE;QACbD,eAAe,CAAC;UAAE,GAAGP,aAAa;UAAEG,KAAK,EAAEJ,OAAO,CAACc,KAAK;QAAE,CAAC,CAAC;MAC9D;IACF,CAAC,CAAC;IAEJ,OAAO,MAAM;MACXL,QAAQ,GAAG,IAAI;MACf,IAAIC,OAAO,IAAI,IAAI,EAAE;QACnBX,gBAAgB,CAACW,OAAO,CAACP,MAAM,EAAE,wBAAwB,CAAC;MAC5D;MACAK,eAAe,CAACP,aAAa,CAAC;IAChC,CAAC;EACH,CAAC,EAAE,CAACK,OAAO,CAAC,CAAC;EAEb,OAAOC,YAAY;AACrB","ignoreList":[]}

package/dist/module/internal/useManagedPooledTrack.js

@@ -0,0 +1,120 @@
+import { createCustomVideoBufferPool, createCustomVideoTrack } from '@fishjam-cloud/react-native-webrtc';
+import { useEffect, useState } from 'react';
+import { stopStreamTracks } from './stopStreamTracks';
+import { toError } from './toError';
+
+/** One pooled output surface as plain values the frame worklet can capture and import itself. */
+
+/**
+ * State of a pooled custom video track managed by {@link useManagedPooledTrack}.
+ * While the pool and track are being created (or after an error) all fields are `null`.
+ */
+
+const INITIAL_STATE = {
+  track: null,
+  stream: null,
+  bufferDescriptors: null,
+  error: null
+};
+
+/** A fully-allocated pool + its track, owned and torn down as a single unit. */
+
+function toWorkletBufferDescriptor(buffer) {
+  return {
+    index: buffer.index,
+    surfaceHandle: buffer.surfaceHandle,
+    width: buffer.width,
+    height: buffer.height
+  };
+}
+function disposePool(pool) {
+  void pool.dispose().catch(cause => {
+    console.warn('useManagedPooledTrack: disposing the buffer pool failed', cause);
+  });
+}
+
+/** Tears an allocation down in the required order: stop the track's frames, then free its pool. */
+function disposeAllocation({
+  pool,
+  stream
+}) {
+  stopStreamTracks(stream, 'useManagedPooledTrack');
+  disposePool(pool);
+}
+
+/** Allocates the surface pool and a track bound to it. If the track fails, frees the orphan pool. */
+async function allocatePooledTrack(width, height, poolSize) {
+  const pool = await createCustomVideoBufferPool({
+    width,
+    height,
+    poolSize
+  });
+  try {
+    const {
+      track,
+      stream
+    } = await createCustomVideoTrack({
+      pool
+    });
+    return {
+      pool,
+      track,
+      stream,
+      bufferDescriptors: pool.buffers.map(toWorkletBufferDescriptor)
+    };
+  } catch (cause) {
+    disposePool(pool);
+    throw cause;
+  }
+}
+
+/**
+ * Owns the async lifecycle of a surface pool + pooled custom video track: allocates both while
+ * `enabled` (re-allocates when the dimensions change), exposes worklet-ready descriptors, and
+ * tears down in the correct order (stop tracks, then dispose the pool) on disable/unmount.
+ */
+export function useManagedPooledTrack(enabled, width, height, poolSize) {
+  const [managedTrack, setManagedTrack] = useState(INITIAL_STATE);
+  useEffect(() => {
+    // The disabled case needs no work: the previous run's cleanup already reset the state (so
+    // consumers never hold descriptors of a disposed pool).
+    if (!enabled) {
+      return;
+    }
+
+    // Allocation is async, so the effect may be torn down before it resolves. `disposed` records
+    // that; `allocation` holds the result once it exists so cleanup can free it exactly once.
+    let disposed = false;
+    let allocation = null;
+    allocatePooledTrack(width, height, poolSize).then(result => {
+      if (disposed) {
+        // Torn down while allocating — throw the just-built resources away.
+        disposeAllocation(result);
+        return;
+      }
+      allocation = result;
+      setManagedTrack({
+        track: result.track,
+        stream: result.stream,
+        bufferDescriptors: result.bufferDescriptors,
+        error: null
+      });
+    }).catch(cause => {
+      if (!disposed) {
+        setManagedTrack({
+          ...INITIAL_STATE,
+          error: toError(cause)
+        });
+      }
+    });
+    return () => {
+      disposed = true;
+      if (allocation) {
+        disposeAllocation(allocation);
+      }
+      setManagedTrack(INITIAL_STATE);
+    };
+  }, [enabled, width, height, poolSize]);
+  return managedTrack;
+}
+//# sourceMappingURL=useManagedPooledTrack.js.map

package/dist/module/internal/useManagedPooledTrack.js.map

@@ -0,0 +1 @@
+{"version":3,"names":["createCustomVideoBufferPool","createCustomVideoTrack","useEffect","useState","stopStreamTracks","toError","INITIAL_STATE","track","stream","bufferDescriptors","error","toWorkletBufferDescriptor","buffer","index","surfaceHandle","width","height","disposePool","pool","dispose","catch","cause","console","warn","disposeAllocation","allocatePooledTrack","poolSize","buffers","map","useManagedPooledTrack","enabled","managedTrack","setManagedTrack","disposed","allocation","then","result"],"sources":["useManagedPooledTrack.ts"],"sourcesContent":["import {\n  createCustomVideoBufferPool,\n  createCustomVideoTrack,\n  type CustomVideoBuffer,\n  type CustomVideoBufferPool,\n  type MediaStream,\n  type PooledTrack,\n} from '@fishjam-cloud/react-native-webrtc';\nimport { useEffect, useState } from 'react';\n\nimport { stopStreamTracks } from './stopStreamTracks';\nimport { toError } from './toError';\n\n/** One pooled output surface as plain values the frame worklet can capture and import itself. */\nexport interface WorkletBufferDescriptor {\n  index: number;\n  surfaceHandle: bigint;\n  width: number;\n  height: number;\n}\n\n/**\n * State of a pooled custom video track managed by {@link useManagedPooledTrack}.\n * While the pool and track are being created (or after an error) all fields are `null`.\n */\nexport interface ManagedPooledTrack {\n  track: PooledTrack | null;\n  stream: MediaStream | null;\n  /** Plain per-surface descriptors (the pool object itself is not worklet-serializable). */\n  bufferDescriptors: WorkletBufferDescriptor[] | null;\n  error: Error | null;\n}\n\nconst INITIAL_STATE: ManagedPooledTrack = { track: null, stream: null, bufferDescriptors: null, error: null };\n\n/** A fully-allocated pool + its track, owned and torn down as a single unit. */\ninterface PooledTrackAllocation {\n  pool: CustomVideoBufferPool;\n  track: PooledTrack;\n  stream: MediaStream;\n  bufferDescriptors: WorkletBufferDescriptor[];\n}\n\nfunction toWorkletBufferDescriptor(buffer: CustomVideoBuffer): WorkletBufferDescriptor {\n  return { index: buffer.index, surfaceHandle: buffer.surfaceHandle, width: buffer.width, height: buffer.height };\n}\n\nfunction disposePool(pool: CustomVideoBufferPool): void {\n  void pool.dispose().catch((cause: unknown) => {\n    console.warn('useManagedPooledTrack: disposing the buffer pool failed', cause);\n  });\n}\n\n/** Tears an allocation down in the required order: stop the track's frames, then free its pool. */\nfunction disposeAllocation({ pool, stream }: PooledTrackAllocation): void {\n  stopStreamTracks(stream, 'useManagedPooledTrack');\n  disposePool(pool);\n}\n\n/** Allocates the surface pool and a track bound to it. If the track fails, frees the orphan pool. */\nasync function allocatePooledTrack(width: number, height: number, poolSize: number): Promise<PooledTrackAllocation> {\n  const pool = await createCustomVideoBufferPool({ width, height, poolSize });\n  try {\n    const { track, stream } = await createCustomVideoTrack({ pool });\n    return { pool, track, stream, bufferDescriptors: pool.buffers.map(toWorkletBufferDescriptor) };\n  } catch (cause) {\n    disposePool(pool);\n    throw cause;\n  }\n}\n\n/**\n * Owns the async lifecycle of a surface pool + pooled custom video track: allocates both while\n * `enabled` (re-allocates when the dimensions change), exposes worklet-ready descriptors, and\n * tears down in the correct order (stop tracks, then dispose the pool) on disable/unmount.\n */\nexport function useManagedPooledTrack(\n  enabled: boolean,\n  width: number,\n  height: number,\n  poolSize: number,\n): ManagedPooledTrack {\n  const [managedTrack, setManagedTrack] = useState<ManagedPooledTrack>(INITIAL_STATE);\n\n  useEffect(() => {\n    // The disabled case needs no work: the previous run's cleanup already reset the state (so\n    // consumers never hold descriptors of a disposed pool).\n    if (!enabled) {\n      return;\n    }\n\n    // Allocation is async, so the effect may be torn down before it resolves. `disposed` records\n    // that; `allocation` holds the result once it exists so cleanup can free it exactly once.\n    let disposed = false;\n    let allocation: PooledTrackAllocation | null = null;\n\n    allocatePooledTrack(width, height, poolSize)\n      .then((result) => {\n        if (disposed) {\n          // Torn down while allocating — throw the just-built resources away.\n          disposeAllocation(result);\n          return;\n        }\n        allocation = result;\n        setManagedTrack({\n          track: result.track,\n          stream: result.stream,\n          bufferDescriptors: result.bufferDescriptors,\n          error: null,\n        });\n      })\n      .catch((cause: unknown) => {\n        if (!disposed) {\n          setManagedTrack({ ...INITIAL_STATE, error: toError(cause) });\n        }\n      });\n\n    return () => {\n      disposed = true;\n      if (allocation) {\n        disposeAllocation(allocation);\n      }\n      setManagedTrack(INITIAL_STATE);\n    };\n  }, [enabled, width, height, poolSize]);\n\n  return managedTrack;\n}\n"],"mappings":"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","ignoreList":[]}

package/dist/module/webgpu/cameraPassthroughPipeline.js

@@ -0,0 +1,237 @@
+import { GPUBufferUsage, GPUShaderStage } from 'react-native-webgpu';
+import tgpu from 'typegpu';
+import * as d from 'typegpu/data';
+import { add, div, mul, sub } from 'typegpu/std';
+import { createCameraBindGroup, createCameraShaderBindings, sampleCamera } from './cameraShaderBindings';
+import { FrameCropParams, packFrameCropParams } from './cropUtilities';
+import { getOutputSurfaceFormat } from './requiredFeatures';
+
+// Crop is a plain uniform, so it is authored in TGSL and TypeGPU assigns it @group(0). The camera
+// is a `texture_external`, which TypeGPU cannot resolve in a shader, so its bindings are raw WGSL
+// and go at @group(1) (see cameraShaderBindings). This is a group swap from the pre-TGSL shader
+// (which had camera at 0, crop at 1) but is otherwise identical.
+const CROP_BIND_GROUP_INDEX = 0;
+const CAMERA_BIND_GROUP_INDEX = 1;
+const FRAME_CROP_BUFFER_BYTES = d.sizeOf(FrameCropParams);
+
+// TypeGPU bind group layout for the crop uniform — the source of truth for the WGSL declaration
+// and for the fragment's typed access to `cropParams`.
+const cropLayout = /*#__PURE__*/(globalThis.__TYPEGPU_AUTONAME__ ?? (a => a))(tgpu.bindGroupLayout({
+  cropParams: {
+    uniform: FrameCropParams
+  }
+}), "cropLayout");
+
+// One oversized triangle covering the viewport; uv spans [0,1] top-left origin over the visible
+// area.
+const vertexMain = tgpu.vertexFn({
+  in: {
+    vertexIndex: d.builtin.vertexIndex
+  },
+  out: {
+    position: d.builtin.position,
+    uv: d.location(0, d.vec2f)
+  }
+})(/*#__PURE__*/($ => (globalThis.__TYPEGPU_META__ ??= new WeakMap()).set($.f = input => {
+  const positions = [d.vec2f(-1, -1), d.vec2f(3, -1), d.vec2f(-1, 3)];
+  const position = positions[input.vertexIndex];
+  return {
+    position: d.vec4f(position.x, position.y, 0, 1),
+    uv: d.vec2f((position.x + 1) * 0.5, 1 - (position.y + 1) * 0.5)
+  };
+}, {
+  v: 1,
+  name: undefined,
+  ast: {
+    params: [{
+      type: "i",
+      name: "input"
+    }],
+    body: [0, [[13, "positions", [100, [[6, [7, "d", "vec2f"], [[4, "-", [5, "1"]], [4, "-", [5, "1"]]]], [6, [7, "d", "vec2f"], [[5, "3"], [4, "-", [5, "1"]]]], [6, [7, "d", "vec2f"], [[4, "-", [5, "1"]], [5, "3"]]]]]], [13, "position", [8, "positions", [7, "input", "vertexIndex"]]], [10, [104, {
+      position: [6, [7, "d", "vec4f"], [[7, "position", "x"], [7, "position", "y"], [5, "0"], [5, "1"]]],
+      uv: [6, [7, "d", "vec2f"], [[1, [1, [7, "position", "x"], "+", [5, "1"]], "*", [5, "0.5"]], [1, [5, "1"], "-", [1, [1, [7, "position", "y"], "+", [5, "1"]], "*", [5, "0.5"]]]]]
+    }]]]],
+    externalNames: ["d"]
+  },
+  externals: () => {
+    return {
+      d
+    };
+  }
+}) && $.f)({})).$name('vertexMain');
+
+// The fragment applies the FrameCropParams crop + orientation transform and samples the camera via
+// sampleCamera(). Mirroring is folded into a build-time sign/offset on uv.x (mirror → 1 - x) so the
+// shader stays branch-free.
+function makeFragmentMain(mirror) {
+  const mirrorSign = mirror ? -1 : 1;
+  const mirrorOffset = mirror ? 1 : 0;
+  return tgpu.fragmentFn({
+    in: {
+      screenUv: d.location(0, d.vec2f)
+    },
+    out: d.vec4f
+  })(/*#__PURE__*/($ => (globalThis.__TYPEGPU_META__ ??= new WeakMap()).set($.f = input => {
+    // cropUv = (mirrorSign * screenUv.x + mirrorOffset, screenUv.y), expressed with vector ops
+    // so mirrorSign/mirrorOffset fold to literals and the WGSL stays branch-free.
+    const cropUv = add(mul(input.screenUv, d.vec2f(mirrorSign, 1)), d.vec2f(mirrorOffset, 0));
+    const cp = cropLayout.$.cropParams;
+    const sourcePixel = add(cp.cropOrigin, mul(cropUv, cp.cropSize));
+    const sourceUv = div(sourcePixel, d.vec2f(cp.sourceSize));
+    const cameraUv = add(mul(cp.uvTransform, sub(sourceUv, d.vec2f(0.5))), d.vec2f(0.5));
+    return sampleCamera(cameraUv);
+  }, {
+    v: 1,
+    name: undefined,
+    ast: {
+      params: [{
+        type: "i",
+        name: "input"
+      }],
+      body: [0, [[13, "cropUv", [6, "add", [[6, "mul", [[7, "input", "screenUv"], [6, [7, "d", "vec2f"], ["mirrorSign", [5, "1"]]]]], [6, [7, "d", "vec2f"], ["mirrorOffset", [5, "0"]]]]]], [13, "cp", [7, [7, "cropLayout", "$"], "cropParams"]], [13, "sourcePixel", [6, "add", [[7, "cp", "cropOrigin"], [6, "mul", ["cropUv", [7, "cp", "cropSize"]]]]]], [13, "sourceUv", [6, "div", ["sourcePixel", [6, [7, "d", "vec2f"], [[7, "cp", "sourceSize"]]]]]], [13, "cameraUv", [6, "add", [[6, "mul", [[7, "cp", "uvTransform"], [6, "sub", ["sourceUv", [6, [7, "d", "vec2f"], [[5, "0.5"]]]]]]], [6, [7, "d", "vec2f"], [[5, "0.5"]]]]]], [10, [6, "sampleCamera", ["cameraUv"]]]]],
+      externalNames: ["add", "mul", "d", "mirrorSign", "mirrorOffset", "cropLayout", "div", "sub", "sampleCamera"]
+    },
+    externals: () => {
+      return {
+        add,
+        mul,
+        d,
+        mirrorSign,
+        mirrorOffset,
+        cropLayout,
+        div,
+        sub,
+        sampleCamera
+      };
+    }
+  }) && $.f)({})).$name('fragmentMain');
+}
+
+/** Options for {@link createCameraPassthroughPipeline}. */
+
+/**
+ * A ready-made full-screen camera→target render pipeline. Build once at setup with
+ * {@link createCameraPassthroughPipeline}; every field is safe to capture into the frame worklet.
+ *
+ * @group WebGPU
+ */
+
+/**
+ * Resolves the passthrough shader to WGSL: the raw camera-texture declarations (which TypeGPU
+ * cannot emit) followed by the TGSL-authored vertex + fragment functions, `sampleCamera`, and the
+ * `FrameCropParams` struct + crop uniform.
+ */
+function buildPassthroughShaderCode(cameraShaderBindings, mirror) {
+  const resolved = tgpu.resolve({
+    externals: {
+      vertexMain,
+      fragmentMain: makeFragmentMain(mirror)
+    },
+    names: 'strict'
+  });
+  return `${cameraShaderBindings.bindingDeclarations}\n${resolved}`;
+}
+
+/**
+ * Builds the full-screen camera passthrough pipeline: crop/orientation via {@link FrameCrop},
+ * platform-correct camera sampling, one triangle. Use it to publish the camera through the WebGPU
+ * tier with zero WGSL of your own, or as the base pass under your overlay passes.
+ *
+ * @group WebGPU
+ */
+export function createCameraPassthroughPipeline(device, options = {}) {
+  const outputFormat = options.outputFormat ?? getOutputSurfaceFormat();
+  const cameraShaderBindings = createCameraShaderBindings(device, {
+    bindGroupIndex: CAMERA_BIND_GROUP_INDEX
+  });
+  const cropBindGroupLayout = device.createBindGroupLayout({
+    label: 'fishjam-camera-passthrough-crop',
+    entries: [{
+      binding: 0,
+      visibility: GPUShaderStage.FRAGMENT,
+      buffer: {
+        type: 'uniform'
+      }
+    }]
+  });
+  const cropParamsBuffer = /*#__PURE__*/(globalThis.__TYPEGPU_AUTONAME__ ?? (a => a))(device.createBuffer({
+    label: 'fishjam-camera-passthrough-crop-params',
+    size: FRAME_CROP_BUFFER_BYTES,
+    usage: GPUBufferUsage.UNIFORM | GPUBufferUsage.COPY_DST
+  }), "cropParamsBuffer");
+  const cropBindGroup = device.createBindGroup({
+    layout: cropBindGroupLayout,
+    entries: [{
+      binding: 0,
+      resource: {
+        buffer: cropParamsBuffer
+      }
+    }]
+  });
+  const shaderModule = device.createShaderModule({
+    label: 'fishjam-camera-passthrough',
+    code: buildPassthroughShaderCode(cameraShaderBindings, options.mirror ?? false)
+  });
+  const bindGroupLayouts = [];
+  bindGroupLayouts[CROP_BIND_GROUP_INDEX] = cropBindGroupLayout;
+  bindGroupLayouts[CAMERA_BIND_GROUP_INDEX] = cameraShaderBindings.bindGroupLayout;
+  const pipeline = /*#__PURE__*/(globalThis.__TYPEGPU_AUTONAME__ ?? (a => a))(device.createRenderPipeline({
+    label: 'fishjam-camera-passthrough',
+    layout: device.createPipelineLayout({
+      bindGroupLayouts
+    }),
+    vertex: {
+      module: shaderModule,
+      entryPoint: 'vertexMain'
+    },
+    fragment: {
+      module: shaderModule,
+      entryPoint: 'fragmentMain',
+      targets: [{
+        format: outputFormat
+      }]
+    },
+    primitive: {
+      topology: 'triangle-list'
+    }
+  }), "pipeline");
+  return {
+    pipeline,
+    cameraShaderBindings,
+    cropParamsBuffer,
+    cropBindGroup
+  };
+}
+
+/**
+ * Encodes one full-screen pass drawing the camera into `outputView`, cropped per `crop`.
+ * Worklet-safe; call it inside your render callback, and encode any overlay passes after it on
+ * the same command encoder (with `loadOp: 'load'` so they draw on top).
+ *
+ * At most one call per pipeline instance per frame: the crop lives in a single uniform buffer
+ * written via `queue.writeBuffer`, which lands before the submitted command buffer executes — a
+ * second call in the same frame makes both draws use the second crop. Encode to multiple targets
+ * with different crops by building one pipeline per target.
+ *
+ * @group WebGPU
+ */
+export function encodeCameraPassthrough(device, passthrough, cameraTexture, outputView, commandEncoder, crop) {
+  'worklet';
+
+  device.queue.writeBuffer(passthrough.cropParamsBuffer, 0, packFrameCropParams(crop));
+  const cameraBindGroup = createCameraBindGroup(device, passthrough.cameraShaderBindings, cameraTexture);
+  const pass = commandEncoder.beginRenderPass({
+    colorAttachments: [{
+      view: outputView,
+      loadOp: 'clear',
+      storeOp: 'store',
+      clearValue: [0, 0, 0, 1]
+    }]
+  });
+  pass.setPipeline(passthrough.pipeline);
+  pass.setBindGroup(CROP_BIND_GROUP_INDEX, passthrough.cropBindGroup);
+  pass.setBindGroup(CAMERA_BIND_GROUP_INDEX, cameraBindGroup);
+  pass.draw(3);
+  pass.end();
+}
+//# sourceMappingURL=cameraPassthroughPipeline.js.map

package/dist/module/webgpu/cameraPassthroughPipeline.js.map

@@ -0,0 +1 @@
+{"version":3,"names":["GPUBufferUsage","GPUShaderStage","tgpu","d","add","div","mul","sub","createCameraBindGroup","createCameraShaderBindings","sampleCamera","FrameCropParams","packFrameCropParams","getOutputSurfaceFormat","CROP_BIND_GROUP_INDEX","CAMERA_BIND_GROUP_INDEX","FRAME_CROP_BUFFER_BYTES","sizeOf","cropLayout","globalThis","__TYPEGPU_AUTONAME__","a","bindGroupLayout","cropParams","uniform","vertexMain","vertexFn","in","vertexIndex","builtin","out","position","uv","location","vec2f","$","__TYPEGPU_META__","WeakMap","set","f","input","positions","vec4f","x","y","v","name","undefined","ast","params","type","body","externalNames","externals","$name","makeFragmentMain","mirror","mirrorSign","mirrorOffset","fragmentFn","screenUv","cropUv","cp","sourcePixel","cropOrigin","cropSize","sourceUv","sourceSize","cameraUv","uvTransform","buildPassthroughShaderCode","cameraShaderBindings","resolved","resolve","fragmentMain","names","bindingDeclarations","createCameraPassthroughPipeline","device","options","outputFormat","bindGroupIndex","cropBindGroupLayout","createBindGroupLayout","label","entries","binding","visibility","FRAGMENT","buffer","cropParamsBuffer","createBuffer","size","usage","UNIFORM","COPY_DST","cropBindGroup","createBindGroup","layout","resource","shaderModule","createShaderModule","code","bindGroupLayouts","pipeline","createRenderPipeline","createPipelineLayout","vertex","module","entryPoint","fragment","targets","format","primitive","topology","encodeCameraPassthrough","passthrough","cameraTexture","outputView","commandEncoder","crop","queue","writeBuffer","cameraBindGroup","pass","beginRenderPass","colorAttachments","view","loadOp","storeOp","clearValue","setPipeline","setBindGroup","draw","end"],"sources":["cameraPassthroughPipeline.ts"],"sourcesContent":["import { GPUBufferUsage, GPUShaderStage } from 'react-native-webgpu';\nimport tgpu from 'typegpu';\nimport * as d from 'typegpu/data';\nimport { add, div, mul, sub } from 'typegpu/std';\n\nimport {\n  type CameraShaderBindings,\n  createCameraBindGroup,\n  createCameraShaderBindings,\n  sampleCamera,\n} from './cameraShaderBindings';\nimport { type FrameCrop, FrameCropParams, packFrameCropParams } from './cropUtilities';\nimport { getOutputSurfaceFormat } from './requiredFeatures';\n\n// Crop is a plain uniform, so it is authored in TGSL and TypeGPU assigns it @group(0). The camera\n// is a `texture_external`, which TypeGPU cannot resolve in a shader, so its bindings are raw WGSL\n// and go at @group(1) (see cameraShaderBindings). This is a group swap from the pre-TGSL shader\n// (which had camera at 0, crop at 1) but is otherwise identical.\nconst CROP_BIND_GROUP_INDEX = 0;\nconst CAMERA_BIND_GROUP_INDEX = 1;\n\nconst FRAME_CROP_BUFFER_BYTES = d.sizeOf(FrameCropParams);\n\n// TypeGPU bind group layout for the crop uniform — the source of truth for the WGSL declaration\n// and for the fragment's typed access to `cropParams`.\nconst cropLayout = tgpu.bindGroupLayout({ cropParams: { uniform: FrameCropParams } });\n\n// One oversized triangle covering the viewport; uv spans [0,1] top-left origin over the visible\n// area.\nconst vertexMain = tgpu\n  .vertexFn({\n    in: { vertexIndex: d.builtin.vertexIndex },\n    out: { position: d.builtin.position, uv: d.location(0, d.vec2f) },\n  })((input) => {\n    const positions = [d.vec2f(-1, -1), d.vec2f(3, -1), d.vec2f(-1, 3)];\n    const position = positions[input.vertexIndex];\n    return {\n      position: d.vec4f(position.x, position.y, 0, 1),\n      uv: d.vec2f((position.x + 1) * 0.5, 1 - (position.y + 1) * 0.5),\n    };\n  })\n  .$name('vertexMain');\n\n// The fragment applies the FrameCropParams crop + orientation transform and samples the camera via\n// sampleCamera(). Mirroring is folded into a build-time sign/offset on uv.x (mirror → 1 - x) so the\n// shader stays branch-free.\nfunction makeFragmentMain(mirror: boolean) {\n  const mirrorSign = mirror ? -1 : 1;\n  const mirrorOffset = mirror ? 1 : 0;\n  return tgpu\n    .fragmentFn({ in: { screenUv: d.location(0, d.vec2f) }, out: d.vec4f })((input) => {\n      // cropUv = (mirrorSign * screenUv.x + mirrorOffset, screenUv.y), expressed with vector ops\n      // so mirrorSign/mirrorOffset fold to literals and the WGSL stays branch-free.\n      const cropUv = add(mul(input.screenUv, d.vec2f(mirrorSign, 1)), d.vec2f(mirrorOffset, 0));\n      const cp = cropLayout.$.cropParams;\n      const sourcePixel = add(cp.cropOrigin, mul(cropUv, cp.cropSize));\n      const sourceUv = div(sourcePixel, d.vec2f(cp.sourceSize));\n      const cameraUv = add(mul(cp.uvTransform, sub(sourceUv, d.vec2f(0.5))), d.vec2f(0.5));\n      return sampleCamera(cameraUv);\n    })\n    .$name('fragmentMain');\n}\n\n/** Options for {@link createCameraPassthroughPipeline}. */\nexport interface CameraPassthroughPipelineOptions {\n  /** Render-target format. Defaults to {@link getOutputSurfaceFormat} (the Fishjam output surface). */\n  outputFormat?: GPUTextureFormat;\n  /** Mirror the camera horizontally (the usual selfie self-view convention). Defaults to `false`. */\n  mirror?: boolean;\n}\n\n/**\n * A ready-made full-screen camera→target render pipeline. Build once at setup with\n * {@link createCameraPassthroughPipeline}; every field is safe to capture into the frame worklet.\n *\n * @group WebGPU\n */\nexport interface CameraPassthroughPipeline {\n  readonly pipeline: GPURenderPipeline;\n  /** The camera shader bindings the pipeline samples through. */\n  readonly cameraShaderBindings: CameraShaderBindings;\n  /** Uniform buffer holding the packed FrameCropParams; written by {@link encodeCameraPassthrough}. */\n  readonly cropParamsBuffer: GPUBuffer;\n  /** Static bind group with the crop uniform. */\n  readonly cropBindGroup: GPUBindGroup;\n}\n\n/**\n * Resolves the passthrough shader to WGSL: the raw camera-texture declarations (which TypeGPU\n * cannot emit) followed by the TGSL-authored vertex + fragment functions, `sampleCamera`, and the\n * `FrameCropParams` struct + crop uniform.\n */\nfunction buildPassthroughShaderCode(cameraShaderBindings: CameraShaderBindings, mirror: boolean): string {\n  const resolved = tgpu.resolve({\n    externals: { vertexMain, fragmentMain: makeFragmentMain(mirror) },\n    names: 'strict',\n  });\n  return `${cameraShaderBindings.bindingDeclarations}\\n${resolved}`;\n}\n\n/**\n * Builds the full-screen camera passthrough pipeline: crop/orientation via {@link FrameCrop},\n * platform-correct camera sampling, one triangle. Use it to publish the camera through the WebGPU\n * tier with zero WGSL of your own, or as the base pass under your overlay passes.\n *\n * @group WebGPU\n */\nexport function createCameraPassthroughPipeline(\n  device: GPUDevice,\n  options: CameraPassthroughPipelineOptions = {},\n): CameraPassthroughPipeline {\n  const outputFormat = options.outputFormat ?? getOutputSurfaceFormat();\n  const cameraShaderBindings = createCameraShaderBindings(device, { bindGroupIndex: CAMERA_BIND_GROUP_INDEX });\n\n  const cropBindGroupLayout = device.createBindGroupLayout({\n    label: 'fishjam-camera-passthrough-crop',\n    entries: [{ binding: 0, visibility: GPUShaderStage.FRAGMENT, buffer: { type: 'uniform' } }],\n  });\n  const cropParamsBuffer = device.createBuffer({\n    label: 'fishjam-camera-passthrough-crop-params',\n    size: FRAME_CROP_BUFFER_BYTES,\n    usage: GPUBufferUsage.UNIFORM | GPUBufferUsage.COPY_DST,\n  });\n  const cropBindGroup = device.createBindGroup({\n    layout: cropBindGroupLayout,\n    entries: [{ binding: 0, resource: { buffer: cropParamsBuffer } }],\n  });\n\n  const shaderModule = device.createShaderModule({\n    label: 'fishjam-camera-passthrough',\n    code: buildPassthroughShaderCode(cameraShaderBindings, options.mirror ?? false),\n  });\n  const bindGroupLayouts: GPUBindGroupLayout[] = [];\n  bindGroupLayouts[CROP_BIND_GROUP_INDEX] = cropBindGroupLayout;\n  bindGroupLayouts[CAMERA_BIND_GROUP_INDEX] = cameraShaderBindings.bindGroupLayout;\n  const pipeline = device.createRenderPipeline({\n    label: 'fishjam-camera-passthrough',\n    layout: device.createPipelineLayout({ bindGroupLayouts }),\n    vertex: { module: shaderModule, entryPoint: 'vertexMain' },\n    fragment: {\n      module: shaderModule,\n      entryPoint: 'fragmentMain',\n      targets: [{ format: outputFormat }],\n    },\n    primitive: { topology: 'triangle-list' },\n  });\n\n  return { pipeline, cameraShaderBindings, cropParamsBuffer, cropBindGroup };\n}\n\n/**\n * Encodes one full-screen pass drawing the camera into `outputView`, cropped per `crop`.\n * Worklet-safe; call it inside your render callback, and encode any overlay passes after it on\n * the same command encoder (with `loadOp: 'load'` so they draw on top).\n *\n * At most one call per pipeline instance per frame: the crop lives in a single uniform buffer\n * written via `queue.writeBuffer`, which lands before the submitted command buffer executes — a\n * second call in the same frame makes both draws use the second crop. Encode to multiple targets\n * with different crops by building one pipeline per target.\n *\n * @group WebGPU\n */\nexport function encodeCameraPassthrough(\n  device: GPUDevice,\n  passthrough: CameraPassthroughPipeline,\n  cameraTexture: GPUExternalTexture,\n  outputView: GPUTextureView,\n  commandEncoder: GPUCommandEncoder,\n  crop: FrameCrop,\n): void {\n  'worklet';\n  device.queue.writeBuffer(passthrough.cropParamsBuffer, 0, packFrameCropParams(crop));\n  const cameraBindGroup = createCameraBindGroup(device, passthrough.cameraShaderBindings, cameraTexture);\n  const pass = commandEncoder.beginRenderPass({\n    colorAttachments: [{ view: outputView, loadOp: 'clear', storeOp: 'store', clearValue: [0, 0, 0, 1] }],\n  });\n  pass.setPipeline(passthrough.pipeline);\n  pass.setBindGroup(CROP_BIND_GROUP_INDEX, passthrough.cropBindGroup);\n  pass.setBindGroup(CAMERA_BIND_GROUP_INDEX, cameraBindGroup);\n  pass.draw(3);\n  pass.end();\n}\n"],"mappings":"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","ignoreList":[]}