Files
gods-eye-view/src/renderGovernor.js
T

263 lines
9.4 KiB
JavaScript

/**
* Idle render governor — the wave-2 flagship of the 2026-08-05 perf
* investigation.
*
* The problem: Cesium's default render loop repaints every vsync forever, so
* the app burned ~60% GPU + ~54% of a core with ZERO layers enabled and a
* parked camera. The fix: flip the scene into Cesium's `requestRenderMode`
* whenever nothing animates per frame, and return to the continuous loop the
* moment something does.
*
* Architecture — a binary mode driven by owner holds, kept by the
* renderer's frame port (`src/render/contract/frame.d.ts`), which is the one
* place the loop's mode is set:
*
* - **Continuous mode** (every frame drawn) while ANY hold is registered. Every per-frame animator — fleet
* interpolation, traffic sim, satellite motion, tracked-entity follow,
* style crossfades, CCTV projection — registers a hold for exactly the
* lifetime of its scene-loop listener or animation. While one is active,
* behavior is byte-identical to pre-governor main: the locked
* interpolation/tracking invariants are preserved by construction.
* - **Idle mode** (drawn on demand) when zero holds. The renderer draws
* on camera input and tile loads by itself; every other scene mutation
* must call `governorRequestRender()` for its one frame. Discrete
* mutators (layer poll ticks, slider writes, annotation changes) route
* through that.
*
* Holds are identity-keyed (one per owner id), NOT a counter — a module
* that double-holds or double-releases cannot corrupt the mode. Owners are
* short stable strings ('flights', 'traffic', 'style-anim', …) so the
* diagnostics read like a story.
*
* Frame rate: in continuous mode the loop draws at the display's own
* refresh rate. In idle mode the renderer's frame port ticks it at most at
* IDLE_FRAME_RATE, because Cesium still ticks the clock, data sources and
* every pre/post-update listener once per animation frame even when it skips
* the draw. Camera movement takes a 'camera' hold from `moveStart` to
* `moveEnd`, so drags and flights run at the full rate too.
*
* The governor is O(1) passive: no per-frame work of its own, ever.
*/
/** @typedef {import('./render/contract/frame').FramePort} FramePort */
/** @typedef {import('./render/contract/camera').CameraPort} CameraPort */
/** Frames a second the loop ticks while nothing moves. */
export const IDLE_FRAME_RATE = 60;
let _frame = null;
/** Owners holding, each with the frame port's release once installed. */
const _holds = new Map();
/** Removes the camera move listeners added at install. */
let _removeCameraListeners = null;
/** Debug trail of the most recent one-shot render requests (idle mode only). */
const _recentRequests = [];
const RECENT_REQUEST_CAP = 16;
function holdOnFrame(ownerId) {
if (_frame && !_holds.get(ownerId))
_holds.set(ownerId, _frame.holdContinuous(ownerId));
}
/** Pose sampling while the camera moves (see watchCameraMotion). */
const CAMERA_SAMPLE_MS = 250;
const CAMERA_POSITION_TOLERANCE_M = 1e-3;
const CAMERA_DIRECTION_TOLERANCE = 1e-9;
function near(a, b, tolerance) {
return (
Math.abs(a.x - b.x) <= tolerance &&
Math.abs(a.y - b.y) <= tolerance &&
Math.abs(a.z - b.z) <= tolerance
);
}
/**
* Hold continuous render while the camera moves. The camera port's
* `moveStart` takes the hold and `moveEnd` releases it. Cesium compares the
* pose with the last frame's to the last rounding error, and at some poses
* the camera drifts by a rounding error every frame, so `moveEnd` never
* comes (see `installGlobeInViewRecovery` in app/globeInViewRecovery.js). So from `moveStart` until
* `moveEnd` the pose is also sampled every 250 ms with a tolerance for that
* drift: half a second at rest releases the hold and a later move takes it
* again (Cesium raises no new `moveStart` under that drift). Sampling runs
* until `moveEnd`, however long that takes; it costs four checks a second.
* @returns {(() => void)|null} Removes the listeners and the sampling.
*/
function watchCameraMotion(camera, { schedule, unschedule }) {
if (typeof camera?.on !== 'function') return null;
const pose = () => camera.pose?.() ?? null;
const last = { position: null, direction: null };
let timer = null;
let restingSamples = 0;
const copy = (v) => (v ? { x: v.x, y: v.y, z: v.z } : null);
const remember = () => {
const now = pose();
last.position = copy(now?.position);
last.direction = copy(now?.direction);
};
const stopSampling = () => {
if (timer !== null) unschedule(timer);
timer = null;
};
const sample = () => {
timer = null;
const now = pose();
const position = now?.position;
const direction = now?.direction;
const atRest =
!position ||
!direction ||
!last.position ||
(near(position, last.position, CAMERA_POSITION_TOLERANCE_M) &&
near(direction, last.direction, CAMERA_DIRECTION_TOLERANCE));
if (atRest) {
restingSamples += 1;
if (restingSamples >= 2) releaseContinuousRender('camera');
} else {
restingSamples = 0;
holdContinuousRender('camera');
}
remember();
timer = schedule(sample, CAMERA_SAMPLE_MS);
};
const removeStart = camera.on('moveStart', () => {
holdContinuousRender('camera');
stopSampling();
restingSamples = 0;
remember();
timer = schedule(sample, CAMERA_SAMPLE_MS);
});
const removeEnd = camera.on('moveEnd', () => {
stopSampling();
releaseContinuousRender('camera');
});
return () => {
stopSampling();
removeStart();
removeEnd();
};
}
/**
* Install the governor on the renderer's frame port, which keeps the loop
* drawing every frame while any owner holds and on demand otherwise (and
* draws one settling frame when the last hold goes). Idempotent. Before
* install, hold/release still record into the holds (and apply at install
* time); requests are safe no-ops — so modules can call all three
* unconditionally in tests without a renderer. With `camera`, a camera move
* holds the loop drawing every frame (see watchCameraMotion); installing
* again watches the camera given then.
* @param {FramePort} frame
* @param {{camera?: CameraPort|null, setTimeout?: Function,
* clearTimeout?: Function}} [options] The renderer's camera port, and
* injectable timers for tests.
* @returns {void}
*/
export function installRenderGovernor(
frame,
{
camera = null,
setTimeout: schedule = globalThis.setTimeout,
clearTimeout: unschedule = globalThis.clearTimeout,
} = {},
) {
if (typeof frame?.holdContinuous !== 'function')
throw new TypeError('installRenderGovernor requires a frame port');
_removeCameraListeners?.();
_removeCameraListeners = null;
releaseContinuousRender('camera');
if (_frame !== frame) {
if (_frame) releaseFrameHolds();
_frame = frame;
for (const ownerId of _holds.keys()) holdOnFrame(ownerId);
}
_removeCameraListeners = watchCameraMotion(camera, { schedule, unschedule });
}
function releaseFrameHolds() {
for (const [ownerId, release] of _holds) {
release?.();
_holds.set(ownerId, null);
}
}
/**
* Register a continuous-render hold. Idempotent per owner.
* Call where the owner's per-frame work BEGINS (scene listener installed,
* animation starts, tracking begins).
* @param {string} ownerId Short stable id, e.g. 'flights', 'traffic'.
* @returns {void}
*/
export function holdContinuousRender(ownerId) {
if (!ownerId) return;
if (!_holds.has(ownerId)) _holds.set(ownerId, null);
holdOnFrame(ownerId);
}
/**
* Release a hold. Safe when never held.
* Call where the owner's per-frame work ENDS (listener removed, animation
* settled, tracking stopped, layer disabled).
* @param {string} ownerId
* @returns {void}
*/
export function releaseContinuousRender(ownerId) {
if (!ownerId || !_holds.has(ownerId)) return;
const release = _holds.get(ownerId);
_holds.delete(ownerId);
release?.();
}
/**
* One-shot render request for a discrete scene mutation (layer tick, slider
* write, annotation change). Always forwards to the frame port — while held
* that is harmless (and forwarding closes the request-then-last-release
* race); only idle-mode requests are recorded in diagnostics. Cheap enough
* to call unconditionally after any mutation.
* @param {string} [reason] For diagnostics only.
* @returns {void}
*/
export function governorRequestRender(reason = 'unspecified') {
if (!_frame) return;
if (_holds.size === 0) {
_recentRequests.push({ reason, at: Date.now() });
if (_recentRequests.length > RECENT_REQUEST_CAP) _recentRequests.shift();
}
_frame.requestRender(reason);
}
/**
* @returns {{installed: boolean, mode: 'continuous'|'idle', holds: string[],
* recentRequests: Array<{reason: string, at: number}>}}
*/
export function getRenderGovernorDiagnostics() {
return {
installed: Boolean(_frame),
mode: _holds.size > 0 ? 'continuous' : 'idle',
holds: [..._holds.keys()].sort(),
recentRequests: [..._recentRequests],
};
}
/** Release the installed frame port after its animation owners have stopped. */
export function uninstallRenderGovernor(frame) {
if (!_frame || _frame !== frame) return;
_removeCameraListeners?.();
_removeCameraListeners = null;
releaseFrameHolds();
_frame = null;
_holds.clear();
_recentRequests.length = 0;
}
/** Test seam: reset module state between unit tests. */
export function _resetRenderGovernorForTest() {
_removeCameraListeners?.();
_removeCameraListeners = null;
_frame = null;
_holds.clear();
_recentRequests.length = 0;
}