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

+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/imagery.js",
"src/maps/terrain.js",
"src/sceneCommandRelease.js",
"src/services/groundSnap.js",
"src/services/meshFloorSampler.js",
"src/sky/starrySky.js",