mirror of
https://github.com/bilawalsidhu/gods-eye-view.git
synced 2026-11-16 08:12:24 +00:00
The renderer contract names what a renderer does, by role
ROLES sorts every member of PORTS into one of six roles: the Earth (streaming and building the globe from map sources), scene contents, camera and input, world queries, the look, and the host and frame loop. The ports follow the API's shape; the roles say what the engine behind them does, and that the app keeps the data while the renderer owns everything from a source spec or a draw set down to the pixels. roleOf resolves a member to its role, the most specific entry winning. No member changes; a test keeps every member in exactly one role and every entry naming a real member.
This commit is contained in:
1 parent
1f307e0735
commit
21fdc6a332
3 files changed
+132
No files matched your search
@@ -8,6 +8,8 @@ import {
|
|||||||
CONTRACT_VERSION,
|
CONTRACT_VERSION,
|
||||||
FRAME_STEPS,
|
FRAME_STEPS,
|
||||||
PORTS,
|
PORTS,
|
||||||
|
ROLES,
|
||||||
|
roleOf,
|
||||||
QUALITY_KEYS,
|
QUALITY_KEYS,
|
||||||
checkPortShape,
|
checkPortShape,
|
||||||
checkRendererShape,
|
checkRendererShape,
|
||||||
@@ -126,6 +128,36 @@ test('PORTS lists every member of every port, required exactly when the type req
|
|||||||
}
|
}
|
||||||
});
|
});
|
||||||
|
|
||||||
|
test('every member of every port has one role, and each role names real members', () => {
|
||||||
|
const ids = ROLES.map((r) => r.id);
|
||||||
|
assert.equal(new Set(ids).size, ids.length);
|
||||||
|
for (const [port, members] of Object.entries(PORTS))
|
||||||
|
for (const member of Object.keys(members))
|
||||||
|
assert.ok(
|
||||||
|
ids.includes(roleOf(port, member)),
|
||||||
|
`${port}.${member} has no role`,
|
||||||
|
);
|
||||||
|
// An entry is a port, or a member (or a prefix of dotted members) of one.
|
||||||
|
for (const role of ROLES)
|
||||||
|
for (const entry of role.members) {
|
||||||
|
const [port, ...rest] = entry.split('.');
|
||||||
|
const member = rest.join('.');
|
||||||
|
assert.ok(PORTS[port], `${role.id}: ${entry} names no port`);
|
||||||
|
if (member)
|
||||||
|
assert.ok(
|
||||||
|
Object.keys(PORTS[port]).some(
|
||||||
|
(m) => m === member || m.startsWith(`${member}.`),
|
||||||
|
),
|
||||||
|
`${role.id}: ${entry} names no member`,
|
||||||
|
);
|
||||||
|
}
|
||||||
|
// The most specific entry wins.
|
||||||
|
assert.equal(roleOf('globe', 'setBase'), 'surface');
|
||||||
|
assert.equal(roleOf('globe', 'sky.set'), 'look');
|
||||||
|
assert.equal(roleOf('globe', 'setSurfaceShading'), 'look');
|
||||||
|
assert.equal(roleOf('nowhere', 'x'), undefined);
|
||||||
|
});
|
||||||
|
|
||||||
test('the capability and frame-step lists are the types’ own', () => {
|
test('the capability and frame-step lists are the types’ own', () => {
|
||||||
assert.deepEqual([...CAPABILITIES].sort(), unionLiterals('Capability'));
|
assert.deepEqual([...CAPABILITIES].sort(), unionLiterals('Capability'));
|
||||||
assert.deepEqual([...FRAME_STEPS].sort(), unionLiterals('FrameStep'));
|
assert.deepEqual([...FRAME_STEPS].sort(), unionLiterals('FrameStep'));
|
||||||
|
|||||||
Vendored
+18
@@ -28,6 +28,24 @@ export type PortDescriptor = Readonly<
|
|||||||
/** Every port's members, by port name. */
|
/** Every port's members, by port name. */
|
||||||
export declare const PORTS: Readonly<Record<string, PortDescriptor>>;
|
export declare const PORTS: Readonly<Record<string, PortDescriptor>>;
|
||||||
|
|
||||||
|
/** One of the roles a renderer plays, and the members that make it up. */
|
||||||
|
export interface ContractRole {
|
||||||
|
readonly id: 'surface' | 'scene' | 'view' | 'queries' | 'look' | 'host';
|
||||||
|
readonly title: string;
|
||||||
|
readonly summary: string;
|
||||||
|
/** `port` or `port.member`; the most specific entry wins. */
|
||||||
|
readonly members: readonly string[];
|
||||||
|
}
|
||||||
|
|
||||||
|
/** What a renderer does, by role: every member of {@link PORTS} in one. */
|
||||||
|
export declare const ROLES: readonly ContractRole[];
|
||||||
|
|
||||||
|
/** The role of `port`'s `member` (dotted), or undefined. */
|
||||||
|
export declare function roleOf(
|
||||||
|
port: string,
|
||||||
|
member: string,
|
||||||
|
): ContractRole['id'] | undefined;
|
||||||
|
|
||||||
/** Every quality setting a renderer may support. */
|
/** Every quality setting a renderer may support. */
|
||||||
export declare const QUALITY_KEYS: readonly import('./quality').QualityKey[];
|
export declare const QUALITY_KEYS: readonly import('./quality').QualityKey[];
|
||||||
|
|
||||||
|
|||||||
@@ -297,6 +297,88 @@ export const PORTS = deepFreeze({
|
|||||||
lease: Object.fromEntries(required('owner', 'current', 'release')),
|
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'],
|
||||||
|
},
|
||||||
|
{
|
||||||
|
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}
|
||||||
|
* @returns {string|undefined} the role's id
|
||||||
|
*/
|
||||||
|
export function roleOf(port, member) {
|
||||||
|
const parts = 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. */
|
/** The ports a renderer object holds, by the key it holds them under. */
|
||||||
const RENDERER_PORTS = [
|
const RENDERER_PORTS = [
|
||||||
'frame',
|
'frame',
|
||||||
|
|||||||
Reference in new issue
Block a user