Bound drillPick's work, pick before styles, and put changed thresholds behind a capability

The query contract now says picks answer against the scene as drawn before
effects, and that a drillPick limit bounds the work as well as the answer:
the renderer stops at `limit` hits and looks through at most
max(limit, 16) things under the pointer. The Cesium query port passes that
depth to Cesium's drill (a pick looking under something unpickable stays
unbounded), a click's drill caches one pass per depth, and the stub counts
unpickable items toward the depth.

CameraPose says fovy and aspectRatio describe the nearest centred
perspective frustum, the exact projection being in matrices().

A changed listener's own threshold is now the capability
cameraChangeThreshold; without it every listener fires at 0.5. The Cesium
and stub cameras have it, measured per listener without touching Cesium's
shared percentageChanged.

Conformance: draw.drillPick checks limit 0, never the surface, nothing over
the bare globe, an unpickable cover, nearest first and a bounded prefix;
query.pickBeforeStyles picks an icon under a mirroring style; the threshold
trace is skipped without its capability.
This commit is contained in:
Sameh Khamis committed 2026-11-08 12:37:04 -08:00
1 parent 481df0b093
commit 45302e9fbf
19 files changed
+260 -40

No files matched your search

+4 -1
View File
@@ -101,10 +101,13 @@ export function createCesiumCamera({
const removers = [];
// Camera events: Cesium's own moveStart and moveEnd (500 ms after the
// last change, never while following), and `changed` measured per
// listener on every tick, where Cesium measures its single threshold.
// listener on every tick, where Cesium measures its single threshold
// (`camera.percentageChanged`, which this leaves as it is for everyone
// else listening to Cesium's own event).
const cameraEvents = createCameraEvents({
pose: () => cameraPort.pose(),
report,
thresholds: capabilities?.has('cameraChangeThreshold') ?? true,
});
removers.push(
scene.postUpdate.addEventListener(() => {
+3 -1
View File
@@ -52,11 +52,13 @@ function headlessHarness(clock) {
scene.primitives = { add() {}, remove() {} };
scene.requestRender = () => {};
clock.now = 0;
const capabilities = new Set(['cameraChangeThreshold']);
const ports = createCesiumPorts(
{ scene, clock: { currentTime: Cesium.JulianDate.now() } },
{ capabilities: new Set() },
{ capabilities },
);
return {
capabilities,
camera: ports.camera,
query: ports.query,
destroy: () => ports.dispose(),
+1
View File
@@ -83,6 +83,7 @@ export const CESIUM_CHECKS = new Set([
'input.lease.grab',
'input.lease.press',
'query.heights',
'query.pickBeforeStyles',
'query.heights.sets',
'query.projectMany',
'query.rays',
+14 -16
View File
@@ -257,7 +257,7 @@ export function createCesiumInput(
let picked = false;
let ground;
let grounded = false;
/** @type {Map<string, {limit: number, hits: object[]}>} */
/** @type {Map<string, object[]>} */
const drills = new Map();
ev.pick = () => {
if (!picked) {
@@ -269,22 +269,20 @@ export function createCesiumInput(
ev.drill = (options = {}) => {
const { limit, ...window } = options;
const want = limit ?? Infinity;
const key = `${window.width ?? ''}x${window.height ?? ''}:${window.purpose ?? ''}`;
let pass = drills.get(key);
// A pass that found fewer than it asked for found everything.
if (!pass || (pass.hits.length >= pass.limit && want > pass.limit)) {
const depth =
want === Infinity ? Infinity : Math.max(want, DRILL_DEPTH);
pass = {
limit: depth,
hits: query.drillPick(x, y, {
...window,
...(depth === Infinity ? {} : { limit: depth }),
}),
};
drills.set(key, pass);
// 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 ? pass.hits.slice() : pass.hits.slice(0, want);
return want === Infinity ? hits.slice() : hits.slice(0, want);
};
ev.ground = () => {
if (!grounded) {
+4 -1
View File
@@ -203,7 +203,10 @@ test('a click carries its gesture and one pick, drill and ground', () => {
ev.drill().map((h) => h.id),
['a', 'b', 'c'],
);
assert.equal(s.passes.drill, 1, 'a short pass found everything');
// Each depth is a pass of its own: a bounded one looks only so deep.
assert.equal(s.passes.drill, 2, 'a bounded pass is drilled again for more');
ev.drill({ limit: 2 });
assert.equal(s.passes.drill, 2, 'the same depth is drilled once');
assert.deepEqual(ev.ground(), { x: 1, y: 2, z: 3 });
s.handler.fire(T.LEFT_CLICK, { position: s.at(3, 4) });
assert.deepEqual(
+1
View File
@@ -63,6 +63,7 @@ export function cesiumCapabilities(scene, only) {
'quads',
'meshes',
'followFrame',
'cameraChangeThreshold',
...GPU_ICON_CAPABILITIES,
'styles',
'bloom',
+25 -1
View File
@@ -11,6 +11,7 @@ import { updateCameraChanged } from './internals.js';
test('capabilities follow what the scene supports', () => {
const effects = [
'followFrame',
'cameraChangeThreshold',
'columns',
'motionSegments',
'courseGlide',
@@ -568,7 +569,9 @@ test('changed fires per listener, at each threshold as Cesium would', () => {
];
const { widget, scene, raise } = tickingWidget();
cityView(scene.camera);
const ports = createCesiumPorts(widget, { capabilities: all });
const ports = createCesiumPorts(widget, {
capabilities: new Set([...all, 'cameraChangeThreshold']),
});
const counts = { 0.5: 0, 0.1: 0 };
for (const t of [0.5, 0.1])
ports.camera.on('changed', () => (counts[t] += 1), { threshold: t });
@@ -583,6 +586,27 @@ test('changed fires per listener, at each threshold as Cesium would', () => {
ports.dispose();
});
test('without cameraChangeThreshold every changed listener fires at 0.5', () => {
const steps = Array.from({ length: 24 }, () => (c) => c.lookRight(0.05));
const { widget, scene, raise } = tickingWidget();
cityView(scene.camera);
const before = scene.camera.percentageChanged;
const ports = createCesiumPorts(widget, { capabilities: all });
const counts = { 0.5: 0, 0.1: 0 };
for (const t of [0.5, 0.1])
ports.camera.on('changed', () => (counts[t] += 1), { threshold: t });
raise('postUpdate');
for (const step of steps) {
step(scene.camera);
raise('postUpdate');
}
assert.equal(counts[0.1], counts[0.5], JSON.stringify(counts));
assert.equal(counts[0.5], cesiumChangedCount(0.5, steps));
// Cesium's own threshold, shared with everyone else, is left as it was.
assert.equal(scene.camera.percentageChanged, before);
ports.dispose();
});
test('camera events: Cesium’s moves relayed, a throw reported, off and dispose stop them', () => {
const { widget, scene, raise } = tickingWidget();
cityView(scene.camera);
+16 -3
View File
@@ -18,6 +18,9 @@ import { toCartesian } from './common.js';
import { unboundDrawPart } from './draw.js';
import { drawHitOf } from './drawHit.js';
/** The fewest things a bounded drill looks through (`QueryPort.drillPick`). */
const DRILL_DEPTH = 16;
/**
* The query capabilities a Cesium scene has: depth picks, height samples
* and ray casts all need depth textures, which `pickPositionSupported` and
@@ -80,15 +83,24 @@ export function createCesiumQuery({
* The pickable draw-set items under a pixel, nearest first, once each (a
* shape's fill and outline share one id). `untilForeign` stops at the first
* thing that is not a draw-set item (a tile, the app's own primitives):
* what is behind it is hidden.
* what is behind it is hidden. With a `limit`, Cesium looks through at
* most `max(limit, 16)` things of any kind (each a pick pass), as the
* contract bounds the work; without one, or with `unbounded` (a `pick`
* looking under something unpickable), it picks until nothing is left.
*/
function drill(x, y, { width = 3, height = 3, limit, untilForeign } = {}) {
function drill(
x,
y,
{ width = 3, height = 3, limit, untilForeign, unbounded = false } = {},
) {
const hits = [];
if (limit === 0) return hits;
const seen = new Set();
for (const picked of scene.drillPick(
screen(x, y),
undefined,
limit === undefined || unbounded
? undefined
: Math.max(limit, DRILL_DEPTH),
width,
height,
)) {
@@ -269,6 +281,7 @@ export function createCesiumQuery({
...window,
limit: 1,
untilForeign: true,
unbounded: true,
});
if (under) return under;
}