feat(globe): picks on input payloads

input.on('click'|'doubleClick'|'move', fn, { pick, drill }) delivers
{ …event, picked, drilled }: PickResult { id, owner, instance, primitive
(Cesium) } names the mover set (and instance) or line hit. One pick (and
one drill, as deep as the deepest listener) per event, shared by its
listeners; moves with picks are coalesced to one delivery per frame with
the latest position (src/globe/pickDelivery.js). Option checks in the
contract (normalizeInputOptions).

- Cesium: scene.pick / drillPick, and the picker names the owner: movers
  map billboards, points and models to their set and instance, lines
  their primitives to the line.
- Navara: a click with pick takes Navara's GPU pick of the same gesture
  (featureClick; its pick helper answers on the same pointerup, usually
  before the engine's click, so a fresh answer waits for it; otherwise
  the click waits up to 250 ms, then the CPU pick). Navara 0.2.1 answers
  clicks in quick succession with the first click's pick: a GPU answer
  whose instance is not drawn near the click is stale and the CPU pick
  answers. Hover, drill and the synchronous picker.pick/drillPick are CPU
  picks (src/globe/cpuPicks.js) of pickable mover sets and pickable lines
  (within half the width + 3 px), behind the globe excluded, nearest
  first; lines are picked on the CPU after an empty GPU answer.
  picker.clickStats() (Navara only) counts the answers and latencies.
- The fake engine picks its own movers and lines on the CPU unless
  scripted.
- The contract suite clicks with real pointer events (puppeteer) on both
  engines: a sprite is picked with its owner and instance, the map picks
  nothing, two sprites in one place drill both, a line is picked, a
  hover picks the sprite under it. Navara, 20 clicks: payload p50 2.8 ms,
  p95 4.1 ms after the click (puppeteer dispatch included), 20/20 GPU
  answers. The Cesium harness keeps the first-run card closed.
This commit is contained in:
German Khokhlov committed 2026-10-16 18:25:12 +04:00
1 parent 86aa0bc9ba
commit b0cb8ce881
26 files changed
+1267 -68

No files matched your search

+118
View File
@@ -0,0 +1,118 @@
// Picks on Navara. A click is answered by Navara's own GPU pick of the same
// gesture (`featureClick`, a frame or two after the click, null over empty
// space): its batch id resolves to the mover set and instance (pickIds.js).
// Lines are not in the GPU pick, so an empty GPU answer still checks them
// on the CPU; no answer within the timeout falls back to the CPU pick.
// Hover (move with pick), drill and the synchronous picker.pick are CPU
// picks (src/globe/cpuPicks.js). No three.
import { createCpuPicker } from '../cpuPicks.js';
export { distanceToSegment } from '../cpuPicks.js';
const CLICK_TIMEOUT_MS = 250;
// A GPU answer this recent belongs to the click being delivered.
const EARLY_ANSWER_MS = 100;
/**
* @param {{
* view: { on: Function, off: Function },
* projector: { worldToWindow: Function, horizonVisible: Function },
* camera: { livePosition: object },
* movers: () => { options: object, store: object }[],
* lines: () => { options: object, flat: Float64Array, modelMatrix: number[] | null }[],
* resolveBatch: (batchId: number) => ({ set: string, instance: number, pickId: any } | null),
* setTimeout?: Function, clearTimeout?: Function, timeoutMs?: number,
* }} ports
*/
export function createNavaraPicking({
view,
projector,
camera,
movers,
lines,
resolveBatch,
setTimeout: later = globalThis.setTimeout,
clearTimeout: cancel = globalThis.clearTimeout,
timeoutMs = CLICK_TIMEOUT_MS,
now = () => performance.now(),
}) {
const drillPick = createCpuPicker({ projector, camera, movers, lines });
// Clicks waiting for Navara's GPU answer, oldest first.
const waiting = [];
// Diagnostics: how clicks were answered and how long it took (ms).
const stats = { gpu: 0, timeout: 0, stale: 0, latencies: [] };
const answered = (entry, how) => {
stats[how]++;
stats.latencies.push(now() - entry.startedAt);
if (stats.latencies.length > 200) stats.latencies.shift();
};
// Navara 0.2.1 answers clicks in quick succession (within a frame or so)
// with the first click's pick: a GPU answer whose instance is not drawn
// near the click is stale, and the CPU pick answers instead.
const answerFrom = (info, at) => {
const hit = info ? resolveBatch(info.batchId) : null;
if (hit && !drillPick.near(hit.set, hit.instance, at)) {
stats.stale++;
return drillPick(at, 1)[0];
}
return hit
? { id: hit.pickId, owner: hit.set, instance: hit.instance }
: drillPick(at, 1, { includeMovers: false })[0];
};
// Navara's pick helper listens to the same pointerup and, registered
// first, usually answers before the engine's click: that answer waits
// here, for the click of the same gesture.
let early = null;
const onFeatureClick = (info) => {
const next = waiting.shift();
if (!next) {
early = { info, at: now() };
return;
}
cancel(next.timer);
answered(next, 'gpu');
next.resolve(answerFrom(info, next.at));
};
view.on('featureClick', onFeatureClick);
return {
pick: (at) => drillPick(at, 1)[0],
drillPick: (at, limit) => drillPick(at, limit ?? Infinity),
/** The answer for a click at `at`: the GPU pick of its gesture. */
clickPick(at) {
const gesture = early;
early = null;
if (gesture && now() - gesture.at <= EARLY_ANSWER_MS) {
const entry = { startedAt: gesture.at };
answered(entry, 'gpu');
return Promise.resolve(answerFrom(gesture.info, at));
}
return new Promise((resolve) => {
const entry = {
at: { x: at.x, y: at.y },
resolve,
timer: null,
startedAt: now(),
};
entry.timer = later(() => {
const index = waiting.indexOf(entry);
if (index >= 0) waiting.splice(index, 1);
answered(entry, 'timeout');
resolve(drillPick(entry.at, 1)[0]);
}, timeoutMs);
waiting.push(entry);
});
},
/** How clicks were answered: GPU picks, timeouts, recent latencies (ms). */
clickStats: () => ({ ...stats, latencies: [...stats.latencies] }),
destroy() {
view.off('featureClick', onFeatureClick);
for (const entry of waiting.splice(0)) {
cancel(entry.timer);
entry.resolve(undefined);
}
},
};
}