Read the HUD and share-link camera through the renderer's camera port

The first camera-family slice. The camera port's events move into a
shared module (render/camera/events.js) that the stub and the Cesium
port both use: listener lists, delivery with errors reported, and the
contract's per-listener `changed` measure.

The Cesium port gains:
- camera.on: `changed` measured per listener on every tick, where Cesium
  measures its single threshold (the counts match Cesium's own at each
  threshold); moveStart and moveEnd relayed from Cesium's camera;
- camera.viewRectangle, in degrees (now in CESIUM_CHECKS);
- lon and lat in pose, and NaN where Cesium has no cartographic position.

Code that still holds the viewer reaches the renderer through
rendererOf(viewer); the application renderer binds it on create and
unbinds on destroy.

The HUD reads its telemetry from the camera port and no longer imports
Cesium (off the allow-list). The share link writes the hash from the
pose. Its restore path stays on the viewer's camera for a later slice.

Behaviour changes:
- The share link listens to `changed` at its own 0.5 threshold, not at
  whatever global threshold layers had set, and also to moveEnd, so the
  hash always catches up with where the camera comes to rest.
- The HUD's and share link's camera callbacks run from the port's single
  relay, ahead of other moveStart/moveEnd listeners, and a throw in one
  is reported to the renderer's error listeners instead of escaping from
  Cesium's render.
This commit is contained in:
Sameh Khamis committed 2026-11-05 19:48:58 -08:00
1 parent 910185bfe0
commit b5900b4178
28 files changed
+688 -243

No files matched your search

+118
View File
@@ -0,0 +1,118 @@
/**
* @module render/camera/events
* @description The camera port's events, shared by the Cesium port and the stub: the
* listener lists, delivery (a throwing listener is reported, the rest still
* run), and the contract's per-listener `changed` measure. A renderer calls
* `stepChanged()` once per frame and `emit()` for the events its engine
* raises.
*/
import { acosClamped, distance, dot } from '../../geo/index.js';
const TWO_PI = Math.PI * 2;
/** The contract's camera events. */
export const CAMERA_EVENTS = Object.freeze([
'changed',
'moveStart',
'moveEnd',
'followChanged',
'flightEnd',
]);
/** How far an angle moved, as a fraction of π, the short way round. */
const angleDelta = (a, b) => {
const d = Math.abs(a - b) % TWO_PI;
return (d > Math.PI ? TWO_PI - d : d) / Math.PI;
};
/**
* @param {{pose: () => import('../contract/camera').CameraPose,
* report: (error: unknown) => void}} options `pose` is read only while a
* `changed` listener is registered.
*/
export function createCameraEvents({ pose, report }) {
const listeners = Object.fromEntries(CAMERA_EVENTS.map((e) => [e, []]));
function deliver(entry) {
if (!entry.live) return;
try {
entry.cb();
} catch (error) {
report(error);
}
}
function emit(event) {
for (const entry of listeners[event].slice()) deliver(entry);
}
/**
* @param {string} event
* @param {() => void} cb
* @param {{threshold?: number}} [options]
* @returns {() => void}
*/
function on(event, cb, options = {}) {
const list = listeners[event];
if (!list) throw new Error(`Unknown camera event: ${event}`);
const entry = { cb, live: true, threshold: options.threshold ?? 0.5 };
list.push(entry);
return () => {
entry.live = false;
const i = list.indexOf(entry);
if (i >= 0) list.splice(i, 1);
};
}
/**
* Per listener, the reference camera's formula: heading and roll each
* against their own last reported value, then direction and position
* against the last reported view. Each can report in the same frame.
*/
function stepChanged() {
const list = listeners.changed;
if (!list.length) return;
const current = pose();
for (const entry of list.slice()) {
if (!entry.live) continue;
const t = entry.threshold;
entry.heading ??= current.heading;
entry.roll ??= current.roll;
const headingF = angleDelta(entry.heading, current.heading);
const rollF = angleDelta(entry.roll, current.roll);
if (headingF > t) entry.heading = current.heading;
if (rollF > t) entry.roll = current.roll;
if (headingF > t || rollF > t) deliver(entry);
if (!entry.view) {
entry.view = {
position: current.position,
direction: current.direction,
};
continue;
}
const dirF =
acosClamped(dot(current.direction, entry.view.direction)) /
(current.fovy * 0.5);
const heightF =
distance(current.position, entry.view.position) / current.height;
if (dirF > t || heightF > t) {
entry.view = {
position: current.position,
direction: current.direction,
};
deliver(entry);
}
}
}
/** Drop every listener, including those of an event under way. */
function clear() {
for (const list of Object.values(listeners)) {
for (const entry of list) entry.live = false;
list.length = 0;
}
}
return { on, emit, stepChanged, clear };
}