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.
This commit is contained in:
Sameh Khamis committed 2026-11-07 05:29:57 -08:00
1 parent 71ff682c7f
commit b9248bfce5
10 files changed
+226 -170

No files matched your search

+5 -1
View File
@@ -43,7 +43,11 @@ await app.destroy();
``` ```
The example's containers and three remaining constructors are supplied by the 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 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 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 this export: the consuming build must provide the same instance used elsewhere
+5 -3
View File
@@ -2416,9 +2416,11 @@ which embeds the MAP_KEY.
> so a turned-off layer's entities stayed reachable (Data Centers kept 116 > so a turned-off layer's entities stayed reachable (Data Centers kept 116
> MiB). `src/sceneCommandRelease.js`, installed in `src/app/tools.js`, > MiB). `src/sceneCommandRelease.js`, installed in `src/app/tools.js`,
> requests one frame through `governorRequestRender` after every layer > requests one frame through `governorRequestRender` after every layer
> disable and then trims those arrays. It reads private Cesium fields through > disable and then has `src/render/cesium/sceneCommandRelease.js` (handed
> `src/render/cesium/internals.js`; `src/sceneCommandRelease.test.mjs` pins > over by `src/app/scene.js`) trim those arrays. It reads private Cesium
> them and fails if Cesium renames them or changes which passes it truncates. > 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 > **2026-08-08 — performance waves 1+2:** the app idles via an explicit render
> governor (`src/renderGovernor.js` — hold/release from every per-frame > governor (`src/renderGovernor.js` — hold/release from every per-frame
+1
View File
@@ -3112,6 +3112,7 @@
"src/app/layers/traffic.js", "src/app/layers/traffic.js",
"src/app/operations.js", "src/app/operations.js",
"src/app/scene.js", "src/app/scene.js",
"src/render/cesium/sceneCommandRelease.js",
"src/render/cesium/appRenderer.js", "src/render/cesium/appRenderer.js",
"src/render/cesium/frame.js", "src/render/cesium/frame.js",
"src/render/creditMarkup.js", "src/render/creditMarkup.js",
+4
View File
@@ -4,6 +4,7 @@ import {
cesiumRenderer, cesiumRenderer,
cesiumViewerOf, cesiumViewerOf,
} from '../render/cesium/appRenderer.js'; } from '../render/cesium/appRenderer.js';
import { trimStaleSceneCommands } from '../render/cesium/sceneCommandRelease.js';
import { registerDataCredits } from '../data/dataCredits.js'; import { registerDataCredits } from '../data/dataCredits.js';
import { configureCreditKeyboardAccess } from '../creditKeyboard.js'; import { configureCreditKeyboardAccess } from '../creditKeyboard.js';
import { MapStackController } from '../mapStackController.js'; import { MapStackController } from '../mapStackController.js';
@@ -165,5 +166,8 @@ export async function createApplicationScene({
mapStackController, mapStackController,
operations, operations,
input, 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),
}; };
} }
+16 -10
View File
@@ -20,7 +20,11 @@ import {
import { entityRecord, readEntityRecord } from '../data/entityRecords.js'; import { entityRecord, readEntityRecord } from '../data/entityRecords.js';
import { overlayHost } from './layers/overlayHost.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({ export function createApplicationTools({
scene, scene,
controls, controls,
@@ -131,15 +135,17 @@ export function createApplicationTools({
// per frame. It goes idle only now, after every module above has had its // per frame. It goes idle only now, after every module above has had its
// chance to hold. (perf wave 2) // chance to hold. (perf wave 2)
releaseContinuousRender('boot'); releaseContinuousRender('boot');
// Cesium keeps a turned-off layer's draw commands (and so all its entities) // The renderer may keep a turned-off layer's draw commands (and so all its
// alive in reused per-pass arrays; trim them after each disable. // entities) alive; trim them after each disable.
defer( if (scene.trimStaleCommands)
installLayerReleaseTrim({ defer(
scene: viewer.scene, installLayerReleaseTrim({
dataManager, frame: renderer.frame,
requestRender: governorRequestRender, dataManager,
}), requestRender: governorRequestRender,
); trim: scene.trimStaleCommands,
}),
);
// Install the explicit scope mask used by the DISPLAY controls. // Install the explicit scope mask used by the DISPLAY controls.
installScopeMask(viewer); installScopeMask(viewer);
+51
View File
@@ -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 });
}
@@ -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',
);
});
-1
View File
@@ -78,7 +78,6 @@
"src/maps/google3d.js", "src/maps/google3d.js",
"src/maps/imagery.js", "src/maps/imagery.js",
"src/maps/terrain.js", "src/maps/terrain.js",
"src/sceneCommandRelease.js",
"src/services/groundSnap.js", "src/services/groundSnap.js",
"src/services/meshFloorSampler.js", "src/services/meshFloorSampler.js",
"src/sky/starrySky.js", "src/sky/starrySky.js",
+17 -55
View File
@@ -1,73 +1,35 @@
/** /**
* Let a turned-off layer's memory go. * Let a turned-off layer's memory go.
* *
* Cesium (engine 22.3, `Scene/View.js`) reuses each view's per-pass command * A renderer may keep a turned-off layer's draw commands, and through them
* arrays: every frame resets `frustumCommands.indices[pass]` to 0 and * its whole data source, reachable after the layer stops drawing: the
* overwrites `commands[pass][i]` from the start. `Scene.js` truncates the * default renderer does (see `src/render/cesium/sceneCommandRelease.js`).
* voxel, Gaussian-splat and translucent passes to their counts; the opaque * After a layer finishes turning off, this asks for one frame and, once it
* and other passes keep the slots past the new count. When a layer is turned * is drawn, has the renderer trim what that frame no longer drew.
* 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.
*/ */
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. * 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 * @returns {() => void} uninstall
*/ */
export function installLayerReleaseTrim({ scene, dataManager, requestRender }) { export function installLayerReleaseTrim({
frame,
dataManager,
requestRender,
trim,
}) {
let removeOneShot = null; let removeOneShot = null;
const unsubscribe = dataManager.subscribe((change) => { const unsubscribe = dataManager.subscribe((change) => {
if (change?.type !== 'visibility' || change.enabled !== false) return; if (change?.type !== 'visibility' || change.enabled !== false) return;
if (removeOneShot) return; // a trim is already waiting for its frame if (removeOneShot) return; // a trim is already waiting for its frame
removeOneShot = scene.postRender.addEventListener(() => { removeOneShot = frame.on('postRender', () => {
removeOneShot(); removeOneShot();
removeOneShot = null; removeOneShot = null;
trimStaleSceneCommands(scene); trim();
}); });
requestRender('layer-release-trim'); requestRender('layer-release-trim');
}); });
+40 -100
View File
@@ -1,67 +1,22 @@
// A turned-off layer's draw commands must not stay reachable through Cesium's // A layer disable asks for one frame and has the renderer trim what it no
// reused per-pass command arrays (src/sceneCommandRelease.js). // longer draws once that frame is drawn (src/sceneCommandRelease.js).
import { test } from 'node:test'; import { test } from 'node:test';
import assert from 'node:assert/strict'; import assert from 'node:assert/strict';
import { readFileSync } from 'node:fs'; import { installLayerReleaseTrim } from './sceneCommandRelease.js';
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],
);
});
test('a layer disable renders one frame and trims after it', () => { test('a layer disable renders one frame and trims after it', () => {
const listeners = new Set(); const listeners = new Set();
const postRender = new Set(); const postRender = new Set();
const requests = []; const requests = [];
const view = { frustumCommandsList: [frustum([['a', 'stale']], [1])] }; let trims = 0;
const scene = { const uninstall = installLayerReleaseTrim({
_defaultView: view, frame: {
postRender: { on(phase, fn) {
addEventListener(fn) { assert.equal(phase, 'postRender');
postRender.add(fn); postRender.add(fn);
return () => postRender.delete(fn); return () => postRender.delete(fn);
}, },
}, },
};
const uninstall = installLayerReleaseTrim({
scene,
dataManager: { dataManager: {
subscribe(fn) { subscribe(fn) {
listeners.add(fn); listeners.add(fn);
@@ -69,6 +24,7 @@ test('a layer disable renders one frame and trims after it', () => {
}, },
}, },
requestRender: (reason) => requests.push(reason), requestRender: (reason) => requests.push(reason),
trim: () => (trims += 1),
}); });
const emit = (change) => listeners.forEach((fn) => fn(change)); 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'], ['layer-release-trim'],
'one frame for back-to-back disables', 'one frame for back-to-back disables',
); );
assert.equal( assert.equal(trims, 0, 'not before the frame');
view.frustumCommandsList[0].commands[0].length,
2,
'not before the frame',
);
postRender.forEach((fn) => fn()); 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'); assert.equal(postRender.size, 0, 'the frame listener is one-shot');
emit({ type: 'visibility', layerId: 'z', enabled: false });
assert.equal(postRender.size, 1);
uninstall(); uninstall();
assert.equal(listeners.size, 0); 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 test('on the frame port the trim runs once, after the frame, beside other listeners', async () => {
// fail when Cesium starts clearing the tail itself so the module can go. const { listenerList } = await import('./render/cesium/common.js');
test('Cesium still reuses per-pass command arrays without clearing their tail', () => { const postRender = listenerList((error) => {
const require = createRequire(import.meta.url); throw error;
const enginePkg = require.resolve('@cesium/engine/package.json'); });
const read = (rel) => const seen = [];
readFileSync(new URL(rel, pathToFileURL(enginePkg)), 'utf8'); postRender.on(() => seen.push('before'));
const scene = read('./Source/Scene/Scene.js'); let emit;
const view = read('./Source/Scene/View.js'); const uninstall = installLayerReleaseTrim({
const frustumCommands = read('./Source/Scene/FrustumCommands.js'); frame: { on: (phase, cb) => postRender.on(cb) },
const picking = read('./Source/Scene/Picking.js'); dataManager: {
// Every private field the trim reads. A rename would otherwise turn the subscribe(fn) {
// trim into a silent no-op (it reaches them through `?.` and `|| []`). emit = fn;
assert.match(scene, /this\._picking = new Picking\(this\);/); return () => {};
assert.match(scene, /this\._defaultView = new View\(/); },
assert.match(picking, /this\._pickOffscreenView = new View\(/); },
assert.match(view, /this\.frustumCommandsList = \[\];/); requestRender() {},
assert.match(view, /frustumCommandsList\[n\]\.indices\[p\] = 0;/); trim: () => seen.push('trim'),
assert.match(view, /this\._commandExtents = \[\];/); });
assert.match( emit({ type: 'visibility', enabled: false });
frustumCommands, postRender.on(() => seen.push('after'));
/this\.commands = commands;\s*this\.indices = indices;/, postRender.fire();
); postRender.fire();
// Cesium truncates only the voxel, Gaussian-splat and translucent passes, assert.deepEqual(seen, ['before', 'trim', 'after', 'before', 'after']);
// each in its own draw step; the opaque and other passes keep their tail. assert.equal(postRender.size, 2);
// A change here means Cesium's handling moved: re-check whether this uninstall();
// 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',
);
}); });