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
+200
@@ -0,0 +1,200 @@
|
||||
/**
|
||||
* Shared value types of the renderer contract.
|
||||
*
|
||||
* Only plain numbers, strings and typed arrays cross the contract: no engine
|
||||
* object ever does. Positions are f64 Earth-centred, Earth-fixed metres
|
||||
* (`Ecef`) or geodetic degrees and metres (`LonLatH`). Angles are radians
|
||||
* unless a name says degrees. Times are epoch milliseconds. Screen positions
|
||||
* are CSS pixels from the top left of the renderer's canvas.
|
||||
*/
|
||||
|
||||
/** Earth-centred, Earth-fixed position in metres (WGS84). */
|
||||
export interface Ecef {
|
||||
x: number;
|
||||
y: number;
|
||||
z: number;
|
||||
}
|
||||
|
||||
/** A direction or offset in metres; the frame is stated where it is used. */
|
||||
export interface Vec3 {
|
||||
x: number;
|
||||
y: number;
|
||||
z: number;
|
||||
}
|
||||
|
||||
/** Geodetic position: degrees, and metres above the WGS84 ellipsoid. */
|
||||
export interface LonLatH {
|
||||
lon: number;
|
||||
lat: number;
|
||||
height?: number;
|
||||
}
|
||||
|
||||
/** Geodetic position without a height. */
|
||||
export interface LonLat {
|
||||
lon: number;
|
||||
lat: number;
|
||||
}
|
||||
|
||||
/** Either position form. A value with `lon` and `lat` is geodetic. */
|
||||
export type Position = Ecef | LonLatH;
|
||||
|
||||
/** CSS pixels from the canvas's top left. */
|
||||
export interface ScreenXY {
|
||||
x: number;
|
||||
y: number;
|
||||
}
|
||||
|
||||
/** A screen rectangle in CSS pixels. */
|
||||
export interface ScreenRect {
|
||||
x: number;
|
||||
y: number;
|
||||
width: number;
|
||||
height: number;
|
||||
}
|
||||
|
||||
/** A geodetic rectangle in degrees. */
|
||||
export interface GeoRect {
|
||||
west: number;
|
||||
south: number;
|
||||
east: number;
|
||||
north: number;
|
||||
}
|
||||
|
||||
/** A ray in ECEF metres; `direction` is a unit vector. */
|
||||
export interface Ray {
|
||||
origin: Ecef;
|
||||
direction: Vec3;
|
||||
}
|
||||
|
||||
/** A bounding sphere. */
|
||||
export interface Sphere {
|
||||
center: Ecef;
|
||||
radius: number;
|
||||
}
|
||||
|
||||
export interface HeadingPitchRoll {
|
||||
heading: number;
|
||||
pitch: number;
|
||||
roll: number;
|
||||
}
|
||||
|
||||
export interface HeadingPitchRange {
|
||||
heading: number;
|
||||
pitch: number;
|
||||
range: number;
|
||||
}
|
||||
|
||||
/** A quaternion `(x, y, z, w)`, unit length. */
|
||||
export interface Quaternion {
|
||||
x: number;
|
||||
y: number;
|
||||
z: number;
|
||||
w: number;
|
||||
}
|
||||
|
||||
/** A CSS colour string, or linear `[r, g, b, a]` in 0..1 (`a` defaults to 1). */
|
||||
export type Color = string | readonly [number, number, number, number?];
|
||||
|
||||
/**
|
||||
* A distance curve: `nearValue` at `near` metres from the eye, `farValue`
|
||||
* at `far`, linear in between and clamped outside.
|
||||
*/
|
||||
export interface NearFar {
|
||||
near: number;
|
||||
nearValue: number;
|
||||
far: number;
|
||||
farValue: number;
|
||||
}
|
||||
|
||||
/**
|
||||
* Unsubscribes. Calling it twice is harmless.
|
||||
*
|
||||
* Every `on(...)` in the contract keeps these rules: listeners run in the
|
||||
* order they subscribed; one removed while an event is being delivered does
|
||||
* not run for it if it has not yet; one added during delivery first runs for
|
||||
* the next event; a listener that throws is reported (`Renderer` `error`,
|
||||
* or the platform's `reportError` when nothing listens for errors) and the
|
||||
* others, and the frame, still run.
|
||||
*/
|
||||
export type Off = () => void;
|
||||
|
||||
/** Gives back a hold. Calling it twice is harmless. */
|
||||
export type Release = () => void;
|
||||
|
||||
/** A handle on something the renderer draws. */
|
||||
export interface Handle {
|
||||
show: boolean;
|
||||
dispose(): void;
|
||||
}
|
||||
|
||||
/** Opaque data the application attaches to a drawn item and gets back on a pick. */
|
||||
export type Meta = unknown;
|
||||
|
||||
/**
|
||||
* Optional features. A renderer lists the ones it has in
|
||||
* `Renderer.capabilities`. A member's documentation names the capability
|
||||
* it depends on, in backticks, first:
|
||||
* - on an optional member (`?`), the member exists only with the capability;
|
||||
* - on a required member, the member always exists, and without the
|
||||
* capability it answers null, an empty list or a status saying so (a
|
||||
* query asked for depth on a renderer without `pickPosition` returns null).
|
||||
* Options guarded by a capability are ignored without it. Quality settings
|
||||
* are not capabilities: `QualityPort.knobs()` lists the ones a renderer has.
|
||||
*/
|
||||
export type Capability =
|
||||
/** Google photorealistic 3D tiles as the base. */
|
||||
| 'photoreal'
|
||||
/** A vector basemap (`BaseSpec.vector`), with its own labels. */
|
||||
| 'vectorBase'
|
||||
/** Heights from the finest data available, not only what is drawn. */
|
||||
| 'finestHeights'
|
||||
/** Height terrain under the globe. */
|
||||
| 'terrain'
|
||||
/** Atmosphere scattering applied to drawn models. */
|
||||
| 'modelAtmosphere'
|
||||
/** Imagery draped onto 3D tiles as well as the globe. */
|
||||
| 'imageryOnTiles'
|
||||
/** A screen-split comparison between imagery layers. */
|
||||
| 'splitSwipe'
|
||||
/** Timed imagery frames with hidden prefetch. */
|
||||
| 'imageryFrames'
|
||||
/** Wind-relief and similar shading of the globe surface. */
|
||||
| 'surfaceShading'
|
||||
/** A screen-space sector modulation pass (a sweeping sonar band). */
|
||||
| 'screenModulation'
|
||||
/** GPU frame timing through timer queries. */
|
||||
| 'gpuTiming'
|
||||
/** Depth picks against tiles and terrain. */
|
||||
| 'pickPosition'
|
||||
/** Height sampling against tiles and terrain. */
|
||||
| 'sampleHeight'
|
||||
/** Ray casts against tiles and terrain. */
|
||||
| 'rayCast'
|
||||
/** Columnar draw-set updates with dirty ranges. */
|
||||
| 'columns'
|
||||
/** Icon motion segments evaluated on the renderer's clock. */
|
||||
| 'motionSegments'
|
||||
/** glTF models. */
|
||||
| 'models'
|
||||
/** Image, video and canvas planes. */
|
||||
| 'quads'
|
||||
/** Custom meshes in a local east-north-up frame. */
|
||||
| 'meshes'
|
||||
/** Wind streamlines, scalar rasters and raised raster shells. */
|
||||
| 'fields'
|
||||
/** Stars and orbit rings in an inertial frame. */
|
||||
| 'celestial'
|
||||
/** Agents moving along polylines (traffic flow). */
|
||||
| 'agents'
|
||||
/** Screen-space clustering of icons. */
|
||||
| 'cluster'
|
||||
/** Post-processing styles. */
|
||||
| 'styles'
|
||||
/** A bloom pass. */
|
||||
| 'bloom'
|
||||
/** A sharpen pass. */
|
||||
| 'sharpen'
|
||||
/** Following with an automatically chosen frame (orbit or north-up). */
|
||||
| 'followAutodetect'
|
||||
/** A built-in quality benchmark. */
|
||||
| 'benchmark';
|
||||
Reference in new issue
Block a user