Stack sprite layers by draw order, flights on top

Each sprite layer's icon or dot set is now made at a draw order taken
from SPRITE_LAYER_ORDER through the renderer's per-set drawOrder:
flights over military, vessels, directions, transit, bikeshare, FIRMS
and CCTV, whichever layer was turned on first. Picks name the topmost
first. The orders are negative, so selection highlights, route
endpoints, the tracked plane and every other set at the default order
still draw over all sprite layers, as they did before.

The raise-to-top restorer, the sprite registry and the primitive-name
lookups are gone, which takes spriteOrder.js off the viewer-access list.
Before, the restorer raised the layers to the bottom of the scene in the
order they were enabled, so flights usually ended up under the others.
This commit is contained in:
Sameh Khamis committed 2026-11-09 14:32:50 -08:00
1 parent 657ef94f77
commit c073064507
40 files changed
+271 -562

No files matched your search

+5 -4
View File
@@ -259,17 +259,18 @@ export function createAircraftIcons({
/**
* Create the draw set for one layer lifetime, drawn over depth and culled
* at the horizon on the delayed live clock.
* @returns {string} The set's id, for the sprite order.
* at the horizon on the delayed live clock, stacked by the sprite order.
* @returns {string} The set's id.
*/
function _createIcons(viewer) {
const set = drawOf(viewer).icons({
id: `${layerId}-icons:${++instances}`,
horizonCull: true,
motionClock: { kind: 'live', delayMs },
drawOrder: services.sprites?.spriteDrawOrder?.(layerId) ?? 0,
});
// Columns of no rows put the set's host in the scene now, where the
// sprite order finds it, rather than with its first contact.
// Columns of no rows put the set's host in the scene now, rather than
// with its first contact.
set.setColumns?.({ ids: [] });
switchPx = _imageSwitchPx(viewer);
state._icons = createContactIcons(set, {
-2
View File
@@ -9,7 +9,6 @@ import {
reportMeshFloorCell,
setMeshFloorPreferred,
} from './groundFloor.js';
import { unregisterSpriteCollection } from './spriteOrder.js';
import { isOverlayPointVisible, normalizeOverlayEntry } from '../overlays/worldOverlay.js';
import { createIconSet, ICON_CULL_LIFT } from './iconSet.js';
import { writeHoldSegment } from './iconSegment.js';
@@ -426,7 +425,6 @@ function createHarness(rawFires) {
},
cleanup() {
layer.destroy(viewer);
unregisterSpriteCollection('firms');
Cesium.SceneTransforms.worldToWindowCoordinates = originalProject;
globalThis.fetch = originalFetch;
if (originalWindow === undefined) delete globalThis.window; else globalThis.window = originalWindow;
+1 -1
View File
@@ -80,7 +80,7 @@ test('Directions introduces the shared OSM credit when the requested route draws
credits: { showOsmCredit, hideOsmCredit }, input, camera: {},
overlays: { setOverlayEntries: noop, setOverlaySourceVisible: noop, clearOverlaySource: noop },
render: { governorRequestRender: noop, holdContinuousRender: noop, releaseContinuousRender: noop },
sprites: { registerSpriteCollection: noop, unregisterSpriteCollection: noop, restoreSpriteOrder: noop },
sprites: {},
picking: { registerPickOwner: noop, unregisterPickOwner: noop },
ground: { warmGroundFloor: noop, resolveGroundFloorCells: async () => {} },
} });
+12 -91
View File
@@ -1,4 +1,4 @@
/** Bottom-to-top order for near-plane-clamped contact sprite collections. */
/** Bottom-to-top order of the sprite layers' icon and dot sets. */
export const SPRITE_LAYER_ORDER = Object.freeze([
'cctv',
'firms',
@@ -11,97 +11,18 @@ export const SPRITE_LAYER_ORDER = Object.freeze([
'flights',
]);
/** @type {Map<string, Object>} */
const _collections = new Map();
/**
* Register the current primitive collection for a sprite layer.
* The draw order (`SetSpec.drawOrder`) a sprite layer's set is made with:
* its place in `SPRITE_LAYER_ORDER`, counted back from -1 for flights, so
* flights draw over every other sprite layer and the rest follow the list,
* whichever layer was turned on first. Every set at the default order, 0
* (selection highlights, route endpoints, the tracked plane and the other
* overlays), stays over all of them, as it did when the sprite sets were
* raised to the bottom of the scene. A key not in the list gets 0.
* @param {string} layerId - Stable sprite-order layer key.
* @param {Object} collection - Cesium billboard/point primitive collection.
* @returns {void}
* @returns {number}
*/
export function registerSpriteCollection(layerId, collection) {
if (!layerId || !collection) return;
_collections.set(layerId, collection);
}
/**
* Register a renderer draw set for a sprite layer, by its set id. The
* default renderer names each set's host primitive with `drawSetId`; the
* restorer raises the host it finds under that name, whichever host the
* set draws with now.
* @param {string} layerId - Stable sprite-order layer key.
* @param {string} setId - The draw set's id.
* @returns {object} The registration, for `unregisterSpriteCollection`'s guard.
*/
export function registerSpriteSet(layerId, setId) {
const entry = Object.freeze({ drawSetId: setId });
if (layerId && typeof setId === 'string') _collections.set(layerId, entry);
return entry;
}
/**
* The primitive `entry` names: itself, or a draw set's host found by its id.
* The topmost match wins, so a host still retiring below its replacement is
* skipped.
*/
function resolveSprite(primitives, entry) {
if (typeof entry?.drawSetId !== 'string') return entry;
for (let i = (primitives.length ?? 0) - 1; i >= 0; i--) {
const primitive = primitives.get(i);
if (primitive?.drawSetId === entry.drawSetId) return primitive;
}
return null;
}
/**
* Remove a registered collection (primarily useful to lifecycle tests).
* @param {string} layerId - Stable sprite-order layer key.
* @param {Object} [collection] - Optional identity guard against stale teardown.
* @returns {void}
*/
export function unregisterSpriteCollection(layerId, collection) {
if (collection && _collections.get(layerId) !== collection) return;
_collections.delete(layerId);
}
/**
* Reassert deterministic sprite stacking after any layer enable/init.
* Cesium's stable translucent sort otherwise preserves first-enable primitive
* order. Raising bottom-to-top makes flights the final/top collection.
* @param {Cesium.Viewer|Object} viewer - Active viewer.
* @returns {void}
*/
export function restoreSpriteOrder(viewer) {
if (!viewer || viewer.isDestroyed?.()) return;
const scene = viewer.scene;
const primitives = scene?.primitives;
if (!primitives || scene.isDestroyed?.() || primitives.isDestroyed?.())
return;
for (const layerId of SPRITE_LAYER_ORDER) {
const collection = resolveSprite(primitives, _collections.get(layerId));
if (!collection || collection.isDestroyed?.()) continue;
if (primitives.contains?.(collection) === false) continue;
primitives.raiseToTop(collection);
}
}
/**
* Explicit layer-enable wiring seam. Production callers use the shared
* restorer by default; tests inject a spy to pin each enable path without
* constructing a WebGL viewer.
* @param {string} layerId - Sprite layer whose enable path is restoring order.
* @param {Cesium.Viewer|Object} viewer - Active viewer.
* @param {(viewer: Object) => void} [restore=restoreSpriteOrder] - Test seam.
* @returns {void}
*/
export function restoreSpriteOrderOnEnable(
layerId,
viewer,
restore = restoreSpriteOrder,
) {
if (!SPRITE_LAYER_ORDER.includes(layerId) || typeof restore !== 'function')
return;
restore(viewer);
export function spriteDrawOrder(layerId) {
const index = SPRITE_LAYER_ORDER.indexOf(layerId);
return index < 0 ? 0 : index - SPRITE_LAYER_ORDER.length;
}
+93 -116
View File
@@ -1,121 +1,98 @@
import { createRendering as createFirmsRendering } from '../layers/firms/rendering.js';
import test from 'node:test';
import assert from 'node:assert/strict';
import {
registerSpriteCollection,
restoreSpriteOrder,
restoreSpriteOrderOnEnable,
unregisterSpriteCollection,
} from './spriteOrder.js';
import flightsLayer from './flights.js';
import aisLiveVesselsLayer from './aisLiveVessels.js';
import { createFirmsHeatmapLayer } from './firmsHeatmap.js';
import * as sprites from './spriteOrder.js';
import { SPRITE_LAYER_ORDER, spriteDrawOrder } from './spriteOrder.js';
import { createAircraftIcons } from './aircraftIconLayer.js';
import { createRendering as createBikeshareRendering } from '../layers/bikeshare/rendering.js';
import { createRendering as createCctvRendering } from '../layers/cctv/rendering.js';
import { createRendering as createFirmsRendering } from '../layers/firms/rendering.js';
import { bindFakeDraw } from '../testSupport/fakeDrawPort.mjs';
const ORDER = ['cctv', 'firms', 'bikeshare', 'ais', 'military', 'flights'];
function makePrimitives(initial = []) {
return {
items: [...initial],
calls: [],
contains(collection) { return this.items.includes(collection); },
raiseToTop(collection) {
this.calls.push(collection.id);
const index = this.items.indexOf(collection);
if (index >= 0) this.items.splice(index, 1);
this.items.push(collection);
},
};
}
function makeCollection(id, destroyed = false) {
return { id, isDestroyed: () => destroyed };
}
test('restoreSpriteOrder raises live collections bottom-to-top and skips destroyed entries', () => {
const collections = Object.fromEntries(ORDER.map((id) => [id, makeCollection(id)]));
const destroyedFirms = makeCollection('firms', true);
for (const id of ORDER) {
registerSpriteCollection(id, id === 'firms' ? destroyedFirms : collections[id]);
}
const primitives = makePrimitives([
collections.flights,
collections.ais,
collections.cctv,
collections.bikeshare,
collections.military,
]);
restoreSpriteOrder({ scene: { primitives } });
assert.deepEqual(primitives.calls, ['cctv', 'bikeshare', 'ais', 'military', 'flights']);
assert.deepEqual(primitives.items.map((item) => item.id), [
'cctv', 'bikeshare', 'ais', 'military', 'flights',
]);
for (const id of ORDER) unregisterSpriteCollection(id);
});
test('late CCTV registration still restores flights above the ambient collection', () => {
const flights = makeCollection('flights');
const cctv = makeCollection('cctv');
const primitives = makePrimitives([flights]);
const viewer = { scene: { primitives } };
registerSpriteCollection('flights', flights);
restoreSpriteOrder(viewer);
primitives.items.push(cctv); // CCTV enabled after flights: it starts on top.
registerSpriteCollection('cctv', cctv);
primitives.calls.length = 0;
restoreSpriteOrder(viewer);
assert.deepEqual(primitives.calls, ['cctv', 'flights']);
assert.deepEqual(primitives.items.map((item) => item.id), ['cctv', 'flights']);
unregisterSpriteCollection('cctv', cctv);
unregisterSpriteCollection('flights', flights);
});
test('restoreSpriteOrder is inert for destroyed viewers and primitive collections', () => {
const flights = makeCollection('flights');
const primitives = makePrimitives([flights]);
registerSpriteCollection('flights', flights);
restoreSpriteOrder({ isDestroyed: () => true, scene: { primitives } });
restoreSpriteOrder({ scene: { primitives: { ...primitives, isDestroyed: () => true } } });
assert.deepEqual(primitives.calls, []);
unregisterSpriteCollection('flights', flights);
});
test('restoreSpriteOrder never raises a registered collection absent from scene primitives', () => {
const flights = makeCollection('flights');
const primitives = makePrimitives([]);
registerSpriteCollection('flights', flights);
restoreSpriteOrder({ scene: { primitives } });
assert.deepEqual(primitives.calls, []);
assert.deepEqual(primitives.items, []);
unregisterSpriteCollection('flights', flights);
});
test('flights, AIS, and FIRMS enable paths are wired through the shared sprite restorer', () => {
const viewer = { id: 'viewer' };
const calls = [];
const restoreSpy = (value) => calls.push(value);
for (const layerId of ['flights', 'ais', 'firms']) {
restoreSpriteOrderOnEnable(layerId, viewer, restoreSpy);
}
assert.deepEqual(calls, [viewer, viewer, viewer]);
const firmsLayer = createFirmsHeatmapLayer({ id: 'firms', name: 'FIRMS' });
assert.match(flightsLayer.enable.toString(), /restoreSpriteOrderOnEnable\('flights', viewer\)/);
assert.match(aisLiveVesselsLayer.enable.toString(), /restoreSpriteOrderOnEnable\('ais', activeViewer\)/);
assert.match(firmsLayer.enable.toString(), /restoreSpriteOrderOnEnable\('firms', viewer\)/);
assert.match(
createFirmsRendering.toString(),
/spriteEntry = registerSpriteSet\('firms', set\.id\);\s*restoreSpriteOrder\(layerState\._viewer\);/,
'lazy FIRMS registration must restore order immediately',
test('each sprite layer draws at its place in the order, flights on top', () => {
assert.deepEqual(
SPRITE_LAYER_ORDER.map(spriteDrawOrder),
SPRITE_LAYER_ORDER.map((_, i) => i - SPRITE_LAYER_ORDER.length),
);
assert.equal(
Math.max(...SPRITE_LAYER_ORDER.map(spriteDrawOrder)),
spriteDrawOrder('flights'),
);
assert.ok(spriteDrawOrder('military') > spriteDrawOrder('ais'));
assert.ok(spriteDrawOrder('ais') > spriteDrawOrder('transit'));
assert.ok(spriteDrawOrder('transit') > spriteDrawOrder('cctv'));
// Any other layer stays at the default, over every sprite layer.
assert.equal(spriteDrawOrder('flights'), -1);
assert.equal(spriteDrawOrder('street-level:marker'), 0);
assert.equal(spriteDrawOrder(undefined), 0);
});
/** A viewer double with a fake draw port, unbound after the test. */
function drawnViewer(t) {
const viewer = {};
const { draw, unbind } = bindFakeDraw(viewer);
t.after(unbind);
return { viewer, draw };
}
test('flights and military make their icon sets at their draw orders', (t) => {
const { viewer, draw } = drawnViewer(t);
for (const layerId of ['flights', 'military']) {
const icons = createAircraftIcons({
state: {},
services: { focus: { focusPassIsNeeded: () => false }, sprites },
parts: {},
layerId,
renderDelaySec: 0,
courseMaxDps: 1,
cockpitContactSizePx: 4,
});
const id = icons._createIcons(viewer);
assert.equal(draw.set(id).spec.drawOrder, spriteDrawOrder(layerId));
icons._disposeIcons();
}
});
test('CCTV, FIRMS and bikeshare make their sprite sets at their draw orders', (t) => {
const { viewer, draw } = drawnViewer(t);
const cctv = createCctvRendering({
state: {},
services: { focus: {}, sprites },
parts: {},
source: {},
});
const cctvId = cctv.createCameraIcons(viewer);
assert.equal(draw.set(cctvId).spec.drawOrder, spriteDrawOrder('cctv'));
cctv.destroyCameraIcons();
const layerState = { _viewer: viewer, _enabled: true };
const firms = createFirmsRendering({
layerState,
services: { anchors: {}, sprites },
components: {},
config: {
overlayHost: { setVisible() {}, clearSource() {} },
},
});
firms.ensureDetectionCollections();
assert.equal(
draw.set(layerState._icons.id).spec.drawOrder,
spriteDrawOrder('firms'),
);
firms.removeDetectionCollections();
const bikeState = {};
const bikeshare = createBikeshareRendering({
state: bikeState,
services: { render: {}, sprites },
parts: {},
source: {},
});
bikeshare.attachSets(viewer);
assert.equal(
draw.set(bikeState._stationSet.id).spec.drawOrder,
spriteDrawOrder('bikeshare'),
);
// The selected station's highlight is not a sprite layer.
assert.equal(draw.set(bikeState._selectedSet.id).spec.drawOrder, undefined);
bikeshare.detachSets();
});