Contract and docs text describe the ports and the Cesium renderer only

This commit is contained in:
Sameh Khamis committed 2026-11-15 19:08:46 -08:00
1 parent 1fdf52198d
commit 9862b2a165
31 files changed
+80 -85

No files matched your search

+1 -1
View File
@@ -740,7 +740,7 @@ test('each drawn shape is a row whose actions reach the board, and fly-to is a n
}
});
test("an application's row actions show on the shapes they are for and run with the shape", async () => {
test("row actions given to the tool show on the shapes they are for and run with the shape", async () => {
const ran = [];
const h = harness({
markActions: [
+1 -1
View File
@@ -313,7 +313,7 @@ export function createApplicationTools({
terrain: operations.requests.terrain,
}),
);
// An application's own tool takes the pointer as Draw does (the newest
// Any other tool takes the pointer as Draw does (the newest
// claim takes over; `claim(owner, {onLost})` tells the tool it replaces),
// and its own click handlers yield while a tool holds it, as the layers' do
// (data/inputOwnership.js).
+1 -1
View File
@@ -193,7 +193,7 @@ test('consumer build includes only infrastructure code and resolves assets under
const output = result.output;
const entry = output.find((item) => item.type === 'chunk' && item.isEntry);
const sources = Object.keys(entry.modules).filter((id) => id.endsWith('.js'));
// It draws and takes clicks through the renderer's ports: a viewer of the
// It draws and takes clicks through the renderer's ports: a viewer with no
// renderer bound draws once the caller has loaded
// `./render/cesium/unbound`.
assert.deepEqual(sources.map((id) => id.split('/').at(-1)).sort(), [
+1 -1
View File
@@ -1,7 +1,7 @@
# Sky background
Catalogue stars over a soft Milky Way, exported Cesium-free by `src/sky/index.js`
(`@gods-eye-view/core/sky`) and drawn on Cesium by `src/render/cesium/starrySky.js` in
(`gods-eye-view/sky`) and drawn on Cesium by `src/render/cesium/starrySky.js` in
place of Cesium's blocky Tycho-2 sky box.
| File | Content | Size |
+1 -1
View File
@@ -19,7 +19,7 @@ export function createViewport({ state: layerState, services, parts, source }) {
/**
* The renderer's camera and query ports for the layer's scene: the bound
* renderer's, or those the default renderer's adapter builds over a viewer
* renderer's, or those the Cesium adapter builds over a viewer with no
* renderer bound.
*/
const cameraPort = () => findCamera(layerState._viewer);
+1 -1
View File
@@ -6,7 +6,7 @@
*
* The renderer's plugin may hand the application a map engine of its own
* (`mapEngine` in `src/render/applicationHooks.js`); when it hands none, the
* renderer switches through its globe port (`globeEngine.js`). A viewer
* hands none switches through its globe port (`globeEngine.js`). A viewer
* with no renderer bound uses the engine its adapter
* provided as it loaded (the Cesium one through the package's
* `./render/cesium/unbound` export).
+1 -1
View File
@@ -1,7 +1,7 @@
/**
* @module maps/globeEngine
* @description The map engine (`engine.js`) over the renderer contract's
* globe port, for when the renderer's plugin hands the application no map
* globe port, for a renderer whose plugin hands the application no map
* engine of its own (`src/render/applicationHooks.js`). The map stacks'
* sources become the port's specs: Esri and OSM as `xyz` imagery, Cesium
* ion's world imagery as `world` imagery, the photoreal stack as the port's
+3 -4
View File
@@ -1,9 +1,8 @@
/**
* @module render/cesium/plugin
* @description The Cesium renderer plugin made with options, for an
* application that hands it something of its own: `cameraController`, the
* shared camera controller's factory, which then drives Cesium's camera
* and takes the user's input in place of Cesium's own controls
* @description The Cesium renderer plugin made with options:
* `cameraController`, a camera controller's factory, which then drives
* Cesium's camera and takes the user's input in place of Cesium's own controls
* (`controlledCamera.js`). Without options it is the default plugin the
* application scene loads (`application.js`).
*/
+2 -2
View File
@@ -1,6 +1,6 @@
/**
* The renderer conformance suite (`index.js`): every check run against a
* renderer through the contract alone, in Node or in a browser page.
* The renderer conformance suite (`index.js`): every check run against the
* Cesium renderer or the stub through the contract alone, in Node or in a browser page.
*/
import type {
CameraPose,
+1 -1
View File
@@ -1,7 +1,7 @@
/**
* @module render/conformance
* @description The renderer conformance suite. It runs every check against
* a renderer through the contract alone, in Node or in a browser page, and
* the Cesium renderer or the stub through the contract alone, in Node or in a browser page, and
* reports each as passed, failed or skipped.
*
* A harness says how to make the renderer under test and drive its clock:
+2 -2
View File
@@ -370,8 +370,8 @@ export interface NativeCamera {
}
/**
* A camera controller, as an application hands one to a renderer without a
* camera of its own (or in place of its own): given the native camera, the
* A camera controller, handed to a renderer in place of its own camera:
* given the native camera, the
* input port's pointer events and the page's keys, it makes the camera port.
* The renderer runs `frame.beforeUpdate` before its `preUpdate` listeners
* and `frame.afterUpdate` after them, each tick, drawn or not.
+1 -1
View File
@@ -219,7 +219,7 @@ test('a draw set’s events: ready with the id, loadFailed with the id and why',
});
test('members added to version 0 later are optional, each behind its capability', () => {
// A renderer written before an addition still conforms without it.
// A renderer conforms without them.
assert.equal(PORTS.globe.isGlobeVisible, 'globeVisibility');
assert.equal(PORTS.camera.followFrame, 'followFrame');
// Item fields added later are optional too.
+1 -1
View File
@@ -1,6 +1,6 @@
/**
* Full-screen effects: visual styles, bloom, sharpen and screen modulation.
* Each style is a plain full-screen pass over the frame's colour. The
* Each style is a plain full-screen pass over the frame's colour. The application owns
* application owns the styles and defines them on the renderer
* renderer runs the same set; a renderer's own styles are extra ones.
*/
+1 -2
View File
@@ -285,8 +285,7 @@ export interface LoadProgress {
/**
* `surface`: what `against: 'surface'` heights answer from has loaded what
* is in view: the terrain while the globe is shown, otherwise the drawn
* tiles; false when neither is drawn. A renderer that predates it answers
* as `base`.
* tiles; false when neither is drawn.
*/
export type SettleKind = 'base' | 'tiles' | 'terrain' | 'imagery' | 'surface';
+1 -1
View File
@@ -1,6 +1,6 @@
/**
* The renderer contract: what the application asks of a renderer, typed
* than the default one can draw the same application.
* one file per port.
*/
export * from './common';
export * from './renderer';
+2 -2
View File
@@ -173,8 +173,8 @@ export interface Renderer {
releaseUnused(): void;
on(event: 'error', cb: (error: Error) => void): Off;
/**
* The drawing context was lost, or came back. Where the renderer cannot
* restore its context it never sends `contextRestored`; the application
* The drawing context was lost, or came back. A renderer that cannot restore its context
* never sends `contextRestored`; the application then makes
* a new renderer.
*/
on(event: 'contextLost' | 'contextRestored', cb: () => void): Off;
+1 -1
View File
@@ -9,7 +9,7 @@
const renderers = new WeakMap();
/**
* Ports built for scene objects no renderer is bound to (a viewer of a
* Ports built for scene objects no renderer is bound to (a Cesium viewer
* made directly, say), per port: each `{port, dispose}` kept for as long
* as its scene object lives, or until a renderer is bound to it. The
* renderer adapter provides the factory each is built with as it loads.
+2 -2
View File
@@ -1,7 +1,7 @@
/**
* The stub renderer's camera (`camera.js`): the reference camera's poses,
* views, flights and events in plain maths, which a renderer of its own can
* build its camera port on.
* views, flights and events in plain maths, which a camera port can be
* built on.
*/
import type { CameraPort, Ecef, GeoRect, Vec3 } from '../contract/index';
+1 -1
View File
@@ -5,7 +5,7 @@
* 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.
* conformance 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.
*/
+3 -3
View File
@@ -1,6 +1,6 @@
/**
* A public entry that reaches the renderer bridge (`rendererOf.js`) may hand
* `cameraOf` a viewer of the caller's own, with no renderer bound. The
* `cameraOf` a Cesium viewer with no renderer bound. The
* bridge builds a camera port for it with the factory the Cesium adapter
* provides as `render/cesium/camera.js` loads, so every such entry must load
* that module too. It loads `render/cesium/credits.js`, whose factory
@@ -183,7 +183,7 @@ const CAMERA_FROM_CALLER = new Set([
'./maps/controller',
// The application shell and what assembles it: their controls fly, read
// the eye, shade the globe and set styles through the ports alone; the
// application's renderer is bound to its viewer, and a viewer of the
// application's renderer is bound to its viewer, and a viewer with no
// renderer bound gets its ports from `./render/cesium/unbound`.
'./ui/shell',
'./ui/composition',
@@ -195,7 +195,7 @@ const CAMERA_FROM_CALLER = new Set([
// when it is given none), so its own viewer needs no factory.
'./application/scene',
// The map stacks switch through the renderer's map engine or its globe
// port (`maps/globeEngine.js`), which a viewer of the caller's own gets
// port (`maps/globeEngine.js`), which a viewer with no renderer bound gets
// from `./render/cesium/unbound`.
'./maps/defaults',
// It restores a shared view through the camera, frame and canvas of the
+1 -1
View File
@@ -2,7 +2,7 @@
* @module sky
* @description The sky background, Cesium-free: catalogue stars over a
* soft Milky Way, both in ICRF/J2000, and the precise ICRF-to-fixed rotation
* a renderer may provide for the rest of the application.
* the Cesium renderer provides for the rest of the application.
*/
export {
+1 -1
View File
@@ -1,7 +1,7 @@
import { radioLayer } from '../data/radio.js';
import { bindRenderer } from '../render/rendererOf.js';
import { bindFakeDraw } from './fakeDrawPort.mjs';
// The layer's clicks and floors take a viewer of the test's own, as a
// The layer's clicks and floors take a viewer of the test's own, with no
// renderer bound: its factories load as `./render/cesium/unbound` loads them.
import '../render/cesium/unbound.js';
+1 -1
View File
@@ -1,4 +1,4 @@
/** A row of a group an application adds to the Display panel. */
/** A row of a group added to the Display panel. */
export type DisplayGroupRow =
| {
kind: 'toggle';
+2 -2
View File
@@ -1,6 +1,6 @@
/**
* Groups of controls an application adds to the Display panel, under
* Effects: toggles, sliders and notes it describes and answers itself.
* Groups of controls added to the Display panel, under
* Effects: toggles, sliders and notes, each answered by whoever added it.
*/
import { applicationPinia } from './vueRuntime.js';
import { useDisplayStore } from './stores/display.js';
+1 -1
View File
@@ -1,4 +1,4 @@
// src/ui/displayGroups.test.mjs — an application's groups reach the Display
// src/ui/displayGroups.test.mjs — added groups reach the Display
// panel's store on the page's Pinia.
import test from 'node:test';
import assert from 'node:assert/strict';
+1 -1
View File
@@ -803,7 +803,7 @@ test('the real portal lays out once the groups have moved and puts back the focu
assert.deepEqual(layouts, [true]);
});
test('a group an application adds to Effects shows its toggles, notes and sliders, and goes', async (t) => {
test('a group added to Effects shows its toggles, notes and sliders, and goes', async (t) => {
const { store, $ } = fixture(t);
const changes = [];
store.publishGroup('conditions', {
+1 -1
View File
@@ -29,7 +29,7 @@ export const useDisplayStore = defineStore('gev-display', () => {
}
/**
* The groups an application adds under Effects, in the order first
* The groups added under Effects, in the order first
* published: each `{id, rows}`. A row is a `toggle` (`{kind, id, label,
* icon?, title?, checked, onChange(checked)}`), a `slider` (`{kind, id,
* label, min, max, value, onChange(value)}`, its value shown in percent)