mirror of
https://github.com/bilawalsidhu/gods-eye-view.git
synced 2026-11-16 08:12:24 +00:00
Settle imagery, world data and sky capabilities in the renderer contract
- setFrames takes a timed source (URL frames, or video tiles in segments) on the scene clock by default or its own; frameReady fires once each time the shown frame is drawn. - drapeOn is 'surface' | 'objects' | 'all' plus lit; imagery.host() and onHostChange go, and the drape rule the app derives is written out. - ImagerySpec.fetchTile answers bytes, missing or defer on every renderer; tileTransform, admit and canvas imagery need imageHooks, and add() throws for them without it. - Generic names for the default renderer's world data: worldDataToken, the photoreal fallback route, and world terrain and imagery. - clouds and water capabilities, with globe.setClouds and setWater.
This commit is contained in:
1 parent
a7aeeb558a
commit
3dc79515bb
7 files changed
+360
-52
No files matched your search
Vendored
+6
@@ -160,6 +160,12 @@ export type Capability =
|
||||
| 'imageryFrames'
|
||||
/** Wind-relief and similar shading of the globe surface. */
|
||||
| 'surfaceShading'
|
||||
/** 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. */
|
||||
|
||||
Vendored
+95
-18
@@ -10,13 +10,16 @@ export interface PhotorealSpec {
|
||||
key?: string;
|
||||
/** Renews a session token; called again when the token expires. */
|
||||
token?: () => Promise<string>;
|
||||
/** Fall back to an ion-hosted copy when Google refuses. */
|
||||
ionFallback?: boolean;
|
||||
/**
|
||||
* 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' | 'ion' | 'none';
|
||||
route: 'google' | 'fallback' | 'none';
|
||||
error?: { code: string; message: string };
|
||||
}
|
||||
|
||||
@@ -29,7 +32,11 @@ export interface PhotorealStatus {
|
||||
export type TerrainSpec = (
|
||||
| { kind: 'ellipsoid' }
|
||||
| { kind: 'quantizedMesh'; url: string; requestVertexNormals?: boolean }
|
||||
| { kind: 'ion'; assetId: number }
|
||||
/**
|
||||
* The renderer's global terrain, through `CreateOptions.worldDataToken`
|
||||
* (for the default renderer, Cesium World Terrain).
|
||||
*/
|
||||
| { kind: 'world'; requestVertexNormals?: boolean }
|
||||
/** A DEM image pyramid (`{z}/{x}/{y}`), heights encoded in RGB. */
|
||||
| {
|
||||
kind: 'heightmap';
|
||||
@@ -53,11 +60,27 @@ export interface TileRequest {
|
||||
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 {
|
||||
kind: 'xyz' | 'wmts' | 'arcgis' | 'bing' | 'single-image' | 'canvas';
|
||||
/**
|
||||
* `world`: the renderer's global imagery through
|
||||
* `CreateOptions.worldDataToken` (for the default renderer, Cesium ion's
|
||||
* world imagery), in `worldStyle`. `canvas`: `imageHooks`.
|
||||
*/
|
||||
kind: 'xyz' | 'wmts' | 'arcgis' | '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'`: draws one tile. */
|
||||
/** `'canvas'` (`imageHooks`): draws one tile. */
|
||||
drawTile?: (tile: TileRequest, canvas: HTMLCanvasElement) => void;
|
||||
/** WMTS: layer, style, tile matrix set and format. */
|
||||
wmts?: {
|
||||
@@ -77,14 +100,26 @@ export interface ImagerySpec {
|
||||
maxConcurrentRequests?: number;
|
||||
/** HTTP statuses retried rather than treated as missing. */
|
||||
retryStatuses?: number[];
|
||||
/** Changes a tile's image before it is drawn. */
|
||||
/**
|
||||
* 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>;
|
||||
/**
|
||||
* Decides each tile request: call `issue()` to fetch it, or return
|
||||
* `undefined` to defer it and be asked again on a later frame.
|
||||
* `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,
|
||||
@@ -100,20 +135,56 @@ export interface TimedUrl {
|
||||
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. `'active'` follows whichever base is showing. */
|
||||
drapeOn: 'globe' | 'tiles' | 'both' | 'active';
|
||||
/** `imageryFrames`: a timed sequence, prefetched hidden. */
|
||||
/**
|
||||
* 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?(
|
||||
frames: TimedUrl[],
|
||||
options?: { mode?: 'nearest' | 'blend'; prefetch?: number },
|
||||
source: TimedSource,
|
||||
options?: {
|
||||
mode?: 'nearest' | 'blend';
|
||||
prefetch?: number;
|
||||
clock?: 'scene' | 'own';
|
||||
},
|
||||
): void;
|
||||
/** `imageryFrames`: which time to show. */
|
||||
/** `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',
|
||||
@@ -189,12 +260,18 @@ export interface GlobePort {
|
||||
setGlobeVisible(visible: boolean): void;
|
||||
/** `surfaceShading`. */
|
||||
setSurfaceShading?(shading: SurfaceShading | null): void;
|
||||
/** `clouds`: the renderer's volumetric clouds, or none. */
|
||||
setClouds?(clouds: { coverage: number } | null): void;
|
||||
/** `water`: the renderer's own water surface on the oceans, on or off. */
|
||||
setWater?(enabled: boolean): 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[];
|
||||
/** What imagery drapes onto now. */
|
||||
host(): 'globe' | 'tiles' | 'both';
|
||||
onHostChange(cb: (host: 'globe' | 'tiles' | 'both') => void): Off;
|
||||
/** `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. */
|
||||
|
||||
@@ -23,6 +23,9 @@ export const CAPABILITIES = Object.freeze([
|
||||
'splitSwipe',
|
||||
'imageryFrames',
|
||||
'surfaceShading',
|
||||
'clouds',
|
||||
'water',
|
||||
'imageHooks',
|
||||
'screenModulation',
|
||||
'gpuTiming',
|
||||
'pickPosition',
|
||||
@@ -138,8 +141,6 @@ export const PORTS = deepFreeze({
|
||||
'imagery',
|
||||
'imagery.add',
|
||||
'imagery.list',
|
||||
'imagery.host',
|
||||
'imagery.onHostChange',
|
||||
'sky',
|
||||
'sky.get',
|
||||
'sky.set',
|
||||
@@ -147,6 +148,8 @@ export const PORTS = deepFreeze({
|
||||
'on',
|
||||
),
|
||||
['setSurfaceShading', 'surfaceShading'],
|
||||
['setClouds', 'clouds'],
|
||||
['setWater', 'water'],
|
||||
['imagery.getSplit', 'splitSwipe'],
|
||||
['imagery.setSplit', 'splitSwipe'],
|
||||
]),
|
||||
@@ -293,6 +296,7 @@ export const PORTS = deepFreeze({
|
||||
'show',
|
||||
'split',
|
||||
'drapeOn',
|
||||
'lit',
|
||||
'on',
|
||||
'raise',
|
||||
'lower',
|
||||
|
||||
Vendored
+6
-2
@@ -34,8 +34,12 @@ export interface CreateOptions {
|
||||
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;
|
||||
/**
|
||||
* 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;
|
||||
/** Keep the drawing buffer after presenting, for capture. */
|
||||
|
||||
Reference in new issue
Block a user