diff --git a/changelog.d/1752-uncapped-frame-rate.md b/changelog.d/1752-uncapped-frame-rate.md new file mode 100644 index 000000000..db09e754b --- /dev/null +++ b/changelog.d/1752-uncapped-frame-rate.md @@ -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. diff --git a/docs/CURRENT-STATE.md b/docs/CURRENT-STATE.md index ceaa5e4e9..7d6fc3698 100644 --- a/docs/CURRENT-STATE.md +++ b/docs/CURRENT-STATE.md @@ -10,6 +10,19 @@ or an older position from another feed) and one reported slower than 2 m/s give no course and keep the last; an aircraft with no course at all faces north. +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 containers can read it on enforcing SELinux hosts. The separate image-owned `node_modules` volume and loopback-only port publishing remain unchanged. diff --git a/docs/PERFORMANCE.md b/docs/PERFORMANCE.md index 7bf6d3751..d8354709d 100644 --- a/docs/PERFORMANCE.md +++ b/docs/PERFORMANCE.md @@ -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 | | 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 includes the first visual and data settling window. All three samples reached the display ceiling during both motion and rest. diff --git a/scripts/package-boundaries.json b/scripts/package-boundaries.json index 5f3bfd12e..ec76dd86f 100644 --- a/scripts/package-boundaries.json +++ b/scripts/package-boundaries.json @@ -1354,7 +1354,8 @@ "src/ui/views/panels/WildlifeSightingCard.vue", "src/ui/wildlifeSightingPlacement.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"] }, @@ -3843,7 +3844,8 @@ "src/layers/vessels/photos.js", "src/layers/flights/placed.js", "src/data/placementProvider.js", - "src/data/courseFromFixes.js" + "src/data/courseFromFixes.js", + "src/time/frameWait.js" ], "external": [ "hls.js", @@ -4570,7 +4572,8 @@ "src/data/openVesselPhoto.js", "src/layers/flights/placed.js", "src/data/placementProvider.js", - "src/data/courseFromFixes.js" + "src/data/courseFromFixes.js", + "src/time/frameWait.js" ], "external": [ "hls.js", diff --git a/src/annotations/screenAnnotationRenderer.js b/src/annotations/screenAnnotationRenderer.js index 0509a47a5..ef0448f8a 100644 --- a/src/annotations/screenAnnotationRenderer.js +++ b/src/annotations/screenAnnotationRenderer.js @@ -399,7 +399,12 @@ export function createScreenAnnotationRenderer( // 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. 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 _scratchTrackedWin = new Cesium.Cartesian2(); @@ -677,6 +682,14 @@ export function createScreenAnnotationRenderer( // safe and not jarring. function fadeTracked(trackedRect) { 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; for (const rec of records.values()) { const { anno, group } = rec; @@ -705,10 +718,10 @@ export function createScreenAnnotationRenderer( } } 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; // 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.) const opacity = String( (anno.alpha ?? 1) * (rec._trackedFade !== 1 ? rec._trackedFade : 1), diff --git a/src/app/viewer.js b/src/app/viewer.js index adaa06406..85a4e1285 100644 --- a/src/app/viewer.js +++ b/src/app/viewer.js @@ -1,4 +1,5 @@ import * as Cesium from 'cesium'; +import { IDLE_FRAME_RATE } from '../renderGovernor.js'; import { applyModelAtmosphereWorkaround } from './atmosphereCompat.js'; import { StarrySky } from '../sky/starrySky.js'; import { @@ -420,7 +421,9 @@ export function createApplicationViewer({ applicationViewerOptions(creditContainer, { showRenderLoopErrors }), ); 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. // Keep Cesium's distance-aware zoom and collision limits, with less travel // required on touch-first screens. Mouse/trackpad sensitivity stays native. diff --git a/src/data/trackedCamera.js b/src/data/trackedCamera.js index b5991835d..f79acd6ff 100644 --- a/src/data/trackedCamera.js +++ b/src/data/trackedCamera.js @@ -1,6 +1,8 @@ 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 ZOOM_INERTIA_STATES = new WeakMap(); @@ -154,7 +156,7 @@ export function clampTrackedCameraPosition( */ export function applyTrackedCameraFrame(viewer, entity, viewFrom) { if (!viewer || !entity || !viewFrom) return; - let attempts = 0; + const positionWait = createFrameWait(MAX_POSITION_WAIT_MS); const trackedTransform = new Cesium.Matrix4(); const trackedPosition = new Cesium.Cartesian3(); const resolvedViewFrom = new Cesium.Cartesian3(); @@ -184,7 +186,6 @@ export function applyTrackedCameraFrame(viewer, entity, viewFrom) { stop(); return; } - attempts += framed ? 0 : 1; // Prefer the display cache exposed by the flight layer. Calling the // CallbackProperty from preUpdate can advance dead reckoning again while // Cesium's billboard/label still holds the prior visualizer sample. At a @@ -198,7 +199,7 @@ export function applyTrackedCameraFrame(viewer, entity, viewFrom) { trackedPosition, ); if (!position) { - if (attempts >= MAX_FRAME_ATTEMPTS) stop(); + if (positionWait.tick()) stop(); return; } const transform = Cesium.Transforms.eastNorthUpToFixedFrame( diff --git a/src/data/trailRenderer.js b/src/data/trailRenderer.js index 97c7d3497..cf0bb40f6 100644 --- a/src/data/trailRenderer.js +++ b/src/data/trailRenderer.js @@ -33,6 +33,7 @@ */ import * as Cesium from 'cesium'; import { registerPickOwner } from './pickRegistry.js'; +import { createFrameWait } from '../time/frameWait.js'; // Round 6: trail ENTITIES are pickable (the old Primitive had // 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([]); /** @constant {number} Points per chunk; adjacent chunks share one point. */ export const CHUNK_POINTS = 128; -/** @constant {number} Visible frames a frozen chunk's stand-in waits for its - * static geometry before it is dropped anyway. */ -const STAND_IN_MAX_FRAMES = 600; +/** @constant {number} Drawn time (ms) a frozen chunk's stand-in waits for its + * static geometry while the trail is shown before it is dropped anyway. */ +const STAND_IN_MAX_MS = 10_000; /** * 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); let destroyed = false; 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 = []; /** Newest chunk of the newest segment: the only part that changes. */ let tail = NO_POSITIONS; @@ -152,9 +153,11 @@ export function createTrail(viewer, { color, width = 2.5 }) { function staticReady(chunk) { const display = viewer.dataSourceDisplay; if (typeof display?.getBoundingSphere !== 'function') return true; - if (!visible) return false; - chunk.frames += 1; - if (chunk.frames > STAND_IN_MAX_FRAMES) return true; + if (!visible) { + chunk.wait.pause(); + return false; + } + if (chunk.wait.tick()) return true; try { return ( display.getBoundingSphere(chunk.entity, false, scratchSphere) === @@ -262,7 +265,7 @@ export function createTrail(viewer, { color, width = 2.5 }) { positions, entity: addEntity(positions), standIn: true, - frames: 0, + wait: createFrameWait(STAND_IN_MAX_MS), }); i = end; } diff --git a/src/data/trailRenderer.test.mjs b/src/data/trailRenderer.test.mjs index bcf256db4..3bad9e8a3 100644 --- a/src/data/trailRenderer.test.mjs +++ b/src/data/trailRenderer.test.mjs @@ -287,3 +287,38 @@ test('replacing the newest point and removing points inside the trail draws exac for (const run of drawnRuns(viewer)) 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; + } +}); diff --git a/src/renderGovernor.js b/src/renderGovernor.js index 215132c1c..1fc953307 100644 --- a/src/renderGovernor.js +++ b/src/renderGovernor.js @@ -28,12 +28,24 @@ * short stable strings ('flights', 'traffic', 'style-anim', …) so the * 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. */ +/** Frames a second the viewer ticks while nothing moves. */ +export const IDLE_FRAME_RATE = 60; + let _viewer = null; let _installed = false; 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). */ const _recentRequests = []; @@ -43,6 +55,7 @@ function applyMode() { if (!_installed || !_viewer?.scene) return; const continuous = _holds.size > 0; const scene = _viewer.scene; + _viewer.targetFrameRate = continuous ? undefined : IDLE_FRAME_RATE; if (scene.requestRenderMode === !continuous) return; scene.requestRenderMode = !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, * 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 * in tests without a viewer. * @param {Cesium.Viewer} viewer + * @param {{setTimeout?: Function, clearTimeout?: Function}} [timers] Injectable + * timers for tests. * @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) throw new TypeError('installRenderGovernor requires a Cesium viewer'); _viewer = viewer; @@ -69,6 +168,12 @@ export function installRenderGovernor(viewer) { // idle means idle. All re-renders are camera/tiles (Cesium-native) or // explicit requests. viewer.scene.maximumRenderTimeChange = Infinity; + _removeCameraListeners?.(); + _holds.delete('camera'); + _removeCameraListeners = watchCameraMotion( + viewer.camera ?? viewer.scene.camera, + timers, + ); applyMode(); } @@ -132,6 +237,8 @@ export function getRenderGovernorDiagnostics() { /** Release the installed viewer after its animation owners have stopped. */ export function uninstallRenderGovernor(viewer) { if (_viewer !== viewer) return; + _removeCameraListeners?.(); + _removeCameraListeners = null; _viewer = null; _installed = false; _holds.clear(); @@ -140,6 +247,8 @@ export function uninstallRenderGovernor(viewer) { /** Test seam: reset module state between unit tests. */ export function _resetRenderGovernorForTest() { + _removeCameraListeners?.(); + _removeCameraListeners = null; _viewer = null; _installed = false; _holds.clear(); diff --git a/src/renderGovernor.test.mjs b/src/renderGovernor.test.mjs index 5057fd926..7cd1a60a4 100644 --- a/src/renderGovernor.test.mjs +++ b/src/renderGovernor.test.mjs @@ -7,6 +7,8 @@ import { governorRequestRender, getRenderGovernorDiagnostics, _resetRenderGovernorForTest, + uninstallRenderGovernor, + IDLE_FRAME_RATE, } from './renderGovernor.js'; function makeViewer() { @@ -98,3 +100,132 @@ test('holds registered before install apply at install time', () => { releaseContinuousRender('flights'); 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); +}); diff --git a/src/time/frameWait.js b/src/time/frameWait.js new file mode 100644 index 000000000..b5d470aa1 --- /dev/null +++ b/src/time/frameWait.js @@ -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; + }, + }; +} diff --git a/src/time/frameWait.test.mjs b/src/time/frameWait.test.mjs new file mode 100644 index 000000000..c8e9e253a --- /dev/null +++ b/src/time/frameWait.test.mjs @@ -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); +}); diff --git a/src/ui/shareFollow.js b/src/ui/shareFollow.js index a18deeaca..c90a4f295 100644 --- a/src/ui/shareFollow.js +++ b/src/ui/shareFollow.js @@ -1,5 +1,6 @@ import * as Cesium from 'cesium'; import { trackedDisplayPositionForCamera } from '../data/trackedCamera.js'; +import { createFrameWait } from '../time/frameWait.js'; import { SHARE_VIEW_ENTITY_KINDS, SHARE_VIEW_FOLLOW_RANGE_MAX_M, @@ -17,7 +18,8 @@ import { const KIND_BY_LAYER = new Map( 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. */ function enuOffset(origin, position) { @@ -136,6 +138,7 @@ export function applyShareFollowOffset(viewer, entity, offset) { return () => {}; const local = followOffsetToEnu(offset); let frames = 0; + const framingWait = createFrameWait(MAX_FRAMING_WAIT_MS); let remove = null; const stop = () => { remove?.(); @@ -160,7 +163,7 @@ export function applyShareFollowOffset(viewer, entity, offset) { ) : null; if (!target) { - if (frames >= MAX_FRAMES) stop(); + if (framingWait.tick()) stop(); return; } // The offset is east/north/up at the entity; the follow's own frame may