diff --git a/docs/RENDERER-CONTRACT.md b/docs/RENDERER-CONTRACT.md index 3655a7985..e9c426229 100644 --- a/docs/RENDERER-CONTRACT.md +++ b/docs/RENDERER-CONTRACT.md @@ -42,6 +42,12 @@ optional, so a renderer written before it still conforms: target's east-north-up frame, or the identity. `setView` keeps that frame while it places a world pose. A share link's follow offset is re-expressed in it, satellites included. +- `globe.surfaceVersion()` (capability `surfaceIdentity`) is a number that + changes whenever what surface heights answer against changes (base, + terrain or photoreal route swapped, the globe shown or hidden) and never + otherwise (not on camera moves or tile loads), so the application can key cached + heights by it. `isSettled('surface')` says whether that surface has + loaded what is in view; a renderer without it answers `surface` as `base`. - `camera.on('changed', cb, { threshold })` measures each listener by its own threshold under the capability `cameraChangeThreshold`; a renderer without it fires every `changed` listener at 0.5. diff --git a/src/render/cesium/globe.js b/src/render/cesium/globe.js index 1ddb4c806..12f7cf31b 100644 --- a/src/render/cesium/globe.js +++ b/src/render/cesium/globe.js @@ -114,6 +114,9 @@ async function terrainProvider(spec, { worldDataToken }) { throw new TypeError(`Unknown terrain kind: ${spec.kind}`); } +/** The last `surfaceVersion` any globe port handed out. */ +let surfaceVersions = 0; + /** * @param {object} widget A Cesium `CesiumWidget` or `Viewer`. * @param {{capabilities: ReadonlySet, @@ -370,7 +373,56 @@ export function createCesiumGlobe( }; const imageryLoaded = () => imagery.pending() === 0 && terrainLoaded(); + /** + * `surface`: what surface heights answer from has loaded what is in view: + * the globe's terrain while it is shown, otherwise the shown 3D tiles; + * false with neither drawn. + */ + function surfaceLoaded() { + if (scene.globe?.show) return scene.globe.tilesLoaded !== false; + let found = false; + for (const tileset of tilesets()) { + if (!tileset.show || tileset.isDestroyed?.()) continue; + found = true; + if (tileset.tilesLoaded === false) return false; + } + return found; + } + + // `surfaceVersion`: bumped when what heights answer against changes, read + // off the scene (so a base changed around the port counts too): whether + // the globe is shown, its terrain provider, and the shown 3D tilesets. + // Taken from one counter for every port, so no two surfaces share one. + let surfaceVersion = 0; + const surfaceSeen = { globe: null, terrain: null, tiles: new Set() }; + function readSurfaceVersion() { + const globe = Boolean(scene.globe?.show); + const terrain = scene.globe?.terrainProvider ?? null; + let changed = + surfaceSeen.globe !== globe || surfaceSeen.terrain !== terrain; + // The shown tilesets as a set: their order among the primitives is no + // change to the surface. + let count = 0; + for (const tileset of tilesets()) { + if (!tileset.show || tileset.isDestroyed?.()) continue; + count += 1; + if (!surfaceSeen.tiles.has(tileset)) changed = true; + } + if (count !== surfaceSeen.tiles.size) changed = true; + if (changed) { + surfaceSeen.globe = globe; + surfaceSeen.terrain = terrain; + surfaceSeen.tiles.clear(); + for (const tileset of tilesets()) + if (tileset.show && !tileset.isDestroyed?.()) + surfaceSeen.tiles.add(tileset); + surfaceVersion = ++surfaceVersions; + } + return surfaceVersion; + } + function isSettled(kind) { + if (kind === 'surface' && can('surfaceIdentity')) return surfaceLoaded(); if (kind === 'terrain') return terrainLoaded(); if (kind === 'tiles') return tilesLoaded(); if (kind === 'imagery') return imageryLoaded(); @@ -440,6 +492,7 @@ export function createCesiumGlobe( }; if (can('globeVisibility')) port.isGlobeVisible = () => scene.globe?.show === true; + if (can('surfaceIdentity')) port.surfaceVersion = readSurfaceVersion; if (can('splitSwipe')) { // Cesium's split starts at the canvas's left edge, as the scene was // made: a `left` layer shows once the split moves. @@ -473,7 +526,12 @@ provideUnboundGlobe((viewer) => { if (!viewer?.scene) return null; // Visibility reads back only from a globe that keeps it: a scene made // without one gives no reading, so its callers keep their own default. - const capabilities = new Set(['imageHooks', 'imageryOnTiles', 'splitSwipe']); + const capabilities = new Set([ + 'imageHooks', + 'imageryOnTiles', + 'splitSwipe', + 'surfaceIdentity', + ]); if (typeof viewer.scene.globe?.show === 'boolean') capabilities.add('globeVisibility'); const { port, dispose } = createCesiumGlobe(viewer, { diff --git a/src/render/cesium/globe.test.mjs b/src/render/cesium/globe.test.mjs index 4e24bd5d2..c4c67fc70 100644 --- a/src/render/cesium/globe.test.mjs +++ b/src/render/cesium/globe.test.mjs @@ -602,3 +602,30 @@ test('a provider that fails to build is told as an error of its root tile', asyn assert.deepEqual(errors, [{ tile: { x: 0, y: 0, level: 0 } }]); layer.remove(); }); + +test('surfaceVersion follows what heights answer against; surface settles on it', () => { + const { scene, port } = setup(new Set([...ALL, 'surfaceIdentity'])); + const first = port.surfaceVersion(); + assert.equal(port.surfaceVersion(), first, 'steady while nothing changes'); + assert.equal(port.isSettled('surface'), true, 'the globe has loaded'); + scene.globe.tilesLoaded = false; + assert.equal(port.isSettled('surface'), false, 'the globe still loading'); + assert.equal(port.surfaceVersion(), first, 'tile loads are not a change'); + scene.globe.show = false; + const hidden = port.surfaceVersion(); + assert.notEqual(hidden, first, 'the globe hidden'); + assert.equal(port.isSettled('surface'), false, 'no globe and no tiles'); + const tileset = fakeTileset(); + scene.primitives.add(tileset); + const tiled = port.surfaceVersion(); + assert.notEqual(tiled, hidden, 'tiles shown'); + assert.equal(port.isSettled('surface'), true, 'the tiles have loaded'); + scene.globe.show = true; + scene.globe.terrainProvider = {}; + assert.notEqual(port.surfaceVersion(), tiled, 'new terrain under the globe'); + // Without the capability there is no version and surface answers as base. + const plain = setup(); + assert.equal(plain.port.surfaceVersion, undefined); + plain.scene.globe.show = false; + assert.equal(plain.port.isSettled('surface'), plain.port.isSettled('base')); +}); diff --git a/src/render/cesium/harness.js b/src/render/cesium/harness.js index 9df9da99c..9dde08480 100644 --- a/src/render/cesium/harness.js +++ b/src/render/cesium/harness.js @@ -76,6 +76,7 @@ export const CESIUM_CHECKS = new Set([ 'globe.imagery', 'globe.sky', 'globe.split', + 'globe.surfaceVersion', 'globe.visible', 'globe.withoutImageHooks', 'input.behaviours', diff --git a/src/render/cesium/ports.js b/src/render/cesium/ports.js index fee62ab4c..8c5da2761 100644 --- a/src/render/cesium/ports.js +++ b/src/render/cesium/ports.js @@ -44,6 +44,7 @@ const GLOBE_CAPABILITIES = [ 'imageryOnTiles', 'splitSwipe', 'imageHooks', + 'surfaceIdentity', 'globeVisibility', ]; diff --git a/src/render/cesium/ports.test.mjs b/src/render/cesium/ports.test.mjs index e42e43473..a56173d23 100644 --- a/src/render/cesium/ports.test.mjs +++ b/src/render/cesium/ports.test.mjs @@ -23,6 +23,7 @@ test('capabilities follow what the scene supports', () => { 'imageryOnTiles', 'splitSwipe', 'imageHooks', + 'surfaceIdentity', ]; const globe = { show: true }; const draw = ['models', 'quads', 'meshes']; diff --git a/src/render/conformance/checks/ports.js b/src/render/conformance/checks/ports.js index d4924612b..62b8c8eaf 100644 --- a/src/render/conformance/checks/ports.js +++ b/src/render/conformance/checks/ports.js @@ -3053,6 +3053,39 @@ export function portChecks() { }, { capability: 'globeVisibility' }, ), + check( + 'globe.surfaceVersion', + 'the surface version changes with what heights answer against, only', + async (h, r) => { + await overAustin(h, r); + await drawn(h, r); + const first = r.globe.surfaceVersion(); + equal(typeof first, 'number', 'a number'); + r.camera.setView({ + destination: { ...AUSTIN, height: 9000 }, + orientation: { heading: 1, pitch: -1, roll: 0 }, + }); + await drawn(h, r, 4); + equal( + r.globe.surfaceVersion(), + first, + 'steady across frames and moves', + ); + r.globe.setGlobeVisible(false); + await drawn(h, r); + const hidden = r.globe.surfaceVersion(); + ok(hidden !== first, 'the globe hidden changes it'); + equal( + r.globe.isSettled('surface'), + false, + 'with no globe and no tiles there is no surface to settle', + ); + r.globe.setGlobeVisible(true); + await drawn(h, r); + ok(r.globe.surfaceVersion() !== hidden, 'shown again changes it'); + }, + { capability: 'surfaceIdentity' }, + ), check( 'globe.sky', 'sky settings round-trip and keep unchanged keys', diff --git a/src/render/contract/common.d.ts b/src/render/contract/common.d.ts index 02ad50adf..68f9f96cb 100644 --- a/src/render/contract/common.d.ts +++ b/src/render/contract/common.d.ts @@ -160,6 +160,8 @@ export type Capability = | 'imageryFrames' /** Wind-relief and similar shading of the globe surface. */ | 'surfaceShading' + /** A version of what surface heights answer against (`globe.surfaceVersion`). */ + | 'surfaceIdentity' /** Volumetric clouds (`globe.setClouds`). */ | 'clouds' /** A water surface on the oceans (`globe.setWater`). */ diff --git a/src/render/contract/globe.d.ts b/src/render/contract/globe.d.ts index 4c5cd0000..31c10bdd0 100644 --- a/src/render/contract/globe.d.ts +++ b/src/render/contract/globe.d.ts @@ -248,7 +248,13 @@ export interface LoadProgress { terrainPending: number; } -export type SettleKind = 'base' | 'tiles' | 'terrain' | 'imagery'; +/** + * `surface`: what `against: 'surface'` heights answer from has loaded what + * is in view: the terrain while the globe is shown, otherwise the drawn + * tiles; false when neither is drawn. A renderer that predates it answers + * as `base`. + */ +export type SettleKind = 'base' | 'tiles' | 'terrain' | 'imagery' | 'surface'; export interface GlobePort { /** Switch the whole base at once; resolves when the new base has settled. */ @@ -265,6 +271,13 @@ export interface GlobePort { * drawn. */ isGlobeVisible?(): boolean; + /** + * `surfaceIdentity`: a number that changes whenever what heights answer + * against changes (base, terrain or photoreal route swapped, the globe + * shown or hidden) and never otherwise (not on camera moves or tile + * loads). The application keys cached surface heights by it. + */ + surfaceVersion?(): number; /** `surfaceShading`. */ setSurfaceShading?(shading: SurfaceShading | null): void; /** `clouds`: the renderer's volumetric clouds, or none. */ diff --git a/src/render/contract/index.js b/src/render/contract/index.js index da0eff940..5545ad805 100644 --- a/src/render/contract/index.js +++ b/src/render/contract/index.js @@ -23,6 +23,7 @@ export const CAPABILITIES = Object.freeze([ 'splitSwipe', 'imageryFrames', 'surfaceShading', + 'surfaceIdentity', 'clouds', 'water', 'imageHooks', @@ -151,6 +152,7 @@ export const PORTS = deepFreeze({ 'on', ), ['isGlobeVisible', 'globeVisibility'], + ['surfaceVersion', 'surfaceIdentity'], ['setSurfaceShading', 'surfaceShading'], ['setClouds', 'clouds'], ['setWater', 'water'], diff --git a/src/render/stub/index.js b/src/render/stub/index.js index 83b717016..8f058fd77 100644 --- a/src/render/stub/index.js +++ b/src/render/stub/index.js @@ -1142,6 +1142,9 @@ export function createStubRenderer(options = {}) { return layer; } + // `surfaceIdentity`: bumped by whatever changes what heights answer against. + let surfaceVersion = 0; + let terrainKey = 'null'; const globe = { async setBase(base) { log('globe', 'setBase', [base]); @@ -1153,19 +1156,26 @@ export function createStubRenderer(options = {}) { }, async setPhotoreal(spec) { log('globe', 'setPhotoreal', [spec]); + const route = photorealStatus.route; photorealStatus = spec && capabilities.has('photoreal') ? { route: 'google' } : { route: 'none' }; + if (photorealStatus.route !== route || spec) surfaceVersion += 1; requestRender('base'); return photorealStatus; }, async setTerrain(spec) { log('globe', 'setTerrain', [spec]); + // The stub keeps no terrain: a spec unlike the last is a new surface. + const key = JSON.stringify(spec ?? null); + if (key !== terrainKey) surfaceVersion += 1; + terrainKey = key; requestRender('base'); }, setGlobeVisible(visible) { log('globe', 'setGlobeVisible', [visible]); + if (globeVisible !== Boolean(visible)) surfaceVersion += 1; globeVisible = Boolean(visible); requestRender('base'); }, @@ -1180,7 +1190,13 @@ export function createStubRenderer(options = {}) { requestRender('sky'); }, }, - isSettled: (kind) => settled[kind] ?? true, + isSettled(kind) { + if (kind !== 'surface') return settled[kind] ?? true; + if (!capabilities.has('surfaceIdentity')) return settled.base; + // Heights answer from the globe, else the tiles; neither drawn, none. + if (!globeVisible && photorealStatus.route === 'none') return false; + return settled.surface ?? settled[globeVisible ? 'terrain' : 'tiles']; + }, on(event, cb) { if (event !== 'progress') return () => {}; progressListeners.push(cb); @@ -1192,6 +1208,8 @@ export function createStubRenderer(options = {}) { }; if (capabilities.has('globeVisibility')) globe.isGlobeVisible = () => globeVisible; + if (capabilities.has('surfaceIdentity')) + globe.surfaceVersion = () => surfaceVersion; if (capabilities.has('surfaceShading')) globe.setSurfaceShading = (shading) => { log('globe', 'setSurfaceShading', [shading]);