diff --git a/docs/RENDERER-CONTRACT.md b/docs/RENDERER-CONTRACT.md index 547a786cd..745a5ed31 100644 --- a/docs/RENDERER-CONTRACT.md +++ b/docs/RENDERER-CONTRACT.md @@ -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 diff --git a/src/data/iconAtlas.js b/src/data/iconAtlas.js index 019c36c26..48c984159 100644 --- a/src/data/iconAtlas.js +++ b/src/data/iconAtlas.js @@ -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( diff --git a/src/render/cesium/common.js b/src/render/cesium/common.js index 6e8a15eac..59241b7b2 100644 --- a/src/render/cesium/common.js +++ b/src/render/cesium/common.js @@ -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; +} diff --git a/src/render/cesium/draw.js b/src/render/cesium/draw.js index 788bca101..bfbc39169 100644 --- a/src/render/cesium/draw.js +++ b/src/render/cesium/draw.js @@ -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, diff --git a/src/render/cesium/draw.test.mjs b/src/render/cesium/draw.test.mjs index 28c930dc0..632330097 100644 --- a/src/render/cesium/draw.test.mjs +++ b/src/render/cesium/draw.test.mjs @@ -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) => { diff --git a/src/render/cesium/drawFields.js b/src/render/cesium/drawFields.js index 5cc6d64be..04b8a9649 100644 --- a/src/render/cesium/drawFields.js +++ b/src/render/cesium/drawFields.js @@ -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 diff --git a/src/render/cesium/gpuIcons.js b/src/render/cesium/gpuIcons.js index 7a9cadee6..524c80adb 100644 --- a/src/render/cesium/gpuIcons.js +++ b/src/render/cesium/gpuIcons.js @@ -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', ); } diff --git a/src/render/cesium/gpuIcons.test.mjs b/src/render/cesium/gpuIcons.test.mjs index ad6cb4667..a55626644 100644 --- a/src/render/cesium/gpuIcons.test.mjs +++ b/src/render/cesium/gpuIcons.test.mjs @@ -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([''], { + 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'); diff --git a/src/render/cesium/harness.js b/src/render/cesium/harness.js index 3f448a17d..92bfa4315 100644 --- a/src/render/cesium/harness.js +++ b/src/render/cesium/harness.js @@ -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', diff --git a/src/render/conformance/checks/ports.js b/src/render/conformance/checks/ports.js index 22c3bcf8d..e7627024b 100644 --- a/src/render/conformance/checks/ports.js +++ b/src/render/conformance/checks/ports.js @@ -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',