@displayxr/inline3d 1.11.0 → 1.12.1

package/js/inline3d-playcanvas-engine.js

@@ -0,0 +1,82 @@
+// inline3d-playcanvas-engine.js — the slice of `playcanvas` the SDK's two PlayCanvas backends use,
+// as NAMED re-exports.
+//
+// Internal. ./model and ./splat import THIS module (dynamically) instead of `import('playcanvas')`.
+// A dynamic import of the package hands back its whole namespace, and a bundler cannot know which
+// members a namespace object will be asked for — so it keeps all of them: the full engine
+// (physics, UI, audio, particles, XR, the WebGPU backend …) lands in the page's bundle. Naming
+// the members here is what lets a bundler drop everything else. The page's own `import … from
+// 'playcanvas'` still resolves to the SAME module instance, so entities a page adds under
+// `handle.engine.root` are the engine's own types.
+//
+// Adding an engine member to either adapter? Add it here too; test/playcanvas-engine.test.mjs
+// fails on a `pc.X` the adapters read that this list does not export.
+export {
+  // app + device
+  AppBase,
+  AppOptions,
+  createGraphicsDevice,
+  DEVICETYPE_WEBGL2,
+  RESOLUTION_FIXED,
+  // component systems + resource handlers (PLAYCANVAS_SYSTEMS / PLAYCANVAS_HANDLERS)
+  CameraComponentSystem,
+  GSplatComponentSystem,
+  RenderComponentSystem,
+  LightComponentSystem,
+  AnimComponentSystem,
+  TextureHandler,
+  GSplatHandler,
+  ContainerHandler,
+  // scene graph + cameras
+  Entity,
+  GraphNode,
+  Camera,
+  RenderView,
+  Asset,
+  Color,
+  Vec4,
+  Quat,
+  LAYERID_SKYBOX,
+  LAYERID_UI,
+  // materials / meshes (the edge feather)
+  Mesh,
+  MeshInstance,
+  ShaderMaterial,
+  BlendState,
+  BLENDEQUATION_ADD,
+  BLENDMODE_SRC_ALPHA,
+  BLENDMODE_ZERO,
+  BLENDMODE_ONE,
+  BLENDMODE_ONE_MINUS_SRC_ALPHA,
+  CULLFACE_NONE,
+  SEMANTIC_POSITION,
+  SEMANTIC_TEXCOORD0,
+  ShaderChunks,
+  SHADERLANGUAGE_GLSL,
+  // setSource's frame snapshot
+  RenderTarget,
+  FILTER_NEAREST,
+  // splats
+  WORKBUFFER_UPDATE_ALWAYS,
+  WORKBUFFER_UPDATE_ONCE,
+  // tone mapping (TONE_MAPPINGS)
+  TONEMAP_NONE,
+  TONEMAP_LINEAR,
+  TONEMAP_NEUTRAL,
+  TONEMAP_ACES,
+  TONEMAP_ACES2,
+  TONEMAP_FILMIC,
+  TONEMAP_HEJL,
+  // lighting (./model)
+  Texture,
+  EnvLighting,
+  PIXELFORMAT_RGBA8,
+  TEXTURETYPE_RGBE,
+  TEXTUREPROJECTION_EQUIRECT,
+  ADDRESS_REPEAT,
+  ADDRESS_CLAMP_TO_EDGE,
+  // compressed glTF (./model)
+  dracoInitialize,
+  basisInitialize,
+  version,
+} from 'playcanvas';

package/js/inline3d-splat-playcanvas.js

@@ -84,6 +84,8 @@ import {
   streamedBytesError,
   resolveControls,
   normalizeCameraPose,
+  coverageExponent,
+  FADE_TRANSMITTANCE_FLOOR,
 } from './inline3d-splat-shared.js';
 
 /**
@@ -145,6 +147,17 @@ const PAGE_POSE_ERROR =
 
 const DEG = Math.PI / 180;
 
+/** Tone-mapping names the viewer takes → the engine's constant names. */
+export const TONE_MAPPINGS = Object.freeze({
+  none: 'TONEMAP_NONE',
+  linear: 'TONEMAP_LINEAR',
+  neutral: 'TONEMAP_NEUTRAL',
+  aces: 'TONEMAP_ACES',
+  aces2: 'TONEMAP_ACES2',
+  filmic: 'TONEMAP_FILMIC',
+  hejl: 'TONEMAP_HEJL',
+});
+
 // ── pure matrix arithmetic (column-major, the layout XRView, three and the engine all use) ──
 
 /** three's `Matrix4.makePerspective(left, right, top, bottom, near, far)`, element for element. */
@@ -606,6 +619,7 @@ export class PlayCanvasSplatViewer {
       farClip,
       sky = false,
       pageCamera = false,
+      toneMapping = 'none',
     } = opts;
     this.canvas = canvas;
     // controls:'page': the PAGE owns the camera (setPageCamera). No orbit, no idle, no fit; the
@@ -620,6 +634,10 @@ export class PlayCanvasSplatViewer {
     // hidden (mid-setSource, or a page showing only its meshes). The SDK's contract is a
     // transparent canvas the page shows through, so the sky layer is off unless asked for.
     this.sky = sky === true;
+    // The eye camera's tone mapping, by name (the engine constant is looked up once the engine has
+    // loaded). 'none' for splats — their colours are already display-referred; ./model's mesh
+    // tiles pass 'neutral' (Khronos PBR Neutral), the glTF Sample Viewer's default.
+    this.toneMapping = toneMapping;
     // Depth range for a MIXED scene (meshes under handle.engine.root depth-test against each
     // other; splats only test against them). The projections' own near/far stay the adapter's —
     // these only raise the near (floor) and lower the far (cap). Unset: untouched.
@@ -637,6 +655,10 @@ export class PlayCanvasSplatViewer {
     this.onCaptureFov = null;
     /** Per-frame hooks, `(tMs) => boolean` — return false to be removed. setSource's crossfade. */
     this._hooks = [];
+    /** captureFrame() callers waiting for the next drawn frame. */
+    this._captureWaiters = [];
+    /** The crossfade's frame snapshot: { w, h, tex, rt, mi, mat } once captured. */
+    this._snap = null;
     this.vH = virtualDisplayHeight;
     this.fit = fit;
     this.margin = margin;
@@ -952,6 +974,10 @@ export class PlayCanvasSplatViewer {
     if (this._ro) this._ro.disconnect();
     else if (typeof removeEventListener === 'function') removeEventListener('resize', this._onResize);
     this._unbindOrbit();
+    for (const w of this._captureWaiters.splice(0)) {
+      clearTimeout(w.timer);
+      w.resolve(false);
+    }
     try {
       this.app?.destroy();
     } catch (err) {
@@ -972,13 +998,15 @@ export class PlayCanvasSplatViewer {
    * @param {object} o.perf  the resolved playcanvasPerfSettings().
    * @param {string} [o.viewPath]  force 'cameras' | 'renderview' (diagnostics).
    */
-  async attachEngine(pc, { preserveDrawingBuffer = false, perf, viewPath } = {}) {
+  async attachEngine(pc, { preserveDrawingBuffer = false, perf, viewPath, antialias = false, patchSplats = true } = {}) {
     this.pc = pc;
     const device = await pc.createGraphicsDevice(this.canvas, {
       deviceTypes: [pc.DEVICETYPE_WEBGL2],
       alpha: true,
       premultipliedAlpha: true,
-      antialias: false,
+      // Off for splats (alpha-blended quads gain nothing from MSAA); ./model turns it on, as
+      // three's SceneViewer has it, because mesh silhouettes alias visibly without it.
+      antialias,
       xrCompatible: false,
       preserveDrawingBuffer,
     });
@@ -1022,10 +1050,12 @@ export class PlayCanvasSplatViewer {
     // Footprint fix (§ patchGsplatFootprint) and the perf quad-extent cap, both as chunk
     // overrides. The gsplat chunks are registered by GSplatComponentSystem during init, so
     // after it; before any gsplat material compiles.
-    const chunks = pc.ShaderChunks.get(device, pc.SHADERLANGUAGE_GLSL);
-    const corner = patchGsplatFootprint(chunks.get('gsplatCornerVS'));
+    // ./model passes patchSplats:false: its subject is a mesh, and a page adding a splat under
+    // handle.engine.root on a model tile gets the engine's stock footprint (documented).
+    const chunks = patchSplats ? pc.ShaderChunks.get(device, pc.SHADERLANGUAGE_GLSL) : null;
+    const corner = chunks ? patchGsplatFootprint(chunks.get('gsplatCornerVS')) : { ok: false, skipped: true };
     if (corner.ok) chunks.set('gsplatCornerVS', corner.src);
-    else if (!warnedFootprint) {
+    else if (!corner.skipped && !warnedFootprint) {
       warnedFootprint = true;
       console.warn(
         '[inline3d/splat] engine:playcanvas — this engine build does not have the gsplatCornerVS ' +
@@ -1035,7 +1065,7 @@ export class PlayCanvasSplatViewer {
       );
     }
     this.footprintPatched = corner.ok;
-    if (perf?.quadExtent) {
+    if (chunks && perf?.quadExtent) {
       const q = patchPlayCanvasQuadExtent(chunks.get('gsplatCommonVS'), perf.quadExtent);
       if (q.ok) chunks.set('gsplatCommonVS', q.src);
       else if (!warnedQuadExtent) {
@@ -1157,8 +1187,152 @@ export class PlayCanvasSplatViewer {
     if (this.app.scene.gsplat.splatBudget !== per) this.app.scene.gsplat.splatBudget = per;
   }
 
+  /**
+   * Copy the frame just drawn (the whole buffer: both eyes in 3D) into a texture, on the next
+   * drawn frame. Resolves true once copied, false if no frame is drawn within `timeoutMs` (a
+   * hidden tab) or the engine cannot copy. setSource's crossfade (FRAME_SNAPSHOT).
+   */
+  captureFrame(timeoutMs = 250) {
+    return new Promise((resolve) => {
+      if (!this.app || this._disposed || !this.pc?.RenderTarget) return resolve(false);
+      const waiter = { resolve, timer: 0 };
+      waiter.timer = setTimeout(() => {
+        const i = this._captureWaiters.indexOf(waiter);
+        if (i >= 0) this._captureWaiters.splice(i, 1);
+        resolve(false);
+      }, timeoutMs);
+      this._captureWaiters.push(waiter);
+    });
+  }
+
+  _doCapture() {
+    const run = this._captureWaiters.splice(0);
+    let ok = false;
+    try {
+      const pc = this.pc;
+      const device = this.app.graphicsDevice;
+      const w = this.canvas.width;
+      const h = this.canvas.height;
+      let s = this._snap;
+      if (!s || s.w !== w || s.h !== h) {
+        this._destroySnapshot();
+        const tex = new pc.Texture(device, {
+          name: 'inline3d-snapshot',
+          width: w,
+          height: h,
+          format: pc.PIXELFORMAT_RGBA8,
+          mipmaps: false,
+          minFilter: pc.FILTER_NEAREST,
+          magFilter: pc.FILTER_NEAREST,
+          addressU: pc.ADDRESS_CLAMP_TO_EDGE,
+          addressV: pc.ADDRESS_CLAMP_TO_EDGE,
+        });
+        s = this._snap = { w, h, tex, rt: new pc.RenderTarget({ colorBuffer: tex, depth: false }), parts: null };
+      }
+      // null source = the back buffer, still holding this frame (same task, before compositing).
+      ok = device.copyRenderTarget(null, s.rt, true, false) !== false;
+      if (ok) this._ensureSnapshotOverlay();
+    } catch (err) {
+      console.warn('[inline3d/splat] frame snapshot failed; the crossfade falls back to one pass', err);
+      ok = false;
+    }
+    for (const w of run) {
+      clearTimeout(w.timer);
+      w.resolve(ok);
+    }
+  }
+
+  /**
+   * FRAME_SNAPSHOT: the captured frame lerped with the live scene, in two clip-space quads in the
+   * UI layer (under the edge feather), drawn once per view like the feather. Each samples the
+   * capture at gl_FragCoord, so an eye's viewport reads its own half. Quad 1 scales what the scene
+   * drew by (1 − α) (blend ZERO / SRC_ALPHA, colour AND alpha); quad 2 adds α·A (ONE / ONE). The
+   * result is the plain lerp of the two premultiplied images, `α·A + (1 − α)·B` — alpha included,
+   * so a region only one of the two photos covers fades against the page, not against black.
+   */
+  _ensureSnapshotOverlay() {
+    const s = this._snap;
+    if (s.parts) {
+      for (const p of s.parts) {
+        p.mat.setParameter('dxrSnap', s.tex);
+        p.mat.setParameter('dxrSnapInvSize', [1 / s.w, 1 / s.h]);
+        p.mat.update();
+      }
+      return;
+    }
+    const pc = this.pc;
+    const mesh = new pc.Mesh(this.app.graphicsDevice);
+    mesh.setPositions(new Float32Array([-1, -1, 0, 1, -1, 0, 1, 1, 0, -1, 1, 0]));
+    mesh.setIndices([0, 1, 2, 0, 2, 3]);
+    mesh.update();
+    const part = (name, body, src, dst, drawOrder) => {
+      const mat = new pc.ShaderMaterial({
+        uniqueName: name,
+        attributes: { vertex_position: pc.SEMANTIC_POSITION },
+        vertexGLSL: `
+        attribute vec3 vertex_position;
+        void main() { gl_Position = vec4(vertex_position.xy, 0.0, 1.0); }`,
+        fragmentGLSL: `
+        uniform sampler2D dxrSnap;
+        uniform vec2 dxrSnapInvSize;
+        uniform float dxrSnapAlpha;
+        void main() { ${body} }`,
+      });
+      mat.blendState = new pc.BlendState(true, pc.BLENDEQUATION_ADD, src, dst, pc.BLENDEQUATION_ADD, src, dst);
+      mat.depthTest = false;
+      mat.depthWrite = false;
+      mat.cull = pc.CULLFACE_NONE;
+      mat.setParameter('dxrSnap', s.tex);
+      mat.setParameter('dxrSnapInvSize', [1 / s.w, 1 / s.h]);
+      mat.setParameter('dxrSnapAlpha', 0);
+      mat.update();
+      const mi = new pc.MeshInstance(mesh, mat, new pc.GraphNode(name));
+      mi.cull = false;
+      mi.drawOrder = drawOrder; // both before the edge feather (drawOrder 0)
+      mi.visible = false;
+      return { mat, mi };
+    };
+    s.parts = [
+      part('inline3dSnapshotScale', 'gl_FragColor = vec4(0.0, 0.0, 0.0, 1.0 - dxrSnapAlpha);', pc.BLENDMODE_ZERO, pc.BLENDMODE_SRC_ALPHA, -2),
+      part('inline3dSnapshotAdd', 'gl_FragColor = texture2D(dxrSnap, gl_FragCoord.xy * dxrSnapInvSize) * dxrSnapAlpha;', pc.BLENDMODE_ONE, pc.BLENDMODE_ONE, -1),
+    ];
+    this.app.scene.layers.getLayerById(pc.LAYERID_UI).addMeshInstances(s.parts.map((p) => p.mi));
+  }
+
+  /**
+   * Lerp the snapshot over the scene at `alpha` (0 hides it). Returns false when the canvas buffer
+   * no longer matches the capture (resize, 2D/3D switch): the caller ends its fade.
+   */
+  setSnapshotAlpha(alpha) {
+    const s = this._snap;
+    if (!s?.parts) return false;
+    const fits = s.w === this.canvas.width && s.h === this.canvas.height;
+    const show = alpha > 0 && fits;
+    for (const p of s.parts) {
+      p.mi.visible = show;
+      if (show) {
+        p.mat.setParameter('dxrSnapAlpha', Math.min(1, alpha));
+        p.mat.update();
+      }
+    }
+    return alpha <= 0 || fits;
+  }
+
+  _destroySnapshot() {
+    const s = this._snap;
+    if (!s) return;
+    this._snap = null;
+    if (s.parts) {
+      this.app?.scene?.layers?.getLayerById(this.pc.LAYERID_UI)?.removeMeshInstances?.(s.parts.map((p) => p.mi));
+      s.parts[0].mi.mesh?.destroy?.();
+    }
+    s.rt?.destroy?.();
+    s.tex?.destroy?.();
+  }
+
   /** Read back what the tick just did. Cheap: two numbers off the renderer. */
   _afterTick() {
+    if (this._captureWaiters.length) this._doCapture();
     const n = this.app?.renderer?._gsplatCount ?? 0;
     this.resident = n;
     if (n > this.peakResident) this.peakResident = n;
@@ -1184,7 +1358,7 @@ export class PlayCanvasSplatViewer {
     // The engine's default camera tonemap is LINEAR, which routes every splat colour through
     // decodeGamma → toneMap → gammaCorrectOutput. Spark writes the stored colour straight out;
     // NONE is the same thing here (GAMMA_SRGB alone leaves a gamma-space colour untouched).
-    e.camera.toneMapping = pc.TONEMAP_NONE;
+    e.camera.toneMapping = TONE_MAPPINGS[this.toneMapping] ? pc[TONE_MAPPINGS[this.toneMapping]] ?? pc.TONEMAP_NONE : pc.TONEMAP_NONE;
     this.rigNode.addChild(e);
     return e;
   }
@@ -1800,23 +1974,48 @@ export function describeResource(res) {
 // ── the handle ──────────────────────────────────────────────────────────────────────────────
 
 /**
- * The per-splat crossfade for `setSource`: a work-buffer modifier multiplying each splat's alpha
- * by this ENTITY's `dxrFade` parameter.
+ * setSource's crossfade.
+ *
+ * The 1.11 fade multiplied each splat's alpha by t and drew both assets in ONE sorted pass. That
+ * is not a crossfade: whichever photo sits in FRONT wins. Measured on SHARP photo pairs (the blend
+ * fraction c, least squares of the frame between A-alone and B-alone): the incoming photo in front
+ * reached c = 0.64 at t = 0.2 (a snap), behind it c = 0.18 at t = 0.5 (a late pop). No per-splat
+ * alpha remap fixes that, because a pixel's coverage depends on how many splats stack there and
+ * which asset is nearer — both vary across the picture and between photos (docs/splat-effects.md
+ * §Crossfade has the numbers).
+ *
+ * FRAME_SNAPSHOT: blend IMAGES instead. The last frame of the outgoing asset (both eyes) is copied
+ * into a texture, the outgoing asset is released at once, and the incoming one is drawn untouched;
+ * two overlay quads then lerp the frozen frame with it, `out = (1 − t)·A + t·B` per premultiplied
+ * pixel, alpha included (PlayCanvasSplatViewer._ensureSnapshotOverlay). Linear by construction,
+ * whatever the depth order, coverage or framing; each eye samples its own half of the capture, so
+ * the eyes stay consistent. End state: overlay hidden — exactly the untouched incoming asset.
+ * Trade-offs: the outgoing frame is frozen for the fade (camera and head motion stop for it), and
+ * the new asset's rig applies at once (each photo is seen through its own rig).
  *
- * Per entity, not per material: the engine's unified renderer composites every splat of a tile
- * through ONE material and ONE work buffer, so a material uniform cannot tell the outgoing asset
- * from the incoming one. `setWorkBufferModifier` + `setParameter` is the engine's supported
- * per-component hook for exactly this; during a fade the work buffer is re-rendered each frame
- * (WORKBUFFER_UPDATE_ALWAYS), and the modifier is removed when the fade ends.
+ * Fallback (no frame drawn within 250 ms — a hidden tab — or no copy on this engine build): the
+ * one-pass fade, with the coverage-linear alpha remap on both assets.
+ */
+
+/**
+ * Per-entity work-buffer modifier: each splat's alpha becomes `1 − (1 − α)^k`, k = `dxrFade`
+ * (coverageExponent). Per entity, not per material: the unified renderer composites every splat of
+ * a tile through ONE material, so only `setWorkBufferModifier` + `setParameter` can tell the two
+ * assets apart. During a fade the work buffer re-renders each frame (WORKBUFFER_UPDATE_ALWAYS);
+ * the modifier is removed when the fade ends. The transmittance floor keeps a fully opaque splat
+ * (SOG alpha 255/255, common in photos) fadeable at all: pow(0, k) is 0 for every k.
  */
 const FADE_MODIFIER_GLSL = `
 uniform float dxrFade;
 void modifySplatCenter(inout vec3 center) {}
 void modifySplatRotationScale(vec3 originalCenter, vec3 modifiedCenter, inout vec4 rotation, inout vec3 scale) {}
-void modifySplatColor(vec3 center, inout vec4 color) { color.a *= dxrFade; }
+void modifySplatColor(vec3 center, inout vec4 color) {
+  if (dxrFade >= 1.0) return;
+  color.a = dxrFade <= 0.0 ? 0.0 : 1.0 - pow(max(1.0 - color.a, ${FADE_TRANSMITTANCE_FLOOR.toFixed(4)}), dxrFade);
+}
 `;
 
-/** Set (or clear, with null) the crossfade alpha on one splat entity. */
+/** Set (or clear, with null) the crossfade alpha exponent on one splat entity. */
 function setFade(pc, entity, value) {
   const g = entity?.gsplat;
   if (!g) return;
@@ -2415,7 +2614,9 @@ export function attachPlayCanvasSplat(out, wall, canvas, src, opts, pending = []
 
   let pcModule = null;
   const booted = (async () => {
-    const pc = opts.playcanvas || (await import('playcanvas'));
+    // Named re-exports, not the package namespace: lets a bundler drop the ~40% of the engine the
+    // SDK never touches (./inline3d-playcanvas-engine.js).
+    const pc = opts.playcanvas || (await import('./inline3d-playcanvas-engine.js'));
     if (removed) return null;
     const app = await viewer.attachEngine(pc, {
       preserveDrawingBuffer,
@@ -2474,9 +2675,19 @@ export function attachPlayCanvasSplat(out, wall, canvas, src, opts, pending = []
       return out;
     }
     const prev = current;
-    const entity = viewer.addSplatAsset(loaded.asset);
     const fade = Number.isFinite(fadeMs) && fadeMs > 0 ? fadeMs : 0;
-    if (fade && prev) setFade(pc, entity, 0);
+    pendingSwap?.finish();
+    // FRAME_SNAPSHOT: freeze the outgoing frame BEFORE anything of the new asset (or its rig) is
+    // drawn. The overlay goes up in the same task, so no frame shows neither photo.
+    const snapped = fade && prev ? await viewer.captureFrame() : false;
+    if (removed || gen !== sourceGen) {
+      app.assets.remove(loaded.asset);
+      loaded.asset.unload?.();
+      return out;
+    }
+    if (snapped) viewer.setSnapshotAlpha(1);
+    const entity = viewer.addSplatAsset(loaded.asset);
+    if (fade && prev && !snapped) setFade(pc, entity, 0);
     out.mesh = {
       numSplats: loaded.desc.numSplats || loaded.cloud?.sourceTotal || 0,
       entity,
@@ -2506,7 +2717,8 @@ export function attachPlayCanvasSplat(out, wall, canvas, src, opts, pending = []
       release();
       return out;
     }
-    pendingSwap?.finish();
+    if (snapped) release(); // the snapshot shows it from here on
+    else setFade(pc, prev.entity, 1);
     await new Promise((resolve) => {
       // The fade clock starts on the SECOND tick after the swap, not now: the first frame that
       // draws the new asset also builds its work buffer (hundreds of ms for a 1M-splat file), and
@@ -2515,21 +2727,31 @@ export function attachPlayCanvasSplat(out, wall, canvas, src, opts, pending = []
       let t0 = null;
       let ticks = 0;
       const finish = () => {
-        setFade(pc, entity, null);
-        release();
+        if (snapped) viewer.setSnapshotAlpha(0);
+        else {
+          setFade(pc, entity, null);
+          release();
+        }
         pendingSwap = null;
         resolve();
       };
       pendingSwap = { finish };
-      setFade(pc, prev.entity, 1);
       viewer._hooks.push((t) => {
         if (removed) return (resolve(), false);
         if (pendingSwap?.finish !== finish) return false; // superseded: already finished
         if (++ticks < 2) return true;
         if (t0 === null) t0 = t;
         const k = Math.min(1, Math.max(0, (t - t0) / fade));
-        setFade(pc, entity, k);
-        setFade(pc, prev.entity, 1 - k);
+        if (snapped) {
+          // A resize or a 2D/3D switch mid-fade: the capture no longer fits the buffer — end now.
+          if (!viewer.setSnapshotAlpha(1 - k)) {
+            finish();
+            return false;
+          }
+        } else {
+          setFade(pc, entity, coverageExponent(k));
+          setFade(pc, prev.entity, coverageExponent(1 - k));
+        }
         if (k >= 1) {
           finish();
           return false;

package/js/inline3d-splat-shared.js

@@ -437,3 +437,36 @@ export function normalizeCameraPose(matrixWorld, o = {}) {
   }
   return { matrixWorld: m, verticalFovDeg: fov, near, far, convergence };
 }
+
+// ── coverage-linear alpha (setSource's crossfade, the `fade` effect) ────────────────────────────
+
+/**
+ * Nominal optical depth of a dense photo's splat stack, per pixel: −ln(transmittance) through the
+ * whole stack at rest. The remap below is exact for a pixel of optical depth `L`. Real pictures
+ * spread widely around any single value (measured 13–25 on SHARP photos), which is why the
+ * crossfade blends IMAGES (FRAME_SNAPSHOT in ./inline3d-splat-playcanvas.js) and uses this only
+ * to shape ramps — never as the thing that makes a fade linear.
+ */
+export const FADE_OPTICAL_DEPTH = 3;
+
+/**
+ * Smallest per-splat transmittance the remap works from. A fully opaque splat (SOG alpha 255/255
+ * decodes to exactly 1, common in photos) has transmittance 0, and 0^k is 0 for every k > 0 — so
+ * without a floor it could never fade at all. 0.02 caps one splat's optical depth at ~3.9.
+ */
+export const FADE_TRANSMITTANCE_FLOOR = 0.02;
+
+/**
+ * The per-splat alpha exponent `k` that puts a stack of nominal optical depth `L` at screen
+ * coverage `c` (0..1).
+ *
+ * Scaling every splat's alpha by `c` saturates: a pixel under n near-opaque splats is covered
+ * `1 − (1 − c·α)^n`. Raising each splat's transmittance to a power instead, `α' = 1 − (1 − α)^k`,
+ * multiplies the stack's optical depth by k: coverage is `1 − e^{−kL}`. Solving for coverage =
+ * c·(1 − e^{−L}) gives this k. Exact ends: k(0) = 0 (α' = 0, invisible) and k(1) = 1 (untouched).
+ */
+export function coverageExponent(c, L = FADE_OPTICAL_DEPTH) {
+  if (!(c > 0)) return 0;
+  if (c >= 1) return 1;
+  return -Math.log(1 - c * (1 - Math.exp(-L))) / L;
+}