Files
gods-eye-view/src/render/cesium/gpuIcons.js
T
Sameh Khamis 46cdeba7fa Remove renderer contract members nothing in the application uses
Drops from the contract, the stub, the Cesium renderer and the
conformance suite: agent paths, renderer-propagated orbits and celestial
draws (orbits stay drawn as icons and inertial lines), scalar raster
fields, lodGroup, volume classification, icon eye offsets, the dash gap
colour, box shapes, courseBlendMs (courseGlide covers easing), relief
surface shading, globe clouds and water, sky atmosphere tuning, heightmap
and quantized-mesh terrain, WMTS and ArcGIS imagery, the batched cached
height read, the quality benchmark and the animated-style and overlay
pixel-ratio knobs. Capabilities clouds, water, celestial, agents, orbits
and benchmark go with them.

The lodGroup check becomes a displayRange check across two sets, the
height-query check uses an extruded polygon in place of a box, the shape
scenes draw extruded blocks where they drew boxes, and the fields scene
draws a raster shell. The shape references are recorded again.
2026-11-10 03:27:10 -08:00

559 lines
20 KiB
JavaScript

/**
* @module render/cesium/gpuIcons
* @description The Cesium draw port's GPU icon sets: an icon set whose items
* move (`motionSegments`), glide their course (`courseGlide`), recede
* toward the limb, pick through a larger proxy,
* switch images by drawn size, or that takes columns (`columns`), draws as
* one instanced primitive (`IconSetPrimitive`) over an icon set's typed
* columns (`iconSet.js`) instead of a billboard collection. Each item is one
* row; the GPU moves it along its segment on the set's motion clock, so a
* row is written only when its item changes.
*
* What these sets draw as billboards do not: an icon set becomes one when
* an item first needs it (or it first takes columns), and stays one. They
* refuse loudly what billboards draw and they do not: clamped heights,
* `fadeByDistance`, `displayRange`, pixel offsets, anchors other than the
* centre, axis and screen rotations, opaque and additive blends, and
* images other than URLs, SVG and atlas slots of those. Their images
* are rasterised square into the icon atlas every GPU icon set shares, and
* refused when it has no room left for them: an SVG at its own size (its
* root's larger `width`/`height`, as a billboard rasterises it), any other
* image at the item's larger side.
*
* Choices the contract leaves open, taken conservatively:
* - `horizonCull` judges each row no lower than `ICON_CULL_HEIGHT_M` above
* the ellipsoid, as the layers drawing their own icon sets do for sea
* level and grounded contacts below it (`ICON_CULL_LIFT`).
* - A row's course is its motion's (`hold.courseDeg`, `lerp.course0Deg`,
* the arc's track), else the item's `course`.
* - Rows draw in the order they were added; removing one moves the last
* into its place.
* - `Columns.dirty` runs include their `end`, and are trusted only when the
* ids are those of the last columns, row for row.
* - A `lerp` whose `t1` is not after `t0` steps from `from` to `to` 1 ms
* after `t0`.
*/
import * as Cesium from 'cesium';
import {
createIconSet,
ICON_CULL_LIFT,
ICON_RECEDES,
ICON_ROTATES,
} from '../../data/iconSet.js';
import {
writeArcSegment,
writeCourseGlide,
writeHoldSegment,
writeLerpSegment,
} from '../../data/iconSegment.js';
import { contextIconSlots, IconSetPrimitive } from './iconSetPrimitive.js';
import { iconAtlas, MAX_ICON_SLOTS } from '../../data/iconAtlas.js';
import {
glideOffset,
LERP_STEP_MS,
motionEndsAt,
} from '../motion/iconMotion.js';
import { toCartesian } from './common.js';
/** The capabilities GPU icon sets bring. */
export const GPU_ICON_CAPABILITIES = Object.freeze([
'columns',
'motionSegments',
'courseGlide',
]);
const nonZero = (v) =>
Boolean(v) && (v.x !== 0 || v.y !== 0 || (v.z ?? 0) !== 0);
/** Whether a curve is one (as the billboards read it). */
const isCurve = (curve) => Boolean(curve) && curve.far > curve.near;
/** An image's atlas URL: itself, or SVG as a data URL; else null. */
function imageUrl(image) {
if (typeof image === 'string') return image;
if (typeof image?.svg === 'string')
return `data:image/svg+xml;charset=utf-8,${encodeURIComponent(image.svg)}`;
return null;
}
/** What a row's segment and course easing are written from. */
function motionOf(item) {
return {
pos: item.pos ? { ...item.pos } : undefined,
course: item.course,
motion: item.motion ? { ...item.motion } : undefined,
courseGlide: item.courseGlide ? { ...item.courseGlide } : undefined,
};
}
/** Whether two plain records hold the same values, nested ones included. */
function sameFields(a, b) {
if (a === b) return true;
if (!a || !b || typeof a !== 'object' || typeof b !== 'object') return false;
const keys = Object.keys(a);
if (keys.length !== Object.keys(b).length) return false;
for (const key of keys) if (!sameFields(a[key], b[key])) return false;
return true;
}
/** Whether two `motionOf`s write the same segment. */
const sameMotion = (a, b) => Boolean(a) && sameFields(a, b);
/** SVG URLs' own raster sizes (px; null: none given), as parsed. */
const svgSizes = new Map();
const SVG_SIZES_KEPT = 128;
/**
* The largest an SVG is rasterised at its own size (px): past it, at this,
* so an icon exported at 1024 px still packs.
*/
export const MAX_OWN_RASTER_PX = 256;
/**
* An SVG data URL's own raster size: the larger of its root's `width` and
* `height` in pixels (unitless or `px`), at most `MAX_OWN_RASTER_PX`, or null
* when it gives no such size.
*/
export function svgRasterPx(url) {
if (!/^data:image\/svg\+xml[;,]/i.test(url)) return null;
let px = svgSizes.get(url);
if (px !== undefined) return px;
px = null;
try {
const comma = url.indexOf(',');
const body = url.slice(comma + 1);
const text = /;base64$/i.test(url.slice(0, comma))
? atob(body)
: decodeURIComponent(body);
// The root tag, comments aside, quoted values whole.
const root =
/<svg\b(?:[^>"']|"[^"]*"|'[^']*')*>/i.exec(
text.replace(/<!--[\s\S]*?-->/g, ''),
)?.[0] ?? '';
const side = (name) => {
const m = new RegExp(
`\\s${name}\\s*=\\s*["']\\s*([0-9]*\\.?[0-9]+)\\s*(px)?\\s*["']`,
'i',
).exec(root);
return m ? Number(m[1]) : NaN;
};
const width = side('width');
const height = side('height');
if (width > 0 && height > 0)
px = Math.min(
MAX_OWN_RASTER_PX,
Math.max(1, Math.round(Math.max(width, height))),
);
} catch {
// Not decodable: drawn at the item's size.
}
if (svgSizes.size >= SVG_SIZES_KEPT) svgSizes.clear();
svgSizes.set(url, px);
return px;
}
/** The square raster size an image (its atlas URL) takes for an item. */
function rasterPxOf(url, item) {
const own = url === null ? null : svgRasterPx(url);
if (own !== null) return own;
const [width = 0, height = 0] = item.size ?? [];
return Math.max(1, Math.round(Math.max(width, height)));
}
/**
* @param {{scene: object, capabilities: ReadonlySet<string>,
* toColor: (color: unknown) => Cesium.Color,
* imageOf: (record: object, image: unknown) => unknown,
* peekImage: (ref: {atlas: string, slot: string}) => unknown,
* requestRender: (reason: string) => void}} options `imageOf` reads an atlas slot
* through the draw port's atlases (undefined while it is not registered),
* noting that the set draws from it; `peekImage` only reads it.
*/
export function createGpuIcons({
scene,
capabilities,
toColor,
imageOf,
peekImage,
requestRender,
}) {
const can = (capability) => capabilities.has(capability);
/** Whether drawing these items needs a GPU icon set. */
function wants(items) {
for (const item of items) {
if (
(item.motion && can('motionSegments')) ||
(item.courseGlide && can('courseGlide')) ||
item.recede ||
item.pickProxy ||
item.imageLod
)
return true;
}
return false;
}
/** Refuse what a GPU icon set cannot draw, before anything changes. */
function check(items, spec = {}) {
if (spec.blend === 'opaque' || spec.blend === 'additive')
throw new Error(
`the Cesium renderer's GPU icons have no ${spec.blend} blend`,
);
// Atlas slots these items would take anew: they must all fit.
const fresh = new Set();
for (const item of items) {
const refuse = (what) => {
throw new Error(`the Cesium renderer's GPU icons have no ${what}`);
};
if (item.height !== undefined && item.height !== 'absolute')
refuse('clamped heights');
if (item.fadeByDistance) refuse('fadeByDistance');
if (item.displayRange) refuse('displayRange');
if (nonZero(item.pixelOffset)) refuse('pixelOffset');
if (item.anchor !== undefined && item.anchor !== 'center')
refuse('anchors but the centre');
if (item.rotationMode === 'axis') refuse('axis rotation');
if (item.rotationMode === 'screen' && (item.rotation ?? 0) !== 0)
refuse('screen rotation');
for (const given of [item.image, item.imageLod?.near]) {
// An atlas slot as what it holds now (none yet draws once it does).
const image =
typeof given?.atlas === 'string' ? peekImage(given) : given;
if (
image !== undefined &&
typeof image !== 'string' &&
typeof image?.svg !== 'string'
)
refuse('images but URLs and SVG');
const url = imageUrl(image);
const px = rasterPxOf(url, item);
if (url !== null && !iconAtlas.has(url, px)) fresh.add(`${px}|${url}`);
}
}
// As many as this scene's context addresses (all of them on WebGL 2).
const room = Math.min(MAX_ICON_SLOTS, contextIconSlots(scene.context));
if (iconAtlas.size + fresh.size > room)
throw new Error(
`the Cesium renderer's GPU icons have no room for ${fresh.size} more images (at most ${room} in all)`,
);
}
/**
* Draw `record`'s icons on the GPU from now on: its icon set, the
* primitive drawing it, and the writes that keep it in step with the
* record's items.
*/
function attach(record) {
const spec = record.spec;
const scratch = new Cesium.JulianDate();
// The motion clock's time now, and in the frame being drawn.
function clockTime(frameState, result = scratch) {
const clock = spec.motionClock;
if (clock?.kind === 'scene')
return Cesium.JulianDate.clone(
frameState?.time ?? scene.frameState?.time ?? Cesium.JulianDate.now(),
result,
);
return Cesium.JulianDate.addSeconds(
Cesium.JulianDate.now(result),
-(clock?.delayMs ?? 0) / 1000,
result,
);
}
// Its epoch starts at the clock, and the primitive keeps it near it.
const set = createIconSet({ epoch: clockTime() });
const msScratch = new Cesium.JulianDate();
const tauOf = (ms) =>
set.seconds(Cesium.JulianDate.fromDate(new Date(ms), msScratch));
const host = new IconSetPrimitive({
set,
renderTime: (frameState) =>
clockTime(frameState, new Cesium.JulianDate()),
requestRender: () => requestRender(`icons:${spec.id}`),
cull: () => spec.horizonCull === true,
// Picked as the draw port's other items are: `{set, id, meta}` as
// the item now is, hidden row by row for drill picks.
pickObject: (id, _set, primitive) => ({
primitive,
id: {
set: spec.id,
id,
get meta() {
return record.items.get(id)?.meta;
},
},
}),
});
record.atlases ??= new Set();
// Until when (epoch ms on the motion clock) a row may still move or turn.
let movingUntil = -Infinity;
const clockMs = () => Cesium.JulianDate.toDate(clockTime()).getTime();
// What each row's segment was last written from, by id.
const written = new Map();
// The ids of the last columns, while no other write came after them.
let columnIds = null;
// Written in full on the first write.
let fresh = true;
/** An item's image as its atlas slot, or -1 while it is not registered. */
function slotOf(image, item) {
const resolved = imageOf(record, image);
if (resolved === undefined) return -1;
const url = imageUrl(resolved);
if (url !== null) return iconAtlas.slot(url, rasterPxOf(url, item));
throw new Error(
"the Cesium renderer's GPU icons have no images but URLs and SVG",
);
}
/** The course a row's motion (else its item) gives. */
function courseOf(item) {
const motion = can('motionSegments') ? item.motion : undefined;
if (motion?.kind === 'hold') return motion.courseDeg ?? item.course ?? 0;
if (motion?.kind === 'lerp') return motion.course0Deg ?? item.course ?? 0;
return item.course ?? 0;
}
/** Write a row's segment. */
function writeMotion(row, item) {
const seg = set.segments;
const motion = can('motionSegments') ? item.motion : undefined;
const pos = toCartesian(item.pos);
switch (motion?.kind) {
case 'lerp': {
const t0 = tauOf(motion.t0);
// Not after t0: a step 1 ms after it.
const t1 = Math.max(tauOf(motion.t1), t0 + LERP_STEP_MS / 1000);
writeLerpSegment(seg, row, {
from: toCartesian(motion.from),
to: toCartesian(motion.to),
t0,
t1,
course0Deg: courseOf(item),
courseSlopeDeg: motion.courseSlopeDeg ?? 0,
});
return;
}
case 'arc': {
const t0 = tauOf(motion.t0);
writeArcSegment(seg, row, {
fix: toCartesian(motion.fix),
t0,
minDt: motion.minDtS,
maxDt: motion.maxDtS,
speedMps: motion.speedMps,
trackDeg: motion.trackDeg,
turnRateDps: motion.turnRateDps,
climbMps: motion.climbMps ?? 0,
});
return;
}
default:
writeHoldSegment(seg, row, pos, courseOf(item));
}
}
/**
* Draw an item as its row (added when it has none). With `motion` false
* (a column change of neither position nor course) its segment and
* course easing are kept as they are.
*/
function writeRow(item, { motion = true } = {}) {
let row = set.row(item.id);
const added = row < 0;
if (added) row = set.add(item.id);
const [width = 0, height = 0] = item.size ?? [];
const far = slotOf(item.image, item);
const near = item.imageLod ? slotOf(item.imageLod.near, item) : far;
set.setImage(row, far, near);
// A switch at 0 px or less is near at any size.
set.setImageSwitch(
row,
item.imageLod ? Math.max(item.imageLod.switchPx, 1e-3) : 0,
);
set.setSize(row, width, height);
set.setScale(row, item.scale ?? 1);
set.setAlpha(row, item.alpha ?? 1);
set.setColor(row, toColor(item.color));
set.setFocus(row, item.focus ?? 1);
set.setScaleByDistance(
row,
isCurve(item.scaleByDistance) ? item.scaleByDistance : undefined,
);
set.setFlag(row, ICON_ROTATES, item.rotationMode === 'course');
set.setFlag(row, ICON_RECEDES, item.recede === true);
set.setFlag(row, ICON_CULL_LIFT, spec.horizonCull === true);
set.setPickProxy(
row,
item.pickProxy?.size?.[0] ?? 0,
item.pickProxy?.size?.[1] ?? 0,
);
set.setDepthTestDistance(row, item.disableDepthTest ?? 0);
set.setShown(row, item.show !== false);
if (!motion && !added) return;
// A write moving it as it already moves (a restyle, a focus change)
// keeps its segment and course easing as they are.
const from = motionOf(item);
if (!added && sameMotion(written.get(item.id), from)) return;
written.set(item.id, from);
writeMotion(row, item);
// The row as the renderer reads it (copies, as `written`'s are): its
// motion, without a glide yet.
const along = {
pos: from.pos,
course: from.course,
motion: can('motionSegments') ? from.motion : undefined,
};
// A glide written with the offset the app reads, so a half turn goes the
// way `iconMotion` says.
const writeGlide = (g) =>
writeCourseGlide(
set.segments,
row,
g.fromCourseDeg,
tauOf(g.t0),
g.rateDps,
glideOffset(along.motion, along.course, g),
);
let end = motionEndsAt(along);
const glide = can('courseGlide') ? from.courseGlide : undefined;
if (glide) {
writeGlide(glide);
end = motionEndsAt({ ...along, courseGlide: glide });
}
set.segmentWritten(row);
if (end > movingUntil) movingUntil = end;
}
/** Bring the rows in line with every item. */
function sync() {
fresh = false;
columnIds = null;
// Every row is written anew.
movingUntil = -Infinity;
written.clear();
for (let row = set.count - 1; row >= 0; row--) {
const id = set.idAt(row);
if (!record.items.has(id)) {
set.remove(id);
written.delete(id);
}
}
for (const item of record.items.values()) writeRow(item);
}
return {
host,
set,
sync,
/** Rows for these items, already in the record's. */
write(items) {
if (fresh) return sync();
columnIds = null;
for (const item of items) writeRow(record.items.get(item.id) ?? item);
},
/** Rows of items gone from the record's. */
drop(ids) {
if (fresh) return sync();
columnIds = null;
for (const id of ids) {
set.remove(id);
written.delete(id);
}
if (record.items.size === 0) movingUntil = -Infinity;
},
/**
* Columns as rows, as the contract's `Columns`: each column's value
* merged into its row's item (added when it has none), and the rows
* not in `ids` removed.
*/
columns(columns) {
if (fresh) sync();
const ids = columns.ids.map(String);
const n = ids.length;
const same =
columnIds !== null &&
columnIds.length === n &&
ids.every((id, i) => columnIds[i] === id);
if (!same) {
const keep = new Set(ids);
for (const id of [...record.items.keys()])
if (!keep.has(id)) {
record.items.delete(id);
set.remove(id);
written.delete(id);
}
}
const runs =
same && columns.dirty ? columns.dirty : [{ start: 0, end: n - 1 }];
const {
positions: p,
courses,
shown,
scales,
alphas,
colors,
meta,
} = columns;
// Neither moved nor turned: segments and course easing stay.
const motion = Boolean(p || courses);
for (const run of runs)
for (
let i = Math.max(0, run.start);
i <= Math.min(n - 1, run.end);
i++
) {
const id = ids[i];
const item = { ...(record.items.get(id) ?? { id }) };
if (p) item.pos = { x: p[i * 3], y: p[i * 3 + 1], z: p[i * 3 + 2] };
if (courses) item.course = courses[i];
if (shown) item.show = shown[i] !== 0;
if (scales) item.scale = scales[i];
if (alphas) item.alpha = alphas[i];
if (colors)
item.color = [0, 1, 2, 3].map((k) => colors[i * 4 + k] / 255);
if (meta) item.meta = meta[i];
record.items.set(id, item);
writeRow(item, { motion });
}
columnIds = ids;
},
/** After `setOptions`: the cull lift follows `horizonCull`. */
restyle() {
for (let row = 0; row < set.count; row++)
set.setFlag(row, ICON_CULL_LIFT, spec.horizonCull === true);
},
/** Rewrite the rows drawing from atlas `id`. */
reatlas(id) {
const drawing = [];
for (const item of record.items.values())
if (item.image?.atlas === id || item.imageLod?.near?.atlas === id)
drawing.push(item);
if (fresh) return sync();
for (const item of drawing) writeRow(item);
},
/** Whether a live-clock row is still moving: frames should keep coming. */
animating() {
if (spec.motionClock?.kind === 'scene' || spec.show === false)
return false;
return set.count > 0 && clockMs() < movingUntil;
},
/** The images shown rows draw: `failed`, `loading` or `settled`. */
imageState() {
let loading = false;
for (let row = 0; row < set.count; row++) {
if (!set.shown(row)) continue;
for (const slot of [set.imageFar(row), set.imageNear(row)]) {
if (slot < 0) continue;
if (iconAtlas.failed(slot)) return 'failed';
if (!iconAtlas.ready(slot)) loading = true;
}
}
return loading ? 'loading' : 'settled';
},
};
}
return { wants, check, attach };
}