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

+65 -71
View File
@@ -1,4 +1,6 @@
import * as Cesium from 'cesium';
import * as geo from '../geo/index.js';
import { engineFromViewer } from '../globe/cesium/engineFromViewer.js';
import {
createCyberSonarSampler,
isCyberContactSonarActive as isCyberSonarActive,
@@ -27,6 +29,11 @@ import { WORLD_OVERLAY_STYLE } from './worldOverlayTokens.js';
* @description Shared screen-space renderer/scheduler for world-anchored
* labels and cards. Sources own data, business rules, and bounded candidate
* generation; this host owns projection, final placement, paint, and hits.
*
* It runs on the page's globe engine (src/globe/contract.js): frames, camera
* events, canvas size, projection matrix, horizon test and render requests
* all come from the engine. Sources still hand it world positions they
* computed themselves.
*/
const ROOT_ID = 'world-overlay-root';
@@ -131,7 +138,7 @@ export const WORLD_OVERLAY_OCCLUDER_SELECTORS = Object.freeze([
* @typedef {object} WorldOverlayEntry
* @property {string} id Stable identity within the source.
* @property {string} source Owning source id.
* @property {Cesium.Cartesian3|function():Cesium.Cartesian3} position
* @property {{x: number, y: number, z: number}|function():{x: number, y: number, z: number}} position
* @property {'label'|'track'|'card'|'thumbnail'|'selected'|'tracked'} variant
* @property {string} [accessibilityLabel] Accessible name for an actionable card.
* @property {function():*} [activate] Keyboard/assistive activation callback.
@@ -148,8 +155,8 @@ export const WORLD_OVERLAY_OCCLUDER_SELECTORS = Object.freeze([
* @property {number} [solveIntervalMs=125]
*/
/** @type {Cesium.Viewer|null} */
let _viewer = null;
/** @type {import('../globe/contract.js').GlobeEngine|null} */
let _engine = null;
/** @type {HTMLElement|null} */
let _root = null;
/** @type {HTMLCanvasElement|null} */
@@ -218,13 +225,14 @@ const _domains = new Map();
const _domainList = [];
/** @type {Map<string, object>} */
const _records = new Map();
const _scratchViewProjection = new Cesium.Matrix4();
const _scratchViewProjection = geo.matrix4.create();
const _viewProjectionScalars = {};
const _viewport = { width: 0, height: 0 };
/** `{ isPointVisible }` over the engine's horizon test, for painters too. */
let _occluder = null;
let _occluderCameraX = Number.NaN;
let _occluderCameraY = Number.NaN;
let _occluderCameraZ = Number.NaN;
/** The engine's live camera position and the camera height, per frame. */
let _cameraPosition = null;
let _cameraHeight = Number.NaN;
/** Cached keyhole geometry, versioned by both its box and shared tuning. */
let _keyhole = null;
let _keyholeWidth = -1;
@@ -421,6 +429,7 @@ function snapshotCullPosition(entry) {
const { x, y, z } = candidate;
if (!Number.isFinite(x) || !Number.isFinite(y) || !Number.isFinite(z))
return null;
// Still the sources' own vector type until they move off Cesium (phase 1c).
return new Cesium.Cartesian3(x, y, z);
}
@@ -860,7 +869,11 @@ function invalidateHost({ solve = true, layout = false } = {}) {
_paintRectCount = 0;
_hitRectCount = 0;
_paintRectByKey.clear();
_viewer?.scene?.requestRender?.();
requestRender();
}
function requestRender() {
_engine?.render.request('world-overlay');
}
function inertPaintLaneHandle() {
@@ -1227,9 +1240,10 @@ function ensureOverlayDom() {
_root = document.createElement('div');
_root.id = ROOT_ID;
_root.setAttribute('aria-hidden', 'true');
const parent = _viewer.container?.parentElement || document.body;
if (_viewer.container?.nextSibling)
parent.insertBefore(_root, _viewer.container.nextSibling);
const container = _engine.host.container;
const parent = container?.parentElement || document.body;
if (container?.nextSibling)
parent.insertBefore(_root, container.nextSibling);
else parent.appendChild(_root);
}
_canvas =
@@ -1249,7 +1263,7 @@ function ensureOverlayDom() {
// the browser silently discard the blend while the CSS string stayed
// `'screen'`. Paint order is expressed purely by z-index: this surface is
// z5, the shared card canvas inside the root is z6.
const detectionParent = _viewer?.container || document.body;
const detectionParent = _engine?.host.container || document.body;
_detectionSurface =
detectionParent.querySelector?.(`#${DETECTION_SURFACE_ID}`) ||
document.getElementById(DETECTION_SURFACE_ID);
@@ -1317,15 +1331,10 @@ function sizeCanvasSurface(canvas, ctx, width, height, dpr) {
* that actually has paint work.
*/
function ensureCanvasSize() {
if (!_canvas || !_viewer?.canvas) return false;
const width = Math.max(
0,
Math.round(Number(_viewer.canvas.clientWidth) || 0),
);
const height = Math.max(
0,
Math.round(Number(_viewer.canvas.clientHeight) || 0),
);
if (!_canvas || !_engine) return false;
const size = _engine.host.size();
const width = Math.max(0, Math.round(Number(size.width) || 0));
const height = Math.max(0, Math.round(Number(size.height) || 0));
const dpr = Math.max(1, Number(globalThis.window?.devicePixelRatio) || 1);
const changed =
_canvas.width !== Math.round(width * dpr) ||
@@ -1450,7 +1459,7 @@ function refreshUiOccluders(timestamp, force = false) {
_occluderRefreshTimer = setTimeout(
() => {
_occluderRefreshTimer = null;
_viewer?.scene?.requestRender?.();
requestRender();
},
Math.max(0, OCCLUDER_REFRESH_MS - elapsed),
);
@@ -1694,12 +1703,7 @@ function overlayHasPaintWork(timestamp = nowMs()) {
}
function prepareProjectionMatrix() {
const camera = _viewer.camera;
const matrix = Cesium.Matrix4.multiply(
camera.frustum.projectionMatrix,
camera.viewMatrix,
_scratchViewProjection,
);
const matrix = _engine.projector.viewProjection(_scratchViewProjection);
_viewProjectionScalars.m0 = matrix[0];
_viewProjectionScalars.m1 = matrix[1];
_viewProjectionScalars.m3 = matrix[3];
@@ -1717,17 +1721,9 @@ function prepareProjectionMatrix() {
function prepareCustomPaintFrame(timestamp, keyhole) {
const viewProjection = prepareProjectionMatrix();
const camera = _viewer.camera.positionWC;
if (
camera.x !== _occluderCameraX ||
camera.y !== _occluderCameraY ||
camera.z !== _occluderCameraZ
) {
_occluder.cameraPosition = camera;
_occluderCameraX = camera.x;
_occluderCameraY = camera.y;
_occluderCameraZ = camera.z;
}
const camera = _engine.camera.livePosition;
_cameraPosition = camera;
_cameraHeight = _engine.camera.height();
_customPaintFrame.canvas = _canvas;
_customPaintFrame.surface = _canvas;
_customPaintFrame.ctx = _ctx;
@@ -1749,7 +1745,7 @@ function getProjectionRecord(entry) {
record = {
key: entry._overlayKey,
entry,
position: new Cesium.Cartesian3(),
position: geo.cartesian3.create(),
screen: { x: 0, y: 0 },
layout: entry._overlayLayout,
placements: [],
@@ -1933,7 +1929,7 @@ function snapshotAndProject(entry, source, viewProjection, keyhole) {
// scalar steps stay local: the range is computed inline, and the common
// "no far limit" fade policy resolves without calling out at all. Both are
// exact restatements of `Cartesian3.distance` / `distanceFade`.
const cameraPosition = _viewer.camera.positionWC;
const cameraPosition = _cameraPosition;
const rangeX = cameraPosition.x - record.position.x;
const rangeY = cameraPosition.y - record.position.y;
const rangeZ = cameraPosition.z - record.position.z;
@@ -1946,7 +1942,7 @@ function snapshotAndProject(entry, source, viewProjection, keyhole) {
? 1
: 0
: distanceFade(distance, record.distanceOptions);
const cameraAltitude = _viewer.camera.positionCartographic?.height;
const cameraAltitude = _cameraHeight;
record.paintScale = entry.distanceScale
? distanceScale(distance, entry.distanceScale)
: 1;
@@ -2607,7 +2603,7 @@ function drawWorldOverlay() {
clearTimeout(_sonarRenderTimer);
_sonarRenderTimer = null;
}
if (_destroyed || !_viewer || !_canvas || !_ctx) return;
if (_destroyed || !_engine || !_canvas || !_ctx) return;
const timestamp = nowMs();
if (!overlayHasPaintWork(timestamp)) {
resetFrameDiagnostics();
@@ -2653,13 +2649,12 @@ function drawWorldOverlay() {
if (_paintRectCount > 0 && isCyberSonarActive()) {
_sonarRenderTimer = setTimeout(() => {
_sonarRenderTimer = null;
if (!_destroyed && isCyberSonarActive())
_viewer?.scene?.requestRender?.();
if (!_destroyed && isCyberSonarActive()) requestRender();
}, CYBER_SONAR_RENDER_INTERVAL_MS);
}
const animationsRemaining =
activeFadeCount(timestamp) + activeLeaderAnimationCount(timestamp);
if (animationsRemaining > 0) _viewer.scene.requestRender?.();
if (animationsRemaining > 0) requestRender();
}
function createDevFacade() {
@@ -2668,37 +2663,37 @@ function createDevFacade() {
}
/**
* Initialize the singleton host. Repeated calls for the same viewer are no-op.
* @param {Cesium.Viewer} viewer
* Initialize the singleton host. Repeated calls for the same engine are no-op.
* @param {import('../globe/contract.js').GlobeEngine | object} target The
* globe engine, or a Cesium viewer (its engine: engineFromViewer).
*/
export function initWorldOverlay(viewer) {
if (!viewer?.scene?.postRender?.addEventListener) {
export function initWorldOverlay(target) {
const engine = engineFromViewer(target);
if (!engine)
throw new TypeError(
'initWorldOverlay requires a Cesium viewer with scene.postRender',
'initWorldOverlay requires a globe engine or a Cesium viewer',
);
}
if (_viewer === viewer && _canvas && _removePostRender) return;
if (_viewer) destroyWorldOverlay();
if (_engine === engine && _canvas && _removePostRender) return;
if (_engine) destroyWorldOverlay();
_destroyed = false;
_viewer = viewer;
_engine = engine;
ensureOverlayDom();
_occluder = new Cesium.EllipsoidalOccluder(
Cesium.Ellipsoid.WGS84,
viewer.camera?.positionWC || new Cesium.Cartesian3(),
);
const { projector } = engine;
_occluder = {
isPointVisible: (position) => projector.horizonVisible(position),
};
_cockpitActive = !!document.body?.classList?.contains('cockpit-mode');
_cockpitModeHandler = (event) => {
_cockpitActive = event?.detail?.active === true;
invalidateHost();
};
window.addEventListener('gev:cockpit-mode-changed', _cockpitModeHandler);
_removePostRender =
viewer.scene.postRender.addEventListener(drawWorldOverlay);
if (viewer.camera?.moveEnd?.addEventListener) {
_removeMoveEnd = viewer.camera.moveEnd.addEventListener(() =>
invalidateHost(),
);
}
_removePostRender = engine.frames.postRender.addEventListener(() =>
drawWorldOverlay(),
);
_removeMoveEnd = engine.camera.moveEnd.addEventListener(() =>
invalidateHost(),
);
installUiOccluderObservers();
// The backing store and the occluder inventory are both deferred to the
// first frame with real paint work: a dormant host must not hold a
@@ -2719,7 +2714,7 @@ export function destroyWorldOverlay() {
// Tearing down a host that was never initialized must not arm the
// post-destroy guard: sources are allowed to publish before the first
// `initWorldOverlay`, and that buffering has to survive a stray destroy.
const hadHost = _viewer !== null;
const hadHost = _engine !== null;
_removePostRender?.();
_removePostRender = null;
_removeMoveEnd?.();
@@ -2785,7 +2780,7 @@ export function destroyWorldOverlay() {
_uiOcclusionRects.length = 0;
_uiOcclusionRectPool.length = 0;
_destroyed = hadHost || _destroyed;
_viewer = null;
_engine = null;
_root = null;
_canvas = null;
_ctx = null;
@@ -2795,9 +2790,8 @@ export function destroyWorldOverlay() {
_detectionSurface = null;
_detectionCtx = null;
_occluder = null;
_occluderCameraX = Number.NaN;
_occluderCameraY = Number.NaN;
_occluderCameraZ = Number.NaN;
_cameraPosition = null;
_cameraHeight = Number.NaN;
_keyhole = null;
_keyholeWidth = -1;
_keyholeHeight = -1;