Files
gods-eye-view/src/render/cesium/internals.test.mjs
T
Sameh Khamis e6d22e55d7 Complete the Cesium frame port
The frame port now does everything the contract asks of it on Cesium:
preUpdate says whether the tick draws (Cesium's own render test, read
live until the tick is over), holds are counted per reason, and suspend,
target fps, renderNow and diagnostics are real. Releasing the last hold
asks for one more frame.

whenSettled also waits until Cesium stops redrawing on its own. Each
request or worker task Cesium completes queues a redraw (a terrain
picker build after the camera moved, say), which no loading flag shows,
so it now waits for quiet frames and then a short stretch in which the
loop draws nothing by itself. It is bounded by its timeout, names a
stopped loop, and ends on destroy.

The app renderer still leaves out the members that steer the loop:
the render governor and the page's visibility handling own those
settings until they move onto the port.

The new frame.prediction check compares the preUpdate answer with what
each tick drew.
2026-11-05 17:11:25 -08:00

236 lines
8.7 KiB
JavaScript

import { test } from 'node:test';
import assert from 'node:assert/strict';
import fs from 'node:fs';
import path from 'node:path';
import { createRequire } from 'node:module';
import { fileURLToPath } from 'node:url';
import {
atEndOfTick,
billboardCollectionOf,
billboardLoadError,
cameraFlightActive,
closeRenderLoopLatch,
clusterPointCollection,
commandExtents,
defaultView,
lastRenderTime,
lastSeenCamera,
onEngineWorkCompleted,
pickOffscreenView,
renderPending,
updateCameraChanged,
webglContext,
} from './internals.js';
const ROOT = path.resolve(
path.dirname(fileURLToPath(import.meta.url)),
'..',
'..',
'..',
);
const require = createRequire(import.meta.url);
const packageSource = (name) =>
path.join(path.dirname(require.resolve(`${name}/package.json`)), 'Source');
const ENGINE = packageSource('@cesium/engine');
const WIDGETS = packageSource('@cesium/widgets');
test('every private field the app reaches is still declared by the installed Cesium', () => {
const fields = [
[ENGINE, 'Scene/Scene.js', '_defaultView'],
[ENGINE, 'Scene/Scene.js', '_picking'],
[ENGINE, 'Scene/Picking.js', '_pickOffscreenView'],
[ENGINE, 'Scene/View.js', '_commandExtents'],
[ENGINE, 'Scene/Billboard.js', '_billboardCollection'],
[ENGINE, 'DataSources/EntityCluster.js', '_clusterPointCollection'],
[ENGINE, 'Widget/CesiumWidget.js', '_renderLoopRunning'],
[WIDGETS, 'Viewer/Viewer.js', '_cesiumWidget'],
[ENGINE, 'Renderer/Context.js', '_gl'],
[ENGINE, 'Scene/Camera.js', '_currentFlight'],
[ENGINE, 'Scene/Scene.js', '_renderRequested'],
[ENGINE, 'Scene/Scene.js', '_logDepthBufferDirty'],
[ENGINE, 'Scene/Scene.js', '_hdrDirty'],
[ENGINE, 'Scene/Scene.js', '_lastRenderTime'],
[ENGINE, 'Scene/Scene.js', '_view'],
[ENGINE, 'Scene/View.js', '_cameraClone'],
[ENGINE, 'Scene/Scene.js', '_frameState'],
];
const missing = fields.filter(
([root, file, field]) =>
!new RegExp(`this\\.${field}\\s*=`).test(
fs.readFileSync(path.join(root, file), 'utf8'),
),
);
assert.deepEqual(missing, []);
const camera = fs.readFileSync(path.join(ENGINE, 'Scene/Camera.js'), 'utf8');
assert.match(camera, /Camera\.prototype\._updateCameraChanged = function/);
const billboard = fs.readFileSync(
path.join(ENGINE, 'Scene/Billboard.js'),
'utf8',
);
assert.match(billboard, /\n {2}loadError: \{/, 'Billboard#loadError');
const read = (file) => fs.readFileSync(path.join(ENGINE, file), 'utf8');
assert.match(
read('Core/RequestScheduler.js'),
/\nRequestScheduler\.requestCompletedEvent = /,
);
assert.match(
read('Core/TaskProcessor.js'),
/\nTaskProcessor\.taskCompletedEvent = /,
);
assert.match(read('Scene/FrameState.js'), /this\.afterRender = \[\]/);
// What makes them matter: each completion redraws the scene.
const scene = read('Scene/Scene.js');
// Every tick empties the after-render queue, outside its draw.
const render = scene.slice(
scene.indexOf('Scene.prototype.render = function'),
);
const body = render.slice(0, render.indexOf('\n};'));
assert.match(
body,
/\n {2}callAfterRenderFunctions\(this\);\n/,
'callAfterRenderFunctions runs at the top level of Scene#render',
);
for (const event of [
'RequestScheduler.requestCompletedEvent',
'TaskProcessor.taskCompletedEvent',
])
assert.match(
scene,
new RegExp(
`${event.replace('.', '\\.')}\\.addEventListener\\(\\s*requestRenderAfterFrame\\(this\\)`,
),
event,
);
});
test('the helpers read and write exactly those fields', () => {
const view = { _commandExtents: [{ command: {} }] };
assert.equal(defaultView({ _defaultView: view }), view);
assert.equal(
pickOffscreenView({ _picking: { _pickOffscreenView: view } }),
view,
);
assert.equal(commandExtents(view), view._commandExtents);
assert.deepEqual(commandExtents(undefined), []);
const collection = {};
assert.equal(
billboardCollectionOf({ _billboardCollection: collection }),
collection,
);
assert.equal(
clusterPointCollection({ _clusterPointCollection: collection }),
collection,
);
assert.equal(clusterPointCollection(undefined), null);
const widget = { _renderLoopRunning: true };
closeRenderLoopLatch({ _cesiumWidget: widget });
assert.equal(widget._renderLoopRunning, false);
closeRenderLoopLatch({});
assert.equal(renderPending({}), false);
assert.equal(renderPending({ _renderRequested: true }), true);
assert.equal(renderPending({ _hdrDirty: true }), true);
assert.equal(renderPending({ _logDepthBufferDirty: true }), true);
const time = {};
assert.equal(lastRenderTime({ _lastRenderTime: time }), time);
const clone = {};
assert.equal(lastSeenCamera({ _view: { _cameraClone: clone } }), clone);
assert.equal(lastSeenCamera({}), undefined);
const error = new Error('404');
assert.equal(billboardLoadError({ loadError: error }), error);
const gl = {};
assert.equal(webglContext({ context: { _gl: gl } }), gl);
assert.equal(cameraFlightActive({ _currentFlight: {} }), true);
assert.equal(cameraFlightActive({ _currentFlight: undefined }), false);
let checked = 0;
updateCameraChanged({ _updateCameraChanged: () => (checked += 1) });
assert.equal(checked, 1);
const afterRender = [];
const fn = () => {};
atEndOfTick({ _frameState: { afterRender } }, fn);
assert.deepEqual(afterRender, [fn]);
const event = () => {
const listeners = new Set();
return {
addEventListener(cb) {
listeners.add(cb);
return () => listeners.delete(cb);
},
raise: () => listeners.forEach((cb) => cb('ignored')),
};
};
const RequestScheduler = { requestCompletedEvent: event() };
const TaskProcessor = { taskCompletedEvent: event() };
const calls = [];
const off = onEngineWorkCompleted(
{ RequestScheduler, TaskProcessor },
(...args) => calls.push(args),
);
RequestScheduler.requestCompletedEvent.raise();
TaskProcessor.taskCompletedEvent.raise();
assert.deepEqual(calls, [[], []]);
off();
TaskProcessor.taskCompletedEvent.raise();
assert.equal(calls.length, 2);
});
test('private Cesium fields are reached only through internals.js', () => {
// A private field is one Cesium assigns as `this._name`. The app's own objects
// use underscore fields too, and some share a name with one of Cesium's,
// so a name the app itself defines (on `this`, a state object or as a key) is
// the app's; any other `._name` from Cesium's set is a private Cesium read.
const walk = (dir, filter) =>
fs.readdirSync(dir, { withFileTypes: true }).flatMap((entry) => {
const full = path.join(dir, entry.name);
if (entry.isDirectory()) return walk(full, filter);
return filter(entry.name) ? [full] : [];
});
const cesiumPrivate = new Set();
for (const file of [
...walk(ENGINE, (name) => name.endsWith('.js')),
...walk(WIDGETS, (name) => name.endsWith('.js')),
])
for (const [, name] of fs
.readFileSync(file, 'utf8')
.matchAll(/this\._([A-Za-z]\w*)/g))
cesiumPrivate.add(name);
const INTERNALS = 'src/render/cesium/internals.js';
const sources = walk(path.join(ROOT, 'src'), (name) =>
/\.(js|vue)$/.test(name),
)
.map((file) => path.relative(ROOT, file))
.filter((file) => file !== INTERNALS)
.map((file) => [
file,
fs
.readFileSync(path.join(ROOT, file), 'utf8')
.replace(/\/\*[\s\S]*?\*\//g, '')
.replace(/^\s*\/\/.*$/gm, ''),
]);
const coreOwn = new Set();
const definitions = [
/\b(?:this|\w*[sS]tate|owner|self|parts|anno|entry|record|rec|cal|label|controller)\._([A-Za-z]\w*)\s*=(?!=)/g,
/^\s*(?:static\s+)?(?:async\s+)?_([A-Za-z]\w*)\s*[(=:;]/gm,
/[{,]\s*_([A-Za-z]\w*)\s*:/g,
];
for (const [, code] of sources)
for (const pattern of definitions)
for (const [, name] of code.matchAll(pattern)) coreOwn.add(name);
// A Cesium object's private field is flagged whatever the app names its own
// fields: on a receiver that is a Cesium object, or by bracket access.
const CESIUM_RECEIVER =
/\b_?(?:viewer|scene|camera|globe|context|frameState|clustering|tileset|imageryProvider|terrainProvider|screenSpaceCameraController|cesiumWidget|imageryLayers|primitives|dataSources|entities|clock)\??\._([A-Za-z]\w*)\b/g;
const BRACKET = /\[\s*['"`]_([A-Za-z]\w*)['"`]\s*\]/g;
const offenders = [];
for (const [file, code] of sources) {
for (const [, name] of code.matchAll(/\._([A-Za-z]\w*)\b/g))
if (cesiumPrivate.has(name) && !coreOwn.has(name))
offenders.push(`${file} ._${name}`);
for (const pattern of [CESIUM_RECEIVER, BRACKET])
for (const [, name] of code.matchAll(pattern))
if (cesiumPrivate.has(name)) offenders.push(`${file} ._${name}`);
}
assert.deepEqual([...new Set(offenders)], []);
});