A renderer plugin may supply applicationHooks(renderer) for what only its
renderer has (map engine, own credits, stale commands, QA handles). What every
renderer should do moves onto the contract: controls.keepEarthFramed (behind
the keepEarthFramed capability), query.occlusionTest (behind occlusionTest),
and panel drawing, which keepPanelRendering now does through resize and
frame.renderNow through the contract. renderNow throws when the frame fails to draw.
The Cesium port installs its zoom-out guard through keepEarthFramed (a setView
no longer cancels its turn) and answers occlusionTest with the scene's probe;
the stub answers it with a horizon test.
Drops from the contract, the stub, the Cesium renderer and the
conformance suite: agent paths, renderer-propagated orbits and celestial
draws (orbits stay drawn as icons and inertial lines), scalar raster
fields, lodGroup, volume classification, icon eye offsets, the dash gap
colour, box shapes, courseBlendMs (courseGlide covers easing), relief
surface shading, globe clouds and water, sky atmosphere tuning, heightmap
and quantized-mesh terrain, WMTS and ArcGIS imagery, the batched cached
height read, the quality benchmark and the animated-style and overlay
pixel-ratio knobs. Capabilities clouds, water, celestial, agents, orbits
and benchmark go with them.
The lodGroup check becomes a displayRange check across two sets, the
height-query check uses an extruded polygon in place of a box, the shape
scenes draw extruded blocks where they drew boxes, and the fields scene
draws a raster shell. The shape references are recorded again.
A new capability, surfaceIdentity, adds globe.surfaceVersion(): a number
that changes whenever what surface heights answer against changes (base,
terrain or photoreal swapped, the globe shown or hidden) and never on
camera moves or tile loads, so the app can key cached heights by it. The
settle kind 'surface' says whether that surface has loaded what is in
view: the terrain while the globe is shown, otherwise the drawn tiles,
false with neither; a renderer without the capability answers it as base.
The Cesium globe port reads both off the scene, so a base changed around
the port counts too; its versions come from one counter shared by every
port. The stub bumps on real base, terrain, photoreal and visibility
changes. A conformance check and a globe port test cover them.
The query contract now says picks answer against the scene as drawn before
effects, and that a drillPick limit bounds the work as well as the answer:
the renderer stops at `limit` hits and looks through at most
max(limit, 16) things under the pointer. The Cesium query port passes that
depth to Cesium's drill (a pick looking under something unpickable stays
unbounded), a click's drill caches one pass per depth, and the stub counts
unpickable items toward the depth.
CameraPose says fovy and aspectRatio describe the nearest centred
perspective frustum, the exact projection being in matrices().
A changed listener's own threshold is now the capability
cameraChangeThreshold; without it every listener fires at 0.5. The Cesium
and stub cameras have it, measured per listener without touching Cesium's
shared percentageChanged.
Conformance: draw.drillPick checks limit 0, never the surface, nothing over
the bare globe, an unpickable cover, nearest first and a bounded prefix;
query.pickBeforeStyles picks an icon under a mirroring style; the threshold
trace is skipped without its capability.
The camera port gains an optional followFrame() (capability followFrame):
the frame the eye is placed in now, as a column-major 4x4 matrix to ECEF.
Once a follow has framed the camera it is the follow's own frame
(east-north-up, or the orbit frame an autodetect follow chose), under
lookAt the target's east-north-up frame, otherwise the identity. setView
places a world pose and keeps that frame. The Cesium port reads it from
camera.transform, only when the capability is on; the stub from its own
eye frame. A conformance check covers the world, lookAt and enu-follow
frames, the offset in it, and setView keeping it.
src/ui/shareFollow.js now reads the pose, the frame and the follow offset
through the camera and frame ports: a shared offset is re-expressed in the
follow's own frame as before, satellites included, and the eye is placed
with setView at exact heading, pitch and roll, so a near-vertical view
keeps its roll. placeFollowEye returns false on a camera that cannot say
its frame. offsetFromHeadingPitchRange moves to src/geo/frames.js, shared
with the stub.
The globe port could show or hide the globe surface but not say whether it
is shown. It now has an optional isGlobeVisible(), gated by a new
globeVisibility capability, in the Cesium adapter, the stub and a
conformance check. A Cesium scene without a globe does not offer it, so
callers keep their own default for an unknown surface.
The OSM overlays, the CCTV ground regime and the submarine cable drape now
read the getter instead of the scene's globe. cableClassificationTypeForScene
takes the viewer rather than its scene.
- 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.
- lodGroup links items across sets as one thing at different detail;
picks name the member shown and report the group. displayRange is
half-open.
- An orbits capability: the renderer propagates two-line elements with
SGP4 on the set's motion clock. The stub propagates with satellite.js.
- Height queries see draw sets only with includeInHeightQueries (was
excludeFromHeightQueries); HeightSample.source gains 'set'.
- courseGlide is a capability; courseBlendMs eases the course on every
renderer.
- Arc segments climb at climbMps; a negative minDtS stays for the
aircraft warm-up.
- The star catalogue is optional, a hidden column row keeps its motion,
and draw.clampState() reports the drape fallback.
Checks cover the climb and warm-up, lodGroup ranges, orbits against SGP4
(with and without motionSegments), hidden rows resuming, and sets not
answering height queries by default.
The renderer contract is what the application asks of a 3D renderer. It is nine ports
(frame, globe, draw, camera, query, input, effects, credits, quality) plus
the renderer itself, one strict .d.ts per port in src/render/contract/.
PORTS lists every member at run time, and a TypeScript-compiler test fails
when the list and the types disagree on one member. An optional member
exists only with its capability; a required one answers null or empty
without it. Nothing in the application uses the contract yet.
The stub renderer (src/render/stub/) implements every port in memory and
draws nothing. Its camera is a port of the default camera's maths: views,
lookAt, flights with their height arc and easing, rectangle framing on the
geodesic midpoint, the view rectangle with its horizon and pole cases,
changed thresholds, follows, and flights that finish inside the call.
The conformance suite (src/render/conformance/) runs 59 checks against
a renderer through the contract alone, in Node or in a browser page. The
camera checks compare traces recorded from Cesium's own Camera, headless on
a virtual clock (scripts/record-camera-goldens.mjs), to 1 mm, 1e-9 and
1e-3 px. The other checks cover listener rules on every subscription, the
frame loop, draw sets, picks, motion clocks, heights, leases, imagery,
styles, credits and quality knobs. The stub passes all of them but the
model check, which needs a glTF asset.
Reference scenes draw one scene per primitive family, a city and a
calibration path from orbit to the street, from contract calls only and
with no network. /dev/conformance/ draws them on the Cesium scene renderer
(src/render/cesium/sceneRenderer.js), records references through a
dev-server-only, loopback-only endpoint, and compares captures with
pixelmatch's antialias detection plus a solid-pixel count. Measured on
Cesium: every MSAA setting passes, and a dropped 4 px point, a dropped 2 px
line and a 1 px shift of the view fail. visual.js states the limits.
The package exports ./render/contract, ./render/stub and
./render/conformance. Documented in docs/RENDERER-CONTRACT.md,
docs/CODE-BOUNDARIES.md and docs/CURRENT-STATE.md.