diff --git a/dev/conformance/main.js b/dev/conformance/main.js index 7189d3a86..2d32b806c 100644 --- a/dev/conformance/main.js +++ b/dev/conformance/main.js @@ -27,7 +27,14 @@ import { const REFERENCES = '/src/render/conformance/goldens/visual/'; const SAVE = '/__conformance/references/'; -const ctx = { toEcef, assets: { model: '/models/c172.glb' } }; +const ctx = { + toEcef, + assets: { + model: '/models/c172.glb', + // Not served: the model failure check loads it. + missingModel: '/models/conformance-missing.glb', + }, +}; const $ = (id) => document.getElementById(id); const status = (text) => ($('status').textContent = text); @@ -38,7 +45,10 @@ const RENDERERS = { const HARNESSES = { stub: () => [createStubHarness('stub (browser)'), {}], cesium: () => [ - createCesiumHarness({ model: ctx.assets.model }), + createCesiumHarness({ + model: ctx.assets.model, + missingModel: ctx.assets.missingModel, + }), { only: (id) => CESIUM_CHECKS.has(id) }, ], }; diff --git a/docs/RENDERER-CONTRACT.md b/docs/RENDERER-CONTRACT.md index 8e4d6a970..c6071b1ab 100644 --- a/docs/RENDERER-CONTRACT.md +++ b/docs/RENDERER-CONTRACT.md @@ -109,7 +109,10 @@ in memory and draws nothing. It has: height arc and easing, `changed` thresholds and follows; - picks against what was drawn, or a scripted table; - scripted heights; -- a virtual clock that nothing advances on its own. +- a virtual clock that nothing advances on its own; +- models that load at once, but for urls under `stub-fail:` + (`STUB_FAILING_MODEL_SCHEME`), which fire `loadFailed` instead of `ready` + (they are still picked where they are). `renderer.testing` drives it with `tick()`, `advance(ms)`, `pointer(type, x, y)`, `scriptPicks`, `setHeights` and `cacheHeight`, and records its calls. @@ -132,7 +135,8 @@ renderer under test: - `tolerance` and `flightPaths`. Optional members widen what is checked: `pointer` for synthetic input, -`scriptHeights`, and `assets.model`. +`scriptHeights`, `assets.model`, and `assets.missingModel` (a model url +that fails to load, for the `loadFailed` check). There are two layers of checks. diff --git a/src/data/aircraftModelLayer.js b/src/data/aircraftModelLayer.js index b010d1e3a..37de8e6a0 100644 --- a/src/data/aircraftModelLayer.js +++ b/src/data/aircraftModelLayer.js @@ -30,10 +30,9 @@ const PRELOAD_ID = '~preload'; /** Where the preload item waits, unshown. */ const NOWHERE = Object.freeze({ x: 0, y: 0, z: 0 }); -/** How often (ms) a model that has not loaded is written again, so a - * renderer that retries failed loads on write (as the Cesium one does) - * gets the chance even for a parked contact whose item never changes. */ -const UNREADY_REWRITE_MS = 5000; +/** How long (ms) a fleet model whose load failed (`loadFailed`) waits + * before it is removed and added again, which loads it again. */ +const FLEET_MODEL_RETRY_MS = 5000; /** A colour as the draw contract's `[r, g, b, a]`, from `{red, green, blue, alpha}`. */ function rgba(color) { @@ -68,8 +67,13 @@ function inView(pose, point) { * layer lifetime (`_createModelSets`): the fleet's, one item per modelled * contact, and the tracked contact's (with a hidden item that keeps the * tracked asset loaded). Each item is re-posed and restyled in place; the - * layer keeps its own record of each (`modelRecord.js`), and a set's `ready` - * says when a model has loaded. Picks name the set and the contact's id. + * layer keeps its own record of each (`modelRecord.js`), a set's `ready` + * says when a model has loaded and its `loadFailed` when one failed to. A + * failed fleet model is loaded again every `FLEET_MODEL_RETRY_MS`; the + * tracked model has a per-selection budget (`TRACKED_MODEL_MAX_LOAD_FAILS` + * failures, `TRACKED_MODEL_RETRY_BACKOFF_MS` apart), after which the contact + * stays an icon until another is selected. Picks name the set and the + * contact's id. * @param {object} options * @param {object} options.state The layer state. * @param {object} options.services @@ -79,7 +83,8 @@ function inView(pose, point) { * @param {string} options.logLabel Console prefix, e.g. `Data:Flights`. * @param {string} options.setPrefix The draw sets' id prefix, e.g. `flights`. * @param {object} options.policy The layer's model budgets, radii, pixel - * bounds, heading offset and fleet tick interval. + * bounds, heading offset, fleet tick interval and tracked-model load + * budget. * @param {(klass: string) => object} options.modelSpec The class's GLB, scale, * geometry and tint blend; `headingOffsetDeg` overrides the policy's. * @param {(icao24: string) => object} options.modelColor Model tint @@ -161,11 +166,32 @@ export function createAircraftModels({ const offs = [ fleet.on('ready', (id) => { const record = state._models.get(id); - if (record) record.ready = true; + if (!record) return; + record.ready = true; + // Loaded after all (a renderer may retry on its own): no retry due. + record.failedAt = 0; + }), + fleet.on('loadFailed', (id) => { + const record = state._models.get(id); + if (record) record.failedAt = Date.now(); }), tracked.on('ready', (id) => { - if (id === state._trackedIcao && state._trackedModel) - state._trackedModel.ready = true; + if (id !== state._trackedIcao || !state._trackedModel) return; + state._trackedModel.ready = true; + // Loaded after all (a renderer may retry on its own): kept. + state._trackedModel.failedAt = 0; + // A good load retires this selection's failure budget: a contact + // that recovers after a transient blip is not one attempt from + // giving up. + state._trackedModelFailIcao = null; + state._trackedModelFailCount = 0; + state._trackedModelRetryAtMs = 0; + }), + tracked.on('loadFailed', (id, message) => { + const record = state._trackedModel; + if (id !== state._trackedIcao || !record || record.id !== id) return; + record.failedAt = Date.now(); + _noteTrackedModelLoadFailure(record.url, message); }), ]; state._modelSets = { fleet, tracked, offs }; @@ -351,11 +377,7 @@ export function createAircraftModels({ if (!set) return; const p = record.position; const t = record.tint ?? WHITE; - // A model still loading is rewritten now and then, for the renderer's retry. - const loading = record.ready - ? '' - : Math.floor(Date.now() / UNREADY_REWRITE_MS); - const key = `${record.url}|${p.x},${p.y},${p.z}|${record.heading}|${record.scale}|${record.minPixelSize}|${t[0]},${t[1]},${t[2]},${t[3]}|${state._irBoost === true}|${spec.blendAmount}|${record.show}|${loading}`; + const key = `${record.url}|${p.x},${p.y},${p.z}|${record.heading}|${record.scale}|${record.minPixelSize}|${t[0]},${t[1]},${t[2]},${t[3]}|${state._irBoost === true}|${spec.blendAmount}|${record.show}`; if (key === record.sent) return; record.sent = key; const item = _itemOf(id, record, spec); @@ -363,6 +385,23 @@ export function createAircraftModels({ else set.upsert([item]); } + /** A fleet model whose load failed, removed from its set once + * `FLEET_MODEL_RETRY_MS` has passed; the write that follows adds it + * again, and the set loads it again. */ + function _retryFailedFleetModel(set, icao24, record) { + if ( + !set || + !record.failedAt || + Date.now() - record.failedAt < FLEET_MODEL_RETRY_MS + ) + return; + record.failedAt = 0; + record.sent = null; + // A fresh load: not ready until the set says so again. + record.ready = false; + set.remove([icao24]); + } + /** Atomically hand one fleet contact from its icon to a safely placed, * ready 3D model. Missing/loading models and unresolved terrain always leave * the icon owning the visual, so no render frame can hide both. @@ -386,6 +425,7 @@ export function createAircraftModels({ const klass = state.records.data.get(icao24)?.klass; const spec = _modelSpec(klass); const set = state._modelSets?.fleet ?? null; + _retryFailedFleetModel(set, icao24, record); const displayPos = _modelDisplayPosition(icao24, pos); if (!displayPos) { showModel(record, false); // no ground evidence → nothing safe to place a depth-tested model at @@ -587,6 +627,33 @@ export function createAircraftModels({ icons.setShown(icao24, true); } + /** Whether the driver may load the tracked model again: an untried + * selection, or one under its failure budget past its backoff. */ + function _trackedModelLoadAllowed(nowMs = Date.now()) { + if (state._trackedModelFailIcao !== state._trackedIcao) return true; + if (state._trackedModelFailCount >= policy.TRACKED_MODEL_MAX_LOAD_FAILS) + return false; + return nowMs >= state._trackedModelRetryAtMs; + } + + /** Count a failed tracked-model load against the selection's budget and + * arm the backoff, or the give-up latch. */ + function _noteTrackedModelLoadFailure(url, message) { + if (state._trackedModelFailIcao !== state._trackedIcao) { + state._trackedModelFailIcao = state._trackedIcao; + state._trackedModelFailCount = 0; + } + state._trackedModelFailCount += 1; + state._trackedModelRetryAtMs = + Date.now() + policy.TRACKED_MODEL_RETRY_BACKOFF_MS; + if (state._trackedModelFailCount >= policy.TRACKED_MODEL_MAX_LOAD_FAILS) + console.warn( + `[${logLabel}] tracked 3D model gave up after ${state._trackedModelFailCount} failed loads of ${url}; ` + + 'this contact stays 2D until another is selected', + message, + ); + } + /** Drop the standalone tracked-aircraft model. */ function _releaseTrackedModel() { @@ -615,6 +682,9 @@ export function createAircraftModels({ * in, can never stall or freeze the centering (the old model-graphic-on-entity failure mode). */ function _updateTrackedModel() { + // A failed load is let go (the icon carries the contact); the budget + // decides when, if ever, it is loaded again. + if (state._trackedModel?.failedAt) _releaseTrackedModel(); const active = state._trackedIcao && parts.tracking._trackedModelRegimeActive() && @@ -640,6 +710,7 @@ export function createAircraftModels({ if (state._trackedModel && state._trackedModel.id !== icao24) _releaseTrackedModel(); if (!state._trackedModel) { + if (!_trackedModelLoadAllowed()) return; // the icon carries it const record = createModelRecord({ specKey: _specKeyFor(klass), // class-change sync compares against this bellyM: spec.bellyM, diff --git a/src/data/aircraftModelLayer.test.mjs b/src/data/aircraftModelLayer.test.mjs index 6d0822ec1..82a90fda2 100644 --- a/src/data/aircraftModelLayer.test.mjs +++ b/src/data/aircraftModelLayer.test.mjs @@ -19,6 +19,8 @@ const POLICY = { TRACKED_MODEL_MAX_PX: 600, MODEL_HEADING_OFFSET_DEG: 0, FLEET_DR_INTERVAL_MS: 80, + TRACKED_MODEL_MAX_LOAD_FAILS: 3, + TRACKED_MODEL_RETRY_BACKOFF_MS: 1500, }; const SPEC = { @@ -247,7 +249,7 @@ test('a failed fleet write leaves the icons in charge and is sent again', () => assert.equal(f.shown.get('a1'), false); }); -test('a model that has not loaded is written again for the renderer to retry', () => { +test('a fleet model whose load failed is loaded again after a wait, not before', () => { const positions = new Map([['a1', near(1)]]); const f = fleetFixture(positions); const realNow = Date.now; @@ -256,18 +258,39 @@ test('a model that has not loaded is written again for the renderer to retry', ( try { f.tick(); const writes = f.fleet().writes; + clock += 60_000; f.tick(); assert.equal( f.fleet().writes, writes, - 'an unchanged loading model is not rewritten every tick', + 'a model still loading is not rewritten, however long it takes', ); - clock += 5_000; + f.draw.loadFailed(f.fleetId, 'a1'); + f.removes.length = 0; + clock += 4_999; f.tick(); + assert.deepEqual(f.removes, [], 'not before the wait'); + assert.equal(f.shown.get('a1'), true, 'the icon carries the contact'); + clock += 1; + f.tick(); + assert.deepEqual(f.removes, [['a1']], 'removed once the wait is over'); + assert.ok(f.fleet().items.has('a1'), 'and added again in the same tick'); + assert.equal(f.state._models.get('a1').failedAt, 0); + assert.equal(f.state._models.get('a1').ready, false, 'a fresh load'); + f.removes.length = 0; + clock += 60_000; + f.tick(); + assert.deepEqual(f.removes, [], 'tried again only after another failure'); + // A renderer's own retry that loads before the layer's: nothing is due. + f.draw.loadFailed(f.fleetId, 'a1'); + f.draw.ready(f.fleetId, 'a1'); + clock += 60_000; + f.tick(); + assert.deepEqual(f.removes, [], 'a model that loaded is not tried again'); assert.equal( - f.fleet().writes, - writes + 1, - 'but it is rewritten every few seconds', + f.shown.get('a1'), + false, + 'the model takes over once it loads', ); } finally { Date.now = realNow; diff --git a/src/data/modelRecord.js b/src/data/modelRecord.js index 92b1c3ddb..d3e8d5d85 100644 --- a/src/data/modelRecord.js +++ b/src/data/modelRecord.js @@ -5,7 +5,8 @@ * layer reads what it pushed (and what the set told it) back from itself. * * Write `show` and the placement with {@link showModel} and - * {@link placeModel}; the set's `ready` event sets `ready`. The placement is + * {@link placeModel}; the set's `ready` event sets `ready`, and its + * `loadFailed` event `failedAt`. The placement is * kept as the column-major frame the model is posed in, the same frame a * renderer builds from the item's position and heading, so anchors on the * model can be read from it. @@ -19,6 +20,8 @@ import { eastNorthUp } from '../geo/frames.js'; * @property {string|null} url The model asset the layer sends. * @property {boolean} ready Whether the set reported the model loaded and * posed (`ready`). + * @property {number} failedAt When (epoch ms) the set last reported the + * model's load failed (`loadFailed`); 0 when it has not. * @property {boolean} show Whether the layer last showed the model. * @property {boolean} placed Whether the layer has placed it yet. * @property {Float64Array} matrix Where the layer last placed it: the @@ -55,6 +58,7 @@ export function createModelRecord({ id, url, ready: false, + failedAt: 0, show: false, placed: false, matrix, diff --git a/src/data/trackedModelRegime.test.mjs b/src/data/trackedModelRegime.test.mjs index b96abbb36..c903218eb 100644 --- a/src/data/trackedModelRegime.test.mjs +++ b/src/data/trackedModelRegime.test.mjs @@ -345,6 +345,84 @@ for (const fixture of LAYERS) { } }); + test(`${fixture.name}: a tracked model that fails to load is retried within a per-selection budget`, () => { + clearTr3bRegistry(); + fixture.layer.stopTracking(); + fixture.layer.setParams({ models3d: false }); + const realNow = Date.now; + const realWarn = console.warn; + const warnings = []; + let now = 7_000_000; + Date.now = () => now; + console.warn = (...args) => warnings.push(args.join(' ')); + const viewer = viewerAtHeight(30_000); + const icao24 = fixture.name === 'flights' ? 'a0f401' : 'b0f401'; + try { + fixture.seed({ viewer, icao24 }); + fixture.driveTrackedModel(); + let tracked = modelSet(fixture, viewer, 'tracked'); + const fail = () => viewer.draw.loadFailed(tracked.spec.id, icao24, '404'); + assert.ok(tracked.items.has(icao24), 'the tracked model loads'); + for (let attempt = 1; attempt <= 3; attempt++) { + fail(); + fixture.driveTrackedModel(); + assert.equal(tracked.items.has(icao24), false, `failure ${attempt}: let go`); + assert.equal(fixture.trackedModel(), null); + assert.equal(fixture.trackedBillboardColor()[3], 1, 'the icon carries the contact'); + now += 1499; + fixture.driveTrackedModel(); + assert.equal(tracked.items.has(icao24), false, 'not before the backoff'); + now += 1; + fixture.driveTrackedModel(); + assert.equal(tracked.items.has(icao24), attempt < 3, + attempt < 3 ? 'loaded again after the backoff' : 'given up after the third failure'); + } + assert.equal(warnings.length, 1, 'giving up is said once'); + now += 60_000; + fixture.driveTrackedModel(); + assert.equal(tracked.items.has(icao24), false, 'the selection stays 2D'); + + // A new selection of the same contact starts with a full budget. + fixture.layer.stopTracking(); + fixture.seed({ viewer, icao24 }); + fixture.driveTrackedModel(); + tracked = modelSet(fixture, viewer, 'tracked'); + assert.ok(tracked.items.has(icao24), 'reselected, it loads again'); + // A failure the renderer recovers from before the driver runs keeps it. + const recovered = fixture.trackedModel(); + fail(); + viewer.draw.ready(tracked.spec.id, icao24); + fixture.driveTrackedModel(); + assert.equal(fixture.trackedModel(), recovered, 'a model that loaded after all is kept'); + assert.ok(tracked.items.has(icao24)); + fixture.layer.stopTracking(); + fixture.seed({ viewer, icao24 }); + fixture.driveTrackedModel(); + tracked = modelSet(fixture, viewer, 'tracked'); + // And a good load retires the failures counted so far. + fail(); + fixture.driveTrackedModel(); + now += 1500; + fixture.driveTrackedModel(); + viewer.draw.ready(tracked.spec.id, icao24); + fixture.driveTrackedModel(); + assert.equal(fixture.trackedModel()?.ready, true); + fail(); + fixture.driveTrackedModel(); + now += 1500; + fixture.driveTrackedModel(); + fail(); + fixture.driveTrackedModel(); + now += 1500; + fixture.driveTrackedModel(); + assert.ok(tracked.items.has(icao24), 'two failures after a good load are under the budget'); + } finally { + Date.now = realNow; + console.warn = realWarn; + fixture.layer.stopTracking(); + } + }); + test(`${fixture.name}: the IR boost restyles a drawn model in place, flat white and unlit`, () => { clearTr3bRegistry(); fixture.layer.stopTracking(); diff --git a/src/layers/flights/policy.js b/src/layers/flights/policy.js index 6cc04197e..dec6425cd 100644 --- a/src/layers/flights/policy.js +++ b/src/layers/flights/policy.js @@ -290,6 +290,19 @@ export const ENRICH_AMBIENT_PER_SWEEP = 150; export const DR_CORRECTION_MS = 900; +/** Bounded loading for the tracked model. Its driver runs every frame, so a + * missing or corrupt GLB, or a dead network, would otherwise ask for the + * model again for as long as the contact stays selected. Failures (the + * model set's `loadFailed`) are counted PER SELECTION: a short backoff + * absorbs a transient blip, then the layer stops asking until the operator + * selects something else. The icon is the visual throughout (the handoff + * only fades it once a model actually renders), so a latched failure + * degrades to exactly the pre-3D presentation. */ + +export const TRACKED_MODEL_MAX_LOAD_FAILS = 3; + +export const TRACKED_MODEL_RETRY_BACKOFF_MS = 1500; + /** @constant {number} Cap on NEW cells the display corridors may add to one * poll's warm/sample batch — a view full of ground traffic must not balloon * it. Cells the poll already collected are free (deduped before budgeting). */ diff --git a/src/layers/flights/state.js b/src/layers/flights/state.js index a9838f03c..37b51e28b 100644 --- a/src/layers/flights/state.js +++ b/src/layers/flights/state.js @@ -333,6 +333,15 @@ export function createFlightState({ source, services }) { flightState._trackedZoomLatchIcao = null; + /** The tracked-model load-failure budget: the selection it counts for, + * its failures, and when it may load again (`TRACKED_MODEL_*`). */ + + flightState._trackedModelFailIcao = null; + + flightState._trackedModelFailCount = 0; + + flightState._trackedModelRetryAtMs = 0; + /** @type {Map { } }); +test('a failed model load fires loadFailed once, after the frame, with why', async () => { + const { loads, restore } = fakeModelLoads(); + try { + const scene = fakeScene(); + const part = createCesiumDraw({ + scene, + report: (error) => assert.fail(error), + }); + const set = part.port.models({ id: 'm' }); + const failed = []; + set.on('loadFailed', (id, message) => failed.push([id, message])); + const item = (id, url) => ({ + id, + pos: { lon: 0, lat: 0 }, + url, + orientation: { heading: 0, pitch: 0, roll: 0 }, + }); + // A load that rejects (the glTF did not fetch). + set.set([item('a', 'a.glb'), item('b', 'b.glb')]); + loads[0].reject(new Error('404 for a.glb')); + await settle(); + assert.deepEqual(failed, [['a', '404 for a.glb']]); + // One that fails in its update: told after that update, not inside it. + loads[1].resolve(); + await settle(); + loads[1].model.errorEvent.raiseEvent(new Error('bad texture')); + assert.equal(failed.length, 1, 'not inside the model update'); + await settle(); + assert.deepEqual(failed[1], ['b', 'bad texture']); + // A listener may change the set: removing and adding again loads at once. + set.remove(['a']); + set.upsert([item('a', 'a.glb')]); + assert.equal(loads.length, 3, 'added again, loaded again'); + // A load superseded before it fails is not told. + set.upsert([item('a', 'c.glb')]); + loads[2].reject(new Error('late')); + await settle(); + assert.equal(failed.length, 2, 'a superseded load does not fire'); + // Nor one whose item went before the failure was told. + loads[3].reject('plain reason'); + set.remove(['a']); + await settle(); + assert.equal(failed.length, 2, 'an item gone does not fire'); + set.upsert([item('d', 'd.glb')]); + loads[4].reject({}); + await settle(); + assert.deepEqual(failed[2], ['d', 'the model did not load']); + set.dispose(); + } finally { + restore(); + } +}); + test('a failed model load is tried again on a later update, after a wait', async () => { const { loads, restore } = fakeModelLoads(); const realNow = Date.now; diff --git a/src/render/cesium/drawModels.js b/src/render/cesium/drawModels.js index f61e017e2..06044ae12 100644 --- a/src/render/cesium/drawModels.js +++ b/src/render/cesium/drawModels.js @@ -15,8 +15,9 @@ * measures `minPixelSize`), `scaleByDistance`, `fadeByDistance` (the tint's * alpha) and the set's `horizonCull`. * - * A failed load is tried again when its item is next updated, once - * `MODEL_RETRY_MS` has passed. + * A failed load fires `loadFailed` (after the frame Cesium reported it in, + * so a listener may change the set), and is tried again when its item is + * next updated, once `MODEL_RETRY_MS` has passed. * * `shading: 'thermal'` draws the model unlit and white-hot (its texture * left out), then tinted as asked: a hot target, as the thermal views draw @@ -116,6 +117,13 @@ const tintKey = (tint) => ? tint : tint.join(','); +/** Why a load failed, as `loadFailed` reports it. */ +function failureMessage(error) { + if (error instanceof Error && error.message) return error.message; + const text = error === undefined || error === null ? '' : String(error); + return text && text !== '[object Object]' ? text : 'the model did not load'; +} + /** Whether an item needs the per-frame pass. */ const needsFrame = (item, spec) => item.maxPixelSize > 0 || @@ -183,8 +191,11 @@ export function createModelSets({ // A load counts until it is ready, fails or is superseded; once. host.loading += 1; let settled = false; + const item = entry.item; + const current = () => + entry.token === token && record.host === host && !host.isDestroyed(); const settleLoad = () => settle(false); - const settle = (failed) => { + const settle = (failed, error) => { if (settled) return; settled = true; if (entry.settleLoad === settleLoad) entry.settleLoad = null; @@ -193,13 +204,17 @@ export function createModelSets({ entry.failed = true; entry.failedAt = Date.now(); host.failed += 1; + // Told once Cesium is done with the frame it raised this in; not + // when the item has moved on to another load meanwhile. + const message = failureMessage(error); + queueMicrotask(() => { + if (current() && entry.failed) + record.listeners.loadFailed.fire(item.id, message); + }); } requestRender(); }; entry.settleLoad = settleLoad; - const item = entry.item; - const current = () => - entry.token === token && record.host === host && !host.isDestroyed(); Cesium.Model.fromGltfAsync({ url: item.url, modelMatrix: matrixOf(entry, new Cesium.Matrix4()), @@ -241,7 +256,7 @@ export function createModelSets({ }); // A failed load is let go (Cesium would keep drawing frames for // it); the failure stays for `whenSettled` until the item changes. - model.errorEvent.addEventListener(() => { + model.errorEvent.addEventListener((error) => { if (current() && entry.next === model) { entry.next = null; // Cesium raises this inside the model's update: removing it @@ -251,11 +266,11 @@ export function createModelSets({ host.remove(model); }); } - settle(true); + settle(true, error); }); requestRender(); }, - () => settle(true), + (error) => settle(true, error), ); } diff --git a/src/render/cesium/harness.js b/src/render/cesium/harness.js index b93109556..48865269f 100644 --- a/src/render/cesium/harness.js +++ b/src/render/cesium/harness.js @@ -45,6 +45,7 @@ export const CESIUM_CHECKS = new Set([ 'draw.lines.segments', 'draw.ids', 'draw.models', + 'draw.models.loadFailed', 'draw.models.tint', 'draw.models.update', 'draw.motion', @@ -113,11 +114,16 @@ function nextFrame() { } /** - * @param {{name?: string, model?: string}} [options] `model`: a glTF URL - * for the model checks. + * @param {{name?: string, model?: string, missingModel?: string}} [options] + * `model`: a glTF URL for the model checks; `missingModel`: one that + * fails to load, for the failure check. * @returns {import('../conformance/index.js').ConformanceHarness} */ -export function createCesiumHarness({ name = 'cesium', model } = {}) { +export function createCesiumHarness({ + name = 'cesium', + model, + missingModel, +} = {}) { return { name, async create({ viewport, capabilities }) { @@ -157,6 +163,6 @@ export function createCesiumHarness({ name = 'cesium', model } = {}) { toEcef, tolerance: DEFAULT_TOLERANCE, flightPaths: 'endpoints', - ...(model ? { assets: { model } } : {}), + ...(model ? { assets: { model, missingModel } } : {}), }; } diff --git a/src/render/conformance/checks/ports.js b/src/render/conformance/checks/ports.js index 17ae67091..4aeb08b22 100644 --- a/src/render/conformance/checks/ports.js +++ b/src/render/conformance/checks/ports.js @@ -1754,6 +1754,60 @@ export function portChecks() { }, { capability: 'models' }, ), + check( + 'draw.models.loadFailed', + 'a model set says when a model fails to load, and loads it when added again', + async (h, r) => { + if (!h.assets?.model || !h.assets?.missingModel) + return { skip: 'no missing model asset in this harness' }; + const set = r.draw.models({ id: 'conf:models.loadFailed' }); + const ready = []; + const failed = []; + set.on('ready', (id) => ready.push(id)); + set.on('loadFailed', (id, message) => failed.push([id, message])); + const model = (id, url) => ({ + id, + pos: { ...AUSTIN, height: 0 }, + url, + orientation: { heading: 0, pitch: 0, roll: 0 }, + }); + const until = async (done) => { + for (let i = 0; i < 600 && !done(); i++) await drawn(h, r, 1); + }; + set.set([ + model('bad', h.assets.missingModel), + model('good', h.assets.model), + ]); + await until(() => failed.length >= 1 && ready.length >= 1); + deepEqual(ready, ['good'], 'the good one is ready'); + deepEqual( + failed.map(([id]) => id), + ['bad'], + 'the missing one failed', + ); + ok( + typeof failed[0]?.[1] === 'string' && failed[0][1].length > 0, + 'with a message', + ); + equal(set.size(), 2, 'the failed item stays in the set'); + // Removed and added again, it is tried at once, and fails again. + set.remove(['bad']); + set.upsert([model('bad', h.assets.missingModel)]); + await until(() => failed.length >= 2); + deepEqual( + failed.map(([id]) => id), + ['bad', 'bad'], + 'tried again when added again', + ); + // Pointed at a url that loads, it is ready. + set.upsert([model('bad', h.assets.model)]); + await until(() => ready.length >= 2); + deepEqual(ready, ['good', 'bad'], 'a good url loads'); + equal(failed.length, 2, 'no failure for a good url'); + set.dispose(); + }, + { capability: 'models' }, + ), check( 'draw.models.update', 'a model moves, turns and restyles in place; only a new url loads it again', diff --git a/src/render/contract/contract.test.mjs b/src/render/contract/contract.test.mjs index 167646543..fc887c78b 100644 --- a/src/render/contract/contract.test.mjs +++ b/src/render/contract/contract.test.mjs @@ -143,6 +143,37 @@ test('the capability and frame-step lists are the types’ own', () => { ); }); +test('a draw set’s events: ready with the id, loadFailed with the id and why', () => { + const on = checker + .getTypeAtLocation(declared('DrawSet').name) + .getProperty('on'); + const signatures = checker + .getTypeOfSymbolAtLocation(on, declared('DrawSet')) + .getCallSignatures(); + const events = Object.fromEntries( + signatures.map((signature) => { + const [event, cb] = signature.getParameters(); + const callback = checker + .getTypeOfSymbolAtLocation(cb, cb.valueDeclaration) + .getCallSignatures()[0]; + return [ + checker.getTypeOfSymbolAtLocation(event, event.valueDeclaration).value, + callback + .getParameters() + .map((p) => + checker.typeToString( + checker.getTypeOfSymbolAtLocation(p, p.valueDeclaration), + ), + ), + ]; + }), + ); + assert.deepEqual(events, { + ready: ['string'], + loadFailed: ['string', 'string'], + }); +}); + test('the shape check names what is missing and what a capability does not allow', () => { assert.deepEqual(checkRendererShape(null), ['renderer is not an object']); assert.deepEqual(checkRendererShape({}), [ diff --git a/src/render/contract/draw.d.ts b/src/render/contract/draw.d.ts index 4af39a985..6700214ba 100644 --- a/src/render/contract/draw.d.ts +++ b/src/render/contract/draw.d.ts @@ -507,6 +507,15 @@ export interface DrawSet { show: boolean; /** `models`: a model has loaded and is posed. */ on(event: 'ready', cb: (id: string) => void): Off; + /** + * `models`: a model's url failed to load (`message` says why), once per + * failed load. The item stays in the set, drawing what it drew before (a + * new item draws nothing); a renderer may try the url again when the item + * is next updated. Removing the item and adding it again tries at once. + * Optional: where the renderer cannot tell a failure it may never fire it, so + * a fallback must not wait on it. + */ + on(event: 'loadFailed', cb: (id: string, message: string) => void): Off; dispose(): void; } diff --git a/src/render/stub/harness.js b/src/render/stub/harness.js index 7a102bdab..462090044 100644 --- a/src/render/stub/harness.js +++ b/src/render/stub/harness.js @@ -4,7 +4,7 @@ * the Node test and the browser page alike. */ import { DEFAULT_TOLERANCE } from '../conformance/index.js'; -import { createStubRenderer } from './index.js'; +import { createStubRenderer, STUB_FAILING_MODEL_SCHEME } from './index.js'; import { toEcef } from './math.js'; /** @returns {import('../conformance/index.js').ConformanceHarness} */ @@ -23,7 +23,11 @@ export function createStubHarness(name = 'stub') { pointer: (r, type, x, y, extra) => r.testing.pointer(type, x, y, extra), scriptHeights: (r, fn) => r.testing.setHeights(fn), wallTime: (r) => r.testing.wallTime(), - // The stub loads nothing: any url is a model it draws. - assets: { model: 'stub:model.glb' }, + // The stub loads nothing: any url is a model it draws, but one under + // its failing scheme. + assets: { + model: 'stub:model.glb', + missingModel: `${STUB_FAILING_MODEL_SCHEME}model.glb`, + }, }; } diff --git a/src/render/stub/index.js b/src/render/stub/index.js index 7be7eed67..f83ce0005 100644 --- a/src/render/stub/index.js +++ b/src/render/stub/index.js @@ -34,6 +34,12 @@ import { const FRAME_MS = 1000 / 60; +/** + * Model urls under this scheme fail to load (`loadFailed`), so tests can + * see a failure; the stub loads nothing, and every other url is a model. + */ +export const STUB_FAILING_MODEL_SCHEME = 'stub-fail:'; + /** Every setting the stub accepts, with its descriptor. */ const KNOBS = Object.freeze([ { key: 'pixelRatio', kind: 'number', min: 0, max: 4, default: 0, cost: 1 }, @@ -314,21 +320,37 @@ export function createStubRenderer(options = {}) { items: new Map(), show: spec.show ?? true, readyListeners: [], + loadFailedListeners: [], }; sets.set(spec.id, record); log('draw', kind, [spec]); // A model is ready once per load: when it is new or its url changes, - // not when it is moved or restyled. + // not when it is moved or restyled. One under the failing scheme fails + // its load instead. + // Each load is told once: a listener that starts another load of the + // same item (or removes it) supersedes the one queued here. + const loadTokens = new Map(); const loads = (items) => kind === 'models' ? items .filter( (item) => record.items.get(String(item.id))?.url !== item.url, ) - .map((item) => String(item.id)) + .map((item) => { + const token = {}; + loadTokens.set(String(item.id), token); + return [String(item.id), token]; + }) : []; - const ready = (ids) => { - for (const id of ids) deliver(record.readyListeners, id); + const ready = (loading) => { + for (const [id, token] of loading) { + if (loadTokens.get(id) !== token || !record.items.has(id)) continue; + loadTokens.delete(id); + const url = String(record.items.get(id).url ?? ''); + if (url.startsWith(STUB_FAILING_MODEL_SCHEME)) + deliver(record.loadFailedListeners, id, `${url} does not load`); + else deliver(record.readyListeners, id); + } }; const handle = { id: spec.id, @@ -369,9 +391,15 @@ export function createStubRenderer(options = {}) { requestRender('draw'); }, on(event, cb) { - if (event !== 'ready') return () => {}; + const list = + event === 'ready' + ? record.readyListeners + : event === 'loadFailed' + ? record.loadFailedListeners + : null; + if (!list) return () => {}; const entry = { cb, live: true }; - record.readyListeners.push(entry); + list.push(entry); return () => { entry.live = false; }; diff --git a/src/render/stub/stub.test.mjs b/src/render/stub/stub.test.mjs index fc4dccf82..8f5eee824 100644 --- a/src/render/stub/stub.test.mjs +++ b/src/render/stub/stub.test.mjs @@ -74,3 +74,26 @@ test('a throwing listener with no error listener is reported and the frame goes globalThis.reportError = saved; } }); + +test('a model load is told once, even when a listener loads it again', () => { + const r = createStubRenderer({ capabilities: ['models'] }); + const set = r.draw.models({ id: 'm' }); + const told = []; + const model = (id, url) => ({ + id, + pos: { lon: 0, lat: 0 }, + url, + orientation: { heading: 0, pitch: 0, roll: 0 }, + }); + set.on('ready', (id) => told.push(`ready ${id}`)); + set.on('loadFailed', (id) => { + told.push(`failed ${id}`); + // Pointing b at another failing url is a new load, told by its upsert. + if (id === 'a') set.upsert([model('b', 'stub-fail:other.glb')]); + }); + set.set([model('a', 'stub-fail:a.glb'), model('b', 'stub-fail:b.glb')]); + assert.deepEqual(told, ['failed a', 'failed b']); + set.remove(['a']); + set.upsert([model('a', 'good.glb')]); + assert.deepEqual(told.slice(2), ['ready a']); +}); diff --git a/src/testSupport/fakeDrawPort.mjs b/src/testSupport/fakeDrawPort.mjs index 4ada5de4d..5bacf4d37 100644 --- a/src/testSupport/fakeDrawPort.mjs +++ b/src/testSupport/fakeDrawPort.mjs @@ -20,6 +20,7 @@ export function fakeDrawPort() { disposed: false, writes: 0, ready: new Set(), + loadFailed: new Set(), }; sets.set(spec.id, record); const write = (fn) => { @@ -55,9 +56,13 @@ export function fakeDrawPort() { record.show = value; }, on(event, cb) { - if (event !== 'ready') return () => {}; - record.ready.add(cb); - return () => record.ready.delete(cb); + const listeners = { + ready: record.ready, + loadFailed: record.loadFailed, + }[event]; + if (!listeners) return () => {}; + listeners.add(cb); + return () => listeners.delete(cb); }, dispose() { record.disposed = true; @@ -82,6 +87,11 @@ export function fakeDrawPort() { ready(setId, id) { for (const cb of [...(sets.get(setId)?.ready ?? [])]) cb(id); }, + /** Fire a models set's `loadFailed` for an item, as a failed load does. */ + loadFailed(setId, id, message = 'the model did not load') { + for (const cb of [...(sets.get(setId)?.loadFailed ?? [])]) + cb(id, message); + }, clampState: () => 'draped', on: () => () => {}, atlas() {},