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',
+58
View File
@@ -721,6 +721,64 @@ export function portChecks() {
stack.dispose();
},
),
check(
'draw.drawOrder',
'of sets drawn over depth, the higher draw order is on top and picked',
async (h, r) => {
await overAustin(h, r);
const pos = h.toEcef({ ...AUSTIN, height: 0 });
const icon = (id) => ({
id,
pos,
image: DOT,
size: [24, 24],
disableDepthTest: Infinity,
});
const first = r.draw.icons({ id: 'conf:order-first' });
// Made after it, but drawn over it.
const second = r.draw.icons({ id: 'conf:order-second', drawOrder: 2 });
first.set([icon('a')]);
second.set([icon('b')]);
await drawn(h, r);
await settled(r);
const s = r.query.project(pos);
ok(s, 'the icons project');
const sets = () =>
r.query
.drillPick(s.x, s.y)
.filter((x) => x.set.startsWith('conf:order-'))
.map((x) => x.set);
equal(r.query.pick(s.x, s.y)?.set, 'conf:order-second', 'the higher');
deepEqual(
sets(),
['conf:order-second', 'conf:order-first'],
'topmost first',
);
first.setOptions({ drawOrder: 3 });
await drawn(h, r);
equal(
r.query.pick(s.x, s.y)?.set,
'conf:order-first',
'raised, the pick flips',
);
deepEqual(
sets(),
['conf:order-first', 'conf:order-second'],
'and the drill',
);
// Of one order, they keep the order they were made in.
first.setOptions({ drawOrder: 0 });
second.setOptions({ drawOrder: 0 });
await drawn(h, r);
equal(
r.query.pick(s.x, s.y)?.set,
'conf:order-first',
'equal ones as they were made',
);
first.dispose();
second.dispose();
},
),
check(
'query.pickBeforeStyles',
'picks answer against the scene as drawn before styles',
+6 -1
View File
@@ -51,7 +51,12 @@ export interface SetSpec {
/** `cluster`: screen-space clustering (icons only). */
cluster?: ClusterSpec | null;
blend?: 'opaque' | 'translucent' | 'additive';
/** Draw order between sets that do not depth-test against each other. */
/**
* Among sets that do not depth-test against each other (items drawn with
* `disableDepthTest`), a higher one draws over a lower one whatever order
* they were made in; equal ones keep that order. `pick` and `drillPick`
* name them topmost first. Default 0.
*/
drawOrder?: number;
/** `false`: the set never takes part in picks. */
pickable?: boolean;
+22 -2
View File
@@ -313,6 +313,7 @@ export function createStubRenderer(options = {}) {
const sets = new Map();
const atlases = new Map();
let setSeq = 0;
function makeSet(kind, spec) {
if (!spec?.id) throw new TypeError('A draw set needs an id');
if (sets.has(spec.id))
@@ -320,6 +321,8 @@ export function createStubRenderer(options = {}) {
const record = {
kind,
spec: { ...spec },
// When it was made: of sets of one `drawOrder`, the earlier is on top.
seq: (setSeq += 1),
items: new Map(),
show: spec.show ?? true,
readyListeners: [],
@@ -443,6 +446,8 @@ export function createStubRenderer(options = {}) {
const record = {
kind,
spec: { ...spec },
// When it was made: of sets of one `drawOrder`, the earlier is on top.
seq: (setSeq += 1),
items: new Map(),
show: true,
readyListeners: [],
@@ -779,17 +784,32 @@ export function createStubRenderer(options = {}) {
...(item.lodGroup !== undefined ? { lodGroup: item.lodGroup } : {}),
surface: false,
position: p,
depth: magnitude(sub(p, eye().position)),
depth: distance,
blocked: blockedItem(item),
// Drawn over depth here: stacked by its set's draw order.
over: (item.disableDepthTest ?? 0) > distance,
order: set.spec.drawOrder ?? 0,
seq: set.seq,
});
}
}
hits.sort((a, b) => a.depth - b.depth);
// What skips the depth test is on top, the highest draw order first and
// of one order the set made first (as the default renderer stacks
// opaque ones); the rest nearest first.
hits.sort(
(a, b) =>
(b.over === true) - (a.over === true) ||
(a.over ? b.order - a.order || a.seq - b.seq : 0) ||
a.depth - b.depth,
);
const looked = depth === undefined ? hits : hits.slice(0, depth);
const out = looked.filter((hit) => !hit.blocked);
for (const hit of out) {
delete hit.depth;
delete hit.blocked;
delete hit.over;
delete hit.order;
delete hit.seq;
}
return out;
}