mirror of
https://github.com/bilawalsidhu/gods-eye-view.git
synced 2026-11-17 08:42:21 +00:00
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.
895 lines
30 KiB
JavaScript
895 lines
30 KiB
JavaScript
/**
|
||
* @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();
|
||
},
|
||
};
|
||
}
|