From b9248bfce5f908dd34d3a9a2095dddee81edc6c9 Mon Sep 17 00:00:00 2001 From: Sameh Khamis Date: Sat, 7 Nov 2026 05:29:21 -0800 Subject: [PATCH] Keep the scene command trim in the Cesium adapter and take its installer off the Cesium list The private-field trim of Cesium's reused per-pass command arrays moves to src/render/cesium/sceneCommandRelease.js. The installer waits for the renderer frame port's postRender after each layer disable and calls a trim the application scene hands over, so it no longer touches the Cesium scene. --- docs/APPLICATION.md | 6 +- docs/CURRENT-STATE.md | 8 +- scripts/package-boundaries.json | 1 + src/app/scene.js | 4 + src/app/tools.js | 26 ++-- src/render/cesium/sceneCommandRelease.js | 51 +++++++ .../cesium/sceneCommandRelease.test.mjs | 87 +++++++++++ src/render/cesiumAllowList.json | 1 - src/sceneCommandRelease.js | 72 +++------ src/sceneCommandRelease.test.mjs | 140 +++++------------- 10 files changed, 226 insertions(+), 170 deletions(-) create mode 100644 src/render/cesium/sceneCommandRelease.js create mode 100644 src/render/cesium/sceneCommandRelease.test.mjs diff --git a/docs/APPLICATION.md b/docs/APPLICATION.md index 7fb047c26..9b2798de3 100644 --- a/docs/APPLICATION.md +++ b/docs/APPLICATION.md @@ -43,7 +43,11 @@ await app.destroy(); ``` The example's containers and three remaining constructors are supplied by the -consumer. The viewer helper preserves the standalone viewer's render settings; +caller. The standalone scene also returns `trimStaleCommands()`, which drops +the draw commands the Cesium scene keeps after a turned-off layer stops drawing; +the application tools call it one frame after each layer disable. A scene +without it keeps those commands, and so the layer's memory, until they are +overwritten. The viewer helper preserves the standalone viewer's render settings; it neither selects map sources nor reads keys. Supply a visible credit container and retain all attribution required by the chosen sources. Cesium is external to this export: the consuming build must provide the same instance used elsewhere diff --git a/docs/CURRENT-STATE.md b/docs/CURRENT-STATE.md index ccbcf8e78..53ce65ee8 100644 --- a/docs/CURRENT-STATE.md +++ b/docs/CURRENT-STATE.md @@ -2416,9 +2416,11 @@ which embeds the MAP_KEY. > so a turned-off layer's entities stayed reachable (Data Centers kept 116 > MiB). `src/sceneCommandRelease.js`, installed in `src/app/tools.js`, > requests one frame through `governorRequestRender` after every layer -> disable and then trims those arrays. It reads private Cesium fields through -> `src/render/cesium/internals.js`; `src/sceneCommandRelease.test.mjs` pins -> them and fails if Cesium renames them or changes which passes it truncates. +> disable and then has `src/render/cesium/sceneCommandRelease.js` (handed +> over by `src/app/scene.js`) trim those arrays. It reads private Cesium +> fields through `src/render/cesium/internals.js`; +> `src/render/cesium/sceneCommandRelease.test.mjs` pins them and fails if +> Cesium renames them or changes which passes it truncates. > **2026-08-08 — performance waves 1+2:** the app idles via an explicit render > governor (`src/renderGovernor.js` — hold/release from every per-frame diff --git a/scripts/package-boundaries.json b/scripts/package-boundaries.json index 6c86f5b60..5aa2eab4b 100644 --- a/scripts/package-boundaries.json +++ b/scripts/package-boundaries.json @@ -3112,6 +3112,7 @@ "src/app/layers/traffic.js", "src/app/operations.js", "src/app/scene.js", + "src/render/cesium/sceneCommandRelease.js", "src/render/cesium/appRenderer.js", "src/render/cesium/frame.js", "src/render/creditMarkup.js", diff --git a/src/app/scene.js b/src/app/scene.js index 852518cb1..b4a397013 100644 --- a/src/app/scene.js +++ b/src/app/scene.js @@ -4,6 +4,7 @@ import { cesiumRenderer, cesiumViewerOf, } from '../render/cesium/appRenderer.js'; +import { trimStaleSceneCommands } from '../render/cesium/sceneCommandRelease.js'; import { registerDataCredits } from '../data/dataCredits.js'; import { configureCreditKeyboardAccess } from '../creditKeyboard.js'; import { MapStackController } from '../mapStackController.js'; @@ -165,5 +166,8 @@ export async function createApplicationScene({ mapStackController, operations, input, + // Drops the draw commands the scene keeps after it stops drawing them; + // run after a drawn frame (see src/sceneCommandRelease.js). + trimStaleCommands: () => trimStaleSceneCommands(viewer.scene), }; } diff --git a/src/app/tools.js b/src/app/tools.js index b7dfcb375..8cfa2be05 100644 --- a/src/app/tools.js +++ b/src/app/tools.js @@ -20,7 +20,11 @@ import { import { entityRecord, readEntityRecord } from '../data/entityRecords.js'; import { overlayHost } from './layers/overlayHost.js'; -/** Attach scene tools, rendering listeners and the application debug handle. */ +/** + * Attach scene tools, rendering listeners and the application debug handle. + * `scene` is what `createApplicationScene` returns; its `trimStaleCommands` + * runs after each layer disable (a scene without one keeps that memory). + */ export function createApplicationTools({ scene, controls, @@ -131,15 +135,17 @@ export function createApplicationTools({ // per frame. It goes idle only now, after every module above has had its // chance to hold. (perf wave 2) releaseContinuousRender('boot'); - // Cesium keeps a turned-off layer's draw commands (and so all its entities) - // alive in reused per-pass arrays; trim them after each disable. - defer( - installLayerReleaseTrim({ - scene: viewer.scene, - dataManager, - requestRender: governorRequestRender, - }), - ); + // The renderer may keep a turned-off layer's draw commands (and so all its + // entities) alive; trim them after each disable. + if (scene.trimStaleCommands) + defer( + installLayerReleaseTrim({ + frame: renderer.frame, + dataManager, + requestRender: governorRequestRender, + trim: scene.trimStaleCommands, + }), + ); // Install the explicit scope mask used by the DISPLAY controls. installScopeMask(viewer); diff --git a/src/render/cesium/sceneCommandRelease.js b/src/render/cesium/sceneCommandRelease.js new file mode 100644 index 000000000..41be5a94a --- /dev/null +++ b/src/render/cesium/sceneCommandRelease.js @@ -0,0 +1,51 @@ +/** + * Drop the draw commands a Cesium scene keeps after it stops drawing them. + * + * Cesium (engine 22.3, `Scene/View.js`) reuses each view's per-pass command + * arrays: every frame resets `frustumCommands.indices[pass]` to 0 and + * overwrites `commands[pass][i]` from the start. `Scene.js` truncates the + * voxel, Gaussian-splat and translucent passes to their counts; the opaque + * and other passes keep the slots past the new count. When a layer is turned + * off the next frame has fewer commands, so that tail keeps the destroyed + * primitives' DrawCommands, and through `_owner` → primitive → entity → + * EntityCollection the whole data source stays reachable. The offscreen view + * `scene.sampleHeight` / `pickFromRay` render into keeps its last list the + * same way, until the next height sample. + * + * Measured (production build, heap after GC, Data Centers on → off): 116 MiB + * kept on main, 13 MiB with this module; heap snapshots traced the entities + * through `View.frustumCommandsList` and `Picking._pickOffscreenView`. + * + * After a layer finishes turning off (`src/sceneCommandRelease.js` waits for + * the frame), this trims the main view's arrays to that frame's counts, and + * empties the offscreen pick view's lists (it rebuilds them in full on every + * pick). It reads private Cesium fields: `sceneCommandRelease.test.mjs` fails + * if any of them is renamed or if Cesium changes which passes it truncates, + * and once Cesium clears the tail itself this module can go. + */ + +import { commandExtents, defaultView, pickOffscreenView } from './internals.js'; + +/** Drop command references a view no longer draws. */ +function trimView(view, { keepCurrent }) { + for (const frustum of view?.frustumCommandsList || []) { + const { commands, indices } = frustum; + for (let pass = 0; pass < commands.length; pass += 1) { + const keep = keepCurrent ? indices[pass] : 0; + if (commands[pass].length > keep) commands[pass].length = keep; + if (!keepCurrent) indices[pass] = 0; + } + } + if (!keepCurrent) + for (const extent of commandExtents(view)) extent.command = undefined; +} + +/** + * Release stale command references in the scene's main view (keeping what + * the last frame drew) and in its offscreen pick view (all of it). + * @param {object} scene Cesium Scene, right after a render. + */ +export function trimStaleSceneCommands(scene) { + trimView(defaultView(scene), { keepCurrent: true }); + trimView(pickOffscreenView(scene), { keepCurrent: false }); +} diff --git a/src/render/cesium/sceneCommandRelease.test.mjs b/src/render/cesium/sceneCommandRelease.test.mjs new file mode 100644 index 000000000..1eb3d7d6a --- /dev/null +++ b/src/render/cesium/sceneCommandRelease.test.mjs @@ -0,0 +1,87 @@ +// A turned-off layer's draw commands must not stay reachable through Cesium's +// reused per-pass command arrays (src/render/cesium/sceneCommandRelease.js). +import { test } from 'node:test'; +import assert from 'node:assert/strict'; +import { readFileSync } from 'node:fs'; +import { createRequire } from 'node:module'; +import { pathToFileURL } from 'node:url'; +import { trimStaleSceneCommands } from './sceneCommandRelease.js'; + +const frustum = (lists, counts) => ({ + commands: lists.map((list) => [...list]), + indices: [...counts], +}); + +test('the main view keeps what the last frame drew and drops the stale tail', () => { + const view = { + frustumCommandsList: [frustum([['a', 'b', 'stale'], ['c'], []], [2, 1, 0])], + }; + trimStaleSceneCommands({ _defaultView: view }); + assert.deepEqual(view.frustumCommandsList[0].commands, [ + ['a', 'b'], + ['c'], + [], + ]); + assert.deepEqual(view.frustumCommandsList[0].indices, [2, 1, 0]); +}); + +test('the offscreen pick view is emptied, since every pick rebuilds it', () => { + const extents = [{ command: 'x' }, { command: 'y' }]; + const pick = { + frustumCommandsList: [frustum([['p', 'q'], ['r']], [2, 1])], + _commandExtents: extents, + }; + trimStaleSceneCommands({ + _defaultView: { frustumCommandsList: [] }, + _picking: { _pickOffscreenView: pick }, + }); + assert.deepEqual(pick.frustumCommandsList[0].commands, [[], []]); + assert.deepEqual(pick.frustumCommandsList[0].indices, [0, 0]); + assert.deepEqual( + extents.map((e) => e.command), + [undefined, undefined], + ); +}); + +// The workaround reads private Cesium fields. Pin the shape it relies on, and +// fail when Cesium starts clearing the tail itself so the module can go. +test('Cesium still reuses per-pass command arrays without clearing their tail', () => { + const require = createRequire(import.meta.url); + const enginePkg = require.resolve('@cesium/engine/package.json'); + const read = (rel) => + readFileSync(new URL(rel, pathToFileURL(enginePkg)), 'utf8'); + const scene = read('./Source/Scene/Scene.js'); + const view = read('./Source/Scene/View.js'); + const frustumCommands = read('./Source/Scene/FrustumCommands.js'); + const picking = read('./Source/Scene/Picking.js'); + // Every private field the trim reads. A rename would otherwise turn the + // trim into a silent no-op (it reaches them through `?.` and `|| []`). + assert.match(scene, /this\._picking = new Picking\(this\);/); + assert.match(scene, /this\._defaultView = new View\(/); + assert.match(picking, /this\._pickOffscreenView = new View\(/); + assert.match(view, /this\.frustumCommandsList = \[\];/); + assert.match(view, /frustumCommandsList\[n\]\.indices\[p\] = 0;/); + assert.match(view, /this\._commandExtents = \[\];/); + assert.match( + frustumCommands, + /this\.commands = commands;\s*this\.indices = indices;/, + ); + // Cesium truncates only the voxel, Gaussian-splat and translucent passes, + // each in its own draw step; the opaque and other passes keep their tail. + // A change here means Cesium's handling moved: re-check whether this + // module is still needed. + assert.doesNotMatch( + view, + /\.length\s*=\s*[^;]*indices\[/, + 'View.js now truncates the per-pass arrays: remove src/render/cesium/sceneCommandRelease.js', + ); + assert.deepEqual( + [ + ...scene.matchAll( + /commands\.length = frustumCommands\.indices\[Pass\.(\w+)\];/g, + ), + ].map((match) => match[1]), + ['VOXELS', 'GAUSSIAN_SPLATS', 'TRANSLUCENT'], + 'Scene.js truncates a different set of passes: re-check src/render/cesium/sceneCommandRelease.js', + ); +}); diff --git a/src/render/cesiumAllowList.json b/src/render/cesiumAllowList.json index 807476726..5f0298ed0 100644 --- a/src/render/cesiumAllowList.json +++ b/src/render/cesiumAllowList.json @@ -78,7 +78,6 @@ "src/maps/google3d.js", "src/maps/imagery.js", "src/maps/terrain.js", - "src/sceneCommandRelease.js", "src/services/groundSnap.js", "src/services/meshFloorSampler.js", "src/sky/starrySky.js", diff --git a/src/sceneCommandRelease.js b/src/sceneCommandRelease.js index ba3d76b98..b582df5ff 100644 --- a/src/sceneCommandRelease.js +++ b/src/sceneCommandRelease.js @@ -1,73 +1,35 @@ /** * Let a turned-off layer's memory go. * - * Cesium (engine 22.3, `Scene/View.js`) reuses each view's per-pass command - * arrays: every frame resets `frustumCommands.indices[pass]` to 0 and - * overwrites `commands[pass][i]` from the start. `Scene.js` truncates the - * voxel, Gaussian-splat and translucent passes to their counts; the opaque - * and other passes keep the slots past the new count. When a layer is turned - * off the next frame has fewer commands, so that tail keeps the destroyed - * primitives' DrawCommands, and through `_owner` → primitive → entity → - * EntityCollection the whole data source stays reachable. The offscreen view - * `scene.sampleHeight` / `pickFromRay` render into keeps its last list the - * same way, until the next height sample. - * - * Measured (production build, heap after GC, Data Centers on → off): 116 MiB - * kept on main, 13 MiB with this module; heap snapshots traced the entities - * through `View.frustumCommandsList` and `Picking._pickOffscreenView`. - * - * After a layer finishes turning off, this renders one frame, trims the main - * view's arrays to that frame's counts, and empties the offscreen pick view's - * lists (it rebuilds them in full on every pick). It reads private Cesium - * fields: `src/sceneCommandRelease.test.mjs` fails if any of them is renamed - * or if Cesium changes which passes it truncates, and once Cesium clears the - * tail itself this module can go. + * A renderer may keep a turned-off layer's draw commands, and through them + * its whole data source, reachable after the layer stops drawing: the + * default renderer does (see `src/render/cesium/sceneCommandRelease.js`). + * After a layer finishes turning off, this asks for one frame and, once it + * is drawn, has the renderer trim what that frame no longer drew. */ -import { - commandExtents, - defaultView, - pickOffscreenView, -} from './render/cesium/internals.js'; - -/** Drop command references a view no longer draws. */ -function trimView(view, { keepCurrent }) { - for (const frustum of view?.frustumCommandsList || []) { - const { commands, indices } = frustum; - for (let pass = 0; pass < commands.length; pass += 1) { - const keep = keepCurrent ? indices[pass] : 0; - if (commands[pass].length > keep) commands[pass].length = keep; - if (!keepCurrent) indices[pass] = 0; - } - } - if (!keepCurrent) - for (const extent of commandExtents(view)) extent.command = undefined; -} - -/** - * Release stale command references in the scene's main view (keeping what - * the last frame drew) and in its offscreen pick view (all of it). - * @param {object} scene Cesium Scene, right after a render. - */ -export function trimStaleSceneCommands(scene) { - trimView(defaultView(scene), { keepCurrent: true }); - trimView(pickOffscreenView(scene), { keepCurrent: false }); -} - /** * After every layer disable, render one frame and trim once it is drawn. - * @param {{scene: object, dataManager: object, requestRender: (reason: string) => void}} deps + * @param {{frame: import('./render/contract/frame').FramePort, + * dataManager: object, requestRender: (reason: string) => void, + * trim: () => void}} deps `trim` drops what the last drawn frame did not + * draw. * @returns {() => void} uninstall */ -export function installLayerReleaseTrim({ scene, dataManager, requestRender }) { +export function installLayerReleaseTrim({ + frame, + dataManager, + requestRender, + trim, +}) { let removeOneShot = null; const unsubscribe = dataManager.subscribe((change) => { if (change?.type !== 'visibility' || change.enabled !== false) return; if (removeOneShot) return; // a trim is already waiting for its frame - removeOneShot = scene.postRender.addEventListener(() => { + removeOneShot = frame.on('postRender', () => { removeOneShot(); removeOneShot = null; - trimStaleSceneCommands(scene); + trim(); }); requestRender('layer-release-trim'); }); diff --git a/src/sceneCommandRelease.test.mjs b/src/sceneCommandRelease.test.mjs index d88037872..013903d1e 100644 --- a/src/sceneCommandRelease.test.mjs +++ b/src/sceneCommandRelease.test.mjs @@ -1,67 +1,22 @@ -// A turned-off layer's draw commands must not stay reachable through Cesium's -// reused per-pass command arrays (src/sceneCommandRelease.js). +// A layer disable asks for one frame and has the renderer trim what it no +// longer draws once that frame is drawn (src/sceneCommandRelease.js). import { test } from 'node:test'; import assert from 'node:assert/strict'; -import { readFileSync } from 'node:fs'; -import { createRequire } from 'node:module'; -import { pathToFileURL } from 'node:url'; -import { - installLayerReleaseTrim, - trimStaleSceneCommands, -} from './sceneCommandRelease.js'; - -const frustum = (lists, counts) => ({ - commands: lists.map((list) => [...list]), - indices: [...counts], -}); - -test('the main view keeps what the last frame drew and drops the stale tail', () => { - const view = { - frustumCommandsList: [frustum([['a', 'b', 'stale'], ['c'], []], [2, 1, 0])], - }; - trimStaleSceneCommands({ _defaultView: view }); - assert.deepEqual(view.frustumCommandsList[0].commands, [ - ['a', 'b'], - ['c'], - [], - ]); - assert.deepEqual(view.frustumCommandsList[0].indices, [2, 1, 0]); -}); - -test('the offscreen pick view is emptied, since every pick rebuilds it', () => { - const extents = [{ command: 'x' }, { command: 'y' }]; - const pick = { - frustumCommandsList: [frustum([['p', 'q'], ['r']], [2, 1])], - _commandExtents: extents, - }; - trimStaleSceneCommands({ - _defaultView: { frustumCommandsList: [] }, - _picking: { _pickOffscreenView: pick }, - }); - assert.deepEqual(pick.frustumCommandsList[0].commands, [[], []]); - assert.deepEqual(pick.frustumCommandsList[0].indices, [0, 0]); - assert.deepEqual( - extents.map((e) => e.command), - [undefined, undefined], - ); -}); +import { installLayerReleaseTrim } from './sceneCommandRelease.js'; test('a layer disable renders one frame and trims after it', () => { const listeners = new Set(); const postRender = new Set(); const requests = []; - const view = { frustumCommandsList: [frustum([['a', 'stale']], [1])] }; - const scene = { - _defaultView: view, - postRender: { - addEventListener(fn) { + let trims = 0; + const uninstall = installLayerReleaseTrim({ + frame: { + on(phase, fn) { + assert.equal(phase, 'postRender'); postRender.add(fn); return () => postRender.delete(fn); }, }, - }; - const uninstall = installLayerReleaseTrim({ - scene, dataManager: { subscribe(fn) { listeners.add(fn); @@ -69,6 +24,7 @@ test('a layer disable renders one frame and trims after it', () => { }, }, requestRender: (reason) => requests.push(reason), + trim: () => (trims += 1), }); const emit = (change) => listeners.forEach((fn) => fn(change)); @@ -81,57 +37,41 @@ test('a layer disable renders one frame and trims after it', () => { ['layer-release-trim'], 'one frame for back-to-back disables', ); - assert.equal( - view.frustumCommandsList[0].commands[0].length, - 2, - 'not before the frame', - ); + assert.equal(trims, 0, 'not before the frame'); postRender.forEach((fn) => fn()); - assert.deepEqual(view.frustumCommandsList[0].commands, [['a']]); + assert.equal(trims, 1); assert.equal(postRender.size, 0, 'the frame listener is one-shot'); + emit({ type: 'visibility', layerId: 'z', enabled: false }); + assert.equal(postRender.size, 1); uninstall(); assert.equal(listeners.size, 0); + assert.equal(postRender.size, 0, 'a waiting trim goes with it'); }); -// The workaround reads private Cesium fields. Pin the shape it relies on, and -// fail when Cesium starts clearing the tail itself so the module can go. -test('Cesium still reuses per-pass command arrays without clearing their tail', () => { - const require = createRequire(import.meta.url); - const enginePkg = require.resolve('@cesium/engine/package.json'); - const read = (rel) => - readFileSync(new URL(rel, pathToFileURL(enginePkg)), 'utf8'); - const scene = read('./Source/Scene/Scene.js'); - const view = read('./Source/Scene/View.js'); - const frustumCommands = read('./Source/Scene/FrustumCommands.js'); - const picking = read('./Source/Scene/Picking.js'); - // Every private field the trim reads. A rename would otherwise turn the - // trim into a silent no-op (it reaches them through `?.` and `|| []`). - assert.match(scene, /this\._picking = new Picking\(this\);/); - assert.match(scene, /this\._defaultView = new View\(/); - assert.match(picking, /this\._pickOffscreenView = new View\(/); - assert.match(view, /this\.frustumCommandsList = \[\];/); - assert.match(view, /frustumCommandsList\[n\]\.indices\[p\] = 0;/); - assert.match(view, /this\._commandExtents = \[\];/); - assert.match( - frustumCommands, - /this\.commands = commands;\s*this\.indices = indices;/, - ); - // Cesium truncates only the voxel, Gaussian-splat and translucent passes, - // each in its own draw step; the opaque and other passes keep their tail. - // A change here means Cesium's handling moved: re-check whether this - // module is still needed. - assert.doesNotMatch( - view, - /\.length\s*=\s*[^;]*indices\[/, - 'View.js now truncates the per-pass arrays: remove src/sceneCommandRelease.js', - ); - assert.deepEqual( - [ - ...scene.matchAll( - /commands\.length = frustumCommands\.indices\[Pass\.(\w+)\];/g, - ), - ].map((match) => match[1]), - ['VOXELS', 'GAUSSIAN_SPLATS', 'TRANSLUCENT'], - 'Scene.js truncates a different set of passes: re-check src/sceneCommandRelease.js', - ); +test('on the frame port the trim runs once, after the frame, beside other listeners', async () => { + const { listenerList } = await import('./render/cesium/common.js'); + const postRender = listenerList((error) => { + throw error; + }); + const seen = []; + postRender.on(() => seen.push('before')); + let emit; + const uninstall = installLayerReleaseTrim({ + frame: { on: (phase, cb) => postRender.on(cb) }, + dataManager: { + subscribe(fn) { + emit = fn; + return () => {}; + }, + }, + requestRender() {}, + trim: () => seen.push('trim'), + }); + emit({ type: 'visibility', enabled: false }); + postRender.on(() => seen.push('after')); + postRender.fire(); + postRender.fire(); + assert.deepEqual(seen, ['before', 'trim', 'after', 'before', 'after']); + assert.equal(postRender.size, 2); + uninstall(); });