diff --git a/src/render/cesium/draw.js b/src/render/cesium/draw.js index d9e8f505c..3f3f0637d 100644 --- a/src/render/cesium/draw.js +++ b/src/render/cesium/draw.js @@ -2,7 +2,8 @@ * @module render/cesium/draw * @description The Cesium renderer's draw port * (`src/render/contract/draw.d.ts`): batched sets of items, each set one - * primitive collection in the scene, rebuilt when its items change. Every + * primitive collection in the scene, rebuilt when its items change (icon + * sets, and points restyled where they are, change in place). Every * item carries a pick id `{set, id, meta, lodGroup}`, which the query port * (`ports.js`) reads picks back through. * @@ -99,6 +100,12 @@ class UnpickableGroundPrimitive extends Cesium.GroundPrimitive { } } +/** + * Images an icon set's collection may hold, or twice those it draws when + * that is more, before it is built anew holding only those it draws. + */ +const MAX_SPARE_IMAGES = 64; + const ANCHORS = { center: Cesium.VerticalOrigin.CENTER, bottom: Cesium.VerticalOrigin.BOTTOM, @@ -153,11 +160,18 @@ export function createCesiumDraw({ scene, report }) { setsVersion += 1; }; record.rebuild = rebuild; + // Changed in place: what height queries see through may have changed. + const patched = () => { + setsVersion += 1; + requestRender(); + }; const handle = { id: spec.id, set(list) { items.clear(); for (const item of list) items.set(item.id, item); + // Icons are changed where they are, when they can be. + if (syncIcons(record, items.keys(), true)) return patched(); rebuild(); requestRender(); }, @@ -170,16 +184,25 @@ export function createCesiumDraw({ scene, report }) { return; } for (const item of list) items.set(item.id, item); + if ( + syncIcons( + record, + list.map((item) => item.id), + ) + ) + return patched(); rebuild(); requestRender(); }, remove(ids) { for (const id of ids) items.delete(id); + if (syncIcons(record, [])) return patched(); rebuild(); requestRender(); }, clear() { items.clear(); + if (syncIcons(record, [])) return patched(); rebuild(); requestRender(); }, @@ -368,8 +391,8 @@ export function createCesiumDraw({ scene, report }) { } // Atlases icons name images from, by id: `{atlas, slot}` reads the slot - // when its set is built, and registering an atlas again rebuilds the icon - // sets that drew from it. + // when its icon is drawn, and registering an atlas again swaps the images + // of the icons that drew from it. const atlases = new Map(); /** @@ -388,42 +411,211 @@ export function createCesiumDraw({ scene, report }) { blendOption: pointBlendOf(record.spec.blend), }); record.atlases = new Set(); + // Each drawn icon's billboard, in the order the collection draws them. + record.billboards = new Map(); + record.billboardHost = host; + // Every image loaded into the collection's texture atlas, which keeps + // each until the collection goes. + record.imageKeys = new Set(); for (const item of record.items.values()) { const image = iconImage(record, item.image); - if (image === undefined) continue; - // A generated image is one texture under its key, however many icons - // draw it. - const keyed = image?.canvas && typeof image.key === 'string'; - const position = toCartesian(item.pos); - const options = { - position, - ...(keyed ? {} : { image: toImage(image) }), - width: item.size[0] * (item.scale ?? 1), - height: item.size[1] * (item.scale ?? 1), - color: toColor(item.color, item.alpha ?? 1), - verticalOrigin: ANCHORS[item.anchor ?? 'center'], - disableDepthTestDistance: item.disableDepthTest ?? 0, - heightReference: heightReferenceOf(item.height, record.spec.clampTo), - show: item.show !== false, - id: pickId(record, item), - }; - if (item.rotationMode === 'screen') options.rotation = item.rotation ?? 0; - if (item.rotationMode === 'course') { - const enu = Cesium.Transforms.eastNorthUpToFixedFrame(position); - options.alignedAxis = Cesium.Matrix4.multiplyByPointAsVector( - enu, - Cesium.Cartesian3.UNIT_Y, - new Cesium.Cartesian3(), - ); - options.rotation = -Cesium.Math.toRadians(item.course ?? 0); - } - const billboard = host.add(options); - if (keyed) billboard.setImage(image.key, image.canvas); - place(record, billboard, position, options.show); + if (image !== undefined) addIcon(record, item, image); } replaceHost(record, host); } + /** A generated image, drawn as one texture under its key. */ + const isKeyed = (image) => image?.canvas && typeof image.key === 'string'; + + /** What tells one image from another, for an icon whose image changes. */ + function imageKeyOf(image) { + if (typeof image === 'string') return image; + if (typeof image?.svg === 'string') return `\u0000svg\u0000${image.svg}`; + if (isKeyed(image)) return `\u0000key\u0000${image.key}`; + return image?.canvas ?? image; + } + + /** How a billboard draws an icon item at `position`, but its image and id. */ + function iconLook(record, item, position) { + const look = { + position, + width: item.size[0] * (item.scale ?? 1), + height: item.size[1] * (item.scale ?? 1), + color: toColor(item.color, item.alpha ?? 1), + verticalOrigin: ANCHORS[item.anchor ?? 'center'], + disableDepthTestDistance: item.disableDepthTest ?? 0, + heightReference: heightReferenceOf(item.height, record.spec.clampTo), + show: item.show !== false, + // The defaults, so a restyle in place puts back what an item dropped. + rotation: 0, + alignedAxis: Cesium.Cartesian3.ZERO, + }; + if (item.rotationMode === 'screen') look.rotation = item.rotation ?? 0; + if (item.rotationMode === 'course') { + const enu = Cesium.Transforms.eastNorthUpToFixedFrame(position); + look.alignedAxis = Cesium.Matrix4.multiplyByPointAsVector( + enu, + Cesium.Cartesian3.UNIT_Y, + new Cesium.Cartesian3(), + ); + look.rotation = -Cesium.Math.toRadians(item.course ?? 0); + } + return look; + } + + /** Give a billboard its image: a generated one under its key. */ + function setIconImage(record, billboard, image) { + if (isKeyed(image)) billboard.setImage(image.key, image.canvas); + else billboard.image = toImage(image); + record.imageKeys.add(imageKeyOf(image)); + } + + /** Draw an icon item as a new billboard, after the set's others. */ + function addIcon(record, item, image) { + const position = toCartesian(item.pos); + const options = { + ...iconLook(record, item, position), + id: pickId(record, item), + }; + const billboard = record.billboardHost.add(options); + setIconImage(record, billboard, image); + const placed = place(record, billboard, position, options.show); + record.billboards.set(item.id, { + billboard, + placed, + image: imageKeyOf(image), + canvas: image?.canvas, + }); + } + + /** + * Draw a drawn icon as its item now is, on the billboard it has: its + * image is loaded again only when it changes, so restyled icons never + * blink. An SVG drawn at a new size keeps the raster it was loaded at, as + * Cesium's entities do. + */ + function patchIcon(record, entry, item, image) { + const { billboard, placed } = entry; + const position = toCartesian(item.pos); + const look = iconLook(record, item, position); + // Sized first: a new SVG image rasterises at the billboard's size. + Object.assign(billboard, look); + const key = imageKeyOf(image); + if (key !== entry.image) { + setIconImage(record, billboard, image); + entry.image = key; + entry.canvas = image?.canvas; + } + // Picks and height queries hold this id object: changed, not replaced. + billboard.id.meta = item.meta; + billboard.id.lodGroup = item.lodGroup; + placed.position = position; + // As a rebuild would; the horizon cull, where it runs, hides it again + // past the horizon before the next frame draws. + placed.shown = look.show; + } + + /** + * Bring an icon set's billboards in line with its items without a + * rebuild: those of items gone (or whose image is gone) are removed, the + * items `touched` are drawn as they now are, and new ones are added. A + * collection draws in the order its billboards were added, so this is + * done only when that stays the items' order: new icons come after every + * one kept and, with `reordered` (a `set`), the kept ones keep their + * order. A collection keeps every image it loaded, so it is also rebuilt + * (anew, holding only what it draws) when it would hold many more images + * than it draws, when it is emptied, and when a generated image under a + * key it has comes as a new canvas (its key's texture would not change). + * False, changing nothing, otherwise, and when the set has no live + * collection of its own. + * @param {object} record + * @param {Iterable} touched Ids of items that may have changed. + * @param {boolean} [reordered] The items were replaced, in a new order. + */ + function syncIcons(record, touched, reordered = false) { + const drawn = record.billboards; + const host = record.billboardHost; + if ( + record.kind !== 'icons' || + !drawn || + !host || + record.host !== host || + host.isDestroyed() + ) + return false; + const images = new Map(); + for (const id of touched) { + const item = record.items.get(id); + if (item) images.set(id, iconImage(record, item.image)); + } + if (record.items.size === 0) return false; + const keeps = (id) => + record.items.has(id) && (!images.has(id) || images.get(id) !== undefined); + const adds = (id) => + !drawn.has(id) && images.has(id) && images.get(id) !== undefined; + let adding = false; + const kept = []; + for (const id of record.items.keys()) { + if (adds(id)) adding = true; + else if (drawn.has(id) && keeps(id)) { + if (adding) return false; + kept.push(id); + } + } + if (reordered) { + let at = 0; + for (const id of drawn.keys()) + if (keeps(id) && kept[at++] !== id) return false; + } + // The images drawn once this is done, and those it would load. + const drawing = new Set(); + let loading = 0; + for (const id of kept) { + const entry = drawn.get(id); + if (!images.has(id)) { + drawing.add(entry.image); + continue; + } + const image = images.get(id); + const key = imageKeyOf(image); + if ( + isKeyed(image) && + key === entry.image && + image.canvas !== entry.canvas + ) + return false; + drawing.add(key); + } + for (const [id, image] of images) + if (image !== undefined && !drawn.has(id)) drawing.add(imageKeyOf(image)); + for (const key of drawing) if (!record.imageKeys.has(key)) loading += 1; + if ( + record.imageKeys.size + loading > + Math.max(MAX_SPARE_IMAGES, 2 * drawing.size) + ) + return false; + const gone = new Set(); + for (const [id, entry] of drawn) + if (!keeps(id)) { + host.remove(entry.billboard); + drawn.delete(id); + gone.add(entry.billboard); + } + if (gone.size) { + record.placed = record.placed.filter((p) => !gone.has(p.primitive)); + const ids = new Set([...gone].map((billboard) => billboard.id)); + record.pickIds = record.pickIds.filter((id) => !ids.has(id)); + } + for (const [id, item] of record.items) { + const image = images.get(id); + if (image === undefined) continue; + const entry = drawn.get(id); + if (entry) patchIcon(record, entry, item, image); + else addIcon(record, item, image); + } + return true; + } + function buildPoints(record) { let points = null; let dots = null; @@ -1131,13 +1323,19 @@ export function createCesiumDraw({ scene, report }) { }, atlas(id, images) { atlases.set(id, { ...images }); - let rebuilt = false; + let changed = false; for (const record of [...sets.values()]) if (record.kind === 'icons' && record.atlases?.has(id)) { - record.rebuild(); - rebuilt = true; + // Its icons that draw from the atlas take their new images where + // they are; a set that cannot is rebuilt. + const drawing = []; + for (const [itemId, item] of record.items) + if (item.image?.atlas === id) drawing.push(itemId); + if (syncIcons(record, drawing)) setsVersion += 1; + else record.rebuild(); + changed = true; } - if (rebuilt) scene.requestRender(); + if (changed) scene.requestRender(); }, }; diff --git a/src/render/cesium/draw.test.mjs b/src/render/cesium/draw.test.mjs index 7c4aa4385..5a98c95cb 100644 --- a/src/render/cesium/draw.test.mjs +++ b/src/render/cesium/draw.test.mjs @@ -2,7 +2,7 @@ import assert from 'node:assert/strict'; import * as Cesium from 'cesium'; import test from 'node:test'; import { bindRenderer, drawOf, findDraw } from '../rendererOf.js'; -import './draw.js'; +import { createCesiumDraw } from './draw.js'; // Node has no WebGL context to report line-width limits. Cesium.ContextLimits._minimumAliasedLineWidth = 1; @@ -1227,3 +1227,175 @@ test('icons blend as their set says', () => { ); set.dispose(); }); + +test('icon sets change their billboards in place: restyled, moved, re-imaged, added and removed', () => { + const scene = fakeScene(); + const part = createCesiumDraw({ + scene, + report: (error) => assert.fail(error), + }); + const set = part.port.icons({ id: 'icons:in-place', horizonCull: true }); + const record = part.sets.get('icons:in-place'); + const icon = (id, lon, extra = {}) => ({ + id, + pos: { lon, lat: 0 }, + image: 'a.png', + size: [10, 10], + ...extra, + }); + set.set([icon('a', 0), icon('b', 1)]); + const [host] = scene.added; + const [a, b] = [host.get(0), host.get(1)]; + const version = part.version(); + + set.upsert([ + icon('a', 2, { + color: [0, 1, 0, 1], + scale: 2, + meta: { n: 1 }, + rotationMode: 'screen', + rotation: 0.5, + image: 'b.png', + }), + ]); + assert.equal(scene.added[0], host, 'the same collection'); + assert.equal(host.get(0), a, 'the same billboard'); + assert.ok(Cesium.Color.equals(a.color, Cesium.Color.LIME)); + assert.equal(a.width, 20); + assert.equal(a.rotation, 0.5); + assert.equal(a.image, 'b.png', 'its image swapped'); + assert.equal(b.image, 'a.png', 'the others keep theirs'); + assert.deepEqual(a.id.meta, { n: 1 }, 'picks read the new meta'); + const moved = Cesium.Cartographic.fromCartesian(a.position); + assert.ok(Math.abs(Cesium.Math.toDegrees(moved.longitude) - 2) < 1e-9); + assert.ok(part.version() > version, 'height queries see the change'); + + // Back to the defaults it dropped. + set.upsert([icon('a', 2)]); + assert.equal(a.rotation, 0); + assert.equal(a.width, 10); + + set.upsert([icon('c', 3)]); + assert.equal(scene.added[0], host, 'a new icon is added to it'); + assert.equal(host.length, 3); + set.remove(['b']); + assert.equal(scene.added[0], host, 'and one removed from it'); + assert.equal(host.length, 2); + assert.deepEqual( + record.pickIds.map((id) => id.id).sort(), + ['a', 'c'], + 'height queries no longer see through what went', + ); + assert.deepEqual( + record.placed.map((p) => p.primitive), + [a, host.get(1)], + 'the horizon cull no longer tests it', + ); + + // Hidden in place, then culled with the rest. + set.upsert([icon('a', 2, { show: false })]); + assert.equal(a.show, false); + + // A set in the same order patches; a new order rebuilds. + set.set([icon('a', 2), icon('c', 3)]); + assert.equal(scene.added[0], host); + set.set([icon('c', 3), icon('a', 2)]); + assert.notEqual(scene.added[0], host, 'reordered: rebuilt'); + assert.equal(scene.added[0].get(0).id.id, 'c'); + set.clear(); + assert.equal(scene.added[0].length, 0); + set.dispose(); + assert.equal(scene.added.length, 0); +}); + +test('an icon drawn from an atlas slot takes a re-registered slot in place', () => { + const scene = fakeScene(); + const part = createCesiumDraw({ + scene, + report: (error) => assert.fail(error), + }); + const set = part.port.icons({ id: 'icons:atlas' }); + const icon = (id, slot, lon) => ({ + id, + pos: { lon, lat: 0 }, + image: { atlas: 'marks', slot }, + size: [8, 8], + }); + set.set([icon('one', 'dot', 0), icon('two', 'ring', 1)]); + const [host] = scene.added; + assert.equal(host.length, 0, 'nothing to draw until the atlas comes'); + part.port.atlas('marks', { dot: 'dot.png' }); + assert.equal(scene.added[0], host); + const one = host.get(0); + assert.equal(one.image, 'dot.png'); + part.port.atlas('marks', { dot: 'next.png', ring: 'ring.png' }); + assert.equal(scene.added[0], host, 'not rebuilt'); + assert.equal(host.get(0), one, 'the same billboard'); + assert.equal(one.image, 'next.png'); + assert.equal(host.get(1).image, 'ring.png', 'the slot that came draws'); + part.port.atlas('marks', { ring: 'ring.png' }); + assert.equal(host.length, 1, 'a slot gone takes its icon down'); + assert.equal(host.get(0).id.id, 'two'); + // A slot that comes for an icon ahead of one drawn rebuilds, in order. + part.port.atlas('marks', { dot: 'dot.png', ring: 'ring.png' }); + assert.notEqual(scene.added[0], host); + assert.deepEqual( + [scene.added[0].get(0).id.id, scene.added[0].get(1).id.id], + ['one', 'two'], + ); + set.dispose(); +}); + +test('an icon set is built anew where changing it in place would draw out of order or keep stale images', () => { + const scene = fakeScene(); + const part = createCesiumDraw({ + scene, + report: (error) => assert.fail(error), + }); + const set = part.port.icons({ id: 'icons:anew' }); + const icon = (id, image = 'a.png') => ({ + id, + pos: { lon: 0, lat: 0 }, + image, + size: [8, 8], + }); + set.set([icon('a'), icon('c')]); + let host = scene.added[0]; + set.set([icon('a'), icon('b'), icon('c')]); + assert.notEqual(scene.added[0], host, 'one put between two drawn: rebuilt'); + assert.deepEqual( + [0, 1, 2].map((i) => scene.added[0].get(i).id.id), + ['a', 'b', 'c'], + ); + + // A generated image swaps under a new key; a new canvas under the key it + // had cannot change that key's texture, so it rebuilds. + const canvas = { width: 8, height: 8 }; + set.set([icon('a', { canvas, key: 'one' })]); + host = scene.added[0]; + const a = host.get(0); + set.upsert([icon('a', { canvas, key: 'two' })]); + assert.equal(scene.added[0], host, 'a new key swaps in place'); + assert.equal(host.get(0), a); + set.upsert([icon('a', { canvas: { width: 8, height: 8 }, key: 'two' })]); + assert.notEqual(scene.added[0], host, 'a new canvas, same key: rebuilt'); + + // Its collection keeps what it loaded, so cycling images rebuilds now and + // then, holding only what it draws. + host = scene.added[0]; + let rebuilds = 0; + for (let i = 0; i < 200; i++) { + set.upsert([icon('a', `cycle-${i}.png`)]); + if (scene.added[0] !== host) { + rebuilds += 1; + host = scene.added[0]; + } + } + assert.ok(rebuilds >= 2 && rebuilds <= 4, `rebuilt ${rebuilds} times`); + assert.ok(part.sets.get('icons:anew').imageKeys.size <= 64); + + set.clear(); + assert.notEqual(scene.added[0], host, 'emptied: built anew, empty'); + assert.equal(scene.added[0].length, 0); + set.dispose(); +}); diff --git a/src/render/cesium/harness.js b/src/render/cesium/harness.js index 0f036deea..04e10a98b 100644 --- a/src/render/cesium/harness.js +++ b/src/render/cesium/harness.js @@ -36,6 +36,7 @@ export const CESIUM_CHECKS = new Set([ 'draw.atlas', 'draw.clampState', 'draw.drillPick', + 'draw.icons.update', 'draw.ids', 'draw.models', 'draw.pick', diff --git a/src/render/cesium/ports.test.mjs b/src/render/cesium/ports.test.mjs index ee1b457f7..e23b4c72c 100644 --- a/src/render/cesium/ports.test.mjs +++ b/src/render/cesium/ports.test.mjs @@ -675,7 +675,7 @@ test('clampState drapes without tiles and overlays shown ones, told on change', ports.dispose(); }); -test('an icon draws its atlas slot once the atlas has it, and again when it changes', () => { +test('an icon draws its atlas slot once the atlas has it, and swaps it when it changes', () => { const { widget, scene } = tickingWidget(); const list = []; scene.primitives = listedPrimitives(list); @@ -698,10 +698,12 @@ test('an icon draws its atlas slot once the atlas has it, and again when it chan assert.equal(first.get(0).image, 'dot.png'); ports.draw.atlas('other', { dot: 'other.png' }); assert.equal(list.at(-1), first, 'another atlas leaves the set alone'); + const dot = first.get(0); ports.draw.atlas('conf', { dot: 'next.png', ring: 'ring.png' }); - assert.notEqual(list.at(-1), first, 'rebuilt'); + assert.equal(list.at(-1), first, 'changed in place'); + assert.equal(first.get(0), dot, 'the same billboard, its image swapped'); assert.deepEqual( - [list.at(-1).get(0).image, list.at(-1).get(1).image], + [first.get(0).image, first.get(1).image], ['next.png', 'ring.png'], ); ports.dispose(); diff --git a/src/render/conformance/checks/ports.js b/src/render/conformance/checks/ports.js index 70a4f7612..532f6f304 100644 --- a/src/render/conformance/checks/ports.js +++ b/src/render/conformance/checks/ports.js @@ -1171,6 +1171,56 @@ export function portChecks() { set.dispose(); }, ), + 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', + async (h, r) => { + await overAustin(h, r); + const set = r.draw.icons({ id: 'conf:icons-update' }); + const pos = h.toEcef({ ...AUSTIN, height: 0 }); + const icon = (extra = {}) => ({ + id: 'one', + pos, + image: DOT, + size: [16, 16], + meta: { n: 1 }, + ...extra, + }); + set.set([icon()]); + await drawn(h, r); + await settled(r); + const s = r.query.project(pos); + ok(s, 'the icon projects'); + equal(r.query.pick(s.x, s.y)?.id, 'one', 'drawn and picked'); + const off = () => r.query.pick(s.x + 20, s.y); + ok(off()?.set !== 'conf:icons-update', 'not picked 20 px off'); + // Not settled again: a restyle keeps drawing, with no reload. + set.upsert([ + icon({ size: [64, 64], color: '#00ff00', meta: { n: 2 } }), + ]); + await drawn(h, r); + const hit = off(); + equal(hit?.id, 'one', 'picked at its new size in the next frame'); + deepEqual(hit?.meta, { n: 2 }, 'with its new meta'); + // A new image keeps the icon drawn while it loads. + set.upsert([ + icon({ + size: [64, 64], + meta: { n: 3 }, + image: { svg: DOT.svg.replace('#fff', '#ff0') }, + }), + ]); + await drawn(h, r); + equal(off()?.id, 'one', 'a new image: still drawn in the next frame'); + await settled(r); + deepEqual(off()?.meta, { n: 3 }, 'and drawn with it once loaded'); + set.remove(['one']); + await drawn(h, r); + const gone = r.query.pick(s.x, s.y); + ok(!gone || gone.set !== 'conf:icons-update', 'removed: not picked'); + set.dispose(); + }, + ), check( 'draw.columns', 'column updates are rows: sized, picked, removed',