mirror of
https://github.com/bilawalsidhu/gods-eye-view.git
synced 2026-11-16 08:12:24 +00:00
Define the renderer contract, with a stub renderer and a conformance suite
The renderer contract is what the application asks of a 3D renderer. It is nine ports (frame, globe, draw, camera, query, input, effects, credits, quality) plus the renderer itself, one strict .d.ts per port in src/render/contract/. PORTS lists every member at run time, and a TypeScript-compiler test fails when the list and the types disagree on one member. An optional member exists only with its capability; a required one answers null or empty without it. Nothing in the application uses the contract yet. The stub renderer (src/render/stub/) implements every port in memory and draws nothing. Its camera is a port of the default camera's maths: views, lookAt, flights with their height arc and easing, rectangle framing on the geodesic midpoint, the view rectangle with its horizon and pole cases, changed thresholds, follows, and flights that finish inside the call. The conformance suite (src/render/conformance/) runs 59 checks against a renderer through the contract alone, in Node or in a browser page. The camera checks compare traces recorded from Cesium's own Camera, headless on a virtual clock (scripts/record-camera-goldens.mjs), to 1 mm, 1e-9 and 1e-3 px. The other checks cover listener rules on every subscription, the frame loop, draw sets, picks, motion clocks, heights, leases, imagery, styles, credits and quality knobs. The stub passes all of them but the model check, which needs a glTF asset. Reference scenes draw one scene per primitive family, a city and a calibration path from orbit to the street, from contract calls only and with no network. /dev/conformance/ draws them on the Cesium scene renderer (src/render/cesium/sceneRenderer.js), records references through a dev-server-only, loopback-only endpoint, and compares captures with pixelmatch's antialias detection plus a solid-pixel count. Measured on Cesium: every MSAA setting passes, and a dropped 4 px point, a dropped 2 px line and a 1 px shift of the view fail. visual.js states the limits. The package exports ./render/contract, ./render/stub and ./render/conformance. Documented in docs/RENDERER-CONTRACT.md, docs/CODE-BOUNDARIES.md and docs/CURRENT-STATE.md.
This commit is contained in:
1 parent
464c29a9ed
commit
8db995acfc
65 files changed
+12759
-9
No files matched your search
Vendored
+114
@@ -0,0 +1,114 @@
|
||||
/**
|
||||
* 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>;
|
||||
}
|
||||
|
||||
export interface CreateOptions {
|
||||
/** The element the renderer fills. It creates its own canvas inside. */
|
||||
container: HTMLElement;
|
||||
/** Where the app renders credits, when it has a place for them. */
|
||||
creditContainer?: 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>;
|
||||
/** Cesium ion token, for ion-hosted terrain and fallback tiles. */
|
||||
ionToken?: string;
|
||||
/** Initial multisampling; quality can change it later. */
|
||||
msaa?: 0 | 2 | 4 | 8;
|
||||
/** Keep the drawing buffer after presenting, for capture. */
|
||||
preserveDrawingBuffer?: boolean;
|
||||
/** 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 flights, inertia, tweens and
|
||||
* `FrameTime.now`: `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. */
|
||||
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, 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
|
||||
* a new renderer.
|
||||
*/
|
||||
on(event: 'contextLost' | 'contextRestored', cb: () => void): Off;
|
||||
destroy(): void;
|
||||
}
|
||||
Reference in new issue
Block a user