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 `contract.test.mjs` type-checks the contract under strict TypeScript, and
fails when `PORTS` and the types disagree on a single member. 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 ## Moving code onto the contract
Two ratchet tests keep code that has moved onto the contract from drifting Two ratchet tests keep code that has moved onto the contract from drifting