Files
gods-eye-view/src/input/dispatcher.js
T
Sameh Khamis 0ab31d4fb8 The renderer seam: clicks go to the newest tool, recession and display groups through the contract, drawing at parity with Cesium
- Clicks: when two tools want the globe's clicks, the newest takes them and the older is told and turns itself off; a click is decided when it arrives, and ambient selection fires only when no tool holds the pointer. The "map is busy" paths and their strings are removed.
- Recession: the limb fade is shared (src/render/recession.js) and reaches icon and model sets through SetSpec.recede; tuning applies on the next frame.
- Display panel groups are published through src/ui/displayGroups.js; the Weather group and src/viewWeather.js are removed.
- Draw port: a set whose icons only move is moved in place, and models that did not change are not restyled each frame, so moving fleets cost what they did when drawn directly; an untinted, fully opaque model is drawn without a colour.
- Conformance: input.lease.lost checks the new lease inside onLost and reports a throwing onLost; draw.sets.recede covers model sets.
- QA scripts read the renderer host instead of internals the seam replaced.
2026-11-15 17:03:09 -08:00

552 lines
20 KiB
JavaScript

/**
* @module input/dispatcher
* @description The one place the application's layers and tools take
* pointer input over the globe: the renderer's input port
* (src/render/contract/input.d.ts, `findInput`), a click picked once through
* the renderer's query port and handed to every subscriber, and the
* camera-input and stock-click holds tools take. Each layer family moves
* onto the renderer's own `input` port as it is ported; until then it
* subscribes here, with the events and shapes it always had.
*
* Layers used to bind a handler each and pick the same click again, so one
* click with the usual layers on cost about 25 picks (each one redraws the
* scene for the pick buffer). Now the dispatcher picks lazily on first read
* and every subscriber reads the same {@link ClickEvent}; what a layer does
* with a click that is not its own stays the layer's decision.
*
* Who gets the pointer: while a tool holds it (src/data/inputOwnership.js)
* the port holds a lease for it (`bridgePointer`), so the port is not free,
* but that lease takes no press: each event is decided here when it arrives.
* - Ambient subscribers ({@link InputDispatcher.onClick}, and `onPointer`
* without a lease) run only while no tool holds the pointer. The check is
* made once per event, before any subscriber runs, so a tool that releases
* its lease while handling a click does not let that same click through
* to ambient selection. Ambient `move` and `up` are the exceptions: hover
* sees every move, so it can drop its cursor or card when a tool takes the
* pointer, and a release always reaches whoever began the press, so a drag
* started while the pointer was free still ends (and gives its camera hold
* back).
* - Tool subscribers pass their lease and run only while it is current.
* - A claim made on the port by anyone else takes the presses it grabs; the
* rest reach the subscribers here as above.
*
* Camera input is suspended through the input port's counted holds
* (`suspendCameraControls`), so a camera flight that ends cannot re-enable
* input under a drag or the cockpit.
*
* Positions are plain `{x, y}` CSS pixels. What the renderer's picks cannot
* name, something still drawn outside the draw port, comes from the
* renderer adapter's own picks of the click (`nativeClickOf`), which also
* hangs them on the click as `native` for code still bound to them.
*
* A dispatcher is made per scene object on first use ({@link inputFor}) and
* lives until {@link InputDispatcher.destroy}; the application scene owns
* it.
*/
import {
bridgePointer,
isLeaseCurrent,
pointerOwner,
} from '../data/inputOwnership.js';
import {
findPickOwner,
pickContact,
resolvePickId,
} from '../data/pickRegistry.js';
import { isPickedWorldPosition } from '../data/scenePick.js';
import {
canvasOf,
findInput,
findQuery,
nativeClickOf,
releaseUnboundInput,
} from '../render/rendererOf.js';
import { sensorPickPosition } from './sensorPick.js';
// A tool takes the pointer with a lease before it subscribes with one.
export {
claimPointer,
isLeaseCurrent,
isPointerFree,
pointerOwner,
releasePointer,
} from '../data/inputOwnership.js';
/**
* The world position under a screen point: the rendered surface where the
* depth buffer has it, else the ellipsoid; null over the sky.
*
* @param {object} viewer The scene object.
* @param {{x: number, y: number}} screenPosition
* @returns {{x: number, y: number, z: number}|null} ECEF metres.
*/
export function pickGroundPosition(viewer, screenPosition) {
return groundAt(findQuery(viewer), screenPosition);
}
/** `pickGroundPosition` through a query port. */
function groundAt(query, { x, y }) {
if (!query) return null;
let position = null;
try {
position = query.pickPosition(x, y);
} catch {
position = null;
}
if (!isPickedWorldPosition(position)) {
try {
position = query.pickEllipsoid(x, y);
} catch {
position = null;
}
}
return isPickedWorldPosition(position) ? position : null;
}
const POINTER_TYPES = ['down', 'move', 'up', 'click', 'dblclick'];
/**
* The events Cesium's unmodified left-button actions raised, which is all
* the dispatcher's subscribers have ever seen: the port also has the other
* buttons and the modified presses.
*/
const unmodified = ({ modifiers: m }) => !m.shift && !m.ctrl && !m.alt;
const unmodifiedLeft = (ev) => ev.button === 0 && unmodified(ev);
/** A tool that re-arms takes a new lease each time: it may pass a getter. */
const leaseOf = (entry) =>
typeof entry.lease === 'function' ? entry.lease() : entry.lease;
/** @type {WeakMap<object, InputDispatcher>} scene object -> dispatcher */
const dispatchers = new WeakMap();
const xy = (p) => ({ x: p.x, y: p.y });
/**
* A draw-set item's hit, or, from what the adapter's own pick found
* (`foreign`), a hit with no set for something drawn outside the draw port
* or the hit of a draw-set item the renderer's sets do not hold; null for
* the map itself or nothing.
*/
function topHitOf(hit, foreign) {
if (hit && !hit.surface) return hit;
const other = foreign();
if (!other) return null;
return other.set ? other : { set: '', id: other.id, surface: false };
}
/**
* @typedef {object} ClickGesture
* @property {number} travelPx Pointer travel during the press, summed per
* segment (an orbit nudge that comes back is not a zero-distance click).
* @property {number} durationMs Press time.
*/
/**
* @typedef {import('../render/contract/query').Hit} Hit
*/
/**
* One left click, picked at most once per kind of query. Every getter and
* method is memoized, so subscribers share the passes. Hits are the
* contract's `Hit`; one with `set: ''` is something drawn outside the draw
* port, named by the renderer adapter (its id null when it has none).
* @typedef {object} ClickEvent
* @property {{x: number, y: number}} screenPosition Where the user clicked.
* @property {{x: number, y: number}} position Where that lands in the pick buffer
* (corrected for sensor styles; see sensorPick.js).
* @property {ClickGesture} gesture
* @property {Hit|null} topHit What is on top under the click: a draw-set
* item, or something drawn outside the draw port; null for the map itself
* (the globe, tiles) or nothing.
* @property {Hit|null} drawHit `topHit` when it is an item of a renderer draw
* set; null for anything else. What layers on the draw port read a click
* by.
* @property {Hit|null} hit `topHit`, or on a coarse pointer the first
* registered contact under the map (`pickContact`).
* @property {string|null} id The hit's canonical pick id.
* @property {string|null} ownerId The layer that registered the hit.
* @property {object|undefined} meta The hit's own metadata, when it has any.
* @property {boolean} surface Whether the hit is the map itself, or nothing.
* @property {(width: number, height: number) => {id: string|null, drawHit: Hit|null, surface: boolean}} windowHit
* A pick with a wider window, read as `id`, `drawHit` and `surface` are.
* @property {(limit?: number, width?: number, height?: number) => Hit[]} drill
* The draw-set items under the click, nearest first, at most `limit`
* (`query.drillPick`).
* @property {() => {x: number, y: number, z: number}|null} ground The world
* position under the click: rendered surface, else ellipsoid; null over
* the sky.
* @property {import('../render/rendererOf.js').NativeClick['native']|undefined} native
* The renderer adapter's own picks of the click (`pick`, `pickWindow`,
* `drill`), for code still bound to the engine's pick objects; undefined
* when the adapter has none.
* @property {unknown} pick `native.pick`, for code still bound to the
* engine's pick objects that reads it here.
* @property {(width: number, height: number) => unknown} pickWindow
* `native.pickWindow`, the same.
*/
/**
* @typedef {object} InputDispatcher
* @property {(fn: (event: ClickEvent) => void) => () => void} onClick
* Ambient click subscription. Returns its unsubscribe.
* @property {(type: 'down'|'move'|'up'|'click'|'dblclick', fn: Function, options?: {lease?: object|(() => object|null)}) => () => void} onPointer
* Raw pointer subscription: `click` gets the {@link ClickEvent}, the others
* `{position}` (`move`: `{startPosition, endPosition, pickPosition}`, its
* `pickPosition` its `endPosition` corrected for sensor styles as a
* click's `position` is). With a lease, runs only while that lease is current;
* without one, only while the pointer is free (`move` and `up` always run).
* @property {(reason: string) => () => void} suspendCamera Hold camera input
* off; returns this hold's release.
* @property {() => () => void} suppressStockClicks Take the renderer's stock
* select and double-click follow off; returns this hold's release.
* @property {(name: 'select'|'dblclickFollow') => boolean} stockEnabled
* Whether the renderer's stock select or follow runs now: it does unless a
* hold is out (or the renderer has none).
* @property {() => number} subscriberCount Live click and pointer
* subscriptions, for leak checks.
* @property {() => void} destroy
*/
/**
* What is under canvas CSS pixel `x, y` now, as a click's `topHit` would
* see it (a hit on the follow's helper is a hit on its target), for a reader
* that is not handed a click (point-and-ask). Null when nothing but the map
* is there, or the pick fails.
* @param {object} viewer The scene object.
* @param {number} x
* @param {number} y
* @returns {Hit|null}
*/
export function pickAt(viewer, x, y) {
try {
if (!viewer || viewer.isDestroyed?.()) return null;
const query = findQuery(viewer);
if (!query) return null;
const position = { x, y };
return topHitOf(
query.pick(x, y),
() => nativeClickOf(viewer, position)?.foreign() ?? null,
);
} catch {
return null;
}
}
/**
* The scene object's dispatcher, made on first use.
* @param {object} viewer The scene object (a Cesium viewer, or a test
* double).
* @param {{createHandler?: (canvas: object) => object, now?: () => number,
* document?: object|null, query?: import('../render/contract/query').QueryPort}} [options]
* For a dispatcher over a viewer with no renderer bound: the input port's
* (`findInput`) when this call builds it, and the query port its clicks
* pick through (tests pass doubles). Used only by the call that makes the
* dispatcher.
* @returns {InputDispatcher}
*/
export function inputFor(viewer, options = {}) {
let dispatcher = dispatchers.get(viewer);
if (!dispatcher) {
dispatcher = createDispatcher(viewer, options);
dispatchers.set(viewer, dispatcher);
}
return dispatcher;
}
function createDispatcher(viewer, { query: givenQuery, ...portOptions } = {}) {
const port = findInput(viewer, portOptions);
if (!port)
throw new Error(
viewer?.isDestroyed?.()
? 'This scene has been destroyed'
: 'This scene has no renderer to take input with: bind one, or load ' +
"the Cesium adapter's factories (the ./render/cesium/unbound export) " +
'for a viewer with no renderer bound',
);
const queryOf = () => givenQuery ?? findQuery(viewer);
/** @type {Array<{fn: Function}>} */
const clickSubscribers = [];
/** @type {Record<string, Array<{fn: Function, lease: object|null}>>} */
const pointerSubscribers = Object.fromEntries(
POINTER_TYPES.map((type) => [type, []]),
);
const stockHolds = new Set();
const cameraHolds = new Set();
let destroyed = false;
// The port holds a lease while a tool here holds the pointer.
const bridge = bridgePointer(port);
/** Tool subscribers whose lease is current, and ambient ones if `free`. */
const run = (list, free, arg) => {
for (const entry of [...list]) {
if (entry.lease ? !isLeaseCurrent(leaseOf(entry)) : !free) continue;
try {
entry.fn(arg);
} catch (error) {
console.error('Pointer input handler failed', error);
}
}
};
// Whether ambient subscribers hear a press, read once as it arrives. A
// claim on the port that is not this bridge's has already taken the
// presses it grabs; what reaches here is free unless a tool here holds it.
const free = () => pointerOwner() === null;
// Each type is one port listener.
const deliver = {
down: (ev) => {
if (!unmodifiedLeft(ev)) return;
run(pointerSubscribers.down, free(), { position: xy(ev.position) });
},
move: (ev) => {
if (!unmodified(ev)) return;
const endPosition = xy(ev.endPosition ?? ev.position);
let pickPosition;
run(pointerSubscribers.move, true, {
startPosition: xy(ev.position),
endPosition,
// Where the pointer lands in the pick buffer, as a click's
// `position` is (corrected for sensor styles); made on first read.
get pickPosition() {
pickPosition ??= sensorPickPosition(
viewer,
endPosition,
canvasOf(viewer),
);
return pickPosition;
},
});
},
up: (ev) => {
if (!unmodifiedLeft(ev)) return;
run(pointerSubscribers.up, true, { position: xy(ev.position) });
},
click: (ev) => {
if (!unmodifiedLeft(ev)) return;
const ambient = free();
const event = createClickEvent(
viewer,
queryOf,
xy(ev.position),
ev.gesture ?? { travelPx: 0, durationMs: 0 },
);
run(pointerSubscribers.click, ambient, event);
if (ambient) run(clickSubscribers, true, event);
},
dblclick: (ev) => {
if (!unmodifiedLeft(ev)) return;
run(pointerSubscribers.dblclick, free(), { position: xy(ev.position) });
},
};
const offPort = POINTER_TYPES.map((type) => port.on(type, deliver[type]));
const subscribe = (list, entry) => {
if (destroyed) return () => {};
list.push(entry);
return () => {
const at = list.indexOf(entry);
if (at >= 0) list.splice(at, 1);
};
};
const self = {
onClick(fn) {
return subscribe(clickSubscribers, { fn, lease: null });
},
onPointer(type, fn, { lease = null } = {}) {
const list = pointerSubscribers[type];
if (!list) throw new TypeError(`Unknown pointer event: ${type}`);
return subscribe(list, { fn, lease });
},
suspendCamera(reason) {
if (destroyed) return () => {};
const release = port.suspendCameraControls(reason);
const hold = () => {
if (!cameraHolds.delete(hold)) return;
release();
};
cameraHolds.add(hold);
return hold;
},
suppressStockClicks() {
if (destroyed) return () => {};
// The renderer's own select and double-click follow never see the
// pointer lease; the port runs them, and holds them off here.
const releases = [
port.behaviours.select.suppress(),
port.behaviours.dblclickFollow.suppress(),
];
const hold = () => {
if (!stockHolds.delete(hold)) return;
for (const release of releases) release();
};
stockHolds.add(hold);
return hold;
},
stockEnabled: (name) => port.behaviours[name]?.enabled ?? false,
subscriberCount() {
return POINTER_TYPES.reduce(
(sum, type) => sum + pointerSubscribers[type].length,
clickSubscribers.length,
);
},
destroy() {
if (destroyed) return;
destroyed = true;
if (dispatchers.get(viewer) === self) dispatchers.delete(viewer);
clickSubscribers.length = 0;
for (const type of POINTER_TYPES) pointerSubscribers[type].length = 0;
for (const off of offPort) off();
bridge.off();
for (const hold of [...stockHolds]) hold();
for (const hold of [...cameraHolds]) hold();
// A port built for this viewer goes with its dispatcher; a
// renderer's own stays.
releaseUnboundInput(viewer, port);
},
};
return self;
}
/** A drill is run at least this deep and sliced, so callers asking for
* different depths on one click share one pass. */
const DRILL_DEPTH = 16;
/**
* @param {object} viewer
* @param {() => import('../render/contract/query').QueryPort|null} queryOf
* @param {{x: number, y: number}} at Where the click is, CSS pixels.
* @param {ClickGesture} gesture
* @returns {ClickEvent}
*/
function createClickEvent(viewer, queryOf, at, gesture) {
const position = sensorPickPosition(viewer, at, canvasOf(viewer));
const { x, y } = position;
const memo = new Map();
const once = (key, compute) => {
if (!memo.has(key)) memo.set(key, compute());
return memo.get(key);
};
const native = () => once('native', () => nativeClickOf(viewer, position));
const query = () => once('query', queryOf);
/** The renderer's pick, with a window or not; null without a query port. */
const pick = (window) => {
const q = query();
return q ? (q.pick(x, y, window) ?? null) : null;
};
/** @type {Map<string, {limit: number, hits: Hit[]}>} */
const drills = new Map();
return {
screenPosition: at,
position,
gesture,
get topHit() {
return once('top', () => {
const hit = pick();
// The adapter's own pick of this click is the renderer's pass, held
// now: read later, it would be another, of a scene drawn since.
void native()?.native.pick;
return topHitOf(hit, () => native()?.foreign() ?? null);
});
},
get drawHit() {
const hit = this.topHit;
return hit?.set ? hit : null;
},
get hit() {
return once('hit', () => {
const q = query();
if (!q) return this.topHit;
return pickContact(q, position, {
picked: this.topHit,
// Everything drawn there, as the adapter sees it, so a contact
// search stops at what is drawn over a contact outside the draw
// port and finds a contact drawn there; the draw-set items alone
// without one.
drill: (limit, width, height) => {
const click = native();
return click
? click.drillHits(limit, width, height)
: this.drill(limit, width, height);
},
});
});
},
get id() {
return once('id', () => resolvePickId(this.hit));
},
get ownerId() {
return once('ownerId', () => findPickOwner(this.id));
},
get meta() {
return this.hit?.meta;
},
get surface() {
return !this.hit;
},
windowHit(width, height) {
return once(`windowHit:${width}x${height}`, () => {
const picked = pick({ width, height });
void native()?.native.pickWindow(width, height);
const hit = topHitOf(
picked,
() => native()?.foreign(width, height) ?? null,
);
return {
id: resolvePickId(hit),
drawHit: hit?.set ? hit : null,
surface: !hit,
};
});
},
drill(limit = DRILL_DEPTH, width, height) {
const key = `${width}x${height}`;
const done = drills.get(key);
// A deeper pass already made holds these. (One that came back short
// may not hold every hit: it drops what is not a draw-set item.)
if (done && limit <= done.limit) return done.hits.slice(0, limit);
const q = query();
if (!q) return [];
// Only the default window is shared between layers; round that one up.
const depth =
width === undefined && height === undefined
? Math.max(limit, DRILL_DEPTH)
: limit;
const hits = q.drillPick(x, y, {
...(width === undefined ? {} : { width }),
...(height === undefined ? {} : { height }),
limit: depth,
});
drills.set(key, { limit: depth, hits });
return hits.slice(0, limit);
},
ground() {
return once('ground', () => groundAt(query(), position));
},
get native() {
// After the renderer's pick, whose pass the adapter's reuses.
void this.topHit;
return native()?.native;
},
get pick() {
// After the renderer's pick, whose pass the adapter's reuses.
void this.topHit;
return native()?.native.pick;
},
pickWindow(width, height) {
void this.windowHit(width, height);
return native()?.native.pickWindow(width, height);
},
};
}