The renderer seam: clicks go to the newest tool, recession and display groups through the contract, drawing at parity with Cesium

- Clicks: when two tools want the globe's clicks, the newest takes them and the older is told and turns itself off; a click is decided when it arrives, and ambient selection fires only when no tool holds the pointer. The "map is busy" paths and their strings are removed.
- Recession: the limb fade is shared (src/render/recession.js) and reaches icon and model sets through SetSpec.recede; tuning applies on the next frame.
- Display panel groups are published through src/ui/displayGroups.js; the Weather group and src/viewWeather.js are removed.
- Draw port: a set whose icons only move is moved in place, and models that did not change are not restyled each frame, so moving fleets cost what they did when drawn directly; an untinted, fully opaque model is drawn without a colour.
- Conformance: input.lease.lost checks the new lease inside onLost and reports a throwing onLost; draw.sets.recede covers model sets.
- QA scripts read the renderer host instead of internals the seam replaced.
This commit is contained in:
Sameh Khamis committed 2026-11-15 17:03:09 -08:00
1 parent a0d299523d
commit 0ab31d4fb8
130 files changed
+5438 -1674

No files matched your search

+77 -2
View File
@@ -30,12 +30,15 @@ import type {
GeoRect,
HeadingPitchRange,
HeadingPitchRoll,
LonLat,
Off,
Position,
Release,
Sphere,
Vec3,
} from './common';
import type { PointerEv, PointerEventType } from './input';
import type { HeightOptions } from './query';
export interface CameraPose {
lon: number;
@@ -297,6 +300,7 @@ export interface CameraPort {
* reading is valid only for the tick it is read in. `setView` places a
* world pose and keeps this frame, so code can re-express an offset in
* the follow's own frame, whichever frame that is, and place the eye there.
* Read-only, handed again while it holds, as `matrices()` are.
*/
followFrame?(): Float64Array;
readonly controls: CameraControls;
@@ -313,7 +317,78 @@ export interface CameraPort {
* Column-major, right-handed: `view` takes ECEF to eye space (absolute,
* not eye-relative); `projection` takes eye space to clip space with depth
* in [-1, 1]. A renderer with an infinite far plane returns the
* infinite-far form, and `pose().far` is `Infinity`.
* infinite-far form, and `pose().far` is `Infinity`. Read-only: a
* renderer may hand the same arrays again while they hold, and hands new
* ones once they change (one kept from an earlier frame stays as it was).
*/
matrices(): { view: Float64Array; projection: Float64Array };
matrices(): {
readonly view: Float64Array;
readonly projection: Float64Array;
};
}
/** A camera controller's frame tick: the loop's clock and the scene time. */
export interface CameraTick {
/** The loop's clock, ms, on the `performance.now()` timeline. */
now: number;
/** Scene time, epoch ms. */
time: number;
}
/** The eye a camera controller writes, in ECEF; `fovy` vertical, radians. */
export interface ControllerEye {
position: Ecef;
direction: Ecef;
up: Ecef;
right: Ecef;
fovy: number;
}
/**
* The camera a renderer hands a camera controller: it reads and writes the
* eye exactly, says the canvas's CSS size, and lends the query, draw and
* frame ports' members the controller needs.
*/
export interface NativeCamera {
pose(): {
position: Ecef;
direction: Ecef;
up: Ecef;
near: number;
far: number;
};
setPose(eye: ControllerEye): void;
viewport(): { width: number; height: number };
sampleHeightNow?(point: LonLat, options?: HeightOptions): number | null;
pickPosition?(x: number, y: number): Ecef | null;
/** Where the draw port draws an item it moves itself. */
itemPosition?(
item: { set: string; id: string | number },
aheadMs?: number,
): Ecef | null;
requestRender?(reason: string): void;
}
/**
* A camera controller, as an application hands one to a renderer without a
* camera of its own (or in place of its own): given the native camera, the
* input port's pointer events and the page's keys, it makes the camera port.
* The renderer runs `frame.beforeUpdate` before its `preUpdate` listeners
* and `frame.afterUpdate` after them, each tick, drawn or not.
*/
export type CameraControllerFactory = (options: {
native: NativeCamera;
input?: {
on(type: PointerEventType, cb: (event: PointerEv) => void): Off;
};
report?: (error: unknown) => void;
keyTarget?: EventTarget;
thresholds?: boolean;
}) => {
port: CameraPort;
frame: {
beforeUpdate(tick: CameraTick): void;
afterUpdate(tick: CameraTick): void;
};
destroy(): void;
};
+6 -1
View File
@@ -121,7 +121,12 @@ export type Off = () => void;
/** Gives back a hold. Calling it twice is harmless. */
export type Release = () => void;
/** A handle on something the renderer draws. */
/**
* A handle on something the renderer draws. Once disposed, and once the
* renderer is destroyed, it does nothing: its methods neither draw nor
* throw, and a set or field asked for after destroy is such a handle.
* Disposing it again is harmless.
*/
export interface Handle {
show: boolean;
dispose(): void;
+44 -3
View File
@@ -55,6 +55,35 @@ export interface ClusterSpec {
icon?: (count: number) => ImageRef;
}
/**
* `recede`: a set's items shrink and fade toward the globe's limb, as
* `src/render/recession.js` (exported as `render/recession`) works it out,
* so the renderer draws exactly those factors. Nearer than `startLimbRatio` of
* the eye's distance to the limb an item is drawn as it is; from there it
* eases (smoothstep) to `scaleFloor` times its scale and `alphaFloor` haze
* at the limb and beyond. All of it eases back to nothing as the eye climbs
* from `globeViewBlendStartM` to `globeViewBlendEndM` above the ellipsoid.
* An item draws at its alpha times `max(combinedAlphaFloor, focus × haze)`,
* that floor holding even while nothing recedes. Icons shrink and fade;
* models only fade. Every parameter is optional, the defaults in brackets.
*/
export interface RecedeSpec {
/** Where receding starts, as a share of the limb's distance [0.5]. */
startLimbRatio?: number;
/** The scale an item reaches at the limb [0.45]; icons only. */
scaleFloor?: number;
/** The haze an item reaches at the limb [0.35]. */
alphaFloor?: number;
/** The least `focus × haze` draws with [0.2]. */
combinedAlphaFloor?: number;
/** Eye height above the ellipsoid where receding starts to ease off, metres [3,500,000]. */
globeViewBlendStartM?: number;
/** Eye height from which nothing recedes, metres [4,500,000]. */
globeViewBlendEndM?: number;
/** The radius of the sphere the limb is measured on, metres [6,378,137]. */
earthRadiusM?: number;
}
/** Options of a whole set; the mutable ones can change later through `setOptions`. */
export interface SetSpec {
/**
@@ -66,6 +95,11 @@ export interface SetSpec {
horizonCull?: boolean;
/** `cluster`: screen-space clustering (icons only; see `ClusterSpec`). */
cluster?: ClusterSpec | null;
/**
* Icons and models: the items recede toward the limb (`RecedeSpec`; `{}`
* for the defaults). Omitted or `null`: they do not. Changes live.
*/
recede?: RecedeSpec | 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
@@ -212,9 +246,10 @@ export interface IconItem extends Placed {
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. */
/**
* Emphasis for a focused item, 0..1, 1 = none: the alpha is multiplied by
* it (in a set that recedes, as `RecedeSpec` says).
*/
focus?: number;
}
@@ -409,6 +444,12 @@ export interface ModelItem extends Placed {
* would not hide what lies below it). Can change live.
*/
clip?: 'belowOrigin';
/**
* Emphasis for a focused model, 0..1, 1 = none: the tint's alpha is
* multiplied by it (in a set that recedes, as `RecedeSpec` says). Can
* change live.
*/
focus?: number;
}
/** A plane showing an image, a video or a canvas. */
+5 -1
View File
@@ -84,7 +84,11 @@ export interface FramePort {
* the animation frames the loop runs on.
*/
renderNow(options?: { ifDue?: boolean }): void;
/** Resolves after the next frame has been drawn and presented. */
/**
* Resolves after the next frame has been drawn and presented. Once the
* renderer is destroyed it rejects with a "renderer destroyed" error, and
* so does one still waiting when the renderer is destroyed.
*/
renderOnce(options?: { timeoutMs?: number }): Promise<void>;
/** Cap the loop's rate; 0 is the display's rate. */
setTargetFps(fps: number): void;
+11 -2
View File
@@ -93,7 +93,12 @@ export interface InputPort {
options?: { lease?: Lease | (() => Lease | null) },
): Off;
/**
* Take the pointer for a tool. A new claim ends the previous lease.
* Take the pointer for a tool. The newest claim takes over: it ends the
* previous lease, whose `onLost` is called once, after the new lease holds
* the pointer, so that tool turns itself off (its button, a half-drawn
* shape). A lease its holder releases, or that has already ended, is never
* told, and releasing an ended lease frees nothing. An `onLost` that throws
* is reported.
* `grab` decides each press from its `down` event, synchronously: true
* makes it the tool's, anything else leaves it. A `down` carries no pick,
* so `grab` decides from the position, button and modifiers (and the
@@ -103,7 +108,11 @@ export interface InputPort {
*/
claimPointer(
owner: string,
options?: { grab?: (down: PointerEv) => boolean },
options?: {
grab?: (down: PointerEv) => boolean;
/** Called once when a newer claim ends this lease. */
onLost?: () => void;
},
): Lease;
isPointerFree(): boolean;
/** Suspend user camera input until released. Holds are counted. */
+2 -1
View File
@@ -82,7 +82,8 @@ export interface QueryPort {
pickEllipsoid(x: number, y: number): Ecef | null;
/** Where a ray meets the globe surface (not tiles). */
pickGlobe(ray: Ray): Ecef | null;
pickRay(x: number, y: number): Ray;
/** Null while the canvas has no size (hidden, not laid out yet). */
pickRay(x: number, y: number): Ray | null;
/** Screen position, or null behind the eye (off-screen points still answer). */
project(position: Ecef): ScreenXY | null;
/**
+14 -6
View File
@@ -104,16 +104,16 @@ export interface CreateOptions {
worldDataToken?: string;
/** Initial multisampling; quality can change it later. */
msaa?: 0 | 2 | 4 | 8;
/** Keep the drawing buffer after presenting, for capture. */
preserveDrawingBuffer?: boolean;
/** Sky applied before the first frame, so nothing draws in the wrong sky. */
sky?: Partial<SkySettings>;
/** Scene time in epoch ms. The application passes its boot time. */
time?: number;
/**
* The clocks the renderer reads, for flights, inertia, tweens and
* `FrameTime.now`: `now` on the `performance.now()` timeline, `date` in
* epoch ms. Omitted: the browser's. Tests pass virtual ones.
* The clocks the renderer reads, for `FrameTime.now`, the camera's
* `moveEnd` wait, input, flights and tweens, and for inertia where it
* times that itself (Cesium's keeps Cesium's own timing): `now` on the
* `performance.now()` timeline, `date` in epoch ms. Omitted: the
* browser's. Tests pass virtual ones.
*/
clock?: { now(): number; date(): number };
/** Aborts creation; the renderer cleans up whatever it had built. */
@@ -149,7 +149,10 @@ export interface Renderer {
readonly effects: EffectsPort;
readonly credits: CreditsPort;
readonly quality: QualityPort;
/** The last presented frame as an encoded image. */
/**
* The last presented frame as an encoded image. Once the renderer is
* destroyed it rejects with a "renderer destroyed" error.
*/
capture(options?: CaptureOptions): Promise<Blob>;
/**
* The last presented frame's pixels, synchronously, for loops that render
@@ -175,5 +178,10 @@ export interface Renderer {
* a new renderer.
*/
on(event: 'contextLost' | 'contextRestored', cb: () => void): Off;
/**
* Lets go of everything. Afterwards handles do nothing (`Handle`), and
* `frame.renderOnce` and `capture` reject with a "renderer destroyed"
* error, as does a `renderOnce` still waiting.
*/
destroy(): void;
}