An undraped solid line (straight or geodesic, without a depth-fail colour,
not revealed, at least half a pixel wide) is drawn by the set's polyline
collection at once, as before. Once the set's lines have not changed for
30 drawn frames, every such line is built into static batches beside the
collection: a primitive of polyline geometries for opaque colours and one
for translucent ones, each line coloured and shown by its own instance
attributes under the pick id it had. A batch builds hidden, off the main
thread, and swaps in for the batch before it and the collection's
polylines once it is ready, each line showing as its item then asks. A
polyline collection works out every line's material every frame; a batch
costs nothing until it changes. The data centre stems (4,362 lines) cost
about 16 ms a frame in the collection and about 0.01 ms settled.
A batched line changes its show, colour and meta in place. One that moves,
or whose colour moves it between the opaque and translucent passes, leaves
its batch, hidden there, for the collection until the set settles again;
when a batch exists and fewer than 64 lines are left in the collection,
they settle after 300 frames, as rebuilding the batch for a few lines
costs more than drawing them. A line in the collection that moves or
changes colour drops a batch still building; a show change does not. A
colour-only change of such a line is now made in place in the collection
too, where it rebuilt the set. A batch whose build fails is reported once
and its lines stay in the collection. Glow, dash, arrow, flow, pattern,
revealed and depth-fail lines draw as they did.
The shared conformance suite checks solid lines left unchanged for many
frames still pick, hide, recolour and move in place.
A set of unclamped points drawn by one point collection now takes new
points and removals where it is, instead of building the collection
anew; its pick ids and horizon cull follow, and the draw port's version
changes only when pick ids do. A point moved or restyled in place sets
only the members of its look whose values changed, and writes its
position without allocating, so a set moved every frame makes nothing
new. A draped line drawn by a material of its own takes a colour-only
change on its material, and unmoved lines sent again compare their
positions without flattening them. The shared conformance suite checks
points joining and leaving a set one by one.
A rectangle shape gains an optional rotation: radians counter-clockwise,
turning it about its centre in longitude and latitude, as a KML ground
overlay turns; an image fill turns with it. A renderer that predates it
draws the rectangle unturned. The Cesium draw port passes it as the
rectangle's rotation and texture rotation, and now drapes image fills on
clamped shapes, each on a ground primitive of its own that owns its
material, where it refused them before. Hidden image fills are not built
until they show. The stub picks draped rectangles, turned and across the
antimeridian, and a conformance check picks a quarter-turned overlay on
both renderers. The KML importer still draws its overlays itself.
A line item gains an optional depthFailDash ({ length, pattern16? }): the
parts behind the surface are dashed in depthFailColor, as a dash style
dashes a line. Without a depthFailColor, and on draped lines, it is
ignored; a renderer that predates it draws those parts solid. The Cesium
draw port gives the depth-fail appearance a PolylineDash material, and a
change of dash is a new look. The Draw tool's rubber band uses
{ length: 16 }, the dash its old entity asked for (that entity, a dynamic
polyline, never drew its depth-fail material, so the parts behind the
surface were hidden before the tool moved onto the draw port).
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 renderer contract gains an optional event on model draw sets,
`on('loadFailed', (id, message) => ...)`, beside `ready`: a model's url
failed to load, once per failed load. The item stays in the set drawing
what it drew before; removing it and adding it again tries at once. A
renderer that cannot tell a failure may never fire it.
The Cesium draw port fires it once Cesium is done with the frame it
raised the error in, and not for a load that was superseded or whose item
went. The stub fails urls under `stub-fail:`, telling each load once. A
conformance check (`draw.models.loadFailed`) runs on both, with a model
url the dev server does not serve for Cesium.
The flights and military layers use it in place of rewriting every
unloaded model every 5 s. A fleet model whose load failed is removed and
added again 5 s later. The tracked model gets back its per-selection
budget: a failed load is let go and tried again 1.5 s later, and after
three failures the contact stays 2D until another is selected, as
before the models moved onto the draw port. A good load retires the
budget, and a model that loads after all is kept.
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.
A models set kept one primitive per build and loaded every model again on
any change. Each item now keeps its own Cesium model: an update re-poses it
(position and orientation), and changes its scale, pixel floor, maximum
scale, shading, tint, colour blend, environment map, display range and show
where it is. Only a new url loads again, and the model it draws stays until
the new one is ready. `ready` fires once per load. Each frame before the
scene draws, the set caps models at their maxPixelSize, scales and fades
them by distance, and hides them past the horizon in a horizonCull set. A
load that fails is let go after its update, and stays a failure for
whenSettled until its item changes.
The stub fires `ready` only for a new item or a new url, and draws models
into readPixels as tinted squares. Its harness has a model asset now, so the
model checks run on it. New checks: a model moves, turns and restyles
without loading again, and only a new url loads it; its tint and colour
blend change live.
A draped solid line with segment colours or shows draws each segment as a
ground polyline instance of its own in the set's ground batch, under a
pick id that reads as the line's, so changing its colours or which
segments show writes their attributes without a rebuild; a change made
while the ground still builds is written as it swaps in. Undraped or
non-solid segmented lines are refused, and a segmented line of no length
builds no ground. The shared conformance suite changes a segmented
draped line every frame.
The Cesium draw port now drapes glow and dash lines as well as solid and
flow ones, each with its own ground primitive.
revealFraction is the fraction of the line's length, measured along the
line. Both renderers cut there: Cesium discards fragments past the cut in
the line's material, so the hidden part neither draws nor picks; the stub
cuts the line before drawing and picking.
A draped line whose positions change is rebuilt the same frame, on a ground
primitive of its own, once terrain heights are loaded; until then it is
rebuilt as before. A clamped dot whose look is unchanged is moved in place.
The stub now picks lines. A new shared conformance check, draw.lines.drape,
covers draped glow and dash lines, the reveal cut, a draped line growing
every frame, and a clamped point moving every frame.
Lines take the flow style, draped or not: the route annotation's flowing
dashes as a material whose clock the port runs each frame, asking for
frames while a shown set shows flow lines. Undraped lines with a
depth-fail colour draw it where the surface hides them, and one that moves
is built anew in place under the same pick id, so a line updated every
frame neither rebuilds its set nor blinks. A draped style the port cannot
drape is refused before the set changes. The shared conformance suite
draws both kinds and moves a depth-fail line frame by frame.
Unclamped points that move on an upsert now move on the point they have,
keeping their pick id and horizon cull, instead of rebuilding the set.
Points and clamped dots honour displayRange as icons do. The shared
conformance suite checks moved points and point display ranges, and the
lodGroup check now passes on the Cesium renderer too.
render/motion/iconMotion evaluates a draw item's motion segment and course
glide at a time on the set's motion clock, without a renderer: where the
item is drawn, the course it is drawn with, and when its motion ends. The app
can now read a moving icon back (to follow it, label it, judge a pick or
its horizon) the way the renderer draws it.
The stub renderer evaluates its segments with it, in place of its own copy,
and so now steps a lerp with no span 1 ms after t0, as the Cesium renderer
does. The Cesium GPU icon sets read the course shown before a write, a
blend's target and when rows stop moving through it, from copies of what
they wrote, and write each glide with the offset it computes, so an exact
half turn goes the way the app reads it.
norm360/norm180 and Position-to-ECEF move to geo for both to share.
Conformance gains a check that icons are drawn where the evaluator puts
them.
Cesium icon sets now draw an item's scaleByDistance, fadeByDistance and
displayRange, as point sets already draw their curves, and drop them again
when a restyle in place leaves them out. An empty display range shows the
icon nowhere; a curve whose far end is not past its near one is left out
rather than refused mid-update. Cesium eases between a curve's ends rather
than interpolating linearly, as it always has for points.
The reference renderer now scales an item's pick size by its distance curve
and leaves out items faded or scaled to nothing, and the draw.icons.distance
conformance check covers all three fields.
An icon set's upsert, set, remove and an atlas registered again now restyle,
move, re-image, add and remove billboards in the collection the set already
has, so markers no longer blink as every image reloads on each change. A
changed image swaps on its own billboard; the old one keeps drawing until
the new one has loaded.
The set is still built anew where changing it in place would not draw the
same: when new icons would land ahead of drawn ones, when a set reorders
its items, when a key's generated image comes as a new canvas, when the
set is emptied, and when its collection would hold many more images than
it draws (a collection keeps every image it has loaded).
Adds the draw.icons.update conformance check.
A page's frames come at the display's rate: at 240 Hz the 20 frames the
check allowed pass inside the 100 ms flight, and it failed on 'the flight
ended'. It now waits up to a second by the harness clock, still capped at
600 frames, as the moveEnd check does.
The shared Cesium ports gain readPixels and releaseUnused, on both the
conformance renderer and the application's.
readPixels reads the drawn frame off the canvas at once, cropped in CSS
pixels and scaled from the canvas's CSS size, through one reused 2D canvas.
A canvas with no size reads blank.
releaseUnused trims every 3D tileset's cache, and after the next drawn frame
frees the globe tiles that frame did not draw. Cesium trims the globe's
cache only while tiles load, so a settled view would otherwise free nothing;
the trim goes through internals.js. The reader canvas is dropped too.
Two new checks, renderer.readPixels and renderer.releaseUnused, run on
Cesium and the stub.
The shared Cesium ports gain draw.atlas, draw.clampState and
draw.on('clampState'), on both the conformance renderer and the
application's. An icon names an image by atlas slot; it draws once its atlas
holds the slot, and registering an atlas again rebuilds the icon sets that
read from it. A generated image with a key is one texture however many icons
draw it.
clampState is draped unless a shown 3D tileset is in the scene: the port
draws clamped items where it is given them and drapes nothing onto tiles yet,
so over tiles it says overlay. A change is told after the drawn frame that
shows it, never on subscribing.
A new draw.atlas check registers an atlas after its icons and picks them;
it and draw.clampState now run on Cesium.
camera.controls now maps the contract's CameraControls onto the scene's
ScreenSpaceCameraController: the enable flags, zoom distances, zoom
factor, coast as Cesium inertia (decay seconds, 0 for no coast), the
collision switch, the tilt limit as the upper end of pitchRange, and the
zoom bindings by name. suspend and enabled use the scene's shared input
holds, so they count with the input port's and the dispatcher's.
A follow's zoom hold now composes with the settings: minDistance and
coast.zoom read and set what the follow gives back, a higher floor takes
effect at once, and a follow never lengthens a shorter zoom coast.
The ctrl+wheel binding check reuses the controls' binding helpers, and
the controls checks run in the Cesium conformance set, the settings one
in Node as well.
The effects port puts each style the app defines on its own post-process
stage, takes the scene's bloom stage and adds a sharpen stage, with the
mappings the application uses today. An animated style holds frames and
advances its time uniform while it draws. A replaced style keeps drawing
until its intensity is 0, so the app can crossfade; the contract, the stub
and a new conformance check say so. The conformance renderer has the
port; the application renderer does not yet.
The shared Cesium ports gain credits, on both the conformance renderer and
the application's. list() reports what Cesium owes as plain data: its logo,
its static credits and the last drawn frame's imagery, terrain and tile
credits, read from the credit display through internals.js, with the
credits the app adds listed as given where the display shows them. addStatic
shows a credit through Cesium's display, as markup built from the plain
data with every value escaped and only web links kept, so attribution stays
on screen. change fires when the app adds or removes a credit, and after a
drawn frame whose Cesium credits differ from the last one's.
src/render/creditMarkup.js reads markup credits as plain data. The credits
listener check moves out of renderer.listenerRules into its own check, so a
renderer without every port can run it; it and the credits check now run on
Cesium.
The Cesium camera port gains move, look, rotateAround and zoom, and the
browser conformance run now checks them, the lookAt-frame commands, the
changed thresholds and moveEnd (timed by the clock, not a frame count).
Orbit, the Bhote Koshi focus and cinematic, the launch zoom anchor and
replay chase, the camera verbs' motion tick and roll levelling, and
voice zoom write through the port.
The embed view, the celestial-ring focus, the ground-guard lift, the
Bhote Koshi approach and orbit, launch selection and replay flights, and
the cockpit's view and takeover now drive the renderer's camera port.
The contract gains a sineInOut easing, pinned by a conformance trace.
A viewer with no renderer bound, such as one a caller of a public
export brings, now gets a camera port too, as it already got an input
port: cameraOf builds one over the viewer's own Cesium camera and keeps
it for the viewer's life, until a renderer is bound. The Cesium adapter
provides the factory as it loads; code that reaches Cesium takes cameraOf
from the adapter so the factory comes with it, and findCamera answers
null where a missing camera is not an error (HUD, share link, world
focus, Recent Imagery's ZOOM IN). A test walks every package export and
fails one that can reach the bridge without loading the factory.
A destroyed viewer gets no camera and lets go of a built one, and the
application renderer stays bound until its viewer is destroyed.
flyToBounds takes an easing, as flyTo does: in the contract, the Cesium
port and the reference recorder, pinned by a new conformance trace.
The flights of radio, awareness, CCTV, submarine cables, cyclones, the
launch preview, installations, ALPR, street-level framing, recent
imagery, weather and world focus now go through the renderer's camera
port. Street-level framing cancels its own flight handle rather than
whatever flight is current. worldFocus.js no longer reaches Cesium and
leaves the allow-list.
Layer pose reads stay for each layer's own slice. The local GeoJSON
flight stays on Cesium: gods-eye-view/infrastructure is used with plain
Cesium viewers that have no renderer bound.
The frame port now does everything the contract asks of it on Cesium:
preUpdate says whether the tick draws (Cesium's own render test, read
live until the tick is over), holds are counted per reason, and suspend,
target fps, renderNow and diagnostics are real. Releasing the last hold
asks for one more frame.
whenSettled also waits until Cesium stops redrawing on its own. Each
request or worker task Cesium completes queues a redraw (a terrain
picker build after the camera moved, say), which no loading flag shows,
so it now waits for quiet frames and then a short stretch in which the
loop draws nothing by itself. It is bounded by its timeout, names a
stopped loop, and ends on destroy.
The app renderer still leaves out the members that steer the loop:
the render governor and the page's visibility handling own those
settings until they move onto the port.
The new frame.prediction check compares the preUpdate answer with what
each tick drew.
The Cesium renderer now has every QueryPort member: picks and drill
picks, depth and globe picks, rays, projection, occlusion, heights now
and streamed, clamping and ray casts. Capabilities come from what the
scene supports (depth textures for pickPosition, sampleHeight,
finestHeights and rayCast), in both the conformance and app renderers.
- Picks skip unpickable and hidden items, and report each item once. A
pick under an unpickable item stops at anything that hides the rest.
drillPick's limit counts after that filtering, so 0 gives none.
- Height queries and ray casts see through sets not drawn with
includeInHeightQueries, and through the sets a caller excludes, by
their items' pick ids. The list is built once per change to the sets.
- `tiles` samples and casts run with the globe hidden for the call;
`terrain` casts use the globe alone. A sample reports whether it came
from tiles, terrain, the ellipsoid or a set.
- A position clampToSurface cannot read is a miss, not a failed batch.
- Terrain on an ellipsoid is height 0. Before, sampling it threw, for
want of tile availability.
whenSettled also waits for icon images, and fails when one cannot load.
The conformance checks that pick or query settle first, because a
renderer answers from what it has loaded; the stub settles at once.
The Cesium renderer now passes 14 checks in the browser, and its
visual references are unchanged.
- 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.
- claimPointer takes a grab filter, asked on each down: a lease takes
only the presses it grabs, and wheel, pinch and every other press stay
with the camera and everyone else. Each event of a press goes where its
down went, per button, so a claim never takes a press under way.
- The app owns the styles: effects.defineStyle passes a GLSL (and optionally
WGSL) full-screen pass, with the shader interface written out.
- Credits are plain data ({ text, href, logoUrl, inline }) that the app
renders; CreateOptions.creditContainer goes.
- controls.coast { drag, zoom } in seconds replaces the inertia trio; the
stub's defaults are the default renderer's, converted.
- The frame order is the default renderer's own: a move made by follow or
in preUpdate reaches changed on the next frame.
- 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.