Scope render demand to each scene attachment

Give each scene its own render governor, owner holds and recent idle requests.
Make the Cesium render backend own its request mode directly, so the governor
drives engine.render on both engines without a dependency back from Cesium.
Route layer requests through their attached engine and capture the attachment's
governor for camera motions, orbit, annotations and shell controls. Release
retained-layer holds before clearing the outgoing engine, and destroy the
governor after scene consumers have detached.

Preserve Cesium's owner-keyed holds, pre-install buffering, last-release settling
frame and one-shot requests during continuous rendering. Navara keeps the same
render policy. There is no intended visible change on either engine. Simultaneous
scenes no longer share holds, and an old captured service cannot release a
replacement attachment's hold. Cover both rules on fake and headless Cesium
engines, including an old orbit ending after reattachment.

Viewer-reference lines fall from 910 to 891, Navara-kind checks from 2 to 1,
and engine-name lines from 33 to 32. All other coupling counts stay unchanged.

Checked in the browser, keyless: qa-perf passes on both engines with the
same idle, active and release counts as before (24 checks on Cesium, 22 on
Navara).
This commit is contained in:
German Khokhlov committed 2026-11-07 16:56:34 +04:00
1 parent 4252ed0798
commit 0459ee6d58
87 files changed
+720 -935

No files matched your search

+1 -3
View File
@@ -45,9 +45,7 @@ import { createCesiumSurface } from './surface.js';
* imagery.js) are test seams, `createStage` and `createSonar` too
* (render.js).
*
* `render.setContinuous` takes a hold on the app's singleton renderGovernor
* (src/renderGovernor.js), which governs the one viewer it was installed on;
* so one Cesium engine per page, on that viewer.
* `render` owns this scene's requests and continuous-render mode.
* @returns {import('../contract.js').GlobeEngine}
*/
export function createCesiumEngine(viewer, options = {}) {
+1 -9
View File
@@ -2,11 +2,6 @@ import test from 'node:test';
import assert from 'node:assert/strict';
import * as Cesium from 'cesium';
import { assertGlobeEngine, engineCapabilities } from '../contract.js';
import {
_resetRenderGovernorForTest,
getRenderGovernorDiagnostics,
installRenderGovernor,
} from '../../renderGovernor.js';
import { createContractSuite } from '../testing/contractSuite.mjs';
import { createCesiumEngine } from './createCesiumEngine.js';
import { createCameraViewer } from './testing/cameraViewer.mjs';
@@ -15,8 +10,6 @@ import {
createFakeViewer,
} from './testing/fakeViewer.mjs';
test.afterEach(() => _resetRenderGovernorForTest());
function snapshot(viewer) {
const { scene } = viewer;
return {
@@ -85,7 +78,6 @@ test('the render option reaches render.request', () => {
test('destroy releases holds, listeners, handlers and engine-owned map state', async () => {
const viewer = createFakeViewer();
installRenderGovernor(viewer);
const handlers = createFakeEventHandlers();
const engine = createCesiumEngine(viewer, {
createEventHandler: handlers.create,
@@ -104,7 +96,7 @@ test('destroy releases holds, listeners, handlers and engine-owned map state', a
assert.equal(viewer.scene.camera.changed.numberOfListeners, 0);
assert.equal(viewer.scene.postRender.numberOfListeners, 0);
assert.equal(handlers.handlers[0].destroyed, true);
assert.deepEqual(getRenderGovernorDiagnostics().holds, []);
assert.equal(viewer.scene.requestRenderMode, true);
assert.deepEqual(viewer.staticCredits, []);
assert.deepEqual(viewer.imageryList, []);
});
+6 -23
View File
@@ -1,15 +1,5 @@
// GlobeRender on the app's render governor, which owns Cesium's
// requestRenderMode and maximumRenderTimeChange; the engine only takes a
// hold under its own owner id. The full-frame effects (visual styles,
// bloom, sharpening) are the scene's post stages (postStages.js), the
// contact sonar the scene's native draw commands (sonar.js).
// Cesium owns its render mode and scene effects. Scene services drive this API.
import {
governorRequestRender,
holdContinuousRender,
isRenderGovernorInstalled,
releaseContinuousRender,
} from '../../renderGovernor.js';
import { CONTACT_SONAR_INITIAL, mergeContactSonar } from '../contract.js';
import { createCesiumPostStages } from './postStages.js';
import { createCesiumSonar } from './sonar.js';
@@ -21,8 +11,7 @@ export const RENDER_OWNER = 'globe-engine';
* @param {{ requestRender?: (reason: string) => void,
* createStage?: (options: object) => object,
* createSonar?: typeof createCesiumSonar }} [options] `requestRender`
* defaults to the render governor when it governs this viewer, else the
* scene itself (before the governor is installed, or on another viewer);
* defaults to the scene itself;
* `createStage` (postStages.js) and `createSonar` are test seams.
* @returns {{ render: import('../contract.js').GlobeRender,
* sonarDiagnostics: () => object, destroy: () => void }}
@@ -30,15 +19,12 @@ export const RENDER_OWNER = 'globe-engine';
export function createCesiumRender(
viewer,
{
requestRender = (reason) => {
if (isRenderGovernorInstalled(viewer)) governorRequestRender(reason);
else viewer.scene.requestRender?.();
},
requestRender = () => viewer.scene.requestRender?.(),
createStage,
createSonar = createCesiumSonar,
} = {},
) {
let held = false;
viewer.scene.maximumRenderTimeChange = Infinity;
const effects = createCesiumPostStages(viewer, {
requestRender,
...(createStage ? { createStage } : {}),
@@ -69,11 +55,8 @@ export function createCesiumRender(
requestRender(reason);
},
setContinuous(enabled) {
held = Boolean(enabled);
if (held) holdContinuousRender(RENDER_OWNER);
else releaseContinuousRender(RENDER_OWNER);
viewer.scene.requestRenderMode = !enabled;
},
// The scene's real mode: another owner's hold keeps it continuous.
isContinuous: () => viewer.scene.requestRenderMode === false,
...effects.render,
setContactSonar(options) {
@@ -93,7 +76,7 @@ export function createCesiumRender(
render,
sonarDiagnostics: () => sonar.diagnostics(),
destroy() {
if (held) render.setContinuous(false);
render.setContinuous(false);
removeFrameWatch?.();
sonar.destroy();
effects.destroy();
+24 -80
View File
@@ -1,17 +1,8 @@
import test from 'node:test';
import assert from 'node:assert/strict';
import {
_resetRenderGovernorForTest,
getRenderGovernorDiagnostics,
holdContinuousRender,
installRenderGovernor,
} from '../../renderGovernor.js';
import { createCesiumRender, RENDER_OWNER } from './render.js';
import { createFakeViewer } from './testing/fakeViewer.mjs';
test.beforeEach(() => _resetRenderGovernorForTest());
test.after(() => _resetRenderGovernorForTest());
test('request goes through the injected requestRender with a reason', () => {
const viewer = createFakeViewer();
const reasons = [];
@@ -19,84 +10,37 @@ test('request goes through the injected requestRender with a reason', () => {
requestRender: (reason) => reasons.push(reason),
});
render.request();
assert.deepEqual(reasons, [RENDER_OWNER]);
render.request('world-overlay');
assert.deepEqual(reasons, [RENDER_OWNER, 'world-overlay']);
assert.equal(viewer.callsOf('scene.requestRender').length, 0);
});
test('request defaults to the render governor', () => {
const viewer = createFakeViewer();
installRenderGovernor(viewer);
const { render } = createCesiumRender(viewer);
render.request();
assert.equal(viewer.callsOf('scene.requestRender').length, 1);
assert.deepEqual(
getRenderGovernorDiagnostics().recentRequests.map(({ reason }) => reason),
[RENDER_OWNER],
);
});
test('creation leaves the scene and the governor alone', () => {
test('creation disables time-driven renders and preserves the current mode', () => {
const viewer = createFakeViewer();
viewer.scene.maximumRenderTimeChange = 0.5;
viewer.scene.requestRenderMode = false;
createCesiumRender(viewer);
assert.equal(viewer.scene.requestRenderMode, true);
assert.equal(viewer.scene.maximumRenderTimeChange, 0.5);
assert.equal(getRenderGovernorDiagnostics().installed, false);
assert.deepEqual(getRenderGovernorDiagnostics().holds, []);
});
test('setContinuous holds and releases the governor under its own owner', () => {
const viewer = createFakeViewer();
installRenderGovernor(viewer);
const { render } = createCesiumRender(viewer);
assert.equal(render.isContinuous(), false);
render.setContinuous(true);
assert.deepEqual(getRenderGovernorDiagnostics().holds, [RENDER_OWNER]);
assert.equal(viewer.scene.requestRenderMode, false);
assert.equal(render.isContinuous(), true);
render.setContinuous(false);
assert.deepEqual(getRenderGovernorDiagnostics().holds, []);
assert.equal(render.isContinuous(), false);
assert.equal(viewer.scene.maximumRenderTimeChange, Infinity);
});
test("isContinuous reports the scene's mode, including other owners' holds", () => {
const viewer = createFakeViewer();
installRenderGovernor(viewer);
const { render } = createCesiumRender(viewer);
holdContinuousRender('flights');
render.setContinuous(false);
assert.equal(render.isContinuous(), true);
});
test('destroy releases the engine hold', () => {
const viewer = createFakeViewer();
installRenderGovernor(viewer);
const { render, destroy } = createCesiumRender(viewer);
render.setContinuous(true);
destroy();
assert.deepEqual(getRenderGovernorDiagnostics().holds, []);
});
test('request passes a caller reason through to the governor', () => {
const viewer = createFakeViewer();
installRenderGovernor(viewer);
const { render } = createCesiumRender(viewer);
render.request('world-overlay');
assert.deepEqual(
getRenderGovernorDiagnostics().recentRequests.map(({ reason }) => reason),
['world-overlay'],
);
});
test('without a governor on its viewer, request renders the scene directly', () => {
const viewer = createFakeViewer();
const { render } = createCesiumRender(viewer);
render.request();
assert.equal(viewer.callsOf('scene.requestRender').length, 1);
const governed = createFakeViewer();
installRenderGovernor(governed);
render.request();
assert.equal(viewer.callsOf('scene.requestRender').length, 2);
assert.equal(governed.callsOf('scene.requestRender').length, 0);
assert.deepEqual(getRenderGovernorDiagnostics().recentRequests, []);
test('render mode, requests and destruction affect only the owning scene', () => {
const first = createFakeViewer();
const second = createFakeViewer();
const a = createCesiumRender(first);
const b = createCesiumRender(second);
a.render.setContinuous(true);
b.render.setContinuous(true);
assert.equal(a.render.isContinuous(), true);
assert.equal(b.render.isContinuous(), true);
a.render.setContinuous(false);
assert.equal(a.render.isContinuous(), false);
assert.equal(b.render.isContinuous(), true);
a.render.request('world-overlay');
assert.equal(first.callsOf('scene.requestRender').length, 1);
assert.equal(second.callsOf('scene.requestRender').length, 0);
a.destroy();
assert.equal(b.render.isContinuous(), true);
b.destroy();
assert.equal(b.render.isContinuous(), false);
});
+1 -4
View File
@@ -1,6 +1,5 @@
import * as Cesium from 'cesium';
import { loadBundledJson } from '../../data/bundledJson.js';
import { governorRequestRender } from '../../renderGovernor.js';
import { buildStarVertices, STAR_VERTEX_FLOATS } from '../../sky/stars.js';
/**
@@ -143,9 +142,7 @@ export class StarrySky {
* @param {() => void} [options.requestRender] renders one frame when an
* asset or the precise rotation arrives; the idle governor by default.
*/
constructor({
requestRender = () => governorRequestRender('sky-assets'),
} = {}) {
constructor({ requestRender = () => {} } = {}) {
/** Matches `SkyBox#show`. */
this.show = true;
this.milkyWayIntensity = MILKY_WAY_INTENSITY;
+5 -3
View File
@@ -387,7 +387,7 @@ export const loadCesiumPhotorealTileset = (keys) =>
loadPhotorealisticTileset(Cesium, keys);
/** Cesium.Viewer options of the standard globe viewer. */
export function applicationViewerOptions(creditContainer) {
export function applicationViewerOptions(creditContainer, requestRender) {
return {
timeline: false,
animation: false,
@@ -403,7 +403,7 @@ export function applicationViewerOptions(creditContainer) {
baseLayer: false,
// Replaces the blocky Tycho-2 default. An option, not `skyBox: false`,
// which would also stop CesiumWidget from creating the Sun and Moon.
skyBox: new StarrySky(),
skyBox: new StarrySky({ requestRender }),
creditContainer,
msaaSamples: 4,
contextOptions: { webgl: { preserveDrawingBuffer: true } },
@@ -416,7 +416,9 @@ export function createApplicationViewer({ container, creditContainer }) {
throw new TypeError('Viewer and credit containers are required');
const viewer = new Cesium.Viewer(
container,
applicationViewerOptions(creditContainer),
applicationViewerOptions(creditContainer, () =>
viewer.scene.requestRender(),
),
);
try {
viewer.targetFrameRate = 60;
+1 -2
View File
@@ -1,5 +1,4 @@
import * as Cesium from 'cesium';
import { governorRequestRender } from '../../renderGovernor.js';
/** Whole-Earth input limit; explicit camera destinations can go farther. */
export const MAXIMUM_ZOOM_DISTANCE_M = 40_000_000;
@@ -84,7 +83,7 @@ function readInput(aggregator, bindings) {
export function installZoomOutGuard(
viewer,
{
requestRender = governorRequestRender,
requestRender = () => viewer.scene.requestRender(),
subscribeCameraHandoff,
createAggregator = (canvas) => new Cesium.CameraEventAggregator(canvas),
} = {},