Every image kind draws on the Cesium port, atlas slots wherever an image is taken

Icons on billboards and on the GPU, line patterns, shape fills, quads and
raster shells take a URL, SVG, a blob (one object URL per blob), a keyed
canvas (packed into the GPU icon atlas as it is, by its key) and an atlas
slot as the image it holds. Blobs and canvases were refused on the GPU
path, blobs on billboards, and atlas slots everywhere but billboards. The
new conformance check draw.icons.images draws each kind on still and
receding icons; Cesium runs it.
This commit is contained in:
Sameh Khamis committed 2026-11-11 15:55:27 -08:00
1 parent 0e8be0fb78
commit 71f0945635
10 files changed
+229 -45

No files matched your search

+7
View File
@@ -126,6 +126,13 @@ optional, so a renderer written before it still conforms:
[The application and its renderer](#the-application-and-its-renderer).
- `frame.renderNow()` throws when the frame fails to draw.
The Cesium port takes every kind of `ImageRef` wherever an image is drawn
(icons on billboards and on the GPU, line patterns, shape fills, quads and
raster shells): a URL, SVG, a blob (by an object URL made once per blob), a
keyed canvas, and an atlas slot as the image it holds (an icon waits for an
unregistered slot; anything else refuses it). The check `draw.icons.images`
draws each kind on still and receding icons.
The Cesium port also draws `pattern` line styles (the image repeated
`repeat` times along the line, in the translucent pass), lines in the
`inertial` frame (turned each frame by the set's motion clock; never draped
+27 -14
View File
@@ -81,12 +81,15 @@ function createAtlas() {
},
/**
* The slot for `url` rasterised at `sizePx` square.
* The slot for `url` rasterised at `sizePx` square. Given a `source` (a
* canvas, or anything else `drawImage` takes), `url` is only its key:
* the source is packed at once, as it is now, and never loaded.
* @param {string} url
* @param {number} sizePx
* @param {CanvasImageSource} [source]
* @returns {number}
*/
slot(url, sizePx) {
slot(url, sizePx, source) {
const key = `${sizePx}|${url}`;
const known = slotOfKey.get(key);
if (known !== undefined) return known;
@@ -98,7 +101,8 @@ function createAtlas() {
const entry = { url, sizePx, image: null, x: 0, y: 0 };
entries.push(entry);
slotOfKey.set(key, slot);
load(entry);
if (source) placeLoaded(entry, source);
else load(entry);
return slot;
},
@@ -129,23 +133,32 @@ function createAtlas() {
},
};
/** Pack an entry's loaded image, or leave its slot empty when it does not fit. */
function placeLoaded(entry, image) {
entry.image = image;
// Node: nothing to pack into.
if (
typeof document === 'undefined' &&
typeof OffscreenCanvas === 'undefined'
)
return;
if (!pack()) {
entry.image = null; // does not fit: leave its slot empty, keep the rest
entry.failed = true;
console.warn(
`[iconAtlas] No room for ${entry.sizePx} px icon; slot stays empty`,
);
pack();
}
}
function load(entry) {
if (typeof Image === 'undefined') return; // Node: slots only
const image = new Image(entry.sizePx, entry.sizePx);
image.decoding = 'async';
// A cross-origin image would taint the canvas and every texture upload.
image.crossOrigin = 'anonymous';
image.onload = () => {
entry.image = image;
if (!pack()) {
entry.image = null; // does not fit: leave its slot empty, keep the rest
entry.failed = true;
console.warn(
`[iconAtlas] No room for ${entry.sizePx} px icon; slot stays empty`,
);
pack();
}
};
image.onload = () => placeLoaded(entry, image);
image.onerror = () => {
entry.failed = true;
console.warn(
+10
View File
@@ -65,3 +65,13 @@ export function uncaught(error) {
throw error;
});
}
/** Each blob's object URL, made once and kept while the blob lives. */
const blobUrls = new WeakMap();
/** A blob's object URL: the same one every time it is drawn. */
export function blobUrl(blob) {
let url = blobUrls.get(blob);
if (!url) blobUrls.set(blob, (url = URL.createObjectURL(blob)));
return url;
}
+39 -9
View File
@@ -35,7 +35,7 @@ import * as Cesium from 'cesium';
import { temeToPseudoFixed } from '../../geo/celestial.js';
import { alongLength } from '../../geo/polyline.js';
import { provideUnboundDraw } from '../rendererOf.js';
import { listenerList, toCartesian, uncaught } from './common.js';
import { blobUrl, listenerList, toCartesian, uncaught } from './common.js';
import { createGpuIcons, GPU_ICON_CAPABILITIES } from './gpuIcons.js';
import { createModelSets } from './drawModels.js';
import { materialTexture } from './internals.js';
@@ -54,13 +54,23 @@ export function toColor(color, alpha = 1) {
return c.withAlpha(c.alpha * alpha);
}
/** An image reference as something a billboard takes. */
/**
* 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;
throw new Error('the Cesium renderer takes URL, SVG and canvas images only');
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`. */
@@ -371,7 +381,14 @@ export function createCesiumDraw({
}) {
const sets = new Map();
// Fields share the sets' ids.
const fieldPart = createCesiumFields({ scene, report });
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
@@ -915,6 +932,19 @@ export function createCesiumDraw({
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;
@@ -944,7 +974,7 @@ export function createCesiumDraw({
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;
return image?.canvas ?? image?.blob ?? image;
}
/** How a billboard draws an icon item at `position`, but its image and id. */
@@ -1838,7 +1868,7 @@ export function createCesiumDraw({
return {
type: 'Image',
uniforms: {
image: toImage(style.image),
image: imageAt(style.image),
repeat: new Cesium.Cartesian2(style.repeat, 1),
},
};
@@ -3422,7 +3452,7 @@ export function createCesiumDraw({
if (imageFill && scene.context?.depthTexture === false)
throw new Error('the Cesium renderer cannot drape images here');
// Refused before anything is made, so nothing is left half built.
const image = imageFill ? toImage(imageFill.image) : null;
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
@@ -4134,7 +4164,7 @@ export function createCesiumDraw({
const lit = item.lit ?? solid;
if (imageFill && !item.outlineOnly) {
const material = ownMaterial(
imageMaterial(toImage(imageFill.image), imageFill.repeat),
imageMaterial(imageAt(imageFill.image), imageFill.repeat),
);
// Its image is changed in place (`writeImage`); it never recolours.
part.image = { material, texture: null };
@@ -4257,7 +4287,7 @@ export function createCesiumDraw({
: Math.min(px, scene.maximumAliasedLineWidth ?? 1);
const quadSets = createQuadSets({
toColor,
toImage,
toImage: imageAt,
pickId,
replaceHost,
lineWidth,
+10 -2
View File
@@ -4445,7 +4445,8 @@ test('a draped rectangle turns, its image fill with it, on a ground primitive th
const [flat] = grounds();
assert.equal(flat.geometryInstances[0].geometry._rotation, 0);
plain.dispose();
// An image it cannot take is refused before anything is built.
// An atlas slot fills as the image it holds; one not registered is
// refused before anything is built.
const made = scene.added.length;
assert.throws(
() =>
@@ -4455,9 +4456,16 @@ test('a draped rectangle turns, its image fill with it, on a ground primitive th
overlay(),
overlay({ id: 'b', fill: { image: { atlas: 'a', slot: 's' } } }),
]),
/URL, SVG and canvas images only/,
/atlas a has no slot s registered/,
);
assert.equal(scene.added.length, made, 'nothing drawn');
draw.atlas('a', { s: 'slot.png' });
const slotted = draw.shapes({ id: 'atlas-registered' });
slotted.set([
overlay({ id: 'b', fill: { image: { atlas: 'a', slot: 's' } } }),
]);
assert.ok(scene.added.length > made, 'drawn from the slot');
slotted.dispose();
}));
test('scene data packs draw their geometry and media marker through the Cesium draw port on a viewer of its own', async (t) => {
+14 -5
View File
@@ -10,7 +10,8 @@
* - An image is read when it is first named, as a Cesium material reads
* one: to show new pixels, name another canvas. URL, SVG and blob images
* are decoded before they are handed over, so the frame they replace
* stays until they can be drawn; atlas slots are refused.
* stays until they can be drawn; an atlas slot is read as the image it
* holds when the field is drawn or updated.
* - An `update` of `image` alone, inside the same rectangle and height,
* swaps the texture on the drawn surface: Cesium keeps drawing the old
* one until the new one is uploaded. A new `rectangle` or `heightM` is
@@ -371,7 +372,10 @@ const immediate = (ref) => Boolean(ref?.canvas);
/** An image reference decoded into something a material uploads. */
async function decode(ref) {
if (ref?.atlas) throw new TypeError('a raster shell takes no atlas images');
if (ref?.atlas)
throw new TypeError(
`atlas ${ref.atlas} has no slot ${ref.slot} registered`,
);
const url = ref?.blob
? URL.createObjectURL(ref.blob)
: ref?.svg
@@ -391,7 +395,9 @@ async function decode(ref) {
/**
* The fields part of a Cesium draw port.
* @param {{scene: object, report?: (error: unknown) => void,
* cesium?: object}} options `cesium` is for test doubles.
* cesium?: object, resolveImage?: (ref: unknown) => unknown}} options
* `cesium` is for test doubles; `resolveImage` reads an atlas slot as the
* image it holds.
* @returns {{field: (spec: object) => object, has: (id: string) => boolean,
* dispose: () => void}}
*/
@@ -399,6 +405,7 @@ export function createCesiumFields({
scene,
report = uncaught,
cesium = Cesium,
resolveImage = (ref) => ref,
}) {
const fields = new Map();
const live = () => !scene.isDestroyed?.();
@@ -515,10 +522,12 @@ export function createCesiumFields({
}
function load(c) {
const seq = (contentSeq += 1);
const refs = [c.image, c.detail?.image];
const refs = [c.image, c.detail?.image].map((ref) =>
ref == null ? ref : resolveImage(ref),
);
if (refs.every((ref) => ref == null || immediate(ref))) {
placedSeq = seq;
place(c, c.image.canvas, c.detail?.image.canvas ?? null);
place(c, refs[0].canvas, refs[1]?.canvas ?? null);
return;
}
// A stage of older content must not take the drawn one's place while
+19 -14
View File
@@ -13,8 +13,8 @@
* 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
* centre, axis and screen rotations, and opaque and additive blends. Their
* images (URLs, SVG, blobs, keyed canvases and atlas slots of those)
* 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
@@ -53,7 +53,7 @@ import {
LERP_STEP_MS,
motionEndsAt,
} from '../motion/iconMotion.js';
import { toCartesian } from './common.js';
import { blobUrl, toCartesian } from './common.js';
/** The capabilities GPU icon sets bring. */
export const GPU_ICON_CAPABILITIES = Object.freeze([
@@ -68,11 +68,17 @@ const nonZero = (v) =>
/** 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. */
/**
* An image's atlas key: a URL itself, SVG as a data URL, a blob as its
* object URL, a generated canvas by its key; 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)}`;
if (image?.blob) return blobUrl(image.blob);
if (image?.canvas && typeof image.key === 'string')
return `\u0000key\u0000${image.key}`;
return null;
}
@@ -219,13 +225,11 @@ export function createGpuIcons({
// 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 url = image === undefined ? null : imageUrl(image);
if (image !== undefined && url === null)
throw new TypeError(
'an image is a URL, SVG, blob, keyed canvas or atlas slot',
);
const px = rasterPxOf(url, item);
if (url !== null && !iconAtlas.has(url, px)) fresh.add(`${px}|${url}`);
}
@@ -300,9 +304,10 @@ export function createGpuIcons({
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",
if (url !== null)
return iconAtlas.slot(url, rasterPxOf(url, item), resolved?.canvas);
throw new TypeError(
'an image is a URL, SVG, blob, keyed canvas or atlas slot',
);
}
+37 -1
View File
@@ -330,7 +330,6 @@ test('GPU icon sets refuse what they cannot draw, changing nothing', () => {
{ anchor: 'bottom' },
{ rotationMode: 'axis' },
{ rotationMode: 'screen', rotation: 1 },
{ image: { blob: {} } },
])
assert.throws(
() => set.upsert([icon('b', { motion: { kind: 'hold' }, ...extra })]),
@@ -605,6 +604,43 @@ test('a row takes its item’s motion changed in place', () => {
);
});
test('GPU icons take blobs and keyed canvases into the atlas, an atlas slot of each too', async () => {
const { iconAtlas } = await import('../../data/iconAtlas.js');
const { part, draw } = drawOver();
const blob = new Blob(['<svg xmlns="http://www.w3.org/2000/svg"/>'], {
type: 'image/svg+xml',
});
const canvas = { width: 16, height: 16 };
draw.atlas('gpu:kinds', { blob: { blob }, canvas: { canvas, key: 'sq' } });
const set = draw.icons({ id: 'gpu:kinds' });
const moving = { motion: { kind: 'hold' }, size: [20, 20] };
set.set([
icon('blob', { image: { blob }, ...moving }),
icon('canvas', { image: { canvas, key: 'sq' }, ...moving }),
icon('atlas-blob', {
image: { atlas: 'gpu:kinds', slot: 'blob' },
...moving,
}),
icon('atlas-canvas', {
image: { atlas: 'gpu:kinds', slot: 'canvas' },
...moving,
}),
]);
const { set: rowsOf } = rows(part, 'gpu:kinds');
const far = (id) => rowsOf.imageFar(rowsOf.row(id));
assert.ok(far('blob') >= 0 && far('canvas') >= 0);
assert.notEqual(far('blob'), far('canvas'));
assert.equal(far('atlas-blob'), far('blob'), 'one slot per blob');
assert.equal(far('atlas-canvas'), far('canvas'), 'one slot per canvas key');
assert.ok(iconAtlas.has('\u0000key\u0000sq', 20), 'the canvas by its key');
assert.throws(
() => set.upsert([icon('bad', { image: { nope: 1 }, ...moving })]),
/an image is a URL, SVG, blob, keyed canvas or atlas slot/,
);
assert.equal(set.size(), 4, 'refused, changing nothing');
set.dispose();
});
test('an SVG takes the atlas at its own size, other images at the item’s', async () => {
const { iconAtlas } = await import('../../data/iconAtlas.js');
const { svgRasterPx } = await import('./gpuIcons.js');
+1
View File
@@ -44,6 +44,7 @@ export const CESIUM_CHECKS = new Set([
'draw.field.rasterShell',
'draw.field.windStreamlines',
'draw.icons.distance',
'draw.icons.images',
'draw.icons.update',
'draw.lines.depthFail',
'draw.lines.settled',
+65
View File
@@ -1649,6 +1649,71 @@ export function portChecks() {
set.dispose();
},
),
check(
'draw.icons.images',
'icons draw every kind of image (URL, SVG, blob, keyed canvas and an atlas slot of each), on billboards and moving alike, and are picked',
async (h, r) => {
await overAustin(h, r);
const kinds = {
url: PIXEL_PNG,
svg: DOT,
blob: { blob: new Blob([DOT.svg], { type: 'image/svg+xml' }) },
};
const canvas = globalThis.document?.createElement('canvas');
const g = canvas?.getContext?.('2d');
if (g) {
canvas.width = canvas.height = 16;
g.fillStyle = '#fff';
g.fillRect(0, 0, 16, 16);
kinds.canvas = { canvas, key: 'conf:images-square' };
}
r.draw.atlas('conf:images', kinds);
const images = Object.entries(kinds).flatMap(([kind, image]) => [
[kind, image],
[`atlas-${kind}`, { atlas: 'conf:images', slot: kind }],
]);
// Two sets: still icons, and icons that recede (drawn as moving
// ones are, where a renderer draws them apart).
const rows = [
['still', {}, AUSTIN.lat + 0.004],
['receding', { recede: true }, AUSTIN.lat - 0.004],
];
const at = (i, lat) =>
h.toEcef({
lon: AUSTIN.lon + (i - (images.length - 1) / 2) * 0.0012,
lat,
height: 0,
});
const sets = rows.map(([name, extra, lat]) => {
const set = r.draw.icons({ id: `conf:images-${name}` });
set.set(
images.map(([id, image], i) => ({
id,
pos: at(i, lat),
image,
size: [20, 20],
...extra,
})),
);
return set;
});
await drawn(h, r);
await settled(r);
await drawn(h, r);
for (const [name, , lat] of rows)
images.forEach(([id], i) => {
const s = r.query.project(at(i, lat));
ok(s, `${name} ${id} projects`);
const hit = r.query.pick(s.x, s.y);
deepEqual(
[hit?.set, hit?.id],
[`conf:images-${name}`, id],
`${name} ${id} drawn and picked`,
);
});
for (const set of sets) set.dispose();
},
),
check(
'draw.icons.update',
'an upserted icon keeps drawing, as it now is, from the next frame: picked at its new size with its new meta, even while a new image loads; a removed one is gone',