diff --git a/docs/RENDERER-CONTRACT.md b/docs/RENDERER-CONTRACT.md index da7e1ac38..08d90fbb5 100644 --- a/docs/RENDERER-CONTRACT.md +++ b/docs/RENDERER-CONTRACT.md @@ -341,7 +341,9 @@ What it draws of the style specification: other paint or layout property not listed above. The Cesium port loads the style before the base changes (a style that fails -leaves the base as it was), draws it as Web Mercator imagery under the +leaves the base as it was; a later `setBase`, or disposal, aborts the load and +the overtaken call changes nothing, resolving with `imagery: []` and +`settled: false`), draws it as Web Mercator imagery under the base's other imagery (`src/render/cesium/vectorBase.js`, 256 px tiles to level 20), and credits each source's attribution as plain text. The stub loads the style and paints nothing. The check `globe.base.vector` serves a diff --git a/src/render/cesium/globe.js b/src/render/cesium/globe.js index 7470a5672..3e49d9a9c 100644 --- a/src/render/cesium/globe.js +++ b/src/render/cesium/globe.js @@ -135,6 +135,9 @@ export function createCesiumGlobe( let photorealStatus = { route: 'none' }; let photorealGen = 0; let terrainGen = 0; + let baseGen = 0; + /** Aborts the style load of the `setBase` in flight, if any. */ + let baseLoad = null; let baseCredit = null; // The vector base's sources' credits. const vectorCredits = []; @@ -240,11 +243,36 @@ export function createCesiumGlobe( async function setBase(base) { if (base.vector && !can('vectorBase')) throw new TypeError('This renderer draws no vector base'); + // The last call wins: one superseded (or disposed) before its base + // changes changes nothing and resolves with the base as it stands. + const gen = ++baseGen; + baseLoad?.abort(); + baseLoad = null; + const current = () => gen === baseGen && !disposed; + const superseded = () => ({ + photoreal: photorealStatus, + imagery: [], + settled: false, + }); + if (disposed) return superseded(); // The style loads before the base changes: one that fails changes // nothing. - const style = base.vector - ? await loadVectorStyle(base.vector.styleUrl) - : null; + let style = null; + if (base.vector) { + const load = new AbortController(); + baseLoad = load; + try { + style = await loadVectorStyle(base.vector.styleUrl, undefined, { + signal: load.signal, + }); + } catch (error) { + if (!current()) return superseded(); + throw error; + } finally { + if (baseLoad === load) baseLoad = null; + } + if (!current()) return superseded(); + } for (const handle of imagery.list()) handle.remove(); baseCredit?.(); baseCredit = base.credit && credits ? credits.addStatic(base.credit) : null; @@ -268,7 +296,8 @@ export function createCesiumGlobe( return { photoreal: photorealStatus, imagery: layers, - settled: isSettled('base'), + // A base a later call replaced has not settled. + settled: current() && isSettled('base'), }; } @@ -579,6 +608,9 @@ export function createCesiumGlobe( disposed = true; photorealGen += 1; terrainGen += 1; + baseGen += 1; + baseLoad?.abort(); + baseLoad = null; for (const off of removers) off(); shading = null; dropShadingMaterial(); diff --git a/src/render/cesium/globe.test.mjs b/src/render/cesium/globe.test.mjs index 36a524e47..0a7c51104 100644 --- a/src/render/cesium/globe.test.mjs +++ b/src/render/cesium/globe.test.mjs @@ -470,6 +470,82 @@ test('setBase replaces the imagery and says what it drew', async () => { await assert.rejects(port.setBase({ vector: { styleUrl: 'x' } }), /vector/); }); +/** `globalThis.fetch` answering each URL when the test says, honouring aborts. */ +function heldFetch() { + const held = []; + const original = globalThis.fetch; + const options = { honourAbort: true }; + globalThis.fetch = (url, { signal } = {}) => + new Promise((resolve, reject) => { + if (options.honourAbort) + signal?.addEventListener('abort', () => reject(signal.reason)); + held.push({ + url, + signal, + answer: (body) => + resolve({ ok: true, status: 200, json: async () => body }), + }); + }); + return { held, options, restore: () => (globalThis.fetch = original) }; +} + +const EMPTY_STYLE = { version: 8, sources: {}, layers: [] }; + +test('a slow vector setBase a later setBase supersedes changes nothing', async () => { + const { held, options, restore } = heldFetch(); + try { + const { port } = setup(new Set([...ALL, 'vectorBase'])); + const slow = port.setBase({ + vector: { styleUrl: 'https://s.invalid/a.json' }, + }); + const fast = await port.setBase({ + imagery: [{ kind: 'xyz', url: url('one') }], + }); + assert.equal(held.length, 1); + assert.equal(held[0].signal.aborted, true, 'its style load is aborted'); + const status = await slow; + assert.deepEqual(status.imagery, []); + assert.equal(status.settled, false); + assert.deepEqual(port.imagery.list(), fast.imagery); + + // One whose load ignores the abort and lands late changes nothing either. + options.honourAbort = false; + const late = port.setBase({ + vector: { styleUrl: 'https://s.invalid/b.json' }, + }); + const kept = await port.setBase({ + imagery: [{ kind: 'xyz', url: url('two') }], + }); + held[1].answer(EMPTY_STYLE); + assert.deepEqual((await late).imagery, []); + assert.deepEqual(port.imagery.list(), kept.imagery); + } finally { + restore(); + } +}); + +test('a vector setBase in flight when the globe is disposed resolves, changing nothing', async () => { + const { held, restore } = heldFetch(); + try { + const { port, dispose } = setup(new Set([...ALL, 'vectorBase'])); + const before = await port.setBase({ + imagery: [{ kind: 'xyz', url: url('one') }], + }); + const pending = port.setBase({ + vector: { styleUrl: 'https://s.invalid/a.json' }, + }); + dispose(); + const status = await pending; + assert.deepEqual(status.imagery, []); + assert.equal(status.settled, false); + assert.deepEqual(port.imagery.list(), before.imagery); + assert.equal(held[0].signal.aborted, true); + assert.deepEqual((await port.setBase({ imagery: [] })).imagery, []); + } finally { + restore(); + } +}); + test('globe visibility, settling and progress', () => { const { scene, port, tick } = setup(); port.setGlobeVisible(false); diff --git a/src/render/contract/globe.d.ts b/src/render/contract/globe.d.ts index d890f6182..ba796e51e 100644 --- a/src/render/contract/globe.d.ts +++ b/src/render/contract/globe.d.ts @@ -237,7 +237,14 @@ export interface LoadProgress { export type SettleKind = 'base' | 'tiles' | 'terrain' | 'imagery' | 'surface'; export interface GlobePort { - /** Switch the whole base at once; resolves when the new base has settled. */ + /** + * Switch the whole base at once; resolves when the new base has settled. + * The last call wins: one a later `setBase` (or the renderer's disposal) + * overtakes before its base changes (its vector style still loading) + * changes nothing and resolves with `imagery: []`, `settled: false` and the + * photoreal status as it stands, never rejecting; one overtaken after it + * changed the base resolves with `settled: false`. + */ setBase(base: BaseSpec): Promise; /** `photoreal`: on, off or a new token route. */ setPhotoreal(spec: PhotorealSpec | null): Promise; diff --git a/src/render/stub/index.js b/src/render/stub/index.js index 837833096..e2055ed26 100644 --- a/src/render/stub/index.js +++ b/src/render/stub/index.js @@ -1418,14 +1418,42 @@ export function createStubRenderer(options = {}) { // `surfaceIdentity`: bumped by whatever changes what heights answer against. let surfaceVersion = 0; let terrainKey = 'null'; + // The last `setBase` wins; its style load in flight, if any. + let baseGen = 0; + let baseLoad = null; const globe = { async setBase(base) { log('globe', 'setBase', [base]); if (base.vector && !capabilities.has('vectorBase')) throw new TypeError('This renderer draws no vector base'); + const gen = ++baseGen; + baseLoad?.abort(); + baseLoad = null; + const current = () => gen === baseGen && !destroyed; + // Superseded (or destroyed) before its base changes: nothing changes. + const superseded = () => ({ + photoreal: photorealStatus, + imagery: [], + settled: false, + }); + if (destroyed) return superseded(); // The style is loaded, as a renderer drawing it loads it, so one that // fails changes nothing; the stub paints none of it. - if (base.vector) await loadVectorStyle(base.vector.styleUrl); + if (base.vector) { + const load = new AbortController(); + baseLoad = load; + try { + await loadVectorStyle(base.vector.styleUrl, undefined, { + signal: load.signal, + }); + } catch (error) { + if (!current()) return superseded(); + throw error; + } finally { + if (baseLoad === load) baseLoad = null; + } + if (!current()) return superseded(); + } for (const layer of imageryLayers.slice()) layer.remove(); if (base.photoreal !== undefined) await globe.setPhotoreal(base.photoreal); @@ -1781,6 +1809,9 @@ export function createStubRenderer(options = {}) { // A flight in progress ends cancelled and gives back its input hold. camera.endFlight(); destroyed = true; + baseGen += 1; + baseLoad?.abort(); + baseLoad = null; if (options.container) canvas.remove?.(); for (const clear of onceTimers) clear(); onceTimers.clear(); diff --git a/src/render/stub/stub.test.mjs b/src/render/stub/stub.test.mjs index f23a489da..5ca990359 100644 --- a/src/render/stub/stub.test.mjs +++ b/src/render/stub/stub.test.mjs @@ -197,3 +197,44 @@ test('the stub camera ends no move while it follows', () => { assert.deepEqual(seen, ['start', 'end']); r.destroy(); }); + +test('a slow vector setBase a later setBase supersedes changes nothing, nor one the destroy ends', async () => { + const held = []; + const original = globalThis.fetch; + globalThis.fetch = (url, { signal } = {}) => + new Promise((resolve) => { + held.push({ + signal, + answer: () => + resolve({ + ok: true, + status: 200, + json: async () => ({ version: 8, sources: {}, layers: [] }), + }), + }); + }); + try { + const r = createStubRenderer(); + const slow = r.globe.setBase({ + vector: { styleUrl: 'https://s.invalid/a' }, + }); + const fast = await r.globe.setBase({ + imagery: [{ kind: 'xyz', url: 'https://one.invalid/{z}/{x}/{y}.png' }], + }); + assert.equal(held[0].signal.aborted, true, 'its style load is aborted'); + held[0].answer(); + const status = await slow; + assert.deepEqual([status.imagery, status.settled], [[], false]); + assert.deepEqual(r.globe.imagery.list(), fast.imagery); + + const ended = r.globe.setBase({ + vector: { styleUrl: 'https://s.invalid/b' }, + }); + r.destroy(); + held[1].answer(); + assert.deepEqual((await ended).imagery, []); + assert.deepEqual(r.globe.imagery.list(), fast.imagery); + } finally { + globalThis.fetch = original; + } +});