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.
This commit is contained in:
Sameh Khamis committed 2026-11-15 17:03:09 -08:00
1 parent a0d299523d
commit 0ab31d4fb8
130 files changed
+5438 -1674

No files matched your search

+58
View File
@@ -0,0 +1,58 @@
/**
* The stub renderer's camera (`camera.js`): the reference camera's poses,
* views, flights and events in plain maths, which a renderer of its own can
* build its camera port on.
*/
import type { CameraPort, Ecef, GeoRect, Vec3 } from '../contract/index';
/** The eye in world (ECEF) terms. */
export interface StubEye {
position: Ecef;
direction: Vec3;
up: Vec3;
right: Vec3;
/** Vertical field of view, radians. */
fovy: number;
aspectRatio: number;
near: number;
}
export interface StubCamera {
port: CameraPort;
/** Ends a flight in progress as cancelled, without announcing a command. */
endFlight(): void;
/** One frame's camera steps, run in the contract's order. */
steps: {
stepFlight(): void;
stepChanged(): void;
stepFollow(): void;
stepMoveDetection(): void;
};
eye(): StubEye;
/** The reasons camera controls are held for. */
holds(): string[];
/** The frame the eye is in, column-major from it to the world. */
eyeFrame(): Float64Array;
/** Puts `viewRectangle` on the port. */
setViewRectangle(fn: () => GeoRect | null): void;
}
export function createStubCamera(options: {
/** CSS size. */
viewport: () => { width: number; height: number };
/** The clock, ms. */
now: () => number;
/** Scene time, epoch ms. */
sceneTime: () => number;
requestRender: (reason: string) => void;
report: (error: Error) => void;
/** Where a drawn item is, `aheadMs` on, for a follow of it. */
drawnPosition?: (
item: { set: string; id: string },
aheadMs: number,
) => Ecef | null;
/** `cameraChangeThreshold` (default true). */
thresholds?: boolean;
/** `keepEarthFramed` (default false). */
framing?: boolean;
}): StubCamera;
+4
View File
@@ -0,0 +1,4 @@
/** The stub renderer as the conformance suite's renderer under test. */
import type { ConformanceHarness } from '../conformance/index';
export function createStubHarness(name?: string): ConformanceHarness;
+18 -2
View File
@@ -9,10 +9,26 @@ import { toEcef } from './math.js';
/** @returns {import('../conformance/index.js').ConformanceHarness} */
export function createStubHarness(name = 'stub') {
// Each renderer's container: a stand-in that says its size, which the
// stub's `resize` follows.
const containers = new WeakMap();
return {
name,
create: async ({ viewport, capabilities }) =>
createStubRenderer({ viewport, capabilities }),
create: async ({ viewport, capabilities }) => {
const container = {
clientWidth: viewport.width,
clientHeight: viewport.height,
};
const r = createStubRenderer({ viewport, capabilities, container });
containers.set(r, container);
return r;
},
resizeContainer: (r, { width, height }) => {
const container = containers.get(r);
if (!container) return;
container.clientWidth = width;
container.clientHeight = height;
},
frame: (r) => {
r.testing.tick();
},
+71 -8
View File
@@ -14,6 +14,12 @@ import { alongLength } from '../../geo/polyline.js';
import { clusterScreenPoints } from '../../geo/screenCluster.js';
import { createInputRouter } from '../input/router.js';
import { cssColor } from '../color.js';
import {
recedeFactors,
recedeFrame,
recedeParams,
recededAlpha,
} from '../recession.js';
import { CLEAR_WEATHER, mergeWeather } from '../weather.js';
import { CAPABILITIES, CONTRACT_VERSION } from '../contract/index.js';
import { createStubCamera } from './camera.js';
@@ -154,7 +160,9 @@ function createCanvas(container, viewport) {
* @param {object} [options]
* @param {Iterable<import('../contract/common').Capability>} [options.capabilities] Default: all.
* @param {HTMLElement} [options.container] In a page: the element the stub's
* canvas fills, as a plugin's `CreateOptions.container`.
* canvas fills, as a plugin's `CreateOptions.container`. Elsewhere, an
* object that says a size (`clientWidth`, `clientHeight`): `resize`
* follows it.
* @param {{width: number, height: number}} [options.viewport] CSS size; default 1280 × 720.
* @param {number} [options.time] Scene time, epoch ms.
* @returns {import('../contract/renderer').Renderer & {testing: StubTesting}}
@@ -183,6 +191,7 @@ export function createStubRenderer(options = {}) {
// The frame under way while its `preUpdate` listeners run.
let updating = null;
const onceWaiters = [];
const destroyedError = () => new Error('renderer destroyed');
const onceTimers = new Set();
const stepLog = [];
@@ -296,6 +305,11 @@ export function createStubRenderer(options = {}) {
// A frame each timed layer was asked to show is now drawn.
for (const [layer, flush] of [...frameFlushes])
if (frameFlushes.get(layer) === flush) flush();
// The imagery added since the last frame is drawn: loaded.
if (imageryLoading > 0) {
imageryLoading = 0;
announceProgress();
}
step('postRender');
runPhase('postRender', t);
for (const waiter of onceWaiters.splice(0)) waiter();
@@ -351,12 +365,15 @@ export function createStubRenderer(options = {}) {
tick();
},
renderOnce({ timeoutMs } = {}) {
if (destroyed) return Promise.reject(destroyedError());
requestRender('renderOnce');
return new Promise((resolve, reject) => {
let timer = null;
const waiter = () => {
// Called with an error when the renderer is destroyed first.
const waiter = (error) => {
clearTimeout(timer);
resolve();
if (error) reject(error);
else resolve();
};
onceWaiters.push(waiter);
if (timeoutMs !== undefined)
@@ -405,6 +422,7 @@ export function createStubRenderer(options = {}) {
};
sets.set(spec.id, record);
log('draw', kind, [spec]);
const gone = () => destroyed || sets.get(spec.id) !== record;
// A model is ready once per load: when it is new or its url changes,
// not when it is moved or restyled. One under the failing scheme fails
// its load instead, unless it came with its bytes (`gltf`).
@@ -490,6 +508,9 @@ export function createStubRenderer(options = {}) {
dispose() {
// A newer set under the same id is not this handle's to remove.
if (sets.get(spec.id) === record) sets.delete(spec.id);
// Its listeners hear nothing more, even mid-delivery.
for (const entry of record.readyListeners) entry.live = false;
for (const entry of record.loadFailedListeners) entry.live = false;
requestRender('draw');
},
};
@@ -529,10 +550,20 @@ export function createStubRenderer(options = {}) {
const call = handle[name];
if (!call) continue;
handle[name] = (...args) => {
// Disposed, or its renderer destroyed, it does nothing.
if (gone()) return;
record.version += 1;
return call(...args);
};
}
const { set: showSet } = Object.getOwnPropertyDescriptor(handle, 'show');
Object.defineProperty(handle, 'show', {
get: () => record.show,
set(value) {
if (!gone()) showSet.call(handle, value);
},
enumerable: true,
});
return handle;
}
@@ -774,12 +805,17 @@ export function createStubRenderer(options = {}) {
/**
* The shown models as the stub draws them: a square as wide as a pick
* takes (at most `maxPixelSize`, at least `minPixelSize`), far
* ones first, in white shading blended with the tint by `colorBlend`.
* ones first, in white shading blended with the tint by `colorBlend`,
* over black at the tint's alpha times the model's emphasis (its `focus`,
* composed with the haze in a set that recedes).
*/
function modelSquares() {
const squares = [];
const eyeHeight = toCartographicRadians(eye().position).height;
for (const set of sets.values()) {
if (set.kind !== 'models' || !set.show) continue;
const recede = recedeParams(set.spec.recede);
const frame = recede ? recedeFrame(eyeHeight, recede) : null;
for (const item of set.items.values()) {
if (item.show === false) continue;
const p = itemPosition(set, item);
@@ -795,20 +831,33 @@ export function createStubRenderer(options = {}) {
let side = 10;
if (item.maxPixelSize > 0) side = Math.min(side, item.maxPixelSize);
side = Math.max(side, item.minPixelSize ?? 0);
const focus = Number.isFinite(item.focus)
? Math.min(1, Math.max(0, item.focus))
: 1;
const emphasis = recede
? recededAlpha(
focus,
recedeFactors(distance, frame, recede).alpha,
recede,
)
: focus;
squares.push({
x: s.x,
y: s.y,
half: side / 2,
distance,
rgba: modelColor(item),
rgba: modelColor(item, emphasis),
});
}
}
return squares.sort((a, b) => b.distance - a.distance);
}
/** A model's colour: white shading, the tint blended in by `colorBlend`. */
function modelColor(item) {
/**
* A model's colour: white shading, the tint blended in by `colorBlend`,
* over black at the tint's alpha times `emphasis`.
*/
function modelColor(item, emphasis = 1) {
const shaded = [1, 1, 1];
const tint =
item.tint === undefined || item.tint === null
@@ -829,7 +878,8 @@ export function createStubRenderer(options = {}) {
amount === null ? c * tint[i] : c + (tint[i] - c) * amount,
);
}
return [...rgb.map((c) => Math.round(c * 255)), 255];
const alpha = (tint ? (tint[3] ?? 1) : 1) * emphasis;
return [...rgb.map((c) => Math.round(c * alpha * 255)), 255];
}
/** Where a drawn item is now (or `aheadMs` from now), or null. */
@@ -1431,6 +1481,15 @@ export function createStubRenderer(options = {}) {
/** Each timed layer's announcement of the frame it drew, run after a render. */
const frameFlushes = new Map();
const progressListeners = [];
/** Imagery added since the last drawn frame: loading until it is drawn. */
let imageryLoading = 0;
function announceProgress() {
deliver(progressListeners, {
tilesPending: 0,
imageryPending: imageryLoading,
terrainPending: 0,
});
}
const settled = { base: true, tiles: true, terrain: true, imagery: true };
let sky = {
atmosphere: true,
@@ -1555,6 +1614,8 @@ export function createStubRenderer(options = {}) {
else imageryLayers.splice(index, 0, layer);
log('globe', 'imagery.add', [spec, index]);
requestRender('imagery');
imageryLoading += 1;
announceProgress();
return layer;
}
@@ -1911,6 +1972,7 @@ export function createStubRenderer(options = {}) {
credits,
quality,
async capture(opts = {}) {
if (destroyed) throw destroyedError();
return new Blob([], { type: `image/${opts.type ?? 'png'}` });
},
readPixels(opts = {}) {
@@ -1980,6 +2042,7 @@ export function createStubRenderer(options = {}) {
if (options.container) canvas.remove?.();
for (const clear of onceTimers) clear();
onceTimers.clear();
for (const waiter of onceWaiters.splice(0)) waiter(destroyedError());
sets.clear();
sceneFrameLayers.clear();
frameFlushes.clear();
+67 -1
View File
@@ -20,7 +20,7 @@ test('the stub passes the conformance suite', async () => {
.filter((r) => r.status === 'skip')
.map((r) => r.id);
// It draws only models into pixels, so the sweep's, a lit shape's, a line outline's, a
// split line's, a draped outlined line's and the blends' (over a drawn shape), video tiles' and the weather's pixels (drawn, and by scene time) go unread; its camera takes no user gestures: the drag and wheel scripts are for a
// split line's, a draped outlined line's and the blends' (over a drawn shape), video tiles', the weather's pixels (drawn, and by scene time) and an encoded capture go unread; its camera takes no user gestures: the drag and wheel scripts are for a
// camera that does (a controller over it, say).
assert.deepEqual(skipped, [
'effects.screenModulation.pixels',
@@ -33,6 +33,8 @@ test('the stub passes the conformance suite', async () => {
'globe.imagery.video',
'globe.weather.drawn',
'globe.weather.sceneTime',
'renderer.capture',
'effects.setStyleParams',
...CAMERA_SCRIPTS.filter(usesInput).map((s) => `camera.trace.${s.name}`),
]);
});
@@ -346,3 +348,67 @@ test('a lit-shape check that fails still shows the globe again', async () => {
assert.equal(report.results[0].status, 'fail');
assert.deepEqual(shown, [true]);
});
/** One check over the stub with `change` made to each renderer it makes. */
async function checkWith(id, change, extra = {}) {
const base = createStubHarness();
const report = await runConformance(
{
...base,
...extra,
create: async (options) => {
const r = await base.create(options);
change(r);
return r;
},
},
{ only: (c) => c === id },
);
return report.results[0];
}
test('the resize check fails a renderer whose resize does not follow its container', async () => {
assert.equal((await checkWith('renderer.resize', () => {})).status, 'pass');
const result = await checkWith('renderer.resize', (r) => {
r.resize = () => {};
});
assert.equal(result.status, 'fail', result.detail);
});
test('the progress check fails a renderer that never says what it loads', async () => {
assert.equal((await checkWith('globe.progress', () => {})).status, 'pass');
const result = await checkWith('globe.progress', (r) => {
r.globe.on = () => () => {};
});
assert.equal(result.status, 'fail', result.detail);
});
test('the after-destroy check fails a renderer whose sets keep items once it is destroyed', async () => {
assert.equal(
(await checkWith('renderer.afterDestroy', () => {})).status,
'pass',
);
const result = await checkWith('renderer.afterDestroy', (r) => {
const points = r.draw.points;
r.draw.points = (spec) => {
const set = points(spec);
let held = 0;
set.set = (items) => (held = items.length);
set.upsert = (items) => (held += items.length);
set.size = () => held;
return set;
};
});
assert.equal(result.status, 'fail', result.detail);
});
test('the stub keeps a set’s `recede` as given and as changed', () => {
const r = createStubRenderer({ capabilities: ['models'] });
r.draw.icons({ id: 'i', recede: { scaleFloor: 0.6 } });
const models = r.draw.models({ id: 'm', recede: {} });
assert.deepEqual(r.testing.setRecord('i').spec.recede, { scaleFloor: 0.6 });
assert.deepEqual(r.testing.setRecord('m').spec.recede, {});
models.setOptions({ recede: null });
assert.equal(r.testing.setRecord('m').spec.recede, null);
r.destroy();
});
+8
View File
@@ -0,0 +1,8 @@
/** The view rectangle of a pose, as the reference camera measures it. */
import type { CameraPose, Ecef, GeoRect } from '../contract/index';
export function computeViewRectangle(
pose: CameraPose,
viewport: { width: number; height: number },
pickEllipsoid: (x: number, y: number) => Ecef | null,
): GeoRect | null;