Merge pull request #1752 from bilawalsidhu/render/uncap-frame-rate

Draw at the display's refresh rate while anything moves
This commit is contained in:
Sameh Khamis authored and GitHub committed 2026-11-15 11:16:11 -08:00
commit 46ccce3396
14 files changed
+429 -22

No files matched your search

+3
View File
@@ -0,0 +1,3 @@
### Changed
- While anything moves (layers in motion, the camera, a followed contact), the globe now draws at the display's own refresh rate instead of a fixed 60 frames a second. A parked scene still ticks at most 60 times a second. Waits that counted frames (a followed contact's first position, a shared follow view, a trail's temporary copy) now count drawn time, so they last the same at any refresh rate. Screen marks over a followed contact fade out over the same time at any refresh rate.
+13
View File
@@ -1,5 +1,18 @@
# God's Eye View Current State # God's Eye View Current State
While anything moves (a layer in motion, the camera, a followed contact), the
globe draws at the display's own refresh rate; there is no fixed 60 FPS cap.
The idle render governor (`src/renderGovernor.js`) caps a parked scene at
`IDLE_FRAME_RATE` (60) ticks a second, because Cesium still runs the clock,
data sources and update listeners on every animation frame even when it skips
the draw; the viewer starts at that cap until the governor is installed. The
camera holds continuous render from `moveStart` to `moveEnd`, and samples its
pose every 250 ms in between, so a camera drifting by rounding errors (no
`moveEnd`) is released after half a second at rest and held again if it moves. Waits that used to count frames (a followed contact's first
position, a shared follow view, a trail's temporary copy) count drawn time
through `src/time/frameWait.js`, at most 100 ms a frame, so they last the same
at any refresh rate and a background tab does not use them up.
Docker Compose mounts the checkout with the shared SELinux `:z` label so Docker Compose mounts the checkout with the shared SELinux `:z` label so
containers can read it on enforcing SELinux hosts. The separate image-owned containers can read it on enforcing SELinux hosts. The separate image-owned
`node_modules` volume and loopback-only port publishing remain unchanged. `node_modules` volume and loopback-only port publishing remain unchanged.
+4
View File
@@ -32,6 +32,10 @@ hardware-rendered overlay scenes.
| 3 | 558.527 ms | 1,809.592 ms | 438.8 ms | 60 / 60 FPS | 105.1 MiB | | 3 | 558.527 ms | 1,809.592 ms | 438.8 ms | 60 / 60 FPS | 105.1 MiB |
| Median | 604.849 ms | 1,855.836 ms | 439.5 ms | 60 / 60 FPS | 105.1 MiB | | Median | 604.849 ms | 1,855.836 ms | 439.5 ms | 60 / 60 FPS | 105.1 MiB |
These frame rates were measured when the globe was capped at 60 FPS. It now
draws at the display's refresh rate while anything moves and ticks at most 60
times a second when parked (`src/renderGovernor.js`).
The initial-settle measurement is the more useful launch reference because it The initial-settle measurement is the more useful launch reference because it
includes the first visual and data settling window. All three samples reached includes the first visual and data settling window. All three samples reached
the display ceiling during both motion and rest. the display ceiling during both motion and rest.
+6 -3
View File
@@ -1354,7 +1354,8 @@
"src/ui/views/panels/WildlifeSightingCard.vue", "src/ui/views/panels/WildlifeSightingCard.vue",
"src/ui/wildlifeSightingPlacement.js", "src/ui/wildlifeSightingPlacement.js",
"src/overlays/worldOverlayChrome.js", "src/overlays/worldOverlayChrome.js",
"src/layers/wildlifeSightings/photoText.js" "src/layers/wildlifeSightings/photoText.js",
"src/time/frameWait.js"
], ],
"external": ["cesium", "vue", "pinia", "vue-i18n"] "external": ["cesium", "vue", "pinia", "vue-i18n"]
}, },
@@ -3839,7 +3840,8 @@
"src/data/openVesselPhoto.js", "src/data/openVesselPhoto.js",
"src/layers/vessels/photos.js", "src/layers/vessels/photos.js",
"src/layers/flights/placed.js", "src/layers/flights/placed.js",
"src/data/placementProvider.js" "src/data/placementProvider.js",
"src/time/frameWait.js"
], ],
"external": [ "external": [
"hls.js", "hls.js",
@@ -4565,7 +4567,8 @@
"src/layers/vessels/photos.js", "src/layers/vessels/photos.js",
"src/data/openVesselPhoto.js", "src/data/openVesselPhoto.js",
"src/layers/flights/placed.js", "src/layers/flights/placed.js",
"src/data/placementProvider.js" "src/data/placementProvider.js",
"src/time/frameWait.js"
], ],
"external": [ "external": [
"hls.js", "hls.js",
+16 -3
View File
@@ -399,7 +399,12 @@ export function createScreenAnnotationRenderer(
// from the host's ACTUAL painted rectangle after final layout; the billboard extent // from the host's ACTUAL painted rectangle after final layout; the billboard extent
// is unioned for aircraft/satellites that also own a native tracked graphic. // is unioned for aircraft/satellites that also own a native tracked graphic.
const TRACKED_BBOX_MARGIN = 8; // px buffer added around the footprint const TRACKED_BBOX_MARGIN = 8; // px buffer added around the footprint
const TRACKED_FADE_EASE = 0.22; // per-frame ease toward hidden(0) / visible(1) // Ease toward hidden(0) / visible(1): this share of the gap closes in one
// 60 Hz frame (about 200 ms to settle), scaled by elapsed time so the fade
// takes as long at any refresh rate.
const TRACKED_FADE_EASE = 0.22;
const TRACKED_FADE_FRAME_MS = 1000 / 60;
let trackedFadeAtMs = -Infinity;
const TRACKED_HYSTERESIS_PX = 18; // dead-band so the overlap test can't flip-flop const TRACKED_HYSTERESIS_PX = 18; // dead-band so the overlap test can't flip-flop
const _scratchTrackedWin = new Cesium.Cartesian2(); const _scratchTrackedWin = new Cesium.Cartesian2();
@@ -677,6 +682,14 @@ export function createScreenAnnotationRenderer(
// safe and not jarring. // safe and not jarring.
function fadeTracked(trackedRect) { function fadeTracked(trackedRect) {
if (!shown()) return; if (!shown()) return;
const nowMs = performance.now();
// A gap longer than a slow frame means the fade was not running (nothing
// followed): it starts again as from one 60 Hz frame.
const gapMs = nowMs - trackedFadeAtMs;
const stepMs = gapMs >= 0 && gapMs <= 100 ? gapMs : TRACKED_FADE_FRAME_MS;
trackedFadeAtMs = nowMs;
const ease =
1 - Math.pow(1 - TRACKED_FADE_EASE, stepMs / TRACKED_FADE_FRAME_MS);
let changed = false; let changed = false;
for (const rec of records.values()) { for (const rec of records.values()) {
const { anno, group } = rec; const { anno, group } = rec;
@@ -705,10 +718,10 @@ export function createScreenAnnotationRenderer(
} }
} }
const target = overlapping ? 0 : 1; const target = overlapping ? 0 : 1;
const next = cur + (target - cur) * TRACKED_FADE_EASE; const next = cur + (target - cur) * ease;
rec._trackedFade = Math.abs(next - target) < 0.02 ? target : next; rec._trackedFade = Math.abs(next - target) < 0.02 ? target : next;
// The base alpha applies unless faded. (The CSS `transition: opacity` was // The base alpha applies unless faded. (The CSS `transition: opacity` was
// removed from .gev-anno so this per-frame JS ease is the ONLY easing — // removed from .gev-anno so this JS ease is the ONLY easing —
// previously the two fought and produced an opacity oscillation.) // previously the two fought and produced an opacity oscillation.)
const opacity = String( const opacity = String(
(anno.alpha ?? 1) * (rec._trackedFade !== 1 ? rec._trackedFade : 1), (anno.alpha ?? 1) * (rec._trackedFade !== 1 ? rec._trackedFade : 1),
+4 -1
View File
@@ -1,4 +1,5 @@
import * as Cesium from 'cesium'; import * as Cesium from 'cesium';
import { IDLE_FRAME_RATE } from '../renderGovernor.js';
import { applyModelAtmosphereWorkaround } from './atmosphereCompat.js'; import { applyModelAtmosphereWorkaround } from './atmosphereCompat.js';
import { StarrySky } from '../sky/starrySky.js'; import { StarrySky } from '../sky/starrySky.js';
import { import {
@@ -420,7 +421,9 @@ export function createApplicationViewer({
applicationViewerOptions(creditContainer, { showRenderLoopErrors }), applicationViewerOptions(creditContainer, { showRenderLoopErrors }),
); );
try { try {
viewer.targetFrameRate = 60; // Until the render governor takes over (app/tools.js), tick at the idle
// rate so the startup load does not compete with drawing at 240 fps.
viewer.targetFrameRate = IDLE_FRAME_RATE;
// A phone pinch spans fewer screen pixels than desktop zoom gestures. // A phone pinch spans fewer screen pixels than desktop zoom gestures.
// Keep Cesium's distance-aware zoom and collision limits, with less travel // Keep Cesium's distance-aware zoom and collision limits, with less travel
// required on touch-first screens. Mouse/trackpad sensitivity stays native. // required on touch-first screens. Mouse/trackpad sensitivity stays native.
+5 -4
View File
@@ -1,6 +1,8 @@
import * as Cesium from 'cesium'; import * as Cesium from 'cesium';
import { createFrameWait } from '../time/frameWait.js';
const MAX_FRAME_ATTEMPTS = 120; /** Drawn time (ms) to wait for the tracked entity's first position. */
const MAX_POSITION_WAIT_MS = 2_000;
const MIN_TRACKED_RANGE_M = 150; const MIN_TRACKED_RANGE_M = 150;
const ZOOM_INERTIA_STATES = new WeakMap(); const ZOOM_INERTIA_STATES = new WeakMap();
@@ -154,7 +156,7 @@ export function clampTrackedCameraPosition(
*/ */
export function applyTrackedCameraFrame(viewer, entity, viewFrom) { export function applyTrackedCameraFrame(viewer, entity, viewFrom) {
if (!viewer || !entity || !viewFrom) return; if (!viewer || !entity || !viewFrom) return;
let attempts = 0; const positionWait = createFrameWait(MAX_POSITION_WAIT_MS);
const trackedTransform = new Cesium.Matrix4(); const trackedTransform = new Cesium.Matrix4();
const trackedPosition = new Cesium.Cartesian3(); const trackedPosition = new Cesium.Cartesian3();
const resolvedViewFrom = new Cesium.Cartesian3(); const resolvedViewFrom = new Cesium.Cartesian3();
@@ -184,7 +186,6 @@ export function applyTrackedCameraFrame(viewer, entity, viewFrom) {
stop(); stop();
return; return;
} }
attempts += framed ? 0 : 1;
// Prefer the display cache exposed by the flight layer. Calling the // Prefer the display cache exposed by the flight layer. Calling the
// CallbackProperty from preUpdate can advance dead reckoning again while // CallbackProperty from preUpdate can advance dead reckoning again while
// Cesium's billboard/label still holds the prior visualizer sample. At a // Cesium's billboard/label still holds the prior visualizer sample. At a
@@ -198,7 +199,7 @@ export function applyTrackedCameraFrame(viewer, entity, viewFrom) {
trackedPosition, trackedPosition,
); );
if (!position) { if (!position) {
if (attempts >= MAX_FRAME_ATTEMPTS) stop(); if (positionWait.tick()) stop();
return; return;
} }
const transform = Cesium.Transforms.eastNorthUpToFixedFrame( const transform = Cesium.Transforms.eastNorthUpToFixedFrame(
+11 -8
View File
@@ -33,6 +33,7 @@
*/ */
import * as Cesium from 'cesium'; import * as Cesium from 'cesium';
import { registerPickOwner } from './pickRegistry.js'; import { registerPickOwner } from './pickRegistry.js';
import { createFrameWait } from '../time/frameWait.js';
// Round 6: trail ENTITIES are pickable (the old Primitive had // Round 6: trail ENTITIES are pickable (the old Primitive had
// allowPicking:false). A trail hugs its aircraft, so an unclaimed pick would // allowPicking:false). A trail hugs its aircraft, so an unclaimed pick would
@@ -58,9 +59,9 @@ const MIN_SEGMENT_DISTANCE_SQ = 0.01;
const NO_POSITIONS = Object.freeze([]); const NO_POSITIONS = Object.freeze([]);
/** @constant {number} Points per chunk; adjacent chunks share one point. */ /** @constant {number} Points per chunk; adjacent chunks share one point. */
export const CHUNK_POINTS = 128; export const CHUNK_POINTS = 128;
/** @constant {number} Visible frames a frozen chunk's stand-in waits for its /** @constant {number} Drawn time (ms) a frozen chunk's stand-in waits for its
* static geometry before it is dropped anyway. */ * static geometry while the trail is shown before it is dropped anyway. */
const STAND_IN_MAX_FRAMES = 600; const STAND_IN_MAX_MS = 10_000;
/** /**
* Create an always-visible polyline trail bound to a viewer. * Create an always-visible polyline trail bound to a viewer.
@@ -80,7 +81,7 @@ export function createTrail(viewer, { color, width = 2.5 }) {
const depthFailMaterial = baseColor.withAlpha(TRAIL_OCCLUDED_ALPHA); const depthFailMaterial = baseColor.withAlpha(TRAIL_OCCLUDED_ALPHA);
let destroyed = false; let destroyed = false;
let visible = true; let visible = true;
/** @type {{positions: Cesium.Cartesian3[], entity: Cesium.Entity, standIn: boolean, frames: number}[]} */ /** @type {{positions: Cesium.Cartesian3[], entity: Cesium.Entity, standIn: boolean, wait: {tick: () => boolean, pause: () => void}}[]} */
let frozen = []; let frozen = [];
/** Newest chunk of the newest segment: the only part that changes. */ /** Newest chunk of the newest segment: the only part that changes. */
let tail = NO_POSITIONS; let tail = NO_POSITIONS;
@@ -152,9 +153,11 @@ export function createTrail(viewer, { color, width = 2.5 }) {
function staticReady(chunk) { function staticReady(chunk) {
const display = viewer.dataSourceDisplay; const display = viewer.dataSourceDisplay;
if (typeof display?.getBoundingSphere !== 'function') return true; if (typeof display?.getBoundingSphere !== 'function') return true;
if (!visible) return false; if (!visible) {
chunk.frames += 1; chunk.wait.pause();
if (chunk.frames > STAND_IN_MAX_FRAMES) return true; return false;
}
if (chunk.wait.tick()) return true;
try { try {
return ( return (
display.getBoundingSphere(chunk.entity, false, scratchSphere) === display.getBoundingSphere(chunk.entity, false, scratchSphere) ===
@@ -262,7 +265,7 @@ export function createTrail(viewer, { color, width = 2.5 }) {
positions, positions,
entity: addEntity(positions), entity: addEntity(positions),
standIn: true, standIn: true,
frames: 0, wait: createFrameWait(STAND_IN_MAX_MS),
}); });
i = end; i = end;
} }
+35
View File
@@ -287,3 +287,38 @@ test('replacing the newest point and removing points inside the trail draws exac
for (const run of drawnRuns(viewer)) for (const run of drawnRuns(viewer))
for (let i = 1; i < run.length; i++) assert.equal(next.get(run[i - 1]), run[i]); for (let i = 1; i < run.length; i++) assert.equal(next.get(run[i - 1]), run[i]);
}); });
test('a stand-in is dropped after ten seconds of drawn time, whatever the frame rate', () => {
const viewer = fakeViewer();
const trail = createTrail(viewer, { color: '#ffffff' });
const realNow = performance.now;
let clock = 1_000;
performance.now = () => clock;
try {
trail.setPositions(line(CHUNK_POINTS + 5));
// 2,000 frames at 240 Hz is about 8.3 s: still waiting for the geometry.
for (let i = 0; i < 2_000; i++) {
viewer.frame();
clock += 1000 / 240;
}
assert.equal(trail._chunksForTest().frozen[0].standIn, true);
// Hidden time does not count toward the wait.
trail.setVisible(false);
clock += 60_000;
viewer.frame();
trail.setVisible(true);
viewer.frame();
assert.equal(trail._chunksForTest().frozen[0].standIn, true);
// A background tab draws nothing: a long gap adds at most one frame step.
clock += 60_000;
viewer.frame();
assert.equal(trail._chunksForTest().frozen[0].standIn, true);
for (let i = 0; i < 480 && trail._chunksForTest().frozen[0].standIn; i++) {
clock += 1000 / 240;
viewer.frame();
}
assert.equal(trail._chunksForTest().frozen[0].standIn, false);
} finally {
performance.now = realNow;
}
});
+110 -1
View File
@@ -28,12 +28,24 @@
* short stable strings ('flights', 'traffic', 'style-anim', …) so the * short stable strings ('flights', 'traffic', 'style-anim', …) so the
* diagnostics read like a story. * diagnostics read like a story.
* *
* Frame rate: in continuous mode the viewer draws at the display's own
* refresh rate (no `targetFrameRate`). In idle mode it is capped 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. * The governor is O(1) passive: no per-frame work of its own, ever.
*/ */
/** Frames a second the viewer ticks while nothing moves. */
export const IDLE_FRAME_RATE = 60;
let _viewer = null; let _viewer = null;
let _installed = false; let _installed = false;
const _holds = new Set(); const _holds = new Set();
/** Removes the camera move listeners added at install. */
let _removeCameraListeners = null;
/** Debug trail of the most recent one-shot render requests (idle mode only). */ /** Debug trail of the most recent one-shot render requests (idle mode only). */
const _recentRequests = []; const _recentRequests = [];
@@ -43,6 +55,7 @@ function applyMode() {
if (!_installed || !_viewer?.scene) return; if (!_installed || !_viewer?.scene) return;
const continuous = _holds.size > 0; const continuous = _holds.size > 0;
const scene = _viewer.scene; const scene = _viewer.scene;
_viewer.targetFrameRate = continuous ? undefined : IDLE_FRAME_RATE;
if (scene.requestRenderMode === !continuous) return; if (scene.requestRenderMode === !continuous) return;
scene.requestRenderMode = !continuous; scene.requestRenderMode = !continuous;
if (!continuous) { if (!continuous) {
@@ -52,15 +65,101 @@ function applyMode() {
} }
} }
/** 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. Cesium'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/viewer.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 (!camera?.moveStart || !camera?.moveEnd) return 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 = () => {
last.position = copy(camera.positionWC);
last.direction = copy(camera.directionWC);
};
const stopSampling = () => {
if (timer !== null) unschedule(timer);
timer = null;
};
const sample = () => {
timer = null;
const position = camera.positionWC;
const direction = camera.directionWC;
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.moveStart.addEventListener(() => {
holdContinuousRender('camera');
stopSampling();
restingSamples = 0;
remember();
timer = schedule(sample, CAMERA_SAMPLE_MS);
});
const removeEnd = camera.moveEnd.addEventListener(() => {
stopSampling();
releaseContinuousRender('camera');
});
return () => {
stopSampling();
removeStart();
removeEnd();
};
}
/** /**
* Install the governor on the viewer. Idempotent. Before install, * Install the governor on the viewer. Idempotent. Before install,
* hold/release still record into the holds set (and apply at install time); * hold/release still record into the holds set (and apply at install time);
* requests are safe no-ops — so modules can call all three unconditionally * requests are safe no-ops — so modules can call all three unconditionally
* in tests without a viewer. * in tests without a viewer.
* @param {Cesium.Viewer} viewer * @param {Cesium.Viewer} viewer
* @param {{setTimeout?: Function, clearTimeout?: Function}} [timers] Injectable
* timers for tests.
* @returns {void} * @returns {void}
*/ */
export function installRenderGovernor(viewer) { export function installRenderGovernor(
viewer,
{
setTimeout: schedule = globalThis.setTimeout,
clearTimeout: unschedule = globalThis.clearTimeout,
} = {},
) {
const timers = { schedule, unschedule };
if (!viewer?.scene) if (!viewer?.scene)
throw new TypeError('installRenderGovernor requires a Cesium viewer'); throw new TypeError('installRenderGovernor requires a Cesium viewer');
_viewer = viewer; _viewer = viewer;
@@ -69,6 +168,12 @@ export function installRenderGovernor(viewer) {
// idle means idle. All re-renders are camera/tiles (Cesium-native) or // idle means idle. All re-renders are camera/tiles (Cesium-native) or
// explicit requests. // explicit requests.
viewer.scene.maximumRenderTimeChange = Infinity; viewer.scene.maximumRenderTimeChange = Infinity;
_removeCameraListeners?.();
_holds.delete('camera');
_removeCameraListeners = watchCameraMotion(
viewer.camera ?? viewer.scene.camera,
timers,
);
applyMode(); applyMode();
} }
@@ -132,6 +237,8 @@ export function getRenderGovernorDiagnostics() {
/** Release the installed viewer after its animation owners have stopped. */ /** Release the installed viewer after its animation owners have stopped. */
export function uninstallRenderGovernor(viewer) { export function uninstallRenderGovernor(viewer) {
if (_viewer !== viewer) return; if (_viewer !== viewer) return;
_removeCameraListeners?.();
_removeCameraListeners = null;
_viewer = null; _viewer = null;
_installed = false; _installed = false;
_holds.clear(); _holds.clear();
@@ -140,6 +247,8 @@ export function uninstallRenderGovernor(viewer) {
/** Test seam: reset module state between unit tests. */ /** Test seam: reset module state between unit tests. */
export function _resetRenderGovernorForTest() { export function _resetRenderGovernorForTest() {
_removeCameraListeners?.();
_removeCameraListeners = null;
_viewer = null; _viewer = null;
_installed = false; _installed = false;
_holds.clear(); _holds.clear();
+131
View File
@@ -7,6 +7,8 @@ import {
governorRequestRender, governorRequestRender,
getRenderGovernorDiagnostics, getRenderGovernorDiagnostics,
_resetRenderGovernorForTest, _resetRenderGovernorForTest,
uninstallRenderGovernor,
IDLE_FRAME_RATE,
} from './renderGovernor.js'; } from './renderGovernor.js';
function makeViewer() { function makeViewer() {
@@ -98,3 +100,132 @@ test('holds registered before install apply at install time', () => {
releaseContinuousRender('flights'); releaseContinuousRender('flights');
assert.equal(scene.requestRenderMode, true); assert.equal(scene.requestRenderMode, true);
}); });
function makeEvent() {
const listeners = new Set();
return {
addEventListener(fn) {
listeners.add(fn);
return () => listeners.delete(fn);
},
raise() {
for (const fn of [...listeners]) fn();
},
get size() {
return listeners.size;
},
};
}
test('idle caps the frame rate; anything moving draws at the display rate', () => {
const { viewer } = makeViewer();
installRenderGovernor(viewer);
assert.equal(viewer.targetFrameRate, IDLE_FRAME_RATE);
holdContinuousRender('flights');
assert.equal(viewer.targetFrameRate, undefined);
releaseContinuousRender('flights');
assert.equal(viewer.targetFrameRate, IDLE_FRAME_RATE);
});
test('a camera move holds continuous render from moveStart to moveEnd', () => {
const { viewer, scene } = makeViewer();
viewer.camera = { moveStart: makeEvent(), moveEnd: makeEvent() };
installRenderGovernor(viewer);
viewer.camera.moveStart.raise();
assert.equal(scene.requestRenderMode, false);
assert.equal(viewer.targetFrameRate, undefined);
assert.deepEqual(getRenderGovernorDiagnostics().holds, ['camera']);
viewer.camera.moveEnd.raise();
assert.equal(scene.requestRenderMode, true);
assert.equal(viewer.targetFrameRate, IDLE_FRAME_RATE);
// Installing again does not double the listeners; uninstall removes them.
installRenderGovernor(viewer);
assert.equal(viewer.camera.moveStart.size, 1);
uninstallRenderGovernor(viewer);
assert.equal(viewer.camera.moveStart.size, 0);
assert.equal(viewer.camera.moveEnd.size, 0);
});
function fakeTimers() {
const queue = new Map();
let next = 1;
return {
setTimeout: (fn) => {
queue.set(next, fn);
return next++;
},
clearTimeout: (id) => queue.delete(id),
run() {
const due = [...queue.entries()];
queue.clear();
for (const [, fn] of due) fn();
},
get pending() {
return queue.size;
},
};
}
test('a camera that drifts by rounding errors and never raises moveEnd still releases its hold', () => {
const { viewer, scene } = makeViewer();
const timers = fakeTimers();
viewer.camera = {
moveStart: makeEvent(),
moveEnd: makeEvent(),
positionWC: { x: 6_400_000, y: 0, z: 0 },
directionWC: { x: -1, y: 0, z: 0 },
};
installRenderGovernor(viewer, timers);
viewer.camera.moveStart.raise();
assert.equal(scene.requestRenderMode, false);
// Still moving: the hold stays.
viewer.camera.positionWC = { x: 6_399_000, y: 0, z: 0 };
timers.run();
assert.equal(scene.requestRenderMode, false);
// Drifting by far less than a millimetre: half a second of this is at rest.
viewer.camera.positionWC = { x: 6_399_000 + 1e-7, y: 0, z: 0 };
timers.run();
timers.run();
assert.equal(scene.requestRenderMode, true);
assert.equal(viewer.targetFrameRate, IDLE_FRAME_RATE);
// A later move with no new moveStart takes the hold again.
viewer.camera.positionWC = { x: 6_000_000, y: 0, z: 0 };
timers.run();
assert.equal(scene.requestRenderMode, false);
// moveEnd stops the sampling and releases.
viewer.camera.moveEnd.raise();
assert.equal(scene.requestRenderMode, true);
assert.equal(timers.pending, 0);
});
test('sampling keeps running until moveEnd, so a move after a long drift still takes the hold', () => {
const { viewer, scene } = makeViewer();
const timers = fakeTimers();
viewer.camera = {
moveStart: makeEvent(),
moveEnd: makeEvent(),
positionWC: { x: 1, y: 0, z: 0 },
directionWC: { x: -1, y: 0, z: 0 },
};
installRenderGovernor(viewer, timers);
viewer.camera.moveStart.raise();
// Ten minutes at rest (2,400 samples): released, still sampling.
for (let i = 0; i < 2_400; i++) timers.run();
assert.equal(scene.requestRenderMode, true);
assert.equal(timers.pending, 1);
viewer.camera.positionWC = { x: 1_000, y: 0, z: 0 };
timers.run();
assert.equal(scene.requestRenderMode, false);
});
test('installing again drops a camera hold the old listeners can no longer release', () => {
const { viewer, scene } = makeViewer();
const timers = fakeTimers();
viewer.camera = { moveStart: makeEvent(), moveEnd: makeEvent() };
installRenderGovernor(viewer, timers);
viewer.camera.moveStart.raise();
assert.equal(scene.requestRenderMode, false);
installRenderGovernor(viewer, timers);
assert.equal(scene.requestRenderMode, true);
assert.equal(timers.pending, 0);
});
+37
View File
@@ -0,0 +1,37 @@
/**
* A wait measured in time spent drawing frames, the same at any display
* refresh rate.
*
* Each call to `tick()` adds the time since the previous call, but at most
* MAX_STEP_MS, so a background tab, a parked scene or a hidden owner (which
* draw no frames for this wait) does not use the wait up while nothing is on
* screen.
*/
/** The most one frame may add to a wait, in milliseconds. */
export const MAX_STEP_MS = 100;
/**
* Start a wait of `limitMs` drawn time.
* @param {number} limitMs How long to wait, in milliseconds.
* @param {() => number} [now] Clock in milliseconds.
* @returns {{tick: () => boolean, pause: () => void}} `tick()` counts one
* drawn frame and answers whether the wait is over; `pause()` makes the
* next tick count nothing for the gap since the last one.
*/
export function createFrameWait(limitMs, now = () => performance.now()) {
let waitedMs = 0;
let lastMs = NaN;
return {
tick() {
const at = now();
if (Number.isFinite(lastMs))
waitedMs += Math.min(Math.max(at - lastMs, 0), MAX_STEP_MS);
lastMs = at;
return waitedMs >= limitMs;
},
pause() {
lastMs = NaN;
},
};
}
+49
View File
@@ -0,0 +1,49 @@
import { test } from 'node:test';
import assert from 'node:assert/strict';
import { createFrameWait, MAX_STEP_MS } from './frameWait.js';
function clock() {
let at = 0;
return { now: () => at, advance: (ms) => (at += ms) };
}
test('the wait lasts the same time at 60 and 240 frames a second', () => {
for (const hz of [60, 240]) {
const c = clock();
const wait = createFrameWait(2_000, c.now);
let frames = 0;
while (!wait.tick()) {
c.advance(1000 / hz);
frames += 1;
}
assert.ok(Math.abs(c.now() - 2_000) <= 1000 / hz + 1e-6, `${hz} Hz ended at ${c.now()}`);
assert.ok(frames > 0);
}
});
test('a long gap between frames adds at most one step', () => {
const c = clock();
const wait = createFrameWait(2_000, c.now);
wait.tick();
c.advance(60_000);
assert.equal(wait.tick(), false, 'a background tab does not use the wait up');
let drawnMs = MAX_STEP_MS;
while (!wait.tick()) {
c.advance(16);
drawnMs += 16;
}
assert.ok(drawnMs >= 2_000 && drawnMs < 2_000 + 16 + MAX_STEP_MS);
});
test('after pause the next tick adds nothing', () => {
const c = clock();
const wait = createFrameWait(150, c.now);
wait.tick();
c.advance(90);
wait.tick();
wait.pause();
c.advance(90);
assert.equal(wait.tick(), false);
c.advance(60);
assert.equal(wait.tick(), true);
});
+5 -2
View File
@@ -1,5 +1,6 @@
import * as Cesium from 'cesium'; import * as Cesium from 'cesium';
import { trackedDisplayPositionForCamera } from '../data/trackedCamera.js'; import { trackedDisplayPositionForCamera } from '../data/trackedCamera.js';
import { createFrameWait } from '../time/frameWait.js';
import { import {
SHARE_VIEW_ENTITY_KINDS, SHARE_VIEW_ENTITY_KINDS,
SHARE_VIEW_FOLLOW_RANGE_MAX_M, SHARE_VIEW_FOLLOW_RANGE_MAX_M,
@@ -17,7 +18,8 @@ import {
const KIND_BY_LAYER = new Map( const KIND_BY_LAYER = new Map(
SHARE_VIEW_ENTITY_KINDS.map((entry) => [entry.layerId, entry.kind]), SHARE_VIEW_ENTITY_KINDS.map((entry) => [entry.layerId, entry.kind]),
); );
const MAX_FRAMES = 120; /** Drawn time (ms) to wait for the follow to frame the entity. */
const MAX_FRAMING_WAIT_MS = 2_000;
/** `position`'s local east/north/up offset from `origin`, in metres. */ /** `position`'s local east/north/up offset from `origin`, in metres. */
function enuOffset(origin, position) { function enuOffset(origin, position) {
@@ -136,6 +138,7 @@ export function applyShareFollowOffset(viewer, entity, offset) {
return () => {}; return () => {};
const local = followOffsetToEnu(offset); const local = followOffsetToEnu(offset);
let frames = 0; let frames = 0;
const framingWait = createFrameWait(MAX_FRAMING_WAIT_MS);
let remove = null; let remove = null;
const stop = () => { const stop = () => {
remove?.(); remove?.();
@@ -160,7 +163,7 @@ export function applyShareFollowOffset(viewer, entity, offset) {
) )
: null; : null;
if (!target) { if (!target) {
if (frames >= MAX_FRAMES) stop(); if (framingWait.tick()) stop();
return; return;
} }
// The offset is east/north/up at the entity; the follow's own frame may // The offset is east/north/up at the entity; the follow's own frame may