diff --git a/src/render/cesium/draw.js b/src/render/cesium/draw.js index 9c15d4e6a..82207172a 100644 --- a/src/render/cesium/draw.js +++ b/src/render/cesium/draw.js @@ -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. */ diff --git a/src/render/cesium/draw.test.mjs b/src/render/cesium/draw.test.mjs index eb4826594..85963d727 100644 --- a/src/render/cesium/draw.test.mjs +++ b/src/render/cesium/draw.test.mjs @@ -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(); diff --git a/src/render/cesium/harness.js b/src/render/cesium/harness.js index f5852fd10..9df9da99c 100644 --- a/src/render/cesium/harness.js +++ b/src/render/cesium/harness.js @@ -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', diff --git a/src/render/conformance/checks/ports.js b/src/render/conformance/checks/ports.js index 10f2d38cd..d4924612b 100644 --- a/src/render/conformance/checks/ports.js +++ b/src/render/conformance/checks/ports.js @@ -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', diff --git a/src/render/contract/draw.d.ts b/src/render/contract/draw.d.ts index bcc94ad5b..8b715834d 100644 --- a/src/render/contract/draw.d.ts +++ b/src/render/contract/draw.d.ts @@ -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; diff --git a/src/render/stub/index.js b/src/render/stub/index.js index 36df31bff..83b717016 100644 --- a/src/render/stub/index.js +++ b/src/render/stub/index.js @@ -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; }