mirror of
https://github.com/bilawalsidhu/gods-eye-view.git
synced 2026-11-17 00:32:21 +00:00
263 lines
9.4 KiB
JavaScript
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;
|
|
}
|