/** * Things to draw: batched sets of items keyed by string id. * * The application owns every record; a set is only what it pushed. Each item may carry * an opaque `meta` that comes back on a pick (`Hit.meta`). There is no world * text here: every label goes through the application's screen-space label overlay, * which only needs `query.project`/`projectMany` and `query.isOccluded`. * * Moving icons follow a motion segment the renderer evaluates on its own * clock (`motionSegments`), so the application writes a row only when its motion or * style changes, not every frame. */ import type { Color, Ecef, GeoRect, Handle, Meta, NearFar, Off, Position, Quaternion, ScreenXY, Vec3, } from './common'; /** How an item's height is read. */ export type HeightMode = 'absolute' | 'clampGround' | 'relativeGround'; /** What `clampGround` / `relativeGround` clamp to. */ export type ClampTarget = 'terrain' | 'tiles' | 'both'; /** * `cluster`: screen-space clustering of a set's icons. Which icons cluster * is `clusterScreenPoints` (`src/geo/screenCluster.js`) over the set's shown * icons in front of the eye and above the horizon, in the set's order, each * boxed at its drawn size (its larger side, times its `scale`), with * `pixelRange` and `minimumSize`, and the last pass's clusters kept as it * keeps them: so the renderer forms exactly these clusters. A cluster draws one * icon at the cluster's position (the mean of its members') in place of its * members, which are not drawn: its image is `icon(count)` when given, else * a default badge showing the count, drawn at its seed's size. A pick on a * cluster answers one `Hit` per member, in the cluster's order (seed * first), each with that member's own `set`, `id` and `meta` and the * cluster's `position`: so `pick` gives the seed and `drillPick` every * member. Clusters are recomputed in the frames drawn after the camera * moves or the set changes, never on a timer. */ export interface ClusterSpec { /** Screen distance under which icons merge, CSS pixels. */ pixelRange: number; /** Fewest icons that form a cluster. */ minimumSize: number; /** Draws a cluster's icon from its member count. */ icon?: (count: number) => ImageRef; } /** Options of a whole set; the mutable ones can change later through `setOptions`. */ export interface SetSpec { /** * Unique among the renderer's live sets (making a second set with a live * id throws; a disposed set's id can be used again); returned as `Hit.set`. */ id: string; /** Hide items beyond the ellipsoid's horizon, for sets drawn without depth test. */ horizonCull?: boolean; /** `cluster`: screen-space clustering (icons only; see `ClusterSpec`). */ cluster?: ClusterSpec | null; /** * How the set's items blend with what is drawn. Omitted: opaque parts * opaque with depth writes, items with alpha under 1 alpha-blended without * depth writes. `opaque`: every item opaque, its alpha ignored (taken as * 1), with depth writes (icons and points keep every part they draw, * unblended). `translucent`: every item alpha-blended without depth * writes, even at alpha 1. `additive`: each item's colour times its alpha * added to what is drawn, without depth writes and still depth-tested. * For every kind of set; `setOptions({blend})` takes effect from the next * frame, and models do not load again. */ blend?: 'opaque' | 'translucent' | 'additive'; /** * Among sets that do not depth-test against each other (items drawn with * `disableDepthTest`), a higher one draws over a lower one whatever order * they were made in; equal ones keep that order. `pick` and `drillPick` * name them topmost first. Default 0. */ drawOrder?: number; /** `false`: the set never takes part in picks. */ pickable?: boolean; /** * Height queries (`query.sampleHeight` and the rest) see this set as * ground. Off by default: queries answer from tiles and terrain alone. */ includeInHeightQueries?: boolean; /** What clamped items clamp to. */ clampTo?: ClampTarget; /** * `motionSegments`: the clock motion segments are evaluated on. * `live` (the default) is wall time minus `delayMs`, as a live feed is * drawn a little behind real time; `scene` is the frame port's scene time. */ motionClock?: { kind: 'live'; delayMs?: number } | { kind: 'scene' }; show?: boolean; } /** Common to items placed at one position. */ export interface Placed { id: string; pos: Position; height?: HeightMode; meta?: Meta; show?: boolean; /** `false`: this item never takes part in picks. */ pickable?: boolean; scaleByDistance?: NearFar; fadeByDistance?: NearFar; /** Shown only at eye distances in `[near, far)`, metres. */ displayRange?: [near: number, far: number]; /** Draw over depth within this many metres of the eye (`Infinity`: always). */ disableDepthTest?: number; } /** An image an icon draws: a URL, a slot in a shared atlas, or generated. */ export type ImageRef = | string | { atlas: string; slot: string } | { svg: string } | { blob: Blob } | { canvas: HTMLCanvasElement | OffscreenCanvas; key: string }; /** * How an icon moves between updates, on its set's `motionClock`. Times are * epoch ms. Sending an item a new segment replaces its old one, whatever the * times (an earlier or equal `t0` included). * - hold: stays at `pos`. * - lerp: straight in space from `from` (at `t0`) to `to` (at `t1`), holding * at both ends; the course runs from `course0Deg` by `courseSlopeDeg` * across the segment. * - arc: a constant-rate turn in the plane tangent to the ellipsoid at `fix` * (its east and north axes), from `fix` at `t0`, at `speedMps` along * `trackDeg` turning at `turnRateDps` (under 1e-4 rad/s is straight), and * climbing along the fix's up axis at `climbMps` (default 0). The elapsed * time is clamped to `[minDtS, maxDtS]`; a negative `minDtS` runs the same * path backward before `t0` (a warm-up), `maxDtS` is how long it coasts. * The drawn course turns onto a new one at once; an item with `courseGlide` * eases at its rate instead, on a renderer with the `courseGlide` capability. */ export type MotionSegment = | { kind: 'hold'; courseDeg?: number } | { kind: 'lerp'; from: Ecef; to: Ecef; t0: number; t1: number; course0Deg?: number; courseSlopeDeg?: number; } | { kind: 'arc'; fix: Ecef; t0: number; minDtS: number; maxDtS: number; speedMps: number; trackDeg: number; turnRateDps: number; /** Metres per second along the fix's up axis. */ climbMps?: number; }; export interface CourseGlide { fromCourseDeg: number; t0: number; /** Degrees per second; 0 or less holds `fromCourseDeg`. */ rateDps: number; } export interface IconItem extends Placed { image: ImageRef; /** Drawn size in CSS pixels. */ size: [width: number, height: number]; color?: Color; alpha?: number; scale?: number; /** `motionSegments`: motion on the renderer's clock. */ motion?: MotionSegment; /** `courseGlide`: ease the drawn course at a rate, from `fromCourseDeg`. */ courseGlide?: CourseGlide; /** Degrees clockwise from north. */ course?: number; /** * `screen`: upright on screen, rotated by `rotation`; * `course`: rotated on screen along `course` (or the motion's course); * `axis`: rotated about `alignedAxis`. */ rotationMode?: 'screen' | 'course' | 'axis'; /** Radians counter-clockwise on screen, for `rotationMode: 'screen'`. */ rotation?: number; /** ECEF axis for `rotationMode: 'axis'`. */ alignedAxis?: Vec3; pixelOffset?: ScreenXY; anchor?: 'center' | 'bottom' | 'top'; /** Swap to `near` when drawn larger than `switchPx`. */ imageLod?: { near: ImageRef; switchPx: number }; /** A larger invisible pick target, CSS pixels. */ pickProxy?: { size: [width: number, height: number] }; /** Fade and shrink toward the globe's limb. */ recede?: boolean; /** Emphasis factor for a focused item, 1 = none. */ focus?: number; } export interface PointItem extends Placed { pixelSize: number; color: Color; outlineColor?: Color; outlineWidth?: number; } export type LineStyle = | { kind: 'solid'; color: Color; /** * An edge `widthPx` wide in all, half of it on each side, inside the * line's width (a line 8 px wide with an outline of 4 has 2 px of * outline each side and 4 px of `color` between), drawn in the same * pass as the line: a translucent edge does not darken where it meets * the line. Its colour changes in place. */ outline?: { color: Color; widthPx: number }; } | { kind: 'glow'; color: Color; power: number; taper?: number } | { kind: 'dash'; color: Color; length: number; pattern16?: number } | { kind: 'arrow'; color: Color } | { kind: 'pattern'; image: ImageRef; repeat: number } | { kind: 'flow'; color: Color; repeat: number; duty: number; speed: number }; export interface LineItem { id: string; /** ECEF positions, or packed `x, y, z` triples. */ positions: Ecef[] | Float64Array; widthPx: number; /** * `3d`: straight in space; `geodesic`: along the ellipsoid; `draped`: on * the surface. Where the renderer cannot drape at all, it draws `draped` lines * and clamped shapes as in `overlay`, and `clampState()` says `overlay`. */ mode: '3d' | 'geodesic' | 'draped'; clampTo?: ClampTarget; style: LineStyle; /** * How the parts behind the surface draw, solid or dashed; omitted or * `null` hides them. Ignored on draped lines, which are never behind it. */ depthFail?: | { kind: 'solid'; color: Color } | Extract | null; /** Per-segment colours; changing them does not rebuild the line. */ segmentColors?: Color[]; segmentShow?: boolean[]; /** Draw only the first fraction of the line, 0..1. */ revealFraction?: number; /** Positions are in a frame rotating with the sky (orbits). */ frame?: 'fixed' | 'inertial'; meta?: Meta; show?: boolean; pickable?: boolean; } /** * A shape's fill: a colour, or an image stretched over the shape's extent * (`repeat` times across and up). A canvas image sent again with a new * `key` is new content. */ export type Fill = Color | { image: ImageRef; repeat?: [number, number] }; /** * Declarative animation the renderer runs (no per-frame callbacks): the * fill's and outline's alpha swings between `from` and `to` and back every * `periodMs`, forever. */ export interface Pulse { property: 'alpha'; from: number; to: number; periodMs: number; } export type ShapeGeometry = | { kind: 'polygon'; rings: Position[][]; perPositionHeight?: boolean } | { kind: 'ellipse'; center: Position; /** Metres. */ semiMajor: number; semiMinor: number; /** Radians counter-clockwise from north to the semi-major axis. */ rotation?: number; } /** * `height`: metres above the ellipsoid, for a rectangle not clamped. * `rotation`: radians counter-clockwise, turning the rectangle about its * centre in longitude and latitude (as a KML ground overlay turns); an * image fill turns with it. */ | { kind: 'rectangle'; rect: GeoRect; height?: number; rotation?: number } | { kind: 'wall'; positions: Position[]; minimumHeights?: number[]; maximumHeights?: number[]; }; export interface ShapeItem { id: string; geometry: ShapeGeometry; fill?: Fill | null; outline?: Color | null; outlineWidth?: number; /** Draw the outline only. Clamped outlines are drawn as draped lines. */ outlineOnly?: boolean; /** Height of the extruded face, metres above the ellipsoid (not above the shape). */ extrudeHeight?: number; height?: 'absolute' | 'clampGround'; clampTo?: ClampTarget; /** * Shaded by the renderer's fixed light (true) or flat colour (false). * Omitted: lit for extruded shapes, flat otherwise. A renderer * may draw clamped shapes, which drape on the surface, flat whatever it * says. */ lit?: boolean; animate?: Pulse; meta?: Meta; show?: boolean; pickable?: boolean; } /** * A glTF model. The renderer draws one this way: glTF is Y-up and is * turned to Z-up before `orientation` applies; `minPixelSize` is measured at * the model's bounding-sphere distance from the eye; `colorBlend` mixes the * tint into the shaded colour and never changes the model's alpha. */ export interface ModelItem extends Placed { url: string; orientation: { heading: number; pitch: number; roll: number }; scale?: number; minPixelSize?: number; maxPixelSize?: number; maxScale?: number; /** Can change live. */ shading?: 'pbr' | 'unlit' | 'thermal'; tint?: Color; colorBlend?: { mode: 'highlight' | 'replace' | 'mix'; amount?: number }; environmentMap?: boolean; } /** A plane showing an image, a video or a canvas. */ export interface QuadItem { id: string; center: Position; orientation: Quaternion; /** Metres. */ size: [width: number, height: number]; source: | { image: ImageRef } | { video: HTMLVideoElement } | { canvas: HTMLCanvasElement | OffscreenCanvas }; alpha?: number; outline?: { color: Color; widthPx: number } | null; meta?: Meta; show?: boolean; pickable?: boolean; } /** Custom geometry in a local east-north-up frame at `origin`. */ export interface MeshItem { id: string; origin: Ecef; /** Packed `east, north, up` metres. */ positions: Float32Array; indices: Uint16Array | Uint32Array; color: Color; /** Unlit, with back faces drawn. */ flat?: boolean; meta?: Meta; show?: boolean; pickable?: boolean; } export type FieldSpec = | { kind: 'windStreamlines'; id: string; /** Row-major `u` and `v` in m/s on a `width × height` grid over `rectangle`. */ u: Float32Array; v: Float32Array; width: number; height: number; rectangle: GeoRect; pathBudget: number; steps: number; style: { color: Color; widthPx: number; speedFactor?: number }; /** Draw height, metres; omitted drapes on the surface. */ heightM?: number; /** 0..1, changeable without a rebuild (fade by height). */ alpha?: number; /** Draw the paths still, dimmed. */ paused?: boolean; } | { /** * A raster on a sphere raised above the ground. Shells draw in * ascending `heightM`, alpha-blended and unlit; they are never picked * and never in height queries. Changing `liftM` or `alpha` never * rebuilds. An `update` that changes `image`, `rectangle` or `detail` * keeps drawing what it drew until the new content can be drawn whole. */ kind: 'rasterShell'; id: string; image: ImageRef; rectangle: GeoRect; heightM: number; liftM?: number; /** * A sharper image drawn in place of `image` inside its own * `rectangle`, never blended with it; null or omitted: none. */ detail?: { image: ImageRef; rectangle: GeoRect } | null; alpha?: number; }; export interface FieldHandle extends Handle { update(patch: Partial): void; /** * `fields`: what the spec or the last `update` asked for is drawn now. * Once per such change; never while hidden. Changes made before one is * drawn (the spec and updates, or updates while hidden) are told once, * when the latest is drawn. */ on(event: 'drawn', cb: () => void): Off; } /** * Columnar update for large sets (`columns`). Column `i` of each array is * row `ids[i]`. `dirty` limits the upload to these index runs. */ export interface Columns { ids: readonly string[]; /** Packed ECEF `x, y, z`. */ positions?: Float64Array; /** Degrees clockwise from north. */ courses?: Float32Array; /** * 0 hides a row. A hidden row keeps its motion state (where it is on its * segment, its eased course), so showing it again resumes, not restarts. */ shown?: Uint8Array; scales?: Float32Array; alphas?: Float32Array; /** Packed `r, g, b, a`, 0..255. */ colors?: Uint8Array; meta?: readonly Meta[]; dirty?: ReadonlyArray<{ start: number; end: number }>; } export interface DrawSet { readonly id: string; /** Replace every item. */ set(items: T[]): void; /** Add or replace items by id. */ upsert(items: T[]): void; remove(ids: string[]): void; clear(): void; /** `columns`. */ setColumns?(columns: Columns): void; /** Change the mutable set options. */ setOptions(options: Partial>): void; /** Items in the set. */ size(): number; show: boolean; /** `models`: a model has loaded and is posed. */ on(event: 'ready', cb: (id: string) => void): Off; /** * `models`: a model's url failed to load (`message` says why), once per * failed load. The item stays in the set, drawing what it drew before (a * new item draws nothing); a renderer may try the url again when the item * is next updated. Removing the item and adding it again tries at once. * Optional: where the renderer cannot tell a failure it may never fire it, so * a fallback must not wait on it. */ on(event: 'loadFailed', cb: (id: string, message: string) => void): Off; dispose(): void; } export interface DrawPort { icons(spec: SetSpec): DrawSet; points(spec: SetSpec): DrawSet; lines(spec: SetSpec): DrawSet; shapes(spec: SetSpec): DrawSet; /** `models`. */ models?(spec: SetSpec): DrawSet; /** `quads`. */ quads?(spec: SetSpec): DrawSet; /** `meshes`. */ meshes?(spec: SetSpec): DrawSet; /** `fields`. */ field?(spec: FieldSpec): FieldHandle; /** * Whether clamped items (`clampTo: 'tiles' | 'both'`, draped lines and * shapes) are draped onto the 3D tiles now (`draped`), or drawn over them * and hidden past the ellipsoid's horizon (`overlay`), the fallback a * renderer uses where it cannot drape. Without tiles in the base it is * `draped`: clamping to terrain or the ellipsoid always drapes, on a * renderer that can drape at all (one that cannot is always `overlay`). */ clampState(): 'draped' | 'overlay'; /** Fires when `clampState()` changes (not on subscribing). */ on(event: 'clampState', cb: (state: 'draped' | 'overlay') => void): Off; /** Register an atlas of images icons refer to by slot. */ atlas(id: string, images: Record): void; }