Files
gods-eye-view/src/render/contract/index.js
T
Sameh Khamis 46ad53aa35 A renderer's roles: per-layer lighting is part of the look, and roleOf knows only real members
imageryLayer.lit (a layer shaded by the sun) joins the look with surface
shading. roleOf answers undefined for a member its port does not have, and
the port's own role without a member. The test now fails when two roles
claim the same entry.
2026-11-11 13:43:28 -08:00

463 lines
12 KiB
JavaScript

/**
* @module render/contract
* @description The renderer contract at run time: the capability flags, every
* port's members, and a shape check. The types live beside this file
* (`index.d.ts` and one `.d.ts` per port); `contract.test.mjs` keeps
* {@link PORTS} and those types in step, member for member.
*
* A member is required (`null`) or added by a capability: a renderer without
* that capability leaves the member out.
*/
/** @type {import('./index').ContractVersion} */
export const CONTRACT_VERSION = '0';
/** @type {readonly import('./common').Capability[]} */
export const CAPABILITIES = Object.freeze([
'photoreal',
'vectorBase',
'finestHeights',
'terrain',
'modelAtmosphere',
'imageryOnTiles',
'splitSwipe',
'imageryFrames',
'surfaceShading',
'surfaceIdentity',
'imageHooks',
'screenModulation',
'gpuTiming',
'pickPosition',
'sampleHeight',
'rayCast',
'columns',
'motionSegments',
'models',
'quads',
'meshes',
'fields',
'courseGlide',
'cluster',
'styles',
'bloom',
'sharpen',
'followAutodetect',
'globeVisibility',
'followFrame',
'cameraChangeThreshold',
'occlusionTest',
'keepEarthFramed',
]);
/** @type {readonly import('./frame').FrameStep[]} */
export const FRAME_STEPS = Object.freeze([
'flight',
'input',
'changed',
'follow',
'preUpdate',
'moveDetection',
'preRender',
'render',
'postRender',
]);
/** Every quality setting a renderer may support. */
export const QUALITY_KEYS = Object.freeze([
'pixelRatio',
'msaa',
'tiles3dDetail',
'terrainDetail',
'imageryDetail',
'tilesCacheBytes',
'shadows',
'atmosphere',
'milkyWay',
'particles',
'models',
'postFx',
'targetFps',
]);
const required = (...names) => names.map((name) => [name, null]);
/**
* Every port's members. Nested members are dotted (`imagery.add`); the
* instance shapes a port hands out (`drawSet`, `imageryLayer`, `flight`,
* `lease`) are listed as their own entries.
* @type {Readonly<Record<string, Readonly<Record<string, import('./common').Capability|null>>>>}
*/
export const PORTS = deepFreeze({
renderer: Object.fromEntries(
required(
'id',
'contractVersion',
'capabilities',
'canvas',
'frame',
'globe',
'draw',
'camera',
'query',
'input',
'effects',
'credits',
'quality',
'capture',
'readPixels',
'whenSettled',
'resize',
'releaseUnused',
'on',
'destroy',
),
),
frame: Object.fromEntries(
required(
'on',
'requestRender',
'holdContinuous',
'mode',
'diagnostics',
'suspend',
'renderNow',
'renderOnce',
'setTargetFps',
'setTime',
'time',
),
),
globe: Object.fromEntries([
...required(
'setBase',
'setPhotoreal',
'setTerrain',
'setGlobeVisible',
'imagery',
'imagery.add',
'imagery.list',
'sky',
'sky.get',
'sky.set',
'isSettled',
'on',
),
['isGlobeVisible', 'globeVisibility'],
['surfaceVersion', 'surfaceIdentity'],
['setSurfaceShading', 'surfaceShading'],
['imagery.getSplit', 'splitSwipe'],
['imagery.setSplit', 'splitSwipe'],
]),
draw: Object.fromEntries([
...required(
'icons',
'points',
'lines',
'shapes',
'atlas',
'clampState',
'on',
),
['models', 'models'],
['quads', 'quads'],
['meshes', 'meshes'],
['field', 'fields'],
]),
camera: Object.fromEntries([
...required(
'pose',
'setView',
'setFov',
'viewRectangle',
'flyTo',
'flyToBounds',
'cancelFlight',
'flying',
'lookAt',
'release',
'follow',
'followed',
'followFramed',
'followOffset',
'followOffset.get',
'followOffset.set',
'controls',
'controls.enabled',
'controls.suspend',
'controls.enableTilt',
'controls.enableRotate',
'controls.enableZoom',
'controls.minDistance',
'controls.maxDistance',
'controls.coast',
'controls.coast.drag',
'controls.coast.zoom',
'controls.collision',
'controls.zoomFactor',
'controls.pitchRange',
'controls.zoomInputs',
'on',
'onCommand',
'matrices',
),
['followFrame', 'followFrame'],
['controls.keepEarthFramed', 'keepEarthFramed'],
]),
query: Object.fromEntries([
...required(
'pick',
'drillPick',
'pickPosition',
'pickEllipsoid',
'pickGlobe',
'pickRay',
'project',
'projectMany',
'isOccluded',
'sampleHeightNow',
'sampleHeight',
'clampToSurface',
'rayCast',
),
['occlusionTest', 'occlusionTest'],
]),
input: Object.fromEntries(
required(
'on',
'claimPointer',
'isPointerFree',
'suspendCameraControls',
'behaviours',
'behaviours.select',
'behaviours.select.enabled',
'behaviours.select.suppress',
'behaviours.dblclickFollow',
'behaviours.dblclickFollow.enabled',
'behaviours.dblclickFollow.suppress',
),
),
effects: Object.fromEntries([
...required(
'styles',
'defineStyle',
'setStyle',
'setStyleIntensity',
'setStyleParams',
'bloom',
'sharpen',
'diagnostics',
'on',
),
['screenModulation', 'screenModulation'],
]),
credits: Object.fromEntries(required('addStatic', 'list', 'on')),
quality: Object.fromEntries(
required(
'knobs',
'get',
'set',
'device',
'probe',
'signals',
'signals.gpuTiming',
'signals.on',
),
),
drawSet: Object.fromEntries([
...required(
'id',
'set',
'upsert',
'remove',
'clear',
'setOptions',
'size',
'show',
'on',
'dispose',
),
['setColumns', 'columns'],
]),
imageryLayer: Object.fromEntries([
...required(
'alpha',
'show',
'split',
'drapeOn',
'lit',
'on',
'raise',
'lower',
'remove',
),
['setFrames', 'imageryFrames'],
['setFrameTime', 'imageryFrames'],
]),
flight: Object.fromEntries(required('done', 'cancel')),
lease: Object.fromEntries(required('owner', 'current', 'release')),
});
/**
* What a renderer does, by role rather than by port. A renderer is more than
* a drawing surface: it streams and builds the Earth from map sources, draws
* the application's data as keyed sets, moves the camera, answers questions
* about the world, applies the look, and runs the frame. The application owns the data
* (providers, records, layers); the renderer owns everything from a source
* spec or a draw set down to the pixels.
*
* Each role lists the members it covers as `port` (all of a port) or
* `port.member` (that member and the members under it); the most specific
* entry wins, so every member of {@link PORTS} has exactly one role
* ({@link roleOf}). The roles describe the contract; they change no member.
* @type {readonly import('./index').ContractRole[]}
*/
export const ROLES = deepFreeze([
{
id: 'surface',
// i18n-ignore: developer documentation of the contract, never shown in the app
title: 'The Earth',
summary:
'Streams, decodes and builds the globe from map sources: base imagery, terrain, photoreal 3D tiles and draped imagery layers (frames, split), with their credits and loading state.',
members: ['globe', 'imageryLayer', 'credits'],
},
{
id: 'scene',
// i18n-ignore: developer documentation of the contract, never shown in the app
title: 'Scene contents',
summary:
"Draws the application's data as keyed, retained sets: icons, points, lines, shapes, models, quads, meshes and fields, clamped to the surface where asked.",
members: ['draw', 'drawSet'],
},
{
id: 'view',
// i18n-ignore: developer documentation of the contract, never shown in the app
title: 'Camera and input',
summary:
'Places and moves the camera (views, flights, follow, user controls) and hands pointer input to the application.',
members: ['camera', 'flight', 'input', 'lease'],
},
{
id: 'queries',
// i18n-ignore: developer documentation of the contract, never shown in the app
title: 'World queries',
summary:
'Answers questions about what is drawn: picks, surface positions and heights, rays, projection and occlusion.',
members: ['query'],
},
{
id: 'look',
// i18n-ignore: developer documentation of the contract, never shown in the app
title: 'Look',
summary:
'How the world is lit and finished: sky and atmosphere, surface shading, styles and screen effects.',
members: [
'effects',
'globe.sky',
'globe.setSurfaceShading',
'imageryLayer.lit',
],
},
{
id: 'host',
// i18n-ignore: developer documentation of the contract, never shown in the app
title: 'Host and frame',
summary:
'The renderer itself: its canvas and life cycle, the frame loop and scene time, quality, capture and settling.',
members: ['renderer', 'frame', 'quality'],
},
]);
/**
* The role a member belongs to: the most specific {@link ROLES} entry naming
* its port or one of its dotted prefixes.
* @param {string} port
* @param {string} [member] dotted, as in {@link PORTS}; empty for the port's own role
* @returns {string|undefined} the role's id; undefined for a member the port does not have
*/
export function roleOf(port, member = '') {
if (member && !(PORTS[port] && member in PORTS[port])) return undefined;
const parts = member ? member.split('.') : [];
for (let n = parts.length; n >= 0; n--) {
const key = [port, ...parts.slice(0, n)].join('.');
const role = ROLES.find((r) => r.members.includes(key));
if (role) return role.id;
}
return undefined;
}
/** The ports a renderer object holds, by the key it holds them under. */
const RENDERER_PORTS = [
'frame',
'globe',
'draw',
'camera',
'query',
'input',
'effects',
'credits',
'quality',
];
function deepFreeze(value) {
for (const inner of Object.values(value))
if (inner && typeof inner === 'object') deepFreeze(inner);
return Object.freeze(value);
}
function has(target, dotted) {
let at = target;
for (const key of dotted.split('.')) {
if (at == null || (typeof at !== 'object' && typeof at !== 'function'))
return false;
if (!(key in at)) return false;
at = at[key];
}
return true;
}
/**
* What `target` is missing against one descriptor, and what it has that its
* capabilities do not allow.
* @param {object} target
* @param {string} port
* @param {ReadonlySet<string>} capabilities
* @returns {string[]}
*/
export function checkPortShape(target, port, capabilities) {
const problems = [];
for (const [member, capability] of Object.entries(PORTS[port])) {
const present = has(target, member);
if (capability === null) {
if (!present) problems.push(`${port}.${member} is missing`);
} else if (capabilities.has(capability) && !present) {
problems.push(`${port}.${member} is missing with ${capability}`);
} else if (!capabilities.has(capability) && present) {
problems.push(`${port}.${member} is present without ${capability}`);
}
}
return problems;
}
/**
* What a renderer is missing against the contract.
* @param {unknown} renderer
* @returns {string[]}
*/
export function checkRendererShape(renderer) {
if (!renderer || typeof renderer !== 'object')
return ['renderer is not an object'];
const r = /** @type {any} */ (renderer);
const capabilities = r.capabilities instanceof Set ? r.capabilities : null;
if (!capabilities) return ['renderer.capabilities is not a Set'];
const problems = [];
for (const capability of capabilities)
if (!CAPABILITIES.includes(capability))
problems.push(`unknown capability ${capability}`);
if (r.contractVersion !== CONTRACT_VERSION)
problems.push(`contractVersion is ${r.contractVersion}`);
problems.push(...checkPortShape(r, 'renderer', capabilities));
for (const port of RENDERER_PORTS)
if (r[port]) problems.push(...checkPortShape(r[port], port, capabilities));
return problems;
}