From 0f9bd23829ea770f05ac27c5477d381be66b8e32 Mon Sep 17 00:00:00 2001 From: Sameh Khamis Date: Sat, 7 Nov 2026 19:19:14 -0800 Subject: [PATCH] Change a clamped fill's show in place in the Cesium draw port An upsert that only shows or hides clamped colour fills, or changes their meta, now writes each fill's show attribute instead of rebuilding every ground primitive of the set. Hidden fills are built too, hidden, as Cesium's entity ground batches keep them; a show written while the ground primitives build waits for their swap. A hidden fill the port could not draw shown stays out, as before, and a set whose fills are all hidden no longer keeps the old ones drawn while it builds. Anything else about a fill, including a value changed in place, still rebuilds. --- src/render/cesium/draw.js | 184 ++++++++++++++++++++++++--- src/render/cesium/draw.test.mjs | 213 ++++++++++++++++++++++++++++++++ 2 files changed, 378 insertions(+), 19 deletions(-) diff --git a/src/render/cesium/draw.js b/src/render/cesium/draw.js index 935e55060..475e5a4a6 100644 --- a/src/render/cesium/draw.js +++ b/src/render/cesium/draw.js @@ -324,11 +324,13 @@ export function createCesiumDraw({ record.gpu.write(list); return patched(); } - // Points restyled or moved, and lines that only change how they show - // or where an undraped one runs, are changed where they are. + // Points restyled or moved, lines that only change how they show + // or where an undraped one runs, and clamped shapes that only show + // or hide, are changed where they are. if ( patchPoints(record, list) || patchLines(record, list) || + patchShapes(record, list) || (kind === 'models' && modelSets.upsert(record, list)) ) { for (const item of list) items.set(item.id, item); @@ -495,9 +497,17 @@ export function createCesiumDraw({ * ground primitives), the new host's ground primitives stay hidden and * the old host keeps drawing until every one is ready, then they swap in * one frame, as the entities' ground batches do; a host still waiting - * when the next one comes is dropped. + * when the next one comes is dropped. With `groundShown` false, the new + * ground primitives show nothing yet (all their items are hidden), so + * the old host goes at once rather than wait for them. */ - function replaceHost(record, host, ground = null, own = null) { + function replaceHost( + record, + host, + ground = null, + own = null, + groundShown = true, + ) { const old = record.host; const waiting = ground?.length ? ground : null; // The set keeps its place among the scene's primitives: a rebuild draws @@ -516,6 +526,7 @@ export function createCesiumDraw({ if ( old && waiting && + groundShown && !record.retiring && !record.pending && record.ground @@ -523,7 +534,7 @@ export function createCesiumDraw({ record.retiring = old; if (record.own) old.remove(record.own); } else if (old) scene.primitives.remove(old); - if (!waiting) retire(record); + if (!waiting || !groundShown) retire(record); // Hidden one by one: a hidden collection would not build them. if (waiting) for (const primitive of waiting) primitive.show = false; record.pending = waiting; @@ -1647,6 +1658,15 @@ export function createCesiumDraw({ * and the lines drawn alone since, hidden in their batches. */ function showPending(record) { + for (const part of record.shapeParts?.values() ?? []) + if ( + part.pendingShow !== undefined && + part.ground && + !part.ground.isDestroyed() + ) { + showOn(part.ground, part.id, part.pendingShow); + part.pendingShow = undefined; + } for (const part of record.lineParts?.values() ?? []) { if (part.batchHidden && part.batch && !part.batch.isDestroyed()) showOn(part.batch, part.id, false); @@ -1862,22 +1882,46 @@ export function createCesiumDraw({ */ function groundFills(record, items) { const batches = []; + // Each clamped item as drawn, for upserts that only show or hide it; + // the set keeps them once every one is built. + const parts = new Map(); + record.shapeParts = null; for (const item of items) { if (item.outline) throw new Error('the Cesium renderer has no clamped outlines yet'); - if (!item.fill || item.outlineOnly) continue; + if (!item.fill || item.outlineOnly) { + parts.set(item.id, { look: lookOf(item), id: null, ground: null }); + continue; + } if (typeof item.fill === 'object' && !Array.isArray(item.fill)) throw new Error('the Cesium renderer fills shapes with colours only'); if (item.extrudeHeight !== undefined) throw new Error('the Cesium renderer cannot clamp extruded shapes'); + // Hidden ones are built too, hidden, so showing them is a change of + // their show, not a rebuild of every fill; a hidden one it cannot + // build stays out, as before, and showing it rebuilds. + let geometry; + try { + geometry = groundGeometry(item); + } catch (error) { + if (item.show === false) continue; + throw error; + } + const part = { + look: lookOf(item), + id: pickId(record, item), + ground: null, + }; + parts.set(item.id, part); const instance = new Cesium.GeometryInstance({ - geometry: groundGeometry(item), + geometry, attributes: { color: Cesium.ColorGeometryInstanceAttribute.fromColor( toColor(item.fill), ), + show: new Cesium.ShowGeometryInstanceAttribute(item.show !== false), }, - id: pickId(record, item), + id: part.id, }); const clampTo = item.clampTo ?? record.spec.clampTo ?? 'both'; const rectangle = instance.geometry.rectangle; @@ -1888,27 +1932,116 @@ export function createCesiumDraw({ batch = { clampTo, instances: [], + parts: [], rectangles: new Cesium.RectangleCollisionChecker(), }; batches.push(batch); } batch.rectangles.insert(String(batch.instances.length), rectangle); batch.instances.push(instance); + batch.parts.push(part); } const pickable = record.spec.pickable !== false; const Ground = pickable ? Cesium.GroundPrimitive : UnpickableGroundPrimitive; - return batches.map( - (batch) => - new Ground({ - geometryInstances: batch.instances, - classificationType: classificationOf(batch.clampTo), - allowPicking: pickable, - }), - ); + const grounds = batches.map((batch) => { + const ground = new Ground({ + geometryInstances: batch.instances, + classificationType: classificationOf(batch.clampTo), + allowPicking: pickable, + }); + for (const part of batch.parts) part.ground = ground; + return ground; + }); + record.shapeParts = parts; + return grounds; } + /** + * How a clamped shape draws, but for whether it shows and its `meta`: a + * copy of its values, so an item changed in place still reads as changed. + */ + const lookOf = (item) => { + const { show, meta, ...look } = item; + return plainCopy(look); + }; + + /** A copy of plain data: arrays and objects copied, the rest kept. */ + function plainCopy(value) { + if (Array.isArray(value) || ArrayBuffer.isView(value)) + return Array.from(value, plainCopy); + if (!value || typeof value !== 'object') return value; + const out = {}; + for (const key of Object.keys(value)) + if (value[key] !== undefined) out[key] = plainCopy(value[key]); + return out; + } + + /** Whether `value` holds what `look` (a `plainCopy`) holds. */ + function sameValues(look, value) { + if (Array.isArray(look)) { + if (!(Array.isArray(value) || ArrayBuffer.isView(value))) return false; + if (look.length !== value.length) return false; + for (let i = 0; i < look.length; i++) + if (!sameValues(look[i], value[i])) return false; + return true; + } + if (look && typeof look === 'object') { + if (!value || typeof value !== 'object' || Array.isArray(value)) + return false; + let count = 0; + for (const key of Object.keys(value)) { + if (value[key] === undefined) continue; + count += 1; + if (!(key in look) || !sameValues(look[key], value[key])) return false; + } + return count === Object.keys(look).length; + } + return look === value || (Number.isNaN(look) && Number.isNaN(value)); + } + + /** Whether `item` draws as the part's item did, but for show and `meta`. */ + function sameLook(part, item) { + const { show, meta, ...look } = item; + return sameValues(part.look, look); + } + + /** + * Upsert clamped shapes in place, without a rebuild, when every item is + * drawn now and looks the same: then only whether it shows and its + * `meta` change. A ground primitive still building takes the show once + * it is ready (`swapReady`). False, changing nothing, otherwise. + */ + function patchShapes(record, list) { + const parts = record.shapeParts; + if (record.kind !== 'shapes' || !parts) return false; + for (const item of list) { + const was = parts.get(item.id); + if (!was || !sameLook(was, item)) return false; + if (was.ground?.isDestroyed()) return false; + } + for (const item of list) { + const was = parts.get(item.id); + if (!was.ground) continue; + was.id.meta = item.meta; + const show = item.show !== false; + if (was.ground.ready) { + showOn(was.ground, was.id, show); + was.pendingShow = undefined; + } else was.pendingShow = show; + } + return true; + } + + /** Whether a hidden clamped item is a plain colour fill `groundFills` builds. */ + const hiddenFillBuilds = (item) => + Boolean(item.fill) && + !item.outlineOnly && + !item.outline && + item.extrudeHeight === undefined && + (typeof item.fill !== 'object' || Array.isArray(item.fill)); + function buildShapes(record) { const host = new Cesium.PrimitiveCollection(); const outlines = new Cesium.PolylineCollection(); @@ -1929,11 +2062,16 @@ export function createCesiumDraw({ return material; }; for (const item of record.items.values()) { - if (item.show === false) continue; - if (item.height === 'clampGround') { + // Clamped ones are built hidden as well (`groundFills`), when they + // are a fill it can draw: others hidden stay out, as before. + if ( + item.height === 'clampGround' && + (item.show !== false || hiddenFillBuilds(item)) + ) { clamped.push(item); continue; } + if (item.show === false) continue; const imageFill = item.fill && typeof item.fill === 'object' && !Array.isArray(item.fill) ? item.fill @@ -2033,7 +2171,15 @@ export function createCesiumDraw({ host.add(outlines); const ground = groundFills(record, clamped); if (!ground.length) return replaceHost(record, host); - replaceHost(record, collect(host, ground), ground, host); + replaceHost( + record, + collect(host, ground), + ground, + host, + clamped.some( + (item) => item.show !== false && item.fill && !item.outlineOnly, + ), + ); } const modelSets = createModelSets({ diff --git a/src/render/cesium/draw.test.mjs b/src/render/cesium/draw.test.mjs index 57d9bc8b6..5b5215159 100644 --- a/src/render/cesium/draw.test.mjs +++ b/src/render/cesium/draw.test.mjs @@ -361,6 +361,219 @@ test('while a rebuild builds, only the old ground waits: the rest goes at once', assert.equal(scene.added.length, 0); }); +test('a clamped fill that only shows, hides or changes meta is changed in place', () => { + const { scene, draw, frame } = drawOver(); + const set = draw.shapes({ id: 'toggles' }); + // Apart, so one ground primitive holds them all. + const rings = new Map( + ['a', 'b', 'c'].map((id, i) => [ + id, + [ + { lon: i, lat: 0 }, + { lon: i + 0.1, lat: 0 }, + { lon: i + 0.1, lat: 0.1 }, + ], + ]), + ); + const fill = (id, show, meta = undefined) => ({ + id, + geometry: { kind: 'polygon', rings: [rings.get(id)] }, + fill: [1, 0, 0, 0.3], + height: 'clampGround', + show, + meta, + }); + set.set([fill('a', true), fill('b', false)]); + const host = scene.added[0]; + const groundOf = (h) => { + for (let i = 0; i < h.length; i++) + if (h.get(i) instanceof Cesium.GroundPrimitive) return h.get(i); + return null; + }; + const ground = groundOf(host); + // A hidden one is built too, hidden. + const instances = ground.geometryInstances; + assert.deepEqual( + instances.map((instance) => [ + instance.id.id, + [...instance.attributes.show.value], + ]), + [ + ['a', [1]], + ['b', [0]], + ], + ); + const shows = new Map( + instances.map((instance) => [ + instance.id, + { show: Uint8Array.from(instance.attributes.show.value) }, + ]), + ); + const byItem = (id) => instances.find((i) => i.id.id === id).id; + ground.getGeometryInstanceAttributes = (id) => shows.get(id); + // Still building: the show waits for the swap. + set.upsert([fill('b', true, { n: 1 })]); + assert.equal(scene.added[0], host, 'not rebuilt'); + assert.deepEqual([...shows.get(byItem('b')).show], [0]); + assert.deepEqual(byItem('b').meta, { n: 1 }, 'meta changed in place'); + Object.defineProperty(ground, 'ready', { value: true }); + frame(); + assert.deepEqual([...shows.get(byItem('b')).show], [1]); + // Ready: written at once. + set.upsert([fill('a', false), fill('b', true, { n: 1 })]); + assert.equal(scene.added[0], host, 'still not rebuilt'); + assert.deepEqual([...shows.get(byItem('a')).show], [0]); + // The same look written out anew is the same look. + set.upsert([ + { + ...fill('a', true), + geometry: { kind: 'polygon', rings: [[...rings.get('a')]] }, + }, + ]); + assert.equal(scene.added[0], host); + assert.deepEqual([...shows.get(byItem('a')).show], [1]); + // An item changed in place is a new look: it rebuilds. + const reused = fill('a', true); + set.upsert([reused]); + assert.equal(scene.added[0], host); + reused.geometry.rings[0][0] = { lon: 0.05, lat: 0 }; + set.upsert([reused]); + assert.notEqual(scene.added.at(-1), host, 'a moved corner rebuilds'); + Object.defineProperty(groundOf(scene.added.at(-1)), 'ready', { + value: true, + }); + frame(); + const moved = scene.added.at(-1); + // Anything else rebuilds: a new colour, a new item. + set.upsert([{ ...fill('a', true), fill: [0, 1, 0, 0.3] }]); + assert.notEqual(scene.added.at(-1), moved, 'a new look rebuilds'); + const rebuilt = scene.added.at(-1); + Object.defineProperty(groundOf(rebuilt), 'ready', { value: true }); + frame(); + set.upsert([fill('c', true)]); + assert.notEqual(scene.added.at(-1), rebuilt, 'a new item rebuilds'); + set.dispose(); + assert.equal(scene.added.length, 0); +}); + +test('hidden clamped fills wait for nothing, and the hidden ones it cannot build stay out', () => { + const { scene, draw, frame } = drawOver(); + const set = draw.shapes({ id: 'hide-all' }); + const fill = (id, lon, show, extra = {}) => ({ + id, + geometry: { + kind: 'ellipse', + center: { lon, lat: 0 }, + semiMajor: 1000, + semiMinor: 1000, + }, + fill: '#fff', + height: 'clampGround', + show, + ...extra, + }); + const groundsIn = (host) => { + const found = []; + for (let i = 0; i < host.length; i++) + if (host.get(i) instanceof Cesium.GroundPrimitive) + found.push(host.get(i)); + return found; + }; + set.set([fill('a', 0, true), fill('b', 1, true)]); + const first = scene.added[0]; + Object.defineProperty(groundsIn(first)[0], 'ready', { value: true }); + frame(); + // Everything hidden: nothing to wait for, the old fills go at once. + set.set([fill('a', 0, false), fill('b', 1, false)]); + assert.equal(scene.added.length, 1, 'the old host is gone'); + assert.notEqual(scene.added[0], first); + // Hidden ones it could not draw shown are left out, as before. + assert.doesNotThrow(() => + set.set([ + fill('a', 0, false, { outline: '#000' }), + fill('b', 1, false, { extrudeHeight: 10 }), + fill('c', 2, false, { fill: { preset: 'radialRim' } }), + fill('d', 3, false, { + geometry: { + kind: 'ellipse', + center: { lon: 3, lat: 0 }, + semiMajor: { byCameraHeight: { factor: 1, min: 1, max: 2 } }, + semiMinor: 1000, + }, + }), + ]), + ); + assert.equal(groundsIn(scene.added.at(-1)).length, 0); + set.dispose(); + assert.equal(scene.added.length, 0); +}); + +test('a show patched while a rebuild waits lands on the new fills, the old ones keep drawing', () => { + const { scene, draw, frame } = drawOver(); + const set = draw.shapes({ id: 'patch-pending' }); + const fill = (id, lon, show, color = '#fff') => ({ + id, + geometry: { + kind: 'ellipse', + center: { lon, lat: 0 }, + semiMajor: 1000, + semiMinor: 1000, + }, + fill: color, + height: 'clampGround', + show, + }); + const groundOf = (host) => { + for (let i = 0; i < host.length; i++) + if (host.get(i) instanceof Cesium.GroundPrimitive) return host.get(i); + return null; + }; + set.set([fill('a', 0, true), fill('b', 1, true)]); + const first = scene.added[0]; + Object.defineProperty(groundOf(first), 'ready', { value: true }); + frame(); + // A new colour rebuilds; the old fills draw until the new ones are ready. + set.set([fill('a', 0, true, '#f00'), fill('b', 1, true, '#f00')]); + const second = scene.added.at(-1); + assert.equal(scene.added.length, 2, 'the old host waits'); + const ground = groundOf(second); + const shows = new Map( + ground.geometryInstances.map((instance) => [ + instance.id, + { show: Uint8Array.from(instance.attributes.show.value) }, + ]), + ); + ground.getGeometryInstanceAttributes = (id) => shows.get(id); + const idOf = (item) => + ground.geometryInstances.find((i) => i.id.id === item).id; + set.upsert([fill('b', 1, false, '#f00')]); + set.upsert([fill('b', 1, true, '#f00')]); + set.upsert([fill('a', 0, false, '#f00')]); + assert.equal(scene.added.at(-1), second, 'patched, not rebuilt'); + assert.deepEqual([...shows.get(idOf('a')).show], [1], 'queued until ready'); + Object.defineProperty(ground, 'ready', { value: true }); + frame(); + assert.equal(scene.added.length, 1, 'swapped'); + assert.deepEqual([...shows.get(idOf('a')).show], [0]); + assert.deepEqual([...shows.get(idOf('b')).show], [1], 'the last write wins'); + // A rebuild after a patch builds the patched show. + set.upsert([fill('c', 2, true, '#f00')]); + const third = groundOf(scene.added.at(-1)); + assert.deepEqual( + third.geometryInstances.map((instance) => [ + instance.id.id, + [...instance.attributes.show.value], + ]), + [ + ['a', [0]], + ['b', [1]], + ['c', [1]], + ], + ); + set.dispose(); + assert.equal(scene.added.length, 0); +}); + test('clamped shapes refuse what they cannot draw', () => { const { draw } = drawOver(); const set = draw.shapes({ id: 'refuse' });