Files
gods-eye-view/src/render/cesium/internals.js
T
Sameh Khamis 4ed51930c2 Give a viewer of its own a frame port, and use it for the active fires layer
findFrame and frameOf find the bound renderer's frame port or, for a
caller's viewer with no renderer bound, one the Cesium adapter's factory
builds over it, as findQuery and findDraw do. Unlike the renderer's own,
it leaves the viewer's loop as its owner set it up: it listens to the
scene's phases, asks for frames, holds by asking again after each one
drawn, and maps suspend, the target rate and scene time onto the viewer.
Its preUpdate says whether the tick draws by the same test the renderer's
frame port makes, now shared by both.

The active fires layer's cards and LOD watcher take their query and frame
ports from findQuery and findFrame, in place of the layer's own copy of
projection, occlusion and preRender over the viewer's scene.
2026-11-06 22:25:07 -08:00

217 lines
7.3 KiB
JavaScript

/**
* @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;
}
/**
* Whether the scene has a render pending that its next tick will draw in
* request-render mode: a request, or a depth-buffer or HDR change. With
* `cameraMovedSinceRender` and the time check, this is the test
* `Scene.render` makes after `preUpdate`, so the frame port can say at
* `preUpdate` whether the tick draws.
* @param {object} scene Cesium Scene.
* @returns {boolean}
*/
export function renderPending(scene) {
return Boolean(
scene._renderRequested || scene._logDepthBufferDirty || scene._hdrDirty,
);
}
/**
* Calls `cb` each time Cesium completes a request or a worker task, in any
* scene. A scene redraws on its own after each (its `requestRenderAfterFrame`
* listeners): a terrain picker build after the camera moves, say, which no
* loading flag shows. `whenSettled` uses it to tell when that work has
* stopped. Both events are marked private.
* @param {{RequestScheduler: object, TaskProcessor: object}} cesium The
* Cesium namespace.
* @param {() => void} cb
* @returns {() => void} Removes the listeners.
*/
export function onEngineWorkCompleted({ RequestScheduler, TaskProcessor }, cb) {
const offs = [
RequestScheduler.requestCompletedEvent.addEventListener(() => cb()),
TaskProcessor.taskCompletedEvent.addEventListener(() => cb()),
];
return () => offs.forEach((off) => off());
}
/**
* Runs `fn` at the end of the scene's current tick, drawn or not: Cesium's
* after-render queue, which every `Scene.render` empties after its draw (if
* any) and before `postRender`. `fn` must return nothing; a truthy return
* asks for another frame.
* @param {object} scene Cesium Scene.
* @param {() => void} fn
*/
export function atEndOfTick(scene, fn) {
// A scene without Cesium's frame state (a stand-in) has no tick to end.
scene._frameState?.afterRender?.push(fn);
}
/**
* The scene time of the last drawn frame, for `maximumRenderTimeChange`.
* @param {object} scene Cesium Scene.
* @returns {object|undefined} Cesium JulianDate.
*/
export function lastRenderTime(scene) {
return scene._lastRenderTime;
}
/**
* The camera as the scene last saw it move, which `Scene.render` compares
* the camera with to decide whether it moved.
* @param {object} scene Cesium Scene.
* @returns {object|undefined} Cesium Camera.
*/
export function lastSeenCamera(scene) {
return scene._view?._cameraClone;
}
/**
* 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;
}
/**
* The entity Cesium's EntityView tracks: set once tracking has started and
* framed its entity, which can be frames after `trackedEntity` is set.
* @param {object} widget Viewer or CesiumWidget.
* @returns {object|null} Entity.
*/
export function trackedEntityViewEntity(widget) {
return (widget?._cesiumWidget ?? widget)?._entityView?.entity ?? null;
}
/**
* 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;
}
/**
* Run the camera's `changed` check, as a scene does once a frame. For a
* camera driven without a scene (the reference camera traces).
* @param {object} camera Cesium Camera.
*/
export function updateCameraChanged(camera) {
camera._updateCameraChanged();
}
/**
* The error a billboard's image failed to load with, if it did: Cesium
* keeps `ready` false then, so `whenSettled` reports the failure instead of
* waiting out its timeout.
* @param {object} billboard Cesium Billboard.
* @returns {Error|undefined}
*/
export function billboardLoadError(billboard) {
return billboard.loadError;
}
/**
* Frees the globe tiles the frame just drawn did not use. Cesium trims its
* tile cache only while tiles are loading, so a settled view never would;
* the renderer's `releaseUnused` trims it after a drawn frame, while the
* queue still marks what that frame drew.
* @param {object} globe Cesium Globe.
*/
export function trimGlobeTiles(globe) {
globe?._surface?._tileReplacementQueue?.trimTiles(0);
}
const NO_CREDITS = Object.freeze([]);
/**
* What a credit display shows, for the credits port to report: its static
* credits, the credit elements of the frame under way or last drawn (each
* `{credit, count}`, a static one counted `Number.MAX_VALUE`) and the logo
* credit it shows first. Cesium's public API only adds and removes static
* credits; the per-frame ones (imagery, terrain and tile credits) are seen
* nowhere else.
* @param {object} display Cesium CreditDisplay.
* @returns {{statics: object[], screen: object[], lightbox: object[],
* logo: object|undefined}}
*/
export function creditDisplayContents(display) {
const frame = display?._currentFrameCredits;
return {
statics: display?._staticCredits ?? NO_CREDITS,
screen: frame?.screenCredits?.values ?? NO_CREDITS,
lightbox: frame?.lightboxCredits?.values ?? NO_CREDITS,
logo: display?._currentCesiumCredit,
};
}