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:
Sameh Khamis committed 2026-11-05 13:26:14 -08:00
1 parent a7aeeb558a
commit 3dc79515bb
7 files changed
+360 -52

No files matched your search

+6
View File
@@ -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. */
+95 -18
View File
@@ -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. */
+6 -2
View File
@@ -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',
+6 -2
View File
@@ -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. */