From e72382b1aaf3e0e7d9e0145ea14d3788d5fc77e6 Mon Sep 17 00:00:00 2001 From: Sameh Khamis Date: Sat, 7 Nov 2026 01:39:03 -0800 Subject: [PATCH] Keep each drawn icon's expiry in a shared icon book, for replanning render/motion/iconBook holds the icon items a layer drew to a draw set, as the vessels' book did, and now also when each one's motion stops being what the layer would plan: put(item, {expiresAt}) records it (Infinity: planned, never due; null drops it; a restyle keeps it), and due(t) lists the ones to plan afresh. It reads a moving icon's position and course at a time through the shared evaluator, as the renderer draws it given its capabilities. An item easing its course by courseBlendMs reads its target course. This is what a layer with dead-reckoned contacts keeps on the CPU in place of the GPU set's own row expiry. The vessels' icon book is now this one. --- scripts/package-boundaries.json | 4 + src/layers/vessels/iconBook.js | 55 +----------- src/render/motion/iconBook.js | 119 ++++++++++++++++++++++++++ src/render/motion/iconBook.test.mjs | 128 ++++++++++++++++++++++++++++ 4 files changed, 255 insertions(+), 51 deletions(-) create mode 100644 src/render/motion/iconBook.js create mode 100644 src/render/motion/iconBook.test.mjs diff --git a/scripts/package-boundaries.json b/scripts/package-boundaries.json index 355eaa106..76875d614 100644 --- a/scripts/package-boundaries.json +++ b/scripts/package-boundaries.json @@ -1694,6 +1694,7 @@ "src/layers/vessels/queries.js", "src/geo/vector.js", "src/layers/vessels/rendering.js", + "src/render/motion/iconBook.js", "src/layers/vessels/iconBook.js", "src/data/entityRecords.js", "src/data/iconSetPrimitive.js", @@ -1745,6 +1746,7 @@ "src/render/creditMarkup.js", "src/render/cesium/draw.js", "src/render/cesium/gpuIcons.js", + "src/render/motion/iconMotion.js", "src/render/cesium/frame.js", "src/render/cesium/follow.js", "src/render/cesium/cameraInput.js", @@ -3479,6 +3481,7 @@ "src/layers/vessels/policy.js", "src/layers/vessels/queries.js", "src/layers/vessels/rendering.js", + "src/render/motion/iconBook.js", "src/layers/vessels/iconBook.js", "src/layers/vessels/selection.js", "src/layers/vessels/state.js", @@ -4426,6 +4429,7 @@ "src/layers/vessels/policy.js", "src/layers/vessels/queries.js", "src/layers/vessels/rendering.js", + "src/render/motion/iconBook.js", "src/layers/vessels/iconBook.js", "src/layers/vessels/selection.js", "src/layers/vessels/state.js", diff --git a/src/layers/vessels/iconBook.js b/src/layers/vessels/iconBook.js index 16e089308..7068c57ff 100644 --- a/src/layers/vessels/iconBook.js +++ b/src/layers/vessels/iconBook.js @@ -1,53 +1,6 @@ /** - * The vessel icons the layer draws, as it last drew them: each icon item by - * its row id, and the renderer draw set they go to. The layer reads its own - * icons back from here (focus emphasis, ownership of a pick), never from the - * renderer. + * The vessel icons the layer draws, as it last drew them: the shared icon + * book (`render/motion/iconBook.js`). The layer reads its own icons back from + * there (focus emphasis, ownership of a pick), never from the renderer. */ - -/** - * @param {import('../../render/contract/draw').DrawSet|null} [drawSet] - * Where the icons are drawn; none keeps them only here (tests). - */ -export function createVesselIconBook(drawSet = null) { - const items = new Map(); - const book = { - /** The draw set's id, or null. */ - setId: drawSet?.id ?? null, - get show() { - return drawSet ? drawSet.show : true; - }, - set show(value) { - if (drawSet) drawSet.show = value; - }, - /** How many icons are drawn. */ - get size() { - return items.size; - }, - /** The drawn row ids, in the order first drawn. */ - ids: () => [...items.keys()], - /** Whether a row id is drawn. */ - has: (id) => items.has(id), - /** The item drawn under a row id, or undefined. */ - item: (id) => items.get(id), - /** Draw an item (anew, or as it now is). */ - put(item) { - items.set(item.id, item); - drawSet?.upsert([item]); - }, - remove(id) { - if (items.delete(id)) drawSet?.remove([id]); - }, - /** A row's focus emphasis, 1 when not de-emphasised. */ - focus: (id) => items.get(id)?.focus ?? 1, - setFocus(id, factor) { - const item = items.get(id); - if (item) book.put({ ...item, focus: factor }); - }, - dispose() { - items.clear(); - drawSet?.dispose(); - }, - }; - return book; -} +export { createIconBook as createVesselIconBook } from '../../render/motion/iconBook.js'; diff --git a/src/render/motion/iconBook.js b/src/render/motion/iconBook.js new file mode 100644 index 000000000..4621564bd --- /dev/null +++ b/src/render/motion/iconBook.js @@ -0,0 +1,119 @@ +/** + * @module render/motion/iconBook + * @description The icons a layer draws, as it last drew them: each icon item + * by its id, until when its motion holds, and the renderer draw set they go + * to. A layer reads its own icons back from here (where a moving one is now + * and its course, its focus, whether a pick is its own), never from the + * renderer, and replans the ones whose motion ran out. + * + * Positions and courses come from the shared evaluator (`iconMotion.js`), on + * the set's motion clock: pass the same epoch ms the set draws at (wall time + * less its `delayMs` for a live clock, the frame port's time for a scene + * clock). An item's `courseBlendMs` is not modelled: an item easing its + * course by it reads its target course (give it a `courseGlide` to read the + * eased one). + */ +import { iconCourse, iconPosition } from './iconMotion.js'; + +/** + * @param {import('../contract/draw').DrawSet|null} [drawSet] Where + * the icons are drawn; none keeps them only here (tests). + * @param {{capabilities?: ReadonlySet|null}} [options] The + * renderer's capabilities (`Renderer.capabilities`); without + * `motionSegments` or `courseGlide` an icon is read where, and with the + * course, it is drawn. None given reads both as drawn. + */ +export function createIconBook(drawSet = null, { capabilities = null } = {}) { + const motionSegments = capabilities?.has('motionSegments') ?? true; + const courseGlide = capabilities?.has('courseGlide') ?? true; + const items = new Map(); + // Until when (epoch ms) each item's motion holds, for those given one. + const expiries = new Map(); + + /** An item as the renderer draws it. */ + function asDrawn(item) { + if (motionSegments && courseGlide) return item; + const { motion, courseGlide: glide, ...rest } = item; + return { + ...rest, + ...(motionSegments ? { motion } : null), + ...(courseGlide ? { courseGlide: glide } : null), + }; + } + + const book = { + /** The draw set's id, or null. */ + setId: drawSet?.id ?? null, + get show() { + return drawSet ? drawSet.show : true; + }, + set show(value) { + if (drawSet) drawSet.show = value; + }, + /** How many icons are drawn. */ + get size() { + return items.size; + }, + /** The drawn ids, in the order first drawn. */ + ids: () => [...items.keys()], + /** Whether an id is drawn. */ + has: (id) => items.has(id), + /** The item drawn under an id, or undefined. */ + item: (id) => items.get(id), + /** + * Draw an item (anew, or as it now is). `expiresAt` (epoch ms on the + * motion clock) is when its motion stops being what the layer would + * plan, for `due` (`Infinity`: planned, never due); `null` drops it, and + * omitted (a restyle) keeps what the item had. + */ + put(item, { expiresAt } = {}) { + if ( + expiresAt !== undefined && + expiresAt !== null && + (typeof expiresAt !== 'number' || Number.isNaN(expiresAt)) + ) + throw new TypeError(`expiresAt must be epoch ms, not ${expiresAt}`); + items.set(item.id, item); + if (expiresAt === null) expiries.delete(item.id); + else if (expiresAt !== undefined) expiries.set(item.id, expiresAt); + drawSet?.upsert([item]); + }, + remove(id) { + expiries.delete(id); + if (items.delete(id)) drawSet?.remove([id]); + }, + /** + * When an id's motion runs out (epoch ms; `Infinity`: never), or + * undefined while it was never given one (not planned). + */ + expiresAt: (id) => expiries.get(id), + /** The ids whose motion ran out by `t` (epoch ms), to plan afresh. */ + due(t) { + const ids = []; + for (const [id, at] of expiries) if (at <= t) ids.push(id); + return ids; + }, + /** Where an id's icon is drawn at `t` (epoch ms), ECEF, or null. */ + position(id, t) { + const item = items.get(id); + return item?.pos ? iconPosition(asDrawn(item), t) : null; + }, + /** The course an id's icon is drawn with at `t`, or null. */ + course(id, t) { + const item = items.get(id); + return item ? iconCourse(asDrawn(item), t) : null; + }, + /** An icon's focus emphasis, 1 when not de-emphasised. */ + focus: (id) => items.get(id)?.focus ?? 1, + setFocus(id, factor) { + const item = items.get(id); + if (item) book.put({ ...item, focus: factor }); + }, + dispose() { + items.clear(); + expiries.clear(); + drawSet?.dispose(); + }, + }; + return book; +} diff --git a/src/render/motion/iconBook.test.mjs b/src/render/motion/iconBook.test.mjs new file mode 100644 index 000000000..27d5ad205 --- /dev/null +++ b/src/render/motion/iconBook.test.mjs @@ -0,0 +1,128 @@ +import assert from 'node:assert/strict'; +import test from 'node:test'; +import { fromDegrees } from '../../geo/ellipsoid.js'; +import { createIconBook } from './iconBook.js'; +import { iconCourse, iconPosition } from './iconMotion.js'; + +const A = fromDegrees(4.1, 51.95, 10); +const B = { x: A.x + 1000, y: A.y, z: A.z }; +const T0 = Date.UTC(2026, 10, 7); +const mover = (extra = {}) => ({ + id: 'a', + pos: A, + image: 'a.png', + size: [16, 16], + motion: { kind: 'lerp', from: A, to: B, t0: T0, t1: T0 + 10_000 }, + courseGlide: { fromCourseDeg: 0, t0: T0, rateDps: 10 }, + ...extra, +}); + +/** A draw set that records what it is sent. */ +function recordingSet() { + const calls = []; + return { + calls, + id: 'set:1', + show: true, + upsert: (items) => calls.push(['upsert', items.map((i) => i.id)]), + remove: (ids) => calls.push(['remove', ids]), + dispose: () => calls.push(['dispose']), + }; +} + +test('the book draws what it is given and reads it back as drawn', () => { + const set = recordingSet(); + const book = createIconBook(set); + const item = mover(); + book.put(item); + assert.deepEqual(set.calls, [['upsert', ['a']]]); + assert.equal(book.setId, 'set:1'); + assert.equal(book.item('a'), item); + assert.deepEqual( + book.position('a', T0 + 5000), + iconPosition(item, T0 + 5000), + ); + assert.equal(book.course('a', T0 + 3000), iconCourse(item, T0 + 3000)); + assert.equal(book.position('nobody', T0), null); + assert.equal(book.course('nobody', T0), null); + book.remove('a'); + book.remove('a'); + assert.deepEqual(set.calls.at(-1), ['remove', ['a']]); + assert.equal(set.calls.length, 2, 'removed once'); + book.dispose(); + assert.deepEqual(set.calls.at(-1), ['dispose']); +}); + +test('an item put with an expiry comes due when its motion runs out', () => { + const book = createIconBook(); + book.put(mover(), { expiresAt: T0 + 10_000 }); + book.put(mover({ id: 'b' })); + assert.deepEqual(book.due(T0 + 9999), []); + assert.deepEqual(book.due(T0 + 10_000), ['a']); + assert.equal(book.expiresAt('a'), T0 + 10_000); + assert.equal(book.expiresAt('b'), undefined, 'never due'); + // A focus change keeps the expiry; replanning sets a new one. + book.setFocus('a', 0.5); + assert.equal(book.expiresAt('a'), T0 + 10_000); + book.put(mover(), { expiresAt: T0 + 20_000 }); + assert.deepEqual(book.due(T0 + 10_000), []); + book.put(mover({ alpha: 0.5 })); + assert.equal(book.expiresAt('a'), T0 + 20_000, 'a restyle keeps it'); + book.put(mover(), { expiresAt: Infinity }); + assert.deepEqual(book.due(Number.MAX_VALUE), [], 'planned, never due'); + book.put(mover(), { expiresAt: null }); + assert.equal(book.expiresAt('a'), undefined, 'null drops it'); + assert.throws(() => book.put(mover(), { expiresAt: NaN }), TypeError); + assert.throws(() => book.put(mover(), { expiresAt: '5' }), TypeError); + book.put(mover(), { expiresAt: T0 }); + book.remove('a'); + assert.deepEqual(book.due(Infinity), [], 'gone with its item'); +}); + +test('without the renderer’s motion capabilities, icons read where they are drawn', () => { + const still = createIconBook(null, { capabilities: new Set() }); + still.put(mover({ course: 45 })); + assert.deepEqual(still.position('a', T0 + 5000), A); + assert.equal(still.course('a', T0 + 5000), 45); + const noGlide = createIconBook(null, { + capabilities: new Set(['motionSegments']), + }); + noGlide.put(mover({ motion: { kind: 'hold', courseDeg: 90 } })); + assert.equal(noGlide.course('a', T0 + 1000), 90, 'on course at once'); + // Glides but does not move: the glide eases onto the item's own course. + const noMotion = createIconBook(null, { + capabilities: new Set(['courseGlide']), + }); + noMotion.put(mover({ course: 60 })); + assert.deepEqual(noMotion.position('a', T0 + 5000), A); + assert.equal(noMotion.course('a', T0 + 3000), 30, 'gliding onto 60'); + assert.equal(noMotion.course('a', T0 + 9000), 60); +}); + +test('focus is read and written per icon', () => { + const book = createIconBook(); + book.put(mover()); + assert.equal(book.focus('a'), 1); + book.setFocus('a', 0.25); + assert.equal(book.focus('a'), 0.25); + assert.equal(book.item('a').focus, 0.25); + book.setFocus('nobody', 0.5); + assert.equal(book.has('nobody'), false); + assert.equal(book.expiresAt('a'), undefined, 'focus leaves it unplanned'); +}); + +test('the book shows and hides its draw set, and keeps the order icons came in', () => { + const set = recordingSet(); + const book = createIconBook(set); + book.show = false; + assert.equal(set.show, false); + assert.equal(book.show, false); + const alone = createIconBook(); + alone.show = false; + assert.equal(alone.show, true, 'nothing to hide'); + book.put(mover({ id: 'x' })); + book.put(mover({ id: 'y' })); + book.put(mover({ id: 'x', alpha: 0.2 })); + assert.deepEqual(book.ids(), ['x', 'y']); + assert.equal(book.size, 2); +});