Add a globe visibility getter to the renderer contract

The globe port could show or hide the globe surface but not say whether it
is shown. It now has an optional isGlobeVisible(), gated by a new
globeVisibility capability, in the Cesium adapter, the stub and a
conformance check. A Cesium scene without a globe does not offer it, so
callers keep their own default for an unknown surface.

The OSM overlays, the CCTV ground regime and the submarine cable drape now
read the getter instead of the scene's globe. cableClassificationTypeForScene
takes the viewer rather than its scene.
This commit is contained in:
Sameh Khamis committed 2026-11-07 19:44:15 -08:00
1 parent 23d56f8393
commit 2e91579f8f
23 files changed
+140 -29

No files matched your search

+6
View File
@@ -31,6 +31,12 @@ exposes nine ports, each typed in its own file in `src/render/contract/`:
| `credits` | `credits.d.ts` | Data credits owed |
| `quality` | `quality.d.ts` | Quality knobs, device facts, frame signals, benchmark |
Some members and options were added to version `0` later. Each is
optional, so a renderer written before it still conforms:
- `globe.isGlobeVisible()` (capability `globeVisibility`) reads back whether
the globe surface is shown, for code that holds only the scene.
The renderer itself (`renderer.d.ts`) adds capture, pixel reads, settling,
resize, context loss and `destroy`. `common.d.ts` holds the shared shapes
(ECEF positions, colours, listener semantics) and the capability list.
+8
View File
@@ -1813,6 +1813,10 @@
"exports": ["./render/cesium/unbound"],
"modules": [
"src/render/cesium/unbound.js",
"src/render/cesium/globe.js",
"src/maps/google3d.js",
"src/render/cesium/imagery.js",
"src/render/cesium/tileRequests.js",
"src/data/iconSetPrimitive.js",
"src/data/aircraftRecession.js",
"src/data/motionModel.js",
@@ -2462,6 +2466,10 @@
"cctv-layer": {
"exports": ["./layers/cctv"],
"modules": [
"src/maps/google3d.js",
"src/render/cesium/globe.js",
"src/render/cesium/imagery.js",
"src/render/cesium/tileRequests.js",
"src/data/headingDegrees.js",
"src/data/cctvCards.js",
"src/data/cctvGizmo.js",
+2 -2
View File
@@ -85,12 +85,12 @@ export function createOsmOverlayLayer(overlay, { globeOf = findGlobe } = {}) {
/**
* What the overlay drapes on: the map stack's record, or with no map
* stack, whether the viewer's globe is shown.
* stack, whether the renderer shows the globe.
*/
function drapeSurface() {
const recorded = mapStack?.getDrapeSurface?.();
if (recorded) return recorded;
return viewer?.scene?.globe?.show === true ? 'globe' : 'none';
return globeOf(viewer)?.isGlobeVisible?.() === true ? 'globe' : 'none';
}
/** Add or remove the owned imagery layer to match the state. */
+9 -4
View File
@@ -14,6 +14,10 @@ function fakeGlobe() {
const layers = [];
return {
layers,
visible: true,
isGlobeVisible() {
return this.visible;
},
imagery: {
add(spec) {
const layer = {
@@ -52,7 +56,7 @@ function fakeMapStack() {
function setup(overlay = OSM_OVERLAYS[0]) {
const globe = fakeGlobe();
const viewer = { scene: { globe: { show: true } } };
const viewer = {};
const layer = createOsmOverlayLayer(overlay, {
globeOf: (given) => (given === viewer ? globe : null),
});
@@ -152,14 +156,15 @@ test('with no surface to drape on the row explains itself, and recovers when one
test('without a map stack, the viewer’s globe decides, polled by the stats', () => {
const globe = fakeGlobe();
const viewer = { scene: { globe: { show: false } } };
globe.visible = false;
const viewer = {};
const layer = createOsmOverlayLayer(OSM_OVERLAYS[0], {
globeOf: () => globe,
});
layer.init(viewer);
layer.enable();
assert.equal(layer.getStats().error, NO_IMAGERY_HOST);
viewer.scene.globe.show = true;
globe.visible = true;
assert.equal(layer.getStats().error, null);
});
@@ -177,7 +182,7 @@ test('an overlay enabled before its viewer has a globe port adds it once one doe
const globe = fakeGlobe();
let port = null;
const layer = createOsmOverlayLayer(OSM_OVERLAYS[0], { globeOf: () => port });
layer.init({ scene: { globe: { show: true } } });
layer.init({});
layer.enable();
assert.equal(layer.diagnostics().ownedCount, 0);
port = globe;
+21 -3
View File
@@ -4,6 +4,7 @@ import { readFileSync } from 'node:fs';
import * as Cesium from 'cesium';
import { MAP_STACKS } from '../mapStackController.js';
import { fromDegrees, toLonLatH } from '../geo/ellipsoid.js';
import { bindRenderer } from '../render/rendererOf.js';
import { bindFakeDraw } from '../testSupport/fakeDrawPort.mjs';
import { fakeCameraPort } from '../testSupport/fakeCameraPort.mjs';
import { fakeSceneFrame } from '../testSupport/fakeCesiumScene.mjs';
@@ -216,15 +217,32 @@ test('cable ground lines drape on exactly the active surface on every stack', ()
// Boot fires no stack event; the initial value derives from live scene
// state exactly like the height-datum listeners: photoreal ⇔ globe hidden.
let globeShown = false;
const host = {};
const unbind = bindRenderer(host, {
globe: { isGlobeVisible: () => globeShown },
});
assert.equal(cableClassificationTypeForScene(host), 'tiles');
globeShown = true;
assert.equal(cableClassificationTypeForScene(host), 'terrain');
unbind();
assert.equal(cableClassificationTypeForScene(null), 'both');
// A scene that cannot say whether the globe is shown: every surface.
const other = {};
const unbindOther = bindRenderer(other, { globe: {} });
assert.equal(cableClassificationTypeForScene(other), 'both');
unbindOther();
// A viewer of its own with no renderer bound reads its globe through the
// unbound port; with no globe it gives no reading.
assert.equal(
cableClassificationTypeForScene({ globe: { show: false } }),
cableClassificationTypeForScene({ scene: { globe: { show: false } } }),
'tiles',
);
assert.equal(
cableClassificationTypeForScene({ globe: { show: true } }),
cableClassificationTypeForScene({ scene: { globe: { show: true } } }),
'terrain',
);
assert.equal(cableClassificationTypeForScene(null), 'both');
assert.equal(cableClassificationTypeForScene({ scene: {} }), 'both');
});
test('cable reference sweep gate is dirty-only — no timer path', () => {
+7 -5
View File
@@ -1,4 +1,5 @@
import { fromDegrees } from '../../geo/ellipsoid.js';
import { findGlobe } from '../../render/rendererOf.js';
import {
SUPPORT_KEYS,
planeSupportPoints,
@@ -13,7 +14,7 @@ export function createGround({ state: layerState, services, parts, source }) {
const { resolveEllipsoidalGround } = services.terrain;
/**
* Task 5 (height-datum fix): maps the scene's `globe.show` flag to the surface
* Task 5 (height-datum fix): maps whether the renderer shows the globe to the surface
* regime key the per-camera ground cache is keyed by (spec §2 "cache by
* surface regime", collapsed to two keys — ion World Terrain and Re:Earth
* globe terrain get the same handling):
@@ -26,7 +27,8 @@ export function createGround({ state: layerState, services, parts, source }) {
* Only an explicit `false` (the photoreal stack hides the globe) selects
* `google-3d`; undefined/null (no viewer / torn down) must fall to the regime
* that never touches the scene. Pure — exported for the unit suite.
* @param {boolean|undefined|null} globeShow - `viewer.scene.globe.show`.
* @param {boolean|undefined|null} globeShow - Whether the renderer shows the
* globe (`globe.isGlobeVisible()`).
* @returns {'google-3d'|'terrain-globe'}
*/
@@ -36,15 +38,15 @@ export function createGround({ state: layerState, services, parts, source }) {
/**
* Task 5: the surface regime the scene is CURRENTLY rendering, derived live
* from `globe.show` (mapStackController's `_activatePhotoreal` /
* `_activateGlobeStack` flip exactly this flag). Reading scene state directly
* from whether the renderer shows the globe (mapStackController's
* `_activatePhotoreal` / `_activateGlobeStack` flip exactly this). Reading it live
* — rather than caching the map-stack id — means the regime is correct even
* for stack changes this module never got an event for.
* @returns {'google-3d'|'terrain-globe'}
*/
function currentSurfaceRegime() {
return surfaceRegimeKey(layerState._viewer?.scene?.globe?.show);
return surfaceRegimeKey(findGlobe(layerState._viewer)?.isGlobeVisible?.());
}
/**
+1
View File
@@ -28,6 +28,7 @@ import { toColor } from '../../render/cesium/draw.js';
// Loads the factory a viewer of a caller's own gets its camera port from,
// which the rest of the layer reads the eye through.
import '../../render/cesium/camera.js';
import '../../render/cesium/globe.js';
// The policy's renderer colours as the Cesium colours the icons and lines take.
const ACTIVE_CAMERA_COLOR = toColor(ACTIVE_CAMERA_RGBA);
+1 -1
View File
@@ -175,7 +175,7 @@ export function createState({ services }) {
// Task 5: last surface regime the record geometry was recomputed for. The
// map-stack change listener compares the CURRENT regime (derived live from
// scene.globe.show) against this so bing→osm switches (same 'terrain-globe'
// whether the renderer shows the globe) against this so bing→osm switches (same 'terrain-globe'
// regime) don't trigger a pointless full-catalog rewrite.
layerState._lastAppliedRegime = null;
+2 -2
View File
@@ -15,14 +15,14 @@ export function createLifecycle({ state, parts, source, mapStackEventTarget }) {
init(viewer) {
state._viewer = viewer;
state._clampTo = cableClassificationTypeForScene(viewer?.scene);
state._clampTo = cableClassificationTypeForScene(viewer);
parts.rendering.attach(viewer);
if (!state._mapStackListener && mapStackEventTarget?.addEventListener) {
state._mapStackListener = (event) => {
parts.rendering.applyCableClassification(
event?.detail?.activeId
? cableClassificationTypeForStack(event.detail.activeId)
: cableClassificationTypeForScene(state._viewer?.scene),
: cableClassificationTypeForScene(state._viewer),
);
};
mapStackEventTarget.addEventListener(
+9 -5
View File
@@ -1,3 +1,4 @@
import { findGlobe } from '../../render/rendererOf.js';
import { CABLE_GLOBE_STACK_IDS } from './policy.js';
/**
@@ -20,15 +21,18 @@ export function cableClassificationTypeForStack(activeId) {
}
/**
* Derive the active surface from live scene state. The boot-time
* Derive the active surface from what the renderer draws. The boot-time
* `setStack(..., { silent: true })` fires no 'gev:map-stack-changed' event,
* so the initial surface is read the way the height-datum listeners do: the
* photoreal regime is exactly "globe hidden".
* @param {{globe?: {show?: boolean}}|null|undefined} scene
* @param {object|null|undefined} host The scene object the renderer is bound
* to (the viewer); `both` when it has none, or one that cannot say whether
* the globe is shown.
* @returns {'tiles'|'terrain'|'both'}
*/
export function cableClassificationTypeForScene(scene) {
if (!scene?.globe) return 'both';
return scene.globe.show === false ? 'tiles' : 'terrain';
export function cableClassificationTypeForScene(host) {
const visible = findGlobe(host)?.isGlobeVisible?.();
if (typeof visible !== 'boolean') return 'both';
return visible ? 'terrain' : 'tiles';
}
+8 -1
View File
@@ -438,6 +438,8 @@ export function createCesiumGlobe(
return progressListeners.on(cb);
},
};
if (can('globeVisibility'))
port.isGlobeVisible = () => scene.globe?.show === true;
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.
@@ -469,8 +471,13 @@ export function createCesiumGlobe(
// built over it: imagery and the sky as the renderer's would.
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']);
if (typeof viewer.scene.globe?.show === 'boolean')
capabilities.add('globeVisibility');
const { port, dispose } = createCesiumGlobe(viewer, {
capabilities: new Set(['imageHooks', 'imageryOnTiles', 'splitSwipe']),
capabilities,
requestRender: () => viewer.scene.requestRender?.(),
});
// A renderer bound later leaves it running: its layers keep following
+13 -1
View File
@@ -4,7 +4,13 @@ import * as Cesium from 'cesium';
import { createCesiumGlobe, markBaseTileset } from './globe.js';
import { hookProvider, TILE_RETRY_DELAY_MS, xyzTileUrl } from './imagery.js';
const ALL = new Set(['imageHooks', 'imageryOnTiles', 'splitSwipe', 'terrain']);
const ALL = new Set([
'imageHooks',
'imageryOnTiles',
'splitSwipe',
'terrain',
'globeVisibility',
]);
const url = (name) => `https://${name}.invalid/{z}/{x}/{y}.png`;
function fakeScene() {
@@ -458,8 +464,14 @@ test('globe visibility, settling and progress', () => {
const { scene, port, tick } = setup();
port.setGlobeVisible(false);
assert.equal(scene.globe.show, false);
assert.equal(port.isGlobeVisible(), false);
assert.equal(port.isSettled('terrain'), true, 'a hidden globe loads nothing');
port.setGlobeVisible(true);
assert.equal(port.isGlobeVisible(), true);
// It reads the scene, whoever changed it.
scene.globe.show = false;
assert.equal(port.isGlobeVisible(), false);
scene.globe.show = true;
scene.globe.tilesLoaded = false;
assert.equal(port.isSettled('terrain'), false);
assert.equal(port.isSettled('base'), false);
+1
View File
@@ -69,6 +69,7 @@ export const CESIUM_CHECKS = new Set([
'globe.imagery',
'globe.sky',
'globe.split',
'globe.visible',
'globe.withoutImageHooks',
'input.behaviours',
'input.clickPick',
+8 -1
View File
@@ -44,6 +44,7 @@ const GLOBE_CAPABILITIES = [
'imageryOnTiles',
'splitSwipe',
'imageHooks',
'globeVisibility',
];
/**
@@ -67,7 +68,13 @@ export function cesiumCapabilities(scene, only) {
...queryCapabilities(scene),
];
const allowed = only && new Set(only);
return all.filter((c) => !allowed || allowed.has(c));
return all.filter(
(c) =>
(!allowed || allowed.has(c)) &&
// Visibility reads back only from a globe that keeps it: a scene
// made without one gives no reading.
(c !== 'globeVisibility' || typeof scene?.globe?.show === 'boolean'),
);
}
/**
+9
View File
@@ -22,7 +22,14 @@ test('capabilities follow what the scene supports', () => {
'splitSwipe',
'imageHooks',
];
const globe = { show: true };
assert.deepEqual(cesiumCapabilities({}), ['models', ...effects]);
// A scene with a globe reads its visibility back.
assert.deepEqual(cesiumCapabilities({ globe }), [
'models',
...effects,
'globeVisibility',
]);
assert.deepEqual(cesiumCapabilities({ pickPositionSupported: true }), [
'models',
...effects,
@@ -30,12 +37,14 @@ test('capabilities follow what the scene supports', () => {
]);
assert.deepEqual(
cesiumCapabilities({
globe,
pickPositionSupported: true,
sampleHeightSupported: true,
}),
[
'models',
...effects,
'globeVisibility',
'pickPosition',
'sampleHeight',
'finestHeights',
+2 -1
View File
@@ -2,10 +2,11 @@
* @module render/cesium/unbound
* @description What to load, once, before handing the Cesium-free
* layers a Cesium viewer with no renderer bound: the factories
* that build a camera, credits, effects, draw, frame and query port over
* that build a camera, credits, effects, draw, frame, globe and query port over
* such a viewer when code first asks for one (`rendererOf.js`).
*/
import './camera.js';
import './effects.js';
import './frame.js';
import './globe.js';
import './query.js';
+11
View File
@@ -2617,6 +2617,17 @@ export function portChecks() {
},
{ capability: 'splitSwipe' },
),
check(
'globe.visible',
'the globe surface reads back as it was shown or hidden',
(h, r) => {
r.globe.setGlobeVisible(false);
equal(r.globe.isGlobeVisible(), false, 'hidden');
r.globe.setGlobeVisible(true);
equal(r.globe.isGlobeVisible(), true, 'shown');
},
{ capability: 'globeVisibility' },
),
check(
'globe.sky',
'sky settings round-trip and keep unchanged keys',
+2
View File
@@ -206,5 +206,7 @@ export type Capability =
| 'sharpen'
/** Following with an automatically chosen frame (orbit or north-up). */
| 'followAutodetect'
/** Reading back whether the globe surface is shown (`globe.isGlobeVisible`). */
| 'globeVisibility'
/** A built-in quality benchmark. */
| 'benchmark';
+7
View File
@@ -258,6 +258,13 @@ export interface GlobePort {
setTerrain(spec: TerrainSpec | null): Promise<void>;
/** Show or hide the globe surface (hidden under photoreal). */
setGlobeVisible(visible: boolean): void;
/**
* `globeVisibility`: whether the globe surface is shown now, as
* `setGlobeVisible` or whoever last set it left it. For code that only holds
* the scene and must know whether the surface it drapes on or samples is
* drawn.
*/
isGlobeVisible?(): boolean;
/** `surfaceShading`. */
setSurfaceShading?(shading: SurfaceShading | null): void;
/** `clouds`: the renderer's volumetric clouds, or none. */
+2
View File
@@ -46,6 +46,7 @@ export const CAPABILITIES = Object.freeze([
'bloom',
'sharpen',
'followAutodetect',
'globeVisibility',
'benchmark',
]);
@@ -147,6 +148,7 @@ export const PORTS = deepFreeze({
'isSettled',
'on',
),
['isGlobeVisible', 'globeVisibility'],
['setSurfaceShading', 'surfaceShading'],
['setClouds', 'clouds'],
['setWater', 'water'],
+4
View File
@@ -917,6 +917,7 @@ export function createStubRenderer(options = {}) {
...(options.sky ?? {}),
};
let photorealStatus = { route: 'none' };
let globeVisible = true;
function addImagery(spec, index) {
if (
@@ -1055,6 +1056,7 @@ export function createStubRenderer(options = {}) {
},
setGlobeVisible(visible) {
log('globe', 'setGlobeVisible', [visible]);
globeVisible = Boolean(visible);
requestRender('base');
},
imagery: {
@@ -1078,6 +1080,8 @@ export function createStubRenderer(options = {}) {
};
},
};
if (capabilities.has('globeVisibility'))
globe.isGlobeVisible = () => globeVisible;
if (capabilities.has('surfaceShading'))
globe.setSurfaceShading = (shading) => {
log('globe', 'setSurfaceShading', [shading]);
+6 -3
View File
@@ -7,7 +7,8 @@
* builds `findCredits`' port for such a viewer the same way.
* Likewise an entry that reaches a caller of `findEffects` must load
* `render/cesium/effects.js`, which provides the effects factory, and one
* that reaches a caller of `findGlobe` must load `render/cesium/globe.js`.
* that reaches a caller of `findGlobe` must load `render/cesium/globe.js`,
* or be such a Cesium-free entry (below).
* An entry that reaches a caller of `findDraw` or `drawOf` loads
* `render/cesium/draw.js` the same way (the camera factory loads it),
* unless it is Cesium-free: then it is listed in `DRAW_FROM_CALLER`, and
@@ -287,8 +288,10 @@ test('every public entry that reaches a findEffects caller loads the unbound eff
test('every public entry that reaches a findGlobe caller loads the unbound globe factory', () => {
// A caller may take `findGlobe` as a default rather than call it, so any
// use of the name counts.
checkLookupFactory('findGlobe', GLOBE_FACTORY);
// use of the name counts. A Cesium-free entry with no globe port (its
// caller has not loaded `./render/cesium/unbound`) reads the globe as
// unknown.
checkLookupFactory('findGlobe', GLOBE_FACTORY, { fromCaller: true });
});
test('every public entry that reaches a findQuery or queryOf caller loads the unbound query factory, or its caller can', () => {
+1
View File
@@ -98,6 +98,7 @@ export function fakeGlobePort({ settled = () => true } = {}) {
setGlobeVisible(visible) {
globeVisible = Boolean(visible);
},
isGlobeVisible: () => globeVisible,
get globeVisible() {
return globeVisible;
},