refactor(overlays): use the globe engine

The world overlay host takes its frames (frames.postRender), camera events
(camera.moveEnd), canvas size (host.size), projection matrix
(projector.viewProjection), horizon test (projector.horizonVisible) and
render requests (render.request('world-overlay')) from the globe engine.
initWorldOverlay accepts an engine or, for callers that still hold a
viewer, resolves the viewer's engine through engineFromViewer.

Contract: camera.position(result) becomes camera.livePosition, one
engine-owned object holding the current position, so per-frame readers
and paint lanes keep a live camera position without allocating; engine
events gain raiseValue for argument-list-free frame dispatch. Steady-state
frame allocation is unchanged (worker probe, 30 chunks: 2696/9536/38593
B/frame before and after; detection 473749 -> 408085).
This commit is contained in:
German Khokhlov committed 2026-10-15 18:32:40 +04:00
1 parent 58a196374f
commit aaa6074663
11 files changed
+284 -134

No files matched your search

+3 -7
View File
@@ -111,13 +111,9 @@ export function createCesiumCamera(viewer) {
fovy: cesium.frustum.fovy,
};
},
position(result) {
const { x, y, z } = cesium.positionWC;
if (!result) return geo.cartesian3.create(x, y, z);
result.x = x;
result.y = y;
result.z = z;
return result;
// Cesium updates positionWC in place; it is the live object.
get livePosition() {
return cesium.positionWC;
},
height: () => cesium.positionCartographic.height,
setView(view) {
+3 -9
View File
@@ -347,16 +347,10 @@ test('rectangle destinations become a Cesium.Rectangle in flyTo and setView', ()
}
});
test('position fills a result from positionWC and height reads the camera cartographic', () => {
test('livePosition is the Cesium camera positionWC and height reads its cartographic', () => {
const { camera, cesium } = setup();
cesium.positionCartographic = new Cesium.Cartographic(0.1, 0.2, 1234.5);
const result = geo.cartesian3.create();
assert.equal(camera.position(result), result);
assert.deepEqual({ ...result }, { x: 7e6, y: 1e5, z: 2e5 });
const fresh = camera.position();
notCesium(fresh, 'position()');
assert.notEqual(fresh, cesium.positionWC);
assert.deepEqual({ ...fresh }, { x: 7e6, y: 1e5, z: 2e5 });
assert.equal(camera.livePosition, cesium.positionWC);
assert.equal(camera.height(), 1234.5);
});
@@ -364,5 +358,5 @@ test('the camera is the viewer camera (Viewer.camera is scene.camera)', () => {
const viewer = createFakeViewer();
const own = { ...viewer.camera, positionWC: new Cesium.Cartesian3(1, 2, 3) };
const { camera } = createCesiumCamera({ ...viewer, camera: own });
assert.deepEqual({ ...camera.position() }, { x: 1, y: 2, z: 3 });
assert.equal(camera.livePosition, own.positionWC);
});
+1 -1
View File
@@ -18,7 +18,7 @@ import { createEngineEvent } from '../contract.js';
export function bridgeEvent(source, mapArgs, { unary } = {}) {
const event = createEngineEvent();
const forward = unary
? (a, b, c) => event.raiseEvent(unary(a, b, c))
? (a, b, c) => event.raiseValue(unary(a, b, c))
: mapArgs
? (...args) => event.raiseEvent(...mapArgs(...args))
: (...args) => event.raiseEvent(...args);
+34 -11
View File
@@ -83,9 +83,10 @@
*
* @typedef {object} GlobeCamera
* @property {() => CameraPose} pose Fresh values on every call.
* @property {(result?: Cartesian3) => Cartesian3} position The pose's world
* position; fills and returns `result` when given (no allocation, for
* per-frame readers), else a fresh value.
* @property {Cartesian3} livePosition The pose's world position as one
* engine-owned object: the same object on every read, holding the current
* position (at the latest when read). For per-frame readers, which must not
* allocate; read-only, copy it to keep a value.
* @property {() => number} height The camera's height above the WGS84
* ellipsoid (the pose's cartographic height), without building a pose.
* @property {(view: { destination: Cartesian3 | Rectangle, orientation?: Orientation }) => void} setView
@@ -209,9 +210,10 @@ export const isEngineEvent = (value) =>
value != null && value[ENGINE_EVENT] === true;
/**
* An event with the contract's semantics (see EngineEvent). `raiseEvent` is
* for engine implementations; a listener that throws propagates, and the
* event stays usable.
* An event with the contract's semantics (see EngineEvent). `raiseEvent` and
* `raiseValue` (one argument, no argument list: for per-frame events) are for
* engine implementations; a listener that throws propagates, and the event
* stays usable.
*/
export function createEngineEvent() {
let entries = [];
@@ -226,6 +228,13 @@ export function createEngineEvent() {
else entries.splice(entries.indexOf(entry), 1);
return true;
};
const settle = () => {
depth--;
if (!depth && removedDuringRaise) {
entries = entries.filter((entry) => entry.listener);
removedDuringRaise = false;
}
};
const event = {
get numberOfListeners() {
return entries.reduce(
@@ -259,11 +268,21 @@ export function createEngineEvent() {
if (listener) listener(...args);
}
} finally {
depth--;
if (!depth && removedDuringRaise) {
entries = entries.filter((entry) => entry.listener);
removedDuringRaise = false;
settle();
}
},
// raiseEvent(value) without an argument list, for per-frame events.
raiseValue(value) {
const snapshot = entries;
const length = snapshot.length;
depth++;
try {
for (let index = 0; index < length; index++) {
const listener = snapshot[index].listener;
if (listener) listener(value);
}
} finally {
settle();
}
},
};
@@ -282,7 +301,11 @@ const SHAPE = {
host: { container: isObject, canvas: isObject, size: isFunction },
camera: {
pose: isFunction,
position: isFunction,
livePosition: (value) =>
value != null &&
isNumber(value.x) &&
isNumber(value.y) &&
isNumber(value.z),
height: isFunction,
setView: isFunction,
flyTo: isFunction,
+17 -3
View File
@@ -188,7 +188,7 @@ test('assertGlobeEngine accepts a complete engine and names every missing capabi
test('the contract carries what the shell infrastructure needs', () => {
for (const member of [
'camera.position',
'camera.livePosition',
'camera.height',
'maps.releasePhotorealTiles',
])
@@ -196,12 +196,12 @@ test('the contract carries what the shell infrastructure needs', () => {
const engine = createFakeEngine();
const broken = {
...engine,
camera: { ...engine.camera, position: undefined, height: 1 },
camera: { ...engine.camera, livePosition: undefined, height: 1 },
maps: { ...engine.maps, releasePhotorealTiles: undefined },
};
assert.throws(
() => assertGlobeEngine(broken),
/camera\.position.*camera\.height.*maps\.releasePhotorealTiles/,
/camera\.livePosition.*camera\.height.*maps\.releasePhotorealTiles/,
);
});
@@ -256,3 +256,17 @@ test('the contract suite rejects a raw Cesium-style event that double-registers'
failed.join('\n'),
);
});
test('raiseValue raises exactly one argument with the event semantics', () => {
const event = createEngineEvent();
const seen = [];
const second = (...values) => seen.push(['second', values]);
event.addEventListener((...values) => {
seen.push(['first', values]);
event.removeEventListener(second);
});
event.addEventListener(second);
event.raiseValue(42);
assert.deepEqual(seen, [['first', [42]]]);
assert.equal(event.numberOfListeners, 1);
});
+21 -19
View File
@@ -177,38 +177,40 @@ export function createContractSuite(
},
],
[
'camera.position and camera.height: the pose position and height, without a pose',
'camera.livePosition and camera.height: the pose position and height, without a pose',
async () => {
camera.setView({
destination: cartesian3.fromDegrees(-3.7, 40.4, 12000),
orientation: { heading: 0.4, pitch: -0.5, roll: 0 },
});
await settle();
const pose = camera.pose();
const result = cartesian3.create();
const filled = camera.position(result);
ensure(
filled === result,
'position(result) returns the result it filled',
);
const live = camera.livePosition;
ensure(isCartesian3(live), 'livePosition is a Cartesian3');
near(
cartesian3.distance(filled, pose.position),
cartesian3.distance(live, camera.pose().position),
0,
1e-6,
'position(result) vs pose().position',
);
const fresh = camera.position();
ensure(
isCartesian3(fresh) && fresh !== filled,
'position() returns a fresh Cartesian3',
'livePosition vs pose().position',
);
near(
cartesian3.distance(fresh, pose.position),
camera.height(),
camera.pose().cartographic.height,
0.01,
'height()',
);
const destination = cartesian3.fromDegrees(2.35, 48.85, 30000);
camera.setView({ destination });
await settle();
ensure(
camera.livePosition === live,
'livePosition is the same engine-owned object on every read',
);
near(
cartesian3.distance(camera.livePosition, destination),
0,
1e-6,
'position() vs pose().position',
1e-3,
'livePosition follows the camera',
);
near(camera.height(), pose.cartographic.height, 0.01, 'height()');
},
],
[
+9 -8
View File
@@ -210,8 +210,10 @@ function rectangleFromCartographics(points) {
/**
* @param {{ kind?: 'cesium'|'navara', width?: number, height?: number, fovy?: number,
* longitude?: number, latitude?: number, altitude?: number }} [options]
* Canvas size in CSS px, angles in radians. The initial pose looks straight
* longitude?: number, latitude?: number, altitude?: number,
* container?: object, canvas?: object }} [options]
* Canvas size in CSS px, angles in radians; `container`/`canvas` stand in
* for the host elements (DOM mocks for shell tests). The initial pose looks straight
* down from `altitude` metres (10 000 km).
* @returns {import('../contract.js').GlobeEngine & { fake: object }}
*/
@@ -238,6 +240,7 @@ export function createFakeEngine(options = {}) {
'frames.postRender': createEngineEvent(),
};
const inputs = new Map(INPUT_TYPES.map((type) => [type, new Set()]));
const livePosition = cartesian3.create();
const scripts = new Map();
let transform = [...matrix4.IDENTITY];
let percentageChanged = 0.5;
@@ -602,10 +605,8 @@ export function createFakeEngine(options = {}) {
fovy,
};
},
position(result) {
return result
? cartesian3.clone(state.position, result)
: copy3(state.position);
get livePosition() {
return cartesian3.clone(state.position, livePosition);
},
height: () => cartographic.fromCartesian(state.position, WGS84).height,
setView(view) {
@@ -718,8 +719,8 @@ export function createFakeEngine(options = {}) {
};
const host = {
container: { kind: 'fake-container' },
canvas: { kind: 'fake-canvas' },
container: options.container ?? { kind: 'fake-container' },
canvas: options.canvas ?? { kind: 'fake-canvas' },
size: () => ({ width, height }),
};
+19 -4
View File
@@ -354,12 +354,27 @@ test('fake drillPick records width and height; maps return promises', async () =
}
});
test('fake camera position fills a result and height is the pose height', () => {
test('fake livePosition is one object that follows the camera; height is the pose height', () => {
const engine = createFakeEngine({ altitude: 2_000_000 });
const result = geo.cartesian3.create();
assert.equal(engine.camera.position(result), result);
const live = engine.camera.livePosition;
assert.ok(
geo.cartesian3.distance(result, engine.camera.pose().position) < 1e-6,
geo.cartesian3.distance(live, engine.camera.pose().position) < 1e-6,
);
assert.ok(Math.abs(engine.camera.height() - 2_000_000) < 0.01);
engine.fake.setPose({ longitude: 0.3, latitude: 0.2, height: 500 });
assert.equal(engine.camera.livePosition, live);
assert.ok(
geo.cartesian3.distance(live, engine.camera.pose().position) < 1e-6,
);
});
test('fake host elements can be supplied', () => {
const container = { id: 'globe' };
const canvas = { id: 'canvas' };
const engine = createFakeEngine({ container, canvas });
assert.equal(engine.host.container, container);
assert.equal(engine.host.canvas, canvas);
assert.deepEqual(createFakeEngine().host.container, {
kind: 'fake-container',
});
});