Renderer contract: decoded imagery, tiles the application hands over as finished images

A timed source of kind 'decoded' (capability imageryDecoded) names the slot a
time shows (slotAt), the slots to hold ahead (prefetch) and answers each tile
of a slot with an image, missing or defer. The Cesium renderer draws each held
slot as an imagery layer of its own, as it draws frames; the stub shows the
slot. The check globe.imagery.decoded covers it.
This commit is contained in:
Sameh Khamis committed 2026-11-18 18:37:23 -08:00
1 parent cd144ecad5
commit 4ee0aba82e
12 files changed
+432 -23

No files matched your search

+2
View File
@@ -165,6 +165,8 @@ export type Capability =
| 'splitSwipe'
/** Timed imagery frames with hidden prefetch. */
| 'imageryFrames'
/** Timed imagery the application hands over as finished tile images (`decoded`). */
| 'imageryDecoded'
/** Wind-relief and similar shading of the globe surface. */
| 'surfaceShading'
/** A version of what surface heights answer against (`globe.surfaceVersion`). */
+36 -2
View File
@@ -130,17 +130,51 @@ export interface TimedUrl {
url: string;
}
/**
* A tile of a `decoded` source at one slot: its finished image, `missing`
* (no tile there; draw the parent's), or `defer` (ask again on a later
* frame). The renderer owns the image once answered: it draws it as it is
* (its alpha too) and may close it once drawn.
*/
export type DecodedTile =
{ image: ImageBitmap } | { missing: true } | { defer: true };
/** What a `decoded` source is asked for: one tile at one slot. */
export interface DecodedTileRequest {
tile: TileRequest;
/** The slot, as `slotAt` or `prefetch` named it. */
slot: number;
/** Aborted once the renderer no longer wants the tile. */
signal: AbortSignal;
/** `shown`: the slot the clock shows; `prefetch`: one held ahead. */
urgency: 'shown' | 'prefetch';
}
/**
* 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.
*
* `decoded` (`imageryDecoded`): tiles the application makes itself and hands
* over as finished images. Its slots are times (epoch ms): `slotAt` names
* the slot a time shows (`null`: none, and nothing is drawn), `prefetch` the
* slots to hold ahead of it, nearest first. The renderer asks `tile` for the
* tiles each held slot draws, in the layer's tiling, and only draws what it
* is given. It shows the nearest slot only (`mode` is not read); the
* `prefetch` option caps how many of the source's slots it holds ahead.
*/
export type TimedSource =
| { kind: 'frames'; frames: TimedUrl[] }
| {
kind: 'video';
segments: Array<{ url: string; start: number; end: number }>;
}
| {
kind: 'decoded';
slotAt(time: number): number | null;
prefetch?(time: number): number[];
tile(request: DecodedTileRequest): Promise<DecodedTile>;
};
export interface ImageryLayer {
@@ -176,8 +210,8 @@ export interface ImageryLayer {
/** `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
* `imageryFrames`: the frame the layer's clock now shows (by its time;
* a `decoded` source's by its slot) has been drawn. Fires once each time the shown frame changes, never
* for frames only prefetched.
*/
on(event: 'frameReady', cb: (time: number) => void): Off;
+1
View File
@@ -23,6 +23,7 @@ export const CAPABILITIES = Object.freeze([
'imageryOnTiles',
'splitSwipe',
'imageryFrames',
'imageryDecoded',
'surfaceShading',
'surfaceIdentity',
'imageHooks',