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

+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