feat(globe): instanced movers on both engines

engine.movers.createSet({ id, kind: sprite|point|model, capacity, order,
depthTest, sprite|point|model, pickable }) → a MoverSet: set(index,
fields) stores an instance (position, screen rotation, orientation, rgba,
scale, atlas cell, show, pickId) in flat arrays, commit() uploads the
changed range once and requests one render, positionsView() reads the
positions, destroy() removes it; movers.list() for QA. The options, the
store and the registry are engine-neutral (src/globe/movers.js); the fake
engine keeps them for layer tests.

- Cesium: one primitive per set in an engine-owned PrimitiveCollection
  added with the first set, in `order`: sprites a BillboardCollection
  (one image per atlas cell, NearFarScalar, disableDepthTestDistance),
  points a PointPrimitiveCollection, models a Model per instance.
- Navara: a public MeshDesc per set. Sprites and points are one
  InstancedMesh of a quad, faced to the screen and sized in CSS pixels in
  the vertex shader from uniforms (the pick pass draws the same
  footprint), atlas uv, rotation, colour and scale per instance, drawn in
  the transparent pass unlit; offsets from an origin that follows the
  camera past max(1 km, 10 % of its height). Models: the glTF once, one
  InstancedMesh per mesh, minimumPixelSize/maximumScale on the CPU per
  drawn frame, colorBlend in the shader. Pickable sets register a
  PickableInstancedMeshWrapper; pickIds.js maps batch ids back to
  instances (used by Task 4).
- The contract suite draws three 24 px sprites on both engines: centred
  within 2 px of worldToWindow, hidden by show:false, recoloured, gone on
  destroy, and no frames added once the commit has drawn.
- qa-engine-bench --scenario=movers: 10 000 synthetic aircraft
  (src/bench/syntheticFlights.js, moved from the Navara spike with its
  test), every instance moved and committed every frame. p95 Navara
  (look=minimal) / Cesium: global 5.2/7.0 ms, city 5.6/9.9, orbit 6.0/7.4
  (0.74, 0.57, 0.81; gate 1.1). Cesium is measured without its 60 fps cap.

Main chunk 2,860,302 bytes (+9,706, +0.34 %: the Cesium movers).
This commit is contained in:
German Khokhlov committed 2026-10-16 17:15:24 +04:00
1 parent 4623c8b616
commit 0109097440
24 files changed
+2735 -3

No files matched your search

+55
View File
@@ -243,6 +243,59 @@
* not); Navara on the view's preUpdate, which it emits on every turn of
* its loop.
*
* @typedef {object} MoverSetOptions
* A set of moving objects drawn as one batch (src/globe/movers.js checks
* and defaults these):
* @property {string} id Unique among the engine's live sets.
* @property {'sprite'|'point'|'model'} kind
* @property {number} capacity The most instances the set holds.
* @property {number} [order] Draw order among sets (higher draws later, on
* top); 0 by default.
* @property {'normal'|'always'|{ disableWithinM: number }} [depthTest]
* 'always' draws over the scene; { disableWithinM } skips the depth test for
* instances closer to the camera than that (Cesium's
* disableDepthTestDistance). 'normal' by default.
* @property {{ atlas: { url?: string, canvas?: object, cells: Object<string, number[]> },
* sizePx: number, scaleByDistance?: number[] }} [sprite] An image atlas
* whose cells are [u0, v0, u1, v1] in 0..1 (v down from the image top);
* each sprite is a square of sizePx CSS px times its scale, times the
* NearFarScalar [nearM, nearScale, farM, farScale] when given.
* @property {{ sizePx: number, outlinePx?: number, scaleByDistance?: number[] }} [point]
* A filled disc of sizePx CSS px diameter with a dark outline.
* @property {{ url: string, minimumPixelSize?: number, maximumScale?: number,
* colorBlend?: { mode: 'mix'|'replace', amount: number }, unlit?: boolean }} [model]
* A glTF drawn per instance in metres, at least minimumPixelSize px.
* @property {boolean} [pickable]
*
* @typedef {object} MoverFields
* One instance; omitted fields keep their value (defaults: white, scale 1,
* rotation 0, the first atlas cell, shown, identity orientation).
* @property {Cartesian3} [position]
* @property {number} [rotation] Sprites: screen angle in radians,
* counter-clockwise from screen up (Cesium's Billboard.rotation).
* @property {{ x: number, y: number, z: number, w: number }} [orientation]
* Models: the model frame's rotation into Earth-fixed axes.
* @property {number[]} [color] rgba in 0..1; multiplies the sprite's texels.
* @property {number} [scale]
* @property {string} [cell] An atlas cell key.
* @property {boolean} [show]
* @property {string|number} [pickId] What a pick of this instance returns.
*
* @typedef {object} MoverSet
* @property {(index: number, fields: MoverFields) => void} set Stored only;
* drawn after commit().
* @property {(count: number) => void} setCount Instances [0, count) draw.
* @property {() => number} count
* @property {() => void} commit Uploads what changed (one buffer write) and
* requests a render; nothing else draws a frame.
* @property {() => Float64Array} positionsView x, y, z of the drawn
* instances (a view on the set's own array; read-only).
* @property {() => void} destroy
*
* @typedef {object} GlobeMovers
* @property {(options: MoverSetOptions) => MoverSet} createSet
* @property {() => { id: string, kind: string, count: number, capacity: number }[]} list
*
* @typedef {object} GlobeEngine
* @property {'cesium'|'navara'} kind
* @property {{ container: object, canvas: object, size: () => { width: number, height: number } }} host
@@ -263,6 +316,7 @@
* @property {{ addStatic: (html: string, options?: { onScreen?: boolean }) => () => void }} credits
* @property {GlobeMaps} maps
* @property {GlobeClock} clock
* @property {GlobeMovers} movers
* @property {() => void} destroy
* @property {() => boolean} isDestroyed True once destroy() has run.
*/
@@ -442,6 +496,7 @@ const SHAPE = {
input: { on: isFunction, setCameraInputs: isFunction },
credits: { addStatic: isFunction },
clock: { now: isFunction, frameTime: isFunction, ticked: isEngineEvent },
movers: { createSet: isFunction, list: isFunction },
maps: {
setBaseImagery: isFunction,
setTerrain: isFunction,