Files
gods-eye-view/src/render/contract/renderer.d.ts
T
Sameh KhamisandManjunath Paparaju 3a0842c103 Draw the card previews through the renderer, and show vessel photos too
- The route globe, turning model and cockpit view are the renderer's: the
  Cesium plugin hands them over as its `cardPreviews` application hook
  (src/render/cesium/cardPreviews.js), and the card's tiles keep only the
  words, figures and HUD laid over them. Nothing in the UI reaches Cesium,
  and a renderer without the hook leaves the card its photo and figures.
- The turning model is the fleet model the globe draws for the aircraft's
  type, from the set loaded at startup, so opening a card fetches nothing.
  The flights layer's record now carries the type code and emitter category
  that pick it.
- The photo comes from the item's own layer: the flights layer's
  Planespotters photo for the plane it tracks, and the vessels layer's Open
  Vessel Photos photo for the vessel selected, with its credit. It no longer
  waits for Contacts to follow the same aircraft.
- The satellite models are left out: the card shows a satellite's ground
  view and graphs its altitude and speed.
- The route globe's airport codes are drawn into its own small scene, the
  compass reads its course in the active language, the callouts no longer
  speak to screen readers every six seconds, and figures use the app's
  number format. Esri's tile address and credit live in one place.

Co-authored-by: Manjunath Paparaju <[email protected]>
2026-11-16 15:44:35 -08:00

257 lines
8.9 KiB
TypeScript

/**
* The renderer itself: what a plugin creates and what the application holds.
*
* A renderer draws the globe and what the application asks it to draw, owns the camera,
* and answers queries about what is on screen. The application keeps every record of
* its own; it never reads a renderer to learn its own state, only what the
* renderer itself measures (picks, depth, heights, readiness).
*/
import type { Capability, Off, ScreenRect } from './common';
import type { CameraPort } from './camera';
import type { CreditsPort } from './credits';
import type { DrawPort } from './draw';
import type { EffectsPort } from './effects';
import type { FramePort } from './frame';
import type { GlobePort, SkySettings } from './globe';
import type { InputPort } from './input';
import type { QualityPort } from './quality';
import type { QueryPort } from './query';
/** The version of the contract this file describes. */
export type ContractVersion = '0';
/** What the application is given to make a renderer. */
export interface RendererPlugin {
/** Stable id, recorded with each session (`'cesium'`, ...). */
id: string;
create(options: CreateOptions): Promise<Renderer>;
/**
* What the plugin hands the application beside the contract for a
* renderer it made, asked once, right after `create` resolves. Omitted:
* none.
*/
applicationHooks?(renderer: Renderer): ApplicationHooks;
}
/**
* What the renderer's plugin hands the application beside the contract; the
* application uses each where given and does without where not. None is a
* contract member: what the renderer should do is in the ports.
*/
export interface ApplicationHooks {
/**
* The renderer's own map engine, which the map stacks switch through in
* place of the globe port (`src/maps/engine.js`).
*/
mapEngine?: unknown;
/**
* True when the renderer shows its credits in a display of its own;
* otherwise the application shows what the credits port lists.
*/
ownCreditDisplay?: boolean;
/**
* Drop the draw commands the renderer keeps for a while after it stops
* drawing them; run after a layer turns off.
*/
trimStaleCommands?(): void;
/** Whether an entity is one the renderer draws itself. */
viewerDrawsEntity?(entity: unknown): boolean;
/** Values QA scripts read from the page's debug handle. */
qaHandles?: Readonly<Record<string, unknown>>;
/**
* Show a recoverable notice when the renderer stops drawing (an error, a
* lost context), with Retry and, if `allowReload`, Reset, by publishing it
* to `store`. Returns its removal.
*/
renderFailureNotice?(options: {
allowReload: boolean;
store: RenderFailureStore;
}): () => void;
/** The Context card's previews of a picked aircraft. */
cardPreviews?: CardPreviews;
}
/**
* Previews the Context card draws into an element of its own. Each returns
* at once; one that cannot be made calls its `onFailed`.
*/
export interface CardPreviews {
/**
* A model turning on its own, from its GLB's bytes, starting to face
* `heading` (degrees); `viewRange` is the camera's distance in bounding
* radii. `onPhase` says when it turns to wire for its scan and back;
* `onCycle` when a look and its scan end, with the drawing time they took.
*/
model(
container: HTMLElement,
model: {
gltf: Uint8Array | ArrayBuffer;
basePath?: string;
heading?: number;
viewRange?: number;
},
events?: {
onPhase?(phase: 'plain' | 'scan'): void;
onCycle?(ms: number): void;
onFailed?(): void;
},
): CardPreview<void>;
/** A flight's route from `from` to `to` on a small globe, the craft `at`. */
route(
container: HTMLElement,
route: CardRoute,
events?: { onFailed?(): void },
): CardPreview<CardRoute>;
/** The view ahead from an aircraft's position, height and heading. */
cockpit(
container: HTMLElement,
craft: CardCraft,
events?: { onFailed?(): void },
): CardPreview<CardCraft>;
}
/** A place on a card's route: an airport's code and position, degrees. */
export interface CardPlace {
code?: string;
lat: number;
lon: number;
}
export interface CardRoute {
from: CardPlace;
to: CardPlace;
at?: { lat: number; lon: number } | null;
}
/** An aircraft's position (degrees), height (metres) and heading (degrees). */
export interface CardCraft {
lat: number;
lon: number;
altitudeM?: number | null;
heading?: number | null;
}
/** One preview: hidden, it rests on its last frame. */
export interface CardPreview<Values> {
setActive(active: boolean): void;
update(values: Values): void;
destroy(): void;
}
/** Where a renderer's failure notice is published for the application to show. */
export interface RenderFailureStore {
/** The notice shown now, or null. */
readonly renderFailure: RenderFailureNotice | null;
/** Show a notice, or none with null. */
publishRenderFailure(next: RenderFailureNotice | null): void;
}
/** A notice that the renderer stopped drawing. */
export interface RenderFailureNotice {
/** Why: an error in a frame, or a lost graphics context. */
reason: 'render-error' | 'context-lost';
/** The error's description, or empty. */
detail: string;
/** Draw again; after a lost context, reload the page. */
retry(): void;
/** Open the application's root address, or null where it must not. */
reset: (() => void) | null;
}
export interface CreateOptions {
/** The element the renderer fills. It creates its own canvas inside. */
container: HTMLElement;
/** Google Maps Platform key for photorealistic tiles. */
googleApiKey?: string;
/** Short-lived Google session tokens, when the key is held server-side. */
googleTokens?: () => Promise<string>;
/**
* The token for the renderer's world data: `world` terrain and imagery
* and the photoreal `fallback`. For the default renderer, a Cesium ion
* token.
*/
worldDataToken?: string;
/** Initial multisampling; quality can change it later. */
msaa?: 0 | 2 | 4 | 8;
/** Sky applied before the first frame, so nothing draws in the wrong sky. */
sky?: Partial<SkySettings>;
/** Scene time in epoch ms. The application passes its boot time. */
time?: number;
/**
* The clocks the renderer reads, for `FrameTime.now`, the camera's
* `moveEnd` wait, input, flights and tweens, and for inertia where it
* times that itself (Cesium's keeps Cesium's own timing): `now` on the
* `performance.now()` timeline, `date` in epoch ms. Omitted: the
* browser's. Tests pass virtual ones.
*/
clock?: { now(): number; date(): number };
/** Aborts creation; the renderer cleans up whatever it had built. */
signal: AbortSignal;
}
export interface CaptureOptions {
type?: 'png' | 'jpeg';
/** JPEG quality, 0..1. */
quality?: number;
/** Output scale relative to the canvas's CSS size. */
scale?: number;
/** Part of the canvas, in CSS pixels. */
crop?: ScreenRect;
}
export interface SettleResult {
state: 'settled' | 'timeout' | 'failed';
blockers: string[];
}
export interface Renderer {
readonly id: string;
readonly contractVersion: ContractVersion;
readonly capabilities: ReadonlySet<Capability>;
readonly canvas: HTMLCanvasElement;
readonly frame: FramePort;
readonly globe: GlobePort;
readonly draw: DrawPort;
readonly camera: CameraPort;
readonly query: QueryPort;
readonly input: InputPort;
readonly effects: EffectsPort;
readonly credits: CreditsPort;
readonly quality: QualityPort;
/**
* The last presented frame as an encoded image. Once the renderer is
* destroyed it rejects with a "renderer destroyed" error.
*/
capture(options?: CaptureOptions): Promise<Blob>;
/**
* The last presented frame's pixels, synchronously, for loops that render
* a frame and read it at once (a share clip, a black-frame check). Call it
* right after `frame.renderNow()`.
*/
readPixels(options?: { crop?: ScreenRect; scale?: number }): ImageData;
/**
* Resolves once what is in view has loaded and the last presented frame
* shows it (no redraw of the renderer's own is pending), or the timeout
* passes, or a load failed for good. `blockers` names what was still loading or
* failed (`'tiles'`, `'imagery:<id>'`, `'models'`, ...); empty when settled.
*/
whenSettled(options?: { timeoutMs?: number }): Promise<SettleResult>;
/** Follows the container's size. */
resize(): void;
/** Frees caches and GPU memory nothing in view uses. */
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
* then makes a new renderer.
*/
on(event: 'contextLost' | 'contextRestored', cb: () => void): Off;
/**
* Lets go of everything. Afterwards handles do nothing (`Handle`), and
* `frame.renderOnce` and `capture` reject with a "renderer destroyed"
* error, as does a `renderOnce` still waiting.
*/
destroy(): void;
}