Files
gods-eye-view/src/render/cesium/appRenderer.js
T
Sameh Khamis aa58886e40 feat(render): the Cesium renderer can run an application's camera controller
createCesiumRendererPlugin({cameraController}) (render/cesium/plugin) puts
the camera port on the shared camera controller over a native camera on
Cesium's (controlledCamera.js): poses written exactly, out of any lookAt
transform, the vertical field of view as Cesium's wide-side fov and kept
on a resize. Cesium's own controls hold their input off and their
collision off while it drives; the controller runs before and after the
preUpdate listeners, and what it throws is reported. A followed item's
position is where its GPU icon set draws it (drawnPosition), and the
input port's camera holds are the controller's.

The conformance harness, given a controller, steps a virtual clock 1/60 s
a frame for ticks and pointer events, so flights and pointer scripts are
compared frame by frame.
2026-11-12 11:41:54 -08:00

206 lines
7.6 KiB
JavaScript

/**
* @module render/cesium/appRenderer
* @description The application's default renderer plugin: today's Cesium
* viewer, set up exactly as before, behind the contract's `RendererPlugin`
* (`src/render/contract/renderer.d.ts`).
*
* The renderer it makes is transitional. Its ports are the shared Cesium
* ports (`ports.js`), the ones the conformance renderer is checked with,
* and it has every member of the contract. The application's base (the
* photoreal tiles, the map stack's imagery and terrain) is still loaded
* through the Cesium map engine (`mapEngine.js`), which the plugin hands
* the application with the renderer (its `applicationHooks`); the globe
* port drapes its imagery on that base as drawn (see `globe.js`).
* `whenSettled` waits for the globe, the scene's 3D tiles and what the draw
* sets hold.
*
* What only this renderer needs at startup is set up here: the free-look
* height limit, keyboard access to the credits' expand link (in the page's
* language). The plugin's `applicationHooks` are what the application
* uses where a renderer has them: the map engine, stale command trimming,
* whether an entity is the viewer's own, and the viewer QA scripts read.
* Adapter code reaches the viewer behind a renderer through
* `cesiumViewerOf` (`viewers.js`), never through a renderer member, so no
* engine type crosses the contract.
*/
import { createApplicationViewer } from './applicationViewer.js';
import { CONTRACT_VERSION } from '../contract/index.js';
import { bindRenderer } from '../rendererOf.js';
import { FREE_LOOK_MAX_HEIGHT_METERS } from '../../globeInView.js';
import { createCesiumInput } from './input.js';
import { cesiumCapabilities, createCesiumPorts } from './ports.js';
import { cesiumMapEngine } from './mapEngine.js';
import { installFreeLookHeightLimit } from './freeLookLimit.js';
import { trimStaleSceneCommands } from './sceneCommandRelease.js';
import { configureCreditKeyboardAccess } from './creditKeyboard.js';
import { onLocaleChange } from '../../i18n/index.js';
import { cesiumViewerOf, recordViewer } from './viewers.js';
export { cesiumViewerOf };
/** @typedef {import('../contract/renderer').Renderer} TransitionalRenderer */
/** A Set no one can change once built, so `capabilities` stays true. */
export class ReadonlySet extends Set {
#sealed;
constructor(values = []) {
// Filled here, not by Set's constructor: it would call the guarded add
// before the private field exists.
super();
for (const value of values) super.add(value);
this.#sealed = true;
}
add(value) {
if (this.#sealed) throw new TypeError('capabilities are read-only');
return super.add(value);
}
delete() {
throw new TypeError('capabilities are read-only');
}
clear() {
throw new TypeError('capabilities are read-only');
}
}
/**
* The Cesium plugin over a viewer factory; tests pass a fake one. With
* `cameraController` (the shared camera controller's factory), its camera
* port is that controller's over Cesium's camera, which takes the user's
* input in place of Cesium's own controls (`controlledCamera.js`).
* @param {{createViewer?: typeof createApplicationViewer,
* cameraController?: Function}} [options]
*/
export function createCesiumRendererPlugin({
createViewer = createApplicationViewer,
cameraController,
} = {}) {
return Object.freeze({
id: 'cesium',
/**
* The credentials are the globe port's, for a base set through it; the
* scene still loads the application's own base itself.
* @param {import('../contract/renderer').CreateOptions} options
* @returns {Promise<TransitionalRenderer>}
*/
async create({
container,
signal,
googleApiKey,
googleTokens,
worldDataToken,
}) {
signal?.throwIfAborted();
// Provider attribution stays visible, including clean-view and recording.
const creditContainer = document.createElement('div');
creditContainer.id = 'cesium-credits';
document.body.appendChild(creditContainer);
let viewer;
let ports;
let input;
let capabilities;
let releaseFreeLook = () => {};
let offLocale = () => {};
try {
viewer = createViewer({ container, creditContainer });
capabilities = new ReadonlySet(cesiumCapabilities(viewer.scene));
ports = createCesiumPorts(viewer, {
capabilities,
credentials: { googleApiKey, googleTokens, worldDataToken },
...(cameraController ? { cameraController } : {}),
});
input = createCesiumInput(viewer, {
query: ports.query,
report: ports.report,
...(ports.suspendCamera
? { suspendCamera: ports.suspendCamera }
: {}),
});
ports.attachInput?.(input.port);
// Free look is limited to low heights from the start, on Cesium's
// own controls (the controller keeps its own limits).
if (!cameraController)
releaseFreeLook = installFreeLookHeightLimit(
viewer,
FREE_LOOK_MAX_HEIGHT_METERS,
);
configureCreditKeyboardAccess(document);
offLocale = onLocaleChange(() =>
configureCreditKeyboardAccess(document),
);
} catch (error) {
offLocale();
releaseFreeLook();
input?.dispose();
ports?.dispose();
if (viewer && !viewer.isDestroyed()) viewer.destroy();
creditContainer.remove();
throw error;
}
let unbind = () => {};
const renderer = Object.freeze({
id: 'cesium',
contractVersion: CONTRACT_VERSION,
capabilities,
canvas: viewer.canvas,
frame: ports.frame,
globe: ports.globe,
draw: ports.draw,
camera: ports.camera,
query: ports.query,
input: input.port,
effects: ports.effects,
quality: ports.quality,
capture: ports.capture,
readPixels: ports.readPixels,
releaseUnused: ports.releaseUnused,
credits: ports.credits,
whenSettled: ports.whenSettled,
on: ports.on,
resize() {
viewer.resize();
},
destroy() {
try {
offLocale();
releaseFreeLook();
input.dispose();
ports.dispose();
if (!viewer.isDestroyed()) viewer.destroy();
} finally {
// Bound until the viewer is gone: a late `cameraOf` must not
// build a camera of its own over the application's viewer.
unbind();
creditContainer.remove();
}
},
});
recordViewer(renderer, viewer);
unbind = bindRenderer(viewer, renderer);
return renderer;
},
/**
* @param {TransitionalRenderer} renderer
* @returns {import('../contract/renderer').ApplicationHooks}
*/
applicationHooks(renderer) {
const viewer = cesiumViewerOf(renderer);
return {
mapEngine: cesiumMapEngine,
// Cesium's credit display (#cesium-credits) shows the credits.
ownCreditDisplay: true,
// Drops the draw commands the scene keeps after it stops drawing
// them; run after a drawn frame (see sceneCommandRelease.js).
trimStaleCommands: () => trimStaleSceneCommands(viewer.scene),
// Whether an entity is one of the viewer's own (Cockpit asks whether
// the aircraft it flies still draws).
viewerDrawsEntity: (entity) => viewer.entities.contains(entity),
// QA scripts drive and read the viewer itself.
qaHandles: { viewer },
};
},
});
}
/** The default plugin. */
export const cesiumRenderer = createCesiumRendererPlugin();