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.
This commit is contained in:
Sameh Khamis committed 2026-11-12 11:41:54 -08:00
1 parent 1a7ef7fc7a
commit aa58886e40
11 files changed
+826 -36

No files matched your search

+255
View File
@@ -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;
}
},
};
}