@displayxr/inline3d 1.47.5 → 1.47.6

package/js/inline3d-pc-auto-release.js

@@ -0,0 +1,191 @@
+// inline3d-pc-auto-release.js — when a page destroys a material on one of the SDK's PlayCanvas
+// devices, release the programs it linked, without the page asking.
+//
+// Internal. PlayCanvasSplatViewer.attachEngine (./inline3d-splat-playcanvas.js) installs it on
+// every app it creates, for ./splat (engine: 'playcanvas') and ./model. docs/content-lifecycle-rules.md
+// § rule 1 has the why; `?dxrdiag=keepprograms` turns it off (A/B).
+//
+// WHY. `Material.destroy()` empties `material.variants` and destroys no program, and the engine's
+// ProgramLibrary keeps every program it linked for the device's life. A page that swaps content
+// under one live app (`entity.destroy()`, `asset.unload()`, which destroys the container's
+// materials) therefore keeps every program it ever linked: measured 0 → 170 live programs over 28
+// screen changes on a kiosk app, none deleted. `handle.releaseEntity` releases them on request;
+// this does the same for every material the page destroys, so a page that follows the engine's
+// own teardown is bounded too.
+//
+// HOW. Two methods on the engine's Material prototype, wrapped once (the prototype is shared by
+// every app on the page, so both wrappers act only on devices registered here):
+//   - getShaderVariant: the one place a material links a program. Records the material (weakly)
+//     on its device, so a live material that holds a program keeps it (step 3);
+//   - destroy: BEFORE the engine empties `variants`, collects the programs the material and its
+//     mesh instances hold, and marks the material destroyed.
+// The sweep runs once per frame that had a destroy, at the app's `frameend` (after render, so
+// content added in the same frame has drawn and holds its programs), with a timer as backup for a
+// stopped app. It destroys each collected program that nothing still uses:
+//   1. no mesh instance under `app.root` or in a layer, and no material asset in the registry
+//      (the keep set of ./inline3d-pc-release.js);
+//   2. still registered on the device (not already destroyed, e.g. by releaseEntity);
+//   3. no material that linked it is still alive. ProgramLibrary hands one Shader to every material
+//      with the same key, and a material a page keeps off-scene to show again still has it in its
+//      `variants`; destroying it under that material would leave a dead program there.
+// `Shader.destroy()` also takes the program out of the library, so a later ask for that variant
+// compiles it again. Cost: content shown again after release recompiles on its first draw
+// (`handle.warmEntity` hides that).
+
+import { liveShaders } from './inline3d-pc-release.js';
+
+const states = new WeakMap(); // device -> { app, materials:Set<WeakRef>, pending:Set, scheduled, stats }
+let patchedProto = null;
+
+const deref = (r) => (typeof r?.deref === 'function' ? r.deref() : r);
+const weak = (x) => (typeof WeakRef === 'function' ? new WeakRef(x) : x);
+
+function collect(material) {
+  const into = (s) => {
+    const st = s && states.get(s.device);
+    if (!st) return;
+    st.pending.add(s);
+    schedule(st);
+  };
+  material.variants?.forEach?.(into);
+  material.meshInstances?.forEach?.((mi) => mi?._shaderCache?.forEach?.((si) => into(si?.shader)));
+}
+
+/** Programs some still-alive material on `st`'s device has linked. Prunes dead entries. */
+function heldByLiveMaterials(st) {
+  const held = new Set();
+  for (const r of st.materials) {
+    const m = deref(r);
+    if (!m || m.__dxrDestroyed) {
+      st.materials.delete(r);
+      continue;
+    }
+    m.variants?.forEach?.((s) => s && held.add(s));
+  }
+  return held;
+}
+
+function schedule(st) {
+  if (st.scheduled) return;
+  st.scheduled = true;
+  const run = (st.run ||= () => sweep(st));
+  try {
+    st.app.once?.('frameend', run);
+  } catch {
+    /* no event system: the timer below */
+  }
+  st.timer = setTimeout(run, 1000);
+}
+
+/** Destroy every collected program nothing still uses. Returns how many. Exported for tests. */
+export function sweep(st) {
+  if (!st || !st.scheduled) return 0;
+  st.scheduled = false;
+  clearTimeout(st.timer);
+  if (st.run) st.app.off?.('frameend', st.run); // only ours: the page may listen to frameend too
+  if (!st.pending.size || st.off) {
+    st.pending.clear();
+    return 0;
+  }
+  let keep;
+  try {
+    keep = liveShaders(st.app);
+  } catch {
+    st.pending.clear(); // an app mid-teardown: it frees everything itself
+    return 0;
+  }
+  const held = heldByLiveMaterials(st);
+  let n = 0;
+  for (const s of st.pending) {
+    if (keep.has(s) || held.has(s) || typeof s.destroy !== 'function') continue;
+    const registered = s.device?.shaders;
+    if (Array.isArray(registered) && !registered.includes(s)) continue; // already destroyed
+    try {
+      s.destroy();
+      n++;
+    } catch {
+      /* a program the engine already tore down */
+    }
+  }
+  st.pending.clear();
+  st.stats.released += n;
+  st.stats.sweeps++;
+  st.onSweep?.(n);
+  return n;
+}
+
+/**
+ * The prototype has the shape this relies on (2.22.x): `getShaderVariant(params)` with
+ * `params.device`, and a `destroy()` that clears `variants`. Returns a reason string, or null.
+ */
+export function materialShapeProblem(proto) {
+  if (!proto || typeof proto.getShaderVariant !== 'function' || typeof proto.destroy !== 'function') return 'no Material.getShaderVariant/destroy';
+  const d = Function.prototype.toString.call(proto.destroy);
+  if (!/variants/.test(d)) return 'Material.destroy no longer clears variants';
+  return null;
+}
+
+/** Wrap the engine's Material prototype once. Returns 'patched' | 'already' | 'skipped: …'. */
+export function patchMaterialPrototype(proto) {
+  if (patchedProto === proto || proto?.__dxrAutoRelease) return 'already';
+  const problem = materialShapeProblem(proto);
+  if (problem) return `skipped: ${problem}`;
+  const getShaderVariant = proto.getShaderVariant;
+  const destroy = proto.destroy;
+  proto.getShaderVariant = function (params) {
+    const s = getShaderVariant.apply(this, arguments);
+    const st = states.get(params?.device ?? s?.device);
+    if (st && !this.__dxrTracked) {
+      this.__dxrTracked = true;
+      st.materials.add(weak(this));
+    }
+    return s;
+  };
+  proto.destroy = function () {
+    try {
+      collect(this);
+    } catch {
+      /* never let the release break the engine's own teardown */
+    }
+    this.__dxrDestroyed = true;
+    return destroy.apply(this, arguments);
+  };
+  proto.__dxrAutoRelease = true;
+  patchedProto = proto;
+  return 'patched';
+}
+
+/**
+ * Release the programs of destroyed materials on `app`'s device. `Material` is the engine's
+ * Material class (the one the page's own `import … from 'playcanvas'` also resolves to).
+ * The result is kept on `device.__dxrAutoRelease`.
+ */
+export function installAutoProgramRelease(app, Material) {
+  const device = app?.graphicsDevice;
+  if (!device) return null;
+  if (states.has(device)) return device.__dxrAutoRelease;
+  const patched = patchMaterialPrototype(Material?.prototype);
+  const result = patched === 'already' ? 'patched' : patched; // one prototype for every app on the page
+  device.__dxrAutoRelease = result;
+  if (result.startsWith('skipped')) return result;
+  const st = { app, materials: new Set(), pending: new Set(), scheduled: false, timer: 0, off: false, stats: { released: 0, sweeps: 0 } };
+  states.set(device, st);
+  app.once?.('destroy', () => {
+    st.off = true;
+    clearTimeout(st.timer);
+    st.pending.clear();
+    st.materials.clear();
+  });
+  return result;
+}
+
+/** Programs released on `app`'s device so far (diagnostics), or null. */
+export function autoReleaseStats(app) {
+  const st = app?.graphicsDevice && states.get(app.graphicsDevice);
+  return st ? { ...st.stats, pending: st.pending.size, materials: st.materials.size } : null;
+}
+
+/** The state for `app` (tests, and diag's per-sweep hook). */
+export function autoReleaseState(app) {
+  return (app?.graphicsDevice && states.get(app.graphicsDevice)) || null;
+}

package/js/inline3d-pc-release.js

@@ -0,0 +1,107 @@
+// inline3d-pc-release.js — handle.releaseEntity: take content a page added under
+// `handle.engine.root` out of a PlayCanvas tile and give back what it held on the GPU.
+//
+// Internal. PlayCanvasSplatViewer.releaseEntity (./inline3d-splat-playcanvas.js) calls it, for
+// both ./splat (engine: 'playcanvas') and ./model. docs/content-lifecycle-rules.md has the why.
+//
+// WHY. `entity.destroy()` and `asset.unload()` free meshes, textures and materials, but NOT the
+// shader programs those materials linked: the engine's ProgramLibrary caches every variant for
+// the device's life, and `Material.destroy()` only empties `material.variants`. A page that swaps
+// glTF content in and out (a product carousel, a catalogue) therefore keeps every program it ever
+// linked, and a desktop driver keeps the linked program's compiled IR behind each one (about 5 MB
+// per program, measured on one Linux driver). `Shader.destroy()` is the engine's own explicit
+// release: it deletes the program and drops it from the ProgramLibrary cache, so a later ask for
+// the same variant compiles it again instead of getting a dead one.
+//
+// ORDER (each step needs the one before):
+//   1. collect the programs the entity's materials hold (`variants`, and each mesh instance's own
+//      shader cache) BEFORE anything is destroyed: destroying a material empties `variants`;
+//   2. destroy the entity;
+//   3. the container (`asset`, optional): unloaded and taken out of the registry when nothing
+//      left under `app.root` draws with one of its meshes or materials, after its own materials'
+//      programs are collected too;
+//   4. destroy each collected program that nothing still in the app uses: any mesh instance under
+//      `app.root` (enabled or not), any layer's mesh instances, any material asset still in the
+//      registry. ProgramLibrary returns one Shader for one key, so two materials with the same
+//      options share a program; that is why this check exists.
+
+/** Every program `materials` hold in `variants`, added to `into`. */
+export function materialShaders(materials, into = new Set()) {
+  for (const m of materials) m?.variants?.forEach?.((s) => s && into.add(s));
+  return into;
+}
+
+/** The mesh instances of every render / model component under `entity` (itself included). */
+function meshInstancesUnder(entity) {
+  const out = [];
+  if (!entity?.findComponents) return out;
+  for (const kind of ['render', 'model']) {
+    let comps = [];
+    try {
+      comps = entity.findComponents(kind) || [];
+    } catch {
+      comps = []; // a component system the app does not have
+    }
+    for (const c of comps) for (const mi of c.meshInstances || []) if (mi) out.push(mi);
+  }
+  return out;
+}
+
+/** A mesh instance's programs: its material's variants and its own shader cache. */
+function noteMeshInstance(mi, into) {
+  mi.material?.variants?.forEach?.((s) => s && into.add(s));
+  mi._shaderCache?.forEach?.((si) => si?.shader && into.add(si.shader));
+}
+
+/** Every program something still in `app` may draw with (step 4's keep set). */
+export function liveShaders(app) {
+  const live = new Set();
+  for (const mi of meshInstancesUnder(app.root)) noteMeshInstance(mi, live);
+  for (const layer of app.scene?.layers?.layerList || []) for (const mi of layer.meshInstances || []) noteMeshInstance(mi, live);
+  for (const a of app.assets?.list?.() || []) if (a?.type === 'material' && a.resource) materialShaders([a.resource], live);
+  return live;
+}
+
+/** Does anything left under `app.root` draw with one of `container`'s meshes or materials? */
+function containerInUse(app, container) {
+  const mats = new Set((container?.materials || []).map((a) => a?.resource).filter(Boolean));
+  const meshes = new Set();
+  for (const r of container?.renders || []) for (const m of r?.resource?.meshes || []) meshes.add(m);
+  if (!mats.size && !meshes.size) return false;
+  for (const mi of meshInstancesUnder(app.root)) if (mats.has(mi.material) || meshes.has(mi.mesh)) return true;
+  return false;
+}
+
+/**
+ * Destroy `entity` and release what it held. With `asset` (the container it was instantiated
+ * from), the container too, unless something else in the app still draws from it.
+ * Returns { programs, container } — programs destroyed, and 'unloaded' | 'in-use' | null.
+ */
+export function releaseEntity(app, entity, { asset = null } = {}) {
+  const result = { programs: 0, container: null };
+  if (!app || !app.root) return result;
+  const retired = new Set();
+  if (entity) {
+    for (const mi of meshInstancesUnder(entity)) noteMeshInstance(mi, retired);
+    entity.destroy?.();
+  }
+  if (asset) {
+    const container = asset.resource;
+    if (container && containerInUse(app, container)) {
+      result.container = 'in-use';
+    } else {
+      materialShaders((container?.materials || []).map((a) => a?.resource), retired);
+      app.assets?.remove?.(asset);
+      asset.unload?.();
+      result.container = 'unloaded';
+    }
+  }
+  if (!retired.size) return result;
+  const live = liveShaders(app);
+  for (const s of retired) {
+    if (live.has(s) || typeof s.destroy !== 'function') continue;
+    s.destroy();
+    result.programs++;
+  }
+  return result;
+}

package/js/inline3d-pc-shader-cache.js

@@ -0,0 +1,172 @@
+// inline3d-pc-shader-cache.js — give PlayCanvas's compiled WebGL shaders back when the last
+// program that uses them is destroyed.
+//
+// Internal. The PlayCanvas viewer (./inline3d-splat-playcanvas.js, shared by ./splat and ./model)
+// calls installShaderCacheRelease(device) on every device it creates.
+//
+// WHY. The engine (2.22.3, src/platform/graphics/webgl/webgl-shader.js) keeps every compiled
+// vertex and fragment shader in a module-private CompiledShaderCache, keyed by source, until the
+// DEVICE is destroyed: `WebglShader.destroy()` deletes the program and nothing else. A page that
+// releases what a content swap replaces (`Shader.destroy()` on the outgoing variants, see
+// docs/content-lifecycle-rules.md) therefore still keeps two compiled shaders per program it
+// ever linked, with the driver's compiled IR behind each one. Over a long-lived page that is
+// unbounded growth in the browser's GPU process.
+//
+// WHAT THIS DOES. The engine is the page's own peer dependency (an import map, a bundler, a CDN
+// build), never a file this package ships, so it cannot be patched on disk. Instead this replaces
+// two methods on the engine's WebglShader prototype, reached through the first shader the device
+// creates:
+//   _compileShaderSource — the same lookup the engine does, in a per-device cache of its own
+//                          (keyed by source, as the engine's), plus one count per program that
+//                          took the shader;
+//   destroy              — the engine's destroy (deletes the program), then one release per
+//                          shader. The last program out deletes the shader and drops the entry, so
+//                          the next ask for that source compiles it again.
+// Context loss clears the cache (the GL objects are gone; the engine recompiles on restore), and
+// device destroy deletes whatever is still cached, as the engine's own cache does. Shaders the
+// engine compiled BEFORE the patch stay in the engine's cache and are left alone.
+//
+// ACROSS ENGINE BUMPS. The patch installs only when the prototype has the 2.22.x shape (an
+// `_compileShaderSource(device, src, isVertexShader)` that reads a `.map` keyed by source, and a
+// `destroy` that does not already delete shaders), and otherwise steps aside and says why
+// (`device.__dxrShaderCache`, and the diagnostics overlay). On an engine bump: read the new
+// webgl-shader.js; if CompiledShaderCache still never deletes a shader before device destroy, keep
+// this and update the shape check if the method moved; if upstream releases shaders itself, the
+// `deleteShader` check makes this a no-op — delete the module. test/pc-shader-cache.test.mjs
+// runs this against a copy of the 2.22.3 class shape.
+
+const PATCHED = Symbol.for('@displayxr/inline3d.shaderCacheRelease');
+
+/** The per-device cache: source → shader, per stage, and a count per shader. */
+const caches = new WeakMap();
+
+function cacheFor(device) {
+  let c = caches.get(device);
+  if (!c) {
+    c = { v: new Map(), f: new Map(), refs: new Map(), compiled: 0, deleted: 0 };
+    caches.set(device, c);
+    device.on?.('devicelost', () => {
+      c.v.clear();
+      c.f.clear();
+      c.refs.clear();
+    });
+    device.on?.('destroy', () => {
+      const gl = device.gl;
+      if (gl && !gl.isContextLost?.()) for (const s of c.refs.keys()) gl.deleteShader(s);
+      c.v.clear();
+      c.f.clear();
+      c.refs.clear();
+    });
+  }
+  return c;
+}
+
+function release(device, map, src, glShader) {
+  const c = caches.get(device);
+  if (!c || !glShader || !c.refs.has(glShader)) return false; // not ours (compiled before the patch)
+  const n = c.refs.get(glShader) - 1;
+  if (n > 0) {
+    c.refs.set(glShader, n);
+    return true;
+  }
+  c.refs.delete(glShader);
+  if (map.get(src) === glShader) map.delete(src);
+  device.gl?.deleteShader(glShader);
+  c.deleted++;
+  return true;
+}
+
+/**
+ * Why `proto` cannot take the patch, or null when it can. Exported for the test.
+ * @param {object} proto  the engine's WebglShader.prototype
+ */
+export function shaderCacheShapeProblem(proto) {
+  if (!proto || typeof proto._compileShaderSource !== 'function' || typeof proto.destroy !== 'function') return 'no WebglShader._compileShaderSource/destroy';
+  if (proto._compileShaderSource.length !== 3) return 'WebglShader._compileShaderSource has a different signature';
+  const compile = Function.prototype.toString.call(proto._compileShaderSource);
+  if (!/\.map\.get\(/.test(compile) || !/createShader\(/.test(compile)) return 'WebglShader._compileShaderSource has a different body';
+  const destroy = Function.prototype.toString.call(proto.destroy);
+  if (/deleteShader/.test(destroy)) return 'the engine already releases shaders (WebglShader.destroy deletes them)';
+  return null;
+}
+
+/** Patch the engine's WebglShader prototype once (the prototype is shared by every device). */
+export function patchWebglShaderPrototype(proto) {
+  if (proto[PATCHED]) return 'already';
+  const problem = shaderCacheShapeProblem(proto);
+  if (problem) return `skipped: ${problem}`;
+  const engineDestroy = proto.destroy;
+  proto._compileShaderSource = function (device, src, isVertexShader) {
+    const gl = device.gl;
+    if (gl.isContextLost()) return null;
+    const c = cacheFor(device);
+    const map = isVertexShader ? c.v : c.f;
+    let glShader = map.get(src);
+    if (!glShader) {
+      glShader = gl.createShader(isVertexShader ? gl.VERTEX_SHADER : gl.FRAGMENT_SHADER);
+      gl.shaderSource(glShader, src);
+      gl.compileShader(glShader);
+      map.set(src, glShader);
+      c.compiled++;
+    }
+    c.refs.set(glShader, (c.refs.get(glShader) || 0) + 1);
+    return glShader;
+  };
+  proto.destroy = function (shader) {
+    engineDestroy.call(this, shader);
+    const device = shader?.device;
+    const c = device && caches.get(device);
+    if (!c) return;
+    if (release(device, c.v, this._vsource, this.glVertexShader)) this.glVertexShader = null;
+    if (release(device, c.f, this._fsource, this.glFragmentShader)) this.glFragmentShader = null;
+  };
+  Object.defineProperty(proto, PATCHED, { value: true });
+  return 'patched';
+}
+
+/**
+ * Install the release on `device`'s shader class. Idempotent; WebGL devices only. The result is
+ * also kept on `device.__dxrShaderCache` ('patched' | 'already' | 'skipped: …' | 'pending').
+ * The prototype is reached through the first shader impl the device creates (the class is not
+ * exported), so this wraps `createShaderImpl` until it has one.
+ */
+export function installShaderCacheRelease(device) {
+  if (!device || device.__dxrShaderCache) return device?.__dxrShaderCache ?? null;
+  if (!device.isWebGL2 || typeof device.createShaderImpl !== 'function') {
+    device.__dxrShaderCache = 'skipped: not a WebGL2 device';
+    return device.__dxrShaderCache;
+  }
+  const existing = device.shaders?.find?.((s) => s?.impl);
+  if (existing) {
+    device.__dxrShaderCache = patchWebglShaderPrototype(Object.getPrototypeOf(existing.impl));
+    return device.__dxrShaderCache;
+  }
+  device.__dxrShaderCache = 'pending';
+  const create = device.createShaderImpl;
+  const ownBefore = Object.hasOwn(device, 'createShaderImpl');
+  device.createShaderImpl = function (shader) {
+    // The prototype is only reachable from an impl, and the impl's constructor compiles: this
+    // first pair lands in the engine's own cache (kept for the device's life, as before); every
+    // later shader goes through the counted one.
+    if (device.__dxrShaderCache === 'pending') {
+      device.__dxrShaderCache = 'probing';
+      let impl;
+      try {
+        impl = create.call(this, shader);
+      } finally {
+        if (ownBefore) device.createShaderImpl = create;
+        else delete device.createShaderImpl; // the prototype's method again
+      }
+      device.__dxrShaderCache = patchWebglShaderPrototype(Object.getPrototypeOf(impl));
+      return impl;
+    }
+    return create.call(this, shader);
+  };
+  return device.__dxrShaderCache;
+}
+
+/** Shaders compiled / deleted through the patched cache on `device` (diagnostics), or null. */
+export function shaderCacheStats(device) {
+  const c = device && caches.get(device);
+  return c ? { compiled: c.compiled, deleted: c.deleted, cached: c.refs.size } : null;
+}

package/js/inline3d-playcanvas-engine.js

@@ -42,7 +42,8 @@ export {
   LAYERID_IMMEDIATE,
   // cursor: 'depth' (./inline3d-cursor-depth-playcanvas.js, loaded only on opt-in)
   Picker,
-  // materials / meshes (the edge feather)
+  // materials / meshes (the edge feather; Material: the program release, ./inline3d-pc-auto-release.js)
+  Material,
   Mesh,
   MeshInstance,
   ShaderMaterial,

package/js/inline3d-splat-deferred.js

@@ -126,6 +126,8 @@ export function addSplatDeferred(wall, canvas, src, opts) {
     },
     // Mesh-program warm before the adapter has loaded: runs once it has (it needs the engine).
     warmEntity: (entity, o) => out.ready.then(() => out.warmEntity(entity, o)),
+    // Nothing a page added can exist before the engine has: nothing to release yet.
+    releaseEntity: () => ({ programs: 0, container: null }),
     setEffect: (name, params) => {
       validateEffectCall(name, params, 'set');
       pending.push(['setEffect', [name, params]]);