Renderer contract doc: what a renderer does, by role

Documents ROLES and roleOf: a renderer is a whole globe engine, the
application keeps the data, and every member of PORTS sits in one of six
roles.
This commit is contained in:
Sameh Khamis committed 2026-11-11 15:04:38 -08:00
1 parent ffbd9fe4c2
commit b2ca9a7d3c
1 file changed
+23
+23
View File
@@ -177,6 +177,29 @@ and each capability member present without its capability.
`contract.test.mjs` type-checks the contract under strict TypeScript, and
fails when `PORTS` and the types disagree on a single member.
### What a renderer does, by role
A renderer is more than a drawing surface: it is a whole globe engine. The
application keeps the data (providers, records, layers and their
behaviour). The renderer owns everything from a source spec or a draw set
down to the pixels. The ports follow the API's shape; `ROLES` in
`src/render/contract/index.js` names what the engine behind them does, and
puts every member of `PORTS` in exactly one role. It changes no member.
| Role | What it does | Members |
| --------- | ----------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------- |
| `surface` | Streams, decodes and builds the globe from map sources: imagery, terrain, photoreal 3D tiles, draped layers | `globe`, `imageryLayer`, `credits` |
| `scene` | Draws the application's data as keyed, retained sets | `draw`, `drawSet` |
| `view` | Places and moves the camera, hands pointer input to the application | `camera`, `flight`, `input`, `lease` |
| `queries` | Picks, surface positions and heights, rays, projection, occlusion | `query` |
| `look` | Sky and atmosphere, surface shading, per-layer lighting, styles and screen effects | `effects`, `globe.sky`, `globe.setSurfaceShading`, `imageryLayer.lit` |
| `host` | Canvas and life cycle, the frame loop and scene time, quality, capture, settling | `renderer`, `frame`, `quality` |
An entry is a port or a `port.member` prefix; the most specific one wins, so
`roleOf('globe', 'sky.set')` is `'look'` while `roleOf('globe', 'setBase')`
is `'surface'`. `contract.test.mjs` fails when a member has no role, when
two roles claim the same entry, or when an entry names no member.
## Moving code onto the contract
Two ratchet tests keep code that has moved onto the contract from drifting