From aa58886e405ac474ae9895486f8501610f5bb232 Mon Sep 17 00:00:00 2001 From: Sameh Khamis Date: Thu, 12 Nov 2026 11:41:54 -0800 Subject: [PATCH] feat(render): the Cesium renderer can run an application's camera controller createCesiumRendererPlugin({cameraController}) (render/cesium/plugin) puts the camera port on the shared camera controller over a native camera on Cesium's (controlledCamera.js): poses written exactly, out of any lookAt transform, the vertical field of view as Cesium's wide-side fov and kept on a resize. Cesium's own controls hold their input off and their collision off while it drives; the controller runs before and after the preUpdate listeners, and what it throws is reported. A followed item's position is where its GPU icon set draws it (drawnPosition), and the input port's camera holds are the controller's. The conformance harness, given a controller, steps a virtual clock 1/60 s a frame for ticks and pointer events, so flights and pointer scripts are compared frame by frame. --- package.json | 1 + src/render/cesium/appRenderer.js | 26 +- src/render/cesium/controlledCamera.js | 255 +++++++++++++ src/render/cesium/controlledCamera.test.mjs | 381 ++++++++++++++++++++ src/render/cesium/draw.js | 10 + src/render/cesium/gpuIcons.js | 12 + src/render/cesium/harness.js | 39 +- src/render/cesium/input.js | 14 +- src/render/cesium/plugin.js | 10 + src/render/cesium/ports.js | 94 ++++- src/render/cesium/sceneRenderer.js | 20 +- 11 files changed, 826 insertions(+), 36 deletions(-) create mode 100644 src/render/cesium/controlledCamera.js create mode 100644 src/render/cesium/controlledCamera.test.mjs create mode 100644 src/render/cesium/plugin.js diff --git a/package.json b/package.json index 505f581f5..101bffd47 100644 --- a/package.json +++ b/package.json @@ -311,6 +311,7 @@ "./render/stub": "./src/render/stub/index.js", "./render/occlusion": "./src/render/occlusion/index.js", "./render/camera/events": "./src/render/camera/events.js", + "./render/cesium/plugin": "./src/render/cesium/plugin.js", "./render/cesium/unbound": "./src/render/cesium/unbound.js", "./render/conformance": "./src/render/conformance/index.js", "./layers/wildlife-sightings": "./src/layers/wildlifeSightings/index.js", diff --git a/src/render/cesium/appRenderer.js b/src/render/cesium/appRenderer.js index 3ca4ab39b..96f7d7732 100644 --- a/src/render/cesium/appRenderer.js +++ b/src/render/cesium/appRenderer.js @@ -63,11 +63,16 @@ export class ReadonlySet extends Set { } /** - * The Cesium plugin over a viewer factory; tests pass a fake one. - * @param {{createViewer?: typeof createApplicationViewer}} [options] + * The Cesium plugin over a viewer factory; tests pass a fake one. With + * `cameraController` (the shared camera controller's factory), its camera + * port is that controller's over Cesium's camera, which takes the user's + * input in place of Cesium's own controls (`controlledCamera.js`). + * @param {{createViewer?: typeof createApplicationViewer, + * cameraController?: Function}} [options] */ export function createCesiumRendererPlugin({ createViewer = createApplicationViewer, + cameraController, } = {}) { return Object.freeze({ id: 'cesium', @@ -101,16 +106,23 @@ export function createCesiumRendererPlugin({ ports = createCesiumPorts(viewer, { capabilities, credentials: { googleApiKey, googleTokens, worldDataToken }, + ...(cameraController ? { cameraController } : {}), }); input = createCesiumInput(viewer, { query: ports.query, report: ports.report, + ...(ports.suspendCamera + ? { suspendCamera: ports.suspendCamera } + : {}), }); - // Free look is limited to low heights from the start. - releaseFreeLook = installFreeLookHeightLimit( - viewer, - FREE_LOOK_MAX_HEIGHT_METERS, - ); + ports.attachInput?.(input.port); + // Free look is limited to low heights from the start, on Cesium's + // own controls (the controller keeps its own limits). + if (!cameraController) + releaseFreeLook = installFreeLookHeightLimit( + viewer, + FREE_LOOK_MAX_HEIGHT_METERS, + ); configureCreditKeyboardAccess(document); offLocale = onLocaleChange(() => configureCreditKeyboardAccess(document), diff --git a/src/render/cesium/controlledCamera.js b/src/render/cesium/controlledCamera.js new file mode 100644 index 000000000..fe4e288c6 --- /dev/null +++ b/src/render/cesium/controlledCamera.js @@ -0,0 +1,255 @@ +/** + * @module render/cesium/controlledCamera + * @description The Cesium renderer's camera port on a camera controller the + * application hands in (`CameraControllerFactory`, the shared one a renderer + * without a camera of its own is built on), in place of the port over + * Cesium's own camera (`camera.js`). + * + * The controller does the poses, flights, `lookAt`, follows, events and the + * user's drags, zooms and keys; it is given a native camera over Cesium's: + * - `pose()` reads Cesium's camera in world coordinates, `setPose(eye)` + * writes it exactly (out of any `lookAt` transform), its vertical field + * of view as Cesium's `fov`, which spans the wider side of the canvas; + * - `viewport()` is the canvas's CSS size, `pickPosition` and + * `sampleHeightNow` the query port's, `requestRender` the frame port's, + * `itemPosition` where the draw port draws an item it moves itself. + * + * Cesium's own camera controls are kept off for as long as the port lives + * (a hold on its `ScreenSpaceCameraController`'s input, which Cesium's own + * flights ending cannot lift), and so is its collision: the controller hears + * the input port's pointer events and the page's keys. The input port's + * camera holds are the controller's (`controls.suspend`), through + * `suspendCamera`, which the renderer hands its input port. + * + * The renderer runs `before(tick)` before its `preUpdate` listeners and + * `after(tick)` after them, each scene tick, drawn or not; what they throw + * is reported, never left to stop Cesium's render loop. + */ +import * as Cesium from 'cesium'; +import { acquireCameraInput } from './cameraInput.js'; + +/** + * The input port's events for a controller made before the port: listeners + * taken now, delivered once `attach` hands the port over. + */ +function inputRelay() { + const wanted = []; + let port = null; + return { + on(type, cb) { + const entry = { type, cb, off: null, gone: false }; + wanted.push(entry); + if (port) entry.off = port.on(type, cb); + return () => { + entry.gone = true; + entry.off?.(); + entry.off = null; + }; + }, + attach(input) { + port = input; + for (const entry of wanted) + if (!entry.gone && !entry.off) + entry.off = input.on(entry.type, entry.cb); + }, + }; +} + +const plain = (v) => ({ x: v.x, y: v.y, z: v.z }); + +/** + * How far Cesium's camera may stand from the eye last written and still be + * that eye: its world vectors are derived again in floating point (a unit + * vector's component off by 2e-16 now and then), and the controller counts + * any difference as a move, which would put off `moveEnd` with nothing + * moving. Metres per metre of distance from the Earth's centre, and the + * cosine's shortfall from 1 for the unit vectors. + */ +const ROUNDING = 1e-12; + +/** Whether Cesium's `world` vectors are the `written` eye, up to rounding. */ +function sameEye(world, written) { + const p = world.position; + const q = written.position; + const scale = Math.max(1, Math.hypot(q.x, q.y, q.z)); + if (Math.hypot(p.x - q.x, p.y - q.y, p.z - q.z) > ROUNDING * scale) + return false; + for (const key of ['direction', 'up']) { + const a = world[key]; + const b = written[key]; + if (a.x * b.x + a.y * b.y + a.z * b.z < 1 - ROUNDING) return false; + } + return true; +} + +/** + * @param {{ + * scene: object, + * controller: Function, + * query: {pickPosition?: Function, sampleHeightNow?: Function}, + * itemPosition?: (item: {set: string, id: string|number}, aheadMs?: number) => object|null, + * requestRender: (reason: string) => void, + * report: (error: unknown) => void, + * thresholds: boolean, + * followFrame: boolean, + * keyTarget?: EventTarget, + * }} options + * @returns {{ + * port: import('../contract/camera').CameraPort, + * before: (tick: {now: number, time: number}) => void, + * after: (tick: {now: number, time: number}) => void, + * attachInput: (input: {on: Function}) => void, + * suspendCamera: (reason: string) => () => void, + * dispose: () => void, + * }} + */ +export function createControlledCamera({ + scene, + controller: factory, + query, + itemPosition, + requestRender, + report, + thresholds, + followFrame, + keyTarget = globalThis.document, +}) { + const camera = scene.camera; + const canvas = scene.canvas; + /** The eye last written, while Cesium's camera still stands there. */ + let written = null; + /** The vertical field of view last written, and the aspect it was for. */ + let fovy = null; + let fovAspect = null; + /** Cesium's `fov` for vertical `fovy`: it spans the wider side. */ + function applyFov(frustum) { + const aspect = frustum.aspectRatio; + const fov = aspect > 1 ? 2 * Math.atan(Math.tan(fovy / 2) * aspect) : fovy; + if (frustum.fov !== fov) frustum.fov = fov; + fovAspect = aspect; + } + const native = { + pose() { + const frustum = camera.frustum; + const world = { + position: plain(camera.positionWC), + direction: plain(camera.directionWC), + up: plain(camera.upWC), + }; + // Within rounding of the eye written, it is that eye; anything that + // moved Cesium's camera since is read as it stands. + const eye = written && sameEye(world, written) ? written : world; + if (eye !== written) written = null; + return { + position: { ...eye.position }, + direction: { ...eye.direction }, + up: { ...eye.up }, + near: frustum.near, + far: frustum.far, + }; + }, + setPose(eye) { + if (!Cesium.Matrix4.equals(camera.transform, Cesium.Matrix4.IDENTITY)) + camera.lookAtTransform(Cesium.Matrix4.IDENTITY); + camera.position = new Cesium.Cartesian3( + eye.position.x, + eye.position.y, + eye.position.z, + ); + camera.direction = new Cesium.Cartesian3( + eye.direction.x, + eye.direction.y, + eye.direction.z, + ); + camera.up = new Cesium.Cartesian3(eye.up.x, eye.up.y, eye.up.z); + camera.right = new Cesium.Cartesian3( + eye.right.x, + eye.right.y, + eye.right.z, + ); + const frustum = camera.frustum; + if (Number.isFinite(eye.fovy) && 'fov' in frustum) { + fovy = eye.fovy; + applyFov(frustum); + } + written = { + position: plain(eye.position), + direction: plain(eye.direction), + up: plain(eye.up), + }; + }, + viewport: () => ({ + width: canvas.clientWidth || canvas.width, + height: canvas.clientHeight || canvas.height, + }), + requestRender, + ...(query.pickPosition + ? { pickPosition: (x, y) => query.pickPosition(x, y) } + : {}), + ...(query.sampleHeightNow + ? { + sampleHeightNow: (point, options) => + query.sampleHeightNow(point, options), + } + : {}), + ...(itemPosition ? { itemPosition } : {}), + }; + const relay = inputRelay(); + const made = factory({ + native, + input: relay, + report, + thresholds, + ...(keyTarget ? { keyTarget } : {}), + }); + const port = made.port; + if (!followFrame) delete port.followFrame; + + // Cesium's own controls stay off while the controller drives the camera. + const ownInput = acquireCameraInput(scene); + ownInput.suspend('camera controller'); + // Its collision too, which runs every frame with input off and would lift + // the eye under the controller's own (the controller keeps it above the + // ground through `sampleHeightNow`). + const own = scene.screenSpaceCameraController; + const ownCollision = own?.enableCollisionDetection; + if (own && ownCollision !== undefined) own.enableCollisionDetection = false; + + let disposed = false; + return { + port, + before(tick) { + if (disposed) return; + try { + // A canvas resized since: the same vertical field of view on it. + const frustum = camera.frustum; + if (fovy !== null && frustum.aspectRatio !== fovAspect) + applyFov(frustum); + made.frame.beforeUpdate(tick); + } catch (error) { + report(error); + } + }, + after(tick) { + if (disposed) return; + try { + made.frame.afterUpdate(tick); + } catch (error) { + report(error); + } + }, + attachInput: (input) => relay.attach(input), + suspendCamera: (reason) => port.controls.suspend(reason), + dispose() { + if (disposed) return; + disposed = true; + try { + made.destroy(); + } finally { + ownInput.release(); + if (own && ownCollision !== undefined && !scene.isDestroyed?.()) + own.enableCollisionDetection = ownCollision; + } + }, + }; +} diff --git a/src/render/cesium/controlledCamera.test.mjs b/src/render/cesium/controlledCamera.test.mjs new file mode 100644 index 000000000..54945e31a --- /dev/null +++ b/src/render/cesium/controlledCamera.test.mjs @@ -0,0 +1,381 @@ +import assert from 'node:assert/strict'; +import test from 'node:test'; +import * as Cesium from 'cesium'; +import { createControlledCamera } from './controlledCamera.js'; +import { createCesiumRendererPlugin } from './appRenderer.js'; + +/** A Cesium camera as the native camera reads and writes it. */ +function fakeCamera({ aspectRatio = 2 } = {}) { + const camera = { + position: new Cesium.Cartesian3(1, 2, 3), + direction: new Cesium.Cartesian3(0, 0, -1), + up: new Cesium.Cartesian3(0, 1, 0), + right: new Cesium.Cartesian3(1, 0, 0), + transform: Cesium.Matrix4.clone(Cesium.Matrix4.IDENTITY), + frustum: { fov: 1, aspectRatio, near: 0.5, far: 1e9 }, + lookAtTransform(matrix) { + camera.transform = Cesium.Matrix4.clone(matrix); + }, + get positionWC() { + return camera.position; + }, + get directionWC() { + return camera.direction; + }, + get upWC() { + return camera.up; + }, + }; + return camera; +} + +/** A controller factory recording what it is given and asked. */ +function fakeController(log) { + let given; + const factory = (options) => { + given = options; + return { + port: { + followFrame: () => new Float64Array(16), + controls: { + suspend: (reason) => { + log.push(`suspend ${reason}`); + return () => log.push(`release ${reason}`); + }, + }, + }, + frame: { + beforeUpdate: (tick) => log.push(['before', tick]), + afterUpdate: (tick) => log.push(['after', tick]), + }, + destroy: () => log.push('destroy'), + }; + }; + return { factory, given: () => given }; +} + +function make(log, overrides = {}) { + const camera = fakeCamera(); + const own = { enableInputs: true, enableCollisionDetection: true }; + const scene = { + camera, + canvas: { clientWidth: 800, clientHeight: 400 }, + screenSpaceCameraController: own, + isDestroyed: () => false, + }; + const controller = fakeController(log); + const part = createControlledCamera({ + scene, + controller: controller.factory, + query: {}, + requestRender: (reason) => log.push(`render ${reason}`), + report: () => {}, + thresholds: true, + followFrame: true, + keyTarget: null, + ...overrides, + }); + return { part, camera, own, native: controller.given().native, controller }; +} + +test('the native camera reads Cesium’s camera and writes the eye exactly', () => { + const { native, camera } = make([]); + assert.deepEqual(native.pose(), { + position: { x: 1, y: 2, z: 3 }, + direction: { x: 0, y: 0, z: -1 }, + up: { x: 0, y: 1, z: 0 }, + near: 0.5, + far: 1e9, + }); + assert.deepEqual(native.viewport(), { width: 800, height: 400 }); + // Out of a lookAt frame first. + camera.transform = Cesium.Matrix4.fromTranslation( + new Cesium.Cartesian3(5, 5, 5), + ); + const fovy = Math.PI / 3; + native.setPose({ + position: { x: 7e6, y: 0, z: 0 }, + direction: { x: -1, y: 0, z: 0 }, + up: { x: 0, y: 0, z: 1 }, + right: { x: 0, y: -1, z: 0 }, + fovy, + }); + assert.ok(Cesium.Matrix4.equals(camera.transform, Cesium.Matrix4.IDENTITY)); + assert.deepEqual( + [camera.position, camera.direction, camera.up, camera.right].map((v) => [ + v.x, + v.y, + v.z, + ]), + [ + [7e6, 0, 0], + [-1, 0, 0], + [0, 0, 1], + [0, -1, 0], + ], + ); + // A wide canvas: Cesium's fov spans its width, so the vertical one is kept. + const vertical = + 2 * + Math.atan(Math.tan(camera.frustum.fov / 2) / camera.frustum.aspectRatio); + assert.ok(Math.abs(vertical - fovy) < 1e-12); +}); + +test('Cesium’s rounding of the eye written is still that eye; a real move is read as it stands', () => { + const { native, camera } = make([]); + const eye = { + position: { x: 7e6, y: 1, z: 2 }, + direction: { x: -1, y: 0, z: 0 }, + up: { x: 0, y: 0, z: 1 }, + right: { x: 0, y: -1, z: 0 }, + fovy: 1, + }; + native.setPose(eye); + // Cesium derives its world vectors again: a component off by 2e-16. + camera.direction = new Cesium.Cartesian3(-1, 2.2e-16, 0); + camera.position = new Cesium.Cartesian3(7e6 + 1e-9, 1, 2); + const pose = native.pose(); + assert.deepEqual(pose.direction, eye.direction); + assert.deepEqual(pose.position, eye.position); + // Moved for real (by something other than the controller): read as it is. + camera.position = new Cesium.Cartesian3(7e6 + 1, 1, 2); + assert.equal(native.pose().position.x, 7e6 + 1); + // And the written eye is let go: back within rounding of it, still as it is. + camera.position = new Cesium.Cartesian3(7e6 + 1e-9, 1, 2); + assert.equal(native.pose().position.x, 7e6 + 1e-9); +}); + +test('a tall canvas takes the vertical field of view as Cesium’s fov', () => { + const { native, camera } = make([]); + camera.frustum.aspectRatio = 0.5; + native.setPose({ ...native.pose(), right: { x: 1, y: 0, z: 0 }, fovy: 0.8 }); + assert.equal(camera.frustum.fov, 0.8); +}); + +test('Cesium’s own controls stay off while the controller drives the camera', () => { + const log = []; + const { part, own } = make(log); + assert.equal(own.enableInputs, false); + assert.equal(own.enableCollisionDetection, false, 'its collision off too'); + // Cesium's own flight ending writes it back on: still off. + own.enableInputs = true; + assert.equal(own.enableInputs, false); + part.dispose(); + part.dispose(); + assert.equal(own.enableInputs, true, 'given back'); + assert.equal(own.enableCollisionDetection, true); + assert.deepEqual(log, ['destroy'], 'the controller destroyed once'); +}); + +test('the frame steps go to the controller, and stop once disposed', () => { + const log = []; + const { part } = make(log); + part.before({ now: 1, time: 2 }); + part.after({ now: 1, time: 2 }); + part.dispose(); + part.before({ now: 3, time: 4 }); + assert.deepEqual(log, [ + ['before', { now: 1, time: 2 }], + ['after', { now: 1, time: 2 }], + 'destroy', + ]); +}); + +test('pointer listeners taken before the input port is made hear it once attached', () => { + const log = []; + const { part, controller } = make(log); + const relay = controller.given().input; + const heard = []; + relay.on('down', (e) => heard.push(['down', e])); + const off = relay.on('wheel', (e) => heard.push(['wheel', e])); + off(); + const handlers = new Map(); + part.attachInput({ + on(type, cb) { + handlers.set(type, cb); + return () => handlers.delete(type); + }, + }); + assert.deepEqual([...handlers.keys()], ['down'], 'only what is still wanted'); + handlers.get('down')(1); + relay.on('up', (e) => heard.push(['up', e])); + handlers.get('up')(2); + assert.deepEqual(heard, [ + ['down', 1], + ['up', 2], + ]); +}); + +test('camera holds are the controller’s, and the follow frame only where it is a capability', () => { + const log = []; + const { part } = make(log); + const release = part.suspendCamera('lease'); + release(); + assert.deepEqual(log, ['suspend lease', 'release lease']); + assert.equal(typeof part.port.followFrame, 'function'); + const without = make([], { followFrame: false }); + assert.equal(without.part.port.followFrame, undefined); +}); + +test('the query port’s picks and heights are the native camera’s', () => { + const picks = []; + const { native } = make([], { + query: { + pickPosition: (x, y) => (picks.push([x, y]), { x, y, z: 0 }), + sampleHeightNow: () => 12, + }, + }); + assert.deepEqual(native.pickPosition(3, 4), { x: 3, y: 4, z: 0 }); + assert.equal(native.sampleHeightNow({ lon: 0, lat: 0 }), 12); + assert.equal(make([]).native.pickPosition, undefined, 'none without one'); +}); + +test('a drawn item’s position is the draw port’s, where it has one', () => { + const asked = []; + const { native } = make([], { + itemPosition: (item, aheadMs) => ( + asked.push([item, aheadMs]), + { x: 1, y: 2, z: 3 } + ), + }); + assert.deepEqual(native.itemPosition({ set: 's', id: 'm' }, 250), { + x: 1, + y: 2, + z: 3, + }); + assert.deepEqual(asked, [[{ set: 's', id: 'm' }, 250]]); + assert.equal(make([]).native.itemPosition, undefined, 'none without one'); +}); + +/** A Cesium event of its own, raised in the order listeners were added. */ +function event() { + const listeners = []; + return { + listeners, + addEventListener(cb) { + listeners.push(cb); + return () => listeners.splice(listeners.indexOf(cb), 1); + }, + raise(...args) { + for (const cb of [...listeners]) cb(...args); + }, + }; +} + +test('the application’s Cesium renderer runs the controller around its preUpdate listeners', async (t) => { + const saved = globalThis.document; + globalThis.document = { + createElement: () => ({ remove() {} }), + body: { appendChild() {} }, + getElementById: () => null, + addEventListener() {}, + removeEventListener() {}, + }; + t.after(() => { + globalThis.document = saved; + }); + const order = []; + const scene = { + camera: fakeCamera(), + canvas: { + clientWidth: 800, + clientHeight: 400, + addEventListener() {}, + removeEventListener() {}, + }, + primitives: { add() {}, remove() {} }, + screenSpaceCameraController: { enableInputs: true }, + requestRender() {}, + preUpdate: event(), + postUpdate: event(), + preRender: event(), + postRender: event(), + isDestroyed: () => false, + }; + const viewer = { + scene, + camera: scene.camera, + canvas: scene.canvas, + clock: { currentTime: Cesium.JulianDate.fromDate(new Date(1000)) }, + entities: { contains: () => false }, + isDestroyed: () => false, + destroy() {}, + }; + const holds = []; + const plugin = createCesiumRendererPlugin({ + createViewer: () => viewer, + cameraController: ({ native }) => ({ + port: { + native, + controls: { + suspend: (reason) => (holds.push(reason), () => {}), + }, + }, + frame: { + beforeUpdate: (tick) => order.push(['before', tick.time]), + afterUpdate: () => order.push('after'), + }, + destroy: () => order.push('destroy'), + }), + }); + const renderer = await plugin.create({ container: {} }); + assert.equal(scene.screenSpaceCameraController.enableInputs, false); + assert.equal(typeof renderer.camera.native.setPose, 'function'); + renderer.frame.on('preUpdate', () => order.push('preUpdate')); + scene.preUpdate.raise(scene, Cesium.JulianDate.fromDate(new Date(5000))); + assert.deepEqual(order, [['before', 5000], 'preUpdate', 'after']); + // A lease's hold is the controller's. + renderer.input.lease?.('test', { camera: true })?.release?.(); + renderer.destroy(); + assert.equal(order.at(-1), 'destroy'); + assert.equal(scene.screenSpaceCameraController.enableInputs, true); +}); + +test('what the controller throws in a frame step is reported, not thrown into Cesium’s loop', () => { + const reported = []; + const camera = fakeCamera(); + const part = createControlledCamera({ + scene: { + camera, + canvas: { clientWidth: 800, clientHeight: 400 }, + screenSpaceCameraController: { enableInputs: true }, + isDestroyed: () => false, + }, + controller: () => ({ + port: { controls: { suspend: () => () => {} } }, + frame: { + beforeUpdate: () => { + throw new Error('before'); + }, + afterUpdate: () => { + throw new Error('after'); + }, + }, + destroy() {}, + }), + query: {}, + requestRender() {}, + report: (error) => reported.push(error.message), + thresholds: true, + followFrame: true, + keyTarget: null, + }); + part.before({ now: 0, time: 0 }); + part.after({ now: 0, time: 0 }); + assert.deepEqual(reported, ['before', 'after']); + part.dispose(); +}); + +test('a canvas resized keeps the vertical field of view last written', () => { + const { part, native, camera } = make([]); + native.setPose({ ...native.pose(), right: { x: 1, y: 0, z: 0 }, fovy: 0.8 }); + camera.frustum.aspectRatio = 3; + part.before({ now: 1, time: 1 }); + const vertical = + 2 * + Math.atan(Math.tan(camera.frustum.fov / 2) / camera.frustum.aspectRatio); + assert.ok(Math.abs(vertical - 0.8) < 1e-12); + camera.frustum.aspectRatio = 0.5; + part.before({ now: 2, time: 2 }); + assert.equal(camera.frustum.fov, 0.8); +}); diff --git a/src/render/cesium/draw.js b/src/render/cesium/draw.js index 0ff534c14..ee960fc4f 100644 --- a/src/render/cesium/draw.js +++ b/src/render/cesium/draw.js @@ -5204,6 +5204,16 @@ export function createCesiumDraw({ sets, version: () => setsVersion, tilesets, + /** + * Where a GPU icon set draws an item it moves itself, `aheadMs` after + * `time` (a Julian date; now without one), on its segment; null for any + * other item, whose own position stays the answer. + */ + drawnPosition(ref, aheadMs = 0, time = undefined) { + const record = sets.get(ref?.set); + if (!record || record.kind !== 'icons' || !record.gpu) return null; + return record.gpu.drawnAt(ref.id, aheadMs, time ? { time } : undefined); + }, /** Whether a set's ground primitives are still being built. */ building: () => [...sets.values()].some((record) => record.pending), /** Each frame, before it draws: the horizon cull. */ diff --git a/src/render/cesium/gpuIcons.js b/src/render/cesium/gpuIcons.js index 61bc7ae9c..01cc358c6 100644 --- a/src/render/cesium/gpuIcons.js +++ b/src/render/cesium/gpuIcons.js @@ -815,6 +815,18 @@ export function createGpuIcons({ } return out; }, + /** + * Where the row of `id` is drawn `aheadMs` after the motion clock's + * time in `frameState` (now without one), on its ground when clamped; + * null without a row. + */ + drawnAt(id, aheadMs = 0, frameState = undefined) { + const row = set.row(id); + if (row < 0) return null; + const tau = set.seconds(clockTime(frameState)) + aheadMs / 1000; + const p = set.position(row, tau, { x: 0, y: 0, z: 0 }); + return grounded.has(id) ? onGround(row, p) : p; + }, /** Hide the rows of `ids` (in clusters); show the rest again. */ setClustered(ids) { const before = clustered; diff --git a/src/render/cesium/harness.js b/src/render/cesium/harness.js index 3cb2b2299..a4b01201c 100644 --- a/src/render/cesium/harness.js +++ b/src/render/cesium/harness.js @@ -145,25 +145,43 @@ function nextFrame() { } /** - * @param {{name?: string, model?: string, missingModel?: string}} [options] + * @param {{name?: string, model?: string, missingModel?: string, + * cameraController?: Function}} [options] * `model`: a glTF URL for the model checks; `missingModel`: one that - * fails to load, for the failure check. + * fails to load, for the failure check; `cameraController`: the camera + * port on that controller (`controlledCamera.js`). * @returns {import('../conformance/index.js').ConformanceHarness} */ export function createCesiumHarness({ name = 'cesium', model, missingModel, + cameraController, } = {}) { + // With a camera controller, each renderer's ticks read a clock of its + // own that each frame moves on by 1/60 s: the controller's flights then + // step as the reference traces do, frame by frame (Cesium's own flights + // keep Cesium's clock, so they are checked in Node instead). + const clocks = new WeakMap(); + const virtual = Boolean(cameraController); return { name, + // A camera controller hears the pointer events sent through `pointer` + // (the input port's), so the camera scripts' drags and wheels run. + ...(cameraController ? { cameraInput: true } : {}), async create({ viewport, capabilities }) { const container = document.createElement('div'); container.style.cssText = `position:fixed;left:0;top:0;width:${viewport.width}px;height:${viewport.height}px`; document.body.append(container); let renderer; + const clock = { ms: performance.now() }; try { - renderer = await createCesiumSceneRenderer({ container, capabilities }); + renderer = await createCesiumSceneRenderer({ + container, + capabilities, + ...(cameraController ? { cameraController } : {}), + ...(virtual ? { now: () => clock.ms } : {}), + }); } catch (error) { container.remove(); throw error; @@ -182,18 +200,27 @@ export function createCesiumHarness({ container.remove(); } }; + clocks.set(renderer, clock); return renderer; }, - frame: nextFrame, + frame: virtual + ? (r) => { + const clock = clocks.get(r); + if (clock) clock.ms += 1000 / 60; + return nextFrame(); + } + : nextFrame, // Events as the renderer's handler delivers them: the checks send ones // no real pointer can (a click with no press), so not DOM events. pointer: (r, type, x, y, extra) => pointerFeedOf(r)(type, x, y, extra), - now: () => performance.now(), + now: virtual + ? (r) => clocks.get(r)?.ms ?? performance.now() + : () => performance.now(), // What a live motion clock reads. wallTime: () => Date.now(), toEcef, tolerance: DEFAULT_TOLERANCE, - flightPaths: 'endpoints', + flightPaths: virtual ? 'trace' : 'endpoints', ...(model ? { assets: { model, missingModel } } : {}), }; } diff --git a/src/render/cesium/input.js b/src/render/cesium/input.js index d1199b235..5ad656d90 100644 --- a/src/render/cesium/input.js +++ b/src/render/cesium/input.js @@ -116,6 +116,9 @@ export const cesiumInputOf = (scene) => inputs.get(scene) ?? null; * @param {boolean} [options.takeStock] False leaves the viewer's stock * actions on its own handler, taken off only while suppressed, for a * viewer that is not this renderer's: its owner may still rebind them. + * @param {(reason: string) => () => void} [options.suspendCamera] Where the + * router's camera holds go, in place of Cesium's own camera controls: a + * camera controller's (`controlledCamera.js`). * @returns {{port: object, feed: Function, listenerCount: () => number, dispose: () => void}} * `feed(type, x, y, extra)` delivers one event as the handler would, for * the conformance harness. @@ -129,6 +132,7 @@ export function createCesiumInput( now = () => performance.now(), document: dom = globalThis.document, takeStock = true, + suspendCamera, }, ) { const scene = widget.scene; @@ -167,10 +171,14 @@ export function createCesiumInput( stockHandler.removeInputAction(STOCK[name]); } - const cameraInput = acquireCameraInput(scene); + // Camera holds go to the camera that takes the user's input: Cesium's + // controller through the scene's shared holds, or the camera port's own + // controls when a camera controller drives Cesium's camera + // (`controlledCamera.js`). + const cameraInput = suspendCamera ? null : acquireCameraInput(scene); const router = createInputRouter({ report, - suspendCamera: (reason) => cameraInput.suspend(reason), + suspendCamera: suspendCamera ?? ((reason) => cameraInput.suspend(reason)), supported: { select: has.select, dblclickFollow: has.dblclickFollow }, onBehaviour: borrowStock, }); @@ -453,7 +461,7 @@ export function createCesiumInput( for (const type of DOM_EVENTS) dom?.removeEventListener?.(type, record, { capture: true }); if (!handler.isDestroyed?.()) handler.destroy?.(); - cameraInput.release(); + cameraInput?.release(); for (const name of Object.keys(borrowed)) giveBack(name); if (stockHandler && !stockHandler.isDestroyed?.()) for (const [name, type] of Object.entries(STOCK)) diff --git a/src/render/cesium/plugin.js b/src/render/cesium/plugin.js new file mode 100644 index 000000000..1b8b8cfb9 --- /dev/null +++ b/src/render/cesium/plugin.js @@ -0,0 +1,10 @@ +/** + * @module render/cesium/plugin + * @description The Cesium renderer plugin made with options, for an + * application that hands it something of its own: `cameraController`, the + * shared camera controller's factory, which then drives Cesium's camera + * and takes the user's input in place of Cesium's own controls + * (`controlledCamera.js`). Without options it is the default plugin the + * application scene loads (`application.js`). + */ +export { createCesiumRendererPlugin } from './appRenderer.js'; diff --git a/src/render/cesium/ports.js b/src/render/cesium/ports.js index 48a596d13..dbf9a9feb 100644 --- a/src/render/cesium/ports.js +++ b/src/render/cesium/ports.js @@ -14,6 +14,7 @@ */ import * as Cesium from 'cesium'; import { createCesiumCamera } from './camera.js'; +import { createControlledCamera } from './controlledCamera.js'; import { listenerList, toCartesian, uncaught } from './common.js'; import { createCesiumCredits } from './credits.js'; import { createCesiumDraw } from './draw.js'; @@ -109,12 +110,26 @@ export function cesiumCapabilities(scene, only) { /** * @param {object} widget A Cesium `CesiumWidget` or `Viewer`. - * @param {{capabilities: ReadonlySet, credentials?: object}} options + * @param {{capabilities: ReadonlySet, credentials?: object, + * cameraController?: Function, now?: () => 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`). + * (`googleApiKey`, `googleTokens`, `worldDataToken`). `now` is the clock + * each tick reads (`performance.now` by default; a test's virtual one). + * 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, { capabilities, credentials = {} }) { +export function createCesiumPorts( + widget, + { + capabilities, + credentials = {}, + cameraController, + now: clockNow = () => performance.now(), + }, +) { const scene = widget.scene; const camera = scene.camera; @@ -143,7 +158,7 @@ export function createCesiumPorts(widget, { capabilities, credentials = {} }) { let rendered = 0; // Every tick raises preUpdate, drawn or not; the phases of a tick share // its clock reading. The first tick counts from when the loop was made. - let tickNow = performance.now(); + let tickNow = clockNow(); let dt = 0; // The preUpdate FrameTime of the tick under way: its `rendering` reads // live until the tick has drawn or not, then holds that answer. @@ -163,7 +178,7 @@ export function createCesiumPorts(widget, { capabilities, credentials = {} }) { // A tick that does not draw settles at its end; one that does, at // preRender, before this runs. atEndOfTick(scene, () => void settleTick(false)); - const now = performance.now(); + const now = clockNow(); dt = (now - tickNow) / 1000; tickNow = now; frames += 1; @@ -211,9 +226,22 @@ export function createCesiumPorts(widget, { capabilities, credentials = {} }) { answering = 0; }; let disposed = false; + // The camera controller's steps, around the preUpdate listeners + // (`cameraController` only). + let controlled = null; + const cameraTick = (time) => ({ + now: tickNow, + time: Cesium.JulianDate.toDate(time ?? widget.clock.currentTime).getTime(), + }); const removers = [ scene.preUpdate.addEventListener(tick), + scene.preUpdate.addEventListener( + (_scene, time) => void controlled?.before(cameraTick(time)), + ), scene.preUpdate.addEventListener(onPhase('preUpdate')), + scene.preUpdate.addEventListener( + (_scene, time) => void controlled?.after(cameraTick(time)), + ), scene.preRender.addEventListener(drawing), scene.preRender.addEventListener(onPhase('preRender')), scene.postRender.addEventListener(drew), @@ -352,13 +380,48 @@ export function createCesiumPorts(widget, { capabilities, credentials = {} }) { }); const { port: draw, sets, tilesets } = drawPart; - const cameraPart = createCesiumCamera({ + // --- Query ----------------------------------------------------------------- + + const query = createCesiumQuery({ scene, camera, - report, - widget, + draw: drawPart, capabilities, }); + + if (cameraController) + controlled = createControlledCamera({ + scene, + controller: cameraController, + query: { + ...(capabilities.has('pickPosition') + ? { pickPosition: (x, y) => query.pickPosition(x, y) } + : {}), + ...(typeof query.sampleHeightNow === 'function' + ? { sampleHeightNow: (p, o) => query.sampleHeightNow(p, o) } + : {}), + }, + // Where the draw port draws an item, at the scene clock's time. + ...(capabilities.has('motionSegments') + ? { + itemPosition: (item, aheadMs) => + drawPart.drawnPosition(item, aheadMs, widget.clock.currentTime), + } + : {}), + requestRender: (reason) => frame.requestRender(reason), + report, + thresholds: capabilities.has('cameraChangeThreshold'), + followFrame: capabilities.has('followFrame'), + }); + const cameraPart = controlled + ? { port: controlled.port, dispose: () => controlled.dispose() } + : createCesiumCamera({ + scene, + camera, + report, + widget, + capabilities, + }); const cameraPort = cameraPart.port; const effectsPart = createCesiumEffects(scene, { capabilities, @@ -388,15 +451,6 @@ export function createCesiumPorts(widget, { capabilities, credentials = {} }) { credentials, }); - // --- Query ----------------------------------------------------------------- - - const query = createCesiumQuery({ - scene, - camera, - draw: drawPart, - capabilities, - }); - async function capture({ type = 'png' } = {}) { scene.render(widget.clock.currentTime); return new Promise((resolve) => @@ -657,6 +711,12 @@ export function createCesiumPorts(widget, { capabilities, credentials = {} }) { globe: globePart.port, draw, camera: cameraPort, + ...(controlled + ? { + attachInput: (input) => controlled.attachInput(input), + suspendCamera: (reason) => controlled.suspendCamera(reason), + } + : {}), credits: creditsPart.port, query, effects: effectsPart.port, diff --git a/src/render/cesium/sceneRenderer.js b/src/render/cesium/sceneRenderer.js index 765f8aae3..ff976e811 100644 --- a/src/render/cesium/sceneRenderer.js +++ b/src/render/cesium/sceneRenderer.js @@ -34,14 +34,20 @@ const feeds = new WeakMap(); export const pointerFeedOf = (renderer) => feeds.get(renderer) ?? null; /** - * @param {{container: HTMLElement, msaa?: number, capabilities?: Iterable}} options - * `capabilities` limits the renderer to those it lists. + * @param {{container: HTMLElement, msaa?: number, capabilities?: Iterable, + * cameraController?: Function, now?: () => number}} options + * `capabilities` limits the renderer to those it lists; `cameraController` + * puts the camera port on that controller (`controlledCamera.js`); `now` + * is the clock its ticks and pointer events read (`performance.now` by + * default). * @returns {Promise} A renderer with the members listed above. */ export async function createCesiumSceneRenderer({ container, msaa = 4, capabilities: only, + cameraController, + now, }) { const credits = document.createElement('div'); const widget = new Cesium.CesiumWidget(container, { @@ -72,11 +78,19 @@ export async function createCesiumSceneRenderer({ const capabilities = new Set(cesiumCapabilities(scene, only)); - const ports = createCesiumPorts(widget, { capabilities }); + const ports = createCesiumPorts(widget, { + capabilities, + ...(cameraController ? { cameraController } : {}), + ...(now ? { now } : {}), + }); const input = createCesiumInput(widget, { query: ports.query, report: ports.report, + ...(ports.suspendCamera ? { suspendCamera: ports.suspendCamera } : {}), + // Its events' times on the ticks' clock. + ...(now ? { now } : {}), }); + ports.attachInput?.(input.port); // --- Renderer --------------------------------------------------------------