Make SetSpec.drawOrder exact and draw it in Cesium and the stub

Among sets that skip the depth test, a higher drawOrder draws over a lower
one whatever order they were made in, and picks name them topmost first.

Cesium draws the earlier of two opaque near-plane icons on top and picks
it, so the draw port stacks the sets' hosts with a higher order earlier,
ties in the order the sets were made. Hosts trade places only among the
slots draw-set hosts already hold, so no other primitive moves; nothing
moves while every set is at 0. Translucent items blend
order-independently in Cesium and are not ordered by it.

The stub sorts its hits the same way. A conformance check draws two icon
sets at one spot and swaps their orders.
This commit is contained in:
Sameh Khamis committed 2026-11-08 13:01:36 -08:00
1 parent 45302e9fbf
commit 8fe8b8e14d
6 files changed
+219 -3

No files matched your search

+64
View File
@@ -351,6 +351,7 @@ export function createCesiumDraw({
requestRender: requestFrame = null,
}) {
const sets = new Map();
let setSeq = 0;
// Bumped whenever what height queries see through may have changed: a
// set made, rebuilt, restyled or gone, or items added or removed (icons
// changed in place keep their pick ids, so they do not bump it).
@@ -375,6 +376,8 @@ export function createCesiumDraw({
items,
listeners,
host: null,
// When it was made: `drawOrder`'s ties keep that order.
seq: (setSeq += 1),
pickIds: [],
// What it drew before its ground primitives were ready, still shown.
retiring: null,
@@ -495,6 +498,7 @@ export function createCesiumDraw({
const clampTo = spec.clampTo;
const blend = spec.blend;
const pickable = spec.pickable !== false;
const drawOrder = spec.drawOrder ?? 0;
Object.assign(spec, options);
// What clamped items clamp to, how points blend, and whether ground
// primitives pick, are built into them. Models clamp nothing, only
@@ -520,6 +524,7 @@ export function createCesiumDraw({
showHosts(record);
// No longer culled: what the cull hid comes back.
if (culled && !spec.horizonCull) uncull(record);
if ((spec.drawOrder ?? 0) !== drawOrder) orderHosts(true);
requestRender();
},
size: () => items.size,
@@ -668,6 +673,65 @@ export function createCesiumDraw({
if (at >= 0) scene.primitives.add(host, at);
else scene.primitives.add(host);
showHosts(record);
// A new set's host comes in last; it takes its place by draw order.
if (!old) orderHosts();
}
/**
* `SetSpec.drawOrder`: the sets' hosts stacked in the scene's primitives
* by their draw order. Of opaque billboards and points that skip the
* depth test, Cesium draws the one in the earlier primitive on top (both
* at the near plane, the later fails the depth test) and picks it, so a
* higher order goes earlier; of one order, in the order they were made.
* The hosts trade places among the slots they hold, so nothing else in
* the scene moves. Nothing moves while every set is at 0 (unless an order
* just changed, `changed`), so sets at 0 stack as they were first drawn
* (and as the sprite order raises them); nor while the hosts are already
* in order.
* Translucent ones blend order-independently, whatever their order, and
* items in different view frustums stack nearer frustum first.
* @param {boolean} [changed]
*/
function orderHosts(changed = false) {
if (!live()) return;
let ordered = changed;
for (const record of sets.values())
if ((record.spec.drawOrder ?? 0) !== 0) ordered = true;
if (!ordered) return;
const placed = [];
for (const record of sets.values()) {
if (!record.host || record.host.isDestroyed?.()) continue;
const slot = slotOf(record.host);
if (slot >= 0) placed.push({ record, slot });
}
const slots = placed.map(({ slot }) => slot).sort((a, b) => a - b);
const wanted = [...placed].sort(
(a, b) =>
(b.record.spec.drawOrder ?? 0) - (a.record.spec.drawOrder ?? 0) ||
a.record.seq - b.record.seq,
);
if (wanted.every(({ slot }, i) => slot === slots[i])) return;
// Each slot, lowest first, takes its host by trading places with the
// host in it (taken out and put back, not destroyed): what lies between
// them, and every slot already filled, stays where it is.
const primitives = scene.primitives;
const destroys = primitives.destroyPrimitives;
primitives.destroyPrimitives = false;
try {
wanted.forEach(({ record }, i) => {
const to = slots[i];
const from = slotOf(record.host);
if (from === to) return;
// `from` is later: the hosts still to place sit after the filled slots.
const other = primitives.get(to);
primitives.remove(record.host);
primitives.add(record.host, to);
primitives.remove(other);
primitives.add(other, from);
});
} finally {
primitives.destroyPrimitives = destroys;
}
}
/** Where `primitive` is among the scene's primitives, or -1. */
+68
View File
@@ -1103,6 +1103,74 @@ test('a rebuilt set keeps its place among the scene primitives, and names its ho
set.dispose();
});
test('sets stack by drawOrder, a higher one earlier, ties as they were made', () => {
const scene = fakeScene();
scene.primitives = new Cesium.PrimitiveCollection();
const { draw } = drawOver(scene);
const below = scene.primitives.add(new Cesium.PrimitiveCollection());
const order = () => {
const out = [];
for (let i = 0; i < scene.primitives.length; i++) {
const p = scene.primitives.get(i);
out.push(p === below ? 'below' : p.drawSetId);
}
return out;
};
const dot = { id: 'a', pos: { lon: 0, lat: 0 }, pixelSize: 4, color: '#fff' };
const plain = draw.points({ id: 'plain' });
plain.set([dot]);
const between = scene.primitives.add(new Cesium.PrimitiveCollection());
const high = draw.points({ id: 'high', drawOrder: 2 });
high.set([dot]);
const named = () =>
order().map((n, i) =>
scene.primitives.get(i) === between ? 'between' : n,
);
// Drawn first, so on top; the other primitives keep their places.
assert.deepEqual(named(), ['below', 'high', 'between', 'plain']);
assert.equal(high.size(), 1, 'not destroyed by the move');
high.setOptions({ drawOrder: 0 });
assert.deepEqual(
named(),
['below', 'plain', 'between', 'high'],
'back to 0, it takes its place by when it was made',
);
// All at 0, nothing is moved: what others stacked stays.
scene.primitives.raiseToTop(below);
const added = draw.points({ id: 'added' });
added.set([dot]);
assert.deepEqual(named(), ['plain', 'between', 'high', 'below', 'added']);
for (const set of [high, plain, added]) set.dispose();
});
test('reordering by drawOrder leaves the other primitives where they are', () => {
const scene = fakeScene();
scene.primitives = new Cesium.PrimitiveCollection();
const { draw } = drawOver(scene);
const dot = { id: 'a', pos: { lon: 0, lat: 0 }, pixelSize: 4, color: '#fff' };
const [a, b, c] = ['A', 'B', 'C'].map((id) => draw.points({ id }));
const x = new Cesium.PrimitiveCollection();
const y = new Cesium.PrimitiveCollection();
c.set([dot]);
scene.primitives.add(x);
b.set([dot]);
scene.primitives.add(y);
a.set([dot]);
const order = () => {
const out = [];
for (let i = 0; i < scene.primitives.length; i++) {
const p = scene.primitives.get(i);
out.push(p === x ? 'X' : p === y ? 'Y' : p.drawSetId);
}
return out;
};
assert.deepEqual(order(), ['C', 'X', 'B', 'Y', 'A']);
a.setOptions({ drawOrder: 1 });
assert.deepEqual(order(), ['A', 'X', 'B', 'Y', 'C']);
assert.ok(!x.isDestroyed() && !y.isDestroyed());
for (const set of [a, b, c]) set.dispose();
});
test('changing an option rebuilds only the kinds that build it in, in their place', () => {
const scene = fakeScene();
scene.primitives = new Cesium.PrimitiveCollection();
+1
View File
@@ -38,6 +38,7 @@ export const CESIUM_CHECKS = new Set([
'draw.clampState',
'draw.columns',
'draw.columns.shown',
'draw.drawOrder',
'draw.drillPick',
'draw.icons.distance',
'draw.icons.update',