Files
gods-eye-view/src/render/stub/index.js
T
Sameh Khamis f9749ac83c Redefine the modulation sector: a sweep over markers with a reach and a floor
ModulationSector gains radius and floor and says what it dims and what it
leaves alone; picks are unchanged and setting or clearing a sector asks
for one frame. The stub names its pass screenModulation, and a
conformance check covers the pass, the frame request and the pick.
2026-11-08 14:37:59 -08:00

1633 lines
52 KiB
JavaScript
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
/**
* @module render/stub
* @description A renderer that draws nothing: every port of the contract in
* memory, with exact camera poses, a scripted clock, picks against what was
* drawn (or a scripted table), scripted heights, and a log of calls.
*
* Tests across the repository use it in place of a real renderer, and the
* suite runs against it, so the stub is itself checked against the contract.
* Nothing runs on its own: `testing.tick()` and `testing.advance()` drive the
* loop on a virtual clock, one frame at a time, in the contract's order.
*/
import { horizonFrom } from '../../geo/horizon.js';
import { alongLength } from '../../geo/polyline.js';
import { createInputRouter } from '../input/router.js';
import { cssColor } from '../color.js';
import { CAPABILITIES, CONTRACT_VERSION } from '../contract/index.js';
import { createStubCamera } from './camera.js';
import { motionPosition } from '../motion/iconMotion.js';
import { orbitPosition } from './orbits.js';
import { computeViewRectangle } from './viewRectangle.js';
import {
add,
dot,
magnitude,
normalize,
rayEllipsoid,
scale,
sub,
toCartographicRadians,
toDegrees,
toEcef,
vec,
} from './math.js';
const FRAME_MS = 1000 / 60;
/**
* Model urls under this scheme fail to load (`loadFailed`), so tests can
* see a failure; the stub loads nothing, and every other url is a model.
*/
export const STUB_FAILING_MODEL_SCHEME = 'stub-fail:';
/** Every setting the stub accepts, with its descriptor. */
const KNOBS = Object.freeze([
{ key: 'pixelRatio', kind: 'number', min: 0, max: 4, default: 0, cost: 1 },
{ key: 'msaa', kind: 'enum', options: [0, 2, 4, 8], default: 4, cost: 0.4 },
{
key: 'tiles3dDetail',
kind: 'number',
min: 0,
max: 1,
default: 1,
cost: 0.8,
couples: ['lower detail lowers height accuracy'],
},
{
key: 'terrainDetail',
kind: 'number',
min: 0,
max: 1,
default: 1,
cost: 0.4,
},
{
key: 'imageryDetail',
kind: 'number',
min: 0,
max: 1,
default: 1,
cost: 0.3,
},
{ key: 'particles', kind: 'number', min: 0, max: 1, default: 1, cost: 0.3 },
{ key: 'targetFps', kind: 'number', min: 0, max: 240, default: 0, cost: 0.2 },
]);
/** A distance curve's value at `distance`: held past each end. */
function nearFarValue(curve, distance) {
if (distance <= curve.near) return curve.nearValue;
if (distance >= curve.far) return curve.farValue;
const t = (distance - curve.near) / (curve.far - curve.near);
return curve.nearValue + (curve.farValue - curve.nearValue) * t;
}
function uncaught(error) {
if (typeof globalThis.reportError === 'function')
globalThis.reportError(error);
else
queueMicrotask(() => {
throw error;
});
}
/**
* @param {object} [options]
* @param {Iterable<import('../contract/common').Capability>} [options.capabilities] Default: all.
* @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}}
*/
export function createStubRenderer(options = {}) {
const capabilities = new Set(options.capabilities ?? CAPABILITIES);
const viewport = { width: 1280, height: 720, ...(options.viewport ?? {}) };
const calls = [];
const log = (port, member, args) => calls.push({ port, member, args });
const rendererListeners = { error: [], contextLost: [], contextRestored: [] };
let clock = 0;
let sceneTime = options.time ?? Date.UTC(2026, 0, 1);
// Wall time is the virtual clock from a fixed epoch, so live motion is scripted too.
const wallEpoch = options.wallTime ?? Date.UTC(2026, 0, 1);
const wallTime = () => wallEpoch + clock;
let frameCount = 0;
let rendered = 0;
let suspended = false;
let targetFps = 0;
let destroyed = false;
const pendingReasons = [];
const continuous = new Map();
let holdSeq = 0;
const phaseListeners = { preUpdate: [], preRender: [], postRender: [] };
const onceWaiters = [];
const onceTimers = new Set();
const stepLog = [];
/**
* Hands a listener's throw to the `error` listeners. With none, it goes to
* the platform's `reportError` (or is rethrown on a microtask), as a
* browser reports an event listener's exception: loud, but the frame and
* the other listeners carry on.
*/
function report(error) {
const errorListeners = rendererListeners.error;
if (!errorListeners.length) return uncaught(error);
for (const entry of errorListeners.slice()) {
// One removed during delivery does not run, as everywhere.
if (!entry.live) continue;
try {
entry.cb(error);
} catch (thrown) {
uncaught(thrown);
}
}
}
/**
* Calls each listener in `list` (callbacks, or `{cb, live}` entries) with
* the contract's rules: one removed during delivery does not run, one
* added during delivery waits for the next event, and one that throws is
* reported while the rest still run.
*/
function deliver(list, ...args) {
for (const entry of list.slice()) {
const fn = typeof entry === 'function' ? entry : entry.cb;
if (typeof entry === 'function' ? !list.includes(entry) : !entry.live)
continue;
try {
fn(...args);
} catch (error) {
report(error);
}
}
}
function requestRender(reason) {
if (!pendingReasons.includes(reason)) pendingReasons.push(reason);
}
const camera = createStubCamera({
viewport: () => viewport,
now: () => clock,
sceneTime: () => sceneTime,
requestRender,
report,
drawnPosition: (ref, aheadMs) => drawnPosition(ref, aheadMs),
thresholds: capabilities.has('cameraChangeThreshold'),
});
camera.setViewRectangle(viewRectangle);
if (capabilities.has('followFrame'))
camera.port.followFrame = camera.eyeFrame;
camera.port.setView({
destination: { lon: -97.7431, lat: 30.2672, height: 15000000 },
});
pendingReasons.length = 0;
// --- Frame -----------------------------------------------------------------
function runPhase(phase, t) {
deliver(phaseListeners[phase], t);
}
const signalListeners = [];
function tick() {
if (destroyed || suspended) return false;
clock += FRAME_MS;
frameCount += 1;
stepLog.length = 0;
const step = (name) => stepLog.push(name);
step('flight');
camera.steps.stepFlight();
step('input');
step('changed');
camera.steps.stepChanged();
step('follow');
camera.steps.stepFollow();
const rendering = pendingReasons.length > 0 || continuous.size > 0;
const t = {
frame: frameCount,
time: sceneTime,
now: clock,
dt: FRAME_MS / 1000,
rendering,
};
step('preUpdate');
runPhase('preUpdate', t);
step('moveDetection');
camera.steps.stepMoveDetection();
if (!rendering) return false;
const requested = pendingReasons.length > 0;
pendingReasons.length = 0;
step('preRender');
runPhase('preRender', t);
step('render');
rendered += 1;
// A frame each timed layer was asked to show is now drawn.
for (const [layer, flush] of [...frameFlushes])
if (frameFlushes.get(layer) === flush) flush();
step('postRender');
runPhase('postRender', t);
for (const waiter of onceWaiters.splice(0)) waiter();
const signals = {
cpuMs: 0,
pixelRatio: qualitySettings.pixelRatio || 1,
width: viewport.width,
height: viewport.height,
mode: 'demand',
requested,
holds: [...continuous.values()],
drawCalls: sets.size,
};
deliver(signalListeners, signals);
return true;
}
const frame = {
on(phase, cb) {
const entry = { cb, live: true };
phaseListeners[phase].push(entry);
return () => {
entry.live = false;
const list = phaseListeners[phase];
const i = list.indexOf(entry);
if (i >= 0) list.splice(i, 1);
};
},
requestRender(reason) {
requestRender(String(reason));
},
holdContinuous(reason) {
const key = ++holdSeq;
continuous.set(key, String(reason));
return () => continuous.delete(key);
},
mode: () => 'demand',
diagnostics: () => ({
mode: 'demand',
frames: frameCount,
rendered,
pendingReasons: pendingReasons.slice(),
holds: [...continuous.values()],
suspended,
targetFps,
}),
suspend(hidden) {
suspended = Boolean(hidden);
},
renderNow() {
requestRender('renderNow');
tick();
},
renderOnce({ timeoutMs } = {}) {
requestRender('renderOnce');
return new Promise((resolve, reject) => {
let timer = null;
const waiter = () => {
clearTimeout(timer);
resolve();
};
onceWaiters.push(waiter);
if (timeoutMs !== undefined)
timer = setTimeout(() => {
const i = onceWaiters.indexOf(waiter);
if (i >= 0) onceWaiters.splice(i, 1);
reject(new Error('renderOnce timed out'));
}, timeoutMs);
onceTimers.add(() => clearTimeout(timer));
});
},
setTargetFps(fps) {
targetFps = fps;
},
setTime(ms) {
sceneTime = ms;
for (const show of [...sceneFrameLayers.values()]) show(ms);
requestRender('time');
},
time: () => sceneTime,
};
// --- Draw ------------------------------------------------------------------
/** @type {Map<string, {kind: string, spec: object, items: Map<string, object>, columns: object|null, show: boolean, ready: Function[]}>} */
const sets = new Map();
const atlases = new Map();
let setSeq = 0;
function makeSet(kind, spec) {
if (!spec?.id) throw new TypeError('A draw set needs an id');
if (sets.has(spec.id))
throw new Error(`Draw set ${spec.id} already exists`);
const record = {
kind,
spec: { ...spec },
// When it was made: of sets of one `drawOrder`, the earlier is on top.
seq: (setSeq += 1),
items: new Map(),
show: spec.show ?? true,
readyListeners: [],
loadFailedListeners: [],
};
sets.set(spec.id, record);
log('draw', kind, [spec]);
// 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.
// Each load is told once: a listener that starts another load of the
// same item (or removes it) supersedes the one queued here.
const loadTokens = new Map();
const loads = (items) =>
kind === 'models'
? items
.filter(
(item) => record.items.get(String(item.id))?.url !== item.url,
)
.map((item) => {
const token = {};
loadTokens.set(String(item.id), token);
return [String(item.id), token];
})
: [];
const ready = (loading) => {
for (const [id, token] of loading) {
if (loadTokens.get(id) !== token || !record.items.has(id)) continue;
loadTokens.delete(id);
const url = String(record.items.get(id).url ?? '');
if (url.startsWith(STUB_FAILING_MODEL_SCHEME))
deliver(record.loadFailedListeners, id, `${url} does not load`);
else deliver(record.readyListeners, id);
}
};
const handle = {
id: spec.id,
set(items) {
const loading = loads(items);
record.items.clear();
for (const item of items)
record.items.set(String(item.id), { ...item });
requestRender('draw');
ready(loading);
},
upsert(items) {
const loading = loads(items);
for (const item of items)
record.items.set(String(item.id), { ...item });
requestRender('draw');
ready(loading);
},
remove(ids) {
for (const id of ids) record.items.delete(String(id));
requestRender('draw');
},
clear() {
record.items.clear();
requestRender('draw');
},
setOptions(patch) {
Object.assign(record.spec, patch);
if ('show' in patch) record.show = patch.show;
requestRender('draw');
},
size: () => record.items.size,
get show() {
return record.show;
},
set show(value) {
record.show = Boolean(value);
requestRender('draw');
},
on(event, cb) {
const list =
event === 'ready'
? record.readyListeners
: event === 'loadFailed'
? record.loadFailedListeners
: null;
if (!list) return () => {};
const entry = { cb, live: true };
list.push(entry);
return () => {
entry.live = false;
};
},
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);
requestRender('draw');
},
};
if (capabilities.has('columns'))
// Columns become rows like any other, so remove, size and picks see them.
handle.setColumns = (columns) => {
const next = new Map();
columns.ids.forEach((id, i) => {
const key = String(id);
const row = { ...(record.items.get(key) ?? { id: key }) };
const p = columns.positions;
if (p) row.pos = vec(p[i * 3], p[i * 3 + 1], p[i * 3 + 2]);
if (columns.courses) row.course = columns.courses[i];
if (columns.shown) row.show = columns.shown[i] !== 0;
if (columns.scales) row.scale = columns.scales[i];
if (columns.alphas) row.alpha = columns.alphas[i];
if (columns.colors)
row.color = [0, 1, 2, 3].map(
(k) => columns.colors[i * 4 + k] / 255,
);
if (columns.meta) row.meta = columns.meta[i];
next.set(key, row);
});
record.items = next;
requestRender('draw');
};
return handle;
}
function simpleHandle(kind, spec) {
const record = {
kind,
spec: { ...spec },
// When it was made: of sets of one `drawOrder`, the earlier is on top.
seq: (setSeq += 1),
items: new Map(),
show: true,
readyListeners: [],
};
sets.set(spec.id, record);
log('draw', kind, [spec]);
requestRender('draw');
const handle = {
get show() {
return record.show;
},
set show(value) {
record.show = Boolean(value);
requestRender('draw');
},
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);
requestRender('draw');
},
};
return handle;
}
const clampListeners = [];
const draw = {
icons: (spec) => makeSet('icons', spec),
points: (spec) => makeSet('points', spec),
lines: (spec) => makeSet('lines', spec),
shapes: (spec) => makeSet('shapes', spec),
atlas(id, images) {
atlases.set(id, { ...images });
log('draw', 'atlas', [id]);
},
// The stub drapes wherever it is asked to: it never falls back.
clampState: () => 'draped',
on(event, cb) {
if (event !== 'clampState') return () => {};
const entry = { cb, live: true };
clampListeners.push(entry);
return () => {
entry.live = false;
const i = clampListeners.indexOf(entry);
if (i >= 0) clampListeners.splice(i, 1);
};
},
};
if (capabilities.has('models'))
draw.models = (spec) => makeSet('models', spec);
if (capabilities.has('quads')) draw.quads = (spec) => makeSet('quads', spec);
if (capabilities.has('meshes'))
draw.meshes = (spec) => makeSet('meshes', spec);
if (capabilities.has('agents'))
draw.agents = (spec) => makeSet('agents', spec);
/** Parsed orbit elements, by line pair; cleared on destroy. */
const satrecs = new Map();
if (capabilities.has('orbits'))
draw.orbits = (spec) => makeSet('orbits', spec);
if (capabilities.has('fields'))
draw.field = (spec) => {
const handle = simpleHandle('field', spec);
const record = sets.get(spec.id);
// 'drawn': once the next render after the spec or an update has drawn
// it, while it shows.
const drawnListeners = [];
let owed = true;
const key = { field: spec.id };
frameFlushes.set(key, () => {
if (!owed || !record.show || sets.get(spec.id) !== record) return;
owed = false;
deliver(drawnListeners);
});
const dispose = handle.dispose;
handle.dispose = () => {
frameFlushes.delete(key);
for (const entry of drawnListeners) entry.live = false;
drawnListeners.length = 0;
dispose();
};
handle.update = (patch) => {
Object.assign(record.spec, patch);
owed = true;
requestRender('draw');
};
handle.on = (event, cb) => {
if (event !== 'drawn') return () => {};
const entry = { cb, live: true };
drawnListeners.push(entry);
return () => {
entry.live = false;
const i = drawnListeners.indexOf(entry);
if (i >= 0) drawnListeners.splice(i, 1);
};
};
return handle;
};
if (capabilities.has('celestial'))
draw.celestial = (spec) => simpleHandle('celestial', spec);
// --- Query -----------------------------------------------------------------
function eye() {
return camera.eye();
}
function project(position) {
const e = eye();
const v = sub(position, e.position);
const depth = dot(v, e.direction);
if (depth <= 0) return null;
const right = e.right;
const tanPhi = Math.tan(e.fovy * 0.5);
const tanTheta = e.aspectRatio * tanPhi;
const x = dot(v, right) / (depth * tanTheta);
const y = dot(v, e.up) / (depth * tanPhi);
return {
x: ((x + 1) / 2) * viewport.width,
y: ((1 - y) / 2) * viewport.height,
};
}
function pickRay(x, y) {
const e = eye();
const tanPhi = Math.tan(e.fovy * 0.5);
const tanTheta = e.aspectRatio * tanPhi;
const nx = (2 / viewport.width) * x - 1;
const ny = (2 / viewport.height) * (viewport.height - y) - 1;
const near = e.near;
const target = add(
add(
add(e.position, scale(e.direction, near)),
scale(e.right, nx * near * tanTheta),
),
scale(e.up, ny * near * tanPhi),
);
return {
origin: e.position,
direction: normalize(sub(target, e.position)),
};
}
function isOccluded(position) {
return !horizonFrom(eye().position).isPointVisible(position);
}
let scriptedPicks = null;
const heightCache = new Map();
let heightSource = null;
const cacheKey = (p, against = 'surface') =>
`${against}:${p.lon.toFixed(7)},${p.lat.toFixed(7)}`;
/** The time a set's motion segments are evaluated at. */
function motionTime(set) {
const clockSpec = set.spec.motionClock;
return clockSpec?.kind === 'scene'
? sceneTime
: wallTime() - (clockSpec?.delayMs ?? 0);
}
function itemPosition(set, item, aheadMs = 0) {
if (set.kind === 'orbits')
return item.tle
? orbitPosition(satrecs, item.tle, motionTime(set) + aheadMs)
: null;
if (!item.pos) return null;
const base = toEcef(item.pos);
if (
set.kind === 'icons' &&
item.motion &&
capabilities.has('motionSegments')
)
return motionPosition(item.motion, base, motionTime(set) + aheadMs);
return base;
}
/**
* 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`.
*/
function modelSquares() {
const squares = [];
for (const set of sets.values()) {
if (set.kind !== 'models' || !set.show) continue;
for (const item of set.items.values()) {
if (item.show === false) continue;
const p = itemPosition(set, item);
if (!p || isOccluded(p)) continue;
const distance = magnitude(sub(p, eye().position));
if (item.displayRange) {
const [nearM, farM] = item.displayRange;
if (distance < nearM || distance >= farM) continue;
}
const s = project(p);
if (!s) continue;
// The pixel floor wins over the cap, as Cesium's does.
let side = 10;
if (item.maxPixelSize > 0) side = Math.min(side, item.maxPixelSize);
side = Math.max(side, item.minPixelSize ?? 0);
squares.push({
x: s.x,
y: s.y,
half: side / 2,
distance,
rgba: modelColor(item),
});
}
}
return squares.sort((a, b) => b.distance - a.distance);
}
/** A model's colour: white shading, the tint blended in by `colorBlend`. */
function modelColor(item) {
const shaded = [1, 1, 1];
const tint =
item.tint === undefined || item.tint === null
? null
: typeof item.tint === 'string'
? cssColor(item.tint)
: item.tint;
let rgb = shaded;
if (tint) {
const mode = item.colorBlend?.mode ?? 'highlight';
const amount =
mode === 'replace'
? 1
: mode === 'mix'
? (item.colorBlend.amount ?? 0.5)
: null;
rgb = shaded.map((c, i) =>
amount === null ? c * tint[i] : c + (tint[i] - c) * amount,
);
}
return [...rgb.map((c) => Math.round(c * 255)), 255];
}
/** Where a drawn item is now (or `aheadMs` from now), or null. */
function drawnPosition(ref, aheadMs = 0) {
const set = sets.get(ref.set);
const item = set?.items.get(String(ref.id));
return set && item ? itemPosition(set, item, aheadMs) : null;
}
/**
* Whether `lon`, `lat` (degrees) is in a rectangle geometry, turned by its
* `rotation` about its centre in longitude and latitude.
*/
function inRectangle({ rect, rotation = 0 }, lon, lat) {
// A rectangle across the antimeridian runs east past 180°.
const span = rect.east - rect.west;
const width = span >= 360 ? 360 : ((span % 360) + 360) % 360;
const wrap = (d) => ((((d + 180) % 360) + 360) % 360) - 180;
const dLon = wrap(lon - (rect.west + width / 2));
const dLat = lat - (rect.south + rect.north) / 2;
const cos = Math.cos(rotation);
const sin = Math.sin(rotation);
return (
Math.abs(cos * dLon + sin * dLat) <= width / 2 &&
Math.abs(-sin * dLon + cos * dLat) <= (rect.north - rect.south) / 2
);
}
/**
* The pickable items under a pixel, nearest first. With a `depth`, only
* the nearest `depth` things drawn there are looked through, unpickable
* ones included (as a bounded `drillPick` does).
*/
function hitsAt(x, y, win = {}, depth = undefined) {
if (scriptedPicks) return scriptedPicks(x, y, win) ?? [];
const halfW = (win.width ?? 3) / 2;
const halfH = (win.height ?? 3) / 2;
const hits = [];
for (const [setId, set] of sets) {
if (!set.show) continue;
// Drawn but never picked: it still takes up a place under the pointer.
const setBlocked = set.spec.pickable === false;
const blockedItem = (item) => setBlocked || item.pickable === false;
if (set.kind === 'lines') {
for (const item of set.items.values()) {
if (item.show === false) continue;
// Lines in the sky's frame are not picked where they are drawn.
if (item.frame === 'inertial') continue;
const p = lineHit(item, x, y, Math.max(halfW, halfH));
if (p)
hits.push({
set: setId,
id: item.id,
meta: item.meta,
surface: false,
position: p,
depth: magnitude(sub(p, eye().position)),
blocked: blockedItem(item),
});
}
continue;
}
if (set.kind === 'shapes') {
// Draped rectangles are picked where they cover the ellipsoid, turned
// as the default renderer turns them; other shapes are not picked.
const ground = rayEllipsoid(pickRay(x, y));
const at = ground && toCartographicRadians(ground);
if (!at) continue;
for (const item of set.items.values()) {
if (item.show === false) continue;
if (!item.fill || item.outlineOnly) continue;
if (item.height !== 'clampGround') continue;
if (item.geometry?.kind !== 'rectangle') continue;
if (!inRectangle(item.geometry, toDegrees(at.lon), toDegrees(at.lat)))
continue;
hits.push({
set: setId,
id: item.id,
meta: item.meta,
surface: false,
position: ground,
depth: magnitude(sub(ground, eye().position)),
blocked: blockedItem(item),
});
}
continue;
}
if (
set.kind !== 'icons' &&
set.kind !== 'points' &&
set.kind !== 'models' &&
set.kind !== 'orbits'
)
continue;
for (const item of set.items.values()) {
if (item.show === false) continue;
const p = itemPosition(set, item);
if (!p || isOccluded(p)) continue;
const distance = magnitude(sub(p, eye().position));
if (item.displayRange) {
const [nearM, farM] = item.displayRange;
if (distance < nearM || distance >= farM) continue;
}
// Faded out entirely, it is not drawn.
if (
item.fadeByDistance &&
nearFarValue(item.fadeByDistance, distance) <= 0
)
continue;
const s = project(p);
if (!s) continue;
const pixel = item.pixelSize ?? item.marker?.pixelSize ?? 10;
const size = item.pickProxy?.size ??
item.size ??
item.marker?.size ?? [pixel, pixel];
const scale = item.scaleByDistance
? nearFarValue(item.scaleByDistance, distance)
: 1;
// Scaled to nothing, it is not drawn.
if (scale <= 0) continue;
if (
Math.abs(s.x - x) <= (size[0] * scale) / 2 + halfW &&
Math.abs(s.y - y) <= (size[1] * scale) / 2 + halfH
)
hits.push({
set: setId,
id: item.id,
meta: item.meta,
...(item.lodGroup !== undefined ? { lodGroup: item.lodGroup } : {}),
surface: false,
position: p,
depth: distance,
blocked: blockedItem(item),
// Drawn over depth here: stacked by its set's draw order.
over: (item.disableDepthTest ?? 0) > distance,
order: set.spec.drawOrder ?? 0,
seq: set.seq,
});
}
}
// What skips the depth test is on top, the highest draw order first and
// of one order the set made first (as the default renderer stacks
// opaque ones); the rest nearest first.
hits.sort(
(a, b) =>
(b.over === true) - (a.over === true) ||
(a.over ? b.order - a.order || a.seq - b.seq : 0) ||
a.depth - b.depth,
);
const looked = depth === undefined ? hits : hits.slice(0, depth);
const out = looked.filter((hit) => !hit.blocked);
for (const hit of out) {
delete hit.depth;
delete hit.blocked;
delete hit.over;
delete hit.order;
delete hit.seq;
}
return out;
}
/**
* A line's positions as ECEF, cut at its `revealFraction` of length (as
* drawn straight between its positions).
*/
function revealedLine(item) {
const flat = item.positions instanceof Float64Array;
const n = flat ? item.positions.length / 3 : item.positions.length;
const points = [];
for (let i = 0; i < n; i++)
points.push(
flat
? vec(
item.positions[i * 3],
item.positions[i * 3 + 1],
item.positions[i * 3 + 2],
)
: toEcef(item.positions[i]),
);
const fraction = item.revealFraction;
if (fraction === undefined || fraction >= 1) return points;
const at = alongLength(points, fraction);
if (!at) return [];
const { index, t } = at;
return [
...points.slice(0, index + 1),
add(points[index], scale(sub(points[index + 1], points[index]), t)),
];
}
/**
* Where a line is under the pixel `(x, y)`: the nearest point of a
* drawn segment within half its width (and `slack`) of it, or null.
*/
function lineHit(item, x, y, slack) {
const points = revealedLine(item);
const reach = (item.widthPx ?? 1) / 2 + slack;
let best = null;
let bestDistance = Infinity;
for (let i = 0; i + 1 < points.length; i++) {
if (item.segmentShow?.[i] === false) continue;
const a = points[i];
const b = points[i + 1];
if (isOccluded(a) && isOccluded(b)) continue;
const sa = project(a);
const sb = project(b);
if (!sa || !sb) continue;
const dx = sb.x - sa.x;
const dy = sb.y - sa.y;
const span = dx * dx + dy * dy;
const t =
span > 0
? Math.max(0, Math.min(1, ((x - sa.x) * dx + (y - sa.y) * dy) / span))
: 0;
const distance = Math.hypot(sa.x + dx * t - x, sa.y + dy * t - y);
if (distance <= reach && distance < bestDistance) {
bestDistance = distance;
best = add(a, scale(sub(b, a), t));
}
}
return best;
}
function surfaceHit(x, y) {
const position = rayEllipsoid(pickRay(x, y));
return position
? { set: '', id: '', meta: undefined, surface: true, position }
: null;
}
/**
* The geodetic box of the ellipsoid under the screen's border, or null
* when any of the border looks past the globe. A pole in view widens it to
* that pole and every longitude.
*/
function viewRectangle() {
return computeViewRectangle(camera.port.pose(), viewport, (x, y) =>
rayEllipsoid(pickRay(x, y)),
);
}
function lookupHeight(point, against) {
const key = cacheKey(point, against);
if (heightCache.has(key)) return heightCache.get(key);
if (heightSource) return heightSource(point, against);
return null;
}
const query = {
pick(x, y, win) {
return hitsAt(x, y, win)[0] ?? surfaceHit(x, y);
},
drillPick(x, y, opts = {}) {
if (opts.limit === undefined) return hitsAt(x, y, opts);
return hitsAt(x, y, opts, Math.max(opts.limit, 16)).slice(0, opts.limit);
},
pickPosition(x, y) {
if (!capabilities.has('pickPosition')) return null;
return rayEllipsoid(pickRay(x, y));
},
pickEllipsoid: (x, y) => rayEllipsoid(pickRay(x, y)),
pickGlobe: (ray) => rayEllipsoid(ray),
pickRay,
project,
projectMany(source, out) {
for (let i = 0, j = 0; i + 2 < source.length; i += 3, j += 2) {
const s = project(vec(source[i], source[i + 1], source[i + 2]));
out[j] = s ? s.x : NaN;
out[j + 1] = s ? s.y : NaN;
}
},
isOccluded,
sampleHeightNow(point, opts = {}) {
if (!capabilities.has('sampleHeight')) return null;
const key = cacheKey(point, opts.against);
return heightCache.has(key) ? heightCache.get(key) : null;
},
sampleHeightNowMany(points, out, opts = {}) {
for (let i = 0; i < out.length; i++) {
const height = query.sampleHeightNow(
{ lon: points[i * 2], lat: points[i * 2 + 1] },
opts,
);
out[i] = height ?? NaN;
}
},
async sampleHeight(points, opts = {}) {
if (!capabilities.has('sampleHeight')) return points.map(() => null);
return points.map((point) => {
const height = lookupHeight(point, opts.against);
if (height === null || height === undefined) return null;
heightCache.set(cacheKey(point, opts.against), height);
const lod =
opts.mostDetailed && capabilities.has('finestHeights')
? 'finest'
: 'visible';
return { height, confidence: 1, source: 'terrain', lod };
});
},
async clampToSurface(positions, opts = {}) {
const points = positions.map((p) => {
const c = toCartographicRadians(p);
return { lon: toDegrees(c.lon), lat: toDegrees(c.lat) };
});
const samples = await query.sampleHeight(points, opts);
return samples.map((sample, i) =>
sample ? toEcef({ ...points[i], height: sample.height }) : null,
);
},
async rayCast(ray) {
if (!capabilities.has('rayCast')) return null;
return rayEllipsoid(ray);
},
};
// --- Input -----------------------------------------------------------------
const router = createInputRouter({
report,
suspendCamera: (reason) => camera.port.controls.suspend(reason),
});
const input = router.port;
function dispatchPointer(type, x, y, extra = {}) {
let picked;
const ev = {
type,
position: { x, y },
button: extra.button ?? 0,
modifiers: {
shift: false,
ctrl: false,
alt: false,
meta: false,
...(extra.modifiers ?? {}),
},
timestamp: clock,
pointerType: extra.pointerType ?? 'mouse',
...(extra.endPosition ? { endPosition: extra.endPosition } : {}),
...(extra.delta !== undefined ? { delta: extra.delta } : {}),
};
if (type === 'click' || type === 'dblclick') {
ev.gesture = extra.gesture ?? { travelPx: 0, durationMs: 120 };
const hits = () => (picked ??= hitsAt(x, y));
ev.pick = () => hits()[0] ?? surfaceHit(x, y);
ev.drill = (opts = {}) =>
opts.limit === undefined ? hits().slice() : query.drillPick(x, y, opts);
ev.ground = () => rayEllipsoid(pickRay(x, y));
}
router.dispatch(ev);
requestRender('input');
}
// --- Globe -----------------------------------------------------------------
const imageryLayers = [];
let split = 0.5;
/** Layers whose frames follow scene time, each with its show-a-time function. */
const sceneFrameLayers = new Map();
/** Each timed layer's announcement of the frame it drew, run after a render. */
const frameFlushes = new Map();
const progressListeners = [];
const settled = { base: true, tiles: true, terrain: true, imagery: true };
let sky = {
atmosphere: true,
stars: true,
milkyWay: 0.5,
sun: true,
moon: true,
fog: true,
lighting: false,
...(options.sky ?? {}),
};
let photorealStatus = { route: 'none' };
let globeVisible = true;
function addImagery(spec, index) {
if (
!capabilities.has('imageHooks') &&
(spec.tileTransform || spec.admit || spec.kind === 'canvas')
)
throw new TypeError(
'tileTransform, admit and canvas imagery need imageHooks',
);
const listeners = { frameReady: [], tileError: [] };
const layer = {
spec: { ...spec },
alpha: 1,
show: true,
split: 'none',
drapeOn: 'all',
lit: true,
on(event, cb) {
listeners[event]?.push(cb);
return () => {
const list = listeners[event] ?? [];
const i = list.indexOf(cb);
if (i >= 0) list.splice(i, 1);
};
},
raise() {
const i = imageryLayers.indexOf(layer);
if (i >= 0 && i < imageryLayers.length - 1) {
imageryLayers.splice(i, 1);
imageryLayers.splice(i + 1, 0, layer);
}
requestRender('imagery');
},
lower() {
const i = imageryLayers.indexOf(layer);
if (i > 0) {
imageryLayers.splice(i, 1);
imageryLayers.splice(i - 1, 0, layer);
}
requestRender('imagery');
},
remove() {
const i = imageryLayers.indexOf(layer);
if (i >= 0) imageryLayers.splice(i, 1);
sceneFrameLayers.delete(layer);
frameFlushes.delete(layer);
requestRender('imagery');
},
};
if (capabilities.has('imageryFrames')) {
let source = null;
let clockKind = 'scene';
/** The time the source shows for `ms`: the nearest frame, or within the videos. */
const shownTime = (ms) => {
if (source?.kind === 'video') {
let best = null;
let bestOff = Infinity;
for (const seg of source.segments) {
const t = Math.min(seg.end, Math.max(seg.start, ms));
if (Math.abs(t - ms) < bestOff) {
best = t;
bestOff = Math.abs(t - ms);
}
}
return best;
}
const frames = source?.frames ?? [];
let best = null;
for (const f of frames)
if (!best || Math.abs(f.time - ms) < Math.abs(best.time - ms))
best = f;
return best ? best.time : null;
};
// The stub has every frame at once, so the frame asked for is drawn
// by the next render; it is said once per change of the drawn frame.
let wanted = null;
let drawnTime = null;
const show = (ms) => {
wanted = shownTime(ms);
requestRender('imagery');
};
frameFlushes.set(layer, () => {
if (wanted === null || wanted === drawnTime) return;
drawnTime = wanted;
deliver(listeners.frameReady, drawnTime);
});
layer.setFrames = (next, opts = {}) => {
source =
next.kind === 'video'
? { kind: 'video', segments: next.segments.map((s) => ({ ...s })) }
: { kind: 'frames', frames: next.frames.slice() };
wanted = null;
drawnTime = null;
clockKind = opts.clock ?? 'scene';
if (clockKind === 'scene') {
sceneFrameLayers.set(layer, show);
show(sceneTime);
} else sceneFrameLayers.delete(layer);
requestRender('imagery');
};
layer.setFrameTime = (ms) => {
// On the scene clock the frame port's time decides.
if (clockKind !== 'own') return;
show(ms);
requestRender('imagery');
};
}
if (index === undefined) imageryLayers.push(layer);
else imageryLayers.splice(index, 0, layer);
log('globe', 'imagery.add', [spec, index]);
requestRender('imagery');
return layer;
}
// `surfaceIdentity`: bumped by whatever changes what heights answer against.
let surfaceVersion = 0;
let terrainKey = 'null';
const globe = {
async setBase(base) {
log('globe', 'setBase', [base]);
for (const layer of imageryLayers.slice()) layer.remove();
if (base.photoreal !== undefined)
await globe.setPhotoreal(base.photoreal);
const layers = (base.imagery ?? []).map((spec) => addImagery(spec));
return { photoreal: photorealStatus, imagery: layers, settled: true };
},
async setPhotoreal(spec) {
log('globe', 'setPhotoreal', [spec]);
const route = photorealStatus.route;
photorealStatus =
spec && capabilities.has('photoreal')
? { route: 'google' }
: { route: 'none' };
if (photorealStatus.route !== route || spec) surfaceVersion += 1;
requestRender('base');
return photorealStatus;
},
async setTerrain(spec) {
log('globe', 'setTerrain', [spec]);
// The stub keeps no terrain: a spec unlike the last is a new surface.
const key = JSON.stringify(spec ?? null);
if (key !== terrainKey) surfaceVersion += 1;
terrainKey = key;
requestRender('base');
},
setGlobeVisible(visible) {
log('globe', 'setGlobeVisible', [visible]);
if (globeVisible !== Boolean(visible)) surfaceVersion += 1;
globeVisible = Boolean(visible);
requestRender('base');
},
imagery: {
add: addImagery,
list: () => imageryLayers.slice(),
},
sky: {
get: () => ({ ...sky }),
set(patch) {
sky = { ...sky, ...patch };
requestRender('sky');
},
},
isSettled(kind) {
if (kind !== 'surface') return settled[kind] ?? true;
if (!capabilities.has('surfaceIdentity')) return settled.base;
// Heights answer from the globe, else the tiles; neither drawn, none.
if (!globeVisible && photorealStatus.route === 'none') return false;
return settled.surface ?? settled[globeVisible ? 'terrain' : 'tiles'];
},
on(event, cb) {
if (event !== 'progress') return () => {};
progressListeners.push(cb);
return () => {
const i = progressListeners.indexOf(cb);
if (i >= 0) progressListeners.splice(i, 1);
};
},
};
if (capabilities.has('globeVisibility'))
globe.isGlobeVisible = () => globeVisible;
if (capabilities.has('surfaceIdentity'))
globe.surfaceVersion = () => surfaceVersion;
if (capabilities.has('surfaceShading'))
globe.setSurfaceShading = (shading) => {
log('globe', 'setSurfaceShading', [shading]);
requestRender('base');
};
if (capabilities.has('clouds'))
globe.setClouds = (clouds) => {
log('globe', 'setClouds', [clouds]);
requestRender('base');
};
if (capabilities.has('water'))
globe.setWater = (water) => {
log('globe', 'setWater', [water]);
requestRender('base');
};
if (capabilities.has('splitSwipe')) {
globe.imagery.getSplit = () => split;
globe.imagery.setSplit = (x01) => {
split = Math.min(1, Math.max(0, x01));
requestRender('imagery');
};
}
// --- Effects, credits, quality ---------------------------------------------
const effectState = {
style: null,
params: {},
intensity: {},
bloom: null,
sharpen: null,
modulation: null,
};
const effectListeners = [];
/** The styles a setStyle replaced, drawing until their intensity is 0. */
const fading = new Set();
const styleIntensity = (id) => effectState.intensity[id] ?? 1;
const styleDraws = (id) =>
(id === effectState.style || fading.has(id)) && styleIntensity(id) > 0;
/** Styles the app defined, by id. */
const defined = new Map();
const STYLES = Object.freeze([
{
id: 'retro',
params: [{ key: 'grain', min: 0, max: 1, default: 0.5 }],
animated: true,
},
{ id: 'thermal', params: [], animated: false },
]);
function effectsChanged() {
const d = effects.diagnostics();
deliver(effectListeners, d);
requestRender('effects');
}
const effects = {
styles: () =>
capabilities.has('styles')
? [
...STYLES.filter((s) => !defined.has(s.id)),
...defined.values(),
].map(({ id, params, animated }) => ({
id,
params: params.map((p) => ({ ...p })),
animated,
}))
: [],
defineStyle(definition) {
// The stub runs GLSL only, as the default renderer does.
if (
!capabilities.has('styles') ||
typeof definition?.shader?.glsl !== 'string'
)
return null;
const entry = {
id: String(definition.id),
params: (definition.params ?? []).map((p) => ({ ...p })),
animated: Boolean(definition.animated),
};
defined.set(entry.id, entry);
effectsChanged();
let removed = false;
return () => {
if (removed) return;
removed = true;
if (defined.get(entry.id) !== entry) return;
defined.delete(entry.id);
fading.delete(entry.id);
if (effectState.style === entry.id) effectState.style = null;
effectsChanged();
};
},
setStyle(id, params) {
if (id !== effectState.style) {
if (effectState.style !== null && styleIntensity(effectState.style) > 0)
fading.add(effectState.style);
fading.delete(id);
}
effectState.style = id;
if (params) effectState.params[id] = { ...params };
effectsChanged();
},
setStyleIntensity(id, value) {
effectState.intensity[id] = value;
if (!(value > 0)) fading.delete(id);
effectsChanged();
},
setStyleParams(id, params) {
effectState.params[id] = { ...(effectState.params[id] ?? {}), ...params };
effectsChanged();
},
bloom(settings) {
effectState.bloom = capabilities.has('bloom') ? { ...settings } : null;
effectsChanged();
},
sharpen(settings) {
effectState.sharpen = capabilities.has('sharpen')
? { ...settings }
: null;
effectsChanged();
},
diagnostics: () => ({
style: effectState.style,
passes: [
...effects
.styles()
.filter((s) => styleDraws(s.id))
.map((s) => `style:${s.id}`),
...(effectState.bloom?.enabled ? ['bloom'] : []),
...(effectState.sharpen?.enabled ? ['sharpen'] : []),
...(effectState.modulation ? ['screenModulation'] : []),
],
}),
on(event, cb) {
if (event !== 'change') return () => {};
effectListeners.push(cb);
return () => {
const i = effectListeners.indexOf(cb);
if (i >= 0) effectListeners.splice(i, 1);
};
},
};
if (capabilities.has('screenModulation'))
effects.screenModulation = (sector) => {
effectState.modulation = sector ? { ...sector } : null;
effectsChanged();
};
const creditList = [];
const creditListeners = [];
const creditsChanged = () => {
const list = creditList.map((c) => ({ ...c }));
deliver(creditListeners, list);
};
const credits = {
addStatic(credit) {
const entry = { ...credit };
creditList.push(entry);
creditsChanged();
return () => {
const i = creditList.indexOf(entry);
if (i < 0) return;
creditList.splice(i, 1);
creditsChanged();
};
},
list: () => creditList.map((c) => ({ ...c })),
on(event, cb) {
if (event !== 'change') return () => {};
creditListeners.push(cb);
return () => {
const i = creditListeners.indexOf(cb);
if (i >= 0) creditListeners.splice(i, 1);
};
},
};
const qualitySettings = Object.fromEntries(
KNOBS.map((k) => [k.key, k.default]),
);
const device = () => ({
backend: 'webgl2',
maxTextureSize: 16384,
msaaSamples: [0, 2, 4, 8],
gpuTimer: capabilities.has('gpuTiming'),
});
const quality = {
knobs: () => KNOBS.map((k) => ({ ...k })),
get: () => ({ ...qualitySettings }),
set(patch) {
const ignored = [];
for (const [key, value] of Object.entries(patch)) {
if (key in qualitySettings) qualitySettings[key] = value;
else ignored.push(key);
}
requestRender('quality');
return ignored;
},
device,
probe: () => ({
device: device(),
browser: {
devicePixelRatio: 1,
screen: { width: viewport.width, height: viewport.height },
touchOnly: false,
},
knobs: quality.knobs(),
}),
signals: {
gpuTiming: capabilities.has('gpuTiming') ? 'frame' : 'none',
on(event, cb) {
const entry = { cb, live: true };
if (event === 'frame') signalListeners.push(entry);
return () => {
entry.live = false;
const i = signalListeners.indexOf(entry);
if (i >= 0) signalListeners.splice(i, 1);
};
},
},
};
if (capabilities.has('benchmark'))
quality.benchmark = async ({ durationMs }) => ({
frames: Math.round(durationMs / FRAME_MS),
cpuMs: { median: 0, p95: 0 },
});
// --- Renderer --------------------------------------------------------------
const canvas = /** @type {HTMLCanvasElement} */ (
/** @type {unknown} */ ({
width: viewport.width,
height: viewport.height,
clientWidth: viewport.width,
clientHeight: viewport.height,
})
);
const renderer = {
id: 'stub',
contractVersion: CONTRACT_VERSION,
capabilities,
canvas,
frame,
globe,
draw,
camera: camera.port,
query,
input,
effects,
credits,
quality,
async capture(opts = {}) {
return new Blob([], { type: `image/${opts.type ?? 'png'}` });
},
readPixels(opts = {}) {
const crop = opts.crop ?? {
x: 0,
y: 0,
width: viewport.width,
height: viewport.height,
};
const k = opts.scale ?? 1;
const width = Math.round(crop.width * k);
const height = Math.round(crop.height * k);
const data = new Uint8ClampedArray(width * height * 4);
// Models are the only things the stub draws into pixels.
for (const square of modelSquares()) {
for (let row = 0; row < height; row++) {
const y = crop.y + (row + 0.5) / k;
if (Math.abs(y - square.y) > square.half) continue;
for (let col = 0; col < width; col++) {
const x = crop.x + (col + 0.5) / k;
if (Math.abs(x - square.x) > square.half) continue;
data.set(square.rgba, (row * width + col) * 4);
}
}
}
return /** @type {ImageData} */ (
/** @type {unknown} */ ({ width, height, data })
);
},
async whenSettled() {
const blockers = Object.keys(settled).filter((kind) => !settled[kind]);
return { state: blockers.length ? 'timeout' : 'settled', blockers };
},
resize() {
requestRender('resize');
},
releaseUnused() {
log('renderer', 'releaseUnused', []);
},
on(event, cb) {
const list = rendererListeners[event];
if (!list) return () => {};
// Each subscription is its own entry, so one callback subscribed
// again during delivery waits for the next event like any other.
const entry = { cb, live: true };
list.push(entry);
return () => {
entry.live = false;
const i = list.indexOf(entry);
if (i >= 0) list.splice(i, 1);
};
},
destroy() {
// A flight in progress ends cancelled and gives back its input hold.
camera.endFlight();
destroyed = true;
for (const clear of onceTimers) clear();
onceTimers.clear();
sets.clear();
satrecs.clear();
sceneFrameLayers.clear();
frameFlushes.clear();
},
testing: {
/** Run one frame of the loop; true when it drew. */
tick,
/** Run frames until `ms` of the clock has passed. */
advance(ms) {
// By frame count: a suspended or destroyed loop does not move the clock.
const frames = Math.floor(ms / FRAME_MS + 1e-9);
let drew = 0;
for (let i = 0; i < frames; i++) if (tick()) drew += 1;
return drew;
},
/** Run frames until a condition holds, at most `maxFrames`. */
until(condition, maxFrames = 10000) {
for (let i = 0; i < maxFrames; i++) {
if (condition()) return i;
tick();
}
throw new Error('condition not met');
},
now: () => clock,
/** Wall time, epoch ms: what a set's `live` motion clock reads before its delay. */
wallTime,
/** The steps of the last frame, in order. */
lastSteps: () => stepLog.slice(),
/** A pointer event at `(x, y)`. */
pointer: dispatchPointer,
/** Answer picks from a function instead of the drawn items. */
scriptPicks(fn) {
scriptedPicks = fn;
},
/** Heights: a function answering async samples, and cached values. */
setHeights(fn) {
heightSource = fn;
},
/** A cached height, against `against` (default `'surface'`). */
cacheHeight(point, height, against) {
heightCache.set(cacheKey(point, against), height);
},
setSettled(kind, value) {
settled[kind] = value;
},
setViewport(size) {
Object.assign(viewport, size);
canvas.width = viewport.width;
canvas.height = viewport.height;
},
/** What a set holds. */
setRecord: (id) => sets.get(id) ?? null,
sets: () => [...sets.keys()],
calls,
effects: () => ({ ...effectState }),
emitError: (error) => report(error),
},
};
return renderer;
}
/**
* @typedef {object} StubTesting
* @property {() => boolean} tick
* @property {(ms: number) => number} advance
* @property {(condition: () => boolean, maxFrames?: number) => number} until
* @property {() => number} now
* @property {() => string[]} lastSteps
* @property {(type: string, x: number, y: number, extra?: object) => void} pointer
* @property {(fn: ((x: number, y: number, win: object) => object[])|null) => void} scriptPicks
* @property {(fn: ((point: object, against?: string) => number|null)|null) => void} setHeights
* @property {(point: object, height: number) => void} cacheHeight
* @property {(kind: string, value: boolean) => void} setSettled
* @property {(size: {width?: number, height?: number}) => void} setViewport
* @property {(id: string) => object|null} setRecord
* @property {() => string[]} sets
* @property {Array<{port: string, member: string, args: unknown[]}>} calls
* @property {() => object} effects
* @property {(error: Error) => void} emitError
*/