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

+1
View File
@@ -311,6 +311,7 @@
"./render/stub": "./src/render/stub/index.js", "./render/stub": "./src/render/stub/index.js",
"./render/occlusion": "./src/render/occlusion/index.js", "./render/occlusion": "./src/render/occlusion/index.js",
"./render/camera/events": "./src/render/camera/events.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/cesium/unbound": "./src/render/cesium/unbound.js",
"./render/conformance": "./src/render/conformance/index.js", "./render/conformance": "./src/render/conformance/index.js",
"./layers/wildlife-sightings": "./src/layers/wildlifeSightings/index.js", "./layers/wildlife-sightings": "./src/layers/wildlifeSightings/index.js",
+19 -7
View File
@@ -63,11 +63,16 @@ export class ReadonlySet extends Set {
} }
/** /**
* The Cesium plugin over a viewer factory; tests pass a fake one. * The Cesium plugin over a viewer factory; tests pass a fake one. With
* @param {{createViewer?: typeof createApplicationViewer}} [options] * `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({ export function createCesiumRendererPlugin({
createViewer = createApplicationViewer, createViewer = createApplicationViewer,
cameraController,
} = {}) { } = {}) {
return Object.freeze({ return Object.freeze({
id: 'cesium', id: 'cesium',
@@ -101,16 +106,23 @@ export function createCesiumRendererPlugin({
ports = createCesiumPorts(viewer, { ports = createCesiumPorts(viewer, {
capabilities, capabilities,
credentials: { googleApiKey, googleTokens, worldDataToken }, credentials: { googleApiKey, googleTokens, worldDataToken },
...(cameraController ? { cameraController } : {}),
}); });
input = createCesiumInput(viewer, { input = createCesiumInput(viewer, {
query: ports.query, query: ports.query,
report: ports.report, report: ports.report,
...(ports.suspendCamera
? { suspendCamera: ports.suspendCamera }
: {}),
}); });
// Free look is limited to low heights from the start. ports.attachInput?.(input.port);
releaseFreeLook = installFreeLookHeightLimit( // Free look is limited to low heights from the start, on Cesium's
viewer, // own controls (the controller keeps its own limits).
FREE_LOOK_MAX_HEIGHT_METERS, if (!cameraController)
); releaseFreeLook = installFreeLookHeightLimit(
viewer,
FREE_LOOK_MAX_HEIGHT_METERS,
);
configureCreditKeyboardAccess(document); configureCreditKeyboardAccess(document);
offLocale = onLocaleChange(() => offLocale = onLocaleChange(() =>
configureCreditKeyboardAccess(document), configureCreditKeyboardAccess(document),
+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;
}
},
};
}
+381
View File
@@ -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);
});
+10
View File
@@ -5204,6 +5204,16 @@ export function createCesiumDraw({
sets, sets,
version: () => setsVersion, version: () => setsVersion,
tilesets, 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. */ /** Whether a set's ground primitives are still being built. */
building: () => [...sets.values()].some((record) => record.pending), building: () => [...sets.values()].some((record) => record.pending),
/** Each frame, before it draws: the horizon cull. */ /** Each frame, before it draws: the horizon cull. */
+12
View File
@@ -815,6 +815,18 @@ export function createGpuIcons({
} }
return out; 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. */ /** Hide the rows of `ids` (in clusters); show the rest again. */
setClustered(ids) { setClustered(ids) {
const before = clustered; const before = clustered;
+33 -6
View File
@@ -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 * `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} * @returns {import('../conformance/index.js').ConformanceHarness}
*/ */
export function createCesiumHarness({ export function createCesiumHarness({
name = 'cesium', name = 'cesium',
model, model,
missingModel, 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 { return {
name, 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 }) { async create({ viewport, capabilities }) {
const container = document.createElement('div'); const container = document.createElement('div');
container.style.cssText = `position:fixed;left:0;top:0;width:${viewport.width}px;height:${viewport.height}px`; container.style.cssText = `position:fixed;left:0;top:0;width:${viewport.width}px;height:${viewport.height}px`;
document.body.append(container); document.body.append(container);
let renderer; let renderer;
const clock = { ms: performance.now() };
try { try {
renderer = await createCesiumSceneRenderer({ container, capabilities }); renderer = await createCesiumSceneRenderer({
container,
capabilities,
...(cameraController ? { cameraController } : {}),
...(virtual ? { now: () => clock.ms } : {}),
});
} catch (error) { } catch (error) {
container.remove(); container.remove();
throw error; throw error;
@@ -182,18 +200,27 @@ export function createCesiumHarness({
container.remove(); container.remove();
} }
}; };
clocks.set(renderer, clock);
return renderer; 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 // 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. // 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), 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. // What a live motion clock reads.
wallTime: () => Date.now(), wallTime: () => Date.now(),
toEcef, toEcef,
tolerance: DEFAULT_TOLERANCE, tolerance: DEFAULT_TOLERANCE,
flightPaths: 'endpoints', flightPaths: virtual ? 'trace' : 'endpoints',
...(model ? { assets: { model, missingModel } } : {}), ...(model ? { assets: { model, missingModel } } : {}),
}; };
} }
+11 -3
View File
@@ -116,6 +116,9 @@ export const cesiumInputOf = (scene) => inputs.get(scene) ?? null;
* @param {boolean} [options.takeStock] False leaves the viewer's stock * @param {boolean} [options.takeStock] False leaves the viewer's stock
* actions on its own handler, taken off only while suppressed, for a * 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. * 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}} * @returns {{port: object, feed: Function, listenerCount: () => number, dispose: () => void}}
* `feed(type, x, y, extra)` delivers one event as the handler would, for * `feed(type, x, y, extra)` delivers one event as the handler would, for
* the conformance harness. * the conformance harness.
@@ -129,6 +132,7 @@ export function createCesiumInput(
now = () => performance.now(), now = () => performance.now(),
document: dom = globalThis.document, document: dom = globalThis.document,
takeStock = true, takeStock = true,
suspendCamera,
}, },
) { ) {
const scene = widget.scene; const scene = widget.scene;
@@ -167,10 +171,14 @@ export function createCesiumInput(
stockHandler.removeInputAction(STOCK[name]); 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({ const router = createInputRouter({
report, report,
suspendCamera: (reason) => cameraInput.suspend(reason), suspendCamera: suspendCamera ?? ((reason) => cameraInput.suspend(reason)),
supported: { select: has.select, dblclickFollow: has.dblclickFollow }, supported: { select: has.select, dblclickFollow: has.dblclickFollow },
onBehaviour: borrowStock, onBehaviour: borrowStock,
}); });
@@ -453,7 +461,7 @@ export function createCesiumInput(
for (const type of DOM_EVENTS) for (const type of DOM_EVENTS)
dom?.removeEventListener?.(type, record, { capture: true }); dom?.removeEventListener?.(type, record, { capture: true });
if (!handler.isDestroyed?.()) handler.destroy?.(); if (!handler.isDestroyed?.()) handler.destroy?.();
cameraInput.release(); cameraInput?.release();
for (const name of Object.keys(borrowed)) giveBack(name); for (const name of Object.keys(borrowed)) giveBack(name);
if (stockHandler && !stockHandler.isDestroyed?.()) if (stockHandler && !stockHandler.isDestroyed?.())
for (const [name, type] of Object.entries(STOCK)) for (const [name, type] of Object.entries(STOCK))
+10
View File
@@ -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';
+77 -17
View File
@@ -14,6 +14,7 @@
*/ */
import * as Cesium from 'cesium'; import * as Cesium from 'cesium';
import { createCesiumCamera } from './camera.js'; import { createCesiumCamera } from './camera.js';
import { createControlledCamera } from './controlledCamera.js';
import { listenerList, toCartesian, uncaught } from './common.js'; import { listenerList, toCartesian, uncaught } from './common.js';
import { createCesiumCredits } from './credits.js'; import { createCesiumCredits } from './credits.js';
import { createCesiumDraw } from './draw.js'; import { createCesiumDraw } from './draw.js';
@@ -109,12 +110,26 @@ export function cesiumCapabilities(scene, only) {
/** /**
* @param {object} widget A Cesium `CesiumWidget` or `Viewer`. * @param {object} widget A Cesium `CesiumWidget` or `Viewer`.
* @param {{capabilities: ReadonlySet<string>, credentials?: object}} options * @param {{capabilities: ReadonlySet<string>, credentials?: object,
* cameraController?: Function, now?: () => number}} options
* The renderer's capabilities, which gate the members that need them, and * The renderer's capabilities, which gate the members that need them, and
* the credentials its globe loads photoreal tiles and world data with * 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 scene = widget.scene;
const camera = scene.camera; const camera = scene.camera;
@@ -143,7 +158,7 @@ export function createCesiumPorts(widget, { capabilities, credentials = {} }) {
let rendered = 0; let rendered = 0;
// Every tick raises preUpdate, drawn or not; the phases of a tick share // 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. // its clock reading. The first tick counts from when the loop was made.
let tickNow = performance.now(); let tickNow = clockNow();
let dt = 0; let dt = 0;
// The preUpdate FrameTime of the tick under way: its `rendering` reads // The preUpdate FrameTime of the tick under way: its `rendering` reads
// live until the tick has drawn or not, then holds that answer. // 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 // A tick that does not draw settles at its end; one that does, at
// preRender, before this runs. // preRender, before this runs.
atEndOfTick(scene, () => void settleTick(false)); atEndOfTick(scene, () => void settleTick(false));
const now = performance.now(); const now = clockNow();
dt = (now - tickNow) / 1000; dt = (now - tickNow) / 1000;
tickNow = now; tickNow = now;
frames += 1; frames += 1;
@@ -211,9 +226,22 @@ export function createCesiumPorts(widget, { capabilities, credentials = {} }) {
answering = 0; answering = 0;
}; };
let disposed = false; 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 = [ const removers = [
scene.preUpdate.addEventListener(tick), scene.preUpdate.addEventListener(tick),
scene.preUpdate.addEventListener(
(_scene, time) => void controlled?.before(cameraTick(time)),
),
scene.preUpdate.addEventListener(onPhase('preUpdate')), scene.preUpdate.addEventListener(onPhase('preUpdate')),
scene.preUpdate.addEventListener(
(_scene, time) => void controlled?.after(cameraTick(time)),
),
scene.preRender.addEventListener(drawing), scene.preRender.addEventListener(drawing),
scene.preRender.addEventListener(onPhase('preRender')), scene.preRender.addEventListener(onPhase('preRender')),
scene.postRender.addEventListener(drew), scene.postRender.addEventListener(drew),
@@ -352,13 +380,48 @@ export function createCesiumPorts(widget, { capabilities, credentials = {} }) {
}); });
const { port: draw, sets, tilesets } = drawPart; const { port: draw, sets, tilesets } = drawPart;
const cameraPart = createCesiumCamera({ // --- Query -----------------------------------------------------------------
const query = createCesiumQuery({
scene, scene,
camera, camera,
report, draw: drawPart,
widget,
capabilities, 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 cameraPort = cameraPart.port;
const effectsPart = createCesiumEffects(scene, { const effectsPart = createCesiumEffects(scene, {
capabilities, capabilities,
@@ -388,15 +451,6 @@ export function createCesiumPorts(widget, { capabilities, credentials = {} }) {
credentials, credentials,
}); });
// --- Query -----------------------------------------------------------------
const query = createCesiumQuery({
scene,
camera,
draw: drawPart,
capabilities,
});
async function capture({ type = 'png' } = {}) { async function capture({ type = 'png' } = {}) {
scene.render(widget.clock.currentTime); scene.render(widget.clock.currentTime);
return new Promise((resolve) => return new Promise((resolve) =>
@@ -657,6 +711,12 @@ export function createCesiumPorts(widget, { capabilities, credentials = {} }) {
globe: globePart.port, globe: globePart.port,
draw, draw,
camera: cameraPort, camera: cameraPort,
...(controlled
? {
attachInput: (input) => controlled.attachInput(input),
suspendCamera: (reason) => controlled.suspendCamera(reason),
}
: {}),
credits: creditsPart.port, credits: creditsPart.port,
query, query,
effects: effectsPart.port, effects: effectsPart.port,
+17 -3
View File
@@ -34,14 +34,20 @@ const feeds = new WeakMap();
export const pointerFeedOf = (renderer) => feeds.get(renderer) ?? null; export const pointerFeedOf = (renderer) => feeds.get(renderer) ?? null;
/** /**
* @param {{container: HTMLElement, msaa?: number, capabilities?: Iterable<string>}} options * @param {{container: HTMLElement, msaa?: number, capabilities?: Iterable<string>,
* `capabilities` limits the renderer to those it lists. * 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<object>} A renderer with the members listed above. * @returns {Promise<object>} A renderer with the members listed above.
*/ */
export async function createCesiumSceneRenderer({ export async function createCesiumSceneRenderer({
container, container,
msaa = 4, msaa = 4,
capabilities: only, capabilities: only,
cameraController,
now,
}) { }) {
const credits = document.createElement('div'); const credits = document.createElement('div');
const widget = new Cesium.CesiumWidget(container, { const widget = new Cesium.CesiumWidget(container, {
@@ -72,11 +78,19 @@ export async function createCesiumSceneRenderer({
const capabilities = new Set(cesiumCapabilities(scene, only)); 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, { const input = createCesiumInput(widget, {
query: ports.query, query: ports.query,
report: ports.report, report: ports.report,
...(ports.suspendCamera ? { suspendCamera: ports.suspendCamera } : {}),
// Its events' times on the ticks' clock.
...(now ? { now } : {}),
}); });
ports.attachInput?.(input.port);
// --- Renderer -------------------------------------------------------------- // --- Renderer --------------------------------------------------------------