/** * @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 (icon * sets, unclamped points restyled or moved, and models, change in place; * `drawModels.js`). Every * item carries a pick id `{set, id, meta}`, which the query port * (`ports.js`) reads picks back through. * * Clamped items follow the ground as Cesium's own entities do: a clamped * point is a billboard of a drawn dot, a draped line a ground polyline, a * clamped fill a ground primitive (packed so no two fills in one overlap, * so overlapping translucent fills blend as they did). A rebuilt set keeps * drawing its last ground primitives until the new ones are ready, so a * refresh never blinks. `horizonCull` hides a set's points and icons past * the ellipsoid's horizon, each frame before it draws, tested at the * position each was given (not where clamping put it). The ground fills and * draped lines of a set made with `pickable: false` stay out of the pick * pass, so they never hide the ground geometry drawn under them from picks. * * Solid lines in space start in a polyline collection, which costs every * line every frame; once a set's lines stop changing for a few frames they * settle into static batches that cost nothing until they change, and a * line that moves again goes back to the collection (`settleLines`). * * Icon sets whose items move, glide, recede, pick by proxy or switch images * by size, or that take columns, draw on the GPU instead (`gpuIcons.js`). * * Built over a scene by `createCesiumPorts`, and on its own over a Cesium * viewer with no renderer bound, when code first asks * `findDraw` for one (`rendererOf.js`). */ import * as Cesium from 'cesium'; import { temeToPseudoFixed } from '../../geo/celestial.js'; import { alongLength } from '../../geo/polyline.js'; import { clusterScreenPoints } from '../../geo/screenCluster.js'; import { provideUnboundDraw } from '../rendererOf.js'; import { blobUrl, blobUrlFrameDrawn, listenerList, toCartesian, uncaught, } from './common.js'; import { createGpuIcons, GPU_ICON_CAPABILITIES } from './gpuIcons.js'; import { blendHost } from './setBlend.js'; import { createModelSets } from './drawModels.js'; import { materialTexture } from './internals.js'; import { createMeshSets } from './drawMeshes.js'; import { createQuadSets } from './drawQuads.js'; import { createCesiumFields } from './drawFields.js'; /** The contract's colour as Cesium's. */ export function toColor(color, alpha = 1) { if (color === undefined || color === null) return Cesium.Color.WHITE.withAlpha(alpha); const c = typeof color === 'string' ? Cesium.Color.fromCssColorString(color) : new Cesium.Color(color[0], color[1], color[2], color[3] ?? 1); return c.withAlpha(c.alpha * alpha); } /** * An image reference as something a billboard or material takes: a URL, an * SVG as a data URL, a blob as its object URL, or the canvas itself. An * atlas slot is read through the draw port's atlases first * (`createCesiumDraw`'s `imageAt`). */ export function toImage(image) { if (typeof image === 'string') return image; if (image?.svg) return `data:image/svg+xml;charset=utf-8,${encodeURIComponent(image.svg)}`; if (image?.blob) return blobUrl(image.blob); if (image?.canvas) return image.canvas; if (typeof image?.atlas === 'string') throw new TypeError( `atlas ${image.atlas} has no slot ${image.slot} registered`, ); throw new TypeError('an image is a URL, SVG, blob, canvas or atlas slot'); } /** Cesium's height reference for an item's `height` and `clampTo`. */ export function heightReferenceOf(height, clampTo = 'both') { const H = Cesium.HeightReference; if (height === 'clampGround') return ( { terrain: H.CLAMP_TO_TERRAIN, tiles: H.CLAMP_TO_3D_TILE }[clampTo] ?? H.CLAMP_TO_GROUND ); if (height === 'relativeGround') return ( { terrain: H.RELATIVE_TO_TERRAIN, tiles: H.RELATIVE_TO_3D_TILE }[ clampTo ] ?? H.RELATIVE_TO_GROUND ); return H.NONE; } /** Cesium's classification for what clamped lines and fills drape onto. */ const classificationOf = (clampTo = 'both') => ({ terrain: Cesium.ClassificationType.TERRAIN, tiles: Cesium.ClassificationType.CESIUM_3D_TILE, })[clampTo] ?? Cesium.ClassificationType.BOTH; /** * A distance curve as Cesium's, or undefined. Cesium's curves hold the same * end values but ease between them (not linearly, as the contract's do): * points and icons draw them as Cesium's own entities always have. A curve * whose far end is not past its near one is left out. */ const nearFarOf = (curve) => // One that ends where it starts is no curve, which Cesium refuses. curve && curve.far > curve.near ? new Cesium.NearFarScalar( curve.near, curve.nearValue, curve.far, curve.farValue, ) : undefined; /** Whether a `displayRange` shows anything: `[near, far)` is not empty. */ const displayable = (range) => !range || range[1] > range[0]; /** * A `displayRange` as Cesium's, or undefined for none (or an empty one). * Cesium still shows an item at exactly its far distance. */ const displayConditionOf = (range) => range && displayable(range) ? new Cesium.DistanceDisplayCondition(range[0], range[1]) : undefined; /** * `columns` on a set drawn from items: column `i` is row `ids[i]`, the item * of that id the set holds with the columns' fields over it (`pos`, * `course`, `show`, `scale`, `alpha`, `color` as 0..1, `meta`). Rows not * named are gone, as `set` replaces every item. * @param {import('../contract/draw').Columns} columns * @param {Map} items */ export function columnRows(columns, items) { const { positions: p, courses, shown, scales, alphas, colors, meta, } = columns; return columns.ids.map((id, i) => { const key = String(id); const row = { ...(items.get(key) ?? { id: key }) }; if (p) row.pos = { x: p[i * 3], y: p[i * 3 + 1], z: p[i * 3 + 2] }; if (courses) row.course = courses[i]; if (shown) row.show = shown[i] !== 0; if (scales) row.scale = scales[i]; if (alphas) row.alpha = alphas[i]; if (colors) row.color = [0, 1, 2, 3].map((k) => colors[i * 4 + k] / 255); if (meta) row.meta = meta[i]; return row; }); } /** * Cesium's point blending for a set's `blend`: additive ones are built * translucent, a command a set, and added where they draw (`setBlend.js`). */ const pointBlendOf = (blend) => ({ opaque: Cesium.BlendOption.OPAQUE, translucent: Cesium.BlendOption.TRANSLUCENT, additive: Cesium.BlendOption.TRANSLUCENT, })[blend] ?? Cesium.BlendOption.OPAQUE_AND_TRANSLUCENT; /** * Ground fills of a set that never takes part in picks (`pickable: false`). * `allowPicking: false` drops their ids, but a ground primitive still draws * its stencil in the pick pass, which would erase picks of ground geometry * under it; these skip the pick pass altogether. */ class UnpickableGroundPrimitive extends Cesium.GroundPrimitive { update(frameState) { if (!frameState.passes.pick) super.update(frameState); } } /** * 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. */ /** * A static batch of lines (`settleLines`): a build that fails keeps its * error and draws nothing, where a primitive would throw it every frame. */ class StaticLines extends Cesium.Primitive { update(frameState) { if (this.failed) return; try { super.update(frameState); } catch (error) { this.failed = error; } } } const MAX_SPARE_IMAGES = 64; const ANCHORS = { center: Cesium.VerticalOrigin.CENTER, bottom: Cesium.VerticalOrigin.BOTTOM, top: Cesium.VerticalOrigin.TOP, }; /** The longest straight step of a geodesic line, metres: a degree of arc. */ const GEODESIC_STEP_M = Cesium.Ellipsoid.WGS84.maximumRadius * Cesium.Math.RADIANS_PER_DEGREE; /** The fewest straight steps a geodesic line is drawn in. */ const GEODESIC_LINE_STEPS = 64; /** The `flow` line material's type. */ const FLOW_MATERIAL = 'DrawFlowLine'; /** * Along the line (`st.s`, 0 at its start, 1 at its end) the pattern repeats * `repeat` times, each cell lit for its first `duty`, scrolled toward the * end by `time * speed` cells; between the dashes the line stays faintly * drawn, and the lit cells glow. */ const FLOW_SOURCE = ` czm_material czm_getMaterial(czm_materialInput materialInput) { czm_material m = czm_getDefaultMaterial(materialInput); float s = materialInput.st.s; float flow = fract(s * repeat - time * speed); float on = smoothstep(duty + 0.08, duty - 0.08, flow); float a = max(on, 0.18); m.diffuse = color.rgb; m.emission = color.rgb * on * 0.9; m.alpha = color.a * a; return m; }`; /** * How finely a clamped ellipse with an image fill is cut, radians, so an * image's round edge (a zone's rim) runs round. */ const IMAGE_ELLIPSE_GRANULARITY = Cesium.Math.toRadians(0.08); /** * An image fill's material. The image carries its own alpha, so it draws in * the translucent pass whatever its colour, as the entities' image * materials did. */ function imageMaterial(image, repeat = [1, 1]) { // Typed first and given its uniforms after, as `Material.fromType` does: // the image loads when first drawn, not here. const material = new Cesium.Material({ fabric: { type: 'Image' }, translucent: true, }); material.uniforms.image = image; material.uniforms.repeat = new Cesium.Cartesian2(...repeat); return material; } /** * A shape's `animate`, checked: the Cesium renderer pulses alpha, forever. * Null for a shape that does not pulse. */ function pulseOf(item) { const pulse = item.animate; if (!pulse) return null; if (pulse.property !== 'alpha' || pulse.repeat !== undefined) throw new Error('the Cesium renderer pulses alpha only, forever'); if ( !Number.isFinite(pulse.from) || !Number.isFinite(pulse.to) || !(pulse.periodMs > 0 && Number.isFinite(pulse.periodMs)) ) throw new Error( 'the Cesium renderer pulses between finite alphas, over a positive period', ); return pulse; } /** * A pulse's alpha now: a sine between `from` and `to` on the wall clock, * `periodMs` a swing and back, at their middle at each whole period. * @param {{from: number, to: number, periodMs: number}} pulse * @param {number} now */ export function pulseAlpha(pulse, now) { const turn = pulse.periodMs > 0 ? (2 * Math.PI * now) / pulse.periodMs : 0; return pulse.from + (pulse.to - pulse.from) * (0.5 + 0.5 * Math.sin(turn)); } /** * How much of a set's motion clock passes before its draped lines in the * sky's frame are draped again where the sky has turned to (the Earth turns * about 465 m at the equator in a second). */ export const DRAPED_INERTIAL_STEP_MS = 1000; /** The line styles the port drapes. */ const DRAPED_STYLES = new Set([ 'solid', 'glow', 'dash', 'flow', 'arrow', 'pattern', ]); // Whether Cesium's approximate terrain heights have been asked for. let terrainHeightsAsked = false; /** * Whether a ground polyline can be built in the frame it is made: Cesium * needs its approximate terrain heights loaded for that. The first time * one is wanted they are asked for (as Cesium's entities ask, which then * build those lines the same way); until they load, false. */ function groundSyncs() { if (Cesium.ApproximateTerrainHeights.initialized) return true; if (!terrainHeightsAsked) { terrainHeightsAsked = true; try { Cesium.GroundPolylinePrimitive.initializeTerrainHeights().catch(() => {}); } catch { // Nowhere to load them from: such lines are rebuilt as before. } } return false; } /** The prefix of a revealed line's material types, one per style kind. */ const REVEAL_MATERIAL = 'DrawRevealLine'; /** * A line drawn only up to `reveal` along its texture (`st.s`, 0 at its * start, 1 at its end), in its own style past that: the rest is discarded, * so it neither draws nor picks. */ const REVEAL_SOURCE = ` czm_material czm_getMaterial(czm_materialInput materialInput) { if (materialInput.st.s > reveal) discard; return revealed; }`; /** * Where along a drawn line's texture its first `fraction` of length ends, * for the reveal material. A ground polyline's texture runs along its * length; a polyline's runs evenly per vertex, so `positions` (as drawn) * map the length onto it. Nothing past 0, everything from 1. * @param {number} fraction * @param {Array<{x: number, y: number, z: number}>} [positions] */ export function revealUniform(fraction, positions) { if (!(fraction > 0)) return -1; if (fraction >= 1) return 2; if (!positions) return fraction; // As a polyline draws them: neighbours at one place are one vertex. positions = Cesium.arrayRemoveDuplicates( positions, Cesium.Cartesian3.equalsEpsilon, ); const at = alongLength(positions, fraction); return at ? (at.index + at.t) / (positions.length - 1) : 2; } /** * The `flow` lines' clock, seconds, for a line flowing at `speed` cells a * second: wrapped to one cell's time, which draws the same dashes, so the * single-precision uniform never runs out of digits over a long session. */ function flowTime(speed) { if (!speed) return 0; const cells = (performance.now() / 1000) * speed; return (cells - Math.floor(cells)) / speed; } /** * Drawn frames a line set's lines stay unchanged before the solid ones * among them settle into a static batch (`settleLines`). */ export const SETTLE_FRAMES = 30; /** * Fewer lines than this left in the collection beside a static batch wait * `LONG_SETTLE_FRAMES` to settle, as rebuilding the batch for them costs * more than drawing them in the collection for a while. */ export const FEW_LOOSE_LINES = 64; export const LONG_SETTLE_FRAMES = 300; /** * Clamped fills a set draws alone at most, each where it last moved * (`moveShape`): an upsert that would draw more alone rebuilds the set's * batches instead, as each costs a primitive and is built in the frame. */ export const MOVING_SHAPES = 16; /** What `syncIcons` did: icons added or removed, or only changed in place. */ const ICONS_CHANGED = 'changed'; const ICONS_KEPT = 'kept'; /** What `patchPoints` did: points added too, or only changed in place. */ const POINTS_ADDED = 'added'; const POINTS_KEPT = 'kept'; /** * The draw port over `scene`, and what the other ports read of it: the live * sets by id, a version that changes with what height queries see through * in them, the scene's 3D tilesets and * the clamp-state watch the frame loop runs after each draw. * @param {{scene: object, report: (error: unknown) => void, * capabilities?: ReadonlySet, * requestRender?: (reason: string) => void}} options `capabilities` gate * the GPU icon sets' members (by default they all are); `requestRender`, * the frame port's, asks for the frames a GPU icon set needs on its own * (its images packed), under the reason `icons:` (by default the * scene's, with no reason). */ export function createCesiumDraw({ scene, report, capabilities = new Set(GPU_ICON_CAPABILITIES), requestRender: requestFrame = null, }) { const sets = new Map(); // Fields share the sets' ids. const fieldPart = createCesiumFields({ scene, report, resolveImage: (ref) => typeof ref?.atlas === 'string' ? (atlases.get(ref.atlas)?.[ref.slot] ?? ref) : ref, }); 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). let setsVersion = 0; // A viewer can be destroyed before the layers drawing on it // let their sets go; those calls then have nothing left to do. const live = () => !scene.isDestroyed?.(); const requestRender = () => { if (live()) scene.requestRender(); }; function makeSet(kind, spec, build) { if (sets.has(spec.id) || fieldPart.has(spec.id)) throw new Error(`a set with id ${spec.id} is live`); const items = new Map(); const listeners = { ready: listenerList(report), loadFailed: listenerList(report), }; const record = { kind, spec, 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, pending: null, // The host's ground primitives, and the collection beside them. ground: null, own: null, // Each point or icon at its position, for the horizon cull. placed: [], }; // Each build records its items' pick ids, for height queries to see // through. const rebuild = () => { record.pickIds = []; record.placed = []; record.patchable = null; record.pointHost = null; // The lines as the host this build replaces draws them. record.drawnParts = record.lineParts; record.lineParts = null; build(record); setsVersion += 1; }; record.rebuild = rebuild; // Changed in place: what height queries see through may have changed. const patched = () => { setsVersion += 1; requestRender(); }; // Icons changed in place: height queries see through the sets' pick // ids, which an icon keeps, so only icons added or gone change them. const iconsPatched = (synced) => { if (synced === ICONS_CHANGED) setsVersion += 1; requestRender(); }; // A shape's pulse the renderer cannot run is refused before anything // changes. const checkPulses = (list) => { if (kind !== 'shapes') return; for (const item of list) pulseOf(item); if (list.some((item) => item.animate)) record.mayPulse = true; }; const handle = { id: spec.id, set(list) { checkPulses(list); if (onGpu(record, list, true)) { items.clear(); for (const item of list) items.set(item.id, item); record.gpu.sync(); return patched(); } items.clear(); for (const item of list) items.set(item.id, item); // Icons are changed where they are, when they can be. const synced = syncIcons(record, items.keys(), true); if (synced) return iconsPatched(synced); rebuild(); requestRender(); }, upsert(list) { checkPulses(list); if (onGpu(record, list)) { for (const item of list) items.set(item.id, item); record.gpu.write(list); return patched(); } // Points restyled, moved or added keep the pick ids they had, so // only points added change what height queries see through. const points = patchPoints(record, list); if (points) { for (const item of list) items.set(item.id, item); if (points === POINTS_ADDED) setsVersion += 1; requestRender(); return; } // Lines that only change how they show or where an undraped one // runs, and clamped shapes that only show or hide, or a few colour // fills that only move (`moveShape`), are changed where they are. if ( patchLines(record, list) || patchShapes(record, list) || (kind === 'models' && modelSets.upsert(record, list)) || (kind === 'quads' && quadSets.upsert(record, list)) || (kind === 'meshes' && meshSets.upsert(record, list)) ) { for (const item of list) items.set(item.id, item); if (kind === 'lines') noteFlows(record); setsVersion += 1; requestRender(); return; } for (const item of list) items.set(item.id, item); const synced = syncIcons( record, list.map((item) => item.id), ); if (synced) return iconsPatched(synced); rebuild(); requestRender(); }, remove(ids) { for (const id of ids) items.delete(id); if (removePoints(record, ids)) return patched(); if (record.gpu) { record.gpu.drop(ids); return patched(); } const synced = syncIcons(record, []); if (synced) return iconsPatched(synced); rebuild(); requestRender(); }, clear() { items.clear(); if (record.gpu) { record.gpu.sync(); return patched(); } const synced = syncIcons(record, []); if (synced) return iconsPatched(synced); rebuild(); requestRender(); }, setOptions(options) { // Refused, changing nothing, where icons on the GPU cannot take it. if (record.gpu) gpu.check([], { ...spec, ...options }); const culled = spec.horizonCull; 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 // points and icons build in the blend (every set's commands are // turned to it each frame, `setBlend.js`), and only shapes and lines have ground // primitives: other kinds are not rebuilt for those (models would // load again). if ( (kind !== 'models' && spec.clampTo !== clampTo) || ((kind === 'points' || kind === 'icons') && spec.blend !== blend) || ((kind === 'shapes' || kind === 'lines' || kind === 'quads' || kind === 'meshes') && (spec.pickable !== false) !== pickable) ) rebuild(); // A set that stops picking lets its old ground go now: still drawn // while the new builds, it would keep hiding the ground from picks. if (pickable && spec.pickable === false) retire(record); record.gpu?.restyle(); if (kind === 'models') modelSets.restyle(record); setsVersion += 1; 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, get show() { return spec.show !== false; }, set show(value) { spec.show = value; showHosts(record); requestRender(); }, on(event, cb) { return listeners[event]?.on(cb) ?? (() => {}); }, dispose() { if (record.host && !record.host.isDestroyed?.() && live()) scene.primitives.remove(record.host); record.host = null; retire(record); // A newer set under the same id is not this handle's to remove. if (sets.get(spec.id) === record) sets.delete(spec.id); setsVersion += 1; requestRender(); }, }; // `columns`: column updates of an icon set, on the GPU. if (kind === 'icons' && capabilities.has('columns')) handle.setColumns = (columns) => { onGpu(record, [], false, true); record.gpu.columns(columns); patched(); }; // Any other set takes columns as the rows they make, replacing its items. else if (capabilities.has('columns')) handle.setColumns = (columns) => handle.set(columnRows(columns, items)); // A clustered set clusters again in the next frame drawn after a change // (`setColumns` too: set before this, so it is wrapped with the rest). 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); }; } const dispose = handle.dispose; handle.dispose = () => { dropClusters(record); dispose(); }; // Draped lines in the sky's frame are draped where the sky is: held as // given, drawn turned into the fixed frame, and draped again each // `DRAPED_INERTIAL_STEP_MS` of their motion clock (`beforeRender`). if (kind === 'lines') { const { set, upsert, remove, clear } = handle; record.inertialDraped = new Map(); const fixedNow = (list) => { const ms = motionMs(record); let axes = null; const given = new Map(); const drawn = list.map((item) => { if (item.frame !== 'inertial' || item.mode !== 'draped') return item; given.set(item.id, item); axes ??= temeToPseudoFixed(ms); return fixedLine(item, axes); }); return { drawn, given, ms }; }; const keep = (list, given, ms) => { for (const item of list) record.inertialDraped.delete(item.id); for (const [id, item] of given) record.inertialDraped.set(id, item); if (given.size) record.inertialTurnMs = ms; }; handle.set = (list) => { const { drawn, given, ms } = fixedNow(list); const result = set(drawn); record.inertialDraped.clear(); keep(list, given, ms); return result; }; handle.upsert = (list) => { const { drawn, given, ms } = fixedNow(list); const result = upsert(drawn); keep(list, given, ms); return result; }; handle.remove = (ids) => { const result = remove(ids); for (const id of ids) record.inertialDraped.delete(id); return result; }; handle.clear = () => { const result = clear(); record.inertialDraped.clear(); return result; }; record.drapeInertial = () => { if (!record.inertialDraped.size) return; const ms = motionMs(record); if (Math.abs(ms - record.inertialTurnMs) < DRAPED_INERTIAL_STEP_MS) return; handle.upsert([...record.inertialDraped.values()]); }; } sets.set(spec.id, record); setsVersion += 1; return handle; } const gpu = createGpuIcons({ scene, capabilities, toColor, imageOf: (record, image) => iconImage(record, image), peekImage: (image) => atlases.get(image.atlas)?.[image.slot], requestRender: (reason) => { if (!live()) return; if (requestFrame) requestFrame(reason); else scene.requestRender(); }, }); /** * Whether an icon set draws `list` on the GPU: it already does, or the * items (or `force`, for columns) need it to, when its billboards give way * to a GPU host in their place. Refuses, changing nothing, what the GPU * cannot draw: of `list`, and, unless `replacing` them, of the items the * set already holds. */ function onGpu(record, list, replacing = false, force = false) { if (record.kind !== 'icons') return false; if (!record.gpu && !force && !gpu.wants(list)) return false; gpu.check(list, record.spec); if (record.gpu) return true; if (!replacing) gpu.check(record.items.values(), record.spec); record.gpu = gpu.attach(record); record.billboards = null; record.billboardHost = null; record.placed = []; // Icons on the GPU stay out of offscreen passes: height queries never // see them, so there is nothing to see through. record.pickIds = []; replaceHost(record, record.gpu.host); return true; } function pickId(record, item) { const id = { set: record.spec.id, id: item.id, meta: item.meta, }; record.pickIds.push(id); return id; } /** * Draw `host` for the set in place of what it drew. With `ground` (its * 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. 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, 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 // where it drew, so stacking (and picks among overlapping items) does // not change with each update. Its place is under whatever was above // the host it replaces (indices shift as older hosts go). const slot = old ? slotOf(old) : -1; const above = slot >= 0 && slot + 1 < scene.primitives.length ? scene.primitives.get(slot + 1) : null; // Named for code that finds a set's host among the scene's primitives // (`uploadProbe.js`). host.drawSetId = record.spec.id; // `blend`: its commands turned to the set's blend each frame drawn. blendSetHost(record, host); // Only old ground primitives wait for the new ones: the rest of the old // host goes now, as the new host's own parts draw at once. if ( old && waiting && groundShown && !record.retiring && !record.pending && record.ground ) { record.retiring = old; if (record.own) old.remove(record.own); } else if (old) { scene.primitives.remove(old); // Shapes drawn alone in the host that goes show again where the host // still retiring draws them, until the new one is ready. showRetiringShapes(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; record.ground = waiting; record.own = waiting ? own : null; record.host = host; const at = above ? slotOf(above) : -1; 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(); } /** A set's host drawn in the set's `blend`, as it is each frame. */ function blendSetHost(record, host) { blendHost(host, () => record.spec.blend ?? undefined); } /** * `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; * 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. */ function slotOf(primitive) { const primitives = scene.primitives; const n = primitives?.length ?? 0; for (let i = 0; i < n; i++) if (primitives.get(i) === primitive) return i; return -1; } function showHosts(record) { const show = record.spec.show !== false; if (record.host) record.host.show = show; if (record.retiring) record.retiring.show = show; } function retire(record) { if (record.retiring && !record.retiring.isDestroyed?.() && live()) scene.primitives.remove(record.retiring); record.retiring = null; record.retiringFlows = null; record.retiringParts = null; record.retiringShapeParts = null; record.retiringHiddenShapes = null; } /** * After a draw: a set whose ground primitives are all ready shows them, * and lets go of what drew in their place. */ function swapReady() { for (const record of sets.values()) { const ground = record.pending; if (!ground || ground.some((p) => !p.isDestroyed() && !p.ready)) continue; showPending(record); for (const primitive of ground) primitive.show = true; record.pending = null; retire(record); requestRender(); } } // The horizon cull: a point or icon past the ellipsoid's horizon from the // eye is hidden, as layers drawn without depth test used to do themselves. let occluder = null; function cullHorizon() { cullOverlayLines(); for (const record of sets.values()) { if (!record.spec.horizonCull || !record.placed.length) continue; const horizon = horizonNow(); if (!horizon) return; for (const placed of record.placed) { const show = placed.shown && !placed.clustered && horizon.isPointVisible(placed.position); if (placed.primitive.show !== show) placed.primitive.show = show; } } } /** * Draped lines drawn over the surface (where the scene cannot drape) show * while any of their ends or middle is this side of the horizon. */ function cullOverlayLines() { let horizon; for (const record of sets.values()) { if (!record.overlayLines?.length) continue; horizon ??= horizonNow(); for (const line of record.overlayLines) { // With no horizon (2D) every line shows as it was asked to. const show = line.shown && (!horizon || line.ends.some((p) => horizon.isPointVisible(p))); if (line.part.deep && line.part.deep.show !== show) line.part.deep.show = show; } } } // --- Clusters (`cluster`) -------------------------------------------------- /** The default cluster badge: the count on a disc. */ const clusterBadge = (count) => ({ svg: `${count}`, }); /** Whether an icon set clusters now. */ const clusters = (record) => record.kind === 'icons' && Boolean(record.spec.cluster) && capabilities.has('cluster'); /** Let go of a set's cluster icons, and show its members again. */ function dropClusters(record) { const host = record.clusterHost; if (host && !host.isDestroyed() && live()) scene.primitives.remove(host); record.clusterHost = null; 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(); /** * Each frame, before it draws: every clustered icon set clusters its * 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(frameState = scene.frameState) { let pose; const poseNow = () => { const eye = scene.camera?.positionWC; const dir = scene.camera?.directionWC; return `${eye?.x},${eye?.y},${eye?.z},${dir?.x},${dir?.y},${dir?.z},${scene.canvas?.clientWidth},${scene.canvas?.clientHeight}`; }; for (const record of sets.values()) { if (!clusters(record)) { if (record.clusterHost || record.clusterState) { dropClusters(record); for (const placed of record.placed) placed.primitive.show = shownNow(record, placed); } continue; } // 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 = host; } pose ??= poseNow(); // 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 = key; reclusterIcons(record, frameState); } } /** 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 = record.gpu ? gpuClusterPoints(record, frameState, horizon) : []; const entries = new Map(); for (const [id, entry] of record.gpu ? [] : record.billboards) { const item = record.items.get(id); const placed = entry.placed; if (!item || !placed.shown) continue; if (horizon && !horizon.isPointVisible(placed.position)) continue; const screen = Cesium.SceneTransforms.worldToWindowCoordinates( scene, placed.position, clusterScratch, ); if (!screen) continue; points.push({ id, position: placed.position, screen: { x: screen.x, y: screen.y }, pixelSize: Math.max(item.size[0], item.size[1]) * (item.scale ?? 1), }); entries.set(id, entry); } const result = clusterScreenPoints({ points, pixelRange: spec.pixelRange, minimumClusterSize: spec.minimumSize, viewHeight: scene.canvas?.clientHeight ?? 0, eyeHeight: scene.camera.positionCartographic?.height ?? 0, previous: record.clusterState, project: (position) => { const p = Cesium.SceneTransforms.worldToWindowCoordinates( scene, toCartesian(position), new Cesium.Cartesian2(), ); return p ? { x: p.x, y: p.y } : null; }, isOccluded: (position) => horizon ? !horizon.isPointVisible(toCartesian(position)) : false, }); 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); if (entry) entry.placed.clustered = true; } for (const placed of record.placed) { const show = shownNow(record, placed); if (placed.primitive.show !== show) placed.primitive.show = show; } let host = record.clusterHost; if (!host || host.isDestroyed()) { host = new Cesium.BillboardCollection({ scene, blendOption: pointBlendOf(record.spec.blend), }); record.clusterHost = host; blendSetHost(record, host); scene.primitives.add(host); } host.removeAll(); host.show = record.spec.show !== false; for (const cluster of result.clusters) { const seed = record.items.get(cluster.ids[0]); const position = toCartesian(cluster.position); const given = spec.icon?.(cluster.ids.length); const image = given === undefined ? clusterBadge(cluster.ids.length) : typeof given?.atlas === 'string' ? atlases.get(given.atlas)?.[given.slot] : given; if (image === undefined) continue; const scale = seed.scale ?? 1; const billboard = host.add({ position, width: seed.size[0] * scale, height: seed.size[1] * scale, disableDepthTestDistance: seed.disableDepthTest ?? 0, id: { set: record.spec.id, id: cluster.ids[0], get meta() { return record.items.get(cluster.ids[0])?.meta; }, cluster: { ids: cluster.ids.slice(), position: { x: position.x, y: position.y, z: position.z }, }, }, }); if (isKeyed(image)) billboard.setImage(image.key, image.canvas); else billboard.image = toImage(image); } } /** The horizon from the eye as it is now; null where there is none (2D). */ function horizonNow() { const eye = scene.camera?.positionWC; // The eye is ECEF in 3D only. if ( !eye || (scene.mode ?? Cesium.SceneMode.SCENE3D) !== Cesium.SceneMode.SCENE3D ) return null; occluder ??= new Cesium.EllipsoidalOccluder( scene.globe?.ellipsoid ?? Cesium.Ellipsoid.WGS84, eye, ); occluder.cameraPosition = eye; return occluder; } /** * Whether a point or icon updated in place shows now: past the horizon * of a culled set it stays hidden, even when the update comes after this * frame's cull (a frame listener that moves its items). */ function shownNow(record, placed) { if (!placed.shown || placed.clustered) return false; if (!record.spec.horizonCull) return placed.shown; return horizonNow()?.isPointVisible(placed.position) ?? true; } /** Each frame, before it draws: the flow lines' clock. */ function runFlows() { for (const record of sets.values()) { for (const material of record.flowMaterials ?? []) material.uniforms.time = flowTime(material.uniforms.speed); for (const material of record.retiringFlows ?? []) material.uniforms.time = flowTime(material.uniforms.speed); } } /** Whether a shown set shows flow lines, which draw on in later frames. */ const flowing = () => [...sets.values()].some( (record) => record.spec.show !== false && record.flowShown, ); /** Note whether a line set shows any flow line, once its lines change. */ function noteFlows(record) { record.flowShown = false; if (!record.flowMaterials?.length) return; for (const item of record.items.values()) if (item.style?.kind === 'flow' && item.show !== false) { record.flowShown = true; return; } } function uncull(record) { for (const placed of record.placed) placed.primitive.show = placed.shown; } /** Remember a drawn point or icon for the horizon cull. */ function place(record, primitive, position, shown) { const placed = { primitive, position, shown }; record.placed.push(placed); return placed; } // Atlases icons name images from, by id: `{atlas, slot}` reads the slot // when its icon is drawn, and registering an atlas again swaps the images // of the icons that drew from it. const atlases = new Map(); /** * An icon's image: an atlas slot read through its atlas, or undefined * while its atlas or slot is not registered (it draws once it is). */ function iconImage(record, image) { if (typeof image?.atlas !== 'string') return image; record.atlases.add(image.atlas); return atlases.get(image.atlas)?.[image.slot]; } /** * What a line pattern, a shape's fill or a quad draws: `toImage` of the * image, an atlas slot as the slot holds it when it is drawn (one not * registered is refused, as an image it cannot read). */ function imageAt(image) { return toImage( typeof image?.atlas === 'string' ? (atlases.get(image.atlas)?.[image.slot] ?? image) : image, ); } function buildIcons(record) { // A GPU host keeps drawing: what a rebuild changes, it reads live. if (record.gpu) return; const host = new Cesium.BillboardCollection({ scene, 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) 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?.blob ?? 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), // Focus emphasis as the GPU icons draw it: a fade, at most to none. color: toColor( item.color, (item.alpha ?? 1) * Math.min(1, Math.max(0, item.focus ?? 1)), ), verticalOrigin: ANCHORS[item.anchor ?? 'center'], disableDepthTestDistance: item.disableDepthTest ?? 0, heightReference: heightReferenceOf(item.height, record.spec.clampTo), // An empty range shows it nowhere. show: item.show !== false && displayable(item.displayRange), scaleByDistance: nearFarOf(item.scaleByDistance), translucencyByDistance: nearFarOf(item.fadeByDistance), distanceDisplayCondition: displayConditionOf(item.displayRange), // The defaults, so a restyle in place puts back what an item dropped. rotation: 0, alignedAxis: Cesium.Cartesian3.ZERO, // CSS pixels, y down, as the billboard takes them. pixelOffset: new Cesium.Cartesian2( item.pixelOffset?.x ?? 0, item.pixelOffset?.y ?? 0, ), }; if (item.rotationMode === 'screen') look.rotation = item.rotation ?? 0; // Its up turned along the axis on screen, as Cesium's own aligned // billboards stand; an axis of zero length stands upright. if (item.rotationMode === 'axis' && item.alignedAxis) { const { x = 0, y = 0, z = 0 } = item.alignedAxis; const axis = new Cesium.Cartesian3(x, y, z); const length = Cesium.Cartesian3.magnitude(axis); if (length > 0) look.alignedAxis = Cesium.Cartesian3.divideByScalar(axis, length, axis); } 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; } /** * What a billboard draws of an icon item but its position, image and * `meta`, as plain values: the course rotation follows the * position, so it is written with it. */ function iconStyleOf(record, item) { const color = item.color; const curve = (c) => c ? [c.near, c.nearValue, c.far, c.farValue] : undefined; return { width: item.size[0], height: item.size[1], scale: item.scale, color: Array.isArray(color) || ArrayBuffer.isView(color) ? [...color] : color, alpha: item.alpha, focus: item.focus, anchor: item.anchor, disableDepthTest: item.disableDepthTest, heightMode: item.height, clampTo: record.spec.clampTo, show: item.show, displayRange: item.displayRange ? [...item.displayRange] : undefined, scaleByDistance: curve(item.scaleByDistance), fadeByDistance: curve(item.fadeByDistance), rotationMode: item.rotationMode, rotation: item.rotation, alignedAxis: item.alignedAxis ? [item.alignedAxis.x, item.alignedAxis.y, item.alignedAxis.z] : undefined, course: item.course, pixelOffset: item.pixelOffset ? [item.pixelOffset.x ?? 0, item.pixelOffset.y ?? 0] : undefined, }; } /** Two lists, or two missing ones, alike element by element. */ function sameList(a, b) { if (!a || !b) return a === b; if (a.length !== b.length) return false; for (let i = 0; i < a.length; i++) if (a[i] !== b[i]) return false; return true; } /** A curve as `iconStyleOf` keeps it, and one as an item gives it. */ function sameCurve(a, c) { return !a || !c ? !a && !c : a[0] === c.near && a[1] === c.nearValue && a[2] === c.far && a[3] === c.farValue; } /** * Whether `item` draws as `style` (`iconStyleOf`) says, but its position * and, turned on screen, its rotation (`moveIcon` writes both). */ function sameIconStyle(style, record, item) { const color = item.color; return ( style.width === item.size[0] && style.height === item.size[1] && style.scale === item.scale && (Array.isArray(color) || ArrayBuffer.isView(color) ? Array.isArray(style.color) && sameList(style.color, color) : style.color === color) && style.alpha === item.alpha && style.focus === item.focus && style.anchor === item.anchor && style.disableDepthTest === item.disableDepthTest && style.heightMode === item.height && style.clampTo === record.spec.clampTo && style.show === item.show && sameList(style.displayRange, item.displayRange) && sameCurve(style.scaleByDistance, item.scaleByDistance) && sameCurve(style.fadeByDistance, item.fadeByDistance) && style.rotationMode === item.rotationMode && (item.rotationMode === 'screen' || style.rotation === item.rotation) && (item.alignedAxis ? style.alignedAxis?.[0] === item.alignedAxis.x && style.alignedAxis[1] === item.alignedAxis.y && style.alignedAxis[2] === item.alignedAxis.z : style.alignedAxis === undefined) && style.course === item.course && (item.pixelOffset ? style.pixelOffset?.[0] === (item.pixelOffset.x ?? 0) && style.pixelOffset[1] === (item.pixelOffset.y ?? 0) : style.pixelOffset === undefined) ); } const movedEnu = new Cesium.Matrix4(); const movedAxis = new Cesium.Cartesian3(); /** * Move a drawn icon whose look is unchanged (`sameIconStyle`): its * position, the course rotation that follows it or the screen rotation * it is given, and its pick record. */ function moveIcon(record, entry, item) { const { billboard, placed } = entry; const position = toCartesianInto(item.pos, placed.position); billboard.position = position; if (item.rotationMode === 'course') { Cesium.Transforms.eastNorthUpToFixedFrame(position, undefined, movedEnu); // The billboard copies the axis it is given. billboard.alignedAxis = Cesium.Matrix4.multiplyByPointAsVector( movedEnu, Cesium.Cartesian3.UNIT_Y, movedAxis, ); } if (item.rotationMode === 'screen') { billboard.rotation = item.rotation ?? 0; entry.style.rotation = item.rotation; } billboard.id.meta = item.meta; billboard.show = shownNow(record, placed); } /** 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, // What it is drawn as, for `patchIcon`'s quick path. style: iconStyleOf(record, item), }); } /** * 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; // Drawn as it was but for where it is: only that is written, so a set // whose icons move every frame costs little more than the moves. if ( entry.style && imageKeyOf(image) === entry.image && sameIconStyle(entry.style, record, item) ) { moveIcon(record, entry, item); return; } entry.style = iconStyleOf(record, item); 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; placed.position = position; placed.shown = look.show; billboard.show = shownNow(record, placed); } /** * `syncIcons`' quick case: every item is drawn, every touched one keeps * the image it is drawn with, and nothing drawn has gone, so each touched * one is changed where it is and nothing is added, removed or reordered. * False, changing nothing, otherwise. * @param {object} record * @param {readonly string[]} touched */ function patchDrawnIcons(record, touched) { const drawn = record.billboards; // Nothing to remove: every item drawn, and nothing drawn but items. if ( !Array.isArray(touched) || touched.length === 0 || drawn.size !== record.items.size ) return false; for (const id of touched) { const entry = drawn.get(id); const item = record.items.get(id); if (!entry || !item) return false; const image = iconImage(record, item.image); if ( image === undefined || imageKeyOf(image) !== entry.image || (isKeyed(image) && image.canvas !== entry.canvas) ) return false; } for (const id of touched) { const item = record.items.get(id); patchIcon(record, drawn.get(id), item, iconImage(record, item.image)); } return true; } /** * 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. When done, `ICONS_CHANGED` if icons were added * or removed (the set's pick ids changed), else `ICONS_KEPT`. * @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; if (!reordered && patchDrawnIcons(record, touched)) return ICONS_KEPT; 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)); } let added = false; 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); added = true; } } return added || gone.size ? ICONS_CHANGED : ICONS_KEPT; } function buildPoints(record) { let points = null; let dots = null; for (const item of record.items.values()) { const position = toCartesian(item.pos); // An empty range shows it nowhere. const show = item.show !== false && displayable(item.displayRange); const heightReference = heightReferenceOf( item.height, record.spec.clampTo, ); if (heightReference === Cesium.HeightReference.NONE) { points ??= new Cesium.PointPrimitiveCollection({ blendOption: pointBlendOf(record.spec.blend), }); addPoint(record, points, item, position, show); continue; } // Point primitives cannot follow the ground. dots ??= new Cesium.BillboardCollection({ scene }); const primitive = addDot(dots, item, { position, heightReference, show, distanceDisplayCondition: displayConditionOf(item.displayRange), id: pickId(record, item), }); record.patchable ??= new Map(); record.patchable.set(item.id, { primitive, placed: place(record, primitive, position, show), at: placeOf(item), dot: dotLook(item).key, heightReference, }); } // With no clamped dots, its points are drawn by one collection that // takes points added later where it is. if (!dots) points ??= new Cesium.PointPrimitiveCollection({ blendOption: pointBlendOf(record.spec.blend), }); record.patchable ??= new Map(); record.pointHost = dots ? null : points; let host = points ?? dots; if (points && dots) { host = new Cesium.PrimitiveCollection(); host.add(points); host.add(dots); } replaceHost(record, host); } /** Draw an unclamped point item on `points`, the set's collection. */ function addPoint(record, points, item, position, show) { const primitive = points.add({ position, ...pointLook(item), show, id: pickId(record, item), }); record.patchable ??= new Map(); record.patchable.set(item.id, { primitive, placed: place(record, primitive, position, show), at: placeOf(item), look: pointLookOf(item), }); } /** How a point primitive draws an unclamped point item. */ function pointLook(item) { return { pixelSize: item.pixelSize, color: toColor(item.color), outlineColor: toColor(item.outlineColor ?? [0, 0, 0, 0]), outlineWidth: item.outlineWidth ?? 0, disableDepthTestDistance: item.disableDepthTest ?? 0, scaleByDistance: nearFarOf(item.scaleByDistance), translucencyByDistance: nearFarOf(item.fadeByDistance), distanceDisplayCondition: displayConditionOf(item.displayRange), }; } // An unclamped point's look, by the item's members each primitive member // is drawn from: an upsert sets only the members whose values changed, // so a set moving every point each frame makes nothing new for the look. const LOOK = [ ['pixelSize', (item) => item.pixelSize], ['color', (item) => toColor(item.color)], ['outlineColor', (item) => toColor(item.outlineColor ?? [0, 0, 0, 0])], ['outlineWidth', (item) => item.outlineWidth ?? 0], ['disableDepthTestDistance', (item) => item.disableDepthTest ?? 0], ['scaleByDistance', (item) => nearFarOf(item.scaleByDistance)], ['translucencyByDistance', (item) => nearFarOf(item.fadeByDistance)], [ 'distanceDisplayCondition', (item) => displayConditionOf(item.displayRange), ], ]; const LOOK_FROM = [ 'pixelSize', 'color', 'outlineColor', 'outlineWidth', 'disableDepthTest', 'scaleByDistance', 'fadeByDistance', 'displayRange', ]; /** * What a point's look keeps of an item member: a frozen value of plain * members (a frozen colour or curve) as it is, since it cannot change and * is then told unchanged by identity; anything else as a `plainCopy`. */ function lookCopy(value) { if (!value || typeof value !== 'object' || !Object.isFrozen(value)) return plainCopy(value); // Only plain data cannot change: no getters, nothing inherited. const proto = Object.getPrototypeOf(value); if (proto !== Object.prototype && proto !== Array.prototype) return plainCopy(value); for (const key of Reflect.ownKeys(value)) { const member = Object.getOwnPropertyDescriptor(value, key); if ( !('value' in member) || (member.value !== null && typeof member.value === 'object') ) return plainCopy(value); } return value; } /** A copy of the item members a point's look is drawn from. */ const pointLookOf = (item) => LOOK_FROM.map((key) => lookCopy(item[key])); /** * Whether `value` holds what `kept` (a `plainCopy` of a colour, curve or * range) holds, read without allocating: points moved every frame * compare their looks every frame. */ function sameLookValue(kept, value) { if (Object.is(kept, value)) return true; if ( !kept || !value || typeof kept !== 'object' || typeof value !== 'object' ) return false; if (Array.isArray(kept) !== Array.isArray(value)) return false; if (Array.isArray(value)) { // Colours, read by index: a `for...in` over an array is far slower. if (kept.length !== value.length) return false; for (let i = 0; i < value.length; i++) if (!Object.is(kept[i], value[i])) return false; return true; } let count = 0; for (const key in value) { if (value[key] === undefined) continue; count += 1; if (!Object.is(kept[key], value[key])) return false; } for (const key in kept) if (kept[key] !== undefined) count -= 1; return count === 0; } /** Set the members of a point's look whose item values changed. */ function patchLook(was, item) { for (let i = 0; i < LOOK.length; i++) { const value = item[LOOK_FROM[i]]; if (sameLookValue(was.look[i], value)) continue; was.primitive[LOOK[i][0]] = LOOK[i][1](item); was.look[i] = lookCopy(value); } } /** * Where an item is, as its values when drawn: a caller may change the * position object it passes and send the same one again. */ const placeOf = (item) => { const pos = item.pos; return [ pos?.x, pos?.y, pos?.z, pos?.lon, pos?.lat, pos?.height, item.height, ]; }; /** * Whether an item is somewhere else than `at`; if so, `at` takes it. Read * member by member, by name: points moved every frame are compared every * frame. */ function movedFrom(at, item) { const pos = item.pos; const x = pos?.x; const y = pos?.y; const z = pos?.z; const lon = pos?.lon; const lat = pos?.lat; const height = pos?.height; if ( Object.is(x, at[0]) && Object.is(y, at[1]) && Object.is(z, at[2]) && Object.is(lon, at[3]) && Object.is(lat, at[4]) && Object.is(height, at[5]) && Object.is(item.height, at[6]) ) return false; at[0] = x; at[1] = y; at[2] = z; at[3] = lon; at[4] = lat; at[5] = height; at[6] = item.height; return true; } /** A position as Cesium's, written into `result`. */ function toCartesianInto(pos, result) { if ('x' in pos) return Cesium.Cartesian3.fromElements(pos.x, pos.y, pos.z, result); return Cesium.Cartesian3.fromDegrees( pos.lon, pos.lat, pos.height ?? 0, undefined, result, ); } /** * Upsert points in place, without a rebuild, when every item is one the * set draws now, in the same LOD group, and stays drawn the same way: an * unclamped point stays unclamped (then how it looks changes on the point * it has, member by member), a clamped dot clamps the same way and keeps * its look (the dot image it is drawn with). Where it is, its `meta`, its * display range and whether it shows change in place; a dot moved follows * the ground where it now is. A new unclamped item joins a set drawn by * one point collection where it is. `POINTS_ADDED` when items were * added, `POINTS_KEPT` when all were changed in place; false, changing * nothing, otherwise. */ function patchPoints(record, list) { const patchable = record.patchable; if (record.kind !== 'points' || !patchable) return false; // New ids, to tell one sent twice (a rebuild keeps the last). let added = null; for (const item of list) { const was = patchable.get(item.id); const heightReference = heightReferenceOf( item.height, record.spec.clampTo, ); if (!was) { // Only an unclamped point joins, on the set's one collection. if ( !record.pointHost || record.host !== record.pointHost || record.pointHost.isDestroyed?.() || heightReference !== Cesium.HeightReference.NONE || added?.has(item.id) ) return false; (added ??= new Set()).add(item.id); continue; } if (was.dot === undefined) { if (heightReference !== Cesium.HeightReference.NONE) return false; } else if ( heightReference !== was.heightReference || dotLook(item).key !== was.dot ) return false; } for (const item of list) { const was = patchable.get(item.id); const show = item.show !== false && displayable(item.displayRange); if (!was) { const position = toCartesian(item.pos); addPoint(record, record.pointHost, item, position, show); const placed = patchable.get(item.id).placed; placed.primitive.show = shownNow(record, placed); continue; } if (movedFrom(was.at, item)) { // The cull's own copy of where it is; the primitive copies it. toCartesianInto(item.pos, was.placed.position); was.primitive.position = was.placed.position; } if (was.dot === undefined) patchLook(was, item); else { was.primitive.distanceDisplayCondition = displayConditionOf( item.displayRange, ); was.primitive.disableDepthTestDistance = item.disableDepthTest ?? 0; } was.primitive.id.meta = item.meta; was.placed.shown = show; was.primitive.show = shownNow(record, was.placed); } return added ? POINTS_ADDED : POINTS_KEPT; } /** * Remove points from a set drawn by one point collection where they are, * as the items that stay keep drawing. False, changing nothing, for a set * drawn otherwise. */ function removePoints(record, ids) { if ( record.kind !== 'points' || !record.pointHost || record.host !== record.pointHost || record.pointHost.isDestroyed?.() ) return false; const gone = new Set(); for (const id of ids) { const was = record.patchable.get(id); if (!was) continue; record.patchable.delete(id); record.pointHost.remove(was.primitive); gone.add(was.primitive); } if (gone.size) { record.pickIds = record.pickIds.filter((pick) => record.patchable.has(pick.id), ); record.placed = record.placed.filter( (placed) => !gone.has(placed.primitive), ); } return true; } /** * How a clamped point's dot is drawn: its image (by key) and the scale * it is drawn at. */ function dotLook(item) { const color = toColor(item.color); const outlineColor = toColor(item.outlineColor ?? [0, 0, 0, 0]); const outlineWidth = Math.round(item.outlineWidth ?? 0); let pixelSize = Math.max(1, Math.round(item.pixelSize)); let scale = 1; if (outlineWidth <= 0) { // Drawn large and scaled down, as the entity points are. scale = pixelSize / 50; pixelSize = 50; } const css = color.toCssColorString(); const cssOutline = outlineColor.toCssColorString(); return { key: JSON.stringify([css, pixelSize, cssOutline, outlineWidth, scale]), image: JSON.stringify([css, pixelSize, cssOutline, outlineWidth]), alpha: color.alpha, css, cssOutline, outlineWidth, pixelSize, scale, }; } /** * A clamped point as Cesium's entity points draw one: a billboard of a * dot drawn at its pixel size, one texture per look. */ function addDot(collection, item, options) { const look = dotLook(item); const billboard = collection.add({ ...options, scale: look.scale, disableDepthTestDistance: item.disableDepthTest ?? 0, }); billboard.setImage( look.image, Cesium.createBillboardPointCallback( look.alpha, look.css, look.cssOutline, look.outlineWidth, look.pixelSize, ), ); return billboard; } /** * A line's material; with `reveal` (where along its texture the line * ends, `revealUniform`), one drawing only that far. A flow material * (the route annotations' dashes, which run toward the line's end on the * clock `flowTime` keeps) is noted for the frame clock. */ function lineMaterial(record, style, reveal) { const fabric = lineFabric(style); // Built from its type, then given its values, as `fromType` does: // values in the fabric would be merged into copies of the type's. const template = ({ type, source, uniforms }) => source ? { type, source, uniforms } : { type }; // A pattern's image carries its own alpha: drawn in the translucent // pass, whatever its colour. const translucent = style.kind === 'pattern' ? { translucent: true } : {}; const material = reveal === undefined ? new Cesium.Material({ fabric: template(fabric), ...translucent }) : new Cesium.Material({ fabric: { type: `${REVEAL_MATERIAL}_${style.kind}`, materials: { revealed: template(fabric) }, uniforms: { reveal }, source: REVEAL_SOURCE, }, ...translucent, }); const drawn = reveal === undefined ? material : material.materials.revealed; Object.assign(drawn.uniforms, fabric.uniforms); const flow = flowOf(material, style); if (flow) record.flowMaterials.push(flow); return material; } /** * The flow material a line's material runs on (itself, or what a revealed * line draws), for the frame clock; null for other styles. */ const flowOf = (material, style) => style.kind !== 'flow' ? null : material.type === FLOW_MATERIAL ? material : material.materials.revealed; /** Stop running the clock of a line material that no longer draws. */ function dropFlow(record, material, style) { const flow = material && flowOf(material, style); if (flow) record.flowMaterials = record.flowMaterials.filter((m) => m !== flow); } /** Whether a line draws only the first part of its length. */ const revealed = (item) => item.revealFraction !== undefined; /** The fabric of a line style's material. */ function lineFabric(style) { switch (style.kind) { case 'flow': return { type: FLOW_MATERIAL, uniforms: { color: toColor(style.color), time: flowTime(style.speed), repeat: style.repeat, duty: style.duty, speed: style.speed, }, source: FLOW_SOURCE, }; case 'solid': // An outlined line keeps its edge in one material: two lines // stacked would darken where their translucent passes overlap. return style.outline ? { type: 'PolylineOutline', uniforms: { color: toColor(style.color), outlineColor: toColor(style.outline.color), outlineWidth: style.outline.widthPx, }, } : { type: 'Color', uniforms: { color: toColor(style.color) } }; case 'glow': return { type: 'PolylineGlow', uniforms: { color: toColor(style.color), glowPower: style.power, taperPower: style.taper ?? 1, }, }; case 'dash': return { type: 'PolylineDash', uniforms: { color: toColor(style.color), gapColor: toColor([0, 0, 0, 0]), dashLength: style.length, ...(style.pattern16 !== undefined ? { dashPattern: style.pattern16 } : {}), }, }; case 'arrow': return { type: 'PolylineArrow', uniforms: { color: toColor(style.color) }, }; case 'pattern': // The image along the line `repeat` times, across its width once. return { type: 'Image', uniforms: { image: imageAt(style.image), repeat: new Cesium.Cartesian2(style.repeat, 1), }, }; default: throw new Error(`the Cesium renderer has no ${style.kind} lines`); } } function linePositions(item) { const flat = item.positions instanceof Float64Array; const points = []; const n = flat ? item.positions.length / 3 : item.positions.length; for (let i = 0; i < n; i++) points.push( flat ? new Cesium.Cartesian3( item.positions[i * 3], item.positions[i * 3 + 1], item.positions[i * 3 + 2], ) : toCartesian(item.positions[i]), ); if (item.mode !== 'geodesic') return points; const dense = []; for (let i = 0; i + 1 < points.length; i++) { const a = Cesium.Cartographic.fromCartesian(points[i]); const b = Cesium.Cartographic.fromCartesian(points[i + 1]); const geodesic = new Cesium.EllipsoidGeodesic(a, b); // At least a step a degree of arc, as Cesium's own geodesic // polylines are cut, and 64 steps over the whole line: a long trail // of short legs stays as light as its positions. const steps = Math.max( Math.ceil((geodesic.surfaceDistance || 0) / GEODESIC_STEP_M), Math.ceil(GEODESIC_LINE_STEPS / (points.length - 1)), ); for (let k = 0; k < steps; k++) { const s = k / steps; const at = geodesic.interpolateUsingFraction(s); dense.push( Cesium.Cartesian3.fromRadians( at.longitude, at.latitude, a.height + (b.height - a.height) * s, ), ); } } dense.push(points.at(-1)); return dense; } /** * Whether `positions` make a line: two or more of them, not all at one * place. */ const drawable = (positions) => positions.length >= 2 && positions.some((p) => !Cesium.Cartesian3.equals(p, positions[0])); /** * A line not draped that has a `depthFail` style: a primitive of its own, * drawn in that style where the surface hides it. Built at once, so one * built anew where it moves draws in the frame it replaces the old one. * Null when its positions make no line. */ function depthFailLine(record, item, id) { const positions = linePositions(item); if (!drawable(positions)) return null; const reveal = revealed(item) ? revealUniform(item.revealFraction, positions) : undefined; const material = lineMaterial(record, item.style, reveal); return new Cesium.Primitive({ geometryInstances: new Cesium.GeometryInstance({ geometry: new Cesium.PolylineGeometry({ positions, width: item.widthPx, vertexFormat: Cesium.PolylineMaterialAppearance.VERTEX_FORMAT, // Straight between the positions, as the collection's lines are // (geodesic ones come densified); one drawn for a draped line // follows the surface's curve between them, as draping does. arcType: item.overlaid ? Cesium.ArcType.GEODESIC : Cesium.ArcType.NONE, }), id, }), appearance: new Cesium.PolylineMaterialAppearance({ material }), depthFailAppearance: item.depthFail ? new Cesium.PolylineMaterialAppearance({ material: lineMaterial(record, item.depthFail, reveal), }) : undefined, show: item.show !== false, asynchronous: false, // A set that never picks keeps these out of the pick pass too. allowPicking: record.spec.pickable !== false, }); } /** * A draped line's geometry instance under its pick id: coloured per * instance when `solid` (batched with others), else drawn by its * primitive's material. */ function drapedInstance(item, part, solid, positions = linePositions(item)) { const show = new Cesium.ShowGeometryInstanceAttribute(item.show !== false); return new Cesium.GeometryInstance({ geometry: new Cesium.GroundPolylineGeometry({ positions, width: item.widthPx, arcType: Cesium.ArcType.GEODESIC, }), attributes: solid ? { color: Cesium.ColorGeometryInstanceAttribute.fromColor( toColor(item.style.color), ), show, } : { show }, id: part.id, }); } /** * Whether a draped line draws in a batch of solid ones: a batch draws * colours only, so an outlined line draws by its own material. */ const batchable = (item) => item.style.kind === 'solid' && !item.style.outline && !revealed(item); /** * A ground primitive of a draped line's own, drawn by a material (a * style, or a reveal, a batch cannot draw) or, solid, by its colour. With * `sync` it is built in the first frame it is updated in, as Cesium's * entities build ground lines whose positions change: only once Cesium's * approximate terrain heights are loaded (`groundSyncs`). */ function drapedPrimitive(record, item, part, sync, positions) { const solid = batchable(item); let appearance; if (solid) { appearance = new Cesium.PolylineColorAppearance(); part.material = null; } else { part.material = lineMaterial( record, item.style, revealed(item) ? revealUniform(item.revealFraction) : undefined, ); appearance = new Cesium.PolylineMaterialAppearance({ material: part.material, }); } return new Cesium.GroundPolylinePrimitive({ geometryInstances: [drapedInstance(item, part, solid, positions)], appearance, classificationType: classificationOf(part.clampTo), allowPicking: record.spec.pickable !== false, asynchronous: !sync, }); } /** * Turn a line set's inertial lines to the sky at its motion clock's time * now: the frame rotated by sidereal time from the Earth-fixed one. */ /** The time a set's motion clock reads now, epoch ms. */ function motionMs(record) { const clock = record.spec.motionClock; return clock?.kind === 'scene' ? Cesium.JulianDate.toDate( scene.frameState?.time ?? Cesium.JulianDate.now(), ).getTime() : Date.now() - (clock?.delayMs ?? 0); } /** * A draped line in the sky's frame as a fixed one where the sky is at * `axes` (`temeToPseudoFixed`): its positions turned into the fixed frame. */ function fixedLine(item, axes) { const { x, y, z } = axes; const flat = item.positions instanceof Float64Array ? item.positions : item.positions.flatMap((p) => { const c = toCartesian(p); return [c.x, c.y, c.z]; }); const turned = new Float64Array(flat.length); for (let i = 0; i < flat.length; i += 3) { const a = flat[i]; const b = flat[i + 1]; const c = flat[i + 2]; turned[i] = x.x * a + y.x * b + z.x * c; turned[i + 1] = x.y * a + y.y * b + z.y * c; turned[i + 2] = x.z * a + y.z * b + z.z * c; } return { ...item, frame: 'fixed', positions: turned }; } function turnInertial(record) { const lines = record.inertialLines; const pieces = record.inertialPieces ?? []; if ((!lines || lines.isDestroyed()) && !pieces.length) return; const { x, y, z } = temeToPseudoFixed(motionMs(record)); const turn = Cesium.Matrix4.fromRotationTranslation( new Cesium.Matrix3(x.x, y.x, z.x, x.y, y.y, z.y, x.z, y.z, z.z), Cesium.Cartesian3.ZERO, ); if (lines && !lines.isDestroyed()) lines.modelMatrix = Cesium.Matrix4.clone(turn, lines.modelMatrix); for (const primitive of pieces) if (!primitive.isDestroyed()) primitive.modelMatrix = Cesium.Matrix4.clone( turn, primitive.modelMatrix, ); } /** * Whether a line draws piece by piece, each piece a primitive with a * material of its own (`linePieces`): a segmented line that is not a * draped solid one (those are ground instances a segment), and an * inertial line with a depth-fail style (a primitive turned each frame). */ const piecewise = (item) => (segmented(item) && !( item.mode === 'draped' && item.style.kind === 'solid' && !item.style.outline && !revealed(item) )) || (item.frame === 'inertial' && item.mode !== 'draped' && item.depthFail); /** * The style a segment of a line draws in: the line's, in the segment's * colour. An arrow's head is on its last segment only, the others solid; * a pattern keeps its image. */ function pieceStyle(item, j, last) { const style = item.style; if (style.kind === 'pattern') return style; const color = item.segmentColors?.[j] ?? style.color; if (style.kind === 'arrow' && !last) return { kind: 'solid', color }; return { ...style, color }; } /** * A line drawn piece by piece: a segment a piece for a segmented line * (each its own primitive and material, under a pick id of its own that * reads as the line's, so a segment's colour and show change in place), * else one piece for the whole line. A revealed line reveals each piece * by its share of the line's length. Draped pieces are ground polylines. * Inertial pieces turn with the sky (`turnInertial`). */ function linePieces(record, item, host, groundOut) { const id = pickId(record, item); // Its own positions: a geodesic piece is cut along its arc as it is drawn. const points = linePositions({ ...item, mode: '3d' }); const part = { look: lineLook(item), id, from: flatPositions(item.positions), reveal: item.revealFraction, pieces: [], }; const bySegment = segmented(item); const spans = bySegment ? points.slice(1).map((_, j) => [j, j + 1]) : [[0, points.length - 1]]; const lengths = spans.map(([a, b]) => { let length = 0; for (let k = a; k < b; k++) length += Cesium.Cartesian3.distance(points[k], points[k + 1]); return length; }); const total = lengths.reduce((sum, length) => sum + length, 0); let start = 0; spans.forEach(([a, b], j) => { const positions = points.slice(a, b + 1); const begins = start; start += lengths[j]; if (!drawable(positions)) { part.pieces.push(null); return; } // Its share of the revealed length, 0..1. const shown = revealed(item) ? Math.min( 1, Math.max( 0, (item.revealFraction * total - begins) / (lengths[j] || 1), ), ) : 1; const pieceId = bySegment ? Object.create(id) : id; if (bySegment) record.pickIds.push(pieceId); const sub = { ...item, positions, style: pieceStyle(item, j, j === spans.length - 1), ...(revealed(item) && shown < 1 ? { revealFraction: shown } : {}), }; if (!(revealed(item) && shown < 1)) delete sub.revealFraction; const draped = item.mode === 'draped'; const showing = pieceShows(item, j, shown); // A ground piece is built shown, and hidden by its instance's show // once it is ready (before the set's ground shows): one built hidden // would never show. Showing it later needs no build. const primitive = draped ? groundPiece(record, sub, pieceId, true) : depthFailLine(record, sub, pieceId); if (!draped) primitive.show = showing; // Ground pieces swap in with the set's other ground primitives. if (draped) groundOut.push(primitive); else host.add(primitive); if (item.frame === 'inertial' && item.mode !== 'draped') (record.inertialPieces ??= []).push(primitive); part.pieces.push({ primitive, j, last: j === spans.length - 1, shown, draped, id: pieceId, pendingShow: draped && !showing ? false : undefined, }); }); return part; } /** Whether a piece shows: its line, its segment and some of it revealed. */ const pieceShows = (item, j, shown = 1) => item.show !== false && item.segmentShow?.[j] !== false && !(revealed(item) && shown <= 0); /** A draped piece: a ground polyline drawn by its style's material. */ function groundPiece(record, item, id, show) { const reveal = revealed(item) ? revealUniform(item.revealFraction) : undefined; return new Cesium.GroundPolylinePrimitive({ geometryInstances: [ new Cesium.GeometryInstance({ geometry: new Cesium.GroundPolylineGeometry({ positions: item.positions, width: item.widthPx, arcType: Cesium.ArcType.GEODESIC, }), attributes: { show: new Cesium.ShowGeometryInstanceAttribute(show) }, id, }), ], appearance: new Cesium.PolylineMaterialAppearance({ material: lineMaterial(record, item.style, reveal), }), classificationType: classificationOf( item.clampTo ?? record.spec.clampTo ?? 'both', ), allowPicking: record.spec.pickable !== false, }); } /** A pieced line's colours and shows, written in place. */ function writePieces(part, item) { for (const piece of part.pieces) { if (!piece || piece.primitive.isDestroyed()) continue; const style = pieceStyle(item, piece.j, piece.last); const material = piece.primitive.appearance.material; if (style.kind !== 'pattern') paintLine(material.materials?.revealed ?? material, style); const show = pieceShows(item, piece.j, piece.shown); if (!piece.draped) piece.primitive.show = show; else if (piece.primitive.ready) { showOn(piece.primitive, piece.id, show); piece.pendingShow = undefined; } else piece.pendingShow = show; } } /** Whether the scene can drape lines (Cesium's ground polylines need * depth textures, which every WebGL 2 context has). */ const drapes = () => scene.frameState?.context?.depthTexture !== false; /** * A draped line as drawn where the scene cannot drape: undraped along its * positions, in its colour where the surface hides it (so it draws over * the surface), as one colour where it had segments of its own. One with * segments runs from its first shown segment to its last, and is hidden * with none shown. */ function overlayLine(item) { if (item.mode !== 'draped') return item; const { segmentColors, segmentShow, clampTo, ...rest } = item; const line = { ...rest, mode: '3d', depthFail: { kind: 'solid', color: item.style.color }, overlaid: true, }; if (segmentShow?.length) { const first = segmentShow.indexOf(true); const last = segmentShow.lastIndexOf(true); if (first < 0) line.show = false; else if (first > 0 || last < segmentShow.length - 1) line.positions = linePositions(item).slice(first, last + 2); } return line; } /** * Recolour, in place, a line drawn over the surface for a draped one whose * positions are the ones it was built from. False, changing nothing, for * one that moved or is revealed. */ function overlayRecoloured(record, part, item) { const deep = part.deep; if (!item.overlaid || !deep || revealed(item)) return false; if (!flatEquals(item.positions, part.overlayFrom)) return false; // Only its colour may have changed (`patchLines` checked its look). paintLine(deep.appearance.material, item.style); deep.depthFailAppearance.material.uniforms.color = toColor( item.style.color, ); const line = record.overlayLines.find((entry) => entry.part === part); if (line) line.shown = item.show !== false; else deep.show = item.show !== false; return true; } /** An overlay line's look but its colours (its depth-fail style is its * colour too). */ const overlayShape = (item) => lineLook({ ...item, depthFail: null }, true); /** Stop tracking a line no longer drawn over the surface for a draped * one. */ function overlayLeft(record, part) { const lines = record.overlayLines; const at = lines ? lines.findIndex((line) => line.part === part) : -1; if (at >= 0) lines.splice(at, 1); part.overlayFrom = undefined; part.overlayShape = undefined; } /** Track a patched overlay line for the horizon cull, as built now. */ function overlayMoved(record, part, item) { part.overlayFrom = flatPositions(item.positions); part.overlayShape = overlayShape(item); const lines = record.overlayLines; const at = lines.findIndex((line) => line.part === part); if (at >= 0) lines.splice(at, 1); if (!part.deep) return; lines.push({ part, shown: item.show !== false, ends: overlayEnds(item.positions), }); } /** * Points along a line for the horizon test: up to 16 of its positions, * evenly spread, and between each two the point on the surface's curve * halfway (so a long arc under the eye is not taken as past the horizon). */ function overlayEnds(positions) { const all = linePositions({ positions }); if (!all.length) return []; const picks = Math.min(all.length, 16); const probes = []; let previous = null; for (let k = 0; k < picks; k++) { const at = all[Math.round((k * (all.length - 1)) / Math.max(1, picks - 1))]; if (previous) { const mid = Cesium.Cartesian3.midpoint( previous, at, new Cesium.Cartesian3(), ); const radius = (Cesium.Cartesian3.magnitude(previous) + Cesium.Cartesian3.magnitude(at)) / 2; if (Cesium.Cartesian3.magnitude(mid) > 0) probes.push( Cesium.Cartesian3.multiplyByScalar( Cesium.Cartesian3.normalize(mid, mid), radius, mid, ), ); } probes.push(at); previous = at; } return probes; } function buildLines(record) { // Refused before anything changes, so the set keeps drawing as it was. for (const item of record.items.values()) if (item.mode === 'draped' && !DRAPED_STYLES.has(item.style.kind)) throw new Error(`the Cesium renderer has no ${item.style.kind} lines`); else if ( item.mode !== 'draped' && item.depthFail && item.depthFail.kind !== 'solid' && item.depthFail.kind !== 'dash' ) throw new Error( 'the Cesium renderer draws solid and dashed lines behind the surface only', ); // Where the scene cannot drape at all, draped lines draw over the // surface instead (`overlay`): undraped, in their own colour where the // surface hides them, and hidden past the horizon (`cullOverlayLines`). const overlay = !drapes(); const items = overlay ? [...record.items.values()].map(overlayLine) : [...record.items.values()]; record.overlayLines = overlay ? [] : null; const polylines = new Cesium.PolylineCollection(); // Lines in the inertial frame, turned with the sky each frame. let inertial = null; const draped = new Map(); // Draped glow lines that look alike: one ground primitive and one // material for them all, so they recolour together in place. const glows = new Map(); // Draped lines a batch cannot draw, each with a primitive of its own. const alone = []; // Each line as drawn, for upserts that change it in place. const parts = new Map(); // What the old host's flow lines run on, while it still draws; a host // already retiring keeps drawing in its place, with its own. if (!record.retiring) { record.retiringFlows = record.flowMaterials ?? null; record.retiringParts = record.drawnParts ?? null; } record.flowMaterials = []; record.lineParts = parts; // Lines with a depth-fail colour, beside the collection. let deep = null; const looks = lineLooks(); // Lines drawn piece by piece, beside the collection. let pieces = null; const groundPieces = []; record.inertialPieces = []; for (const item of items) { if (piecewise(item)) { if (item.mode !== 'draped') pieces ??= new Cesium.PrimitiveCollection(); parts.set(item.id, linePieces(record, item, pieces, groundPieces)); continue; } if (item.mode === 'draped') { const clampTo = item.clampTo ?? record.spec.clampTo ?? 'both'; const part = { look: lineLook(item), shape: lineLook(item, true), positions: flatPositions(item.positions), clampTo, id: pickId(record, item), // Its ground primitive: its batch's, or its own. ground: null, batch: null, material: null, // Moved in place: drawn by a primitive of its own built at once. solo: false, }; parts.set(item.id, part); if (segmented(item)) { // A line of no length builds no ground primitive (it would // never be ready, and hold the swap). const instances = segmentInstances(record, item, part); if (!instances.length) continue; if (!draped.has(clampTo)) draped.set(clampTo, []); draped.get(clampTo).push(...instances); continue; } if (item.style.kind === 'glow' && !revealed(item)) { if (!glows.has(part.look)) glows.set(part.look, []); glows.get(part.look).push({ item, part }); continue; } if (!batchable(item)) { alone.push({ item, part }); continue; } if (!draped.has(clampTo)) draped.set(clampTo, []); draped.get(clampTo).push(drapedInstance(item, part, true)); continue; } if (item.depthFail) { deep ??= new Cesium.PrimitiveCollection(); const id = pickId(record, item); const primitive = depthFailLine(record, item, id); if (primitive) deep.add(primitive); const part = { look: lineLook(item), id, deep: primitive }; if (item.overlaid) { part.overlayFrom = flatPositions(item.positions); part.overlayShape = overlayShape(item); } parts.set(item.id, part); if (item.overlaid && primitive) record.overlayLines.push({ part, shown: item.show !== false, ends: overlayEnds(item.positions), }); continue; } const id = pickId(record, item); if (item.frame === 'inertial') { inertial ??= new Cesium.PolylineCollection(); const { polyline, reveal, parked } = addPolyline( record, inertial, item, id, true, ); // Never settled into a static batch, which would not turn. parts.set(item.id, { look: lineLook(item), shape: null, positions: null, id, polyline, reveal, parked, home: inertial, batched: null, }); continue; } const settled = settles(item); const { polyline, reveal, parked } = addPolyline( record, polylines, item, id, !settled, ); parts.set(item.id, { look: lineLook(item), // How it draws but for its colour, and where it runs, to tell a // change it takes in place: kept for lines that can settle. shape: settled ? looks.shape(item) : null, positions: settled ? flatPositions(item.positions) : null, // An outlined line, which never settles, takes its colours in // place too: how it draws but for them. outlined: item.style.outline ? looks.shape(item) : null, id, polyline, reveal, // Hidden, out of the collection until it shows (`addPolyline`). parked, home: polylines, // Drawn in the set's static batch instead (`settleLines`). batched: null, }); } let own = polylines; // Lines in the collection that can settle into a static batch draw // beside it once they do. const settling = items.some(settles); if (deep || settling || inertial || pieces) { own = new Cesium.PrimitiveCollection(); own.add(polylines); if (deep) own.add(deep); if (inertial) own.add(inertial); if (pieces) own.add(pieces); } record.deepLines = deep; record.inertialLines = inertial; if (inertial || record.inertialPieces.length) turnInertial(record); record.polylines = polylines; record.lineBox = settling ? own : null; record.batch = null; record.batchPending = null; record.settled = 0; if (!draped.size && !glows.size && !alone.length && !groundPieces.length) { noteFlows(record); return replaceHost(record, own); } // Draped lines drape as the entities' clamped polylines do. const byClamp = new Map(); const ground = [...draped].map(([clampTo, geometryInstances]) => { const primitive = new Cesium.GroundPolylinePrimitive({ geometryInstances, appearance: new Cesium.PolylineColorAppearance(), classificationType: classificationOf(clampTo), allowPicking: record.spec.pickable !== false, }); byClamp.set(clampTo, primitive); return primitive; }); for (const part of parts.values()) if (part.clampTo && byClamp.has(part.clampTo)) { part.ground = byClamp.get(part.clampTo); part.batch = part.ground; } for (const lines of glows.values()) { const [{ item, part: first }] = lines; const material = lineMaterial(record, item.style); const primitive = new Cesium.GroundPolylinePrimitive({ geometryInstances: lines.map(({ item, part }) => drapedInstance(item, part, false), ), appearance: new Cesium.PolylineMaterialAppearance({ material }), classificationType: classificationOf(first.clampTo), allowPicking: record.spec.pickable !== false, }); // A batch as the solid ones are: a line moved leaves it, hidden. for (const { part } of lines) { part.ground = primitive; part.batch = primitive; part.material = material; part.shared = true; } ground.push(primitive); } for (const { item, part } of alone) { part.ground = drapedPrimitive(record, item, part, false); ground.push(part.ground); } ground.push(...groundPieces); noteFlows(record); replaceHost(record, collect(own, ground), ground, own); } /** A line style but for its colours, which its material takes in place. */ const colourlessStyle = (style) => style.outline ? { ...style, color: undefined, outline: { ...style.outline, color: undefined }, } : { ...style, color: undefined }; /** Give a line's material its style's colours, its outline's too. */ function paintLine(material, style) { material.uniforms.color = toColor(style.color); if (style.outline && 'outlineColor' in material.uniforms) material.uniforms.outlineColor = toColor(style.outline.color); } /** * How a line draws, but for where it runs, whether it shows and how much * of it is revealed: lines that keep it can be changed in place. */ const lineLook = (item, colourless = false) => JSON.stringify([ item.mode, item.widthPx, item.clampTo, colourless ? colourlessStyle(item.style) : item.style, // The same depth-fail style in any key order. item.depthFail ? [ item.depthFail.kind, item.depthFail.color, item.depthFail.length, item.depthFail.pattern16, ] : null, // Segment colours and shows change in place. item.segmentColors != null, item.segmentShow != null, revealed(item), item.frame, ]); /** * Whether two lines have the same `lineLook` by the identity of what it * is drawn from, read without stringifying either. */ const sameLookFrom = (a, b) => a.mode === b.mode && Object.is(a.widthPx, b.widthPx) && a.clampTo === b.clampTo && a.style === b.style && a.depthFail === b.depthFail && (a.segmentColors != null) === (b.segmentColors != null) && (a.segmentShow != null) === (b.segmentShow != null) && revealed(a) === revealed(b) && a.frame === b.frame; /** * `lineLook`, kept for the last item asked for: within one upsert, lines * sent with one style object (lines pulsing together) are stringified * once. Not across upserts, where a caller may have changed the style * object it sends again. */ function lineLooks() { let last = null; let look = ''; let shape = ''; return { look(item) { if (!last || !sameLookFrom(last, item)) { last = item; look = lineLook(item); shape = ''; } return look; }, shape(item) { this.look(item); shape ||= lineLook(item, true); return shape; }, }; } /** A line's positions as one flat array of numbers, to compare. */ function flatPositions(positions) { if (positions instanceof Float64Array) return Array.from(positions); const flat = []; for (const p of positions) if ('x' in p) flat.push(p.x, p.y, p.z); else flat.push(p.lon, p.lat, p.height ?? 0, NaN); return flat; } const samePositions = (a, b) => a === b || (a.length === b.length && a.every((value, i) => Object.is(value, b[i]))); /** * Whether a line's positions are those `flat` (a `flatPositions`) holds, * read without flattening them: lines sent again every frame, unmoved, * make nothing new. */ function flatEquals(positions, flat) { const same = (value, at) => at < flat.length && Object.is(value, flat[at]); if (positions instanceof Float64Array) { if (positions.length !== flat.length) return false; for (let i = 0; i < positions.length; i++) if (!same(positions[i], i)) return false; return true; } let at = 0; for (let i = 0; i < positions.length; i++) { const p = positions[i]; if ('x' in p) { if (!same(p.x, at) || !same(p.y, at + 1) || !same(p.z, at + 2)) return false; at += 3; continue; } if ( !same(p.lon, at) || !same(p.lat, at + 1) || !same(p.height ?? 0, at + 2) || !same(NaN, at + 3) ) return false; at += 4; } return at === flat.length; } /** * Whether a draped line drawn by a material of its own (not a batch's, * nor revealed or in segments) changes only its colour: its material * takes the new one in place. */ const recolourable = (was, item, looks) => Boolean(was.clampTo && was.material && !was.segments) && !revealed(item) && was.shape === (looks ? looks.shape(item) : lineLook(item, true)); /** * Whether an undraped line that can settle (in the collection or a * static batch), or an outlined one in the collection, changes only its * colours: it takes the new ones in place. */ const recolourableSolid = (was, item, looks) => (Boolean((was.polyline || was.batched) && was.shape) && was.shape === looks.shape(item)) || (Boolean(was.polyline && was.outlined) && !revealed(item) && was.outlined === looks.shape(item)); /** * Whether a line drawn over the surface for a draped one changes only its * colour where it runs: it takes the new one in place * (`overlayRecoloured`). */ const recolourableOverlay = (was, item, looks) => Boolean(item.overlaid && was.deep && was.overlayShape) && flatEquals(item.positions, was.overlayFrom) && !revealed(item) && was.overlayShape === overlayShape(item); /** * The colours the glow lines sharing a material that `list` recolours * are given together: each such material and the item whose colour it * takes, when every line it draws ends the upsert with one look (its * last in `list`); null when they would not, as the material draws them * all. Lines that move then draw on a material of their own. */ function sharedRecolours(parts, list, looks) { const recolours = new Map(); // Each shared line's last look in `list`, and the item it is from. let final = null; for (let k = 0; k < list.length; k++) { const was = parts.get(list[k].id); if (was.shared && !was.solo) (final ??= new Map()).set(list[k].id, k); } if (!final) return recolours; const lookOf = new Map(); for (const [id, k] of final) { const was = parts.get(id); if (looks[k] === was.look) continue; recolours.set(was.material, list[k]); lookOf.set(was.material, looks[k]); } for (const [id, part] of parts) { if (!part.shared || part.solo || !lookOf.has(part.material)) continue; if (looks[final.get(id)] !== lookOf.get(part.material)) return null; } return recolours; } /** * Whether a draped line's upsert can change it in place: its ground * primitive is still there and, unless it moves, ready or building as * the set's pending one (or drawn alone); one that moves is built anew * at once, which needs Cesium's terrain heights loaded. */ function drapedPatchable(record, was, flat) { if (was.ground?.isDestroyed() || was.batch?.isDestroyed()) return false; if (!samePositions(flat, was.positions)) return groundSyncs() && typeof record.host?.add === 'function'; if (was.solo) return true; return was.ground.ready || record.pending?.includes(was.ground); } /** * Upsert lines in place, without a rebuild, when every item is drawn now * and looks the same: then only whether it shows, its `meta`, how much of * it is revealed and where it runs change. An undraped line moves on the * polyline it has (one with a depth-fail colour is built anew, alone); a * draped one that moves is drawn by a ground primitive of its own, built * anew in the frame it moves (`drapedPatchable`). False, changing * nothing, otherwise. */ function patchLines(record, list) { const parts = record.lineParts; if (record.kind !== 'lines' || !parts) return false; // Where the scene cannot drape, draped lines are patched as the lines // drawn over the surface for them, each built anew alone where it // changes (as any line with a depth-fail colour is). if (record.overlayLines) list = list.map(overlayLine); // Each draped line's positions, flattened once for both passes. const flats = new Map(); // Each item's look, in order: an item sent twice is changed twice. const looks = []; const lookOf = lineLooks(); for (const item of list) { const was = parts.get(item.id); if (!was) return false; // A pieced line takes new colours, shows and meta in place; anything // else about it is built anew. if (was.pieces) { if ( !piecewise(item) || lookOf.look(item) !== was.look || !flatEquals(item.positions, was.from) || item.revealFraction !== was.reveal || was.pieces.some((piece) => piece?.primitive.isDestroyed()) ) return false; looks.push(was.look); continue; } const look = lookOf.look(item); // Only its colour may change: its material takes it in place. if ( was.look !== look && !recolourable(was, item, lookOf) && !recolourableSolid(was, item, lookOf) && !recolourableOverlay(was, item, lookOf) ) return false; // A viewer destroyed under the set took its batch with it. if (was.batched?.isDestroyed()) return false; if (was.home?.isDestroyed()) return false; looks.push(look); if (was.deep !== undefined && record.deepLines?.isDestroyed()) return false; if (!was.clampTo) continue; const flat = flatEquals(item.positions, was.positions) ? was.positions : flatPositions(item.positions); // A segmented line that moves is built anew, segment by segment (so // one that moves every frame is not drawn until it stops: segments // are for lines that move only now and then). if (was.segments && !samePositions(flat, was.positions)) return false; // One with no length draws nothing, whatever its segments' looks. if (was.segments && !was.ground) continue; if (!drapedPatchable(record, was, flat)) return false; flats.set(item.id, flat); } const shared = sharedRecolours(parts, list, looks); if (!shared) return false; // Shared materials take their one colour once, before lines move off // them. for (const [material, item] of shared) paintLine(material, item.style); for (let k = 0; k < list.length; k++) { const item = list[k]; const was = parts.get(item.id); const show = item.show !== false; if (was.pieces) { was.id.meta = item.meta; writePieces(was, item); continue; } if (was.polyline || was.parked || was.batched) { patchUndraped(record, was, item, looks[k]); continue; } if (was.look !== looks[k] && was.deep === undefined) { // A line drawing on a shared material took its colour above. if (!was.shared || was.solo) paintLine(was.material, item.style); was.look = looks[k]; } if (was.deep !== undefined) { was.id.meta = item.meta; was.look = looks[k]; // One drawn for a draped line that runs where it ran takes its new // look in place (heat-lines pulse every frame). if (overlayRecoloured(record, was, item)) continue; // Built anew where it now runs, under the same pick id. const deep = record.deepLines; const old = was.deep; if (old) { dropFlow(record, old.appearance.material, item.style); dropFlow(record, old.depthFailAppearance.material, item.style); } was.deep = depthFailLine(record, item, was.id); if (was.deep) deep.add(was.deep); if (old) deep.remove(old); if (item.overlaid) overlayMoved(record, was, item); else if (was.overlayFrom) overlayLeft(record, was); continue; } was.id.meta = item.meta; if (was.segments) { if (!was.ground) continue; // A newer write supersedes one queued while the ground built. was.pendingItem = was.ground.ready ? undefined : item; if (was.ground.ready) writeSegments(was, item); continue; } const flat = flats.get(item.id); if (!samePositions(flat, was.positions)) { moveDraped(record, was, item, flat); continue; } if (was.material && revealed(item)) was.material.uniforms.reveal = revealUniform(item.revealFraction); if (was.solo) { // Not yet drawn, it is built again showing as asked. if (was.ground && was.ground.ready) showPart(was, show); else if (was.ground) moveDraped(record, was, item, flat); continue; } // A ground primitive still building takes its show once it is ready // (`swapReady`), so a show change never restarts the build. // A show queued while it built is stale once a newer one is applied. if (was.ground.ready) { showPart(was, show); was.pendingShow = undefined; } else was.pendingShow = show; } return true; } /** * An undraped line without a depth-fail colour in the set's polyline * collection, under pick id `id`; `reveal` is the material its reveal * is set on, or null. A hidden line that never settles (`park`) is * parked instead, out of the collection (`polyline` null, `parked` * true): the collection draws every line it holds, shown or not, each * on a material and command of its own, every frame; a hidden line * that settles costs nothing once in its static batch. */ function addPolyline(record, polylines, item, id, park = false) { if (park && item.show === false) return { polyline: null, reveal: null, parked: true }; const positions = linePositions(item); const reveal = revealed(item) ? revealUniform(item.revealFraction, positions) : undefined; const material = lineMaterial(record, item.style, reveal); const polyline = polylines.add({ positions, width: item.widthPx, material, show: item.show !== false, id, }); return { polyline, reveal: reveal === undefined ? null : material, parked: false, }; } /** * Whether an undraped line can be drawn in a static batch: solid, all of * it shown, at least half a pixel wide, and without a depth-fail colour * (those draw alone). */ const settles = (item) => item.mode !== 'draped' && item.frame !== 'inertial' && !item.depthFail && item.style.kind === 'solid' && // A batch draws one colour per line, no outline. !item.style.outline && !revealed(item) && // The collection draws no line under half a pixel wide; a batch // would. item.widthPx >= 0.5; const finitePoint = (p) => Number.isFinite(p.x) && Number.isFinite(p.y) && Number.isFinite(p.z); /** Whether a line's colour is drawn in a batch's translucent pass. */ const translucentLine = (item) => toColor(item.style.color).alpha < 1; /** * Stop waiting for a set's lines to settle: they changed. A static batch * still building drew them as they were, so it is dropped. */ function unsettle(record) { record.settled = 0; const pending = record.batchPending; if (!pending) return; record.batchPending = null; if (record.lineBox && !record.lineBox.isDestroyed()) for (const primitive of pending.primitives) record.lineBox.remove(primitive); } /** * Change an undraped line drawn in the collection or a static batch in * place: its show and colour, and where it runs. A batched line that * moves, or whose colour leaves its batch's pass, leaves the batch, * hidden there, for the collection, until the set settles again. */ function patchUndraped(record, was, item, look) { const show = item.show !== false; // The polyline's pick id and the batch instance's are this one. was.id.meta = item.meta; const recolour = was.look !== look; was.look = look; if (was.batched) { const stays = flatEquals(item.positions, was.positions) && (!recolour || translucentLine(item) === was.translucent); const attributes = was.batched.getGeometryInstanceAttributes(was.id); if (stays) { // A batch still building draws the colour it was built with. if (recolour) { if (record.batchPending) unsettle(record); attributes.color = Cesium.ColorGeometryInstanceAttribute.toValue( toColor(item.style.color), attributes.color, ); } attributes.show = Cesium.ShowGeometryInstanceAttribute.toValue( show, attributes.show, ); return; } attributes.show = Cesium.ShowGeometryInstanceAttribute.toValue( false, attributes.show, ); was.batched = null; was.positions = flatPositions(item.positions); Object.assign(was, addPolyline(record, record.polylines, item, was.id)); unsettle(record); return; } if (!show && !was.shape) { // Parked out of the collection, which would draw it on regardless // (a line that settles is hidden in its batch instead). if (was.polyline) { dropFlow(record, was.polyline.material, item.style); was.home.remove(was.polyline); was.polyline = null; was.reveal = null; requestRender(); } was.parked = true; return; } if (was.parked) { // Back in the collection, as it now is. Object.assign(was, addPolyline(record, was.home, item, was.id)); requestRender(); return; } // Only a change a batch would draw unsettles the set: a show is taken // when the batch swaps in, and lines that cannot settle are not in it. if (was.shape && (recolour || !flatEquals(item.positions, was.positions))) { was.positions = flatPositions(item.positions); unsettle(record); } // A line sent again where it runs keeps its positions: writing them // would have the collection rewrite its vertices. const drawn = was.polyline.positions; const unmoved = drawnAt(drawn, item.positions); // One that moves by as many points (a front stepping out) is written // into the points it has, which the polyline then takes again. const positions = unmoved || rewrite(drawn, item) ? drawn : linePositions(item); if (!unmoved) was.polyline.positions = positions; was.polyline.show = show; if (recolour) paintLine(was.polyline.material, item.style); if (was.reveal) was.reveal.uniforms.reveal = revealUniform( item.revealFraction, positions, ); } /** * Write a line's new positions into `drawn`, the Cartesians a polyline * draws (made by `linePositions`), when they are as many and convert one * for one (not geodesic): true if written, else false, writing nothing. */ function rewrite(drawn, item) { if (item.mode === 'geodesic' || !Array.isArray(drawn)) return false; const positions = item.positions; if (positions instanceof Float64Array) { if (positions.length !== drawn.length * 3) return false; for (let i = 0; i < drawn.length; i++) Cesium.Cartesian3.fromElements( positions[i * 3], positions[i * 3 + 1], positions[i * 3 + 2], drawn[i], ); return true; } if (positions.length !== drawn.length) return false; for (let i = 0; i < drawn.length; i++) toCartesianInto(positions[i], drawn[i]); return true; } /** * Whether `positions` (an item's, ECEF points or packed triples) are the * Cartesians a polyline already draws. False for any given by longitude * and latitude, which are converted, not compared. */ function drawnAt(drawn, positions) { if (!Array.isArray(drawn)) return false; if (positions instanceof Float64Array) { if (positions.length !== drawn.length * 3) return false; for (let i = 0; i < drawn.length; i++) { const p = drawn[i]; if ( !Object.is(p.x, positions[i * 3]) || !Object.is(p.y, positions[i * 3 + 1]) || !Object.is(p.z, positions[i * 3 + 2]) ) return false; } return true; } if (positions.length !== drawn.length) return false; for (let i = 0; i < drawn.length; i++) { const p = positions[i]; const q = drawn[i]; if ( !('x' in p) || !Object.is(p.x, q.x) || !Object.is(p.y, q.y) || !Object.is(p.z, q.z) ) return false; } return true; } /** * After a draw: a line set whose lines have not changed for * `SETTLE_FRAMES` drawn frames starts building its static batch, of all * its lines that `settles`, once some are still in the collection (when * it has a batch and only a few are, after `LONG_SETTLE_FRAMES`); one * built swaps in for the collection's lines it draws (`swapBatch`). * Unchanged lines in a polyline collection cost a material id a line * every frame; in a batch they cost nothing until they change. */ function settleLines(record) { if (!record.lineBox || record.lineBox.isDestroyed()) return; if (record.batchPending) { swapBatch(record); return; } if (record.settled > LONG_SETTLE_FRAMES) return; record.settled += 1; if ( record.settled !== SETTLE_FRAMES && record.settled !== LONG_SETTLE_FRAMES ) return; // The lines that can settle still in the collection: a batch is // rebuilt whole for them, so a few wait longer, as a few cost little. let loose = 0; for (const part of record.lineParts.values()) if (part.polyline && part.shape) loose += 1; if ( record.batch && loose < FEW_LOOSE_LINES && record.settled < LONG_SETTLE_FRAMES ) return; record.settled = LONG_SETTLE_FRAMES + 1; if (!loose) return; const members = []; for (const [itemId, part] of record.lineParts) { if (!part.shape || (!part.polyline && !part.batched)) continue; const item = record.items.get(itemId); if (!item || !settles(item)) continue; const positions = linePositions(item); // A batch that fails to build would throw in every frame after. if (!drawable(positions) || !positions.every(finitePoint)) continue; members.push({ part, item, positions }); } if (!members.some(({ part }) => part.polyline)) return; const groups = [[], []]; for (const member of members) { member.translucent = translucentLine(member.item); member.show = member.item.show !== false; groups[member.translucent ? 1 : 0].push( new Cesium.GeometryInstance({ geometry: new Cesium.PolylineGeometry({ positions: member.positions, width: member.item.widthPx, vertexFormat: Cesium.PolylineColorAppearance.VERTEX_FORMAT, // Straight between the positions, as the collection's lines // are (geodesic ones come densified). arcType: Cesium.ArcType.NONE, }), attributes: { color: Cesium.ColorGeometryInstanceAttribute.fromColor( toColor(member.item.style.color), ), show: new Cesium.ShowGeometryInstanceAttribute(member.show), }, id: member.part.id, }), ); member.flat = flatPositions(member.item.positions); } const primitives = []; for (const [translucent, geometryInstances] of groups.entries()) { if (!geometryInstances.length) continue; const primitive = new StaticLines({ geometryInstances, appearance: new Cesium.PolylineColorAppearance({ translucent: Boolean(translucent), }), // Hidden while it builds: the collection draws its lines. show: false, }); primitive.translucentLines = Boolean(translucent); primitives.push(primitive); record.lineBox.add(primitive); } record.batchPending = { primitives, members }; } /** * A static batch built: it draws its lines in place of the collection's * polylines and the batch before it, each line showing as its item now * asks (shows changed while it built). */ function swapBatch(record) { const { primitives, members } = record.batchPending; const failed = primitives.find((p) => p.failed); if (failed) { // The collection draws on; the set settles no more. unsettle(record); record.lineBox = null; throw failed.failed; } if (primitives.some((p) => !p.ready)) return; record.batchPending = null; const box = record.lineBox; for (const primitive of record.batch ?? []) box.remove(primitive); record.batch = primitives; const byPass = new Map(primitives.map((p) => [p.translucentLines, p])); let removed = 0; for (const { part, item, translucent, show, flat } of members) { const batch = byPass.get(translucent); if (part.polyline) { record.polylines.remove(part.polyline); part.polyline = null; part.reveal = null; removed += 1; } part.batched = batch; part.translucent = translucent; part.positions = flat; const now = record.items.get(item.id)?.show !== false; if (now !== show) { const attributes = batch.getGeometryInstanceAttributes(part.id); attributes.show = Cesium.ShowGeometryInstanceAttribute.toValue( now, attributes.show, ); } } for (const primitive of primitives) primitive.show = true; if (removed) requestRender(); } /** * Draw a draped line where it now runs, in this frame: on a ground * primitive of its own built at once, in place of its own one (or of its * place in its batch, hidden there). Positions that make no line draw * nothing until they do again. */ function moveDraped(record, part, item, flat) { const host = record.host; const old = part.ground; if (old && old !== part.batch) { dropFlow(record, part.material, item.style); for (const list of new Set([record.pending, record.ground])) { const at = list?.indexOf(old) ?? -1; if (at >= 0) list.splice(at, 1); } host.remove(old); } else if (old) { // Its batch draws on without it, hidden now or once it is ready. part.batchHidden = true; if (old.ready) showOn(old, part.id, false); } hideRetiring(record, item.id); part.solo = true; part.positions = flat; part.pendingShow = undefined; const positions = linePositions(item); part.material = null; part.ground = drawable(positions) ? drapedPrimitive(record, item, part, true, positions) : null; if (part.ground) host.add(part.ground); } /** * Hide where the host a set is rebuilding from still draws a draped line, * once the line is drawn where it now is: else both would draw (and * pick) until the rebuild is ready. */ function hideRetiring(record, id) { const part = record.retiring && record.retiringParts?.get(id); const ground = part?.ground; if (!ground || ground.isDestroyed() || !ground.ready) return; // A segmented line draws under a pick id a segment. if (part.segments) for (const segment of part.segments) { if (segment) showOn(ground, segment, false); } else showOn(ground, part.id, false); } /** A draped line part's show, on its ready ground primitive. */ const showPart = (part, show) => showOn(part.ground, part.id, show); /** The show of the instance under pick id `id` in a ready ground primitive. */ function showOn(ground, id, show) { const attributes = ground.getGeometryInstanceAttributes(id); attributes.show = Cesium.ShowGeometryInstanceAttribute.toValue( show, attributes.show, ); } /** * The shows patched in while a set's ground primitives were building, * and the lines drawn alone since, hidden in their batches. */ function showPending(record) { for (const part of record.shapeParts?.values() ?? []) { // A shape drawn alone since it moved stays hidden in its batch. if (part.batchHidden && part.batch && !part.batch.isDestroyed()) showOn(part.batch, part.id, false); if ( part.pendingShow !== undefined && part.ground && !part.ground.isDestroyed() ) { showOn(part.ground, part.id, part.pendingShow); part.pendingShow = undefined; } if ( part.pendingColour !== undefined && part.ground && !part.ground.isDestroyed() ) { colourOn(part.ground, part.id, part.pendingColour); part.pendingColour = undefined; } } for (const part of record.lineParts?.values() ?? []) { for (const piece of part.pieces ?? []) if ( piece?.pendingShow !== undefined && !piece.primitive.isDestroyed() && piece.primitive.ready ) { showOn(piece.primitive, piece.id, piece.pendingShow); piece.pendingShow = undefined; } if (part.batchHidden && part.batch && !part.batch.isDestroyed()) showOn(part.batch, part.id, false); if ( part.pendingShow !== undefined && part.ground && !part.ground.isDestroyed() ) { showPart(part, part.pendingShow); part.pendingShow = undefined; } if (part.pendingItem && part.ground && !part.ground.isDestroyed()) { writeSegments(part, part.pendingItem); part.pendingItem = undefined; } } } /** Whether a line is drawn segment by segment, in colours or shows of their own. */ const segmented = (item) => item.segmentColors != null || item.segmentShow != null; /** A segment's colour and whether it shows. */ const segmentLook = (item, j) => ({ color: toColor(item.segmentColors?.[j] ?? item.style.color), show: item.show !== false && item.segmentShow?.[j] !== false, }); /** What a segment draws, to tell whether an upsert changes it. */ const segmentKey = ({ color, show }) => `${color.red},${color.green},${color.blue},${color.alpha},${show}`; /** * A draped line drawn segment by segment: a ground polyline instance a * segment, each with a pick id of its own that reads as the line's (and * that height queries see through), so its colour and show change in * place. A segment of no length draws nothing. */ function segmentInstances(record, item, part) { const points = linePositions(item); const instances = []; part.segments = []; part.drawn = []; for (let j = 0; j + 1 < points.length; j++) { if (Cesium.Cartesian3.equals(points[j], points[j + 1])) { part.segments.push(null); part.drawn.push(null); continue; } const id = Object.create(part.id); record.pickIds.push(id); const look = segmentLook(item, j); part.segments.push(id); part.drawn.push(segmentKey(look)); instances.push( new Cesium.GeometryInstance({ geometry: new Cesium.GroundPolylineGeometry({ positions: [points[j], points[j + 1]], width: item.widthPx, arcType: Cesium.ArcType.GEODESIC, }), attributes: { color: Cesium.ColorGeometryInstanceAttribute.fromColor(look.color), show: new Cesium.ShowGeometryInstanceAttribute(look.show), }, id, }), ); } return instances; } /** A segmented line's colours and shows, on its ready ground primitive. */ function writeSegments(part, item) { for (let j = 0; j < part.segments.length; j++) { const id = part.segments[j]; if (!id) continue; const look = segmentLook(item, j); const key = segmentKey(look); if (key === part.drawn[j]) continue; part.drawn[j] = key; const attributes = part.ground.getGeometryInstanceAttributes(id); attributes.color = Cesium.ColorGeometryInstanceAttribute.toValue( look.color, attributes.color, ); attributes.show = Cesium.ShowGeometryInstanceAttribute.toValue( look.show, attributes.show, ); } } /** One host for a set's own collection and its ground primitives. */ function collect(own, ground) { const host = new Cesium.PrimitiveCollection(); if (own) host.add(own); for (const primitive of ground) host.add(primitive); return host; } const heightOf = (pos) => 'x' in pos ? Cesium.Cartographic.fromCartesian(toCartesian(pos)).height : (pos.height ?? 0); function shapeGeometry(item, vertexFormat) { const g = item.geometry; const extrudedHeight = item.extrudeHeight; switch (g.kind) { case 'polygon': { const [outer, ...holes] = g.rings.map((ring) => ring.map(toCartesian)); const hierarchy = new Cesium.PolygonHierarchy( outer, holes.map((h) => new Cesium.PolygonHierarchy(h)), ); const polygon = { polygonHierarchy: hierarchy, height: g.perPositionHeight ? undefined : heightOf(g.rings[0][0]), extrudedHeight, perPositionHeight: g.perPositionHeight, }; return { fill: new Cesium.PolygonGeometry({ ...polygon, vertexFormat }), // Extruded, its outline is the volume's edges (both faces and the // walls' corners), as the entities' extruded polygons draw it. outline: item.outline && extrudedHeight !== undefined ? new Cesium.PolygonOutlineGeometry(polygon) : undefined, // Its holes are outlined too, as the entities' polygons outline them. rings: [outer, ...holes], }; } case 'ellipse': { const ellipse = { center: toCartesian(g.center), semiMajorAxis: g.semiMajor, semiMinorAxis: g.semiMinor, rotation: g.rotation ?? 0, height: heightOf(g.center), extrudedHeight, }; return { fill: new Cesium.EllipseGeometry({ ...ellipse, vertexFormat }), // Its outline is an outline geometry, as the entities' ellipses draw it. outline: item.outline ? new Cesium.EllipseOutlineGeometry(ellipse) : undefined, }; } case 'rectangle': return { fill: new Cesium.RectangleGeometry({ rectangle: Cesium.Rectangle.fromDegrees( g.rect.west, g.rect.south, g.rect.east, g.rect.north, ), height: g.height ?? 0, extrudedHeight, // An image fill turns with the rectangle, as a KML overlay's does. rotation: g.rotation ?? 0, stRotation: g.rotation ?? 0, vertexFormat, }), }; case 'wall': { // Up from `minimumHeights` (the ellipsoid) to `maximumHeights` (the // positions' own), as the entities' walls draw. const wall = { positions: g.positions.map(toCartesian), minimumHeights: g.minimumHeights, maximumHeights: g.maximumHeights, }; return { fill: new Cesium.WallGeometry({ ...wall, vertexFormat }), outline: item.outline ? new Cesium.WallOutlineGeometry(wall) : undefined, }; } default: throw new Error(`the Cesium renderer has no ${g.kind} shapes`); } } /** * A clamped shape's fill geometry, on the ellipsoid for draping; an * ellipse with an image fill is cut finely, so a round image's edge runs * round. */ function groundGeometry(item, imageFill = false) { const g = item.geometry; switch (g.kind) { case 'polygon': { const [outer, ...holes] = g.rings.map((ring) => ring.map(toCartesian)); return new Cesium.PolygonGeometry({ polygonHierarchy: new Cesium.PolygonHierarchy( outer, holes.map((h) => new Cesium.PolygonHierarchy(h)), ), }); } case 'ellipse': { const major = g.semiMajor; const minor = g.semiMinor; // A semi-minor axis longer than the semi-major one is drawn as // Cesium's semi-major axis, a quarter turn on. const crossed = minor > major; return new Cesium.EllipseGeometry({ center: toCartesian(g.center), semiMajorAxis: crossed ? minor : major, semiMinorAxis: crossed ? major : minor, rotation: (g.rotation ?? 0) + (crossed ? Math.PI / 2 : 0), ...(imageFill ? { granularity: IMAGE_ELLIPSE_GRANULARITY, vertexFormat: Cesium.MaterialAppearance.MaterialSupport.TEXTURED .vertexFormat, } : {}), }); } case 'rectangle': return new Cesium.RectangleGeometry({ rectangle: Cesium.Rectangle.fromDegrees( g.rect.west, g.rect.south, g.rect.east, g.rect.north, ), rotation: g.rotation ?? 0, stRotation: g.rotation ?? 0, }); default: throw new Error(`the Cesium renderer cannot clamp ${g.kind} shapes`); } } /** The surface's height under a position now, metres; 0 where unknown. */ function surfaceHeight(cartesian, clampTo) { const at = Cesium.Cartographic.fromCartesian(cartesian); if (!at) return 0; const globe = scene.globe; if (clampTo !== 'tiles' && globe?.show !== false) { const h = globe?.getHeight?.(at); if (Number.isFinite(h)) return h; } if (clampTo !== 'terrain' && scene.sampleHeightSupported) { try { const h = scene.sampleHeight(at); if (Number.isFinite(h)) return h; } catch { // No depth to sample in this scene: the ellipsoid. } } return 0; } /** * A clamped shape a ground primitive cannot drape, as one standing on the * surface, unclamped: an extruded one (its base at the lowest surface * height under it, up to its `extrudeHeight`), a wall (its foot on the * surface under each position, its heights above it), and an image fill * where the scene cannot drape materials (on the surface under it). The * surface is read when the set is built. Any other item is itself. */ function standing(record, item) { if (item.height !== 'clampGround') return item; const g = item.geometry; const imageFill = item.fill && typeof item.fill === 'object' && !Array.isArray(item.fill); if ( item.extrudeHeight === undefined && g.kind !== 'wall' && !(imageFill && scene.context?.depthTexture === false) ) return item; const clampTo = item.clampTo ?? record.spec.clampTo ?? 'both'; const at = (cartesian, height) => { const c = Cesium.Cartographic.fromCartesian(cartesian); return { lon: Cesium.Math.toDegrees(c.longitude), lat: Cesium.Math.toDegrees(c.latitude), height, }; }; const lowest = (points) => Math.min(...points.map((p) => surfaceHeight(p, clampTo))); let geometry; switch (g.kind) { case 'polygon': { const rings = g.rings.map((ring) => ring.map(toCartesian)); const base = lowest(rings.flat()); geometry = { kind: 'polygon', rings: rings.map((ring) => ring.map((p) => at(p, base))), }; break; } case 'ellipse': { const center = toCartesian(g.center); geometry = { ...g, center: at(center, lowest([center])) }; break; } case 'rectangle': { const r = g.rect; const corners = [ [r.west, r.south], [r.east, r.south], [r.east, r.north], [r.west, r.north], [(r.west + r.east) / 2, (r.south + r.north) / 2], ].map(([lon, lat]) => Cesium.Cartesian3.fromDegrees(lon, lat)); geometry = { ...g, height: lowest(corners) }; break; } case 'wall': { const points = g.positions.map(toCartesian); const feet = points.map((p) => surfaceHeight(p, clampTo)); geometry = { kind: 'wall', positions: points.map((p, i) => at(p, feet[i])), minimumHeights: feet.map((h, i) => h + (g.minimumHeights?.[i] ?? 0)), maximumHeights: feet.map( (h, i) => h + (g.maximumHeights?.[i] ?? heightOf(g.positions[i])), ), }; break; } default: return item; } return { ...item, geometry, height: 'absolute' }; } /** * A clamped shape's outline as rings on the surface, each closed: a * polygon's rings, an ellipse cut in 64, a rectangle's turned corners. */ function outlineRings(item) { const g = item.geometry; const closed = (ring) => ring.length && !Cesium.Cartesian3.equals(ring[0], ring.at(-1)) ? [...ring, ring[0]] : ring; switch (g.kind) { case 'polygon': return g.rings.map((ring) => closed(ring.map(toCartesian))); case 'ellipse': { const center = toCartesian(g.center); const enu = Cesium.Transforms.eastNorthUpToFixedFrame(center); const turn = g.rotation ?? 0; const ring = []; for (let k = 0; k < 64; k++) { const a = (k / 64) * 2 * Math.PI; // Along the semi-major axis at `rotation` counter-clockwise from north. const major = g.semiMajor * Math.cos(a); const minor = g.semiMinor * Math.sin(a); const east = -major * Math.sin(turn) + minor * Math.cos(turn); const north = major * Math.cos(turn) + minor * Math.sin(turn); ring.push( Cesium.Matrix4.multiplyByPoint( enu, new Cesium.Cartesian3(east, north, 0), new Cesium.Cartesian3(), ), ); } return [closed(ring)]; } case 'rectangle': { const r = g.rect; const cx = (r.west + r.east) / 2; const cy = (r.south + r.north) / 2; const c = Math.cos(g.rotation ?? 0); const sn = Math.sin(g.rotation ?? 0); const ring = [ [r.west, r.south], [r.east, r.south], [r.east, r.north], [r.west, r.north], ].map(([lon, lat]) => { const dx = lon - cx; const dy = lat - cy; return Cesium.Cartesian3.fromDegrees( cx + dx * c - dy * sn, cy + dx * sn + dy * c, ); }); return [closed(ring)]; } default: return []; } } /** * A set's clamped fills as ground primitives, packed as the entities' * ground batches are: a fill goes in the first batch it overlaps nothing * in, so overlapping translucent fills blend over each other. */ 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(); // The shapes as the host this build replaces draws them, while it // still draws; a host already retiring keeps its own. if (!record.retiring) record.retiringShapeParts = record.shapeParts ?? null; record.shapeParts = null; // Clamped outlines, drawn as draped lines: a ground polyline each. const outlines = []; for (const item of items) { if (item.outline) outlines.push(item); if (!item.fill || item.outlineOnly) { parts.set(item.id, { look: lookOf(item), id: null, ground: null, pulse: pulseOf(item), show: item.show !== false, }); continue; } const objectFill = typeof item.fill === 'object' && !Array.isArray(item.fill) ? item.fill : null; const imageFill = objectFill; if (imageFill && !imageFill.image) throw new Error('the Cesium renderer fills shapes with colours only'); // Refused before anything is made, so nothing is left half built. const image = imageFill ? imageAt(imageFill.image) : null; // Hidden colour fills 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. Hidden // image fills are not passed in (`hiddenFillBuilds`): their textures // load when they show. let geometry; try { geometry = groundGeometry(item, Boolean(imageFill)); } catch (error) { if (item.show === false) continue; throw error; } const part = { look: lookOf(item), id: pickId(record, item), ground: null, pulse: pulseOf(item), show: item.show !== false, }; parts.set(item.id, part); const show = new Cesium.ShowGeometryInstanceAttribute( item.show !== false, ); const instance = new Cesium.GeometryInstance({ geometry, attributes: imageFill ? { show } : { color: Cesium.ColorGeometryInstanceAttribute.fromColor( toColor(item.fill), ), show, }, id: part.id, }); const clampTo = item.clampTo ?? record.spec.clampTo ?? 'both'; if (imageFill) { // An image fill is a ground primitive of its own, with its material. // (Cesium turns its texture wrongly across the antimeridian: its // rotation points are taken against a centre wrapped to ±180°.) batches.push({ clampTo, instances: [instance], parts: [part], image, imageFill, }); continue; } const rectangle = instance.geometry.rectangle; let batch = batches.find( (b) => b.rectangles && b.clampTo === clampTo && !b.rectangles.collides(rectangle), ); if (!batch) { 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; const grounds = batches.map((batch) => { const material = batch.imageFill ? imageMaterial(batch.image, batch.imageFill.repeat) : null; const ground = new Ground({ geometryInstances: batch.instances, classificationType: classificationOf(batch.clampTo), allowPicking: pickable, ...(material ? { appearance: new Cesium.MaterialAppearance({ material, materialSupport: Cesium.MaterialAppearance.MaterialSupport.TEXTURED, translucent: true, flat: true, }), } : {}), }); // Its material holds the texture, which the primitive leaves alone: // it goes with the primitive, which may outlive the host that built it // while a rebuild's ground primitives get ready. if (material) { const destroyGround = ground.destroy.bind(ground); ground.destroy = () => { if (!material.isDestroyed()) material.destroy(); return destroyGround(); }; } for (const part of batch.parts) part.ground = ground; return ground; }); for (const item of outlines) { const rings = outlineRings(item).filter((ring) => ring.length >= 2); if (!rings.length) continue; const part = parts.get(item.id); // Picked as its shape. part.id ??= pickId(record, item); // A pulsing outline's rings share one colour, its material's. const pulsing = Boolean(part.pulse); const outline = new Cesium.GroundPolylinePrimitive({ geometryInstances: rings.map( (positions) => new Cesium.GeometryInstance({ geometry: new Cesium.GroundPolylineGeometry({ positions, width: item.outlineWidth ?? 1, arcType: Cesium.ArcType.GEODESIC, }), attributes: { color: Cesium.ColorGeometryInstanceAttribute.fromColor( toColor(item.outline), ), show: new Cesium.ShowGeometryInstanceAttribute( item.show !== false, ), }, id: part.id, }), ), appearance: pulsing ? new Cesium.PolylineMaterialAppearance({ material: Cesium.Material.fromType('Color', { color: toColor(item.outline), }), }) : new Cesium.PolylineColorAppearance(), classificationType: classificationOf( item.clampTo ?? record.spec.clampTo ?? 'both', ), allowPicking: pickable, }); // Any change to an outlined clamped shape rebuilds the set. part.outlineGround = outline; grounds.push(outline); } 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`). A plain colour fill whose geometry alone * changed is drawn alone where it now is (`moveShape`), while no more * than `MOVING_SHAPES` would be. False, changing nothing, otherwise. */ function patchShapes(record, list) { const parts = record.shapeParts; const solids = record.solidParts; if (record.kind !== 'shapes' || (!parts && !solids)) return false; // Each item's way in: `true` moves it (`moveShape`), `'solid'` changes // an unclamped one in place, `'recolour'` recolours a clamped one in // place, else it only shows, hides or takes its `meta`. const moves = []; for (const item of list) { const solid = solids?.get(item.id); if (solid) { if (!solidPatchable(solid, item)) return false; moves.push('solid'); continue; } const was = parts?.get(item.id); if (!was || was.outlineGround) return false; if (was.ground?.isDestroyed() || was.batch?.isDestroyed()) return false; if (sameLook(was, item)) { moves.push(false); continue; } if (groundRecolourable(was, item)) { moves.push('recolour'); continue; } if (!movable(record, was, item)) return false; moves.push(true); } // Drawn alone after this upsert: a few at most, or the batches rebuild. const alone = new Set(); for (const [id, part] of parts ?? []) if (part.solo) alone.add(id); list.forEach((item, k) => moves[k] === true && alone.add(item.id)); // Those the host still retiring draws alone count too, until it goes. let retiringAlone = 0; if (record.retiring) for (const part of record.retiringShapeParts?.values() ?? []) if (part.solo && part.ground && !part.ground.isDestroyed()) retiringAlone += 1; if (alone.size + retiringAlone > MOVING_SHAPES) return false; list.forEach((item, k) => { if (moves[k] === 'solid') return patchSolid(solids.get(item.id), item); const was = parts.get(item.id); if (moves[k] === true) return moveShape(record, was, item); if (moves[k] === 'recolour') recolourGround(was, item); if (!was.ground) return; was.id.meta = item.meta; const show = item.show !== false; was.show = show; if (was.ground.ready) { showOn(was.ground, was.id, show); was.pendingShow = undefined; } else if (was.solo) { // Not yet drawn, it is built again showing as asked. moveShape(record, was, item); } else was.pendingShow = show; }); return true; } /** Whether a fill or outline is a plain colour (or none). */ const plainColour = (value) => value == null || typeof value === 'string' || Array.isArray(value); /** * How a shape draws but for its colours, pulse, show and `meta`, and * whether it has a fill and an outline: shapes alike in it draw alike, * but for their colours. */ const colourlessLookOf = (item) => { const { show, meta, fill, outline, animate, ...look } = item; return plainCopy({ ...look, filled: fill != null, outlined: outline != null, }); }; /** * Whether an upsert changes a shape's colours, its pulse, its show or its * `meta` and nothing else, its fill and outline staying plain colours: * those it takes in place. */ function colourOnly(look, item) { if (!plainColour(item.fill) || !plainColour(item.outline)) return false; if (!plainColour(look.fill) || !plainColour(look.outline)) return false; return sameValues(colourlessLookOf(look), colourlessLookOf(item)); } /** * Whether a clamped colour fill's upsert recolours it (or changes its * pulse), and changes nothing else but its show and `meta`. */ const groundRecolourable = (was, item) => Boolean(was.id && was.ground) && colourFill(item) && colourFill(was.look) && colourOnly(was.look, item) && !sameValues( plainCopy({ fill: was.look.fill, animate: was.look.animate ?? null }), { fill: item.fill, animate: item.animate ?? null }, ); /** * Whether an unclamped shape's upsert only recolours, pulses, shows or * hides it: a colour drawn opaque cannot become translucent in place. */ function solidPatchable(part, item) { if (part.image) return imagePatchable(part, item); if (!colourOnly(part.look, item)) return false; if (part.fill?.isDestroyed?.() || part.outline?.isDestroyed?.()) return false; // Not yet drawn: it has no colours to write, and rebuilds instead. if ( (part.fill && !part.fill.ready) || (part.outline && !part.outline.ready) ) return false; const pulses = Boolean(item.animate); const fits = (translucent, colour) => colour == null || translucent || (!pulses && toColor(colour).alpha >= 1); // Ring outlines are polylines, whose materials take any alpha in place. return ( fits(part.translucent.fill, item.fill) && fits(part.translucent.outline || !part.outline, item.outline) ); } /** * Whether an unclamped image fill's upsert changes only its image (a * canvas, under a new key for new content), its show or its `meta`: its * texture takes a new canvas in place. */ function imagePatchable(part, item) { const fill = item.fill; if (!fill || typeof fill !== 'object' || Array.isArray(fill)) return false; if (!fill.image?.canvas || item.animate || part.pulse) return false; if (!part.fill || part.fill.isDestroyed() || !part.fill.ready) return false; const { fill: was, ...look } = part.look; const { fill: now, show, meta, ...next } = item; return ( sameValues(look, next) && sameValues(was.repeat ?? null, fill.repeat ?? null) ); } /** * An image fill's texture takes `canvas`: copied into the texture it has * where the size is the same, else a texture of its own, which the * material holds (and destroys) from this frame on. Without a drawing * context (a scene with no WebGL), the material takes the canvas, as it * did when built. */ function writeImage(part, canvas) { const image = part.image; const context = scene.context; if (!context) { image.material.uniforms.image = canvas; return; } const texture = image.texture; if ( texture && !texture.isDestroyed() && texture.width === canvas.width && texture.height === canvas.height ) { texture.copyFrom({ source: canvas }); return; } dropPendingTexture(image); image.texture = new Cesium.Texture({ context, source: canvas }); image.material.uniforms.image = image.texture; } /** * Destroys an image fill's newest texture if its material has not taken * it yet. A material takes a texture (and destroys it later) only when it * next updates, so one replaced or disposed before then is no one's. */ function dropPendingTexture(image) { const texture = image.texture; if (!texture || texture.isDestroyed()) return; if (materialTexture(image.material, 'image') === texture) return; texture.destroy(); image.texture = null; } /** An instance's colour, in a ready primitive. */ function colourOn(primitive, id, color) { const attributes = primitive.getGeometryInstanceAttributes(id); attributes.color = Cesium.ColorGeometryInstanceAttribute.toValue( color, attributes.color, ); } /** An unclamped shape changed in place: its colours, pulse, show and `meta`. */ function patchSolid(part, item) { const image = part.image ? item.fill.image : null; if (image && (image.key !== part.look.fill.image.key || !image.key)) writeImage(part, image.canvas); part.look = lookOf(item); part.pulse = pulseOf(item); part.id.meta = item.meta; part.show = item.show !== false; for (const primitive of [part.fill, part.outline]) if (primitive) primitive.show = part.show; for (const polyline of part.rings) polyline.show = part.show; paintSolid( part, part.pulse ? pulseAlpha(part.pulse, performance.now()) : null, ); } /** * Write an unclamped shape's colours where it draws: its own, or with * `alpha` (a pulse's) in place of theirs. A primitive not yet ready * takes them when it is (`runPulses`, or its next patch). */ function paintSolid(part, alpha) { const look = part.look; // Primitives copy the colour they are given; polylines keep theirs. const tint = (colour, result) => { const base = baseColour(part, colour); return alpha === null ? Cesium.Color.clone(base, result) : base.withAlpha(alpha, result); }; if ( look.fill && !part.image && part.fill?.ready && !part.fill.isDestroyed() ) colourOn(part.fill, part.id, tint(look.fill, scratchColour)); // An image fill pulses through its material's colour, white at rest. if (part.image) part.image.material.uniforms.color = Cesium.Color.WHITE.withAlpha( alpha ?? 1, ); if (look.outline) { if (part.outline?.ready && !part.outline.isDestroyed()) colourOn(part.outline, part.id, tint(look.outline, scratchColour)); for (const polyline of part.rings) polyline.material.uniforms.color = tint(look.outline); } } /** * A clamped colour fill recoloured in place, on its ground primitive when * it is ready, else once it is (`showPending`). */ function recolourGround(part, item) { part.look = lookOf(item); part.pulse = pulseOf(item); const colour = toColor(item.fill); if (part.ground.ready) { colourOn(part.ground, part.id, colour); part.pendingColour = undefined; } else part.pendingColour = colour; } /** * Before a frame draws: pulsing shapes take their alpha now, where they * draw (on primitives that are ready). Whether any pulses, so frames go * on being asked for. */ function runPulses() { const now = performance.now(); let pulsing = false; for (const record of sets.values()) { if (record.kind !== 'shapes' || record.spec.show === false) continue; if (!record.mayPulse && !record.retiring) continue; for (const part of record.solidParts?.values() ?? []) { if (!part.pulse || !part.show) continue; // Only what it draws pulses: a shape with nothing drawn asks for // no frames. const live = (primitive) => primitive && !primitive.isDestroyed(); if (!live(part.fill) && !live(part.outline) && !part.rings.length) continue; pulsing = true; paintSolid(part, pulseAlpha(part.pulse, now)); } for (const parts of [record.shapeParts, record.retiringShapeParts]) for (const part of parts?.values() ?? []) { if (!part.pulse || !part.show) continue; const ground = part.ground; const imageFill = typeof part.look.fill === 'object' && !Array.isArray(part.look.fill); if (ground && !ground.isDestroyed() && imageFill) { // An image fill, a ground primitive of its own, pulses through // its material's colour. pulsing = true; ground.appearance.material.uniforms.color = Cesium.Color.WHITE.withAlpha(pulseAlpha(part.pulse, now)); } else if (ground && !ground.isDestroyed()) { // One still building asks for frames, to pulse once it is ready. pulsing = true; if (ground.ready) colourOn( ground, part.id, baseColour(part, part.look.fill).withAlpha( pulseAlpha(part.pulse, now), scratchColour, ), ); } // A clamped outline pulses through its material's colour. const outline = part.outlineGround; if (outline && !outline.isDestroyed() && part.look.outline) { pulsing = true; outline.appearance.material.uniforms.color = baseColour( part, part.look.outline, ).withAlpha(pulseAlpha(part.pulse, now)); } } } return pulsing; } const scratchColour = new Cesium.Color(); /** * A part's colour as a Cesium colour, parsed once for each colour its * look holds (a patch gives it a new look, and new values). */ function baseColour(part, colour) { const cache = part.baseColours ?? (part.baseColours = new Map()); let base = cache.get(colour); if (!base) { if (cache.size > 4) cache.clear(); base = toColor(colour); cache.set(colour, base); } return base; } /** Whether a clamped item is a plain colour fill, drawn in a batch. */ const colourFill = (item) => item.height === 'clampGround' && Boolean(item.fill) && !item.outlineOnly && !item.outline && item.extrudeHeight === undefined && (typeof item.fill !== 'object' || Array.isArray(item.fill)); /** How a clamped shape draws, but for its geometry, show and `meta`. */ const placedLookOf = (item) => { const { show, meta, geometry, ...look } = item; return plainCopy(look); }; /** * Whether a clamped colour fill's upsert moves or reshapes it and nothing * else: then it is drawn alone where it now is, built in this frame, * which needs Cesium's terrain heights loaded. */ function movable(record, was, item) { if (!was.id || !was.ground || !colourFill(item)) return false; if (!colourFill(was.look)) return false; if (!sameValues(placedLookOf(was.look), placedLookOf(item))) return false; const g = item.geometry; if (!['polygon', 'ellipse', 'rectangle'].includes(g?.kind)) return false; return groundSyncs() && typeof record.host?.add === 'function'; } /** * Draw a clamped colour fill where it now is, in this frame: on a ground * primitive of its own built at once, in place of its own one (or of its * place in its batch, hidden there), as a moved draped line is drawn * (`moveDraped`). A shape dragged every frame draws every frame, where a * rebuild would build its batch anew each time and never finish. */ function moveShape(record, part, item) { const host = record.host; // Built first: geometry it cannot build leaves the part as it was. const geometry = groundGeometry(item); if (part.solo) { if (part.ground && !part.ground.isDestroyed()) host.remove(part.ground); } else { part.batch = part.ground; part.batchHidden = true; // Its batch draws on without it, hidden now or once it is ready. if (part.batch.ready) showOn(part.batch, part.id, false); } hideRetiringShape(record, item.id); record.shapesStill = 0; part.solo = true; part.pendingShow = undefined; part.look = lookOf(item); part.pulse = pulseOf(item); part.show = item.show !== false; part.pendingColour = undefined; part.id.meta = item.meta; const pickable = record.spec.pickable !== false; const Ground = pickable ? Cesium.GroundPrimitive : UnpickableGroundPrimitive; part.ground = new Ground({ geometryInstances: [ new Cesium.GeometryInstance({ geometry, attributes: { color: Cesium.ColorGeometryInstanceAttribute.fromColor( toColor(item.fill), ), show: new Cesium.ShowGeometryInstanceAttribute(item.show !== false), }, id: part.id, }), ], classificationType: classificationOf( item.clampTo ?? record.spec.clampTo ?? 'both', ), allowPicking: pickable, asynchronous: false, }); host.add(part.ground); } /** * Hide where the host a set is rebuilding from still draws a clamped * shape, once it is drawn where it now is: else both would draw (and * pick) until the rebuild is ready. */ function hideRetiringShape(record, id) { const part = record.retiring && record.retiringShapeParts?.get(id); const ground = part?.ground; if (!ground || ground.isDestroyed() || !ground.ready) return; const hidden = (record.retiringHiddenShapes ??= new Set()); // Only one it drew: one hidden there already stays hidden. if (!hidden.has(id) && !shownOn(ground, part.id)) return; showOn(ground, part.id, false); hidden.add(id); } /** Whether the instance under pick id `id` in a ready ground primitive shows. */ const shownOn = (ground, id) => ground.getGeometryInstanceAttributes(id).show[0] !== 0; /** * Show again the shapes `hideRetiringShape` hid where the retiring host * draws them: the host that drew them alone is gone before it was ready. */ function showRetiringShapes(record) { const hidden = record.retiringHiddenShapes; record.retiringHiddenShapes = null; if (!record.retiring || !hidden) return; for (const id of hidden) { const ground = record.retiringShapeParts?.get(id)?.ground; if (!ground || ground.isDestroyed() || !ground.ready) continue; // As it is now: one since hidden or removed stays hidden. const item = record.items.get(id); if (!item || item.show === false) continue; showOn(ground, record.retiringShapeParts.get(id).id, true); } } /** * After a draw: a shape set whose shapes drawn alone have not moved for * `SETTLE_FRAMES` drawn frames rebuilds, so they go back into its * batches; the host drawing them alone draws until the rebuild is ready. */ function settleShapes(record) { if (record.pending || !record.shapeParts) return; let alone = false; for (const part of record.shapeParts.values()) if (part.solo) { alone = true; break; } if (!alone) return; record.shapesStill = (record.shapesStill ?? 0) + 1; if (record.shapesStill < SETTLE_FRAMES) return; record.shapesStill = 0; record.rebuild(); requestRender(); } /** 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) { // Refused before anything is built: a pulse it cannot run. record.mayPulse = false; for (const item of record.items.values()) if (pulseOf(item)) record.mayPulse = true; const host = new Cesium.PrimitiveCollection(); const outlines = new Cesium.PolylineCollection(); const clamped = []; // Each unclamped item as drawn, for upserts that only recolour, show or // hide it (`patchShapes`), and its pulse. // Published once the build has gone through. const solids = new Map(); record.solidParts = null; // Image fills' materials hold their textures, which primitives leave // alone: the host destroys them as it goes. const materials = []; // Image fills, whose newest texture the material may not hold yet. const images = []; const ownMaterial = (material) => { if (!materials.length) { const destroyHost = host.destroy.bind(host); host.destroy = () => { for (const image of images.splice(0)) dropPendingTexture(image); for (const owned of materials.splice(0)) if (!owned.isDestroyed()) owned.destroy(); return destroyHost(); }; } materials.push(material); return material; }; for (const given of record.items.values()) { const item = standing(record, given); // Clamped ones are built hidden as well (`groundFills`), when they // are a colour 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 : null; if (imageFill && !imageFill.image) throw new Error('the Cesium renderer fills shapes with colours only'); // A colour fill's geometry carries what its appearance reads, as the // entities' do. With texture coordinates too, Cesium packs them with // the normals, which a colour appearance then misreads: a lit colour // fill shaded darker than the same entity. const shape = shapeGeometry( item, imageFill ? Cesium.MaterialAppearance.MaterialSupport.TEXTURED.vertexFormat : Cesium.PerInstanceColorAppearance.VERTEX_FORMAT, ); const id = pickId(record, item); const pulse = pulseOf(item); const part = { look: lookOf(item), id, fill: null, outline: null, rings: [], pulse, // A pulsing colour is drawn translucent whatever its alpha now. translucent: { fill: false, outline: false }, show: true, }; solids.set(item.id, part); const solid = item.extrudeHeight !== undefined; // `lit`: shaded by Cesium's light, or flat; by default solids are lit. const lit = item.lit ?? solid; if (imageFill && !item.outlineOnly) { const material = ownMaterial( imageMaterial(imageAt(imageFill.image), imageFill.repeat), ); // Its image is changed in place (`writeImage`); it never recolours. part.image = { material, texture: null }; images.push(part.image); part.translucent.fill = true; part.fill = host.add( new Cesium.Primitive({ geometryInstances: new Cesium.GeometryInstance({ geometry: shape.fill, modelMatrix: shape.modelMatrix, id, }), appearance: new Cesium.MaterialAppearance({ material, materialSupport: Cesium.MaterialAppearance.MaterialSupport.TEXTURED, translucent: true, closed: solid, flat: !lit, }), asynchronous: false, }), ); } else if (item.fill && !item.outlineOnly) { const color = toColor(item.fill); part.translucent.fill = color.alpha < 1 || Boolean(pulse); part.fill = host.add( new Cesium.Primitive({ geometryInstances: new Cesium.GeometryInstance({ geometry: shape.fill, modelMatrix: shape.modelMatrix, attributes: { color: Cesium.ColorGeometryInstanceAttribute.fromColor(color), }, id, }), appearance: new Cesium.PerInstanceColorAppearance({ translucent: part.translucent.fill, closed: solid, // Flat shapes unlit by default: lit, their faces shade by // the light (a lit block's sides differ, an unlit one's match). flat: !lit, faceForward: !solid, }), asynchronous: false, }), ); } if (item.outline && shape.outline) { const color = toColor(item.outline); part.translucent.outline = color.alpha < 1 || Boolean(pulse); part.outline = host.add( new Cesium.Primitive({ geometryInstances: new Cesium.GeometryInstance({ geometry: shape.outline, attributes: { color: Cesium.ColorGeometryInstanceAttribute.fromColor(color), }, id, }), appearance: new Cesium.PerInstanceColorAppearance({ flat: true, translucent: part.translucent.outline, renderState: { // Clamped to what the context draws, as entities do. lineWidth: typeof scene.clampLineWidth === 'function' ? scene.clampLineWidth(item.outlineWidth ?? 1) : Math.min( item.outlineWidth ?? 1, scene.maximumAliasedLineWidth ?? 1, ), }, }), asynchronous: false, }), ); } else if (item.outline && shape.rings) for (const ring of shape.rings) part.rings.push( outlines.add({ positions: [...ring, ring[0]], width: item.outlineWidth ?? 1, material: Cesium.Material.fromType('Color', { color: toColor(item.outline), }), id, }), ); } host.add(outlines); const ground = groundFills(record, clamped); record.solidParts = solids; if (!ground.length) return replaceHost(record, host); replaceHost( record, collect(host, ground), ground, host, clamped.some( (item) => item.show !== false && item.fill && !item.outlineOnly, ), ); } const modelSets = createModelSets({ scene, toColor, pickId, replaceHost, horizonNow, requestRender, }); const buildModels = (record) => modelSets.build(record); // Whether shapes pulsed in the last frame, which draws on in the next. let pulsing = false; const lineWidth = (px) => typeof scene.clampLineWidth === 'function' ? scene.clampLineWidth(px) : Math.min(px, scene.maximumAliasedLineWidth ?? 1); const quadSets = createQuadSets({ toColor, toImage: imageAt, pickId, replaceHost, lineWidth, requestRender, }); const meshSets = createMeshSets({ toColor, pickId, replaceHost, requestRender, }); /** The 3D tilesets in the scene, shown or not. */ function tilesets() { const found = []; const primitives = scene.primitives; const n = primitives?.length ?? 0; for (let i = 0; i < n; i++) { const primitive = primitives.get(i); if (primitive instanceof Cesium.Cesium3DTileset) found.push(primitive); } return found; } /** * The Cesium port draws clamped items where it is given them; it does not * drape them onto 3D tiles yet, so over shown tiles it is `overlay`. * Terrain and the ellipsoid take draped items wherever Cesium drapes at * all: its draped lines and image fills need depth textures, which every * WebGL 2 context has; without them it says `overlay`, and draws draped * lines over the surface (`overlayLine`). Clamped shapes there are still * built as ground primitives: only a WebGL 1 context without the * extension lacks depth textures. */ const clampState = () => !drapes() || tilesets().some((tileset) => tileset.show) ? 'overlay' : 'draped'; const clampListeners = listenerList(report); // The state last told, while anyone listens; measured after each drawn // frame, when what the base holds can have changed. let toldClamp = null; function watchClamp() { if (clampListeners.size === 0) return; const state = clampState(); if (state === toldClamp) return; toldClamp = state; clampListeners.fire(state); } const draw = { icons: (spec) => makeSet('icons', { ...spec }, buildIcons), points: (spec) => makeSet('points', { ...spec }, buildPoints), lines: (spec) => makeSet('lines', { ...spec }, buildLines), shapes: (spec) => makeSet('shapes', { ...spec }, buildShapes), models: (spec) => makeSet('models', { ...spec }, buildModels), quads: (spec) => makeSet('quads', { ...spec }, (record) => quadSets.build(record)), meshes: (spec) => makeSet('meshes', { ...spec }, (record) => meshSets.build(record)), ...(capabilities.has('fields') ? { field(spec) { if (sets.has(spec?.id)) throw new Error(`a set with id ${spec.id} is live`); return fieldPart.field(spec); }, } : {}), clampState, on(event, cb) { if (event !== 'clampState') return () => {}; if (clampListeners.size === 0) toldClamp = clampState(); return clampListeners.on(cb); }, atlas(id, images) { atlases.set(id, { ...images }); let changed = false; for (const record of [...sets.values()]) if (record.kind === 'icons' && record.atlases?.has(id)) { if (record.gpu) { record.gpu.reatlas(id); setsVersion += 1; changed = true; continue; } // 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); const synced = syncIcons(record, drawing); if (!synced) record.rebuild(); else if (synced === ICONS_CHANGED) setsVersion += 1; changed = true; } if (changed) scene.requestRender(); }, }; return { port: draw, sets, version: () => setsVersion, tilesets, /** Whether a set's ground primitives are still being built. */ building: () => [...sets.values()].some((record) => record.pending), /** Each frame, before it draws: the horizon cull. */ beforeRender() { pulsing = runPulses(); cullHorizon(); clusterIcons(); runFlows(); for (const record of sets.values()) { if (record.inertialLines || record.inertialPieces?.length) turnInertial(record); record.drapeInertial?.(); } modelSets.beforeRender(sets.values()); quadSets.beforeRender(sets.values()); }, /** Each frame, after it drew: clamp state, and ground swaps. */ afterRender() { blobUrlFrameDrawn(); watchClamp(); swapReady(); // Clamped GPU icons take the ground under their segments. const budget = gpu.groundBudget(); let grounded = false; for (const record of sets.values()) if (record.gpu?.ground(budget)) grounded = true; if (grounded) requestRender(); for (const record of sets.values()) if (record.kind === 'lines') try { settleLines(record); } catch (error) { // Its lines stay in the collection, which draws them all. record.lineBox = null; report(error); } else if (record.kind === 'shapes') try { settleShapes(record); } catch (error) { report(error); } // Rows moving on a live clock, and flowing lines, draw on in the // frames that follow. const playing = quadSets.afterRender(sets.values()); if ( [...sets.values()].some((record) => record.gpu?.animating()) || flowing() || pulsing || playing ) requestRender(); }, /** * Let go of the sets; with `removeHosts`, take what they draw out of * the scene too (a scene the port does not own outlives it). */ dispose({ removeHosts = false } = {}) { clampListeners.clear(); // Fields go with the port, and their frame listeners with them. fieldPart.dispose(); // Late model loads find no host and destroy themselves. for (const record of sets.values()) { if (removeHosts && !scene.isDestroyed?.()) { if (record.host) scene.primitives.remove(record.host); retire(record); } record.host = null; } sets.clear(); }, }; } /** The parts of the draw ports built for viewers with no renderer, by port. */ const unboundParts = new WeakMap(); /** * The draw port part (its sets) behind a port built for a viewer with no * renderer, for that viewer's query port to pick and see through; null for * any other port. * @param {object|null|undefined} port */ export const unboundDrawPart = (port) => (port && unboundParts.get(port)) ?? null; // A Cesium viewer with no renderer bound to it gets a // draw port over its scene when code first asks `findDraw` for one. A // renderer bound later supersedes it: released, its sets keep drawing until // their owners dispose them; gone with the viewer, it lets them go. provideUnboundDraw((viewer) => { const scene = viewer.scene; // By shape, not `instanceof`: the viewer may come from another // copy of Cesium. if ( typeof scene?.primitives?.add !== 'function' || typeof scene.postRender?.addEventListener !== 'function' || typeof scene.requestRender !== 'function' ) return null; const part = createCesiumDraw({ scene, report: uncaught, capabilities: new Set([...GPU_ICON_CAPABILITIES, 'fields']), }); unboundParts.set(part.port, part); const offs = [ scene.preRender?.addEventListener?.(() => part.beforeRender()), scene.postRender.addEventListener(() => part.afterRender()), ]; const off = () => offs.splice(0).forEach((remove) => remove?.()); return { port: part.port, dispose() { off(); part.dispose({ removeHosts: true }); }, // Released, its sets still draw, culled and swapped as before; the // hooks go with the scene. release() {}, }; });