From 0ed6cde956d0b141f066853a847113796b4cc8a0 Mon Sep 17 00:00:00 2001 From: Sameh Khamis Date: Mon, 16 Nov 2026 14:10:01 -0800 Subject: [PATCH] Idle frame rate in the app, timed line batching, KEY REQUIRED status Three fixes to how the globe draws and reports loading. **The idle frame rate is the app's rule.** The Cesium frame port capped the loop at `IDLE_FRAME_RATE` whenever nothing held it, so the rule lived inside the renderer. The render governor now sets the rate: the display's own while the loop is held, `IDLE_FRAME_RATE` while not. The frame port gains `onHeldChange(cb)`, which says when its first hold is taken and its last released (animated visual styles included), so the governor hears every hold. The quality setting's frame-rate cap is kept apart from the governor's rate, and the loop draws at the lower of the two, so neither overwrites the other. **Line batching is timed.** A line set waited 30 drawn frames before its unchanged lines settled into a static batch (300 for the long wait), so the batch built twice as fast at 120 Hz as at 60 Hz, and took seconds at the idle rate. It now waits `SETTLE_MS` (500 ms) and `LONG_SETTLE_MS` (5 s), and moved shapes go back into their batches on the same timing. **KEY REQUIRED.** A layer that cannot load without a provider key ended the global status chip LOAD FAILED. The chip now has a KEY REQUIRED outcome, ranked below a real failure: a layer whose stats say `keyRequired` ends KEY REQUIRED, any other failure still ends LOAD FAILED. Vessels report a missing AISStream key as `keyRequired` and name the key in the panel; a later outage clears it, as it is no longer the key that is missing. Checked: the full suite (new tests for `onHeldChange`, the quality cap against the governor's rate, timed settling, and the chip with and without a key), format, boundaries, build, the stub renderer boot and the Cesium conformance run; in the browser, the idle and held frame rates; and the first-run check now asserts that with no keys set the chip never says LOAD FAILED. --- docs/CURRENT-STATE.md | 31 ++++---- docs/PERFORMANCE.md | 2 +- scripts/qa-firstrun.mjs | 17 +++-- src/firstRunExperience.js | 13 +--- src/firstRunExperience.test.mjs | 18 +++-- src/layers/vessels/ingestion.js | 4 + src/layers/vessels/ingestion.test.mjs | 38 ++++++++++ src/layers/vessels/ownership.test.mjs | 18 +++++ src/layers/vessels/queries.js | 3 + src/loadingFeedback.js | 46 ++++++++---- src/loadingFeedback.test.mjs | 100 +++++++++++++++++++++++-- src/render/cesium/appRenderer.js | 3 - src/render/cesium/appRenderer.test.mjs | 24 ++++-- src/render/cesium/applicationViewer.js | 5 +- src/render/cesium/draw.js | 66 +++++++++------- src/render/cesium/draw.test.mjs | 73 ++++++++++++++---- src/render/cesium/frame.js | 7 ++ src/render/cesium/frame.test.mjs | 17 +++++ src/render/cesium/harness.js | 1 + src/render/cesium/ports.js | 54 +++++++------ src/render/cesium/ports.test.mjs | 50 ++++++++----- src/render/cesium/quality.js | 15 +++- src/render/conformance/checks/ports.js | 20 +++++ src/render/contract/frame.d.ts | 5 ++ src/render/contract/index.js | 1 + src/render/stub/index.js | 21 +++++- src/renderGovernor.js | 34 +++++++-- src/renderGovernor.test.mjs | 59 +++++++++++++-- src/sources/live/standalone.js | 2 + src/sources/live/standalone.test.mjs | 27 +++++++ src/testSupport/fakeFramePort.mjs | 23 +++++- src/ui/shellFeedback.js | 1 + src/ui/styles/status.css | 10 ++- 33 files changed, 629 insertions(+), 179 deletions(-) create mode 100644 src/sources/live/standalone.test.mjs diff --git a/docs/CURRENT-STATE.md b/docs/CURRENT-STATE.md index 811e2a1fd..6d4b2c853 100644 --- a/docs/CURRENT-STATE.md +++ b/docs/CURRENT-STATE.md @@ -12,11 +12,13 @@ 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 Cesium frame port (`src/render/cesium/ports.js`, its `idleFps`) caps a -parked scene at `IDLE_FRAME_RATE` (60, `src/renderGovernor.js`) ticks a -second while no hold is out, 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 frame port takes over. Through the idle +The render governor (`src/renderGovernor.js`) caps a parked scene at +`IDLE_FRAME_RATE` (60) ticks a second while nothing holds the loop, because +Cesium still runs the clock, data sources and update listeners on every +animation frame even when it skips the draw, and lifts the cap while anything +does: the frame port tells it when the loop's first hold is taken and its last +released, its own holds (animated visual styles) included. The viewer starts +at that cap until the governor is installed. Through the idle render governor, the camera port 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. The world clock holds continuous render while @@ -3809,10 +3811,10 @@ which embeds the MAP_KEY. > a layer that needs no key, already holds one, or names a key the registry does > not recognise. The earthquakes half > still delivers in full. The shared loading reducer now treats an explicitly -> declared missing optional key as a configured terminal state rather than a -> failed multi-layer mission, so the global chip completes without showing -> `LOAD FAILED`. A genuine lifecycle or fetch failure still retains failure -> priority. +> declared missing optional key as its own terminal state rather than a +> failed multi-layer mission, so the global chip ends `KEY REQUIRED` (amber) +> instead of `LOAD FAILED`, on the first load and on every refresh. A genuine +> lifecycle or fetch failure still retains failure priority. > > **Acceptance changed with that ruling (2026-08-23).** `qa-firstrun` no longer > asserts "a keyless Environmental never shows a failure chip" — that stopped @@ -4504,12 +4506,13 @@ down | auth-failed` (plus the unchanged `missing-key`/`unsupported`) with > specific error or availability state. The shared presentation is delayed to > avoid flashes, visible outside the rails, and retained in > Cockpit. One continuous overlapping load interval retains the strongest -> terminal outcome (`failed`, then `cancelled`, then `complete`) until every -> participant settles, so a later success cannot mask an earlier failure. -> A participating producer's terminal error, unavailable status, or -> key-required state also outranks generic completion without requiring a +> terminal outcome (`failed`, then `key required`, then `cancelled`, then +> `complete`) until every participant settles, so a later success cannot +> mask an earlier failure. A participating producer's terminal error or +> unavailable status also outranks generic completion without requiring a > separate manager failure event; AIS first-connect expiry therefore ends as -> `LOAD FAILED`, not `LOAD COMPLETE`. +> `LOAD FAILED`, not `LOAD COMPLETE`. A producer whose only problem is a +> missing provider key (`stats.keyRequired`) ends the batch `KEY REQUIRED`. > Slow disable work is labeled as turning live data off rather than > as a completed load. Street Traffic's dedicated sync chip shows genuine > work and one bounded completion; steady TomTom coverage, including 0%, does diff --git a/docs/PERFORMANCE.md b/docs/PERFORMANCE.md index 8b33ce624..32f5fdf03 100644 --- a/docs/PERFORMANCE.md +++ b/docs/PERFORMANCE.md @@ -34,7 +34,7 @@ hardware-rendered overlay scenes. 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 (the Cesium frame port's idle rate, +times a second when parked (the render governor's idle rate, `IDLE_FRAME_RATE` in `src/renderGovernor.js`). The initial-settle measurement is the more useful launch reference because it diff --git a/scripts/qa-firstrun.mjs b/scripts/qa-firstrun.mjs index c8291ed62..021d1b58d 100644 --- a/scripts/qa-firstrun.mjs +++ b/scripts/qa-firstrun.mjs @@ -590,14 +590,9 @@ async function main() { * * KEYED — both datasets must actually arrive, and a failure banner in * that state is a real defect, so the chip IS asserted. - * KEYLESS — only the LAYER ROW is asserted: FIRMS reports KEY REQUIRED, - * which is the honest surface a keyless visitor is judged on. - * The GLOBAL chip is deliberately NOT asserted in either - * direction here: it has no key-required terminal state and - * folds that row into a misleading LOAD FAILED. That - * aggregation is a defect in the shared state machine - * (`src/loadingFeedback.js`), LEDGERED post-launch — it is not - * a desirable outcome and not this tile's contract. + * KEYLESS — the LAYER ROW reports KEY REQUIRED, and the GLOBAL chip + * never says LOAD FAILED: a missing key ends the batch + * KEY REQUIRED (`src/loadingFeedback.js`). */ const keyless = state.firmsError === 'KEY REQUIRED'; console.log(` \x1b[2m FIRMS key state: ${keyless ? 'KEYLESS' : 'KEYED'} ` @@ -613,6 +608,12 @@ async function main() { (state.counts.earthquakes ?? 0) > 0, `${state.counts.earthquakes} quakes`, ); + const keylessChip = await readLoadingChip(page); + record( + 'KEYLESS: the global chip never says LOAD FAILED for a missing key', + !keylessChip.some((entry) => /LOAD FAILED/i.test(entry)), + keylessChip.join(' → ') || 'no chip', + ); } else { record( 'KEYED: both datasets actually arrive', diff --git a/src/firstRunExperience.js b/src/firstRunExperience.js index b1a38a273..79d5460ae 100644 --- a/src/firstRunExperience.js +++ b/src/firstRunExperience.js @@ -98,15 +98,10 @@ export const FIRST_RUN_MISSIONS = Object.freeze({ // for the FULLY CONFIGURED experience (owner ruling, 2026-08-23): the tile // promises both, so it turns on both, and the subcopy in index.html says so. // - // Keyless, FIRMS is honest where it counts — its own layer row reads - // "UNAVAILABLE · NASA FIRMS · LIVE · KEY REQUIRED", and the quakes half of - // the tile still delivers in full. What is NOT honest is the GLOBAL status - // chip, which has no key-required terminal state and folds that row into - // "LOAD FAILED". That aggregation is the defect, not this preset: fixing it - // means a KEY REQUIRED terminal state in src/loadingFeedback.js, a state - // machine shared by every layer and not a thing to refactor the night - // before a launch. LEDGERED post-launch. Until it lands, keyless visitors - // are judged on the layer row, which tells them the truth. + // Keyless, FIRMS says so: its layer row reads + // "UNAVAILABLE · NASA FIRMS · LIVE · KEY REQUIRED", the global status chip + // ends KEY REQUIRED (src/loadingFeedback.js), and the quakes half of the + // tile still delivers in full. layerIds: Object.freeze(['earthquakes', 'local-firms']), busyKey: msg('Scanning active events…'), }), diff --git a/src/firstRunExperience.test.mjs b/src/firstRunExperience.test.mjs index e81e4651e..ef0af4df4 100644 --- a/src/firstRunExperience.test.mjs +++ b/src/firstRunExperience.test.mjs @@ -386,8 +386,13 @@ test('one ESC does one thing — a Cockpit utility disclosure stops later docume // they own the same contract: their capture handler is the only one that can // keep a later document listener (Cockpit exit, the launcher) off the key, and // only the immediate form does it. - const utilityEsc = ui.slice(ui.indexOf('if (!displayOpen && !radioOpen) return;')); - const claim = utilityEsc.slice(0, utilityEsc.indexOf('setCockpitDisclosure(kind, false')); + const utilityEsc = ui.slice( + ui.indexOf('if (!displayOpen && !radioOpen) return;'), + ); + const claim = utilityEsc.slice( + 0, + utilityEsc.indexOf('setCockpitDisclosure(kind, false'), + ); assert.match(claim, /event\.preventDefault\(\);/); assert.match(claim, /event\.stopImmediatePropagation\(\);/); assert.doesNotMatch( @@ -606,11 +611,8 @@ test('the tile is the FULLY CONFIGURED experience: quakes and fires together', ( const environmental = FIRST_RUN_MISSIONS.environmental; assert.deepEqual(environmental.layerIds, ['earthquakes', 'local-firms']); - // Keyless, the honest surface is the LAYER ROW ("KEY REQUIRED"), which the - // FIRMS layer already reports. The misleading part is the GLOBAL chip folding - // that row into LOAD FAILED — a defect in the shared state machine, ledgered - // post-launch, and the note must stay where the next editor will read it - // rather than being re-discovered as a launcher bug. + // Keyless, FIRMS says so on its layer row and in the global chip (both + // KEY REQUIRED), and the note says where the chip's ending comes from. const module = fs.readFileSync( new URL('./firstRunExperience.js', import.meta.url), 'utf8', @@ -621,7 +623,7 @@ test('the tile is the FULLY CONFIGURED experience: quakes and fires together', ( ); assert.match(table, /KEY REQUIRED/); assert.match(table, /src\/loadingFeedback\.js/); - assert.match(table, /LEDGERED post-launch/); + assert.match(table, /global status chip\s+\/\/\s+ends KEY REQUIRED/); }); test('every visitor gets the same tile — there is no degraded keyless variant', async () => { diff --git a/src/layers/vessels/ingestion.js b/src/layers/vessels/ingestion.js index c5a2ca74c..b70d1ee88 100644 --- a/src/layers/vessels/ingestion.js +++ b/src/layers/vessels/ingestion.js @@ -121,6 +121,10 @@ export function createIngestion({ ownsAisRequest(requestController, requestSessionId) && error?.name !== 'AbortError' ) { + // The key is missing only while the source says so; any other + // failure is an outage, not a key to add. + feed.transportStatus = + error?.code === 'key-required' ? 'missing-key' : null; markUnavailable(error?.message || msg('AIS live load failed')); console.warn('[Data:ais-live-vessels]', feed.error, error); } diff --git a/src/layers/vessels/ingestion.test.mjs b/src/layers/vessels/ingestion.test.mjs index 1366ca61d..6c1a90baa 100644 --- a/src/layers/vessels/ingestion.test.mjs +++ b/src/layers/vessels/ingestion.test.mjs @@ -147,3 +147,41 @@ test('vessels are asked for by the area in view, and again only when the view mo await ingestion.refreshIfMoved(); assert.deepEqual(asked.at(-1), { maxRows: 500 }); }); + +test('a source refusing for want of a key leaves the feed waiting for its key', async () => { + const keyless = Object.assign(new Error('AISSTREAM_API_KEY not set'), { + code: 'key-required', + }); + const probe = setup({ + getSnapshot: async () => { + throw keyless; + }, + }); + await probe.methods.update(); + assert.equal(probe.feed.transportStatus, 'missing-key'); + assert.equal(probe.feed.error, 'AISSTREAM_API_KEY not set'); + const down = setup({ + getSnapshot: async () => { + throw new Error('feed down'); + }, + }); + await down.methods.update(); + assert.notEqual(down.feed.transportStatus, 'missing-key'); +}); + +test('a source failing for another reason after a missing key is an outage, not a key to add', async () => { + let fail = Object.assign(new Error('AISSTREAM_API_KEY not set'), { + code: 'key-required', + }); + const probe = setup({ + getSnapshot: async () => { + throw fail; + }, + }); + await probe.methods.update(); + assert.equal(probe.feed.transportStatus, 'missing-key'); + fail = new Error('feed down'); + await probe.methods.update(); + assert.equal(probe.feed.transportStatus, null); + assert.equal(probe.feed.error, 'feed down'); +}); diff --git a/src/layers/vessels/ownership.test.mjs b/src/layers/vessels/ownership.test.mjs index 265c25e27..b4b8772ed 100644 --- a/src/layers/vessels/ownership.test.mjs +++ b/src/layers/vessels/ownership.test.mjs @@ -601,3 +601,21 @@ test('a virtual aid to navigation keeps its disc and its virtual flag', async () assert.equal(layer.testing._vesselRecordForTest('993672009').virtual, true); assert.match(atob(icons.item('993672009').image.split(',')[1]), / { + let current = snapshot([], { + transportStatus: 'missing-key', + complete: false, + }); + const { layer } = setup({ + async getSnapshot() { + return current; + }, + }); + assert.equal(layer.requiresKeyId, 'aisstream'); + await layer.update(); + assert.equal(layer.getStats().keyRequired, true); + current = snapshot([observation('111')]); + await layer.update(); + assert.equal(layer.getStats().keyRequired, false); +}); diff --git a/src/layers/vessels/queries.js b/src/layers/vessels/queries.js index 38bf0f5b7..d5fa214f0 100644 --- a/src/layers/vessels/queries.js +++ b/src/layers/vessels/queries.js @@ -299,6 +299,8 @@ export function createQueries({ icon: '◭', source: 'AISStream', + // Without an AISStream key the feed cannot start; the panel names the key. + requiresKeyId: 'aisstream', updateInterval: REFRESH_MS, @@ -713,6 +715,7 @@ export function createQueries({ ? 'unavailable' : undefined, transportStatus: state.feed.transportStatus, + keyRequired: state.feed.transportStatus === 'missing-key', lastMessageAt: state.feed.lastMessageAt, rawRowCount: state.feed.rawRowCount, acceptedRowCount: state.feed.acceptedRowCount, diff --git a/src/loadingFeedback.js b/src/loadingFeedback.js index b4ea03ba1..3da12d026 100644 --- a/src/loadingFeedback.js +++ b/src/loadingFeedback.js @@ -82,16 +82,22 @@ export function normalizeLayerLoading(layer = {}) { }; } +/** + * A batch's ending from its layers' stats: a layer that failed fails it; a + * layer only waiting for its provider key (whose error is that missing key) + * ends it KEY REQUIRED, which asks the user to act rather than reporting a + * fault. + */ function terminalFromParticipantStats(summary, participantIds) { if (!participantIds?.length) return null; const participants = new Set(participantIds); - return summary.records.some( - (record) => - participants.has(record.id) && - (record.error || record.unavailable || record.keyRequired), - ) - ? 'error' - : null; + let keyRequired = false; + for (const record of summary.records) { + if (!participants.has(record.id)) continue; + if (record.keyRequired) keyRequired = true; + else if (record.error || record.unavailable) return 'error'; + } + return keyRequired ? 'key-required' : null; } /** Aggregate all manager layers without changing their lifecycle authority. */ @@ -272,17 +278,26 @@ export function reduceTrafficSyncFeedback( }; } -function terminalFromEvent(event) { +/** + * A lifecycle event's ending. A layer that failed only for want of its + * provider key (its stats say `keyRequired`) ends KEY REQUIRED on every + * load or refresh, not just the first. + */ +function terminalFromEvent(event, summary) { const type = String(event?.type || ''); if (type === 'visibility-failed' || type === 'refresh-failed' || event?.error) - return 'error'; + return summary?.records?.some( + (record) => record.id === event?.layerId && record.keyRequired, + ) + ? 'key-required' + : 'error'; if (type === 'visibility-cancelled' || event?.cancelled) return 'cancelled'; if (type === 'visibility' || type === 'refresh') return 'complete'; return null; } function mergeTerminalOutcome(current, next) { - const severity = { complete: 1, cancelled: 2, error: 3 }; + const severity = { complete: 1, cancelled: 2, 'key-required': 3, error: 4 }; if (!next) return current || null; if (!current || severity[next] > severity[current]) return next; return current; @@ -306,7 +321,7 @@ export function reduceLoadingFeedback(previous, summary, nowMs, event = null) { beginning ? null : state.batchOutcome, terminalFromParticipantStats(summary, activeIds), ), - eventParticipates ? terminalFromEvent(event) : null, + eventParticipates ? terminalFromEvent(event, summary) : null, ); return { phase: 'loading', @@ -325,7 +340,7 @@ export function reduceLoadingFeedback(previous, summary, nowMs, event = null) { failedEventIds: [ ...new Set([ ...(beginning ? [] : state.failedEventIds || []), - ...(eventParticipates && terminalFromEvent(event) === 'error' + ...(eventParticipates && terminalFromEvent(event, summary) === 'error' ? [eventLayerId] : []), ]), @@ -343,13 +358,13 @@ export function reduceLoadingFeedback(previous, summary, nowMs, event = null) { state.batchOutcome, terminalFromParticipantStats(summary, state.activeIds), ), - eventParticipates ? terminalFromEvent(event) : null, + eventParticipates ? terminalFromEvent(event, summary) : null, ) || 'complete'; const wasVisible = state.visible || now >= state.showAt; if (!wasVisible && terminal === 'complete') return createLoadingFeedbackState(); const dwell = - terminal === 'error' + terminal === 'error' || terminal === 'key-required' ? LOADING_FAILURE_DWELL_MS : LOADING_TERMINAL_DWELL_MS; return { @@ -362,7 +377,7 @@ export function reduceLoadingFeedback(previous, summary, nowMs, event = null) { failedEventIds: [ ...new Set([ ...(state.failedEventIds || []), - ...(eventParticipates && terminalFromEvent(event) === 'error' + ...(eventParticipates && terminalFromEvent(event, summary) === 'error' ? [eventLayerId] : []), ]), @@ -424,6 +439,7 @@ export function presentLoadingFeedback(state, summary, nowMs) { const labels = { complete: 'LOAD COMPLETE', cancelled: 'LOAD CANCELLED', + 'key-required': 'KEY REQUIRED', error: 'LOAD FAILED', }; const label = diff --git a/src/loadingFeedback.test.mjs b/src/loadingFeedback.test.mjs index ab26f6a3e..d5fa36c1f 100644 --- a/src/loadingFeedback.test.mjs +++ b/src/loadingFeedback.test.mjs @@ -474,15 +474,15 @@ test('reveals sustained loading and then a bounded completion state', () => { ); }); -test('terminal loading feedback centers its label without an empty detail slot', () => { +test('terminal loading feedback, KEY REQUIRED included, centers its label without an empty detail slot', () => { const css = readStylesheet(new URL('../style.css', import.meta.url)); assert.match( css, - /#global-loading-status:is\(\s*\[data-state='complete'\],\s*\[data-state='cancelled'\],\s*\[data-state='error'\]\s*\)\s*\{[\s\S]*?justify-content:\s*center;[\s\S]*?text-align:\s*center;/, + /#global-loading-status:is\(\s*\[data-state='complete'\],\s*\[data-state='cancelled'\],\s*\[data-state='key-required'\],\s*\[data-state='error'\]\s*\)\s*\{[\s\S]*?justify-content:\s*center;[\s\S]*?text-align:\s*center;/, ); assert.match( css, - /#global-loading-status:is\(\s*\[data-state='complete'\],\s*\[data-state='cancelled'\],\s*\[data-state='error'\]\s*\)\s*#global-loading-detail\s*\{\s*display:\s*none;/, + /#global-loading-status:is\(\s*\[data-state='complete'\],\s*\[data-state='cancelled'\],\s*\[data-state='key-required'\],\s*\[data-state='error'\]\s*\)\s*#global-loading-detail\s*\{\s*display:\s*none;/, ); }); @@ -618,7 +618,7 @@ test('AIS first-connect grace expiry reports failure even without a terminal man ); }); -test('participant stats failure outranks a simultaneous visibility completion', () => { +test('a participant waiting for its key outranks a simultaneous visibility completion', () => { const enabling = aggregateLayerLoading([ { id: 'ais-live-vessels', @@ -645,7 +645,97 @@ test('participant stats failure outranks a simultaneous visibility completion', enabled: true, }); - assert.equal(state.terminal, 'error'); + assert.equal(state.terminal, 'key-required'); + const view = presentLoadingFeedback(state, missingKey, 250); + assert.equal(view.label, 'KEY REQUIRED'); + assert.equal(view.state, 'key-required'); + assert.equal( + state.hideAt, + 250 + LOADING_FAILURE_DWELL_MS, + 'shown long enough to read', + ); +}); + +test('a keyless layer’s refresh failing ends KEY REQUIRED, and another layer’s LOAD FAILED', () => { + const refreshEnd = (layer) => { + const refreshing = aggregateLayerLoading([ + { + ...layer, + enabled: true, + lifecycleState: 'enabled', + stats: { ...layer.stats, refreshing: true }, + }, + ]); + let state = reduceLoadingFeedback( + createLoadingFeedbackState(), + refreshing, + 0, + ); + state = reduceLoadingFeedback(state, refreshing, 200); + const done = aggregateLayerLoading([ + { ...layer, enabled: true, lifecycleState: 'enabled' }, + ]); + state = reduceLoadingFeedback(state, done, 300, { + type: 'refresh-failed', + layerId: layer.id, + error: new Error(layer.stats.error), + }); + return presentLoadingFeedback(state, done, 300).label; + }; + assert.equal( + refreshEnd({ + id: 'ais-live-vessels', + stats: { keyRequired: true, error: 'AISSTREAM_API_KEY not set' }, + }), + 'KEY REQUIRED', + ); + assert.equal( + refreshEnd({ id: 'ais-live-vessels', stats: { error: 'feed down' } }), + 'LOAD FAILED', + ); +}); + +test('a missing key ends a batch KEY REQUIRED, and another layer failing still ends it LOAD FAILED', () => { + const loading = (ids) => + aggregateLayerLoading( + ids.map((id) => ({ id, lifecycleState: 'enabling' })), + ); + const ended = (layers) => { + let state = reduceLoadingFeedback( + createLoadingFeedbackState(), + loading(layers.map((layer) => layer.id)), + 0, + ); + state = reduceLoadingFeedback( + state, + loading(layers.map((layer) => layer.id)), + 200, + ); + const done = aggregateLayerLoading( + layers.map((layer) => ({ + ...layer, + enabled: true, + lifecycleState: 'enabled', + })), + ); + state = reduceLoadingFeedback(state, done, 300); + return presentLoadingFeedback(state, done, 300).label; + }; + // A keyless layer's own error is the missing key. + const keyless = { + id: 'ais-live-vessels', + stats: { keyRequired: true, error: 'AISSTREAM_API_KEY not set' }, + }; + assert.equal(ended([keyless]), 'KEY REQUIRED'); + assert.equal( + ended([keyless, { id: 'quakes', stats: { count: 3 } }]), + 'KEY REQUIRED', + ); + assert.equal( + ended([keyless, { id: 'flights', stats: { error: 'Failed' } }]), + 'LOAD FAILED', + ); + assert.equal(ended([{ id: 'quakes', stats: { count: 3 } }]), 'LOAD COMPLETE'); }); test('retains the worst terminal outcome until every concurrent load drains', () => { diff --git a/src/render/cesium/appRenderer.js b/src/render/cesium/appRenderer.js index d0673069a..49cb009f4 100644 --- a/src/render/cesium/appRenderer.js +++ b/src/render/cesium/appRenderer.js @@ -30,7 +30,6 @@ import { bindRenderer } from '../rendererOf.js'; import { FREE_LOOK_MAX_HEIGHT_METERS } from '../../globeInView.js'; import { createCesiumInput } from './input.js'; import { cesiumCapabilities, createCesiumPorts } from './ports.js'; -import { IDLE_FRAME_RATE } from '../../renderGovernor.js'; import { cesiumMapEngine } from './mapEngine.js'; import { installFreeLookHeightLimit } from './freeLookLimit.js'; import { trimStaleSceneCommands } from './sceneCommandRelease.js'; @@ -128,8 +127,6 @@ export function createCesiumRendererPlugin({ capabilities = new ReadonlySet(cesiumCapabilities(viewer.scene)); ports = createCesiumPorts(viewer, { capabilities, - // Ticking at the display's rate only while anything moves. - idleFps: IDLE_FRAME_RATE, credentials: { googleApiKey, googleTokens, worldDataToken }, ...(cameraController ? { cameraController } : {}), ...(clock ? { now, date: () => clock.date() } : {}), diff --git a/src/render/cesium/appRenderer.test.mjs b/src/render/cesium/appRenderer.test.mjs index 6b684914a..53a26ba88 100644 --- a/src/render/cesium/appRenderer.test.mjs +++ b/src/render/cesium/appRenderer.test.mjs @@ -3,7 +3,14 @@ import test from 'node:test'; import * as Cesium from 'cesium'; import { CONTRACT_VERSION, checkRendererShape } from '../contract/index.js'; import { rendererOf } from '../rendererOf.js'; -import { IDLE_FRAME_RATE } from '../../renderGovernor.js'; +import { + _resetRenderGovernorForTest, + holdContinuousRender, + IDLE_FRAME_RATE, + installRenderGovernor, + releaseContinuousRender, + uninstallRenderGovernor, +} from '../../renderGovernor.js'; import { cesiumMapEngine } from './mapEngine.js'; import { ReadonlySet, @@ -169,7 +176,7 @@ test('the plugin wraps the viewer it is given, behind the accessor only', async assert.deepEqual(log, ['resize', 'destroy'], 'destroying twice is safe'); }); -test('the application’s loop ticks at the idle rate while nothing moves, and at the display’s while anything does', async (t) => { +test('with the governor installed, the loop ticks at the idle rate while nothing moves, and at the display’s while anything does, the renderer’s own holds included', async (t) => { withDocument(t, fakeDocument()); let viewer; const plugin = createCesiumRendererPlugin({ @@ -184,12 +191,19 @@ test('the application’s loop ticks at the idle rate while nothing moves, and a container: {}, signal: new AbortController().signal, }); + installRenderGovernor(renderer.frame); + t.after(() => _resetRenderGovernorForTest()); + assert.equal(viewer.targetFrameRate, IDLE_FRAME_RATE, 'idle'); + holdContinuousRender('flights'); + assert.equal(viewer.targetFrameRate, undefined, 'a layer moving'); + releaseContinuousRender('flights'); assert.equal(viewer.targetFrameRate, IDLE_FRAME_RATE); - assert.equal(renderer.frame.diagnostics().targetFps, 0, 'no cap'); - const release = renderer.frame.holdContinuous('flights'); - assert.equal(viewer.targetFrameRate, undefined); + // As animated visual styles hold it (effects.js). + const release = renderer.frame.holdContinuous('effects:animated'); + assert.equal(viewer.targetFrameRate, undefined, 'the renderer’s own hold'); release(); assert.equal(viewer.targetFrameRate, IDLE_FRAME_RATE); + uninstallRenderGovernor(renderer.frame); renderer.destroy(); }); diff --git a/src/render/cesium/applicationViewer.js b/src/render/cesium/applicationViewer.js index 91c2f50e5..31e2622ee 100644 --- a/src/render/cesium/applicationViewer.js +++ b/src/render/cesium/applicationViewer.js @@ -106,8 +106,9 @@ export function createApplicationViewer({ }), ); try { - // Until the frame port takes over (appRenderer.js), tick at the idle - // rate so the startup load does not compete with drawing at 240 fps. + // Until the render governor takes over (src/renderGovernor.js, installed + // by src/app/scene.js), tick at the idle rate so the startup load does + // not compete with drawing at 240 fps. viewer.targetFrameRate = IDLE_FRAME_RATE; // No double-click follow or zoom: the Viewer's own (it tracked or // zoomed to the entity picked) is off. Following is a layer's click. diff --git a/src/render/cesium/draw.js b/src/render/cesium/draw.js index 3d9793d41..5cfdb0e7d 100644 --- a/src/render/cesium/draw.js +++ b/src/render/cesium/draw.js @@ -413,18 +413,25 @@ function flowTime(speed) { } /** - * Drawn frames a line set's lines stay unchanged before the solid ones - * among them settle into a static batch (`settleLines`). + * Milliseconds a line set's lines stay unchanged before the solid ones + * among them settle into a static batch (`settleLines`), and a shape set's + * moved shapes go back into its batches (`settleShapes`). Timed, so a + * batch builds as soon at every refresh rate. */ -export const SETTLE_FRAMES = 30; +export const SETTLE_MS = 500; /** * Fewer lines than this left in the collection beside a static batch wait - * `LONG_SETTLE_FRAMES` to settle, as rebuilding the batch for them costs + * `LONG_SETTLE_MS` to settle, as rebuilding the batch for them costs * more than drawing them in the collection for a while. */ export const FEW_LOOSE_LINES = 64; -export const LONG_SETTLE_FRAMES = 300; +export const LONG_SETTLE_MS = 5000; + +/** A line set's settling: waiting the short time, the long one, or done. */ +const SETTLE_SHORT = 0; +const SETTLE_LONG = 1; +const SETTLE_DONE = 2; /** * Clamped fills a set draws alone at most, each where it last moved @@ -452,12 +459,14 @@ const animating = (record) => record.gpu?.animating(); * @param {{scene: object, report: (error: unknown) => void, * capabilities?: ReadonlySet, * requestRender?: (reason: string) => void, - * date?: () => number}} options `capabilities` gate + * date?: () => number, + * now?: () => number}} options `capabilities` gate * the GPU icon sets' members (by default they all are); `requestRender`, * the frame port's, asks for the frames a GPU icon set needs on its own * (its images packed), under the reason `icons:` (by default the * scene's, with no reason); `date`, the epoch ms a `live` motion clock - * reads (by default the system clock's). + * reads (by default the system clock's); `now`, the milliseconds settling + * waits are timed by (`performance.now` by default). */ export function createCesiumDraw({ scene, @@ -465,6 +474,7 @@ export function createCesiumDraw({ capabilities = new Set(GPU_ICON_CAPABILITIES), requestRender: requestFrame = null, date = null, + now = () => performance.now(), }) { const sets = new Map(); // Fields share the sets' ids. @@ -3107,7 +3117,8 @@ export function createCesiumDraw({ record.lineBox = settling ? own : null; record.batch = null; record.batchPending = null; - record.settled = 0; + record.changedAt = now(); + record.settleStage = SETTLE_SHORT; if (!draped.size && !glows.size && !alone.length && !groundPieces.length) { noteFlows(record); return replaceHost(record, own); @@ -3581,7 +3592,8 @@ export function createCesiumDraw({ * still building drew them as they were, so it is dropped. */ function unsettle(record) { - record.settled = 0; + record.changedAt = now(); + record.settleStage = SETTLE_SHORT; const pending = record.batchPending; if (!pending) return; record.batchPending = null; @@ -3736,10 +3748,10 @@ export function createCesiumDraw({ } /** - * After a draw: a line set whose lines have not changed for - * `SETTLE_FRAMES` drawn frames starts building its static batch, of all - * its lines that `settles`, once some are still in the collection (when - * it has a batch and only a few are, after `LONG_SETTLE_FRAMES`); one + * After a draw: a line set whose lines have not changed for `SETTLE_MS` + * starts building its static batch, of all its lines that `settles`, once + * some are still in the collection (when it has a batch and only a few + * are, after `LONG_SETTLE_MS`); one * built swaps in for the collection's lines it draws (`swapBatch`). * Unchanged lines in a polyline collection cost a material id a line * every frame; in a batch they cost nothing until they change. @@ -3750,13 +3762,10 @@ export function createCesiumDraw({ swapBatch(record); return; } - if (record.settled > LONG_SETTLE_FRAMES) return; - record.settled += 1; - if ( - record.settled !== SETTLE_FRAMES && - record.settled !== LONG_SETTLE_FRAMES - ) - return; + if (record.settleStage === SETTLE_DONE) return; + const wait = + record.settleStage === SETTLE_SHORT ? SETTLE_MS : LONG_SETTLE_MS; + if (now() - record.changedAt < wait) return; // The lines that can settle still in the collection: a batch is // rebuilt whole for them, so a few wait longer, as a few cost little. let loose = 0; @@ -3765,10 +3774,12 @@ export function createCesiumDraw({ if ( record.batch && loose < FEW_LOOSE_LINES && - record.settled < LONG_SETTLE_FRAMES - ) + record.settleStage === SETTLE_SHORT + ) { + record.settleStage = SETTLE_LONG; return; - record.settled = LONG_SETTLE_FRAMES + 1; + } + record.settleStage = SETTLE_DONE; if (!loose) return; const members = []; for (const [itemId, part] of record.lineParts) { @@ -5007,7 +5018,7 @@ export function createCesiumDraw({ if (part.batch.ready) showOn(part.batch, part.id, false); } hideRetiringShape(record, item.id); - record.shapesStill = 0; + record.shapesMovedAt = now(); part.solo = true; part.pendingShow = undefined; part.look = lookOf(item); @@ -5081,7 +5092,7 @@ export function createCesiumDraw({ /** * After a draw: a shape set whose shapes drawn alone have not moved for - * `SETTLE_FRAMES` drawn frames rebuilds, so they go back into its + * `SETTLE_MS` rebuilds, so they go back into its * batches; the host drawing them alone draws until the rebuild is ready. */ function settleShapes(record) { @@ -5093,9 +5104,8 @@ export function createCesiumDraw({ break; } if (!alone) return; - record.shapesStill = (record.shapesStill ?? 0) + 1; - if (record.shapesStill < SETTLE_FRAMES) return; - record.shapesStill = 0; + if (now() - record.shapesMovedAt < SETTLE_MS) return; + record.shapesMovedAt = now(); record.rebuild(); requestRender(); } diff --git a/src/render/cesium/draw.test.mjs b/src/render/cesium/draw.test.mjs index 8a5ae33a5..63f42ad4a 100644 --- a/src/render/cesium/draw.test.mjs +++ b/src/render/cesium/draw.test.mjs @@ -5,10 +5,10 @@ import { bindRenderer, drawOf, findDraw } from '../rendererOf.js'; import { createCesiumDraw, FEW_LOOSE_LINES, - LONG_SETTLE_FRAMES, + LONG_SETTLE_MS, MOVING_SHAPES, revealUniform, - SETTLE_FRAMES, + SETTLE_MS, unboundDrawPart, } from './draw.js'; import { drawHitOf } from './drawHit.js'; @@ -93,6 +93,19 @@ test('nothing to draw into, no port', () => { }); /** A draw port over a fake scene, with its frame hooks. */ +/** + * Settling waits are timed. A test that settles times them by `frameClock` + * (`timeFrames`), which each fake frame moves on by `FRAME_MS`. + */ +const FRAME_MS = 20; +const SETTLE_FRAMES = SETTLE_MS / FRAME_MS; +const LONG_SETTLE_FRAMES = LONG_SETTLE_MS / FRAME_MS; +const frameClock = { ms: 0 }; +function timeFrames(t) { + frameClock.ms = 0; + t.mock.method(performance, 'now', () => frameClock.ms); +} + function drawOver(scene = fakeScene()) { const viewer = { scene }; const draw = drawOf(viewer); @@ -100,6 +113,7 @@ function drawOver(scene = fakeScene()) { scene, draw, frame() { + frameClock.ms += FRAME_MS; scene.preRender.raiseEvent(); scene.postRender.raiseEvent(); }, @@ -2978,8 +2992,9 @@ function settlingSet(id = 'stems') { }; } -test('unchanged solid 3D lines settle into a static batch, changed there in place', () => +test('unchanged solid 3D lines settle into a static batch, changed there in place', (t) => withImageClasses(() => { + timeFrames(t); const s = settlingSet(); const { set, frame } = s; const stem = settleStem; @@ -3114,8 +3129,24 @@ test('unchanged solid 3D lines settle into a static batch, changed there in plac set.dispose(); })); -test('many lines left beside a static batch settle as soon as they are unchanged', () => +test('lines settle after the same time at any refresh rate', (t) => withImageClasses(() => { + timeFrames(t); + const s = settlingSet(); + s.set.set([settleStem('a', 100)]); + const host = s.host(); + // Two frames are enough when they are half a second apart. + frameClock.ms = SETTLE_MS - FRAME_MS - 1; + s.frame(); + assert.equal(host.length, 1, 'not before the time'); + s.frame(); + assert.equal(host.length, 2, 'building once it has passed'); + s.set.dispose(); + })); + +test('many lines left beside a static batch settle as soon as they are unchanged', (t) => + withImageClasses(() => { + timeFrames(t); const s = settlingSet(); const { set } = s; const stems = (height) => @@ -3134,8 +3165,9 @@ test('many lines left beside a static batch settle as soon as they are unchanged set.dispose(); })); -test('an outlined solid line draws one outline material, recoloured in place, and never settles', () => +test('an outlined solid line draws one outline material, recoloured in place, and never settles', (t) => withImageClasses(() => { + timeFrames(t); const s = settlingSet(); const outlined = (core, halo) => settleStem('ring', 100, { @@ -3177,8 +3209,9 @@ test('an outlined solid line draws one outline material, recoloured in place, an s.set.dispose(); })); -test('a line that moves by as many points is written into the points it draws; by more, it takes new ones', () => +test('a line that moves by as many points is written into the points it draws; by more, it takes new ones', (t) => withImageClasses(() => { + timeFrames(t); const s = settlingSet(); const style = { kind: 'solid', @@ -3232,8 +3265,9 @@ test('a line that moves by as many points is written into the points it draws; b s.set.dispose(); })); -test('a line under half a pixel wide, which the collection does not draw, never settles', () => +test('a line under half a pixel wide, which the collection does not draw, never settles', (t) => withImageClasses(() => { + timeFrames(t); const s = settlingSet(); s.set.set([ settleStem('thin', 100, { widthPx: 0.25 }), @@ -3248,8 +3282,9 @@ test('a line under half a pixel wide, which the collection does not draw, never s.set.dispose(); })); -test('a settling line set keeps what was drawn, not the item a caller changes in place', () => +test('a settling line set keeps what was drawn, not the item a caller changes in place', (t) => withImageClasses(() => { + timeFrames(t); const s = settlingSet(); const { set } = s; const a = settleStem('a', 100); @@ -3276,8 +3311,9 @@ test('a settling line set keeps what was drawn, not the item a caller changes in set.dispose(); })); -test('a settling line set rebuilt or gone while its batch builds, or after the viewer went, lets the batch go', () => +test('a settling line set rebuilt or gone while its batch builds, or after the viewer went, lets the batch go', (t) => withImageClasses(() => { + timeFrames(t); const s = settlingSet(); const { set } = s; set.set([settleStem('a', 100), settleStem('b', 200)]); @@ -3308,17 +3344,22 @@ test('a settling line set rebuilt or gone while its batch builds, or after the v set.dispose(); })); -test('a static batch that fails to build is reported once, and its lines stay in the collection', () => +test('a static batch that fails to build is reported once, and its lines stay in the collection', (t) => withImageClasses(() => { + timeFrames(t); const scene = fakeScene(); const reported = []; const part = createCesiumDraw({ scene, report: (error) => reported.push(error), }); + const afterFrame = () => { + frameClock.ms += FRAME_MS; + part.afterRender(); + }; const set = part.port.lines({ id: 'failing' }); set.set([settleStem('a', 100)]); - for (let i = 0; i < SETTLE_FRAMES; i++) part.afterRender(); + for (let i = 0; i < SETTLE_FRAMES; i++) afterFrame(); const host = scene.added[0]; const batch = host.get(1); assert.ok(batch, 'building'); @@ -3326,11 +3367,11 @@ test('a static batch that fails to build is reported once, and its lines stay in // batch keeps the error rather than throw it every frame. batch.update({ passes: { render: true }, mode: Cesium.SceneMode.SCENE3D }); assert.ok(batch.failed, 'kept'); - part.afterRender(); + afterFrame(); assert.deepEqual(reported, [batch.failed]); assert.equal(host.length, 1, 'the build is gone'); assert.equal(host.get(0).length, 1, 'the collection draws the line'); - for (let i = 0; i < SETTLE_FRAMES * 2; i++) part.afterRender(); + for (let i = 0; i < SETTLE_FRAMES * 2; i++) afterFrame(); assert.equal(host.length, 1, 'it settles no more'); assert.equal(reported.length, 1); set.dispose(); @@ -7482,8 +7523,9 @@ test('an inertial line with a depth-fail style draws behind the surface too, tur set.dispose(); })); -test('a pattern line draws its image along it, repeated, and an inertial line turns with the sky', () => +test('a pattern line draws its image along it, repeated, and an inertial line turns with the sky', (t) => withImageClasses(() => { + timeFrames(t); const { scene, draw, frame } = drawOver(); const set = draw.lines({ id: 'orbit-rings' }); const ring = [ @@ -7777,8 +7819,9 @@ const firstGround = (host) => { return null; }; -test('moved clamped fills go back into a rebuilt batch once they have been still for a while', () => +test('moved clamped fills go back into a rebuilt batch once they have been still for a while', (t) => withTerrainHeights(() => { + timeFrames(t); const { scene, draw, frame } = drawOver(); const set = draw.shapes({ id: 'settling' }); set.set([groundBox('a', 1), groundBox('b', 2)]); diff --git a/src/render/cesium/frame.js b/src/render/cesium/frame.js index dada22146..6220f4642 100644 --- a/src/render/cesium/frame.js +++ b/src/render/cesium/frame.js @@ -161,6 +161,8 @@ export function createSceneFrame(viewer) { liveTick = null; }; const holds = new Map(); + // Told when the first hold is taken and the last released. + const heldListeners = listenerList(uncaught); const pendingRenders = new Set(); const gone = () => disposed || scene.isDestroyed?.(); const sceneTime = (time) => @@ -244,8 +246,10 @@ export function createSceneFrame(viewer) { }, holdContinuous(reason) { if (disposed) return () => {}; + const first = holds.size === 0; holds.set(reason, (holds.get(reason) ?? 0) + 1); if (!gone()) scene.requestRender(); + if (first) heldListeners.fire(true); let released = false; return () => { if (released) return; @@ -255,8 +259,10 @@ export function createSceneFrame(viewer) { else holds.delete(reason); // What changed in the last held frame still gets drawn. if (!gone()) scene.requestRender(); + if (holds.size === 0) heldListeners.fire(false); }; }, + onHeldChange: (cb) => heldListeners.on(cb), mode: () => (scene.requestRenderMode ? 'demand' : 'continuous'), diagnostics: () => ({ mode: port.mode(), @@ -324,6 +330,7 @@ export function createSceneFrame(viewer) { settleTick(false); for (const off of removers.splice(0)) off(); for (const list of Object.values(listeners)) list.clear(); + heldListeners.clear(); holds.clear(); // Waits settle rather than stay attached to a scene gone quiet. for (const done of [...pendingRenders]) done(); diff --git a/src/render/cesium/frame.test.mjs b/src/render/cesium/frame.test.mjs index e8b69447a..cac269269 100644 --- a/src/render/cesium/frame.test.mjs +++ b/src/render/cesium/frame.test.mjs @@ -190,6 +190,23 @@ test('a built frame port counts holds per reason, times out a wait, and settles unbind(); }); +test('a built frame port says when its first hold is taken and its last released', () => { + const viewer = fakeViewer(); + viewer.useDefaultRenderLoop = false; + const frame = frameOf(viewer); + const heard = []; + const off = frame.onHeldChange((held) => heard.push(held)); + const a = frame.holdContinuous('spin'); + const b = frame.holdContinuous('glow'); + a(); + assert.deepEqual(heard, [true], 'once for the first hold'); + b(); + assert.deepEqual(heard, [true, false], 'once for the last release'); + off(); + frame.holdContinuous('spin')(); + assert.deepEqual(heard, [true, false], 'nothing once off'); +}); + test('renderNow throws the error Cesium raises on renderError', () => { const listeners = new Set(); const failure = new Error('worker failed'); diff --git a/src/render/cesium/harness.js b/src/render/cesium/harness.js index 59bb1e84a..62f06cf0f 100644 --- a/src/render/cesium/harness.js +++ b/src/render/cesium/harness.js @@ -149,6 +149,7 @@ export const CESIUM_CHECKS = new Set([ 'renderer.releaseUnused', 'renderer.whenSettled', 'renderer.resize', + 'frame.onHeldChange', 'frame.setTargetFps', 'globe.setTerrain', 'globe.setPhotoreal', diff --git a/src/render/cesium/ports.js b/src/render/cesium/ports.js index 5488b0fcc..e36898330 100644 --- a/src/render/cesium/ports.js +++ b/src/render/cesium/ports.js @@ -116,22 +116,18 @@ const destroyedError = () => new Error('renderer destroyed'); * @param {{capabilities: ReadonlySet, credentials?: object, * cameraController?: import('../contract/camera').CameraControllerFactory, * now?: () => number, - * date?: () => number, - * idleFps?: number}} options + * date?: () => number}} options * The renderer's capabilities, which gate the members that need them, and * the credentials its globe loads photoreal tiles and world data with * (`googleApiKey`, `googleTokens`, `worldDataToken`). `now` is the clock * each tick reads (`performance.now` by default; a test's virtual one); * `date`, the epoch ms a `live` motion clock reads (the system clock's by - * default). With `idleFps`, the loop ticks at most that often while no - * hold is out (Cesium ticks its clock and every update listener each - * animation frame even when it draws nothing), and at the display's rate - * while one is; `setTargetFps` then caps both, and the loop starts with no - * cap of its own. Without it, the widget's own rate is the cap. - * With - * `cameraController`, the camera port is that controller's over Cesium's - * camera (`controlledCamera.js`); the ports then have `attachInput` and - * `suspendCamera`, which the renderer's input port is wired with. + * default). The loop's rate starts as the widget's own; once set, it is + * the lower of `setTargetFps`'s and the quality port's `targetFps` cap. + * With `cameraController`, the camera port is that controller's over + * Cesium's camera (`controlledCamera.js`); the ports then have + * `attachInput` and `suspendCamera`, which the renderer's input port is + * wired with. */ export function createCesiumPorts( widget, @@ -141,7 +137,6 @@ export function createCesiumPorts( cameraController, now: clockNow = () => performance.now(), date = null, - idleFps = 0, }, ) { const scene = widget.scene; @@ -290,27 +285,30 @@ export function createCesiumPorts( // Holds keep the loop drawing every frame; counted per reason. const holds = new Map(); + // Told when the first hold is taken and the last released. + const heldListeners = listenerList(report); function applyHolds() { const continuous = holds.size > 0; - if (idleFps > 0) applyRate(); if (scene.requestRenderMode === !continuous) return; scene.requestRenderMode = !continuous; - } - /** The loop's rate: the cap, and at most `idleFps` while nothing holds. */ - function applyRate() { - const idle = holds.size === 0 && idleFps > 0; - const rate = - idle && !(targetFps > 0 && targetFps < idleFps) ? idleFps : targetFps; - widget.targetFrameRate = rate || undefined; + heldListeners.fire(continuous); } // On demand means drawn when asked, held or the view changed: never // because scene time moved on by itself. With no holds yet, it starts so. scene.maximumRenderTimeChange = Infinity; scene.requestRenderMode = true; let suspended = false; - let targetFps = - idleFps <= 0 && widget.targetFrameRate > 0 ? widget.targetFrameRate : 0; - if (idleFps > 0) applyRate(); + // The rate `setTargetFps` asks for (the application's), and the quality + // port's cap; the loop draws at the lower of those set. + let targetFps = widget.targetFrameRate > 0 ? widget.targetFrameRate : 0; + let qualityFps = 0; + function applyRate() { + const rate = + targetFps > 0 && qualityFps > 0 + ? Math.min(targetFps, qualityFps) + : targetFps || qualityFps; + widget.targetFrameRate = rate || undefined; + } // Pending one-shot renders; disposal rejects them rather than leave them // attached to a scene that will not render again. @@ -369,6 +367,7 @@ export function createCesiumPorts( if (holds.size === 0) scene.requestRender(); }; }, + onHeldChange: (cb) => heldListeners.on(cb), /** Cesium can idle, so it draws on demand. */ mode: () => 'demand', diagnostics: () => ({ @@ -429,6 +428,7 @@ export function createCesiumPorts( capabilities, requestRender: (reason) => frame.requestRender(reason), date, + now: clockNow, }); const { port: draw, sets, tilesets } = drawPart; @@ -494,6 +494,13 @@ export function createCesiumPorts( report, tickStarted: () => tickNow, gl: capabilities.has('gpuTiming') ? webglContext(scene) : null, + fpsCap: { + get: () => qualityFps, + set(fps) { + qualityFps = fps > 0 ? fps : 0; + applyRate(); + }, + }, }); const creditsPart = createCesiumCredits({ @@ -837,6 +844,7 @@ export function createCesiumPorts( // A listener that disposes the renderer stops the rest of its event. for (const list of Object.values(rendererListeners)) list.clear(); for (const list of Object.values(frameListeners)) list.clear(); + heldListeners.clear(); drawPart.dispose(); cameraPart.dispose(); creditsPart.dispose(); diff --git a/src/render/cesium/ports.test.mjs b/src/render/cesium/ports.test.mjs index de3642949..04ef937fd 100644 --- a/src/render/cesium/ports.test.mjs +++ b/src/render/cesium/ports.test.mjs @@ -507,26 +507,40 @@ test('suspend stops the loop at once and resumes it; target fps caps it', () => ports.dispose(); }); -test('with an idle rate, idle ticks at it and anything held draws at the display rate', () => { +test('the quality cap and the rate setTargetFps asks for draw at the lower, and neither overwrites the other', () => { + const { widget } = tickingWidget(); + const ports = createCesiumPorts(widget, { capabilities: all }); + assert.equal(ports.quality.get().targetFps, 0, 'no cap by default'); + ports.quality.set({ targetFps: 30 }); + ports.frame.setTargetFps(60); + assert.equal(widget.targetFrameRate, 30, 'the cap is lower'); + ports.frame.setTargetFps(0); + assert.equal(widget.targetFrameRate, 30, 'the cap holds at the display rate'); + assert.equal(ports.quality.get().targetFps, 30, 'the cap reads back'); + ports.frame.setTargetFps(24); + assert.equal(widget.targetFrameRate, 24, 'the asked rate is lower'); + ports.quality.set({ targetFps: 0 }); + assert.equal(widget.targetFrameRate, 24, 'cap lifted'); + ports.dispose(); +}); + +test('the loop says when its first hold is taken and its last released, and leaves its rate alone', () => { const { widget } = tickingWidget(); widget.targetFrameRate = 60; - const ports = createCesiumPorts(widget, { capabilities: all, idleFps: 60 }); - assert.equal(widget.targetFrameRate, 60, 'idle: the idle rate'); - assert.equal(ports.frame.diagnostics().targetFps, 0, 'no cap of its own'); - const release = ports.frame.holdContinuous('flights'); - assert.equal(widget.targetFrameRate, undefined, 'held: the display rate'); - release(); - assert.equal(widget.targetFrameRate, 60); - // A cap holds while held, and idle ticks at the lower of the two. - ports.frame.setTargetFps(30); - assert.equal(widget.targetFrameRate, 30); - const again = ports.frame.holdContinuous('flights'); - assert.equal(widget.targetFrameRate, 30); - ports.frame.setTargetFps(120); - assert.equal(widget.targetFrameRate, 120); - again(); - assert.equal(widget.targetFrameRate, 60); - assert.equal(ports.frame.diagnostics().targetFps, 120); + const ports = createCesiumPorts(widget, { capabilities: all }); + assert.equal(ports.frame.diagnostics().targetFps, 60, 'the widget’s cap'); + const heard = []; + const off = ports.frame.onHeldChange((held) => heard.push(held)); + const flights = ports.frame.holdContinuous('flights'); + const effects = ports.frame.holdContinuous('effects:animated'); + flights(); + assert.deepEqual(heard, [true], 'once for the first hold'); + effects(); + assert.deepEqual(heard, [true, false], 'once for the last release'); + assert.equal(widget.targetFrameRate, 60, 'its rate is its caller’s'); + off(); + ports.frame.holdContinuous('flights')(); + assert.deepEqual(heard, [true, false], 'heard no more once off'); ports.dispose(); }); diff --git a/src/render/cesium/quality.js b/src/render/cesium/quality.js index 09afc6c53..21c196a99 100644 --- a/src/render/cesium/quality.js +++ b/src/render/cesium/quality.js @@ -15,7 +15,10 @@ * at 0. While tile detail is lowered, a tileset added later is brought * to it on the next drawn frame; an error is written only when it * changes, since each write resets the tileset's memory-adjusted error. - * - `targetFps`: the frame port's target frame rate, 0 for none. + * - `targetFps`: a cap on the loop's frame rate, 0 for none (`fpsCap`: by + * default the frame port's own `setTargetFps`; the renderer's ports keep + * it apart from the rate the application sets there, and draw at the + * lower of the two). * * Building the port changes nothing in the scene; each setting is applied * when it is first set, and a detail set back to 1 hands each tileset and @@ -156,6 +159,10 @@ export function createCesiumQuality( limits = Cesium.ContextLimits, tickStarted = null, gl = webglContext(widget.scene), + fpsCap = { + get: () => frame.diagnostics?.().targetFps ?? 0, + set: (fps) => frame.setTargetFps(fps), + }, }, ) { const scene = widget.scene; @@ -171,7 +178,7 @@ export function createCesiumQuality( : []; // What the scene had before the port first changed it: the defaults. - const builtFps = frame.diagnostics?.().targetFps ?? 0; + const builtFps = fpsCap.get(); let msaaAtBuild = null; let shadowsAtBuild = null; // Cesium clamps the count to the context's only when it is set. @@ -334,7 +341,7 @@ export function createCesiumQuality( }, targetFps(value) { const fps = inRange(value, 0, MAX_FPS); - if (fps !== null) frame.setTargetFps(fps); + if (fps !== null) fpsCap.set(fps); }, }; @@ -343,7 +350,7 @@ export function createCesiumQuality( pixelRatio, tiles3dDetail: detail.tiles, terrainDetail: detail.terrain, - targetFps: frame.diagnostics?.().targetFps ?? 0, + targetFps: fpsCap.get(), }; if (scene.shadowMap) settings.shadows = Boolean(scene.shadowMap.enabled); if (msaaOptions().length > 1) diff --git a/src/render/conformance/checks/ports.js b/src/render/conformance/checks/ports.js index b14f5a07e..faf4a8468 100644 --- a/src/render/conformance/checks/ports.js +++ b/src/render/conformance/checks/ports.js @@ -5769,6 +5769,26 @@ fn fs_main(@location(0) uv: vec2f) -> @location(0) vec4f { ); }, ), + check( + 'frame.onHeldChange', + 'onHeldChange is told the first hold and the last release, whoever holds, and nothing once off', + (h, r) => { + const heard = []; + const off = r.frame.onHeldChange((held) => heard.push(held)); + try { + const one = r.frame.holdContinuous('conformance:one'); + const two = r.frame.holdContinuous('conformance:two'); + one(); + deepEqual(heard, [true], 'once for the first hold'); + two(); + deepEqual(heard, [true, false], 'once for the last release'); + } finally { + off(); + } + r.frame.holdContinuous('conformance:after')(); + deepEqual(heard, [true, false], 'nothing once off'); + }, + ), check( 'frame.setTargetFps', 'setTargetFps caps the loop; diagnostics say the cap, 0 the display rate', diff --git a/src/render/contract/frame.d.ts b/src/render/contract/frame.d.ts index 8c35411da..948450bb4 100644 --- a/src/render/contract/frame.d.ts +++ b/src/render/contract/frame.d.ts @@ -73,6 +73,11 @@ export interface FramePort { requestRender(reason: string): void; /** Keep drawing every frame until released. Holds are counted. */ holdContinuous(reason: string): Release; + /** + * Hear the loop start drawing every frame (its first hold, whoever took + * it) and stop (its last released): `true` held, `false` not. + */ + onHeldChange(cb: (held: boolean) => void): Off; mode(): 'demand' | 'continuous'; diagnostics(): FrameDiagnostics; /** Stop ticking while the page is hidden; resume on `false`. */ diff --git a/src/render/contract/index.js b/src/render/contract/index.js index 700f8cf58..d494467fa 100644 --- a/src/render/contract/index.js +++ b/src/render/contract/index.js @@ -118,6 +118,7 @@ export const PORTS = deepFreeze({ 'on', 'requestRender', 'holdContinuous', + 'onHeldChange', 'mode', 'diagnostics', 'suspend', diff --git a/src/render/stub/index.js b/src/render/stub/index.js index b5db25511..9eb21cfc5 100644 --- a/src/render/stub/index.js +++ b/src/render/stub/index.js @@ -187,6 +187,16 @@ export function createStubRenderer(options = {}) { const pendingReasons = []; const continuous = new Map(); let holdSeq = 0; + // Told when the first hold is taken and the last released. + const heldListeners = new Set(); + function tellHeld(held) { + for (const entry of [...heldListeners]) + try { + entry.cb(held); + } catch (error) { + report(error); + } + } const phaseListeners = { preUpdate: [], preRender: [], postRender: [] }; // The frame under way while its `preUpdate` listeners run. let updating = null; @@ -345,7 +355,16 @@ export function createStubRenderer(options = {}) { holdContinuous(reason) { const key = ++holdSeq; continuous.set(key, String(reason)); - return () => continuous.delete(key); + if (continuous.size === 1) tellHeld(true); + return () => { + if (!continuous.delete(key)) return; + if (continuous.size === 0) tellHeld(false); + }; + }, + onHeldChange(cb) { + const entry = { cb }; + heldListeners.add(entry); + return () => heldListeners.delete(entry); }, mode: () => 'demand', diagnostics: () => ({ diff --git a/src/renderGovernor.js b/src/renderGovernor.js index 7897a620e..ad160da2b 100644 --- a/src/renderGovernor.js +++ b/src/renderGovernor.js @@ -29,12 +29,15 @@ * 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. + * Frame rate: while the loop is held it draws at the display's own refresh + * rate; while nothing holds it, the governor caps it 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. The frame port says when its first hold is taken and its last + * released (`onHeldChange`), the renderer's own holds included (animated + * visual styles), so those draw at the full rate too. Camera movement takes + * a 'camera' hold from `moveStart` to `moveEnd`, so drags and flights run at + * the full rate as well. * * The governor is O(1) passive: no per-frame work of its own, ever. */ @@ -50,6 +53,13 @@ let _frame = null; const _holds = new Map(); /** Removes the camera move listeners added at install. */ let _removeCameraListeners = null; +/** Stops hearing the installed port's holds. */ +let _offHeldChange = null; + +/** The loop's rate: the display's while held, IDLE_FRAME_RATE while not. */ +function applyRate(held) { + _frame?.setTargetFps(held ? 0 : IDLE_FRAME_RATE); +} /** Debug trail of the most recent one-shot render requests (idle mode only). */ const _recentRequests = []; @@ -163,14 +173,20 @@ export function installRenderGovernor( clearTimeout: unschedule = globalThis.clearTimeout, } = {}, ) { - if (typeof frame?.holdContinuous !== 'function') + if ( + typeof frame?.holdContinuous !== 'function' || + typeof frame.onHeldChange !== 'function' + ) throw new TypeError('installRenderGovernor requires a frame port'); _removeCameraListeners?.(); _removeCameraListeners = null; releaseContinuousRender('camera'); if (_frame !== frame) { if (_frame) releaseFrameHolds(); + _offHeldChange?.(); _frame = frame; + _offHeldChange = frame.onHeldChange(applyRate); + applyRate(frame.diagnostics().holds.length > 0); for (const ownerId of _holds.keys()) holdOnFrame(ownerId); } _removeCameraListeners = watchCameraMotion(camera, { schedule, unschedule }); @@ -247,6 +263,8 @@ export function uninstallRenderGovernor(frame) { _removeCameraListeners?.(); _removeCameraListeners = null; releaseFrameHolds(); + _offHeldChange?.(); + _offHeldChange = null; _frame = null; _holds.clear(); _recentRequests.length = 0; @@ -256,6 +274,8 @@ export function uninstallRenderGovernor(frame) { export function _resetRenderGovernorForTest() { _removeCameraListeners?.(); _removeCameraListeners = null; + _offHeldChange?.(); + _offHeldChange = null; _frame = null; _holds.clear(); _recentRequests.length = 0; diff --git a/src/renderGovernor.test.mjs b/src/renderGovernor.test.mjs index 00c18c234..060d8a284 100644 --- a/src/renderGovernor.test.mjs +++ b/src/renderGovernor.test.mjs @@ -8,6 +8,7 @@ import { getRenderGovernorDiagnostics, _resetRenderGovernorForTest, uninstallRenderGovernor, + IDLE_FRAME_RATE, } from './renderGovernor.js'; import { framePortFor } from './testSupport/fakeFramePort.mjs'; @@ -16,7 +17,9 @@ function makeViewer() { const scene = { requestRenderMode: false, maximumRenderTimeChange: 0, - requestRender() { calls.requestRender += 1; }, + requestRender() { + calls.requestRender += 1; + }, }; return { viewer: { scene }, scene, calls }; } @@ -73,7 +76,11 @@ test('holds are identity-keyed: double-hold cannot leak, double-release cannot c holdContinuousRender('traffic'); holdContinuousRender('traffic'); releaseContinuousRender('traffic'); - assert.equal(scene.requestRenderMode, true, 'single release clears an idempotent double-hold'); + assert.equal( + scene.requestRenderMode, + true, + 'single release clears an idempotent double-hold', + ); releaseContinuousRender('traffic'); releaseContinuousRender('never-held'); assert.equal(scene.requestRenderMode, true); @@ -97,7 +104,10 @@ test('governorRequestRender forwards to the scene and records reasons only in id const baseline = calls.requestRender; governorRequestRender('layer-tick:earthquakes'); assert.equal(calls.requestRender, baseline + 1); - assert.equal(getRenderGovernorDiagnostics().recentRequests.at(-1).reason, 'layer-tick:earthquakes'); + assert.equal( + getRenderGovernorDiagnostics().recentRequests.at(-1).reason, + 'layer-tick:earthquakes', + ); holdContinuousRender('flights'); const idleRequests = getRenderGovernorDiagnostics().recentRequests.length; governorRequestRender('slider'); @@ -119,7 +129,11 @@ test('holds registered before install apply at install time', () => { holdContinuousRender('flights'); const { viewer, scene } = makeViewer(); installRenderGovernor(framePortFor(viewer.scene)); - assert.equal(scene.requestRenderMode, false, 'pre-install hold keeps continuous mode'); + assert.equal( + scene.requestRenderMode, + false, + 'pre-install hold keeps continuous mode', + ); releaseContinuousRender('flights'); assert.equal(scene.requestRenderMode, true); }); @@ -146,8 +160,41 @@ function makeCamera({ position = null, direction = null } = {}) { return camera; } -// The frame rate each mode draws at is the frame port's (ports.test.mjs: -// 'with an idle rate, …'); the governor only holds and releases. +test('idle, the loop ticks at the idle rate; held, at the display rate', () => { + const { viewer, scene } = makeViewer(); + installRenderGovernor(framePortFor(viewer.scene)); + assert.equal(scene.targetFps, IDLE_FRAME_RATE, 'idle at install'); + holdContinuousRender('flights'); + assert.equal(scene.targetFps, 0, 'held: the display rate'); + releaseContinuousRender('flights'); + assert.equal(scene.targetFps, IDLE_FRAME_RATE); +}); + +test('a hold already out at install draws at the display rate', () => { + holdContinuousRender('boot'); + const { viewer, scene } = makeViewer(); + installRenderGovernor(framePortFor(viewer.scene)); + assert.equal(scene.targetFps, 0); + releaseContinuousRender('boot'); + assert.equal(scene.targetFps, IDLE_FRAME_RATE); +}); + +test('the renderer holding the loop itself (animated visual styles) also draws at the display rate', () => { + const { viewer, scene } = makeViewer(); + const frame = framePortFor(viewer.scene); + installRenderGovernor(frame); + const release = frame.holdContinuous('effects:animated'); + assert.equal(scene.targetFps, 0, 'held by the renderer'); + holdContinuousRender('flights'); + release(); + assert.equal(scene.targetFps, 0, 'still held by flights'); + releaseContinuousRender('flights'); + assert.equal(scene.targetFps, IDLE_FRAME_RATE); + // Uninstalled, the governor no longer sets the rate. + uninstallRenderGovernor(frame); + frame.holdContinuous('effects:animated'); + assert.equal(scene.targetFps, IDLE_FRAME_RATE); +}); test('a camera move holds continuous render from moveStart to moveEnd', () => { const { viewer, scene } = makeViewer(); diff --git a/src/sources/live/standalone.js b/src/sources/live/standalone.js index 41e858a93..b5ff68a8e 100644 --- a/src/sources/live/standalone.js +++ b/src/sources/live/standalone.js @@ -261,6 +261,8 @@ export function createVesselSource({ closed: 'feed disconnected', }; error.message = reasons[payload?.status] || error.message; + // No key is not an outage: the feed waits for one. + if (payload?.status === 'missing-key') error.code = 'key-required'; throw error; } return { diff --git a/src/sources/live/standalone.test.mjs b/src/sources/live/standalone.test.mjs new file mode 100644 index 000000000..f25d4e994 --- /dev/null +++ b/src/sources/live/standalone.test.mjs @@ -0,0 +1,27 @@ +import test from 'node:test'; +import assert from 'node:assert/strict'; +import { createVesselSource } from './standalone.js'; + +const answering = (status, payload) => async () => ({ + ok: status < 400, + status, + headers: { get: () => null }, + json: async () => payload, +}); + +test('a vessels server with no AISStream key refuses as key-required, a down feed as unavailable', async () => { + const keyless = createVesselSource({ + fetchImpl: answering(503, { status: 'missing-key' }), + }); + await assert.rejects(keyless.getSnapshot(), { + code: 'key-required', + message: 'AISSTREAM_API_KEY not set', + }); + const down = createVesselSource({ + fetchImpl: answering(503, { status: 'error' }), + }); + await assert.rejects(down.getSnapshot(), { + code: 'unavailable', + message: 'feed down', + }); +}); diff --git a/src/testSupport/fakeFramePort.mjs b/src/testSupport/fakeFramePort.mjs index 4f0259c5d..35fa87cd6 100644 --- a/src/testSupport/fakeFramePort.mjs +++ b/src/testSupport/fakeFramePort.mjs @@ -3,9 +3,10 @@ * render loop through `renderGovernor.js`. It writes the scene the way the * Cesium port does (`src/render/cesium/ports.js`): holds, counted per * reason, keep `requestRenderMode` false; releasing the last asks for one - * frame; a request is the scene's `requestRender`. Only the members the - * governor uses. One port per scene, so a test can uninstall what it - * installed. + * frame; a request is the scene's `requestRender`; the first hold and the + * last release are told to `onHeldChange`; a rate set is kept as the + * scene's `targetFps`. Only the members the governor uses. One port per + * scene, so a test can uninstall what it installed. * @param {{requestRenderMode?: boolean, requestRender?: () => void}} scene */ export function framePortFor(scene) { @@ -18,11 +19,25 @@ const ports = new WeakMap(); function makePort(scene) { const holds = new Map(); + const heldListeners = new Set(); + let wasHeld = false; const apply = () => { - scene.requestRenderMode = holds.size === 0; + const held = holds.size > 0; + scene.requestRenderMode = !held; + if (held === wasHeld) return; + wasHeld = held; + for (const cb of [...heldListeners]) cb(held); }; apply(); return { + onHeldChange(cb) { + heldListeners.add(cb); + return () => heldListeners.delete(cb); + }, + diagnostics: () => ({ holds: [...holds.keys()] }), + setTargetFps(fps) { + scene.targetFps = fps; + }, requestRender() { scene.requestRender?.(); }, diff --git a/src/ui/shellFeedback.js b/src/ui/shellFeedback.js index 7193c3c3a..6a7abbfe7 100644 --- a/src/ui/shellFeedback.js +++ b/src/ui/shellFeedback.js @@ -23,6 +23,7 @@ const STATUS_LABEL_KEYS = Object.freeze({ 'LOAD COMPLETE': msg('LOAD COMPLETE'), 'LOAD CANCELLED': msg('LOAD CANCELLED'), 'LOAD FAILED': msg('LOAD FAILED'), + 'KEY REQUIRED': msg('KEY REQUIRED'), 'LIVE DATA OFF': msg('LIVE DATA OFF'), 'MAPPED SITES LOADED': msg('MAPPED SITES LOADED'), 'RETRYING MAPPED SITES': msg('RETRYING MAPPED SITES'), diff --git a/src/ui/styles/status.css b/src/ui/styles/status.css index ce212a46d..3b71b17e3 100644 --- a/src/ui/styles/status.css +++ b/src/ui/styles/status.css @@ -131,6 +131,7 @@ html:not([lang='en']) #global-loading-detail { #global-loading-status:is( [data-state='complete'], [data-state='cancelled'], + [data-state='key-required'], [data-state='error'] ) { justify-content: center; @@ -139,6 +140,7 @@ html:not([lang='en']) #global-loading-detail { #global-loading-status:is( [data-state='complete'], [data-state='cancelled'], + [data-state='key-required'], [data-state='error'] ) #global-loading-detail { @@ -155,11 +157,13 @@ html:not([lang='en']) #global-loading-detail { #global-loading-status[data-state='cancelled'] { color: #ffd488; } -#global-loading-status[data-state='retry'] { +#global-loading-status:is([data-state='retry'], [data-state='key-required']) { border-color: rgba(255, 212, 136, 0.55); } -#global-loading-status[data-state='retry'] #global-loading-label, -#global-loading-status[data-state='retry'] #global-loading-detail { +#global-loading-status:is([data-state='retry'], [data-state='key-required']) + #global-loading-label, +#global-loading-status:is([data-state='retry'], [data-state='key-required']) + #global-loading-detail { color: #ffd488; } #global-loading-status[data-state='cancelled'] #global-loading-label,