Replace Cesium monkey-patches with hooks and keep internals in one module

The arrival ground guard replaced camera.flyTo, flyToBoundingSphere,
setView, lookAt and cancelFlight with wrappers so a direct caller would stop
it. It now remembers the pose it started on and, before each retry, yields
if a flight is under way or the camera has moved across the ground, down or
around. A straight rise is not a move: Cesium's terrain collision lifts a
buried eye that way as tiles load, which is the case the guard exists for.
This also catches owners the wrappers missed (a pose written directly,
lookAtTransform), and no camera method is replaced.

Recent imagery and weather overwrote provider.requestImage (weather also
provider.credit) to ration tiles. They now state that policy as a hook with
withTileRequestHook(provider, { requestImage, credit }) from
src/render/cesium/tileRequests.js, which hands Cesium a provider delegating
to the original and leaves the original untouched.

Every private Cesium field the app reaches goes through a named helper in
src/render/cesium/internals.js: the main and offscreen pick views and their
command extents, a billboard's collection, a cluster's point collection,
the widget's render-loop latch, the WebGL context and the current camera
flight. internals.test.mjs fails when the installed Cesium stops declaring
one of them, and a source scan fails on private access anywhere else. The
cyber sonar's primitives.update wrap stays until the effects work.

Live (Austin, keyless globe): a buried eye is lifted to 253 m over a 133 m
surface; a setView or flyTo by another caller makes the guard yield; radar
loads its tiles through the hook. Documented in docs/APPLICATION.md and
docs/CURRENT-STATE.md.
This commit is contained in:
Sameh Khamis committed 2026-11-04 11:15:35 -08:00
1 parent 9bdeffeca3
commit 18d6e3292d
18 files changed
+597 -125

No files matched your search

+86
View File
@@ -0,0 +1,86 @@
/**
* @module render/cesium/internals
* @description Every read or write of a private Cesium field, in one place.
*
* The app otherwise uses Cesium's public API. Each helper here names one private
* field the app depends on and says why; `internals.test.mjs` fails when the
* installed Cesium no longer declares one of them, and a source scan fails
* when a private field is reached anywhere else.
*/
/**
* The scene's main view, whose per-pass command arrays outlive a frame.
* Used by `sceneCommandRelease.js` to drop references to destroyed commands.
* @param {object} scene Cesium Scene.
* @returns {object|undefined} Cesium `View`.
*/
export function defaultView(scene) {
return scene?._defaultView;
}
/**
* The offscreen view `sampleHeight` and `pickFromRay` render into.
* @param {object} scene Cesium Scene.
* @returns {object|undefined} Cesium `View`.
*/
export function pickOffscreenView(scene) {
return scene?._picking?._pickOffscreenView;
}
/**
* A view's command-extent records, each holding the command it last drew.
* @param {object} view Cesium `View`.
* @returns {Array<{command: object}>}
*/
export function commandExtents(view) {
return view?._commandExtents || [];
}
/**
* The collection a picked billboard belongs to; Cesium's pick result names
* the billboard, not its collection.
* @param {object} billboard Cesium Billboard.
* @returns {object|undefined} Cesium BillboardCollection.
*/
export function billboardCollectionOf(billboard) {
return billboard?._billboardCollection;
}
/**
* The point collection an `EntityCluster` draws its cluster markers into.
* @param {object} clustering Cesium EntityCluster.
* @returns {object|null} Cesium PointPrimitiveCollection.
*/
export function clusterPointCollection(clustering) {
return clustering?._clusterPointCollection || null;
}
/**
* Close the widget's pending render-loop latch after `useDefaultRenderLoop`
* is set false, so a callback already queued sees the loop as stopped and
* manual renders start without waiting a vsync.
* @param {object} viewer Cesium Viewer.
*/
export function closeRenderLoopLatch(viewer) {
const widget = viewer?._cesiumWidget;
if (widget) widget._renderLoopRunning = false;
}
/**
* The scene's WebGL context, for diagnostics that read the GPU directly.
* @param {object} scene Cesium Scene.
* @returns {WebGLRenderingContext|WebGL2RenderingContext|undefined}
*/
export function webglContext(scene) {
return scene?.context?._gl;
}
/**
* Whether a camera flight is under way. Cesium clears it before calling a
* flight's `complete`, so it reads false inside that callback.
* @param {object} camera Cesium Camera.
* @returns {boolean}
*/
export function cameraFlightActive(camera) {
return camera?._currentFlight != null;
}