diff --git a/scripts/package-boundaries.json b/scripts/package-boundaries.json index ffdd7016d..87a133764 100644 --- a/scripts/package-boundaries.json +++ b/scripts/package-boundaries.json @@ -9,6 +9,7 @@ "src/data/infrastructure.js", "src/data/localGeojsonCore.js", "src/render/cesium/camera.js", + "src/render/cesium/frame.js", "src/render/cesium/query.js", "src/render/cesium/draw.js", "src/render/cesium/cameraControls.js", @@ -875,6 +876,7 @@ "src/ui/cockpitRollingValue.js", "src/ui/cockpitCamera.js", "src/render/cesium/camera.js", + "src/render/cesium/frame.js", "src/render/cesium/query.js", "src/queries/heights.js", "src/render/cesium/draw.js", @@ -1010,6 +1012,7 @@ "src/styles/thermal.js", "src/ui/applicationShell.js", "src/render/cesium/effects.js", + "src/render/cesium/frame.js", "src/render/cesium/query.js", "src/queries/heights.js", "src/render/cesium/draw.js", @@ -1285,6 +1288,7 @@ "src/scenes/director.js", "src/data/followed.js", "src/render/cesium/camera.js", + "src/render/cesium/frame.js", "src/render/cesium/query.js", "src/queries/heights.js", "src/render/cesium/draw.js", @@ -1434,6 +1438,7 @@ "src/layers/flights/policy.js", "src/layers/flights/queries.js", "src/render/cesium/camera.js", + "src/render/cesium/frame.js", "src/render/cesium/query.js", "src/queries/heights.js", "src/render/cesium/draw.js", @@ -1532,6 +1537,7 @@ "src/layers/military/policy.js", "src/layers/military/queries.js", "src/render/cesium/camera.js", + "src/render/cesium/frame.js", "src/render/cesium/query.js", "src/queries/heights.js", "src/render/cesium/draw.js", @@ -1696,6 +1702,7 @@ "exports": ["./render/cesium/unbound"], "modules": [ "src/render/cesium/unbound.js", + "src/render/cesium/frame.js", "src/render/cesium/query.js", "src/render/cesium/drawHit.js", "src/queries/heights.js", @@ -1773,6 +1780,7 @@ "src/layers/firms/cards.js", "src/geo/index.js", "src/render/rendererOf.js", + "src/render/cesium/frame.js", "src/render/cesium/query.js", "src/queries/heights.js", "src/render/cesium/camera.js", @@ -1859,6 +1867,7 @@ "src/layers/satellites/testing.js", "src/layers/satellites/tracking.js", "src/render/cesium/camera.js", + "src/render/cesium/frame.js", "src/render/cesium/query.js", "src/queries/heights.js", "src/render/cesium/draw.js", @@ -1912,6 +1921,7 @@ "src/layers/launches/controls.js", "src/layers/launches/index.js", "src/render/cesium/camera.js", + "src/render/cesium/frame.js", "src/render/cesium/query.js", "src/queries/heights.js", "src/render/cesium/draw.js", @@ -1984,6 +1994,7 @@ "src/layers/installations/controls.js", "src/geo/geodesic.js", "src/render/cesium/camera.js", + "src/render/cesium/frame.js", "src/render/cesium/query.js", "src/queries/heights.js", "src/render/cesium/draw.js", @@ -2268,6 +2279,7 @@ "src/layers/cctv/modelSpecs.js", "src/layers/cctv/navigation.js", "src/render/cesium/camera.js", + "src/render/cesium/frame.js", "src/render/cesium/query.js", "src/queries/heights.js", "src/render/cesium/draw.js", @@ -2341,6 +2353,7 @@ "modules": [ "src/layers/streetLevel/index.js", "src/render/cesium/credits.js", + "src/render/cesium/frame.js", "src/render/cesium/query.js", "src/render/cesium/draw.js", "src/geo/index.js", @@ -2441,6 +2454,7 @@ "src/layers/alpr/policy.js", "src/layers/alpr/presentation.js", "src/render/cesium/camera.js", + "src/render/cesium/frame.js", "src/render/cesium/query.js", "src/render/cesium/draw.js", "src/render/cesium/cameraControls.js", @@ -2520,6 +2534,7 @@ "src/layers/radio/navigation.js", "src/data/followed.js", "src/render/cesium/camera.js", + "src/render/cesium/frame.js", "src/render/cesium/query.js", "src/queries/heights.js", "src/render/cesium/draw.js", @@ -2585,6 +2600,7 @@ "src/geo/index.js", "src/layers/submarineCables/interaction.js", "src/render/cesium/camera.js", + "src/render/cesium/frame.js", "src/render/cesium/query.js", "src/queries/heights.js", "src/render/cesium/draw.js", @@ -2678,6 +2694,7 @@ "src/maps/catalog.js", "src/maps/controller.js", "src/render/cesium/globe.js", + "src/render/cesium/frame.js", "src/render/cesium/query.js", "src/queries/heights.js", "src/render/cesium/drawHit.js", @@ -2896,6 +2913,7 @@ "src/app/operations.js", "src/app/scene.js", "src/render/cesium/appRenderer.js", + "src/render/cesium/frame.js", "src/render/creditMarkup.js", "src/render/rendererOf.js", "src/render/cesium/ports.js", @@ -3891,6 +3909,7 @@ "src/data/bhoteKoshiEmbeddedMedia.js", "src/data/bhoteKoshiLocator.js", "src/render/cesium/camera.js", + "src/render/cesium/frame.js", "src/render/cesium/query.js", "src/render/cesium/draw.js", "src/render/cesium/imagery.js", @@ -4552,6 +4571,7 @@ "src/layers/firms/anchors.js", "src/locations.js", "src/render/cesium/camera.js", + "src/render/cesium/frame.js", "src/render/cesium/query.js", "src/render/cesium/drawHit.js", "src/render/cesium/draw.js", @@ -4665,6 +4685,7 @@ "src/geo/index.js", "src/ui/navigationController.js", "src/render/cesium/camera.js", + "src/render/cesium/frame.js", "src/render/cesium/query.js", "src/queries/heights.js", "src/render/cesium/drawHit.js", @@ -5201,6 +5222,7 @@ "src/cyberSonar.js", "src/celestialRing.js", "src/render/cesium/camera.js", + "src/render/cesium/frame.js", "src/render/cesium/query.js", "src/render/cesium/draw.js", "src/render/cesium/cameraControls.js", diff --git a/src/data/infrastructure.test.mjs b/src/data/infrastructure.test.mjs index 8babcd589..333162c84 100644 --- a/src/data/infrastructure.test.mjs +++ b/src/data/infrastructure.test.mjs @@ -199,6 +199,7 @@ test('consumer build includes only infrastructure code and resolves assets under 'drawHit.js', 'events.js', 'follow.js', + 'frame.js', 'heights.js', 'infrastructure.js', 'infrastructureData.js', diff --git a/src/layers/firms/cells.test.mjs b/src/layers/firms/cells.test.mjs index 8ea76acf6..5b653cac8 100644 --- a/src/layers/firms/cells.test.mjs +++ b/src/layers/firms/cells.test.mjs @@ -70,10 +70,22 @@ function harness(fires, heightM, { sceneFromViewer = false } = {}) { }; const ports = bindFakeCesiumScene(viewer); const { draw } = ports; - // A renderer with no query or frame: the layer reads the viewer's scene. + // A renderer with no query or frame: the Cesium adapter builds them over + // the viewer's scene, as it does for a viewer with no renderer. if (sceneFromViewer) { ports.unbind(); bindRenderer(viewer, { draw, camera: ports.camera }); + Object.assign(viewer.scene, { + preUpdate: new Cesium.Event(), + postRender: new Cesium.Event(), + requestRender() {}, + forceRender() {}, + pick: () => undefined, + drillPick: () => [], + camera: viewer.camera, + }); + viewer.camera.pickEllipsoid = () => undefined; + viewer.clock = { currentTime: Cesium.JulianDate.now() }; } const input = fakeInput(viewer); const layer = createFirmsHeatmapLayer({ @@ -168,7 +180,7 @@ test('close in, detections replace the cells', async () => { } }); -test("with no query or frame port, the layer still follows the camera through the viewer's scene", async () => { +test("with no query or frame port, the layer still follows the camera through ports built over the viewer's scene", async () => { const h = harness([raw(30.5, -98.2, 1500)], 12_000_000, { sceneFromViewer: true, }); diff --git a/src/layers/firms/rendering.js b/src/layers/firms/rendering.js index 7ecc72245..19d8e7f8d 100644 --- a/src/layers/firms/rendering.js +++ b/src/layers/firms/rendering.js @@ -1,13 +1,12 @@ import * as Cesium from 'cesium'; -// Still Cesium for its icons, so this layer loads the unbound camera and -// draw factories its other parts reach the renderer through; see also -// scenePorts below. +// Still Cesium for its icons, so this layer loads the unbound camera +// factory, which loads the draw, frame and query factories its other parts +// reach the renderer through. import '../../render/cesium/camera.js'; import { fromDegrees } from '../../geo/ellipsoid.js'; -import { rendererOf } from '../../render/rendererOf.js'; +import { findFrame, findQuery } from '../../render/rendererOf.js'; import { FIRMS_OVERLAY_SOURCE_ID } from '../../data/firmsLabels.js'; import { LOD_LEVELS, CONTEXT_TOP_N, GLOW_SPRITE_PX } from './policy.js'; -import { horizonOccluder } from '../../data/iconOrientation.js'; import { createIconSet, ICON_CULL_LIFT } from '../../data/iconSet.js'; import { writeHoldSegment } from '../../data/iconSegment.js'; import { IconSetPrimitive } from '../../data/iconSetPrimitive.js'; @@ -371,47 +370,15 @@ export function createRendering({ } /** - * The renderer's query and frame ports the cards and the LOD watcher use. - * A viewer with no renderer bound has neither yet; - * for one, this part (Cesium already, for its icons) answers the members - * the layer uses over the viewer's scene, as the layer did before. + * The renderer's query and frame ports the cards and the LOD watcher use: + * the bound renderer's, or for a viewer with no + * renderer bound, those the Cesium adapter builds over it (`findQuery`, + * `findFrame`; the camera factory loaded above loads theirs). * @returns {{query: object|null, frame: object|null}} */ function scenePorts() { const viewer = layerState._viewer; - const bound = rendererOf(viewer); - if (bound?.query && bound?.frame) - return { query: bound.query, frame: bound.frame }; - const scene = viewer?.scene; - if (!scene) - return { query: bound?.query ?? null, frame: bound?.frame ?? null }; - const eye = () => - viewer.camera?.positionWC ? viewer.camera : scene.camera; - const query = bound?.query ?? { - project(position) { - const screen = Cesium.SceneTransforms.worldToWindowCoordinates( - scene, - Cesium.Cartesian3.clone(position), - ); - return screen ? { x: screen.x, y: screen.y } : null; - }, - isOccluded(position) { - const camera = eye(); - if (!camera?.positionWC) return false; - return !horizonOccluder(camera).isPointVisible( - Cesium.Cartesian3.clone(position), - ); - }, - }; - const frame = bound?.frame ?? { - on(phase, listener) { - const event = scene[phase]; - return event?.addEventListener - ? event.addEventListener(listener) - : () => {}; - }, - }; - return { query, frame }; + return { query: findQuery(viewer), frame: findFrame(viewer) }; } return { diff --git a/src/render/cesium/camera.js b/src/render/cesium/camera.js index b2a6a365c..b5463699b 100644 --- a/src/render/cesium/camera.js +++ b/src/render/cesium/camera.js @@ -12,10 +12,11 @@ import { cameraFlightActive } from './internals.js'; import { createCesiumFollow } from './follow.js'; import { createCesiumControls } from './cameraControls.js'; import { cameraOf, findCamera, provideUnboundCamera } from '../rendererOf.js'; -// Loads the factories an unbound viewer gets its credits, draw and query -// ports from. +// Loads the factories an unbound viewer gets its credits, draw, frame and +// query ports from. import './credits.js'; import './draw.js'; +import './frame.js'; import './query.js'; /** diff --git a/src/render/cesium/frame.js b/src/render/cesium/frame.js new file mode 100644 index 000000000..e8e5def74 --- /dev/null +++ b/src/render/cesium/frame.js @@ -0,0 +1,298 @@ +/** + * @module render/cesium/frame + * @description A frame port (`src/render/contract/frame.d.ts`) over a Cesium + * viewer with no renderer bound, built when code first + * asks `findFrame` for one (`rendererOf.js`). The renderer's own frame port + * (`ports.js`) runs the loop on demand; this one leaves the viewer's loop as + * its owner set it up and only listens to it, asks it for frames and holds + * it drawing: its `mode` is the viewer's, and `requestRender` and holds draw + * a frame however the viewer's loop runs. `setTime`, `suspend` and + * `setTargetFps` are the viewer's own clock, loop and rate. + * + * A `preUpdate` FrameTime's `rendering` says, when read, whether the tick + * draws by the scene's own test so far (`willDraw`, which the renderer's + * frame port makes too) or a hold, and once the tick has drawn or not, + * which it did. `suspend` stops and resumes the viewer's default loop; + * resumed, the loop is as its owner had it. + */ +import * as Cesium from 'cesium'; +import { provideUnboundFrame } from '../rendererOf.js'; +import { listenerList, uncaught } from './common.js'; +import { + atEndOfTick, + lastRenderTime, + lastSeenCamera, + renderPending, +} from './internals.js'; + +const PHASES = ['preUpdate', 'preRender', 'postRender']; + +const scratchPosition0 = new Cesium.Cartesian3(); +const scratchPosition1 = new Cesium.Cartesian3(); + +/** Cesium's own test (`View.js`) for whether the camera moved. */ +function cameraEqual(camera0, camera1, epsilon) { + const maximumPositionComponent = Math.max( + Cesium.Cartesian3.maximumComponent( + Cesium.Cartesian3.abs(camera0.position, scratchPosition0), + ), + Cesium.Cartesian3.maximumComponent( + Cesium.Cartesian3.abs(camera1.position, scratchPosition1), + ), + ); + const scalar = 1 / Math.max(1, maximumPositionComponent); + Cesium.Cartesian3.multiplyByScalar( + camera0.position, + scalar, + scratchPosition0, + ); + Cesium.Cartesian3.multiplyByScalar( + camera1.position, + scalar, + scratchPosition1, + ); + return ( + Cesium.Cartesian3.equalsEpsilon( + scratchPosition0, + scratchPosition1, + epsilon, + ) && + Cesium.Cartesian3.equalsEpsilon( + camera0.direction, + camera1.direction, + epsilon, + ) && + Cesium.Cartesian3.equalsEpsilon(camera0.up, camera1.up, epsilon) && + Cesium.Cartesian3.equalsEpsilon(camera0.right, camera1.right, epsilon) && + Cesium.Matrix4.equalsEpsilon( + camera0.transform, + camera1.transform, + epsilon, + ) && + camera0.frustum.equalsEpsilon(camera1.frustum, epsilon) + ); +} + +/** + * Whether the scene's tick draws: the test `Scene.render` makes just after + * `preUpdate`, made here so `preUpdate` can say. Not seen: a request made + * in between, by a `camera.moveEnd` listener (Cesium raises it there); no + * listener of the app's does that, and the answer is corrected at preRender. + * @param {object} scene Cesium Scene. + * @param {object} [time] The tick's scene time, a Cesium JulianDate. + * @returns {boolean} + */ +export function willDraw(scene, time) { + if (!scene.requestRenderMode || renderPending(scene)) return true; + if (scene.mode === Cesium.SceneMode.MORPHING) return true; + const seen = lastSeenCamera(scene); + if (!seen || !cameraEqual(scene.camera, seen, Cesium.Math.EPSILON15)) + return true; + const last = lastRenderTime(scene); + const max = scene.maximumRenderTimeChange; + return ( + last !== undefined && + max !== undefined && + Math.abs( + Cesium.JulianDate.secondsDifference( + last, + time ?? Cesium.JulianDate.now(), + ), + ) > max + ); +} + +/** + * @param {object} viewer A Cesium `Viewer` or `CesiumWidget`. + * @returns {{port: import('../contract/frame').FramePort, + * dispose: () => void}} + */ +export function createSceneFrame(viewer) { + const scene = viewer.scene; + const listeners = Object.fromEntries( + PHASES.map((phase) => [phase, listenerList(uncaught)]), + ); + let frames = 0; + let rendered = 0; + let tickNow = performance.now(); + let dt = 0; + // Reasons asked for since the last drawn frame; those a drawing frame + // answers are the first `answering`. + const pendingReasons = []; + let answering = 0; + let disposed = false; + let suspended = false; + // Whether the viewer ran Cesium's own loop, for `suspend` to give back. + const ownLoop = viewer.useDefaultRenderLoop !== false; + // The preUpdate FrameTime of the tick under way, until it settles. + let liveTick = null; + const settleTick = (drawn) => { + if (liveTick) + Object.defineProperty(liveTick, 'rendering', { + value: drawn, + enumerable: true, + }); + liveTick = null; + }; + const holds = new Map(); + const pendingRenders = new Set(); + const gone = () => disposed || scene.isDestroyed?.(); + const sceneTime = (time) => + Cesium.JulianDate.toDate( + time ?? viewer.clock?.currentTime ?? Cesium.JulianDate.now(), + ).getTime(); + + const onPhase = (phase) => (_scene, time) => { + if (phase === 'preUpdate') { + settleTick(false); + // A tick that does not draw settles at its end; one that does, at + // preRender. + atEndOfTick(scene, () => void settleTick(false)); + const now = performance.now(); + dt = (now - tickNow) / 1000; + tickNow = now; + frames += 1; + } + if (phase === 'preRender') { + settleTick(true); + answering = pendingReasons.length; + } + if (phase === 'postRender') { + rendered += 1; + pendingReasons.splice(0, answering); + answering = 0; + // Held: the next frame is asked for as this one ends. + if (holds.size) scene.requestRender(); + } + if (listeners[phase].size === 0) return; + const t = { + frame: frames, + time: sceneTime(time), + now: tickNow, + dt, + rendering: true, + }; + // Read as it is asked: what earlier listeners asked for counts. + if (phase === 'preUpdate') { + Object.defineProperty(t, 'rendering', { + enumerable: true, + configurable: true, + get: () => holds.size > 0 || willDraw(scene, time), + }); + liveTick = t; + } + listeners[phase].fire(t); + }; + const removers = PHASES.map((phase) => + scene[phase].addEventListener(onPhase(phase)), + ); + + const port = { + on(phase, cb) { + const list = listeners[phase]; + if (!list) throw new TypeError(`Unknown frame phase: ${phase}`); + return list.on(cb); + }, + requestRender(reason = 'unspecified') { + if (gone()) return; + // During a draw the reasons it answers are spoken for. + if (!pendingReasons.includes(reason, answering)) + pendingReasons.push(reason); + scene.requestRender(); + }, + holdContinuous(reason) { + if (disposed) return () => {}; + holds.set(reason, (holds.get(reason) ?? 0) + 1); + if (!gone()) scene.requestRender(); + let released = false; + return () => { + if (released) return; + released = true; + const left = holds.get(reason) - 1; + if (left > 0) holds.set(reason, left); + else holds.delete(reason); + // What changed in the last held frame still gets drawn. + if (!gone()) scene.requestRender(); + }; + }, + mode: () => (scene.requestRenderMode ? 'demand' : 'continuous'), + diagnostics: () => ({ + mode: port.mode(), + frames, + rendered, + pendingReasons: [...pendingReasons], + holds: [...holds].flatMap(([reason, n]) => Array(n).fill(reason)), + suspended, + targetFps: viewer.targetFrameRate > 0 ? viewer.targetFrameRate : 0, + }), + suspend(hidden) { + if (Boolean(hidden) === suspended) return; + suspended = Boolean(hidden); + // Resumed, the loop runs as its owner had it (perhaps their own). + viewer.useDefaultRenderLoop = suspended ? false : ownLoop; + if (!suspended && !gone()) scene.requestRender(); + }, + renderNow: () => scene.forceRender(viewer.clock?.currentTime), + renderOnce({ timeoutMs } = {}) { + if (gone()) return Promise.resolve(); + return new Promise((resolve, reject) => { + let timer; + const settle = (error) => { + off(); + clearTimeout(timer); + pendingRenders.delete(done); + if (error) reject(error); + else resolve(); + }; + const done = () => settle(); + const off = scene.postRender.addEventListener(done); + pendingRenders.add(done); + if (timeoutMs !== undefined) + timer = setTimeout( + () => settle(new Error('renderOnce timed out')), + timeoutMs, + ); + scene.requestRender(); + }); + }, + setTargetFps(fps) { + viewer.targetFrameRate = fps > 0 ? fps : undefined; + }, + setTime(ms) { + viewer.clock.currentTime = Cesium.JulianDate.fromDate(new Date(ms)); + port.requestRender('time'); + }, + time: () => sceneTime(), + }; + + return { + port, + dispose() { + disposed = true; + settleTick(false); + for (const off of removers.splice(0)) off(); + for (const list of Object.values(listeners)) list.clear(); + holds.clear(); + // Waits settle rather than stay attached to a scene gone quiet. + for (const done of [...pendingRenders]) done(); + }, + }; +} + +// A Cesium viewer with no renderer bound to it gets a +// frame port over its scene when code first asks `findFrame` for one. +provideUnboundFrame((viewer) => { + const scene = viewer.scene; + // By shape, not `instanceof`: the viewer may come from another + // copy of Cesium. + if ( + PHASES.some( + (phase) => typeof scene?.[phase]?.addEventListener !== 'function', + ) || + typeof scene.requestRender !== 'function' || + typeof scene.forceRender !== 'function' || + !viewer.clock + ) + return null; + return createSceneFrame(viewer); +}); diff --git a/src/render/cesium/frame.test.mjs b/src/render/cesium/frame.test.mjs new file mode 100644 index 000000000..a00837e8b --- /dev/null +++ b/src/render/cesium/frame.test.mjs @@ -0,0 +1,191 @@ +import assert from 'node:assert/strict'; +import * as Cesium from 'cesium'; +import test from 'node:test'; +import { bindRenderer, findFrame, frameOf } from '../rendererOf.js'; +import './frame.js'; + +/** A viewer whose scene raises its phases when `tick` is called. */ +function fakeViewer() { + // The camera, as Cesium saw it at its last frame: unmoved since. + const camera = { + position: new Cesium.Cartesian3(2e7, 0, 0), + direction: new Cesium.Cartesian3(-1, 0, 0), + up: new Cesium.Cartesian3(0, 0, 1), + right: new Cesium.Cartesian3(0, 1, 0), + transform: Cesium.Matrix4.IDENTITY, + frustum: { equalsEpsilon: () => true }, + }; + const scene = { + camera, + _view: { _cameraClone: camera }, + maximumRenderTimeChange: Infinity, + preUpdate: new Cesium.Event(), + preRender: new Cesium.Event(), + postRender: new Cesium.Event(), + requestRenderMode: true, + requests: 0, + forced: 0, + requestRender() { + this.requests += 1; + this._renderRequested = true; + }, + forceRender() { + this.forced += 1; + scene.preRender.raiseEvent(scene); + scene.postRender.raiseEvent(scene); + }, + }; + const clock = { + currentTime: Cesium.JulianDate.fromDate(new Date(Date.UTC(2026, 0, 1))), + }; + const tick = () => { + scene._renderRequested = false; + scene.preUpdate.raiseEvent(scene, clock.currentTime); + scene.preRender.raiseEvent(scene, clock.currentTime); + scene.postRender.raiseEvent(scene, clock.currentTime); + }; + return { scene, clock, tick, useDefaultRenderLoop: true }; +} + +test('a viewer of its own, with no renderer bound, runs frames through a built port over its loop', async () => { + const viewer = fakeViewer(); + const frame = frameOf(viewer); + assert.equal(findFrame(viewer), frame, 'one per viewer'); + assert.equal(viewer.scene.requestRenderMode, true, 'its loop left alone'); + assert.equal(frame.mode(), 'demand'); + + const seen = []; + const offs = ['preUpdate', 'preRender', 'postRender'].map((phase) => + frame.on(phase, (t) => seen.push([phase, t.frame, t.time])), + ); + viewer.tick(); + const t0 = Date.UTC(2026, 0, 1); + assert.deepEqual(seen, [ + ['preUpdate', 1, t0], + ['preRender', 1, t0], + ['postRender', 1, t0], + ]); + assert.throws(() => frame.on('postUpdate', () => {}), TypeError); + + frame.requestRender('mine'); + assert.equal(viewer.scene.requests, 1); + assert.deepEqual(frame.diagnostics().pendingReasons, ['mine']); + viewer.tick(); + assert.deepEqual(frame.diagnostics().pendingReasons, []); + + // A hold asks for the next frame as each one ends, until released. + const release = frame.holdContinuous('spin'); + const before = viewer.scene.requests; + viewer.tick(); + assert.equal(viewer.scene.requests, before + 1, 'asked again after a frame'); + assert.deepEqual(frame.diagnostics().holds, ['spin']); + release(); + release(); + const after = viewer.scene.requests; + viewer.tick(); + assert.equal(viewer.scene.requests, after, 'released: no more asking'); + + const once = frame.renderOnce(); + viewer.tick(); + await once; + frame.renderNow(); + assert.equal(viewer.scene.forced, 1); + frame.setTime(Date.UTC(2026, 5, 1)); + assert.equal(frame.time(), Date.UTC(2026, 5, 1)); + frame.suspend(true); + assert.equal(viewer.useDefaultRenderLoop, false); + assert.equal(frame.diagnostics().suspended, true); + frame.suspend(false); + frame.setTargetFps(30); + assert.equal(viewer.targetFrameRate, 30); + + // A renderer bound later replaces it: its listeners hear nothing more. + const unbind = bindRenderer(viewer, { frame: { id: 'renderer' } }); + assert.equal(findFrame(viewer).id, 'renderer'); + seen.length = 0; + viewer.tick(); + assert.deepEqual(seen, []); + unbind(); + offs.forEach((off) => off()); +}); + +test('nothing to run frames over, no port', () => { + assert.equal(findFrame({ scene: {} }), null); + assert.throws(() => frameOf({ scene: {} }), /no renderer to run frames/); +}); + +test('a built frame port says whether a tick draws as its listeners ask, keeps reasons asked mid-draw, and stops once replaced', async () => { + const viewer = fakeViewer(); + const { scene } = viewer; + // Ticks that do not draw: preUpdate only. + const idle = () => { + scene._renderRequested = false; + scene.preUpdate.raiseEvent(scene, viewer.clock.currentTime); + }; + const frame = frameOf(viewer); + const told = []; + let kept = null; + let ask = false; + frame.on('preUpdate', () => { + if (ask) frame.requestRender('first'); + }); + frame.on('preUpdate', (t) => { + told.push(t.rendering); + kept = t; + }); + idle(); + assert.deepEqual(told, [false], 'nothing asked: no draw'); + ask = true; + scene._renderRequested = false; + scene.preUpdate.raiseEvent(scene, viewer.clock.currentTime); + assert.deepEqual(told, [false, true], 'an earlier listener asked'); + scene.preRender.raiseEvent(scene); + assert.equal(kept.rendering, true, 'and it drew: settled'); + ask = false; + + // A reason given while a frame draws waits for the next. + const off = frame.on('preRender', () => frame.requestRender('later')); + scene.postRender.raiseEvent(scene); + frame.requestRender('first'); + viewer.tick(); + assert.deepEqual(frame.diagnostics().pendingReasons, ['later']); + off(); + + const unbind = bindRenderer(viewer, { frame: { id: 'renderer' } }); + await frame.renderOnce(); + const requests = scene.requests; + frame.requestRender('gone'); + frame.holdContinuous('gone')(); + assert.equal(scene.requests, requests, 'a replaced port asks for nothing'); + unbind(); +}); + +test('a built frame port counts holds per reason, times out a wait, and settles waits as it goes', async () => { + const viewer = fakeViewer(); + const { scene } = viewer; + viewer.useDefaultRenderLoop = false; + const frame = frameOf(viewer); + const a = frame.holdContinuous('spin'); + const b = frame.holdContinuous('spin'); + a(); + let requests = scene.requests; + viewer.tick(); + assert.equal(scene.requests, requests + 1, 'one hold left: still held'); + b(); + requests = scene.requests; + viewer.tick(); + assert.equal(scene.requests, requests, 'none left'); + + await assert.rejects(frame.renderOnce({ timeoutMs: 1 }), /timed out/); + // The owner's own loop: suspended and resumed, it stays theirs. + frame.suspend(true); + frame.suspend(false); + assert.equal(viewer.useDefaultRenderLoop, false); + frame.setTargetFps(0); + assert.equal(viewer.targetFrameRate, undefined); + + const waiting = frame.renderOnce(); + const unbind = bindRenderer(viewer, { frame: { id: 'renderer' } }); + await waiting; + unbind(); +}); diff --git a/src/render/cesium/internals.js b/src/render/cesium/internals.js index fb893789d..e9530293d 100644 --- a/src/render/cesium/internals.js +++ b/src/render/cesium/internals.js @@ -109,7 +109,8 @@ export function onEngineWorkCompleted({ RequestScheduler, TaskProcessor }, cb) { * @param {() => void} fn */ export function atEndOfTick(scene, fn) { - scene._frameState.afterRender.push(fn); + // A scene without Cesium's frame state (a stand-in) has no tick to end. + scene._frameState?.afterRender?.push(fn); } /** diff --git a/src/render/cesium/ports.js b/src/render/cesium/ports.js index 696176544..7fb4056f7 100644 --- a/src/render/cesium/ports.js +++ b/src/render/cesium/ports.js @@ -18,14 +18,13 @@ import { listenerList, toCartesian, uncaught } from './common.js'; import { createCesiumCredits } from './credits.js'; import { createCesiumDraw } from './draw.js'; import { createCesiumEffects } from './effects.js'; +import { willDraw } from './frame.js'; import { createCesiumGlobe } from './globe.js'; import { createCesiumQuery, queryCapabilities } from './query.js'; import { createCesiumQuality } from './quality.js'; import { atEndOfTick, billboardLoadError, - lastRenderTime, - lastSeenCamera, onEngineWorkCompleted, renderPending, trimGlobeTiles, @@ -34,52 +33,6 @@ import { export { listenerList, toCartesian }; export { toColor, toImage } from './draw.js'; -const scratchPosition0 = new Cesium.Cartesian3(); -const scratchPosition1 = new Cesium.Cartesian3(); - -/** Cesium's own test (`View.js`) for whether the camera moved. */ -function cameraEqual(camera0, camera1, epsilon) { - const maximumPositionComponent = Math.max( - Cesium.Cartesian3.maximumComponent( - Cesium.Cartesian3.abs(camera0.position, scratchPosition0), - ), - Cesium.Cartesian3.maximumComponent( - Cesium.Cartesian3.abs(camera1.position, scratchPosition1), - ), - ); - const scalar = 1 / Math.max(1, maximumPositionComponent); - Cesium.Cartesian3.multiplyByScalar( - camera0.position, - scalar, - scratchPosition0, - ); - Cesium.Cartesian3.multiplyByScalar( - camera1.position, - scalar, - scratchPosition1, - ); - return ( - Cesium.Cartesian3.equalsEpsilon( - scratchPosition0, - scratchPosition1, - epsilon, - ) && - Cesium.Cartesian3.equalsEpsilon( - camera0.direction, - camera1.direction, - epsilon, - ) && - Cesium.Cartesian3.equalsEpsilon(camera0.up, camera1.up, epsilon) && - Cesium.Cartesian3.equalsEpsilon(camera0.right, camera1.right, epsilon) && - Cesium.Matrix4.equalsEpsilon( - camera0.transform, - camera1.transform, - epsilon, - ) && - camera0.frustum.equalsEpsilon(camera1.frustum, epsilon) - ); -} - /** * What every Cesium globe does: photoreal tiles, terrain, imagery draped on * tiles, the split and main-thread tile hooks. @@ -192,7 +145,7 @@ export function createCesiumPorts(widget, { capabilities, credentials = {} }) { Object.defineProperty(t, 'rendering', { enumerable: true, configurable: true, - get: () => willDraw(time), + get: () => willDraw(scene, time), }); liveTick = t; } @@ -224,31 +177,6 @@ export function createCesiumPorts(widget, { capabilities, credentials = {} }) { scene.postRender.addEventListener(() => trimGlobeAfterDraw()), ]; - /** - * Whether this tick draws: the test `Scene.render` makes just after - * `preUpdate`, made here so `preUpdate` can say. Not seen: a request made - * in between, by a `camera.moveEnd` listener (Cesium raises it there); no - * listener of the app's does that, and the answer is corrected at preRender. - */ - function willDraw(time) { - if (!scene.requestRenderMode || renderPending(scene)) return true; - if (scene.mode === Cesium.SceneMode.MORPHING) return true; - const seen = lastSeenCamera(scene); - if (!seen || !cameraEqual(camera, seen, Cesium.Math.EPSILON15)) return true; - const last = lastRenderTime(scene); - const max = scene.maximumRenderTimeChange; - return ( - last !== undefined && - max !== undefined && - Math.abs( - Cesium.JulianDate.secondsDifference( - last, - time ?? Cesium.JulianDate.now(), - ), - ) > max - ); - } - // Holds keep the loop drawing every frame; counted per reason. const holds = new Map(); function applyHolds() { diff --git a/src/render/cesium/unbound.js b/src/render/cesium/unbound.js index 696e0daa4..850451b39 100644 --- a/src/render/cesium/unbound.js +++ b/src/render/cesium/unbound.js @@ -2,9 +2,10 @@ * @module render/cesium/unbound * @description What to load, once, before handing the Cesium-free * layers a Cesium viewer with no renderer bound: the factories - * that build a camera, credits, effects, draw and query port over such a - * viewer when code first asks for one (`rendererOf.js`). + * that build a camera, credits, effects, draw, frame and query port over + * such a viewer when code first asks for one (`rendererOf.js`). */ import './camera.js'; import './effects.js'; +import './frame.js'; import './query.js'; diff --git a/src/render/rendererOf.js b/src/render/rendererOf.js index 7ab608cdb..89010376c 100644 --- a/src/render/rendererOf.js +++ b/src/render/rendererOf.js @@ -66,6 +66,7 @@ const unboundCredits = unboundPorts('credits'); /** Draw ports are `{port, dispose, release}`, as credits ports are. */ const unboundDraws = unboundPorts('draw'); const unboundQueries = unboundPorts('query'); +const unboundFrames = unboundPorts('frame'); /** * Provide the factory `cameraOf` builds a camera port with for a scene @@ -110,6 +111,15 @@ export function provideUnboundQuery(build) { unboundQueries.provide(build); } +/** + * Provide the factory `findFrame` builds a frame port with for a scene + * object no renderer is bound to, as `provideUnboundCamera` does. + * @param {(host: object) => ({port: object, dispose: () => void} | null)} build + */ +export function provideUnboundFrame(build) { + unboundFrames.provide(build); +} + /** * Provide the factory `findEffects` builds an effects port with for a * scene object no renderer is bound to, as `provideUnboundCamera` does. @@ -163,6 +173,7 @@ export function bindRenderer(host, renderer) { unboundCredits.supersede(host); unboundDraws.supersede(host); unboundQueries.drop(host); + unboundFrames.drop(host); renderers.set(host, renderer); return () => { if (renderers.get(host) === renderer) renderers.delete(host); @@ -295,6 +306,31 @@ export function queryOf(host) { throw noPort(host, 'query'); } +/** + * The frame port of the renderer bound to `host`; with no renderer bound, + * one built over `host` by the provided factory and kept with it while + * `host` lives, as `findCamera` does. A built one listens to the loop + * `host`'s owner runs, as they set it up. Bound later, a renderer's own + * replaces it: its listeners hear nothing more and its holds end. + * @param {object|null|undefined} host + * @returns {import('./contract/frame').FramePort | null} + */ +export function findFrame(host) { + return unboundFrames.find(host); +} + +/** + * `findFrame`, for code that cannot start without one. + * @param {object} host + * @returns {import('./contract/frame').FramePort} + * @throws When there is no frame port for `host`. + */ +export function frameOf(host) { + const frame = findFrame(host); + if (frame) return frame; + throw noPort(host, 'run frames with'); +} + /** * `findCamera`, for code that needs the camera. * @param {object} host diff --git a/src/render/unboundCamera.test.mjs b/src/render/unboundCamera.test.mjs index f3c2535ac..15b9991f4 100644 --- a/src/render/unboundCamera.test.mjs +++ b/src/render/unboundCamera.test.mjs @@ -13,8 +13,10 @@ * unless it is Cesium-free: then it is listed in `DRAW_FROM_CALLER`, and * a caller handing it a viewer with no renderer bound loads the package's * `./render/cesium/unbound` export once. An entry that reaches a caller of - * `findQuery` or `queryOf` loads `render/cesium/query.js` (the camera - * factory loads it too), or is such a Cesium-free entry. + * `findQuery` or `queryOf` loads `render/cesium/query.js`, and one that + * reaches a caller of `findFrame` or `frameOf` loads + * `render/cesium/frame.js` (the camera factory loads both), or is such a + * Cesium-free entry. * * The graph is every static import, re-export and literal dynamic import of * the entry's module and those it reaches, read by the parsers the Cesium @@ -38,6 +40,7 @@ const EFFECTS_FACTORY = 'src/render/cesium/effects.js'; const GLOBE_FACTORY = 'src/render/cesium/globe.js'; const DRAW_FACTORY = 'src/render/cesium/draw.js'; const QUERY_FACTORY = 'src/render/cesium/query.js'; +const FRAME_FACTORY = 'src/render/cesium/frame.js'; const UNBOUND = 'src/render/cesium/unbound.js'; /** @@ -246,15 +249,25 @@ test('every public entry that reaches a findGlobe caller loads the unbound globe }); test('every public entry that reaches a findQuery or queryOf caller loads the unbound query factory, or its caller can', () => { - for (const lookup of ['findQuery', 'queryOf']) - checkLookupFactory(lookup, QUERY_FACTORY, { - reached: false, - fromCaller: true, - }); + checkLookupFactory('findQuery', QUERY_FACTORY, { fromCaller: true }); + checkLookupFactory('queryOf', QUERY_FACTORY, { + reached: false, + fromCaller: true, + }); }); -test('the unbound camera factory loads the unbound query factory', () => { - assert.ok(reachable(FACTORY, { eager: true }).has(QUERY_FACTORY)); +test('every public entry that reaches a findFrame or frameOf caller loads the unbound frame factory, or its caller can', () => { + checkLookupFactory('findFrame', FRAME_FACTORY, { fromCaller: true }); + checkLookupFactory('frameOf', FRAME_FACTORY, { + reached: false, + fromCaller: true, + }); +}); + +test('the unbound camera factory loads the unbound query and frame factories', () => { + const loaded = reachable(FACTORY, { eager: true }); + assert.ok(loaded.has(QUERY_FACTORY)); + assert.ok(loaded.has(FRAME_FACTORY)); }); test('the unbound export brings every unbound factory', () => { @@ -264,6 +277,7 @@ test('the unbound export brings every unbound factory', () => { EFFECTS_FACTORY, DRAW_FACTORY, QUERY_FACTORY, + FRAME_FACTORY, 'src/render/cesium/credits.js', ]) assert.ok(loaded.has(factory), factory);