Files
gods-eye-view/src/render/cesium/input.js
T
Sameh Khamis 7a376ebefc Make quality settings detail only and fold ctrl-wheel zoom into the camera's zoom inputs
Quality no longer switches clouds or water (their ports are gone) and its
atmosphere and post-processing settings are low or high detail; whether the
sky or a pass shows stays with globe.sky and effects. The separate
input.ctrlWheelZoom switch is gone: 'ctrlWheel' in the camera's zoomInputs
also relays trackpad pinches, which the application turns on.
2026-11-10 03:35:35 -08:00

493 lines
18 KiB
JavaScript

/**
* @module render/cesium/input
* @description The Cesium renderer's input port
* (`src/render/contract/input.d.ts`): one `ScreenSpaceEventHandler` over the
* canvas turns Cesium's pointer events into the contract's, and the shared
* router (`src/render/input/router.js`) decides who hears each.
*
* - Presses, releases, clicks and moves come from the handler, for every
* button and with any one modifier held (Cesium raises an action only for
* the modifier it was bound with). The DOM event under each one, seen
* first on the document, gives the full modifiers and the pointer type.
* - Wheel comes from the canvas's own `wheel` event, which this never
* cancels: Ctrl+wheel zooms the globe only while the camera controls'
* `zoomInputs` hold `ctrlWheel`. Pinch comes from the handler's
* two-finger events.
* - A click is picked lazily and once, through the query port, and shared
* by every subscriber.
* - The viewer's stock select (left click) and follow (double-click) are
* taken off its handler and run from here, ahead of the subscribers as
* they ran on it, only for a press that goes to them (no lease took it)
* and while the behaviour is not suppressed. A widget without them reports them
* disabled.
* - Camera input is held off through the scene's shared holds
* (`cameraInput.js`).
*/
import * as Cesium from 'cesium';
import { createInputRouter } from '../input/router.js';
import { acquireCameraInput } from './cameraInput.js';
import { wheelLines } from '../input/wheel.js';
import { provideUnboundInput } from '../rendererOf.js';
const T = Cesium.ScreenSpaceEventType;
const MODIFIERS = [
undefined,
Cesium.KeyboardEventModifier.SHIFT,
Cesium.KeyboardEventModifier.CTRL,
Cesium.KeyboardEventModifier.ALT,
];
const BUTTONS = ['LEFT', 'MIDDLE', 'RIGHT'];
/** The stock behaviours, by the handler action they are. */
const STOCK = { select: T.LEFT_CLICK, dblclickFollow: T.LEFT_DOUBLE_CLICK };
/** The DOM events Cesium's handler reads, in either input model. */
const DOM_EVENTS = [
'pointerdown',
'pointermove',
'pointerup',
'pointercancel',
'mousedown',
'mousemove',
'mouseup',
'touchstart',
'touchmove',
'touchend',
'touchcancel',
'dblclick',
];
/** A drill is run at least this deep and sliced, so asks share one pass. */
const DRILL_DEPTH = 16;
const NO_MODIFIERS = Object.freeze({
shift: false,
ctrl: false,
alt: false,
meta: false,
});
const POINTER_TYPES = new Set(['mouse', 'touch', 'pen']);
/** The one modifier Cesium raised an action for, when no DOM event says. */
const CESIUM_MODIFIER = {
[Cesium.KeyboardEventModifier.SHIFT]: { shift: true },
[Cesium.KeyboardEventModifier.CTRL]: { ctrl: true },
[Cesium.KeyboardEventModifier.ALT]: { alt: true },
};
const xy = (p) => ({ x: p.x, y: p.y });
const distance = (a, b) => Math.hypot(a.x - b.x, a.y - b.y);
const modifiersOf = (dom) =>
dom
? {
shift: Boolean(dom.shiftKey),
ctrl: Boolean(dom.ctrlKey),
alt: Boolean(dom.altKey),
meta: Boolean(dom.metaKey),
}
: { ...NO_MODIFIERS };
/** A DOM event's pointer type; a `dblclick`, which has none, takes `otherwise`. */
function pointerTypeOf(dom, otherwise = 'mouse') {
if (POINTER_TYPES.has(dom?.pointerType)) return dom.pointerType;
if (dom?.type?.startsWith('touch')) return 'touch';
if (dom?.type?.startsWith('mouse')) return 'mouse';
return otherwise;
}
/** @type {WeakMap<object, object>} scene -> its input port */
const inputs = new WeakMap();
/**
* The input port made for a scene, while it lives.
* @param {object} scene
* @returns {ReturnType<typeof createCesiumInput> | null}
*/
export const cesiumInputOf = (scene) => inputs.get(scene) ?? null;
/**
* One per scene: a second would find the stock actions already taken.
* @param {object} widget A Cesium `CesiumWidget` or `Viewer`.
* @param {object} options
* @param {object} [options.query] The renderer's query port: clicks pick
* through it. Without one, clicks carry no picks, for a caller that makes
* its own (the application's dispatcher, over a viewer of its own).
* @param {(error: unknown) => void} options.report Where a listener's or a
* `grab`'s error goes.
* @param {(canvas: object) => object} [options.createHandler]
* @param {() => number} [options.now] Event time, ms.
* @param {object} [options.document] Where the DOM events are watched.
* @param {boolean} [options.takeStock] False leaves the viewer's stock
* actions on its own handler, taken off only while suppressed, for a
* viewer that is not this renderer's: its owner may still rebind them.
* @returns {{port: object, feed: Function, listenerCount: () => number, dispose: () => void}}
* `feed(type, x, y, extra)` delivers one event as the handler would, for
* the conformance harness.
*/
export function createCesiumInput(
widget,
{
query,
report,
createHandler = (canvas) => new Cesium.ScreenSpaceEventHandler(canvas),
now = () => performance.now(),
document: dom = globalThis.document,
takeStock = true,
},
) {
const scene = widget.scene;
if (inputs.has(scene))
throw new TypeError('This scene already has an input port');
const canvas = scene.canvas;
let disposed = false;
// The viewer's stock actions, now this port's to run; or, not taking
// them, borrowed from its handler while suppressed.
const stockHandler = widget.screenSpaceEventHandler;
const stock = {};
const has = {};
for (const [name, type] of Object.entries(STOCK)) {
const action = stockHandler?.getInputAction?.(type);
has[name] = Boolean(action);
if (!action || !takeStock) continue;
stock[name] = action;
stockHandler.removeInputAction(type);
}
/** Actions borrowed while suppressed, to give back by identity. */
const borrowed = {};
const giveBack = (name) => {
const action = borrowed[name];
delete borrowed[name];
if (!action || !stockHandler || stockHandler.isDestroyed?.()) return;
if (!stockHandler.getInputAction(STOCK[name]))
stockHandler.setInputAction(action, STOCK[name]);
};
function borrowStock(name, enabled) {
if (takeStock || !stockHandler) return;
if (enabled) return giveBack(name);
const action = stockHandler.getInputAction?.(STOCK[name]);
if (!action) return;
borrowed[name] = action;
stockHandler.removeInputAction(STOCK[name]);
}
const cameraInput = acquireCameraInput(scene);
const router = createInputRouter({
report,
suspendCamera: (reason) => cameraInput.suspend(reason),
supported: { select: has.select, dblclickFollow: has.dblclickFollow },
onBehaviour: borrowStock,
});
const { behaviours } = router.port;
// The DOM event the handler is answering, seen before it on the document,
// for as long as it is being dispatched: an action Cesium raises later, on
// a timer (a touch held for a right click), has none. The pointer type of
// the last one stays for those.
let lastDom = null;
let lastPointerType = 'mouse';
let clearing = false;
// A task after this one: every event seen before it has been dispatched.
const clear = () => {
clearing = false;
lastDom = null;
};
const record = (event) => {
lastDom = event;
lastPointerType = pointerTypeOf(event, lastPointerType);
if (clearing) return;
clearing = true;
setTimeout(clear, 0);
};
for (const type of DOM_EVENTS)
dom?.addEventListener?.(type, record, { capture: true, passive: true });
/** Presses under way by button, for each click's gesture. */
const pressing = new Map();
/** Each button's last finished press, until its click reads it. */
const finished = new Map();
/** The button of the last event, when it was an up. */
let lastUp = null;
/** The type of the last event delivered. */
let lastType = null;
/**
* The stock behaviours as they stood at the last left down: a press that
* began suppressed stays so, even when its tool lets go on the up.
*/
let stockAtDown = null;
const heldButton = () => {
for (const button of [0, 1, 2]) if (pressing.has(button)) return button;
return 0;
};
function track(type, position, endPosition, button) {
const at = now();
if (type === 'down') {
pressing.set(button, { start: at, last: position, travel: 0 });
finished.delete(button);
} else if (type === 'move') {
for (const press of pressing.values()) {
press.travel += distance(press.last, endPosition);
press.last = endPosition;
}
} else if (type === 'up') {
const press = pressing.get(button);
if (!press) return;
press.travel += distance(press.last, position);
pressing.delete(button);
finished.set(button, {
travelPx: press.travel,
durationMs: Math.max(0, at - press.start),
});
}
}
/** A click's lazy picks, each made at most once. */
function withPicks(ev) {
const { x, y } = ev.position;
let hit;
let picked = false;
let ground;
let grounded = false;
/** @type {Map<string, object[]>} */
const drills = new Map();
ev.pick = () => {
if (!picked) {
picked = true;
hit = query.pick(x, y) ?? null;
}
return hit;
};
ev.drill = (options = {}) => {
const { limit, ...window } = options;
const want = limit ?? Infinity;
// A bounded drill looks only so deep (`drillPick`'s limit bounds the
// work), so each depth is its own pass: a deeper one could name items
// a shallower one never reaches.
const depth = want === Infinity ? Infinity : Math.max(want, DRILL_DEPTH);
const key = `${window.width ?? ''}x${window.height ?? ''}:${window.purpose ?? ''}:${depth}`;
let hits = drills.get(key);
if (!hits) {
hits = query.drillPick(x, y, {
...window,
...(depth === Infinity ? {} : { limit: depth }),
});
drills.set(key, hits);
}
return want === Infinity ? hits.slice() : hits.slice(0, want);
};
ev.ground = () => {
if (!grounded) {
grounded = true;
ground = query.pickPosition(x, y) ?? query.pickEllipsoid(x, y);
}
return ground;
};
return ev;
}
/**
* One event into the router, shaped as the contract's.
* @param {string} type
* @param {{x: number, y: number}} position
* @param {object} [extra] `button`, `endPosition`, `delta`, and, from the
* feed, `modifiers`, `pointerType` and `gesture`.
* @param {object|null} [source] The DOM event under it.
*/
function deliver(type, position, extra = {}, source = lastDom) {
if (disposed) return;
// Cesium ends every held button on any button's release, each with its
// click: the others' presses end there, as they do for its camera, but
// only the button released clicks.
const released = source && /(?:pointer|mouse)up$/.test(source.type);
if (type === 'click' && released && source.button !== extra.button) {
finished.delete(extra.button);
return;
}
const at = xy(position);
const end = extra.endPosition ? xy(extra.endPosition) : undefined;
const button = extra.button ?? heldButton();
// A move with no end is where the pointer is now.
track(type, at, end ?? at, button);
const justUp = lastUp;
lastUp = type === 'up' ? button : null;
const previous = lastType;
lastType = type;
if (type === 'down' && button === 0)
stockAtDown = {
select: behaviours.select.enabled,
dblclickFollow: behaviours.dblclickFollow.enabled,
};
// A click straight after its up, and a double-click straight after
// that click, belong to the last press.
const ofPress =
(type === 'click' && justUp === 0) ||
(type === 'dblclick' && previous === 'click');
const ev = {
type,
position: at,
button,
modifiers: extra.modifiers
? { ...NO_MODIFIERS, ...extra.modifiers }
: source
? modifiersOf(source)
: { ...NO_MODIFIERS, ...CESIUM_MODIFIER[extra.modifier] },
timestamp: now(),
pointerType: extra.pointerType ?? pointerTypeOf(source, lastPointerType),
...(end ? { endPosition: end } : {}),
...(extra.delta !== undefined ? { delta: extra.delta } : {}),
};
if (type === 'click' || type === 'dblclick') {
// A click ends the press whose up came straight before it; one
// Cesium raises on a timer (a touch held) ends none.
const press =
type === 'click' && justUp === button
? finished.get(button)
: undefined;
finished.delete(button);
ev.gesture = extra.gesture ?? press ?? { travelPx: 0, durationMs: 0 };
if (query) withPicks(ev);
}
// The viewer's own select and follow run first, as they did on its
// handler.
router.dispatch(ev, (to) => runStock(ev, to, ofPress ? stockAtDown : null));
// A hold a down subscriber takes covers its press too.
if (type === 'down' && button === 0 && stockAtDown)
stockAtDown = {
select: stockAtDown.select && behaviours.select.enabled,
dblclickFollow:
stockAtDown.dblclickFollow && behaviours.dblclickFollow.enabled,
};
}
/** The viewer's own select or follow, as it would have run. */
function runStock(ev, to, atDown) {
const name =
ev.type === 'click'
? 'select'
: ev.type === 'dblclick'
? 'dblclickFollow'
: null;
if (!name || !stock[name] || ev.button !== 0 || !to.ambient) return;
// Cesium bound them with no modifier: a modified click never ran them.
const { shift, ctrl, alt } = ev.modifiers;
if (shift || ctrl || alt || !behaviours[name].enabled) return;
if (atDown && !atDown[name]) return;
try {
stock[name]({
position: new Cesium.Cartesian2(ev.position.x, ev.position.y),
});
} catch (error) {
report(error);
}
}
const handler = createHandler(canvas);
const bind = (type, action) => {
for (const modifier of MODIFIERS)
handler.setInputAction(
(event) => action(event, modifier),
type,
modifier,
);
};
BUTTONS.forEach((name, button) => {
bind(T[`${name}_DOWN`], (e, modifier) =>
deliver('down', e.position, { button, modifier }),
);
bind(T[`${name}_UP`], (e, modifier) =>
deliver('up', e.position, { button, modifier }),
);
bind(T[`${name}_CLICK`], (e, modifier) =>
deliver('click', e.position, { button, modifier }),
);
});
bind(T.LEFT_DOUBLE_CLICK, (e, modifier) =>
deliver('dblclick', e.position, { button: 0, modifier }),
);
bind(T.MOUSE_MOVE, (e, modifier) =>
deliver('move', e.startPosition ?? e.endPosition, {
endPosition: e.endPosition,
modifier,
}),
);
// Pinch is at the two fingers' midpoint where it started; its delta is
// the scale since the last event.
let pinchAt = null;
bind(T.PINCH_START, (e) => {
pinchAt = {
x: (e.position1.x + e.position2.x) / 2,
y: (e.position1.y + e.position2.y) / 2,
};
});
bind(T.PINCH_MOVE, (e) => {
const from = e.distance.startPosition.y;
const to = e.distance.endPosition.y;
if (!(from > 0) || !(to > 0) || !pinchAt) return;
deliver('pinch', pinchAt, { delta: to / from });
});
bind(T.PINCH_END, () => {
pinchAt = null;
});
const onWheel = (event) => {
const rect = canvas.getBoundingClientRect?.() ?? { left: 0, top: 0 };
deliver(
'wheel',
{ x: event.clientX - rect.left, y: event.clientY - rect.top },
// Lines as the reference counts them (`../input/wheel.js`).
{ delta: wheelLines(event) },
event,
);
};
canvas?.addEventListener?.('wheel', onWheel, { passive: true });
const self = {
port: router.port,
feed(type, x, y, extra = {}) {
deliver(type, { x, y }, extra, null);
},
listenerCount: router.listenerCount,
dispose() {
if (disposed) return;
disposed = true;
router.dispose();
if (inputs.get(scene) === self) inputs.delete(scene);
canvas?.removeEventListener?.('wheel', onWheel, { passive: true });
for (const type of DOM_EVENTS)
dom?.removeEventListener?.(type, record, { capture: true });
if (!handler.isDestroyed?.()) handler.destroy?.();
cameraInput.release();
for (const name of Object.keys(borrowed)) giveBack(name);
if (stockHandler && !stockHandler.isDestroyed?.())
for (const [name, type] of Object.entries(STOCK))
if (stock[name] && !stockHandler.getInputAction(type))
stockHandler.setInputAction(stock[name], type);
},
};
inputs.set(scene, self);
return self;
}
// A Cesium viewer with no renderer bound to it gets an
// input port over its canvas when code first asks `findInput` for one (the
// application's dispatcher, src/input/dispatcher.js). Its clicks carry no
// picks: the dispatcher makes its own through `findQuery`. The viewer is its
// owner's, so its stock actions stay on its own handler, taken off only
// while suppressed. `options` are the test doubles' (`createHandler`, `now`,
// `document`).
provideUnboundInput((viewer, options = {}) => {
const scene = viewer?.scene;
if (!scene || typeof scene !== 'object') return null;
// A port someone already made for the scene (a harness's): borrowed.
const made = inputs.get(scene);
if (made) return { port: made.port, dispose() {} };
const { createHandler, now, document } = options;
const input = createCesiumInput(viewer, {
report: (error) => console.error('Pointer input failed', error),
takeStock: false,
...(createHandler ? { createHandler } : {}),
...(now ? { now } : {}),
...(document !== undefined ? { document } : {}),
});
// Kept for its dispatcher when a renderer is bound later, as the
// dispatcher's clicks would otherwise stop.
return { port: input.port, dispose: () => input.dispose(), keep: true };
});