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

+11 -12
View File
@@ -61,15 +61,14 @@
on. `./render/weather` and `./weather/effects` export the shared rules and
the strengths of a weather observation. The Cesium renderer does not draw
weather (samehkhamis).
- An application can add its own groups of toggles, sliders and notes to the
Display panel under Effects, with `publishDisplayGroup` from
`./ui/display/groups` (samehkhamis).
- The globe opens at planet level, the whole Earth in view, on every
renderer, instead of flying in to Austin. A shared link still flies from
there to its view. An application can start somewhere else, a city for
instance, with the `startView` option of `createApplicationControls`
(longitude, latitude and height, and heading and pitch in degrees)
- Groups of toggles, sliders and notes can be added to the Display panel
under Effects, with `publishDisplayGroup` from `./ui/display/groups`
(samehkhamis).
- The globe opens at planet level, the whole Earth in view, instead of
flying in to Austin. A shared link still flies from
there to its view. The `startView` option of `createApplicationControls`
starts it somewhere else, a city for instance (longitude, latitude and
height, and heading and pitch in degrees) (samehkhamis).
- An application's own tool can take the pointer as Draw does, and its click
handlers can yield while a tool holds it, as the layers' do (`pointer` from
`createApplicationTools`) (samehkhamis, #1641).
@@ -94,14 +93,14 @@
port. A click's `hit`, `topHit`, `drawHit` and `drill()` hits, and
`pickAt`'s result, are the renderer contract's `Hit`; positions are plain
`{ x, y }`; `HANDLER_EVENT_TYPES` is gone. Cesium's own picks stay on
`event.native` (and `event.pick` and `event.pickWindow`). A viewer of your
own with no renderer bound needs `gods-eye-view/render/cesium/unbound`
`event.native` (and `event.pick` and `event.pickWindow`). A viewer with no
renderer bound needs `gods-eye-view/render/cesium/unbound`
loaded once first (samehkhamis).
- `gods-eye-view/application/operations` no longer reaches Cesium: ground
snapping and mesh floor sampling ask the renderer's globe, camera and query
ports, and see through the caller's draw sets by id (the raw
`excludeObjects` option and exclusion callbacks are gone). A viewer of your
own with no renderer bound needs `gods-eye-view/render/cesium/unbound`
`excludeObjects` option and exclusion callbacks are gone). A viewer with no
renderer bound needs `gods-eye-view/render/cesium/unbound`
loaded once first, or location framing throws and snaps answer nothing
(samehkhamis).
- `gods-eye-view/layers/traffic` (and `gods-eye-view/application/sources`,
+1 -1
View File
@@ -153,7 +153,7 @@ does this and returns the dispatcher as `scene.input`.
height queries go. Layers, tools and the camera ask it instead of asking the
renderer's query port (`sampleHeight`, `sampleHeightNow`, `clampToSurface`)
or the scene themselves, so how the renderer answers heights can change
in without touching them. Pass the viewer the renderer is bound to, not its
without touching them. Pass the viewer the renderer is bound to, not its
scene. A viewer with no renderer bound is answered by the Cesium adapter's
fallback once the caller has loaded `gods-eye-view/render/cesium/unbound`;
until then, every query answers `null`.
+6 -6
View File
@@ -1854,7 +1854,7 @@ Islands`, or `M6.4` with no place).
Air quality (`./layers/air-quality`) draws its station discs as one renderer
draw set of ground-clamped fills and reads the view through the camera port; it
no longer reaches Cesium, so a caller handing it a Cesium viewer,
own, with no renderer bound, loads the `./render/cesium/unbound` export once
with no renderer bound, loads the `./render/cesium/unbound` export once
first.
Cockpit (`./ui/cockpit`) flies the camera through the camera port on the frame
@@ -6329,7 +6329,7 @@ between the sets. The renderer moves and turns an icon without restyling it.
Rotation is computed in screen space through the query port's projection
(`perspectiveCourseRotation`), as before. Clicks read the draw-port hit. The
layer no longer reaches Cesium, so a caller handing it a Cesium viewer,
their own, with no renderer bound, loads the `./render/cesium/unbound` export
with no renderer bound, loads the `./render/cesium/unbound` export
once first. Transit listens to the camera port at its own `changed` threshold
(0.05); the port measures each listener separately, so no layer changes
another's camera trigger.
@@ -7690,7 +7690,7 @@ request viewbox and continues searching without that geographic preference.
- UTILITIES ▸ **Draw** turns the globe into a whiteboard drawn by hand. Pick a shape (icon buttons for Area, Line and Pin) and a colour swatch for the next shape, click the vertices on the real world, and finish. **Keyboard contract, live only while Draw is on and never while you are typing in another field:** Enter finishes the shape (as does a double-click, and the two cannot both submit it — the session is replaced before the annotate call is awaited); Backspace removes the last vertex; Esc cancels the shape in progress, and a second Esc — Esc on an empty session — leaves draw mode. **Clear** wipes the board (the shape in progress and every placed mark), so removing marks does not require the console or the microphone.
- **Drawn shapes are listed under Draw like Import's files** (`src/ui/views/panels/DrawMarkList.vue`, rows worded by `presentDrawMarks` in `src/annotations/drawMarks.js`): one row per hand-drawn mark (`manual: true`; voice marks are not listed) with its colour swatch, its name, and show/hide, fly-to and remove. The draw tool publishes the rows with the rest of its controls and answers the row actions (`renameDrawMark`, `recolorDrawMark`, `toggleDrawMark`, `flyToDrawMark`, `removeDrawMark`) through the display store; it republishes on the engine's `onChange`, so a voice clear or an expiry updates the list. Rows are keyed and updated in place: a board change never takes a name being typed (the field keeps its draft while focused) or the button under a click. The name is saved on Enter or on leaving the field, once; Esc restores it, before anything else and with the row's colours open too. Both keep focus in the field, so neither drops it to the page or leaves Draw. The swatch opens the five colours right after it (shown at the end of the row), with the current colour focused; the arrows, Home and End try another, and a click or Esc closes them and returns focus to the swatch. Both colour groups (the next shape's and a row's) are one `DrawSwatches` radio group with a single tab stop, coloured from `DRAW_COLOR_CSS`; on touch screens each dot answers a 24 px target. An unnamed shape shows its kind, and an unnamed line its length; a renamed line keeps its length (`Ridge walk — 950 m`). **Hidden** keeps a mark on the board at alpha 0, and the world renderer takes every one of its entities out (`show = false`), so no material that keeps its own colour (the line's flowing stroke) still paints it; the screen renderer does not project a hidden callout, so it cannot push a visible label aside; `fly_route` skips a hidden route; and with every mark hidden the annotations render hold is released. **Fly to** is an immediate navigation (`runImmediateNavigation('drawing', …)`), like Import's: Cockpit refuses it and a running orbit, follow or track lets go first. A line is framed by its whole path, across the antimeridian too.
- Runtime entry: `createApplicationTools` (`src/app/tools.js`, behind the `src/standalone/tools.js` shim) calls `initDrawTool({ viewer, annotations, navigation, publish, connect, markActions })` after `initAnnotations` and defers its `destroy()`, so disposing the shell returns every DOM listener, the pointer subscriptions, the preview draw sets, the borrowed click actions and the `window.__gevDrawTool` handle. The live preview (a dashed rubber band, dashed behind the surface too through the line's `depthFail` style, and a dot per vertex) is two sets on the renderer's draw port, so the tool no longer reaches Cesium; the rubber band follows each move's `pickPosition`, the dispatcher's sensor-corrected pick-buffer point, as clicks do. Its controls are Vue views in the UTILITIES panel (`DrawControls.vue`, `DrawMarkList.vue`) that render what the tool publishes to the display store and call its actions. That handle (`setActive`, `setShape`, `addVertex(lon, lat)`, `finish`, `cancel`, `clearAll`, `marks`, `setColor`, `diagnostics`) is the no-mouse test seam.
- **The pointer, for an application's own tool.** `createApplicationTools` also returns `pointer` (`data/inputOwnership.js`): `claim(owner, { onLost })` takes the pointer as Draw does, from any tool holding it, and returns its lease; `onLost` is called once when a newer claim takes it, and the tool turns itself off there; `release(lease)` gives it back; `isFree()` lets the application's own click handlers yield, as the layers' do.
- **The pointer, for any other tool.** `createApplicationTools` also returns `pointer` (`data/inputOwnership.js`): `claim(owner, { onLost })` takes the pointer as Draw does, from any tool holding it, and returns its lease; `onLost` is called once when a newer claim takes it, and the tool turns itself off there; `release(lease)` gives it back; `isFree()` lets the application's own click handlers yield, as the layers' do.
- **Row actions are an application's own.** `createApplicationTools({ drawMarkActions })` hands `initDrawTool` buttons for drawn areas' and lines' rows; the standalone shell passes none, so the open-source build shows no new button and makes no new request. Each action (`drawMarkActions` in `src/annotations/drawMarks.js`) is `{ id, icon, label(name), shapes: ['area', 'line'], accepts?(geometry, shape), run({ id, shape, name, title, geometry }) }`: the icon a Material Symbols name, the label worded by the application, `name` the person's own and `title` the row's (the name, else `Area` or `Line · 950 m`), the geometry `drawMarkGeometry`'s `[lon, lat]` `Polygon` (closed; a `MultiPolygon` for an area handle with several parts) or `LineString`, longitudes wrapped into [-180, 180]. A pin, and a shape that crosses the antimeridian or has a part that cannot be given whole, has no geometry and is offered nothing. Malformed actions and repeated ids are dropped once, at construction. What `run` returns or resolves to is a note under the row (`role=status`; past 200 characters it is cut at a word with an ellipsis); the row is busy (`aria-disabled`, no second press) until it settles, a rejection or a throw clears the note and is logged (so an action words its own refusals and resolves with them), and a shape's note goes with the shape, so a late answer never lands on a removed one.
- Contract: a finished shape is submitted through the SAME `annotationEngine.annotate()` the voice agent uses, with geometry supplied and `manual: true` (`type: area` + `ring`, `type: route` + `path`, `type: pin` + coordinates). `resolveSpec` short-circuits manual specs (`resolveManualSpec`) so no geocoder, Places or Overpass call is made. A drawn area is a real (not synthesized) outline and drapes solid; a drawn line is a `route` with `mode: 'manual'`, labelled with its length and never a travel time; a pin is a point. Drawn marks therefore render with the whiteboard look, persist, appear in `.list()`, and clear with `clear_annotations` / `.clear()`. A drawn shape is never merged with another as a duplicate: every one is drawn on purpose, and every one is unnamed until its row names it, so two pins dropped close together are two pins.
- **A vertex is a lon/lat, and the mark is DRAPED.** Clicks are picked through `pickWorldFromScreen` — one of two scene helpers the annotation resolver factory (`src/annotations/resolver.js`) exposes alongside `sampleGroundHeight`, so the app has ONE depth-aware pick cascade rather than a second written beside it — which returns the height the pick landed on as well as the coordinate, so the live preview hangs on the roof or hillside under the pointer instead of sinking to sea level. The world renderer draws areas and routes with `clampToGround`, so the height is dropped at finish in one place (`finishSpec`) rather than being carried downstream and discarded silently: what you get is the outline you drew, lying on the surface beneath it.
@@ -7733,7 +7733,7 @@ request viewbox and continues searching without that geographic preference.
- **Files.** `/api/ghostmaps/file/{product}` serves only catalog products. Files are downloaded by commit-pinned raw URLs, so a CDN cannot return an older edition. They are cached on disk by blob sha, and blobs no current product uses are pruned. A request whose `?v=` names the current blob is `immutable`. Repository paths never reach the page.
- **Source ownership.** The application catalog receives `sources['s2-ghostmaps']` through the shared source contracts; an omitted or null source stays unavailable without opening a stream or fetching. The standalone source factory supplies the same-origin implementation and accepts replacements. Packed-image URLs are released on cancelled or failed product construction, and remain owned by a successfully loaded product until it is removed.
- **Voice and locales.** S2 can be toggled through its registered id and aliases. The model already sees the S2 GhostMaps brand in the id, and compact alias-hint separators keep the complete voice prompt within its existing 52,000-character limit; accepted aliases are unchanged. The row and reports are translated in Spanish, Russian and Simplified Chinese.
- **Rendering.** The page parses the KMZ with the import module's zip, KMZ and XML helpers into renderer draw sets (icons, lines and shapes) per product edition. The layer no longer reaches Cesium, so a consumer handing it a Cesium viewer, with no renderer bound, loads the `./render/cesium/unbound` export once first.
- **Rendering.** The page parses the KMZ with the import module's zip, KMZ and XML helpers into renderer draw sets (icons, lines and shapes) per product edition. The layer no longer reaches Cesium, so a caller handing it a Cesium viewer, with no renderer bound, loads the `./render/cesium/unbound` export once first.
- Points become ground-clamped icons with the depth test off, so they never sink into terrain or 3D tiles. Because the Google 3D map hides the globe, nothing else would stop far-side pins drawing through the planet. Pins are therefore horizon-culled with Street Level's `createHorizonCull` before their first frame and again whenever the camera moves.
- Lines and polygon outlines are ground-clamped lines; polygon fills are ground-clamped shapes.
- Styles, StyleMaps and inline styles are honoured. Icons come only from images packed in the same KMZ and at most 512 KB. Anything else uses a per-product round marker.
@@ -8129,8 +8129,8 @@ renderer's own objects: the record of files that still did,
- The renderer follows its container's size (`Renderer.resize`, from a
`ResizeObserver`).
- The credits: the Cesium renderer's plugin says it shows them in a display
its own (`ownCreditDisplay`; Cesium's `#cesium-credits`) keeps it. On any
other, the application shows what the credits port lists in its own line
its own (`ownCreditDisplay`; Cesium's `#cesium-credits`) keeps it. On the
stub, the application shows what the credits port lists in its own line
at the bottom left (`#gev-credits`, `src/ui/creditsView.js`): the inline
credits on the line, the rest (the layers' data credits among them) in
the "Data attribution" list it opens, a keyboard button with Escape to
+26 -28
View File
@@ -1,8 +1,8 @@
# Renderer contract
The renderer contract is what the application asks of a 3D renderer. A
renderer other than the default Cesium one can draw the same application if
it meets the contract. The contract is version `0`. Today the application
The renderer contract is what the application asks of a 3D renderer. The
Cesium renderer draws the application through it, and the stub renderer
stands in for it in tests. The contract is version `0`. Today the application
still drives Cesium directly; later work moves the layers onto the contract
one family at a time.
@@ -15,8 +15,8 @@ The package exports these modules:
| `gods-eye-view/render/camera/events` | The camera port's events: `changed` per listener, `moveStart`/`moveEnd`, command hooks |
| `gods-eye-view/render/conformance` | The conformance suite, reference scenes and visual comparison |
The pieces that do not depend on Cesium are exported too, each with its
these exports too, each with its own `.d.ts`:
The pieces that do not depend on Cesium are exported
too, each with its own `.d.ts`:
- `gods-eye-view/render/input/router`: the input port's leases and routing;
- `gods-eye-view/render/stub/camera`, `.../stub/viewRectangle` and
@@ -34,10 +34,9 @@ these exports too, each with its own `.d.ts`:
names match what it exports, that it type-checks under strict TypeScript and
that it imports no Cesium.
A camera of its own (a camera controller over a renderer without one) can
take the camera events from `render/camera/events` and the geodesy it needs
(`geodesicAt`, `horizonFrom` and the rest) from `gods-eye-view/geo`, so it
measures and fires exactly as the stub does. `CameraControllerFactory`
A camera controller takes the camera events from `render/camera/events`
and the geodesy it needs (`geodesicAt`, `horizonFrom` and the rest) from
`gods-eye-view/geo`, so it measures and fires exactly as the stub does. `CameraControllerFactory`
(`camera.d.ts`) types such a controller: what it is given (`NativeCamera`)
and what it gives back (the camera port and its two frame steps).
@@ -63,11 +62,11 @@ were removed or replaced (among them `camera.move`, `look`,
`rotateAround` and `zoom`, now step views placed with `setView`;
`query.sampleHeightNowMany`; `input.ctrlWheelZoom`, now the `ctrlWheel`
zoom input), `depthFailColor` and `depthFailDash` became one `depthFail`
style, and quality settings became detail only. A renderer written against
an earlier `0` follows those changes.
style, and quality settings became detail only. The Cesium port and the
stub follow those changes.
Some members and options were added to version `0` later. Each is
optional, so a renderer written before it still conforms:
optional:
- `globe.isGlobeVisible()` (capability `globeVisibility`) reads back whether
the globe surface is shown, for code that holds only the scene.
@@ -93,8 +92,8 @@ optional, so a renderer written before it still conforms:
`detail: {image, rectangle}`, a sharper image drawn in place of the base
one, and says how shells stack, blend and update. `FieldHandle.on('drawn')`
says once per spec or `update` that it is drawn, never while hidden. These
change `fields` itself rather than add to it, so the renderer follows
`fields` before must follow them. The Cesium adapter lists `fields` and
change `fields` itself rather than add to it, so a renderer that lists
`fields` follows them. The Cesium adapter lists `fields` and
draws `rasterShell` and `windStreamlines`. It reads the grid's samples as
points, the first column at `rectangle.west` and the first row at
`rectangle.north`, rows running south. Over the whole globe its paths
@@ -143,8 +142,7 @@ optional, so a renderer written before it still conforms:
- A rectangle shape's `rotation` (radians counter-clockwise) turns it about
its centre in longitude and latitude, as a KML ground overlay turns, and
its image fill turns with it. The Cesium port drapes image fills too, each
on a ground primitive of its own. A renderer that predates it draws the
rectangle unturned.
on a ground primitive of its own.
- `camera.controls.keepEarthFramed` (capability `keepEarthFramed`) stops
the user's outward zooms at a whole-Earth view (about 40,000 km, or
higher where a camera command left the eye) and, from high up, turns the
@@ -154,13 +152,13 @@ optional, so a renderer written before it still conforms:
(`zoomOutGuard.js`). The application turns it on where a renderer has it.
- `query.occlusionTest()` (capability `occlusionTest`) tests many points
against the depth of the frames drawn without waiting for the GPU; the
detection overlay leaves out the street vehicles it finds hidden. A WebGL
renderer that hands over its frame's depth gets one from
`@gods-eye-view/core/render/occlusion` (`createDepthOcclusionTest`, given a
`DepthSource`: depth packed into RGBA8 or a depth texture, standard or
logarithmic, with the view it was drawn from).
detection overlay leaves out the street vehicles it finds hidden. The
Cesium port builds its test with `gods-eye-view/render/occlusion`
(`createDepthOcclusionTest`, given a `DepthSource`: depth packed into
RGBA8 or a depth texture, standard or logarithmic, with the view it was
drawn from).
- `RendererPlugin.applicationHooks(renderer)` hands the application what
only some renderers have (`ApplicationHooks`); see
lies beside the contract (`ApplicationHooks`); see
[The application and its renderer](#the-application-and-its-renderer).
- `frame.renderNow()` throws when the frame fails to draw. With
`{ifDue: true}` it runs one tick of the loop now, as the loop's own would
@@ -197,7 +195,7 @@ off, and no check compares colours. With
none of its look, so the checks that read an exact colour (`bareSky` in
`checks/ports.js`) set that sky first. The
reference images under `src/render/conformance/goldens/visual/` are the
default renderer's own, for checking it against itself.
Cesium renderer's own, for checking it against itself.
The Cesium port lists `followAutodetect`: an `autodetect` follow is
Cesium's own AUTODETECT tracking frame, east-north-up on a still or slow
@@ -214,7 +212,7 @@ jump: from its first frame the eye is in the target's frame, and over
(its offset and its view each turned and eased with smoothstep, the view
ending on the target with no roll). The Cesium port, the stub and a camera
controller import that rule rather than restating it. The tracked aircraft
aircraft and followed trains use it with a `viewFrom` taken from the camera
and followed trains use it with a `viewFrom` taken from the camera
at the click: the eye's own view direction at its own range from the target,
so neither changes and only the eye's place moves, sliding the target to the
centre. The check `camera.follow.transition` pins it.
@@ -566,7 +564,7 @@ on (no `renderer.id`, no engine type, no engine object's presence).
the renderer. Code reaches the renderer's
ports through it (`findCamera`, `drawOf`, `canvasOf`...).
- **What only the Cesium renderer needs at startup** is done in its
`create`: for Cesium, the free-look height limit and keyboard access to its
plugin's `create`: the free-look height limit and keyboard access to its
credits' expand link (`src/render/cesium/appRenderer.js`).
- **What a plugin may hand the application beside the contract** is its
`applicationHooks(renderer)` (`ApplicationHooks`,
@@ -626,7 +624,7 @@ onCreate)` is the stub as a `RendererPlugin`. It has:
`scriptPicks`, `setHeights` and `cacheHeight`, and records its calls.
`testing.drawnPosition({ set, id }, aheadMs)` is where it draws an item now
(or `aheadMs` from now), so a
camera that is not the stub's own can follow drawn items there.
camera controller over the stub can follow drawn items there.
A listener that throws with nothing subscribed to `error` goes to
`reportError`; Node has none, so the stub rethrows it on a microtask and
`node:test` fails the running test. A test that expects a throw subscribes
@@ -635,8 +633,8 @@ The stub passes the whole conformance suite (`src/render/stub/stub.test.mjs`).
## Conformance suite
`runConformance(harness)` runs every check against a renderer through the
contract alone and reports each one as passed, failed or skipped. It runs in
`runConformance(harness)` runs every check against the Cesium renderer or
the stub through the contract alone and reports each one as passed, failed or skipped. It runs in
Node and in a browser page. A harness tells the suite how to drive the
renderer under test:
+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)