Files
gods-eye-view/src/render/contract/globe.d.ts
T
Sameh Khamis 1f307e0735 Keyless terrain reaches the renderer as quantized-mesh terrain
The contract's TerrainSpec gains quantizedMesh terrain: Cesium's tile
format in the folder at its url, heights above the ellipsoid. Without an
ion key the globe-port map engine asks for Re:Earth's keyless terrain as
it, where it asked for the ellipsoid, so the renderer
draws the same ground; without the terrain capability keeps the
ellipsoid. Cesium's globe port draws it through CesiumTerrainProvider with
the keyless terrain's retry policy.
2026-11-11 09:20:33 -08:00

284 lines
9.5 KiB
TypeScript

/**
* The base world: photorealistic tiles or a globe with terrain and imagery,
* the sky, and what drapes onto them.
*/
import type { Credit } from './credits';
import type { GeoRect, Off } from './common';
export interface PhotorealSpec {
provider: 'google';
key?: string;
/** Renews a session token; called again when the token expires. */
token?: () => Promise<string>;
/**
* Fall back to the renderer's copy of the same tiles when Google refuses
* (for the default renderer, one served from Cesium ion).
*/
fallback?: boolean;
}
export interface PhotorealStatus {
/** Which route is drawing, or `'none'` when photoreal is off or failed. */
route: 'google' | 'fallback' | 'none';
error?: { code: string; message: string };
}
/**
* Heights everywhere in the contract are physical (metres above the
* ellipsoid, unexaggerated): absolute positions, `HeightSample.height`,
* `clampToSurface`. Only drawing follows the exaggerated surface:
* `clampGround` and `relativeGround` items sit on the ground as drawn.
*/
export type TerrainSpec = (
| { kind: 'ellipsoid' }
/**
* The renderer's global terrain, through `CreateOptions.worldDataToken`
* (for the default renderer, Cesium World Terrain).
*/
| { kind: 'world'; requestVertexNormals?: boolean }
/**
* Quantized-mesh terrain (Cesium's tile format) in the folder `url`,
* holding `layer.json` and its tiles; heights above the ellipsoid.
*/
| { kind: 'quantizedMesh'; url: string; requestVertexNormals?: boolean }
) & {
/** Vertical exaggeration of the drawn terrain; default 1. */
exaggeration?: number;
};
export type TilingScheme = 'webMercator' | 'geographic';
/** One tile request, as an admission hook sees it. */
export interface TileRequest {
x: number;
y: number;
level: number;
}
/**
* What a tile fetch answered: the bytes to decode, `missing` (no tile
* there; draw the parent's), or `defer` (ask again on a later frame).
*/
export type TileFetch =
| { bytes: ArrayBuffer; contentType?: string }
| { missing: true }
| { defer: true };
export interface ImagerySpec {
/**
* `world`: the renderer's global imagery through
* `CreateOptions.worldDataToken` (for the default renderer, Cesium ion's
* world imagery), in `worldStyle`. `canvas`: `imageHooks`.
*/
kind: 'xyz' | 'world' | 'single-image' | 'canvas';
/** `world`: aerial (the default), or aerial with labels. */
worldStyle?: 'aerial' | 'aerialLabels';
/** URL or URL template (`{x}`, `{y}`, `{z}`, `{s}`, `{time}`). */
url?: string;
/** `'canvas'` (`imageHooks`): draws one tile. */
drawTile?: (tile: TileRequest, canvas: HTMLCanvasElement) => void;
subdomains?: string[];
tiling?: TilingScheme;
rectangle?: GeoRect;
minLevel?: number;
maxLevel?: number;
tileSize?: number;
credit?: Credit;
/** Requests in flight at once for this layer. */
maxConcurrentRequests?: number;
/** HTTP statuses retried rather than treated as missing. */
retryStatuses?: number[];
/**
* Fetches a tile in place of the renderer, with the URL it would fetch.
* The renderer calls it, before its own decoding (in a worker, say).
*/
fetchTile?: (request: {
tile: TileRequest;
url: string;
signal: AbortSignal;
}) => Promise<TileFetch>;
/** `imageHooks`: changes a tile's decoded image before it is drawn. */
tileTransform?: (
tile: TileRequest,
image: ImageBitmap,
) => ImageBitmap | Promise<ImageBitmap>;
/**
* `imageHooks`: decides each tile request on the main thread: call
* `issue()` to fetch it, or return `undefined` to defer it and be asked
* again on a later frame. `fetchTile`'s `defer` does the same anywhere.
* With both, `admit` decides first and an issued request goes through
* `fetchTile`; each defers on its own.
*/
admit?: (
tile: TileRequest,
issue: () => Promise<unknown> | undefined,
) => Promise<unknown> | undefined;
/** Draw order among imagery layers; higher draws on top. */
zOrder?: number;
}
export interface TimedUrl {
/** Epoch ms the frame shows. */
time: number;
url: string;
}
/**
* A timed source: frames as URLs (one template per time), or video tiles
* in segments, each a template whose tiles are videos spanning `start` to
* `end` (epoch ms), a time within shown by its offset into the segment's
* videos. Outside every segment, the nearest segment end is shown.
*/
export type TimedSource =
| { kind: 'frames'; frames: TimedUrl[] }
| {
kind: 'video';
segments: Array<{ url: string; start: number; end: number }>;
};
export interface ImageryLayer {
alpha: number;
show: boolean;
/** Which side of the split this layer shows on. */
split: 'none' | 'left' | 'right';
/**
* What it drapes onto: the globe's surface (terrain or the ellipsoid),
* objects (3D tiles and models; `imageryOnTiles`), or all of them. The
* default `all` drapes on whichever is drawn, so under photoreal it is
* on the tiles. Without `imageryOnTiles`, `objects` drapes on nothing and
* `all` on the surface. So nothing drapes while the globe is hidden and
* either photoreal's route is `none` or there is no `imageryOnTiles`:
* The application reads that from what it set, with no event for it.
*/
drapeOn: 'surface' | 'objects' | 'all';
/** Shaded by the sun like the surface (the default), or drawn unlit. */
lit: boolean;
/**
* `imageryFrames`: a timed source, prefetched hidden. `clock: 'scene'`
* (the default) shows the frame for the frame port's scene time;
* `'own'` shows the one `setFrameTime` names.
*/
setFrames?(
source: TimedSource,
options?: {
mode?: 'nearest' | 'blend';
prefetch?: number;
clock?: 'scene' | 'own';
},
): void;
/** `imageryFrames`: which time to show, on the `own` clock. */
setFrameTime?(ms: number): void;
/**
* `imageryFrames`: the frame the layer's clock now shows (by its time)
* has been drawn. Fires once each time the shown frame changes, never
* for frames only prefetched.
*/
on(event: 'frameReady', cb: (time: number) => void): Off;
on(
event: 'tileError',
cb: (error: { tile: TileRequest; status?: number }) => void,
): Off;
raise(): void;
lower(): void;
remove(): void;
}
export interface BaseSpec {
photoreal?: PhotorealSpec | null;
/** `vectorBase`: a vector basemap from a style document. */
vector?: { styleUrl: string } | null;
terrain?: TerrainSpec | null;
imagery?: ImagerySpec[];
credit?: Credit;
}
export interface BaseStatus {
photoreal: PhotorealStatus;
imagery: ImageryLayer[];
settled: boolean;
}
/**
* The sky. A renderer whose sun, moon or fog are not separate from its
* atmosphere follows `atmosphere` for them and reports them as it draws them.
*/
export interface SkySettings {
atmosphere: boolean;
stars: boolean;
/** Milky Way brightness, 0..1. */
milkyWay: number;
sun: boolean;
moon: boolean;
/** Distance fog, separate from atmosphere on models. */
fog: boolean;
/** Sun lighting of the globe and models. */
lighting: boolean;
}
/**
* View-lit shading of the drawn terrain's own relief (the ellipsoid's
* curvature where terrain has no normals); darkens only, at most
* `strength` opacity.
*/
export type SurfaceShading = { kind: 'hillshade'; strength: number };
export interface LoadProgress {
tilesPending: number;
imageryPending: number;
terrainPending: number;
}
/**
* `surface`: what `against: 'surface'` heights answer from has loaded what
* is in view: the terrain while the globe is shown, otherwise the drawn
* tiles; false when neither is drawn. A renderer that predates it answers
* as `base`.
*/
export type SettleKind = 'base' | 'tiles' | 'terrain' | 'imagery' | 'surface';
export interface GlobePort {
/** Switch the whole base at once; resolves when the new base has settled. */
setBase(base: BaseSpec): Promise<BaseStatus>;
/** `photoreal`: on, off or a new token route. */
setPhotoreal(spec: PhotorealSpec | null): Promise<PhotorealStatus>;
setTerrain(spec: TerrainSpec | null): Promise<void>;
/** Show or hide the globe surface (hidden under photoreal). */
setGlobeVisible(visible: boolean): void;
/**
* `globeVisibility`: whether the globe surface is shown now, as
* `setGlobeVisible` or whoever last set it left it. For code that only holds
* the scene and must know whether the surface it drapes on or samples is
* drawn.
*/
isGlobeVisible?(): boolean;
/**
* `surfaceIdentity`: a number that changes whenever what heights answer
* against changes (base, terrain or photoreal route swapped, the globe
* shown or hidden) and never otherwise (not on camera moves or tile
* loads). The application keys cached surface heights by it.
*/
surfaceVersion?(): number;
/** `surfaceShading`. */
setSurfaceShading?(shading: SurfaceShading | null): void;
readonly imagery: {
/**
* Without `imageHooks`, a spec with `tileTransform`, `admit` or kind
* `canvas` throws, rather than drawing tiles the hooks were meant to
* change.
*/
add(spec: ImagerySpec, index?: number): ImageryLayer;
list(): ImageryLayer[];
/** `splitSwipe`: split position, a fraction of the canvas's CSS width. */
getSplit?(): number;
/** `splitSwipe`: move the split to `x01` of the canvas's CSS width. */
setSplit?(x01: number): void;
};
readonly sky: {
get(): SkySettings;
set(settings: Partial<SkySettings>): void;
};
/** Whether that part of the base has finished loading what is in view. */
isSettled(kind: SettleKind): boolean;
on(event: 'progress', cb: (progress: LoadProgress) => void): Off;
}