diff --git a/docs/RENDERER-CONTRACT.md b/docs/RENDERER-CONTRACT.md index 82328c20e..b5b296721 100644 --- a/docs/RENDERER-CONTRACT.md +++ b/docs/RENDERER-CONTRACT.md @@ -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. diff --git a/scripts/package-boundaries.json b/scripts/package-boundaries.json index 0c66018f5..81e471d3a 100644 --- a/scripts/package-boundaries.json +++ b/scripts/package-boundaries.json @@ -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", diff --git a/src/data/osmOverlays.js b/src/data/osmOverlays.js index 9fab90c14..d78c02393 100644 --- a/src/data/osmOverlays.js +++ b/src/data/osmOverlays.js @@ -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. */ diff --git a/src/data/osmOverlays.test.mjs b/src/data/osmOverlays.test.mjs index 5bb77e78c..37f99f3db 100644 --- a/src/data/osmOverlays.test.mjs +++ b/src/data/osmOverlays.test.mjs @@ -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; diff --git a/src/data/telegeographySubmarineCables.test.mjs b/src/data/telegeographySubmarineCables.test.mjs index 629942bde..16ddc73d4 100644 --- a/src/data/telegeographySubmarineCables.test.mjs +++ b/src/data/telegeographySubmarineCables.test.mjs @@ -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', () => { diff --git a/src/layers/cctv/ground.js b/src/layers/cctv/ground.js index 2a7b135bf..0b57cba13 100644 --- a/src/layers/cctv/ground.js +++ b/src/layers/cctv/ground.js @@ -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?.()); } /** diff --git a/src/layers/cctv/rendering.js b/src/layers/cctv/rendering.js index a15dd97d6..ea06324a6 100644 --- a/src/layers/cctv/rendering.js +++ b/src/layers/cctv/rendering.js @@ -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); diff --git a/src/layers/cctv/state.js b/src/layers/cctv/state.js index 154897d15..3efb82a57 100644 --- a/src/layers/cctv/state.js +++ b/src/layers/cctv/state.js @@ -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; diff --git a/src/layers/submarineCables/lifecycle.js b/src/layers/submarineCables/lifecycle.js index 99c4d6fb5..cb69607a6 100644 --- a/src/layers/submarineCables/lifecycle.js +++ b/src/layers/submarineCables/lifecycle.js @@ -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( diff --git a/src/layers/submarineCables/surface.js b/src/layers/submarineCables/surface.js index 3ef7e57c5..2693d9ed9 100644 --- a/src/layers/submarineCables/surface.js +++ b/src/layers/submarineCables/surface.js @@ -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'; } diff --git a/src/render/cesium/globe.js b/src/render/cesium/globe.js index 90a8d9da0..1ddb4c806 100644 --- a/src/render/cesium/globe.js +++ b/src/render/cesium/globe.js @@ -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 diff --git a/src/render/cesium/globe.test.mjs b/src/render/cesium/globe.test.mjs index f1f3350db..4e24bd5d2 100644 --- a/src/render/cesium/globe.test.mjs +++ b/src/render/cesium/globe.test.mjs @@ -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); diff --git a/src/render/cesium/harness.js b/src/render/cesium/harness.js index 67a695877..b93109556 100644 --- a/src/render/cesium/harness.js +++ b/src/render/cesium/harness.js @@ -69,6 +69,7 @@ export const CESIUM_CHECKS = new Set([ 'globe.imagery', 'globe.sky', 'globe.split', + 'globe.visible', 'globe.withoutImageHooks', 'input.behaviours', 'input.clickPick', diff --git a/src/render/cesium/ports.js b/src/render/cesium/ports.js index ef0f87d07..c414b5b0c 100644 --- a/src/render/cesium/ports.js +++ b/src/render/cesium/ports.js @@ -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'), + ); } /** diff --git a/src/render/cesium/ports.test.mjs b/src/render/cesium/ports.test.mjs index 041566b1c..721518c0e 100644 --- a/src/render/cesium/ports.test.mjs +++ b/src/render/cesium/ports.test.mjs @@ -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', diff --git a/src/render/cesium/unbound.js b/src/render/cesium/unbound.js index 850451b39..fe442a317 100644 --- a/src/render/cesium/unbound.js +++ b/src/render/cesium/unbound.js @@ -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'; diff --git a/src/render/conformance/checks/ports.js b/src/render/conformance/checks/ports.js index 039e92121..17ae67091 100644 --- a/src/render/conformance/checks/ports.js +++ b/src/render/conformance/checks/ports.js @@ -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', diff --git a/src/render/contract/common.d.ts b/src/render/contract/common.d.ts index c6a1e1375..50faf956e 100644 --- a/src/render/contract/common.d.ts +++ b/src/render/contract/common.d.ts @@ -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'; diff --git a/src/render/contract/globe.d.ts b/src/render/contract/globe.d.ts index c24f9e7c8..4c5cd0000 100644 --- a/src/render/contract/globe.d.ts +++ b/src/render/contract/globe.d.ts @@ -258,6 +258,13 @@ export interface GlobePort { setTerrain(spec: TerrainSpec | null): Promise; /** 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. */ diff --git a/src/render/contract/index.js b/src/render/contract/index.js index ed5407bc1..25e5f8542 100644 --- a/src/render/contract/index.js +++ b/src/render/contract/index.js @@ -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'], diff --git a/src/render/stub/index.js b/src/render/stub/index.js index 89bb32430..7be7eed67 100644 --- a/src/render/stub/index.js +++ b/src/render/stub/index.js @@ -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]); diff --git a/src/render/unboundCamera.test.mjs b/src/render/unboundCamera.test.mjs index 1acdf43ad..9cdf2eb1e 100644 --- a/src/render/unboundCamera.test.mjs +++ b/src/render/unboundCamera.test.mjs @@ -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', () => { diff --git a/src/testSupport/fakeGlobePort.mjs b/src/testSupport/fakeGlobePort.mjs index aab20466d..173a7523d 100644 --- a/src/testSupport/fakeGlobePort.mjs +++ b/src/testSupport/fakeGlobePort.mjs @@ -98,6 +98,7 @@ export function fakeGlobePort({ settled = () => true } = {}) { setGlobeVisible(visible) { globeVisible = Boolean(visible); }, + isGlobeVisible: () => globeVisible, get globeVisible() { return globeVisible; },