From 456645f2912e1ee6763b324d2e8a40fbdbbeeccc Mon Sep 17 00:00:00 2001 From: Sameh Khamis Date: Sun, 8 Nov 2026 13:31:03 -0800 Subject: [PATCH] Name the surface heights answer against: globe.surfaceVersion and the surface settle kind A new capability, surfaceIdentity, adds globe.surfaceVersion(): a number that changes whenever what surface heights answer against changes (base, terrain or photoreal swapped, the globe shown or hidden) and never on camera moves or tile loads, so the app can key cached heights by it. The settle kind 'surface' says whether that surface has loaded what is in view: the terrain while the globe is shown, otherwise the drawn tiles, false with neither; a renderer without the capability answers it as base. The Cesium globe port reads both off the scene, so a base changed around the port counts too; its versions come from one counter shared by every port. The stub bumps on real base, terrain, photoreal and visibility changes. A conformance check and a globe port test cover them. --- docs/RENDERER-CONTRACT.md | 6 +++ src/render/cesium/globe.js | 60 +++++++++++++++++++++++++- src/render/cesium/globe.test.mjs | 27 ++++++++++++ src/render/cesium/harness.js | 1 + src/render/cesium/ports.js | 1 + src/render/cesium/ports.test.mjs | 1 + src/render/conformance/checks/ports.js | 33 ++++++++++++++ src/render/contract/common.d.ts | 2 + src/render/contract/globe.d.ts | 15 ++++++- src/render/contract/index.js | 2 + src/render/stub/index.js | 20 ++++++++- 11 files changed, 165 insertions(+), 3 deletions(-) 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]);