Files
gods-eye-view/src/render/contract/input.d.ts
T
Sameh Khamis 90499762f5 Add pointer-driven camera scripts with Cesium goldens, and count wheel lines as Cesium does
Five new camera conformance scripts move the camera by user input: a
left drag that coasts, thirty pixel-mode and thirty line-mode wheel
notches from 5 km, a middle-drag tilt, and Shift and Ctrl drags held too
long to coast. The runner turns input steps into pointer events for a
driver: a move starts where the pointer last pressed or moved and carries
the held button. The golden recorder now drives Cesium's own screen-space
camera controller on a stand-in canvas, with Date on the virtual clock so
inertia is deterministic. The existing goldens are unchanged.

A harness that answers pointer input sets cameraInput and a pointer hook.
Harnesses without it, such as the stub, skip the input scripts.

The input port reported a line-mode wheel at 33 1/3 pixels a line. It now
counts lines as the reference does, 40 pixels a line and 3 lines a page,
so a pixel or line wheel converts back to the same pixels.
2026-11-08 20:08:56 -08:00

127 lines
5.0 KiB
TypeScript

/**
* Pointer input over the scene, through one dispatcher.
*
* A tool takes the pointer with a lease; while a lease is out, ambient
* subscribers (those without a lease) get only `move` and `up`: no presses,
* clicks, double-clicks, wheel or pinch. A lease with `grab` takes only the
* presses it grabs: `grab` is asked on each `down`, and a grabbed press (its
* `down`, and the `click` and `dblclick` it ends in) goes to the lease's
* listeners alone. Every other press, and wheel and pinch, go to ambient
* subscribers and the camera as if the pointer were free; `move` and `up`
* go to both.
*
* Every event of a press goes where its `down` went, even when the lease
* ends or changes before the press is over (an ended lease's to no one), so
* a claim never takes a press already under way. Each button's presses
* are separate. A press runs from its `down` through its `up`, the `click`
* straight after it where it went up, and a `dblclick` straight after that
* at the same spot;
* any other event after its `up` ends it. A click or double-click with no
* press of its own is decided as a press, `grab` seeing it as a `down`
* (without `pick`, `drill` or `ground`).
*
* Suspending camera input is separate and counted, and takes effect on the
* same pointerdown that asked for it, so a tool that grabs a press suspends
* the camera in its `down` listener.
*
* A click is delivered with its pick already made, once, and shared by
* every subscriber (`PointerEv.pick`). Where the renderer's picks answer a
* or two late delivers the click that much later rather than answering
* without them; `query.pick` stays synchronous for everything else.
*
* The engine's stock behaviours (select on click, follow on double-click)
* are explicit and removable here, never implicit.
*/
import type { Hit, PickWindow } from './query';
import type { Ecef, Off, Release, ScreenXY } from './common';
export type PointerEventType =
'down' | 'move' | 'up' | 'click' | 'dblclick' | 'wheel' | 'pinch';
export interface Modifiers {
shift: boolean;
ctrl: boolean;
alt: boolean;
meta: boolean;
}
export interface PointerEv {
type: PointerEventType;
position: ScreenXY;
/** For `move`: where the pointer is now (`position` is where it was). */
endPosition?: ScreenXY;
button: 0 | 1 | 2;
modifiers: Modifiers;
/** Event time, ms (`performance.now()` timeline). */
timestamp: number;
pointerType: 'mouse' | 'touch' | 'pen';
/** `click`: how far the pointer travelled and how long the press lasted. */
gesture?: { travelPx: number; durationMs: number };
/**
* `wheel`: lines scrolled, down positive, counted as the reference
* renderer counts them: a pixel-mode wheel at 40 px a line, a page at 3
* lines (so 40 px a line turns either back into the reference's pixels);
* `pinch`: scale since the last event.
*/
delta?: number;
/** `click` and `dblclick`: the hit under the pointer, picked once for every subscriber. */
pick?(): Hit | null;
/** `click` and `dblclick`: every hit under the pointer, from the same pick. */
drill?(options?: PickWindow & { limit?: number }): Hit[];
/** `click` and `dblclick`: the surface position under the pointer. */
ground?(): Ecef | null;
}
/** A tool's hold on the pointer. */
export interface Lease {
readonly owner: string;
readonly current: boolean;
release(): void;
}
/** A stock behaviour, on until suppressed. */
export interface StockBehaviour {
readonly enabled: boolean;
/** Turn it off until released. Holds are counted. */
suppress(): Release;
}
export interface InputPort {
on(
type: PointerEventType,
cb: (ev: PointerEv) => void,
options?: { lease?: Lease | (() => Lease | null) },
): Off;
/**
* Take the pointer for a tool. A new claim ends the previous lease.
* `grab` decides each press from its `down` event, synchronously: true
* makes it the tool's, anything else leaves it. A `down` carries no pick,
* so `grab` decides from the position, button and modifiers (and the
* tool's own hit test, through `query`). Omitted, every press is the
* tool's. A `grab` that throws is reported and leaves the press to the
* others.
*/
claimPointer(
owner: string,
options?: { grab?: (down: PointerEv) => boolean },
): Lease;
isPointerFree(): boolean;
/** Suspend user camera input until released. Holds are counted. */
suspendCameraControls(reason: string): Release;
/**
* Every behaviour the renderer does on its own in answer to input, each
* suppressible. `select` and `dblclickFollow` are always listed (a
* renderer without one reports it disabled); any other built-in one (a
* double-click zoom) is listed under its own name.
*/
readonly behaviours: {
/** Select the item under a click. */
readonly select: StockBehaviour;
/** Follow the item under a double-click. */
readonly dblclickFollow: StockBehaviour;
readonly [name: string]: StockBehaviour;
};
/** Ctrl+wheel zooms (rather than the page). */
ctrlWheelZoom: boolean;
}