Files
gods-eye-view/src/render/cesium/imagery.js
T
Sameh Khamis 8ff9a1fa29 Base map through the globe port
Cesium switches the map stacks through its globe port, as any renderer
does, rather than through a map engine of its own. Every route keeps its
behaviour:

- Google 3D turned off is kept hidden, and shown again without loading it
  anew; the key route's tiles take clamped marks, as the token routes' do.
- Esri goes to its deepest level (23); its "Map data not yet available"
  picture is a missing tile, so the parent's imagery stays.
- Cesium ion's world imagery is Bing over HTTPS on any page, with ion's
  credits; a token ion refuses refuses the switch, as before.
- Keyless terrain that does not answer is the flat ellipsoid, tried again
  behind it; world terrain asks ion first, as before.
- window.__godsEyeView.tileset is the Cesium photoreal tileset.
2026-11-16 17:06:35 -08:00

895 lines
30 KiB
JavaScript
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
/**
* @module render/cesium/imagery
* @description The Cesium globe port's imagery layers: a contract
* `ImagerySpec` as a Cesium imagery provider, its tile hooks, and the layer
* handles `globe.imagery` hands out (`src/render/contract/globe.d.ts`).
*
* Each handle owns one Cesium `ImageryLayer` and moves it to where its
* `drapeOn` says it drapes: the globe's imagery collection, or the drawn
* base tileset's own (`imageryOnTiles`). `all` drapes on the globe while it
* is shown, else on the base tileset. Port layers keep their order among
* themselves in every collection; layers others added to a collection stay
* where they are.
*
* With `imageryFrames`, a handle given a timed source (`setFrames`) hides
* its own layer and draws the frames its clock shows instead, each a Cesium
* layer of its own just above it: the nearest frame (in `blend` mode the
* later frame over the earlier one, at its share of the way), and the next
* `prefetch` frames loading unseen at alpha 0. A frame is ready
* (`frameReady`) once the globe's tiles drawn are drawn from its own
* imagery (`imageryFrames.js`).
*/
import * as Cesium from 'cesium';
import { vectorBaseProvider } from './vectorBase.js';
import { creditMarkup } from './credits.js';
import { listenerList } from './common.js';
import {
createTileVideos,
framesOf,
heldFrames,
layerDrawn,
shownAt,
videoProvider,
} from './imageryFrames.js';
import { withTileRequestHook } from './tileRequests.js';
import { createIonImagery } from './mapImagery.js';
const SPLITS = { none: 'NONE', left: 'LEFT', right: 'RIGHT' };
const DRAPES = new Set(['surface', 'objects', 'all']);
/** Delay before the one frame that asks again for deferred tiles. */
export const TILE_RETRY_DELAY_MS = 250;
/** Ion's world imagery assets, by contract style. */
const WORLD_ASSETS = { aerial: 2, aerialLabels: 3 };
/** A tile the source says is not there: Cesium draws the parent's. */
class MissingTile extends Error {
constructor() {
super('No tile here');
this.name = 'MissingTile';
}
}
const rectangleOf = (rect) =>
rect &&
Cesium.Rectangle.fromDegrees(rect.west, rect.south, rect.east, rect.north);
const tilingOf = (name) =>
name === 'geographic'
? new Cesium.GeographicTilingScheme()
: new Cesium.WebMercatorTilingScheme();
/** A contract credit as Cesium's, or undefined. */
export const cesiumCredit = (credit) =>
credit
? new Cesium.Credit(creditMarkup(credit), credit.inline === true)
: undefined;
/** The URL, as a resource retrying the statuses the spec names. */
function resourceOf(spec) {
if (!spec.retryStatuses?.length) return spec.url;
const statuses = new Set(spec.retryStatuses);
return new Cesium.Resource({
url: spec.url,
retryAttempts: 3,
retryCallback: (_resource, error) => statuses.has(error?.statusCode),
});
}
/**
* A provider that draws each tile on a canvas (`canvas` imagery), with the
* members Cesium's imagery layer reads.
*/
function canvasProvider(spec) {
const tilingScheme = tilingOf(spec.tiling ?? 'geographic');
const size = spec.tileSize ?? 256;
const errorEvent = new Cesium.Event();
return {
tilingScheme,
tileWidth: size,
tileHeight: size,
minimumLevel: spec.minLevel ?? 0,
maximumLevel: spec.maxLevel,
rectangle: rectangleOf(spec.rectangle) ?? tilingScheme.rectangle,
credit: cesiumCredit(spec.credit),
errorEvent,
hasAlphaChannel: true,
tileDiscardPolicy: undefined,
proxy: undefined,
getTileCredits: () => undefined,
pickFeatures: () => undefined,
requestImage(x, y, level) {
const canvas = document.createElement('canvas');
canvas.width = size;
canvas.height = size;
return guarded(() => {
spec.drawTile({ x, y, level }, canvas);
return Promise.resolve(canvas);
});
},
};
}
/**
* The Cesium layer options a spec asks for: one hidden below its minimum
* level is shown only from the globe level as fine as it (Cesium's globe
* tiles are geographic, two Web Mercator tiles across a level's one).
* @param {import('../contract/globe').ImagerySpec} spec
* @returns {object|undefined}
*/
export function layerOptions(spec) {
if (!spec.hiddenBelowMinLevel || !(spec.minLevel > 0)) return undefined;
const tiling =
spec.tiling ?? (spec.kind === 'canvas' ? 'geographic' : 'webMercator');
const shift = tiling === 'geographic' ? 0 : 1;
return { minimumTerrainLevel: Math.max(0, spec.minLevel - shift) };
}
/**
* The Cesium provider a spec describes; a promise for the kinds Cesium
* builds from metadata it fetches first.
* @param {import('../contract/globe').ImagerySpec} spec
* @param {{worldDataToken?: string}} options
*/
export function providerFor(spec, { worldDataToken } = {}) {
const common = {
rectangle: rectangleOf(spec.rectangle),
minimumLevel: spec.minLevel,
maximumLevel: spec.maxLevel,
credit: cesiumCredit(spec.credit),
...(spec.tileSize
? { tileWidth: spec.tileSize, tileHeight: spec.tileSize }
: {}),
};
for (const key of Object.keys(common))
if (common[key] === undefined) delete common[key];
switch (spec.kind) {
case 'xyz':
return new Cesium.UrlTemplateImageryProvider({
url: resourceOf(spec),
tilingScheme: tilingOf(spec.tiling),
...(spec.subdomains ? { subdomains: spec.subdomains } : {}),
...common,
});
case 'single-image':
return Cesium.SingleTileImageryProvider.fromUrl(resourceOf(spec), common);
case 'world': {
const accessToken = String(worldDataToken || '').trim();
if (!accessToken)
throw new TypeError(
'World imagery needs the renderer’s world data token',
);
// Bing through ion, its tiles over HTTPS on any page, with ion's
// credits, as the map stacks have always drawn it.
return createIonImagery(
WORLD_ASSETS[spec.worldStyle ?? 'aerial'] ?? WORLD_ASSETS.aerial,
accessToken,
);
}
// The app's own: the vector base's tiles, painted from its style.
case 'vectorStyle':
return vectorBaseProvider(spec.style);
case 'canvas':
if (typeof spec.drawTile !== 'function')
throw new TypeError('Canvas imagery needs drawTile');
return canvasProvider(spec);
default:
throw new TypeError(`Unknown imagery kind: ${spec.kind}`);
}
}
/**
* The URL a tile of an `xyz` spec is fetched from, as Cesium's URL template
* provider builds it, for `fetchTile`.
*/
export function xyzTileUrl(spec, tilingScheme, { x, y, level }) {
const subdomains = spec.subdomains?.length
? spec.subdomains
: ['a', 'b', 'c'];
const rows = tilingScheme.getNumberOfYTilesAtLevel(level);
return spec.url
.replaceAll('{x}', String(x))
.replaceAll('{y}', String(y))
.replaceAll('{z}', String(level))
.replaceAll('{reverseY}', String(rows - y - 1))
.replaceAll('{s}', subdomains[(x + y + level) % subdomains.length]);
}
/**
* Cesium draws an `ImageBitmap` tile as decoded, flipped as it decodes its
* own (`imageOrientation: 'flipY'`); any other image it flips as it uploads.
*/
const FLIPPED = { imageOrientation: 'flipY' };
const isBitmap = (image) =>
typeof ImageBitmap !== 'undefined' && image instanceof ImageBitmap;
/** A tile's bytes decoded as Cesium decodes its own. */
const decodeTile = (blob) =>
createImageBitmap(blob, {
...FLIPPED,
premultiplyAlpha: 'none',
colorSpaceConversion: 'default',
});
/**
* `tileTransform` on an upright tile; its result goes back to Cesium
* flipped, as Cesium's own bitmaps are.
*/
async function transformTile(spec, tile, image) {
// Straight alpha throughout, as Cesium uploads its own tiles: WebGL does
// not premultiply an ImageBitmap, so one premultiplied here stays so.
const straight = {
premultiplyAlpha: 'none',
colorSpaceConversion: 'default',
};
const upright = await createImageBitmap(
image,
isBitmap(image) ? { ...FLIPPED, ...straight } : straight,
);
// The input is the hook's until it settles; a bitmap it returns is the
// renderer's, spent once copied.
let result;
try {
result = await spec.tileTransform(tile, upright);
return await createImageBitmap(result, { ...FLIPPED, ...straight });
} finally {
if (isBitmap(result) && result !== upright) result.close();
upright.close();
}
}
/** A hook's synchronous throw as a failed tile, never a throw into the frame. */
function guarded(run) {
try {
return run();
} catch (error) {
return Promise.reject(error);
}
}
/**
* The provider with the spec's hooks and the port's accounting on its tile
* requests: `admit` decides first, an issued request goes through
* `fetchTile` (or the provider), then `tileTransform`; at most
* `maxConcurrentRequests` are in flight.
*
* A tile `admit` defers is asked again on a later frame: the one a request
* of a layer with the same `admit` in flight asks for as it settles, or,
* with none in flight (`busy`), the one `retrySoon` asks for. So layers
* whose shared budget is full never keep the scene drawing while they
* wait.
* @param {object} provider
* @param {import('../contract/globe').ImagerySpec} spec
* @param {{started: () => void, settled: () => void, retrySoon: () => void,
* laterFrame: () => Promise<void>, signals: Set<AbortController>,
* busy?: () => boolean, requests?: Set<object>}} ctx
* `requests`: the Cesium requests in flight, cancelled as the layer goes.
*/
export function hookProvider(provider, spec, ctx) {
const limit =
spec.maxConcurrentRequests > 0 ? spec.maxConcurrentRequests : Infinity;
let inFlight = 0;
async function fetchVia(tile) {
const url = xyzTileUrl(spec, provider.tilingScheme, tile);
const controller = new AbortController();
ctx.signals.add(controller);
try {
for (;;) {
const answer = await spec.fetchTile({
tile,
url,
signal: controller.signal,
});
controller.signal.throwIfAborted();
if (answer?.defer) {
// Its budget slot is free while it waits, so a deferred tile
// never holds up the others.
inFlight -= 1;
try {
await ctx.laterFrame();
// Back in when the budget has room again.
while (inFlight >= limit) {
controller.signal.throwIfAborted();
await ctx.laterFrame();
}
} finally {
inFlight += 1;
}
controller.signal.throwIfAborted();
continue;
}
if (!answer || answer.missing) throw new MissingTile();
const blob = new Blob(
[answer.bytes],
answer.contentType ? { type: answer.contentType } : undefined,
);
return await decodeTile(blob);
}
} finally {
ctx.signals.delete(controller);
}
}
return withTileRequestHook(provider, {
requestImage({ x, y, level, request }, ask) {
const tile = { x, y, level };
// Deferred by the budget: the request in flight asks for a frame as
// it settles, so none is asked for here.
let waitsOnBudget = false;
const issue = () => {
if (inFlight >= limit) {
waitsOnBudget = true;
return undefined;
}
waitsOnBudget = false;
const started = spec.fetchTile ? fetchVia(tile) : guarded(ask);
if (!started) {
// Cesium's own request limits deferred it: one later frame asks
// again.
ctx.retrySoon();
return undefined;
}
inFlight += 1;
ctx.started();
if (request) ctx.requests?.add(request);
let result = Promise.resolve(started);
if (spec.tileTransform)
result = result.then((image) => transformTile(spec, tile, image));
return result.finally(() => {
inFlight -= 1;
if (request) ctx.requests?.delete(request);
ctx.settled();
});
};
if (!spec.admit) return issue();
const answer = guarded(() => spec.admit(tile, issue));
if (answer === undefined && !waitsOnBudget && !ctx.busy?.())
ctx.retrySoon();
return answer;
},
});
}
/**
* The imagery layers of one globe port.
* @param {object} scene Cesium Scene.
* @param {{capabilities: ReadonlySet<string>, requestRender: (reason: string) => void,
* report: (error: unknown) => void, objects: () => object|null,
* worldDataToken?: () => string|undefined}} options
* `objects`: the drawn base tileset imagery drapes onto, or null.
*/
export function createCesiumImagery(
scene,
{
capabilities,
requestRender,
report,
objects,
worldDataToken = () => undefined,
},
) {
/** Port layers, bottom to top. */
const layers = [];
let pending = 0;
/** Tiles in flight by the `admit` their layers share. */
const admitPending = new Map();
let retryTimer = null;
let disposed = false;
const waiters = [];
const retrySoon = () => {
if (retryTimer !== null || disposed) return;
retryTimer = setTimeout(() => {
retryTimer = null;
for (const resolve of waiters.splice(0)) resolve();
if (!disposed) requestRender('imagery');
}, TILE_RETRY_DELAY_MS);
};
const laterFrame = () =>
new Promise((resolve) => {
if (disposed) {
setTimeout(resolve, TILE_RETRY_DELAY_MS);
return;
}
waiters.push(resolve);
retrySoon();
});
const globeCollection = () =>
scene.imageryLayers ?? scene.globe?.imageryLayers;
const usable = (collection) => collection && !collection.isDestroyed?.();
/** The collection a layer should be in now. */
function hostFor(record) {
const tiles = capabilities.has('imageryOnTiles') ? objects() : null;
const tileCollection =
tiles && !tiles.isDestroyed?.() ? tiles.imageryLayers : null;
if (record.drapeOn === 'surface') return globeCollection();
if (record.drapeOn === 'objects') return tileCollection;
if (scene.globe?.show !== true && usable(tileCollection))
return tileCollection;
return globeCollection();
}
/** Where to put a layer in a collection, keeping port order. */
function placeIndex(record, collection) {
const at = layers.indexOf(record);
// A layer taken out of the collection by someone else is passed over.
for (let i = at + 1; i < layers.length; i++) {
const found =
layers[i].host === collection
? collection.indexOf(layers[i].cesium)
: -1;
if (found >= 0) return found;
}
for (let i = at - 1; i >= 0; i--) {
const found =
layers[i].host === collection
? collection.indexOf(layers[i].cesium)
: -1;
if (found >= 0) return found + 1;
}
return record.base ? 0 : collection.length;
}
/** Moves a layer within its collection to its place among port layers. */
function reorder(record) {
const collection = record.host;
if (!usable(collection) || !collection.contains(record.cesium)) return;
const at = layers.indexOf(record);
const inHere = (r) =>
r.host === collection && collection.contains(r.cesium);
const above = layers.slice(at + 1).find(inHere);
const below = layers.slice(0, at).reverse().find(inHere);
let guard = collection.length;
while (
above &&
collection.indexOf(record.cesium) > collection.indexOf(above.cesium) &&
guard-- > 0
)
collection.lower(record.cesium);
guard = collection.length;
while (
below &&
collection.indexOf(record.cesium) < collection.indexOf(below.cesium) &&
guard-- > 0
)
collection.raise(record.cesium);
}
/** A Cesium layer for the record, with its look. */
function build(record) {
const options = layerOptions(record.spec);
const layer =
record.provider !== undefined
? new Cesium.ImageryLayer(record.provider, options)
: Cesium.ImageryLayer.fromProviderAsync(
record.providerPromise,
options,
);
layer.alpha = record.alpha;
// A layer showing timed frames hides its own imagery.
layer.show = record.show && !record.timed;
layer.splitDirection = Cesium.SplitDirection[SPLITS[record.split]];
return layer;
}
/** Puts each layer where it drapes now; rebuilds one a tileset destroyed. */
function sync() {
if (disposed) return;
let changed = false;
for (const record of layers) {
if (record.removed) continue;
if (record.cesium.isDestroyed()) {
record.cesium = build(record);
record.host = null;
}
// Taken out by someone else: put back where it drapes.
if (usable(record.host) && !record.host.contains(record.cesium))
record.host = null;
const next = hostFor(record);
const target = usable(next) ? next : null;
if (record.host === target) continue;
if (usable(record.host) && record.host.contains(record.cesium))
record.host.remove(record.cesium, false);
record.host = null;
if (target) {
target.add(record.cesium, placeIndex(record, target));
record.host = target;
}
changed = true;
}
if (changed) requestRender('imagery');
}
function add(spec, index, { base = false } = {}) {
if (disposed) throw new Error('This globe has been disposed');
if (
!capabilities.has('imageHooks') &&
(spec.tileTransform || spec.admit || spec.kind === 'canvas')
)
throw new TypeError(
'tileTransform, admit and canvas imagery need imageHooks',
);
if (spec.fetchTile && spec.kind !== 'xyz')
throw new TypeError('fetchTile is supported for xyz imagery only');
const listeners = {
tileError: listenerList(report),
frameReady: listenerList(report),
};
const signals = new Set();
const requests = new Set();
// Layers given one `admit` share its waits: a tile it defers is asked
// again on the frame any of their tiles asks for as it settles.
const shared = spec.admit ?? {};
const ctx = {
busy: () => (admitPending.get(shared) ?? 0) > 0,
requests,
started: () => {
pending += 1;
admitPending.set(shared, (admitPending.get(shared) ?? 0) + 1);
},
settled: () => {
pending -= 1;
const left = (admitPending.get(shared) ?? 1) - 1;
if (left > 0) admitPending.set(shared, left);
else admitPending.delete(shared);
if (!disposed) requestRender('imagery');
},
retrySoon,
laterFrame,
signals,
};
const record = {
spec: { ...spec },
base,
alpha: 1,
show: true,
split: 'none',
drapeOn: 'all',
lit: true,
host: null,
removed: false,
provider: undefined,
providerPromise: undefined,
cesium: null,
signals,
offError: null,
};
const watchErrors = (provider) =>
provider.errorEvent?.addEventListener?.((error) => {
if (error?.error instanceof MissingTile) return;
if (listeners.tileError.size === 0) return;
const status = error?.error?.statusCode;
listeners.tileError.fire({
tile: { x: error?.x, y: error?.y, level: error?.level },
...(Number.isFinite(status) ? { status } : {}),
});
});
record.listeners = listeners;
record.ctx = ctx;
record.watchErrors = watchErrors;
const made = providerFor(spec, { worldDataToken: worldDataToken() });
if (typeof made?.then === 'function') {
record.providerPromise = Promise.resolve(made).then((provider) => {
const hooked = hookProvider(provider, spec, ctx);
if (!record.removed) record.offError = watchErrors(provider);
record.provider = hooked;
return hooked;
});
// A provider that fails to build (its metadata, or a single image)
// loads no tile: told as an error of the layer's root tile.
record.providerPromise.catch((error) => {
if (record.removed || listeners.tileError.size === 0) return;
const status = error?.statusCode;
listeners.tileError.fire({
tile: { x: 0, y: 0, level: 0 },
...(Number.isFinite(status) ? { status } : {}),
});
});
} else {
record.provider = hookProvider(made, spec, ctx);
record.offError = watchErrors(made);
}
record.cesium = build(record);
const handle = {
get alpha() {
return record.alpha;
},
set alpha(value) {
record.alpha = Number(value);
record.cesium.alpha = record.alpha;
requestRender('imagery');
},
get show() {
return record.show;
},
set show(value) {
record.show = Boolean(value);
record.cesium.show = record.show && !record.timed;
requestRender('imagery');
},
get split() {
return record.split;
},
set split(value) {
if (!(value in SPLITS)) throw new TypeError(`Unknown split: ${value}`);
record.split = value;
record.cesium.splitDirection = Cesium.SplitDirection[SPLITS[value]];
requestRender('imagery');
},
get drapeOn() {
return record.drapeOn;
},
set drapeOn(value) {
if (!DRAPES.has(value)) throw new TypeError(`Unknown drape: ${value}`);
record.drapeOn = value;
sync();
},
get lit() {
return record.lit;
},
// Cesium lights imagery with its surface; an unlit layer is recorded
// and drawn as the surface draws it.
set lit(value) {
record.lit = Boolean(value);
},
on(event, cb) {
return listeners[event]?.on(cb) ?? (() => {});
},
raise() {
const i = layers.indexOf(record);
if (i < 0 || i === layers.length - 1) return;
layers.splice(i, 1);
layers.splice(i + 1, 0, record);
reorder(record);
requestRender('imagery');
},
lower() {
const i = layers.indexOf(record);
if (i <= 0) return;
layers.splice(i, 1);
layers.splice(i - 1, 0, record);
reorder(record);
requestRender('imagery');
},
remove() {
if (record.removed) return;
record.removed = true;
const i = layers.indexOf(record);
if (i >= 0) layers.splice(i, 1);
record.offError?.();
dropFrames(record);
for (const controller of signals) controller.abort();
// Cesium leaves a removed layer's requests running: cancelled, they
// are aborted and free their per-server slots on the next frame.
for (const request of requests) request.cancel?.();
requests.clear();
listeners.tileError.clear();
listeners.frameReady.clear();
if (usable(record.host) && record.host.contains(record.cesium))
record.host.remove(record.cesium, true);
else if (!record.cesium.isDestroyed()) record.cesium.destroy();
record.host = null;
requestRender('imagery');
},
};
if (capabilities.has('imageryFrames')) {
handle.setFrames = (source, options = {}) => {
const frames = framesOf(source);
if (record.removed) return;
dropFrames(record);
record.timed = {
video: source.kind === 'video',
frames,
mode: options.mode === 'blend' ? 'blend' : 'nearest',
prefetch: Math.max(0, Math.floor(options.prefetch ?? 1)),
clock: options.clock === 'own' ? 'own' : 'scene',
own: null,
at: null,
announced: null,
layers: new Map(),
videos: source.kind === 'video' ? createTileVideos() : null,
};
record.cesium.show = false;
requestRender('imagery');
};
handle.setFrameTime = (ms) => {
// On the scene clock the frame port's time decides.
if (record.timed?.clock !== 'own') return;
record.timed.own = Number(ms);
requestRender('imagery');
};
}
record.handle = handle;
let at = index;
if (at === undefined) {
// Above every layer of the same or a lower zOrder; none is 0.
const z = Number.isFinite(spec.zOrder) ? spec.zOrder : 0;
at = layers.length;
while (at > 0 && (layers[at - 1].spec.zOrder ?? 0) > z) at -= 1;
}
if (at === undefined || at > layers.length) at = layers.length;
layers.splice(Math.max(0, at), 0, record);
sync();
requestRender('imagery');
return handle;
}
// --- Timed frames (`imageryFrames`) ---------------------------------------
/** A Cesium layer drawing one frame of a record's timed source. */
function frameLayer(record, frame) {
const timed = record.timed;
const spec = { ...record.spec, url: frame.url };
const entry = { layer: null, host: null, offError: null };
let made;
try {
made = timed.video
? videoProvider(record.spec, frame, timed.videos)
: providerFor(spec, { worldDataToken: worldDataToken() });
} catch (error) {
report(error);
made = Promise.reject(error);
}
if (typeof made?.then === 'function') {
const provider = Promise.resolve(made).then((provider) => {
if (!entry.removed) entry.offError = record.watchErrors(provider);
return hookProvider(provider, spec, record.ctx);
});
provider.catch(() => {});
entry.layer = Cesium.ImageryLayer.fromProviderAsync(
provider,
layerOptions(spec),
);
} else {
entry.offError = record.watchErrors(made);
entry.layer = new Cesium.ImageryLayer(
timed.video ? made : hookProvider(made, spec, record.ctx),
layerOptions(spec),
);
}
entry.layer.alpha = 0;
return entry;
}
function dropFrameLayer(entry) {
entry.removed = true;
entry.offError?.();
if (usable(entry.host) && entry.host.contains(entry.layer))
entry.host.remove(entry.layer, true);
else if (!entry.layer.isDestroyed()) entry.layer.destroy();
entry.host = null;
}
/** Let go of a record's timed source and its frames' layers. */
function dropFrames(record) {
const timed = record.timed;
if (!timed) return;
for (const entry of timed.layers.values()) dropFrameLayer(entry);
timed.layers.clear();
timed.videos?.clear();
record.timed = null;
if (!record.cesium.isDestroyed()) record.cesium.show = record.show;
}
/**
* Before each frame: the frames each timed layer's clock shows now, and
* those it prefetches, as layers just above its own, in time order.
*/
function stepFrames(time) {
if (disposed) return;
const sceneMs = time ? Cesium.JulianDate.toDate(time).getTime() : NaN;
for (const record of layers) {
const timed = record.timed;
if (!timed || record.removed) continue;
const ms = timed.clock === 'own' ? (timed.own ?? NaN) : sceneMs;
const at = shownAt(timed.frames, ms, timed.mode);
timed.at = at;
const held = at ? heldFrames(timed.frames, at, timed.prefetch) : [];
for (const [index, entry] of timed.layers)
if (!held.includes(index) || entry.layer.isDestroyed()) {
dropFrameLayer(entry);
timed.layers.delete(index);
}
const host =
usable(record.host) && record.host.contains(record.cesium)
? record.host
: null;
const weights = new Map(at?.shown.map((s) => [s.index, s.weight]));
let place = host ? host.indexOf(record.cesium) + 1 : -1;
for (const index of held.sort((a, b) => a - b)) {
let entry = timed.layers.get(index);
if (!entry) {
entry = frameLayer(record, timed.frames[index]);
timed.layers.set(index, entry);
}
const layer = entry.layer;
const weight = weights.get(index);
// Prefetched frames load unseen: shown, at alpha 0.
layer.show = record.show;
layer.alpha = weight === undefined ? 0 : record.alpha * weight;
layer.splitDirection = Cesium.SplitDirection[SPLITS[record.split]];
if (entry.host !== host) {
if (usable(entry.host) && entry.host.contains(layer))
entry.host.remove(layer, false);
entry.host = null;
if (host) {
host.add(layer, Math.min(place, host.length));
entry.host = host;
}
} else if (host && host.indexOf(layer) !== place) {
host.remove(layer, false);
host.add(layer, Math.min(place, host.length));
}
if (host) place = host.indexOf(layer) + 1;
}
}
}
/** Whether a frame's layer is drawn where it drapes. */
function frameDrawn(entry) {
if (!entry?.host || !entry.layer.ready) return false;
if (entry.host === globeCollection()) return layerDrawn(scene, entry.layer);
return objects()?.tilesLoaded === true;
}
/** After each frame: each timed layer's shown frame, once it is drawn. */
function announceFrames() {
if (disposed) return;
// Most frames have no timed layer: the copy below is made only for one.
let timedLayers = false;
for (const record of layers) if (record.timed?.at) timedLayers = true;
if (!timedLayers) return;
for (const record of layers.slice()) {
const timed = record.timed;
// A layer removed by another's listener says nothing.
if (record.removed || !timed?.at || !record.show) continue;
const time = timed.frames[timed.at.nearest].time;
if (time === timed.announced) continue;
if (!timed.at.shown.every((s) => frameDrawn(timed.layers.get(s.index))))
continue;
timed.announced = time;
record.listeners.frameReady.fire(time);
}
}
const frameOffs = capabilities.has('imageryFrames')
? [
scene.preRender?.addEventListener?.((_, time) => stepFrames(time)),
scene.postRender?.addEventListener?.(() => announceFrames()),
]
: [];
return {
add,
list: () => layers.map((record) => record.handle),
/** How many layers the port holds, without listing them. */
get size() {
return layers.length;
},
/** Layers whose providers are still being built, as promises. */
ready: (handles) =>
Promise.allSettled(
layers
.filter((r) => handles.includes(r.handle) && r.providerPromise)
.map((r) => r.providerPromise),
),
sync,
/** Whether any port layer has a tile request in flight. */
pending: () => pending,
/**
* Stop asking for frames. Layers stay drawn where they are and their
* handles keep working; a deferred fetch asks again on a timer.
*/
dispose() {
disposed = true;
for (const off of frameOffs.splice(0)) off?.();
clearTimeout(retryTimer);
retryTimer = null;
for (const resolve of waiters.splice(0)) resolve();
},
};
}