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.
This commit is contained in:
Sameh Khamis committed 2026-11-07 02:36:39 -08:00
1 parent 0349941b71
commit e72382b1aa
4 files changed
+255 -51

No files matched your search

+119
View File
@@ -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<object>|null} [drawSet] Where
* the icons are drawn; none keeps them only here (tests).
* @param {{capabilities?: ReadonlySet<string>|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;
}
+128
View File
@@ -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);
});