mirror of
https://github.com/bilawalsidhu/gods-eye-view.git
synced 2026-11-16 08:12:24 +00:00
A new capability, surfaceIdentity, adds globe.surfaceVersion(): a number that changes whenever what surface heights answer against changes (base, terrain or photoreal swapped, the globe shown or hidden) and never on camera moves or tile loads, so the app can key cached heights by it. The settle kind 'surface' says whether that surface has loaded what is in view: the terrain while the globe is shown, otherwise the drawn tiles, false with neither; a renderer without the capability answers it as base. The Cesium globe port reads both off the scene, so a base changed around the port counts too; its versions come from one counter shared by every port. The stub bumps on real base, terrain, photoreal and visibility changes. A conformance check and a globe port test cover them.
219 lines
6.4 KiB
TypeScript
219 lines
6.4 KiB
TypeScript
/**
|
|
* 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 version of what surface heights answer against (`globe.surfaceVersion`). */
|
|
| 'surfaceIdentity'
|
|
/** Volumetric clouds (`globe.setClouds`). */
|
|
| 'clouds'
|
|
/** A water surface on the oceans (`globe.setWater`). */
|
|
| 'water'
|
|
/** Main-thread tile hooks: `tileTransform`, `admit` and `canvas` imagery. */
|
|
| 'imageHooks'
|
|
/** 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'
|
|
/** Satellites propagated by the renderer from their elements (`draw.orbits`). */
|
|
| 'orbits'
|
|
/** Rate-limited course easing (`IconItem.courseGlide`). */
|
|
| 'courseGlide'
|
|
/** 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'
|
|
/** Reading back whether the globe surface is shown (`globe.isGlobeVisible`). */
|
|
| 'globeVisibility'
|
|
/** Reading the frame the eye is placed in (`camera.followFrame`). */
|
|
| 'followFrame'
|
|
/** A `threshold` per `changed` listener (`camera.on`). */
|
|
| 'cameraChangeThreshold'
|
|
/** A built-in quality benchmark. */
|
|
| 'benchmark';
|