diff --git a/docs/RENDERER-CONTRACT.md b/docs/RENDERER-CONTRACT.md index 16bbe94a8..81194a92b 100644 --- a/docs/RENDERER-CONTRACT.md +++ b/docs/RENDERER-CONTRACT.md @@ -175,12 +175,14 @@ and `meta` and the cluster's position, so `pick` gives the seed and `drillPick` every member. Clusters are made again in the frames drawn after the camera moves or the set changes, never on a timer. The Cesium port draws a set's cluster icons in a billboard collection of their own and hides the -members' billboards; a set on the GPU (`columns`, or moving, receding, -proxy-picked or level-of-detail icons) refuses clustering. The check -`draw.icons.cluster` draws a cluster, picks it, and parts it by moving in. +members' billboards. A set on the GPU (`columns`, or moving, receding, +proxy-picked or level-of-detail icons) clusters its rows where their segments +(and ground) put them at the frame's motion-clock time, hiding the members' +rows; while rows still move it clusters again every frame. The checks +`draw.icons.cluster` and `draw.motion.cluster` (members coming to rest on +their segments) draw a cluster, pick it, and part it by moving in. -Icon sets on the Cesium GPU path draw what its billboards draw but -clustering: pixel offsets, `bottom` and `top` anchors, screen and axis +Icon sets on the Cesium GPU path draw what its billboards draw: pixel offsets, `bottom` and `top` anchors, screen and axis rotations (turned as Cesium's billboards turn), `fadeByDistance`, `displayRange`, and `clampGround` / `relativeGround` heights. Each row reads these from a float texture by instance, so the 16 vertex attributes hold; diff --git a/src/render/cesium/draw.js b/src/render/cesium/draw.js index aeda2f944..b88fef27d 100644 --- a/src/render/cesium/draw.js +++ b/src/render/cesium/draw.js @@ -648,8 +648,16 @@ export function createCesiumDraw({ }, }; // A clustered set clusters again in the next frame drawn after a change. - for (const name of ['set', 'upsert', 'remove', 'clear', 'setOptions']) { + for (const name of [ + 'set', + 'upsert', + 'remove', + 'clear', + 'setOptions', + 'setColumns', + ]) { const call = handle[name]; + if (!call) continue; handle[name] = (...args) => { record.clusterKey = null; return call(...args); @@ -992,8 +1000,7 @@ export function createCesiumDraw({ const clusters = (record) => record.kind === 'icons' && Boolean(record.spec.cluster) && - capabilities.has('cluster') && - !record.gpu; + capabilities.has('cluster'); /** Let go of a set's cluster icons, and show its members again. */ function dropClusters(record) { @@ -1003,6 +1010,7 @@ export function createCesiumDraw({ record.clusterState = null; record.clusterKey = null; for (const placed of record.placed) placed.clustered = false; + record.gpu?.setClustered(new Set()); } const clusterScratch = new Cesium.Cartesian2(); @@ -1011,7 +1019,7 @@ export function createCesiumDraw({ * icons again where the camera moved or the set changed since it last * did (`ClusterSpec`), hiding the members and drawing an icon a cluster. */ - function clusterIcons() { + function clusterIcons(frameState = scene.frameState) { let pose; const poseNow = () => { const eye = scene.camera?.positionWC; @@ -1027,30 +1035,59 @@ export function createCesiumDraw({ } continue; } - if (!record.billboardHost || record.billboardHost.isDestroyed()) continue; - // A rebuilt collection starts afresh. - if (record.billboardHost !== record.clusteredHost) { + // A rebuilt collection (or the GPU's host in its place) starts afresh. + const host = record.gpu?.host ?? record.billboardHost; + if (!host || host.isDestroyed()) continue; + if (host !== record.clusteredHost) { record.clusterState = null; record.clusterKey = null; - record.clusteredHost = record.billboardHost; + record.clusteredHost = host; } pose ??= poseNow(); - if (record.clusterKey === pose) { + // Rows still moving on their segments cluster again every frame. + const key = record.gpu?.moving(frameState) + ? `${pose}@${frameState?.frameNumber ?? Math.random()}` + : pose; + if (record.clusterKey === key) { if (record.clusterHost) record.clusterHost.show = record.spec.show !== false; continue; } - record.clusterKey = pose; - reclusterIcons(record); + record.clusterKey = key; + reclusterIcons(record, frameState); } } - function reclusterIcons(record) { + /** The points a GPU set clusters: its shown rows where they are drawn. */ + function gpuClusterPoints(record, frameState, horizon) { + const points = []; + for (const { id, item, position } of record.gpu.drawnRows(frameState)) { + const at = toCartesian(position); + if (horizon && !horizon.isPointVisible(at)) continue; + const screen = Cesium.SceneTransforms.worldToWindowCoordinates( + scene, + at, + clusterScratch, + ); + if (!screen) continue; + points.push({ + id, + position: at, + screen: { x: screen.x, y: screen.y }, + pixelSize: Math.max(item.size[0], item.size[1]) * (item.scale ?? 1), + }); + } + return points; + } + + function reclusterIcons(record, frameState) { const spec = record.spec.cluster; const horizon = horizonNow(); - const points = []; + const points = record.gpu + ? gpuClusterPoints(record, frameState, horizon) + : []; const entries = new Map(); - for (const [id, entry] of record.billboards) { + for (const [id, entry] of record.gpu ? [] : record.billboards) { const item = record.items.get(id); const placed = entry.placed; if (!item || !placed.shown) continue; @@ -1089,6 +1126,7 @@ export function createCesiumDraw({ }); record.clusterState = result.state; const inCluster = new Set(result.clusters.flatMap((c) => c.ids)); + record.gpu?.setClustered(inCluster); for (const placed of record.placed) placed.clustered = false; for (const id of inCluster) { const entry = entries.get(id); diff --git a/src/render/cesium/gpuIcons.js b/src/render/cesium/gpuIcons.js index 3f6a552e6..61bc7ae9c 100644 --- a/src/render/cesium/gpuIcons.js +++ b/src/render/cesium/gpuIcons.js @@ -11,8 +11,9 @@ * * What these sets draw as billboards do not: an icon set becomes one when * an item first needs it (or it first takes columns), and stays one. They - * draw what billboards draw but clustering, which they refuse loudly; on - * WebGL 1 they also refuse what each row reads from its extras texture + * draw what billboards draw, clustering included (the draw port clusters + * the rows where their segments put them in the frame drawn); on WebGL 1 + * they refuse what each row reads from its extras texture * there is none of: clamped heights, `fadeByDistance`, `displayRange`, pixel * offsets, anchors other than the centre, and axis and screen rotations. * @@ -233,8 +234,6 @@ export function createGpuIcons({ /** Refuse what a GPU icon set cannot draw, before anything changes. */ function check(items, spec = {}) { - if (spec.cluster) - throw new Error("the Cesium renderer's GPU icons have no clustering"); // Atlas slots these items would take anew: they must all fit. const fresh = new Set(); for (const item of items) { @@ -325,6 +324,8 @@ export function createGpuIcons({ // Until when (epoch ms on the motion clock) a row may still move or turn. let movingUntil = -Infinity; const clockMs = () => Cesium.JulianDate.toDate(clockTime()).getTime(); + // Rows drawn as part of a cluster, hidden. + let clustered = new Set(); // What each row's segment was last written from, by id. const written = new Map(); // The ids of the last columns, while no other write came after them. @@ -428,7 +429,12 @@ export function createGpuIcons({ ); set.setDepthTestDistance(row, item.disableDepthTest ?? 0); // An empty range shows it nowhere. - set.setShown(row, item.show !== false && displayable(item.displayRange)); + set.setShown( + row, + item.show !== false && + displayable(item.displayRange) && + !clustered.has(item.id), + ); writeExtras(row, item); writeSegment(row, item, added, motion); writeGround(row, item); @@ -556,6 +562,49 @@ export function createGpuIcons({ groundQueue.add(item.id); } + /** + * `p` on a clamped row's ground, as its shader puts it: the ground + * between the heights under its segment's ends, by how far along it is. + */ + function onGround(row, p) { + const [from, to] = set.groundSpan(row); + const [g0, g1] = set.groundHeights(row); + const sx = to.x - from.x; + const sy = to.y - from.y; + const sz = to.z - from.z; + const spanSq = sx * sx + sy * sy + sz * sz; + const along = + spanSq > 0 + ? Math.min( + 1, + Math.max( + 0, + ((p.x - from.x) * sx + + (p.y - from.y) * sy + + (p.z - from.z) * sz) / + spanSq, + ), + ) + : 0; + const ground = g0 + (g1 - g0) * along; + const carto = Cesium.Cartographic.fromCartesian( + Cesium.Cartesian3.fromElements(p.x, p.y, p.z, groundAt), + undefined, + groundCarto, + ); + if (!carto) return p; + const height = + set.groundMode(row) === ICON_GROUND_CLAMP + ? ground + : carto.height + ground; + const c = Cesium.Cartesian3.fromRadians( + carto.longitude, + carto.latitude, + height, + ); + return { x: c.x, y: c.y, z: c.z }; + } + const groundAt = new Cesium.Cartesian3(); const groundCarto = new Cesium.Cartographic(); /** @@ -744,6 +793,53 @@ export function createGpuIcons({ for (const id of later) groundQueue.add(id); return changed; }, + /** + * The rows a cluster pass sees: each whose item is shown, where it + * is drawn at `frameState`'s time (on its segment, on its ground), + * with its item. + */ + drawnRows(frameState) { + const tau = set.seconds(clockTime(frameState)); + const out = []; + for (let row = 0; row < set.count; row++) { + const id = set.idAt(row); + const item = record.items.get(id); + if (!item || item.show === false || !displayable(item.displayRange)) + continue; + const p = set.position(row, tau, { x: 0, y: 0, z: 0 }); + out.push({ + id, + item, + position: grounded.has(id) ? onGround(row, p) : p, + }); + } + return out; + }, + /** Hide the rows of `ids` (in clusters); show the rest again. */ + setClustered(ids) { + const before = clustered; + clustered = ids; + for (const id of new Set([...before, ...ids])) { + if (before.has(id) === ids.has(id)) continue; + const row = set.row(id); + const item = record.items.get(id); + if (row < 0 || !item) continue; + set.setShown( + row, + item.show !== false && + displayable(item.displayRange) && + !ids.has(id), + ); + } + }, + /** Whether rows still move at the motion clock's time in `frameState`. */ + moving(frameState) { + return ( + set.count > 0 && + Cesium.JulianDate.toDate(clockTime(frameState)).getTime() < + movingUntil + ); + }, /** Whether a live-clock row is still moving: frames should keep coming. */ animating() { if (spec.motionClock?.kind === 'scene' || spec.show === false) diff --git a/src/render/cesium/gpuIcons.test.mjs b/src/render/cesium/gpuIcons.test.mjs index 6852cdf5a..1179ecfcb 100644 --- a/src/render/cesium/gpuIcons.test.mjs +++ b/src/render/cesium/gpuIcons.test.mjs @@ -492,19 +492,92 @@ test('ground samples are budgeted across frames, the drawn surface the fewest', ); }); -test('GPU icon sets refuse clustering, changing nothing', () => { - const { part, draw } = drawOver(); - const cluster = { pixelRange: 10, minimumSize: 2 }; - const set = draw.icons({ id: 'gpu:cluster' }); - set.set([icon('a', { motion: { kind: 'hold' } })]); - assert.throws(() => set.setOptions({ cluster }), /no clustering/); - assert.equal(part.sets.get('gpu:cluster').spec.cluster, undefined); - const clustered = draw.icons({ id: 'gpu:clustered', cluster }); - assert.throws( - () => clustered.set([icon('a', { motion: { kind: 'hold' } })]), - /no clustering/, - ); - assert.equal(clustered.size(), 0); +test('a GPU icon set clusters its rows where their segments put them in the frame', () => { + const transforms = Cesium.SceneTransforms; + const project = transforms.worldToWindowCoordinates; + // Window positions: a degree of longitude is `spread` pixels. + let spread = 1; + transforms.worldToWindowCoordinates = (_, position, result) => { + const at = Cesium.Cartographic.fromCartesian(position); + result ??= new Cesium.Cartesian2(); + result.x = 200 + Cesium.Math.toDegrees(at.longitude) * spread; + result.y = 150 - Cesium.Math.toDegrees(at.latitude) * spread; + return result; + }; + try { + const { part, draw, scene } = drawOver({ + capabilities: new Set(['motionSegments', 'columns', 'cluster']), + }); + scene.camera.directionWC = new Cesium.Cartesian3(-1, 0, 0); + scene.camera.positionCartographic = { height: 1000 }; + scene.canvas = { clientWidth: 400, clientHeight: 300 }; + const t0 = Cesium.JulianDate.toDate(scene.frameState.time).getTime(); + const counts = []; + const set = draw.icons({ + id: 'gpu:cluster', + motionClock: { kind: 'scene' }, + cluster: { + pixelRange: 10, + minimumSize: 2, + icon: (count) => (counts.push(count), 'badge.png'), + }, + }); + // Each given far apart, each moving to within a few pixels of the rest. + const mover = (id, lon) => { + const from = ecef(Cesium.Cartesian3.fromDegrees(lon * 40, 30)); + const to = ecef(Cesium.Cartesian3.fromDegrees(lon, 0)); + return icon(id, { + pos: from, + size: [8, 8], + meta: { id }, + motion: { kind: 'lerp', from, to, t0, t1: t0 + 1000 }, + }); + }; + set.set([mover('a', 0), mover('b', 2), mover('c', 4)]); + // At the start, apart: no cluster. + part.beforeRender(); + const { set: s } = rows(part, 'gpu:cluster'); + assert.deepEqual(counts, []); + assert.ok(['a', 'b', 'c'].every((id) => s.shown(s.row(id)))); + // At the end, together. + scene.frameState.time = julian(t0 + 5000); + part.beforeRender(); + assert.deepEqual(counts, [3]); + assert.ok( + ['a', 'b', 'c'].every((id) => !s.shown(s.row(id))), + 'members are not drawn', + ); + const clusters = part.sets.get('gpu:cluster').clusterHost; + assert.equal(clusters.length, 1); + const { id, width } = clusters.get(0); + assert.equal(width, 8, 'at its seed’s size'); + assert.deepEqual(id.cluster.ids, ['a', 'b', 'c'], 'seed first'); + const mean = Cesium.Cartographic.fromCartesian( + new Cesium.Cartesian3( + id.cluster.position.x, + id.cluster.position.y, + id.cluster.position.z, + ), + ); + assert.ok(Math.abs(Cesium.Math.toDegrees(mean.longitude) - 2) < 1e-3); + // Held still, not made again. + part.beforeRender(); + assert.deepEqual(counts, [3]); + // The camera moved: apart, each drawn again. + spread = 100; + scene.camera.positionWC = new Cesium.Cartesian3(2e7, 1, 0); + part.beforeRender(); + assert.equal(clusters.length, 0); + assert.ok(['a', 'b', 'c'].every((id) => s.shown(s.row(id)))); + // A member hidden by its item stays hidden out of a cluster. + set.upsert([{ ...mover('b', 2), show: false }]); + part.beforeRender(); + assert.equal(s.shown(s.row('b')), false); + set.dispose(); + assert.ok(!scene.added.includes(clusters), 'let go with the set'); + } finally { + transforms.worldToWindowCoordinates = project; + } }); test('columns update rows by index: positions, courses, shown, scales, tints and meta', () => { diff --git a/src/render/cesium/harness.js b/src/render/cesium/harness.js index e762b8721..201332d24 100644 --- a/src/render/cesium/harness.js +++ b/src/render/cesium/harness.js @@ -65,6 +65,7 @@ export const CESIUM_CHECKS = new Set([ 'draw.motion', 'draw.motion.arc', 'draw.motion.climb', + 'draw.motion.cluster', 'draw.motion.live', 'draw.motion.look', 'draw.motion.shared', diff --git a/src/render/conformance/checks/ports.js b/src/render/conformance/checks/ports.js index c221d4566..9b2cc10ad 100644 --- a/src/render/conformance/checks/ports.js +++ b/src/render/conformance/checks/ports.js @@ -146,8 +146,10 @@ function check(id, title, run, extra = {}) { async run(h) { const r = await fresh(h); try { - if (extra.capability && !r.capabilities.has(extra.capability)) - return { skip: `no ${extra.capability}` }; + // One capability or several, each needed. + for (const capability of [extra.capability ?? []].flat()) + if (!r.capabilities.has(capability)) + return { skip: `no ${capability}` }; return await run(h, r); } finally { r.destroy(); @@ -220,6 +222,138 @@ fn fs_main(@location(0) uv: vec2f) -> @location(0) vec4f { }, }); +/** `draw.icons.cluster`, and with `moving` its rows on their segments. */ +function clusterCheck(moving) { + return check( + moving ? 'draw.motion.cluster' : 'draw.icons.cluster', + moving + ? 'moving icons cluster where their segments put them, picked as their members seed first; apart again, each is its own' + : 'icons close on screen draw as one cluster, picked as its members seed first at its position; apart again, each is its own', + async (h, r) => { + await overAustin(h, r, 2000); + const counts = []; + const t0 = r.frame.time(); + if (moving) r.frame.setTime(t0 + 20000); + const set = r.draw.icons({ + id: 'conf:cluster', + ...(moving ? { motionClock: { kind: 'scene' } } : {}), + cluster: { + pixelRange: 20, + minimumSize: 3, + icon: (count) => { + counts.push(count); + return DOT; + }, + }, + }); + const at = (dx, dy) => + h.toEcef({ + lon: AUSTIN.lon + 0.0008 + dx * 0.0003, + lat: AUSTIN.lat + 0.0006 + dy * 0.0003, + height: 0, + }); + const members = [ + ['a', at(0, 0)], + ['b', at(1, 0)], + ['c', at(0, 1)], + ['d', at(1, 1)], + ]; + const far = h.toEcef({ + lon: AUSTIN.lon - 0.003, + lat: AUSTIN.lat - 0.002, + height: 0, + }); + set.set([ + ...members.map(([id, pos]) => ({ + id, + // Moving: given far off, come to rest where the rest are. + pos: moving ? far : pos, + image: DOT, + size: [16, 16], + meta: { m: id }, + ...(moving + ? { + motion: { + kind: 'lerp', + from: far, + to: pos, + t0, + t1: t0 + 10000, + }, + } + : {}), + })), + { + id: 'far', + pos: far, + image: DOT, + size: [16, 16], + ...(moving ? { motion: { kind: 'hold' } } : {}), + }, + ]); + await drawn(h, r); + await settled(r); + await drawn(h, r); + ok(counts.includes(4), 'the icon is drawn for its count'); + const mean = members.reduce( + (m, [, p]) => ({ + x: m.x + p.x / members.length, + y: m.y + p.y / members.length, + z: m.z + p.z / members.length, + }), + { x: 0, y: 0, z: 0 }, + ); + const s = r.query.project(mean); + ok(s, 'the cluster projects'); + const hit = r.query.pick(s.x, s.y); + deepEqual( + [hit?.set, hit?.id, hit?.meta], + ['conf:cluster', 'a', { m: 'a' }], + 'pick gives the seed, with its own meta', + ); + ok(hit?.position, 'at a position'); + nearVec(hit.position, mean, 1, 'the cluster’s position'); + const drilled = r.query + .drillPick(s.x, s.y) + .filter((x) => x.set === 'conf:cluster'); + deepEqual( + drilled.map((x) => [x.id, x.meta?.m]), + members.map(([id]) => [id, id]), + 'drillPick gives every member, seed first', + ); + const sf = r.query.project(far); + equal(r.query.pick(sf.x, sf.y)?.id, 'far', 'an icon on its own'); + + await overAustin(h, r, 300); + r.camera.setView({ + destination: { + lon: AUSTIN.lon + 0.00095, + lat: AUSTIN.lat + 0.00075, + height: 300, + }, + orientation: { heading: 0, pitch: -Math.PI / 2, roll: 0 }, + }); + await drawn(h, r); + await settled(r); + await drawn(h, r); + for (const [id, pos] of members) { + const m = r.query.project(pos); + ok(m, `${id} projects`); + deepEqual( + r.query + .drillPick(m.x, m.y) + .filter((x) => x.set === 'conf:cluster') + .map((x) => x.id), + [id], + `${id} on its own once apart`, + ); + } + set.dispose(); + }, + { capability: moving ? ['cluster', 'motionSegments'] : 'cluster' }, + ); +} + export function portChecks() { return [ // --- Shape ------------------------------------------------------------- @@ -1722,111 +1856,8 @@ export function portChecks() { for (const set of sets) set.dispose(); }, ), - check( - 'draw.icons.cluster', - 'icons close on screen draw as one cluster, picked as its members seed first at its position; apart again, each is its own', - async (h, r) => { - await overAustin(h, r, 2000); - const counts = []; - const set = r.draw.icons({ - id: 'conf:cluster', - cluster: { - pixelRange: 20, - minimumSize: 3, - icon: (count) => { - counts.push(count); - return DOT; - }, - }, - }); - const at = (dx, dy) => - h.toEcef({ - lon: AUSTIN.lon + 0.0008 + dx * 0.0003, - lat: AUSTIN.lat + 0.0006 + dy * 0.0003, - height: 0, - }); - const members = [ - ['a', at(0, 0)], - ['b', at(1, 0)], - ['c', at(0, 1)], - ['d', at(1, 1)], - ]; - const far = h.toEcef({ - lon: AUSTIN.lon - 0.003, - lat: AUSTIN.lat - 0.002, - height: 0, - }); - set.set([ - ...members.map(([id, pos]) => ({ - id, - pos, - image: DOT, - size: [16, 16], - meta: { m: id }, - })), - { id: 'far', pos: far, image: DOT, size: [16, 16] }, - ]); - await drawn(h, r); - await settled(r); - await drawn(h, r); - ok(counts.includes(4), 'the icon is drawn for its count'); - const mean = members.reduce( - (m, [, p]) => ({ - x: m.x + p.x / members.length, - y: m.y + p.y / members.length, - z: m.z + p.z / members.length, - }), - { x: 0, y: 0, z: 0 }, - ); - const s = r.query.project(mean); - ok(s, 'the cluster projects'); - const hit = r.query.pick(s.x, s.y); - deepEqual( - [hit?.set, hit?.id, hit?.meta], - ['conf:cluster', 'a', { m: 'a' }], - 'pick gives the seed, with its own meta', - ); - ok(hit?.position, 'at a position'); - nearVec(hit.position, mean, 1, 'the cluster’s position'); - const drilled = r.query - .drillPick(s.x, s.y) - .filter((x) => x.set === 'conf:cluster'); - deepEqual( - drilled.map((x) => [x.id, x.meta?.m]), - members.map(([id]) => [id, id]), - 'drillPick gives every member, seed first', - ); - const sf = r.query.project(far); - equal(r.query.pick(sf.x, sf.y)?.id, 'far', 'an icon on its own'); - - await overAustin(h, r, 300); - r.camera.setView({ - destination: { - lon: AUSTIN.lon + 0.00095, - lat: AUSTIN.lat + 0.00075, - height: 300, - }, - orientation: { heading: 0, pitch: -Math.PI / 2, roll: 0 }, - }); - await drawn(h, r); - await settled(r); - await drawn(h, r); - for (const [id, pos] of members) { - const m = r.query.project(pos); - ok(m, `${id} projects`); - deepEqual( - r.query - .drillPick(m.x, m.y) - .filter((x) => x.set === 'conf:cluster') - .map((x) => x.id), - [id], - `${id} on its own once apart`, - ); - } - set.dispose(); - }, - { capability: 'cluster' }, - ), + clusterCheck(false), + clusterCheck(true), check( 'draw.icons.update', 'an upserted icon keeps drawing, as it now is, from the next frame: picked at its new size with its new meta, even while a new image loads; a removed one is gone',