From 50cb7bd5f4e2e0de4f9fba1d0652f372f6ae8b41 Mon Sep 17 00:00:00 2001 From: Sameh Khamis Date: Mon, 9 Nov 2026 07:02:54 -0800 Subject: [PATCH 1/3] render: Cesium draws raster-shell fields; weather shells use the draw port The Cesium draw port now implements draw.field for the rasterShell kind and advertises the 'fields' capability. The shell surface (a raised rectangle with a detail window, drawn in primitive order without depth writes) moves from the weather layer into src/render/cesium/drawFields.js. A new rectangle or height is drawn invisibly first and swapped in whole, and 'drawn' is told in the frame of the swap. A stage of older content never replaces the drawn one while newer content decodes. A field hidden mid-stage keeps building it. The weather shell (src/layers/weather/shellRendering.js) now drives one field through the draw, camera, frame and globe ports and no longer imports Cesium, so it leaves the Cesium allow list. The wind shell on photoreal hosts also draws through draw.field. The conformance page runs each visual scene on its own, so a kind the Cesium renderer does not draw yet (scalarRaster) fails only its own scene. --- dev/conformance/main.js | 117 ++-- scripts/format-scope.json | 2 + scripts/package-boundaries.json | 5 + src/layers/weather/shellFixture.mjs | 44 ++ src/layers/weather/shellRendering.js | 565 +++++++----------- src/layers/weather/shellRendering.test.mjs | 371 +----------- src/layers/weather/weather.test.mjs | 11 +- src/layers/wind/rendering.js | 72 ++- src/layers/wind/rendering.test.mjs | 21 +- src/render/cesium/draw.js | 23 +- src/render/cesium/drawFields.js | 644 ++++++++++++++++++++ src/render/cesium/drawFields.test.mjs | 645 +++++++++++++++++++++ src/render/cesium/harness.js | 1 + src/render/cesium/ports.js | 2 + src/render/cesium/ports.test.mjs | 2 +- src/render/cesiumAllowList.json | 1 - 16 files changed, 1765 insertions(+), 761 deletions(-) create mode 100644 src/render/cesium/drawFields.js create mode 100644 src/render/cesium/drawFields.test.mjs diff --git a/dev/conformance/main.js b/dev/conformance/main.js index 2d32b806c..f577614c5 100644 --- a/dev/conformance/main.js +++ b/dev/conformance/main.js @@ -137,67 +137,76 @@ async function runScenes({ record = false, only } = {}) { continue; } status(`${scene.id}…`); - await drawScene(renderer, scene, ctx, async (view, capture, settle) => { - const name = referenceName(scene.id, view.name); - const figure = document.createElement('figure'); - $('views').append(figure); - if (settle.state !== 'settled') { - const detail = `${settle.state}: ${settle.blockers.join(', ')}`; + // A scene the renderer refuses fails alone; the others still draw. + try { + await drawScene(renderer, scene, ctx, async (view, capture, settle) => { + const name = referenceName(scene.id, view.name); + const figure = document.createElement('figure'); + $('views').append(figure); + if (settle.state !== 'settled') { + const detail = `${settle.state}: ${settle.blockers.join(', ')}`; + results.push({ + scene: scene.id, + view: view.name, + status: 'fail', + detail, + }); + figure.innerHTML = `
${name}: ${escape(detail)}
`; + return; + } + if (record) { + const res = await fetch(SAVE + name, { + method: 'PUT', + body: capture, + }); + results.push({ + scene: scene.id, + view: view.name, + status: res.ok ? 'recorded' : 'fail', + detail: res.ok ? undefined : `save ${res.status}`, + }); + figure.innerHTML = `
${name}: recorded
`; + return; + } + const refBlob = await reference(name); + if (!refBlob) { + results.push({ + scene: scene.id, + view: view.name, + status: 'fail', + detail: 'no reference', + }); + figure.innerHTML = `
${name}: no reference
`; + return; + } + const [actual, expected] = await Promise.all([ + pixels(capture), + pixels(refBlob), + ]); + const diff = new Uint8ClampedArray(actual.data.length); + const outcome = compareImages(actual, expected, { diff }); results.push({ scene: scene.id, view: view.name, - status: 'fail', - detail, + status: outcome.match ? 'pass' : 'fail', + diffFraction: outcome.diffFraction, + solidPixels: outcome.solidPixels, + mismatchedPixels: outcome.mismatchedPixels, + ...(outcome.reason ? { detail: outcome.reason } : {}), }); - figure.innerHTML = `
${name}: ${escape(detail)}
`; - return; - } - if (record) { - const res = await fetch(SAVE + name, { - method: 'PUT', - body: capture, - }); - results.push({ - scene: scene.id, - view: view.name, - status: res.ok ? 'recorded' : 'fail', - detail: res.ok ? undefined : `save ${res.status}`, - }); - figure.innerHTML = `
${name}: recorded
`; - return; - } - const refBlob = await reference(name); - if (!refBlob) { - results.push({ - scene: scene.id, - view: view.name, - status: 'fail', - detail: 'no reference', - }); - figure.innerHTML = `
${name}: no reference
`; - return; - } - const [actual, expected] = await Promise.all([ - pixels(capture), - pixels(refBlob), - ]); - const diff = new Uint8ClampedArray(actual.data.length); - const outcome = compareImages(actual, expected, { diff }); + const diffUrl = outcome.reason + ? '' + : await toUrl(new ImageData(diff, actual.width, actual.height)); + figure.innerHTML = `
+
${name}: ${outcome.solidPixels} solid, ${outcome.mismatchedPixels} unexcused, ${(outcome.diffFraction * 100).toFixed(3)}% differ ${outcome.reason ?? ''}
`; + }); + } catch (error) { results.push({ scene: scene.id, - view: view.name, - status: outcome.match ? 'pass' : 'fail', - diffFraction: outcome.diffFraction, - solidPixels: outcome.solidPixels, - mismatchedPixels: outcome.mismatchedPixels, - ...(outcome.reason ? { detail: outcome.reason } : {}), + status: 'fail', + detail: String(error?.message ?? error), }); - const diffUrl = outcome.reason - ? '' - : await toUrl(new ImageData(diff, actual.width, actual.height)); - figure.innerHTML = `
-
${name}: ${outcome.solidPixels} solid, ${outcome.mismatchedPixels} unexcused, ${(outcome.diffFraction * 100).toFixed(3)}% differ ${outcome.reason ?? ''}
`; - }); + } } if (record) { // A partial recording keeps the other scenes' entries. diff --git a/scripts/format-scope.json b/scripts/format-scope.json index b7ca37fd3..07f8d9110 100644 --- a/scripts/format-scope.json +++ b/scripts/format-scope.json @@ -871,6 +871,8 @@ "src/layers/weather/rendering.js", "src/layers/weather/shellRendering.js", "src/layers/weather/shellRendering.test.mjs", + "src/render/cesium/drawFields.js", + "src/render/cesium/drawFields.test.mjs", "src/layers/weather/infraredAlpha.js", "src/layers/weather/infraredAlpha.test.mjs", "src/layers/weather/infraredImage.js", diff --git a/scripts/package-boundaries.json b/scripts/package-boundaries.json index 08a5326bf..5b9bbd12a 100644 --- a/scripts/package-boundaries.json +++ b/scripts/package-boundaries.json @@ -1070,6 +1070,7 @@ "src/render/cesium/heights.js", "src/queries/heights.js", "src/render/cesium/draw.js", + "src/render/cesium/drawFields.js", "src/render/cesium/drawQuads.js", "src/render/cesium/drawMeshes.js", "src/render/cesium/drawModels.js", @@ -1854,6 +1855,7 @@ "src/render/cesium/effects.js", "src/render/cesium/screenModulation.js", "src/render/cesium/draw.js", + "src/render/cesium/drawFields.js", "src/render/cesium/drawQuads.js", "src/render/cesium/drawMeshes.js", "src/render/cesium/drawModels.js", @@ -3056,6 +3058,7 @@ "src/render/cesium/credits.js", "src/render/cesium/tileRequests.js", "src/render/cesium/draw.js", + "src/render/cesium/drawFields.js", "src/render/cesium/drawQuads.js", "src/render/cesium/drawMeshes.js", "src/render/cesium/drawModels.js", @@ -3296,6 +3299,7 @@ "src/render/baseTilesets.js", "src/render/cesium/drawHit.js", "src/render/cesium/draw.js", + "src/render/cesium/drawFields.js", "src/render/cesium/drawMeshes.js", "src/render/cesium/drawQuads.js", "src/render/cesium/drawModels.js", @@ -4308,6 +4312,7 @@ "src/render/cesium/query.js", "src/render/cesium/heights.js", "src/render/cesium/draw.js", + "src/render/cesium/drawFields.js", "src/render/cesium/drawQuads.js", "src/render/cesium/drawMeshes.js", "src/render/cesium/drawModels.js", diff --git a/src/layers/weather/shellFixture.mjs b/src/layers/weather/shellFixture.mjs index 18e5de788..6cbe9e3a8 100644 --- a/src/layers/weather/shellFixture.mjs +++ b/src/layers/weather/shellFixture.mjs @@ -1,4 +1,6 @@ import * as Cesium from 'cesium'; +import { createCesiumFields } from '../../render/cesium/drawFields.js'; +import { bindRenderer } from '../../render/rendererOf.js'; /** Test double for the Cesium classes a weather shell constructs. */ export function createShellCesium({ maximumTextureSize = 0 } = {}) { @@ -154,3 +156,45 @@ export function renderShells(cesium, scene, count = 4) { scene.postRender.emit(); } } + +/** + * Bind to `viewer` a renderer whose draw port draws raster-shell fields + * with the Cesium adapter's code over these doubles, whose camera port reads + * the viewer's Cesium-shaped camera double (its view rectangle, `moveEnd` + * and height) and whose frame port runs on the scene's own events. + * @returns {{fields: object, unbind: () => void}} + */ +export function bindShellFields(viewer, cesium) { + const scene = viewer.scene; + const fields = createCesiumFields({ scene, cesium }); + const camera = () => viewer.camera ?? scene.camera; + const deg = 180 / Math.PI; + const unbind = bindRenderer(viewer, { + draw: { field: (spec) => fields.field(spec) }, + camera: { + pose: () => ({ height: camera()?.positionCartographic?.height }), + viewRectangle() { + const rect = camera()?.computeViewRectangle?.(); + return rect + ? { + west: rect.west * deg, + south: rect.south * deg, + east: rect.east * deg, + north: rect.north * deg, + } + : null; + }, + on(event, cb) { + if (event !== 'moveEnd') return () => {}; + return camera()?.moveEnd?.addEventListener(cb) ?? (() => {}); + }, + }, + frame: { + on(phase, cb) { + return scene[phase]?.addEventListener?.(cb) ?? (() => {}); + }, + requestRender: () => scene.requestRender(), + }, + }); + return { fields, unbind }; +} diff --git a/src/layers/weather/shellRendering.js b/src/layers/weather/shellRendering.js index 71ad2fca7..2031e88c4 100644 --- a/src/layers/weather/shellRendering.js +++ b/src/layers/weather/shellRendering.js @@ -1,9 +1,12 @@ -import * as Cesium from 'cesium'; -// The weather layers fly through `cameraOf`, drape through `findGlobe` and -// read `findCamera` and `findQuery`; this module is their Cesium side, so it -// brings the factories a viewer with no renderer bound gets those ports from. -import '../../render/cesium/camera.js'; -import '../../render/cesium/globe.js'; +// The shell draws through the draw port's raster-shell field; its detail +// window follows the camera port and its lift the frame port. +import { + findCamera, + findDraw, + findFrame, + findGlobe, + rendererOf, +} from '../../render/rendererOf.js'; import { acquireWeatherImage } from './infraredImage.js'; import { imageryHostStatus } from './imageryHost.js'; import { WEATHER_DETAIL_SIZE, WEATHER_IMAGE_SIZES } from './source.js'; @@ -11,12 +14,13 @@ import { msg } from '../../i18n/index.js'; /** * The viewer's own globe imagery, as a weather imagery host: where a layer - * drapes when the application shell names no host of its own. - * @param {object|null|undefined} viewer A Cesium viewer. - * @returns {{collection: object|undefined, kind: 'globe'}} + * drapes when the application shell names no host of its own. Its globe + * port's imagery stands for it, one object per port. + * @param {object|null|undefined} viewer The scene object the layer holds. + * @returns {{collection: object|null, kind: 'globe'}} */ export function globeImageryHost(viewer) { - return { collection: viewer?.imageryLayers, kind: 'globe' }; + return { collection: findGlobe(viewer)?.imagery ?? null, kind: 'globe' }; } /** Metres above the ellipsoid. Lower shells draw first, so lightning draws last. */ @@ -29,64 +33,19 @@ export const WEATHER_SHELL_HEIGHTS = Object.freeze({ }); // Decoded canvases per renderer, full-extent and detail images alike: the shown // frame and the warmed next frame, each full-extent and detail (four 4096×2048 -// canvases); nothing older survives them. Cesium holds the shown canvases -// through the material uniforms in any case. +// canvases); nothing older survives them. The renderer holds the shown +// canvases in any case. export const WEATHER_SHELL_CACHE_BYTES = 128 * 1024 * 1024; const MAX_IMAGE_BYTES = 16 * 1024 * 1024; -const MATERIAL_TYPE = 'WeatherFrame'; -// Renders after an image swap: one queues the upload, one uploads and draws, one spare. -const UPLOAD_FRAMES = 3; -// An empty detail window: the full-extent image shows everywhere. -const NO_WINDOW = Object.freeze({ west: 0, south: 0, east: -1, north: -1 }); // Detail windows, in degrees. const DETAIL_MIN_WIDTH = 6; const DETAIL_GRID = 0.5; -const shellHeights = new WeakMap(); // From far away Google's coarse 3D tiles rise tens of kilometres above the // ground and hide the shells, so the shells rise with the camera: 4 m per // kilometre of camera height, at most 60 km, in 500 m steps. const LIFT_PER_METRE = 0.004; const MAX_LIFT = 60_000; const LIFT_STEP = 500; -// Cesium binds a 1×1 white texture to an image uniform until its first upload: -// draw nothing until the full-extent image has arrived, and sample the detail -// image only once it has arrived. The window is west, south, east, north in the -// full-extent image's texture coordinates. -const MATERIAL_SOURCE = `czm_material czm_getMaterial(czm_materialInput materialInput) -{ - czm_material material = czm_getDefaultMaterial(materialInput); - vec2 st = materialInput.st; - vec4 coarse = texture(image, st); - vec2 dst = (st - window.xy) / max(window.zw - window.xy, vec2(1e-6)); - float inside = float(all(greaterThanEqual(st, window.xy)) && all(lessThanEqual(st, window.zw))); - float useDetail = inside * step(1.5, float(detailDimensions.x)); - vec4 c = mix(coarse, texture(detail, clamp(dst, 0.0, 1.0)), useDetail); - material.diffuse = czm_gammaCorrect(c.rgb); - material.alpha = c.a * alpha * step(1.5, float(imageDimensions.x)); - return material; -} -`; - -function registerMaterial(cesium) { - const cache = cesium.Material._materialCache; - if (cache.getMaterial(MATERIAL_TYPE)) return; - // A plain template: building the first material from a fabric would make that - // instance Cesium's shared template and keep its last image alive. - cache.addMaterial(MATERIAL_TYPE, { - fabric: { - type: MATERIAL_TYPE, - uniforms: { - image: cesium.Material.DefaultImageId, - detail: cesium.Material.DefaultImageId, - alpha: 1, - window: { type: 'vec4', x: 0, y: 0, z: -1, w: -1 }, - }, - // Diffuse and alpha share these samples, so one source, not components. - source: MATERIAL_SOURCE, - }, - translucent: false, - }); -} const sameEdges = (a, b) => a.west === b.west && @@ -101,239 +60,31 @@ export function shellLift(cameraHeight) { return Math.round(lift / LIFT_STEP) * LIFT_STEP; } -/** Keep weather shells first in the primitive collection, in ascending height: - * higher shells draw over lower ones and other opaque content draws over both. */ -export function orderWeatherShells(primitives, primitive, height) { - shellHeights.set(primitive, height); - if (typeof primitives.lowerToBottom !== 'function') return; - const shells = []; - for (let i = 0; i < primitives.length; i++) { - const item = primitives.get(i); - if (shellHeights.has(item)) shells.push(item); - } - const ordered = [...shells].sort( - (a, b) => shellHeights.get(a) - shellHeights.get(b), - ); - if (ordered.every((item, i) => primitives.get(i) === item)) return; - for (const item of ordered.reverse()) primitives.lowerToBottom(item); -} - -/** One raised rectangle drawing one full-extent image and, inside a window of - * it, an optional detail image. The owner calls destroy(). */ -export function createShellSurface({ +/** + * Tell `apply` the shell lift for the camera's height now and, each frame + * before it draws, whenever it changes. + * @param {object} viewer + * @param {(liftM: number) => void} apply + * @param {{cameraOf?: Function, frameOf?: Function}} [ports] + * @returns {() => void} Stops. + */ +export function followShellLift( viewer, - cesium, - rectangle, - height, - onSettled = () => {}, -}) { - registerMaterial(cesium); - const scene = viewer.scene; - const primitives = scene.primitives; - const material = new cesium.Material({ - fabric: { type: MATERIAL_TYPE }, - translucent: false, - }); - // Flat shading keeps the product colours independent of the viewing angle. - const appearance = new cesium.EllipsoidSurfaceAppearance({ - aboveGround: true, - flat: true, - translucent: false, - material, - }); - // Cesium orders its translucent pass itself (weighted OIT or distance), which - // cannot honour stacked heights. Draw in the opaque pass in scene.primitives - // order, alpha-blended and without depth writes, so higher shells draw over - // lower ones and nothing is hidden or picked through a shell. - appearance.getRenderState = () => ({ - depthTest: { enabled: true }, - depthMask: false, - blending: cesium.BlendingState.ALPHA_BLEND, - }); - const primitive = new cesium.Primitive({ - geometryInstances: new cesium.GeometryInstance({ - geometry: new cesium.RectangleGeometry({ - rectangle, - height, - granularity: cesium.Math.toRadians(0.5), - vertexFormat: cesium.EllipsoidSurfaceAppearance.VERTEX_FORMAT, - }), - }), - appearance, - asynchronous: true, - allowPicking: false, - }); - primitives.add(primitive); - orderWeatherShells(primitives, primitive, height); - // A uniform scale about the Earth's centre lifts every shell alike and keeps - // their order. - let lift = 0; - const offLift = scene.preRender?.addEventListener(() => { - const next = shellLift(scene.camera?.positionCartographic?.height); + apply, + { cameraOf = findCamera, frameOf = findFrame } = {}, +) { + let lift = null; + const read = () => { + const next = shellLift(cameraOf(viewer)?.pose?.().height); if (next === lift) return; lift = next; - primitive.modelMatrix = cesium.Matrix4.fromUniformScale( - 1 + lift / cesium.Ellipsoid.WGS84.maximumRadius, - ); - }); - let image = null; - let frames = 0; - // The detail image, its own upload count and a window waiting for it to draw. - let detail = null; - let detailFrames = 0; - let pendingWindow = null; - let offRender = null; - let destroyed = false; - - const fits = (size, value) => - !size || (size.x === value.width && size.y === value.height); - const uploaded = () => - image !== null && fits(material.uniforms.imageDimensions, image); - const detailDrawn = () => - detail !== null && - detailFrames === 0 && - fits(material.uniforms.detailDimensions, detail); - const drawn = () => - primitive.ready && - uploaded() && - frames === 0 && - (detail === null || (detailDrawn() && pendingWindow === null)); - function appliedWindow() { - const { x, y, z, w } = material.uniforms.window; - return z < x ? null : { west: x, south: y, east: z, north: w }; - } - function setWindow(rect) { - const next = rect ?? NO_WINDOW; - const { x, y, z, w } = material.uniforms.window; - if ( - x === next.west && - y === next.south && - z === next.east && - w === next.north - ) - return; - material.uniforms.window = new cesium.Cartesian4( - next.west, - next.south, - next.east, - next.north, - ); - scene.requestRender(); - } - // The render governor may idle the scene; request frames only until the - // asynchronous geometry is ready and the latest images have been drawn. - function tick() { - // Cesium updates a material only while its primitive is shown, so hidden - // frames upload nothing and count for nothing. - if (primitive.ready && primitive.show) { - if (frames > 0) frames--; - if (detailFrames > 0) detailFrames--; - // A texture is never shown at another window's place. - if (pendingWindow && detailDrawn()) { - setWindow(pendingWindow); - pendingWindow = null; - } - } - if (primitive.show && !drawn()) { - scene.requestRender(); - return; - } - offRender?.(); - offRender = null; - if (drawn()) onSettled(); - } - function wake() { - if (destroyed || !primitive.show || image === null || drawn()) return; - offRender ??= scene.postRender.addEventListener(tick); - scene.requestRender(); - } - - return { - setImage(next) { - if (destroyed || next === image) return; - image = next; - material.uniforms.image = next; - frames = UPLOAD_FRAMES; - wake(); - }, - setAlpha(value) { - if (destroyed || material.uniforms.alpha === value) return; - material.uniforms.alpha = value; - scene.requestRender(); - }, - /** Draw `next` inside `rect` (west, south, east, north in the full-extent - * image's texture coordinates, 0–1); null clears it. In the same window only - * the image changes, and Cesium keeps drawing the previous texture until - * this one is uploaded. A different window applies once its image has - * drawn; until then the full-extent image covers it. */ - setDetail(next, rect) { - if (destroyed) return; - if (!next) { - if (detail === null) return; - detail = null; - detailFrames = 0; - pendingWindow = null; - material.uniforms.detail = cesium.Material.DefaultImageId; - setWindow(null); - scene.requestRender(); - return; - } - if (next !== detail) { - detail = next; - material.uniforms.detail = next; - detailFrames = UPLOAD_FRAMES; - } - const applied = appliedWindow(); - if (applied && sameEdges(applied, rect)) { - pendingWindow = null; - } else { - setWindow(null); - pendingWindow = rect; - } - wake(); - }, - /** Returns whether visibility changed. */ - setShow(value) { - const show = Boolean(value); - if (destroyed || primitive.show === show) return false; - primitive.show = show; - wake(); - scene.requestRender(); - return true; - }, - destroy() { - if (destroyed) return; - destroyed = true; - offRender?.(); - offRender = null; - offLift?.(); - if (!primitives.isDestroyed?.() && primitives.contains(primitive)) - primitives.remove(primitive); - if (!primitive.isDestroyed()) primitive.destroy(); - // Primitive.destroy leaves the material and its texture alive. - if (!material.isDestroyed()) material.destroy(); - image = null; - detail = null; - pendingWindow = null; - scene.requestRender(); - }, - getDiagnostics() { - return { - height, - ready: Boolean(primitive.ready), - uploaded: uploaded(), - show: primitive.show, - alpha: material.uniforms.alpha, - rendering: offRender !== null, - // `uploaded` once the detail image has drawn; the window applies after. - detail: { uploaded: detailDrawn(), window: appliedWindow() }, - }; - }, + apply(next); }; + read(); + return frameOf(viewer)?.on('preRender', read) ?? (() => {}); } -function fitTexture(cesium, { width, height }) { - const limit = cesium.ContextLimits?.maximumTextureSize; +function fitTexture({ width, height }, limit) { // Halve, down to 1024 px wide, on devices with a smaller texture limit. while (limit > 0 && width > limit && width > 1024) { width /= 2; @@ -404,13 +155,14 @@ export function detailWindow(footprint, bounds, previous = null) { return previous && sameEdges(previous, next) ? previous : next; } +let weatherShells = 0; + /** Observed weather on 3D Tiles: one raised shell per product and one * full-extent image per frame. The previous image stays until the next is ready. * Inside a window around the view the same surface samples a sharper image of * that area, so the two images share one mesh and never blend. */ export function createWeatherShell({ viewer, - cesium = Cesium, product, height = WEATHER_SHELL_HEIGHTS[product], getHost = () => ({ collection: null, kind: 'tileset' }), @@ -421,17 +173,35 @@ export function createWeatherShell({ decodeImage, createCanvas = () => document.createElement('canvas'), cacheBytes = WEATHER_SHELL_CACHE_BYTES, + drawOf = findDraw, + cameraOf = findCamera, + frameOf = findFrame, + maxTextureSize = rendererOf(viewer)?.quality?.device?.().maxTextureSize ?? 0, }) { if (!Object.hasOwn(WEATHER_IMAGE_SIZES, product)) throw new TypeError('Unknown weather product'); - const scene = viewer.scene; - const size = fitTexture(cesium, WEATHER_IMAGE_SIZES[product]); - const detailSize = fitTexture(cesium, WEATHER_DETAIL_SIZE); + const size = fitTexture(WEATHER_IMAGE_SIZES[product], maxTextureSize); + const detailSize = fitTexture(WEATHER_DETAIL_SIZE, maxTextureSize); const infrared = product === 'clouds' || product === 'clouds-regional'; // Global infrared contrast depends on the requested extent, so a window would // not match the image around it; the globe host also shows one mosaic. const detailed = product !== 'clouds'; - let surface = null; + const requestRender = () => frameOf(viewer)?.requestRender('weather'); + // The shell's field, and what it was last given: the committed frame's + // bounds and image, and the detail. + let field = null; + let offLift = null; + let fieldBounds = null; + let fieldImage = null; + let fieldRect = null; + let fieldDetail = null; + let fieldAlpha = 0; + // What its 'drawn' has told: anything yet, the image and the detail it + // was last given, and whether a change waits for it. + let everDrawn = false; + let imageDrawn = false; + let detailDrawn = false; + let owed = false; let current = null; let incoming = null; let alpha = 0.7; @@ -456,6 +226,72 @@ export function createWeatherShell({ `${time}|${infrared ? mode : 'none'}${box ? `|${boundsKey(box)}` : ''}`; const wantedDetail = () => current && view ? cacheKey(current.time, current.infrared, view) : null; + const imageRef = (canvas, key) => ({ canvas, key }); + + function update(patch) { + owed = true; + field.update(patch); + } + function onDrawn() { + owed = false; + everDrawn = true; + imageDrawn = true; + detailDrawn = fieldDetail !== null; + if (incoming?.staged) commit(incoming); + } + function makeField(rectangle, image) { + field = drawOf(viewer).field({ + kind: 'rasterShell', + id: `weather-shell:${product}:${(weatherShells += 1)}`, + image, + rectangle, + heightM: height, + alpha, + detail: null, + }); + fieldAlpha = alpha; + owed = true; + field.on('drawn', onDrawn); + offLift = followShellLift(viewer, (liftM) => update({ liftM }), { + cameraOf, + frameOf, + }); + } + function dropField() { + offLift?.(); + offLift = null; + field?.dispose(); + field = null; + fieldBounds = null; + fieldImage = null; + fieldRect = null; + fieldDetail = null; + everDrawn = false; + imageDrawn = false; + detailDrawn = false; + owed = false; + } + /** Give the field `next` for its detail, unless it has it already. */ + function giveDetail(next) { + if (!field) return; + const given = incoming?.staged ? incoming.keptDetail : fieldDetail; + const same = + next === given || + (next && + given && + next.image.canvas === given.image.canvas && + sameEdges(next.rectangle, given.rectangle)); + if (same) return; + // A frame being staged takes its detail once it is committed; until + // then the detail is what the field goes back to if it is given up. + if (incoming?.staged) { + incoming.keptDetail = next; + return; + } + fieldDetail = next; + detailDrawn = false; + update({ detail: next }); + } function evict(keep = []) { const kept = new Set([...keep, current?.key, detail?.key]); @@ -517,11 +353,19 @@ export function createWeatherShell({ }; } function syncDetail() { - if (detail && current) surface?.setDetail(detail.image, detailRect()); - else surface?.setDetail(null); + if (detail && current) + giveDetail({ + image: imageRef(detail.image, detail.key), + rectangle: { ...detail.box }, + }); + else giveDetail(null); } function applyVisibility() { - return surface?.setShow(visible()) ?? false; + if (!field) return false; + const show = visible(); + if (field.show === show) return false; + field.show = show; + return true; } function cancelDetail() { clearTimeout(detailJob?.timeout); @@ -531,7 +375,7 @@ export function createWeatherShell({ function dropDetail() { detail = null; // The full-extent image covers the window in the same turn. - surface?.setDetail(null); + giveDetail(null); } function installDetail(job, image) { if (detailJob !== job) return; @@ -540,14 +384,14 @@ export function createWeatherShell({ detail = { box: job.box, key: job.key, image, stale: false }; syncDetail(); evict(); - scene.requestRender(); + requestRender(); } function failDetail(job) { if (detailJob !== job) return; clearTimeout(job.timeout); detailJob = null; if (detail?.stale) dropDetail(); - scene.requestRender(); + requestRender(); } /** Bring the detail to the shown frame and window. The previous detail image * stays until the next is decoded unless the window itself moved, and over at @@ -585,16 +429,9 @@ export function createWeatherShell({ } /** Recompute the window from the camera's ground footprint; returns whether it changed. */ function computeView() { - const rectangle = detailed - ? viewer.camera?.computeViewRectangle?.(scene.globe?.ellipsoid) + const footprint = detailed + ? (cameraOf(viewer)?.viewRectangle?.() ?? null) : null; - const degrees = cesium.Math.toDegrees; - const footprint = rectangle && { - west: degrees(rectangle.west), - south: degrees(rectangle.south), - east: degrees(rectangle.east), - north: degrees(rectangle.north), - }; const next = detailWindow( footprint, current.extent, @@ -608,7 +445,7 @@ export function createWeatherShell({ function watchCamera() { if (offCamera || !detailed) return; offCamera = - viewer.camera?.moveEnd?.addEventListener(() => { + cameraOf(viewer)?.on?.('moveEnd', () => { if (current && computeView()) refreshDetail(); }) ?? null; } @@ -623,18 +460,30 @@ export function createWeatherShell({ frame.owned = true; const abort = () => { if (incoming === frame) cancelIncoming(); - scene.requestRender(); + requestRender(); }; signal.addEventListener('abort', abort, { once: true }); frame.offAbort = () => signal.removeEventListener('abort', abort); } + /** A staged frame given up: the field goes back to what it drew. */ + function unstage(frame) { + if (!frame.staged) return; + frame.staged = false; + if (fieldBounds === null) { + dropField(); + return; + } + fieldDetail = frame.keptDetail ?? null; + detailDrawn = false; + imageDrawn = false; + update({ image: fieldImage, rectangle: fieldRect, detail: fieldDetail }); + } function close(frame) { frame.closed = true; frame.controller.abort(); clearTimeout(frame.timeout); frame.offAbort?.(); - frame.surface?.destroy(); - frame.surface = null; + unstage(frame); } function cancelIncoming() { if (!incoming) return; @@ -649,7 +498,7 @@ export function createWeatherShell({ close(frame); lastError = msg('Weather tiles unavailable · previous frame retained'); frame.resolve(false); - scene.requestRender(); + requestRender(); onChange(); } function commit(frame) { @@ -657,12 +506,13 @@ export function createWeatherShell({ incoming = null; clearTimeout(frame.timeout); frame.offAbort?.(); - if (frame.surface) { - surface?.destroy(); - surface = frame.surface; - frame.surface = null; - } const { west, south, east, north } = frame.snapshot.bounds; + if (frame.staged) { + frame.staged = false; + fieldBounds = frame.bounds; + fieldRect = { west, south, east, north }; + } + fieldImage = frame.image; current = { time: frame.time, product: frame.product, @@ -673,7 +523,10 @@ export function createWeatherShell({ mosaic: frame.mosaic, loadMs: now() - frame.startedAt, }; - surface.setAlpha(alpha); + if (fieldAlpha !== alpha) { + fieldAlpha = alpha; + update({ alpha }); + } applyVisibility(); lastError = null; evict(); @@ -684,31 +537,35 @@ export function createWeatherShell({ if (detail?.stale && detail.key !== wantedDetail()) dropDetail(); refreshDetail(); frame.resolve(true); - scene.requestRender(); + requestRender(); onChange(); } - function install(frame, image) { + function install(frame, texture) { if (frame.closed || incoming !== frame) return; - if (surface?.bounds === frame.bounds) { - // Cesium keeps drawing the previous texture until this one is uploaded. - surface.setImage(image); + frame.image = imageRef(texture, frame.key); + if (field && fieldBounds === frame.bounds) { + // The renderer keeps drawing the previous image until this one is drawn. + imageDrawn = false; + update({ image: frame.image }); commit(frame); return; } - // First frame or a new extent: stage an invisible surface and keep the - // previous one until the new geometry and texture are drawable. + // First frame or a new extent: the field keeps what it draws until the + // new rectangle and image can be drawn, then the frame commits. const { west, south, east, north } = frame.snapshot.bounds; - const next = createShellSurface({ - viewer, - cesium, - height, - rectangle: cesium.Rectangle.fromDegrees(west, south, east, north), - onSettled: () => commit(frame), - }); - next.bounds = frame.bounds; - frame.surface = next; - next.setAlpha(0); - next.setImage(image); + const rectangle = { west, south, east, north }; + frame.staged = true; + imageDrawn = false; + if (!field) makeField(rectangle, frame.image); + else { + frame.keptDetail = fieldDetail; + fieldDetail = null; + detailDrawn = false; + update({ image: frame.image, rectangle, detail: null }); + } + // A hidden field tells nothing drawn: the renderer readies the new + // content unseen and shows it, not the old, once the field shows. + if (!visible()) commit(frame); } return { @@ -724,7 +581,7 @@ export function createWeatherShell({ computeView(); refreshDetail(); } - if (changed) scene.requestRender(); + if (changed) requestRender(); return changed; }, cancelPrefetch, @@ -799,7 +656,9 @@ export function createWeatherShell({ mosaic: { fetched: false, decodeMs: null, cached: false }, controller: new AbortController(), startedAt: now(), - surface: null, + image: null, + staged: false, + keptDetail: null, owned: false, closed: false, resolve: null, @@ -821,7 +680,7 @@ export function createWeatherShell({ install(frame, texture); }) .catch(() => fail(frame)); - scene.requestRender(); + requestRender(); onChange(); return frame.result; }, @@ -834,12 +693,15 @@ export function createWeatherShell({ } applyVisibility(); if (!hidden) refreshDetail(); - scene.requestRender(); + requestRender(); }, setAlpha(value) { alpha = value; - surface?.setAlpha(alpha); - scene.requestRender(); + if (field && fieldAlpha !== alpha) { + fieldAlpha = alpha; + update({ alpha }); + } + requestRender(); }, clear() { cancelPrefetch(); @@ -848,8 +710,7 @@ export function createWeatherShell({ offCamera?.(); offCamera = null; dropDetail(); - surface?.destroy(); - surface = null; + dropField(); current = null; view = null; viewBounds = null; @@ -857,11 +718,21 @@ export function createWeatherShell({ lastError = null; images.clear(); imageBytes = 0; - scene.requestRender(); + requestRender(); }, getDiagnostics() { - const drawn = surface?.getDiagnostics(); - const applied = drawn?.detail.window; + // The detail is drawn once its image has drawn in its window. + const window = + current && detail && detailDrawn && fieldDetail ? detailRect() : null; + const drawn = field && { + height, + ready: everDrawn, + uploaded: imageDrawn, + show: field.show, + alpha: fieldAlpha, + rendering: owed && field.show, + detail: { uploaded: detailDrawn, window }, + }; return { host: 'shell', height, @@ -882,8 +753,8 @@ export function createWeatherShell({ drawn.ready && drawn.show && drawn.detail.uploaded && - applied && - sameEdges(applied, detailRect()), + window && + !owed, ), enabled: view !== null, }, @@ -894,7 +765,7 @@ export function createWeatherShell({ bytes: imageBytes, prefetching: !!prefetchJob, }, - imageryCount: Number(!!surface) + Number(!!incoming?.surface), + imageryCount: Number(fieldBounds !== null) + Number(!!incoming?.staged), mosaic: (incoming || current)?.mosaic, infrared: (incoming || current)?.infrared ?? 'filtered', loading: !!incoming, diff --git a/src/layers/weather/shellRendering.test.mjs b/src/layers/weather/shellRendering.test.mjs index ad65dcef2..f1f755f1c 100644 --- a/src/layers/weather/shellRendering.test.mjs +++ b/src/layers/weather/shellRendering.test.mjs @@ -2,16 +2,16 @@ import test from 'node:test'; import assert from 'node:assert/strict'; import * as Cesium from 'cesium'; import { - createShellSurface, createWeatherShell, detailWindow, - orderWeatherShells, + followShellLift, shellLift, WEATHER_SHELL_CACHE_BYTES, WEATHER_SHELL_HEIGHTS, } from './shellRendering.js'; import { NO_IMAGERY_HOST } from './imageryHost.js'; import { + bindShellFields, createShellCesium, createShellScene, renderShells, @@ -72,10 +72,12 @@ function harness({ product = 'radar', camera, ...options } = {}) { const fetches = []; const decoded = []; let host = { collection: null, kind: 'tileset' }; + const viewer = { scene, camera }; + bindShellFields(viewer, cesium); const shell = createWeatherShell({ - viewer: { scene, camera }, - cesium, + viewer, product, + maxTextureSize: cesium.ContextLimits.maximumTextureSize, getHost: () => host, fetchImpl: async (url, init) => { fetches.push({ url, signal: init.signal }); @@ -131,317 +133,36 @@ test('shell heights stack every product with lightning highest', () => { assert.equal(WEATHER_SHELL_CACHE_BYTES, 128 * 1024 * 1024); }); -test('surface builds a flat raised rectangle drawn in primitive order without depth writes', () => { - const cesium = createShellCesium(); - const scene = createShellScene(); - const rectangle = Cesium.Rectangle.fromDegrees(-130, 20, -60, 55); - const surface = createShellSurface({ - viewer: { scene }, - cesium, - rectangle, - height: 6_200, - }); - const template = cesium.templates.get('WeatherFrame'); - assert.ok(!(template instanceof cesium.Material), 'plain template'); - assert.deepEqual(template.fabric.uniforms, { - image: Cesium.Material.DefaultImageId, - detail: Cesium.Material.DefaultImageId, - alpha: 1, - window: { type: 'vec4', x: 0, y: 0, z: -1, w: -1 }, - }); - const { source } = template.fabric; - assert.match( - source, - /material\.alpha = c\.a \* alpha \* step\(1\.5, float\(imageDimensions\.x\)\);/, - 'nothing draws before the full-extent image', - ); - assert.match( - source, - /float useDetail = inside \* step\(1\.5, float\(detailDimensions\.x\)\);/, - 'the detail image is sampled only once it has arrived', - ); - assert.match( - source, - /all\(greaterThanEqual\(st, window\.xy\)\) && all\(lessThanEqual\(st, window\.zw\)\)/, - ); - assert.match( - source, - /mix\(coarse, texture\(detail, clamp\(dst, 0\.0, 1\.0\)\), useDetail\)/, - ); - assert.match(source, /material\.diffuse = czm_gammaCorrect\(c\.rgb\);/); - const [primitive] = scene.primitives.items; - const appearance = primitive.appearance; - assert.equal(appearance.material.options.translucent, false); - assert.deepEqual( - { ...appearance.options, material: undefined }, - { - aboveGround: true, - flat: true, - translucent: false, - material: undefined, - }, - ); - assert.deepEqual(appearance.getRenderState(), { - depthTest: { enabled: true }, - depthMask: false, - blending: Cesium.BlendingState.ALPHA_BLEND, - }); - const geometry = primitive.options.geometryInstances.geometry.options; - assert.equal(geometry.rectangle, rectangle); - assert.equal(geometry.height, 6_200); - assert.equal(geometry.granularity, Cesium.Math.toRadians(0.5)); - assert.equal( - geometry.vertexFormat, - Cesium.EllipsoidSurfaceAppearance.VERTEX_FORMAT, - ); - assert.equal(primitive.options.asynchronous, true); - assert.equal(primitive.options.allowPicking, false); - const lower = createShellSurface({ - viewer: { scene }, - cesium, - rectangle, - height: 5_000, - }); - assert.equal(cesium.templates.size, 1, 'the template registers once'); - assert.deepEqual( - scene.primitives.items.map( - (item) => item.options.geometryInstances.geometry.options.height, - ), - [5_000, 6_200], - ); - lower.destroy(); - surface.destroy(); -}); - -test('a surface applies a new detail window only once its image has drawn; the same window swaps only the image', () => { - const cesium = createShellCesium(); - const scene = createShellScene(); - const surface = createShellSurface({ - viewer: { scene }, - cesium, - rectangle: Cesium.Rectangle.fromDegrees(-130, 20, -60, 55), - height: 6_200, - }); - const [primitive] = scene.primitives.items; - const { uniforms } = primitive.appearance.material; - const render = (count) => renderShells(cesium, scene, count); - const image = () => ({ width: 4096, height: 2048 }); - surface.setImage(image()); - render(); - assert.deepEqual(surface.getDiagnostics().detail, { - uploaded: false, - window: null, - }); - const a = { west: 0.25, south: 0.5, east: 0.5, north: 0.75 }; - const first = image(); - surface.setDetail(first, a); - assert.equal(uniforms.detail, first); - assert.deepEqual(windowOf(primitive), NONE, 'the full-extent image covers'); - assert.equal(scene.postRender.size, 1, 'renders until the detail has drawn'); - render(2); - assert.deepEqual(windowOf(primitive), NONE); - render(1); - assert.deepEqual(windowOf(primitive), { x: 0.25, y: 0.5, z: 0.5, w: 0.75 }); - assert.ok(uniforms.window instanceof Cesium.Cartesian4); - assert.deepEqual(surface.getDiagnostics().detail, { - uploaded: true, - window: a, - }); - assert.equal(scene.postRender.size, 0); - - // A time change in the same window: Cesium keeps drawing the previous - // texture until the new one is uploaded, so the window stays. - const applied = uniforms.window; - const second = image(); - surface.setDetail(second, { ...a }); - assert.equal(uniforms.detail, second); - assert.equal(uniforms.window, applied, 'only the image is written'); - assert.equal(surface.getDiagnostics().detail.uploaded, false); - render(); - assert.equal(surface.getDiagnostics().detail.uploaded, true); - assert.equal(uniforms.window, applied); - const renders = scene.renders; - surface.setDetail(second, { ...a }); - assert.equal(scene.renders, renders, 'an unchanged detail costs nothing'); - assert.equal(scene.postRender.size, 0); - - // A different window empties at once and applies once its image has drawn. - const b = { west: 0.5, south: 0.25, east: 0.75, north: 0.5 }; - surface.setDetail(image(), b); - assert.deepEqual(windowOf(primitive), NONE); - render(2); - assert.deepEqual(windowOf(primitive), NONE); - render(1); - assert.deepEqual(windowOf(primitive), { x: 0.5, y: 0.25, z: 0.75, w: 0.5 }); - - surface.setDetail(null); - assert.equal(uniforms.detail, Cesium.Material.DefaultImageId); - assert.deepEqual(windowOf(primitive), NONE); - assert.deepEqual(surface.getDiagnostics().detail, { - uploaded: false, - window: null, - }); - render(); - assert.deepEqual( - { ...uniforms.detailDimensions }, - { type: 'ivec3', x: 1, y: 1 }, - ); - // Counted renders alone are not enough: the bound texture must be this image. - surface.setDetail(image(), a); - for (let i = 0; i < 4; i++) scene.postRender.emit(); - assert.deepEqual(windowOf(primitive), NONE, 'still the 1×1 default'); - render(1); - assert.deepEqual(windowOf(primitive), { x: 0.25, y: 0.5, z: 0.5, w: 0.75 }); - surface.destroy(); - surface.setDetail(image(), b); - assert.deepEqual(windowOf(primitive), { x: 0.25, y: 0.5, z: 0.5, w: 0.75 }); - assert.equal(scene.postRender.size, 0); -}); - test('shells rise with the camera over coarse 3D tiles, in steps, up to 60 km', () => { assert.equal(shellLift(undefined), 0); assert.equal(shellLift(1_200), 0, 'city views keep the shell heights'); assert.equal(shellLift(3_000_000), 12_000); assert.equal(shellLift(8_000_000), 32_000); assert.equal(shellLift(18_500_000), 60_000); - const camera = { positionCartographic: { height: 1_200 } }; - const scene = { - primitives: new Cesium.PrimitiveCollection(), - preRender: new Cesium.Event(), - postRender: new Cesium.Event(), - camera, - requestRender() {}, - }; - const surface = createShellSurface({ - viewer: { scene }, - cesium: Cesium, - rectangle: Cesium.Rectangle.fromDegrees(-130, 20, -60, 55), - height: 5_800, + let height = 1_200; + const preRender = new Set(); + const lifts = []; + const off = followShellLift({}, (lift) => lifts.push(lift), { + cameraOf: () => ({ pose: () => ({ height }) }), + frameOf: () => ({ + on(phase, cb) { + assert.equal(phase, 'preRender'); + preRender.add(cb); + return () => preRender.delete(cb); + }, + }), }); - const primitive = scene.primitives.get(0); - const identity = primitive.modelMatrix; - scene.preRender.raiseEvent(); - assert.equal(primitive.modelMatrix, identity, 'no lift, no new matrix'); - camera.positionCartographic.height = 8_000_000; - scene.preRender.raiseEvent(); - const radius = Cesium.Ellipsoid.WGS84.maximumRadius; - assert.ok( - Math.abs(primitive.modelMatrix[0] * radius - (radius + 32_000)) < 1e-3, - ); - const lifted = primitive.modelMatrix; - camera.positionCartographic.height = 8_010_000; - scene.preRender.raiseEvent(); - assert.equal(primitive.modelMatrix, lifted, 'the same step keeps the matrix'); - surface.destroy(); - assert.equal(scene.preRender.numberOfListeners, 0); -}); - -test('real Cesium builds the two-texture material, the opaque-pass appearance and the rectangle primitive', () => { - const scene = { - primitives: new Cesium.PrimitiveCollection(), - postRender: new Cesium.Event(), - requestRender() {}, - }; - const surface = createShellSurface({ - viewer: { scene }, - cesium: Cesium, - rectangle: Cesium.Rectangle.fromDegrees(-130, 20, -60, 55), - height: 6_600, - }); - const cached = Cesium.Material._materialCache.getMaterial('WeatherFrame'); - assert.ok(cached && !(cached instanceof Cesium.Material)); - const primitive = scene.primitives.get(0); - const material = primitive.appearance.material; - assert.ok(primitive instanceof Cesium.Primitive); - assert.equal(material.type, 'WeatherFrame'); - assert.equal(material.isTranslucent(), false); - assert.equal(primitive.appearance.isTranslucent(), false, 'opaque pass'); - assert.equal(primitive.appearance.getRenderState().depthMask, false); - assert.equal( - Cesium.Appearance.prototype.getRenderState.call(primitive.appearance) - .depthMask, - true, - 'the default opaque render state would write depth', - ); - assert.deepEqual( - [material.uniforms.imageDimensions.x, material.uniforms.detailDimensions.x], - [1, 1], - 'Cesium tracks both bound texture sizes', - ); - const shader = material.shaderSource; - for (const declaration of [ - /uniform sampler2D image_\d+;/, - /uniform sampler2D detail_\d+;/, - /uniform float alpha_\d+;/, - /uniform vec4 window_\d+;/, - /uniform ivec3 imageDimensions_\d+;/, - /uniform ivec3 detailDimensions_\d+;/, - ]) - assert.match(shader, declaration); - assert.match(shader, /texture\(image_\d+, st\)/); - assert.match(shader, /texture\(detail_\d+, clamp\(dst, 0\.0, 1\.0\)\)/); - assert.match(shader, /lessThanEqual\(st, window_\d+\.zw\)/); - assert.match(shader, /step\(1\.5, float\(detailDimensions_\d+\.x\)\)/); - assert.match( - shader, - /material\.alpha = c\.a \* alpha_\d+ \* step\(1\.5, float\(imageDimensions_\d+\.x\)\);/, - 'the uniform is renamed, the material field is not', - ); - assert.match(shader, /float useDetail = inside \* step/, 'locals keep names'); - const detail = { width: 4096, height: 2048 }; - surface.setDetail(detail, { west: 0.1, south: 0.2, east: 0.3, north: 0.4 }); - assert.equal(material.uniforms.detail, detail); - assert.deepEqual( - [material.uniforms.window.z, material.uniforms.window.w], - [-1, -1], - 'no window before the image has drawn', - ); - surface.setDetail(null); - assert.equal(material.uniforms.detail, Cesium.Material.DefaultImageId); - surface.setAlpha(0.4); - assert.equal(material.uniforms.alpha, 0.4); - surface.destroy(); - assert.equal(scene.primitives.length, 0); - assert.equal(primitive.isDestroyed(), true); - assert.equal(material.isDestroyed(), true); - assert.equal(scene.postRender.numberOfListeners, 0); -}); - -test('shells draw first, in height order, regardless of add order', () => { - const scene = createShellScene(); - const other = { name: 'other' }; - scene.primitives.add(other); - const add = (name, height) => { - const primitive = { name }; - scene.primitives.add(primitive); - orderWeatherShells(scene.primitives, primitive, height); - return primitive; - }; - add('lightning', 6_600); - add('radar', 6_200); - add('wind', 5_000); - const later = { name: 'later' }; - scene.primitives.add(later); - add('regional', 5_800); - assert.deepEqual( - scene.primitives.items.map(({ name }) => name), - ['wind', 'regional', 'radar', 'lightning', 'other', 'later'], - ); - const primitives = new Cesium.PrimitiveCollection({ - destroyPrimitives: false, - }); - const real = (name) => ({ name, update() {}, isDestroyed: () => false }); - const tileset = primitives.add(real('tileset')); - const lightning = primitives.add(real('lightning')); - orderWeatherShells(primitives, lightning, 6_600); - const radar = primitives.add(real('radar')); - orderWeatherShells(primitives, radar, 6_200); - assert.deepEqual( - [0, 1, 2].map((i) => primitives.get(i).name), - ['radar', 'lightning', 'tileset'], - 'real Cesium collection order', - ); - assert.equal(tileset.name, 'tileset'); + const frame = () => [...preRender].forEach((cb) => cb()); + assert.deepEqual(lifts, [0], 'told at once'); + frame(); + assert.deepEqual(lifts, [0], 'no change, nothing told'); + height = 8_000_000; + frame(); + height = 8_010_000; + frame(); + assert.deepEqual(lifts, [0, 32_000], 'the same step is told once'); + off(); + assert.equal(preRender.size, 0); }); test('first frame stages invisibly, requests renders until drawable and then commits', async () => { @@ -871,40 +592,6 @@ test('an unowned restage is joined by the next request for the same frame', asyn const footprint = (west, south, east, north) => ({ west, south, east, north }); const box = (west, south, east, north) => ({ west, south, east, north }); -test('hidden frames do not count towards a pending detail window', () => { - const cesium = createShellCesium(); - const scene = createShellScene(); - const surface = createShellSurface({ - viewer: { scene }, - cesium, - rectangle: Cesium.Rectangle.fromDegrees(-130, 20, -60, 55), - height: 6_200, - }); - const [primitive] = scene.primitives.items; - const render = (count) => renderShells(cesium, scene, count); - const image = () => ({ width: 4096, height: 2048 }); - surface.setImage(image()); - const a = { west: 0.25, south: 0.5, east: 0.5, north: 0.75 }; - surface.setDetail(image(), a); - render(); - assert.deepEqual(windowOf(primitive), { x: 0.25, y: 0.5, z: 0.5, w: 0.75 }); - // A different window with a same-sized image: the dimensions alone cannot - // tell the textures apart, so only shown frames may count. - const b = { west: 0.5, south: 0.25, east: 0.75, north: 0.5 }; - surface.setDetail(image(), b); - assert.deepEqual(windowOf(primitive), NONE); - for (let i = 0; i < 3; i++) { - surface.setShow(false); - scene.postRender.emit(); - surface.setShow(true); - } - assert.deepEqual(windowOf(primitive), NONE, 'hidden frames counted nothing'); - render(2); - assert.deepEqual(windowOf(primitive), NONE); - render(1); - assert.deepEqual(windowOf(primitive), { x: 0.5, y: 0.25, z: 0.75, w: 0.5 }); -}); - test('detail windows are sized from the footprint, snapped to 0.5° and clamped inside the product', () => { // max(2 × the longitude span, 6°) wide, half as tall. assert.deepEqual( diff --git a/src/layers/weather/weather.test.mjs b/src/layers/weather/weather.test.mjs index d4a2a726d..cf341f31f 100644 --- a/src/layers/weather/weather.test.mjs +++ b/src/layers/weather/weather.test.mjs @@ -7,6 +7,7 @@ import * as Cesium from 'cesium'; import { Color, ImageryLayerCollection, GeographicTilingScheme } from 'cesium'; import { NO_IMAGERY_HOST } from './imageryHost.js'; import { createWeatherShell } from './shellRendering.js'; +import { createCesiumFields } from '../../render/cesium/drawFields.js'; import { WEATHER_IMAGERY_Z } from './imageryOrder.js'; import { fakeGlobePort } from '../../testSupport/fakeGlobePort.mjs'; import { fakeSceneFrame } from '../../testSupport/fakeCesiumScene.mjs'; @@ -222,6 +223,9 @@ function renderingHarness(options = {}) { Credit: Cesium.Credit, Rectangle: Cesium.Rectangle, }; + // The Cesium draw port's raster shells, over the doubles. + const fields = createCesiumFields({ scene: viewer.scene, cesium }); + const draw = { field: (spec) => fields.field(spec) }; const rendering = createWeatherRendering({ viewer, globeOf: () => globe, @@ -230,7 +234,12 @@ function renderingHarness(options = {}) { frameOf: () => frame, toBitmap: (canvas) => canvas, createShell: (shellOptions) => - createWeatherShell({ ...shellOptions, cesium }), + createWeatherShell({ + ...shellOptions, + drawOf: () => draw, + cameraOf: cameraOver, + frameOf: () => frame, + }), fetchImpl: async () => mockResponse(), decodeImage: async () => ({ width: 2048, height: 1024, close() {} }), createCanvas, diff --git a/src/layers/wind/rendering.js b/src/layers/wind/rendering.js index 21735a93e..cfcf324dc 100644 --- a/src/layers/wind/rendering.js +++ b/src/layers/wind/rendering.js @@ -5,12 +5,12 @@ import * as Cesium from 'cesium'; import '../../render/cesium/globe.js'; import '../../render/cesium/camera.js'; import { - createShellSurface, + followShellLift, WEATHER_SHELL_HEIGHTS, } from '../weather/shellRendering.js'; import { createWindRelief } from './relief.js'; import { WEATHER_IMAGERY_Z } from '../weather/imageryOrder.js'; -import { findGlobe } from '../../render/rendererOf.js'; +import { findDraw, findGlobe } from '../../render/rendererOf.js'; import { NO_IMAGERY_HOST } from '../weather/imageryHost.js'; import { msg } from '../../i18n/index.js'; import { createWindGpuRendering } from './gpuRendering.js'; @@ -63,6 +63,58 @@ function sameWind(previous, next, previousField, nextField) { return true; } +let windShells = 0; + +/** The colour field as a raised shell over the whole globe, through the + * draw port's raster-shell field; it rises with the camera. */ +function createWindShell(viewer, draw, texture, alpha) { + const seq = (windShells += 1); + const height = WEATHER_SHELL_HEIGHTS.wind; + const field = draw.field({ + kind: 'rasterShell', + id: `wind-shell:${seq}`, + image: { canvas: texture, key: `wind-shell:${seq}` }, + rectangle: { west: -180, south: -90, east: 180, north: 90 }, + heightM: height, + alpha, + }); + let shownAlpha = alpha; + let drawn = false; + let owed = true; + field.on('drawn', () => { + drawn = true; + owed = false; + }); + const offLift = followShellLift(viewer, (liftM) => { + owed = true; + field.update({ liftM }); + }); + return { + setAlpha(value) { + if (value === shownAlpha) return; + shownAlpha = value; + owed = true; + field.update({ alpha: value }); + }, + setShow(value) { + field.show = Boolean(value); + }, + destroy() { + offLift(); + field.dispose(); + }, + getDiagnostics: () => ({ + height, + ready: drawn, + uploaded: drawn, + show: field.show, + alpha: shownAlpha, + rendering: owed && field.show, + detail: { uploaded: false, window: null }, + }), + }; +} + /** Globe-projected surface flow plus one owned, static colour field: globe * imagery on the globe host, a raised shell on the 3D Tiles host. */ export function createWindRendering({ @@ -73,6 +125,7 @@ export function createWindRendering({ eventTarget = globalThis.window, createGpuRendering = createWindGpuRendering, globeOf = findGlobe, + drawOf = findDraw, onStatusChange, } = {}) { // The host the shell names, else the viewer's globe imagery. @@ -362,7 +415,8 @@ export function createWindRendering({ imageryError = fieldUnavailableText(overlay); return; } - if (kind === 'tileset' ? !cesium.Primitive : !globe) { + const draw = kind === 'tileset' ? drawOf(viewer) : null; + if (kind === 'tileset' ? !draw?.field : !globe) { imageryError = msg('Globe imagery unavailable'); return; } @@ -375,15 +429,13 @@ export function createWindRendering({ pixels.data.set(raster.rgba); ctx.putImageData(pixels, 0, 0); if (kind === 'tileset') { - shell = createShellSurface({ + shell = createWindShell( viewer, - cesium, - rectangle: cesium.Rectangle.MAX_VALUE, - height: WEATHER_SHELL_HEIGHTS.wind, - }); - shell.setImage(texture); + draw, + texture, + overlay === 'temperature' ? 1 : 0.85, + ); imageryKind = kind; - shell.setAlpha(overlay === 'temperature' ? 1 : 0.85); updateImageryFade(viewer.scene.camera, true); viewer.scene?.requestRender?.(); return; diff --git a/src/layers/wind/rendering.test.mjs b/src/layers/wind/rendering.test.mjs index f34825527..815f8c90a 100644 --- a/src/layers/wind/rendering.test.mjs +++ b/src/layers/wind/rendering.test.mjs @@ -8,7 +8,9 @@ import { WEATHER_IMAGERY_Z } from '../weather/imageryOrder.js'; import { createShellCesium, createShellScene, + renderShells, } from '../weather/shellFixture.mjs'; +import { createCesiumFields } from '../../render/cesium/drawFields.js'; function event() { const listeners = new Set(); @@ -197,8 +199,9 @@ function harness({ }, isDestroyed: () => false, }; + const shellCesium = shell ? createShellCesium() : null; const cesium = { - ...(shell ? createShellCesium() : {}), + ...(shellCesium ?? {}), GeographicTilingScheme: Cesium.GeographicTilingScheme, Credit: Cesium.Credit, Event: Cesium.Event, @@ -220,11 +223,17 @@ function harness({ } }, }; + const fields = shellCesium + ? createCesiumFields({ scene: viewer.scene, cesium: shellCesium }) + : null; + const draw = fields && { field: (spec) => fields.field(spec) }; const rendering = createWindRendering({ cesium, container, getViewer: () => viewer, globeOf: (given) => (given === viewer ? globe : null), + // The Cesium draw port's raster shells, over the doubles. + drawOf: (given) => (given === viewer ? draw : null), createGpuRendering, onStatusChange, getHost, @@ -245,7 +254,7 @@ function harness({ motion, preRender, viewer, - cesium, + cesium: shellCesium ?? cesium, imagery, removed, primitives: () => shellScene?.primitives.items ?? [], @@ -1028,10 +1037,14 @@ test('scalar field becomes a raised shell on 3D Tiles and survives no-host event eventTarget.dispatchEvent(new Event('gev:map-stack-changed')); assert.equal(h.imagery.length, 0); assert.equal(h.removed[0].destroy, true); + // It shows once its geometry and image are ready. + renderShells(h.cesium, h.viewer.scene); const [primitive] = h.primitives(); const geometry = primitive.options.geometryInstances.geometry.options; assert.equal(geometry.height, 5_000); - assert.equal(geometry.rectangle, h.cesium.Rectangle.MAX_VALUE); + assert.ok( + h.cesium.Rectangle.equals(geometry.rectangle, h.cesium.Rectangle.MAX_VALUE), + ); const material = primitive.appearance.material; assert.equal(h.textures.length, 2); assert.equal(material.uniforms.image, h.textures[1]); @@ -1121,6 +1134,7 @@ for (const overlay of ['speed', 'temperature', 'pressure']) { h.rendering.setOptions({ overlay }); h.rendering.setField(field); h.rendering.start(); + renderShells(h.cesium, h.viewer.scene); assert.equal(h.imagery.length, 0); const [primitive] = h.primitives(); const { uniforms } = primitive.appearance.material; @@ -1185,6 +1199,7 @@ for (const overlay of ['speed', 'temperature', 'pressure']) { }, }); h.rendering.start(); + renderShells(h.cesium, h.viewer.scene); const [primitive] = h.primitives(); const textures = h.textures.length; const baseAlpha = overlay === 'temperature' ? 1 : 0.85; diff --git a/src/render/cesium/draw.js b/src/render/cesium/draw.js index 43b008259..1f9e63ad2 100644 --- a/src/render/cesium/draw.js +++ b/src/render/cesium/draw.js @@ -40,6 +40,7 @@ import { createGpuIcons, GPU_ICON_CAPABILITIES } from './gpuIcons.js'; import { createModelSets } from './drawModels.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) { @@ -358,6 +359,8 @@ export function createCesiumDraw({ requestRender: requestFrame = null, }) { const sets = new Map(); + // Fields share the sets' ids. + const fieldPart = createCesiumFields({ scene, report }); 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 @@ -371,7 +374,8 @@ export function createCesiumDraw({ }; function makeSet(kind, spec, build) { - if (sets.has(spec.id)) throw new Error(`a set with id ${spec.id} is live`); + 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), @@ -3868,6 +3872,15 @@ export function createCesiumDraw({ 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 () => {}; @@ -3950,6 +3963,8 @@ export function createCesiumDraw({ */ 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?.()) { @@ -3989,7 +4004,11 @@ provideUnboundDraw((viewer) => { typeof scene.requestRender !== 'function' ) return null; - const part = createCesiumDraw({ scene, report: uncaught }); + 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()), diff --git a/src/render/cesium/drawFields.js b/src/render/cesium/drawFields.js new file mode 100644 index 000000000..4d95244b4 --- /dev/null +++ b/src/render/cesium/drawFields.js @@ -0,0 +1,644 @@ +/** + * @module render/cesium/drawFields + * @description The Cesium draw port's `field` handles. It draws one kind: + * `rasterShell`, a raster on a rectangle raised above the ellipsoid, drawn + * flat in the opaque pass in the scene's primitive order (ascending height), + * alpha-blended, without depth writes and never picked. Other kinds are + * refused loudly. + * + * Choices the contract leaves open, taken conservatively: + * - 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. + * - 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 + * built as a second surface, drawn invisibly until its geometry and + * images are ready, and then takes the first one's place in one frame. + * - A `detail` in a new rectangle shows the full image there until the + * detail image has drawn, never the old detail at the new place; one in + * the same rectangle swaps only the image, the old one drawing until the + * new is uploaded. + * - `liftM` scales the shell about the Earth's centre, so every shell + * rises alike and keeps its order. + */ +import * as Cesium from 'cesium'; +import { listenerList, uncaught } from './common.js'; + +const MATERIAL_TYPE = 'DrawRasterShell'; +// Renders after an image swap: one queues the upload, one uploads and draws, one spare. +const UPLOAD_FRAMES = 3; +// An empty detail window: the full-extent image shows everywhere. +const NO_WINDOW = Object.freeze({ west: 0, south: 0, east: -1, north: -1 }); +const shellHeights = new WeakMap(); +// Cesium binds a 1×1 white texture to an image uniform until its first upload: +// draw nothing until the full-extent image has arrived, and sample the detail +// image only once it has arrived. The window is west, south, east, north in the +// full-extent image's texture coordinates. +const MATERIAL_SOURCE = `czm_material czm_getMaterial(czm_materialInput materialInput) +{ + czm_material material = czm_getDefaultMaterial(materialInput); + vec2 st = materialInput.st; + vec4 coarse = texture(image, st); + vec2 dst = (st - window.xy) / max(window.zw - window.xy, vec2(1e-6)); + float inside = float(all(greaterThanEqual(st, window.xy)) && all(lessThanEqual(st, window.zw))); + float useDetail = inside * step(1.5, float(detailDimensions.x)); + vec4 c = mix(coarse, texture(detail, clamp(dst, 0.0, 1.0)), useDetail); + material.diffuse = czm_gammaCorrect(c.rgb); + material.alpha = c.a * alpha * step(1.5, float(imageDimensions.x)); + return material; +} +`; + +function registerMaterial(cesium) { + const cache = cesium.Material._materialCache; + if (cache.getMaterial(MATERIAL_TYPE)) return; + // A plain template: building the first material from a fabric would make that + // instance Cesium's shared template and keep its last image alive. + cache.addMaterial(MATERIAL_TYPE, { + fabric: { + type: MATERIAL_TYPE, + uniforms: { + image: cesium.Material.DefaultImageId, + detail: cesium.Material.DefaultImageId, + alpha: 1, + window: { type: 'vec4', x: 0, y: 0, z: -1, w: -1 }, + }, + // Diffuse and alpha share these samples, so one source, not components. + source: MATERIAL_SOURCE, + }, + translucent: false, + }); +} + +const sameEdges = (a, b) => + a.west === b.west && + a.south === b.south && + a.east === b.east && + a.north === b.north; + +/** Keep raster shells first in the primitive collection, in ascending height: + * higher shells draw over lower ones and other opaque content draws over both. */ +export function orderShells(primitives, primitive, height) { + shellHeights.set(primitive, height); + if (typeof primitives.lowerToBottom !== 'function') return; + const shells = []; + for (let i = 0; i < primitives.length; i++) { + const item = primitives.get(i); + if (shellHeights.has(item)) shells.push(item); + } + const ordered = [...shells].sort( + (a, b) => shellHeights.get(a) - shellHeights.get(b), + ); + if (ordered.every((item, i) => primitives.get(i) === item)) return; + for (const item of ordered.reverse()) primitives.lowerToBottom(item); +} + +/** One raised rectangle drawing one full-extent image and, inside a window of + * it, an optional detail image. The owner calls destroy(). `onSettled` is + * told each time what it was last given has drawn. With `onWake` its owner + * runs its frames: it is told when the surface needs them, and calls + * `tick()` after each render while `awake()`; without, it listens itself. */ +export function createShellSurface({ + scene, + cesium = Cesium, + rectangle, + height, + onSettled = () => {}, + onWake = null, +}) { + registerMaterial(cesium); + const primitives = scene.primitives; + // A scene destroyed under it asks for nothing. + const ask = () => { + if (!scene.isDestroyed?.()) scene.requestRender(); + }; + const material = new cesium.Material({ + fabric: { type: MATERIAL_TYPE }, + translucent: false, + }); + // Flat shading keeps the product colours independent of the viewing angle. + const appearance = new cesium.EllipsoidSurfaceAppearance({ + aboveGround: true, + flat: true, + translucent: false, + material, + }); + // Cesium orders its translucent pass itself (weighted OIT or distance), which + // cannot honour stacked heights. Draw in the opaque pass in scene.primitives + // order, alpha-blended and without depth writes, so higher shells draw over + // lower ones and nothing is hidden or picked through a shell. + appearance.getRenderState = () => ({ + depthTest: { enabled: true }, + depthMask: false, + blending: cesium.BlendingState.ALPHA_BLEND, + }); + const primitive = new cesium.Primitive({ + geometryInstances: new cesium.GeometryInstance({ + geometry: new cesium.RectangleGeometry({ + rectangle, + height, + granularity: cesium.Math.toRadians(0.5), + vertexFormat: cesium.EllipsoidSurfaceAppearance.VERTEX_FORMAT, + }), + }), + appearance, + asynchronous: true, + allowPicking: false, + }); + primitives.add(primitive); + orderShells(primitives, primitive, height); + let lift = 0; + let image = null; + let frames = 0; + // The detail image, its own upload count and a window waiting for it to draw. + let detail = null; + let detailFrames = 0; + let pendingWindow = null; + let offRender = null; + let awake = false; + let destroyed = false; + + const fits = (size, value) => + !size || (size.x === value.width && size.y === value.height); + const uploaded = () => + image !== null && fits(material.uniforms.imageDimensions, image); + const detailDrawn = () => + detail !== null && + detailFrames === 0 && + fits(material.uniforms.detailDimensions, detail); + const drawn = () => + primitive.ready && + uploaded() && + frames === 0 && + (detail === null || (detailDrawn() && pendingWindow === null)); + function appliedWindow() { + const { x, y, z, w } = material.uniforms.window; + return z < x ? null : { west: x, south: y, east: z, north: w }; + } + function setWindow(rect) { + const next = rect ?? NO_WINDOW; + const { x, y, z, w } = material.uniforms.window; + if ( + x === next.west && + y === next.south && + z === next.east && + w === next.north + ) + return; + material.uniforms.window = new cesium.Cartesian4( + next.west, + next.south, + next.east, + next.north, + ); + ask(); + } + // The render governor may idle the scene; request frames only until the + // asynchronous geometry is ready and the latest images have been drawn. + function tick() { + // Cesium updates a material only while its primitive is shown, so hidden + // frames upload nothing and count for nothing. + if (primitive.ready && primitive.show) { + if (frames > 0) frames--; + if (detailFrames > 0) detailFrames--; + // A texture is never shown at another window's place. + if (pendingWindow && detailDrawn()) { + setWindow(pendingWindow); + pendingWindow = null; + } + } + if (primitive.show && !drawn()) { + ask(); + return; + } + awake = false; + offRender?.(); + offRender = null; + if (drawn()) onSettled(); + } + function wake() { + if (destroyed || !primitive.show || image === null || drawn()) return; + awake = true; + if (onWake) onWake(); + else offRender ??= scene.postRender.addEventListener(tick); + ask(); + } + + return { + setImage(next) { + if (destroyed || next === image) return; + image = next; + material.uniforms.image = next; + frames = UPLOAD_FRAMES; + wake(); + }, + setAlpha(value) { + if (destroyed || material.uniforms.alpha === value) return; + material.uniforms.alpha = value; + ask(); + }, + /** Metres the surface rises, by a uniform scale about the Earth's centre. */ + setLift(value) { + const next = Number(value) || 0; + if (destroyed || next === lift) return; + lift = next; + primitive.modelMatrix = cesium.Matrix4.fromUniformScale( + 1 + lift / cesium.Ellipsoid.WGS84.maximumRadius, + ); + ask(); + }, + /** Draw `next` inside `rect` (west, south, east, north in the full-extent + * image's texture coordinates, 0–1); null clears it. In the same window only + * the image changes, and Cesium keeps drawing the previous texture until + * this one is uploaded. A different window applies once its image has + * drawn; until then the full-extent image covers it. */ + setDetail(next, rect) { + if (destroyed) return; + if (!next) { + if (detail === null) return; + detail = null; + detailFrames = 0; + pendingWindow = null; + material.uniforms.detail = cesium.Material.DefaultImageId; + setWindow(null); + ask(); + return; + } + if (next !== detail) { + detail = next; + material.uniforms.detail = next; + detailFrames = UPLOAD_FRAMES; + } + const applied = appliedWindow(); + if (applied && sameEdges(applied, rect)) { + pendingWindow = null; + } else { + setWindow(null); + pendingWindow = rect; + } + wake(); + }, + /** Returns whether visibility changed. */ + setShow(value) { + const show = Boolean(value); + if (destroyed || primitive.show === show) return false; + primitive.show = show; + wake(); + ask(); + return true; + }, + /** Whether what it was last given has drawn. */ + isDrawn: () => !destroyed && drawn(), + /** Whether it needs frames until what it was given has drawn. */ + awake: () => awake && !destroyed, + tick, + getDiagnostics() { + return { + height, + lift, + ready: Boolean(primitive.ready), + uploaded: uploaded(), + show: primitive.show, + alpha: material.uniforms.alpha, + rendering: awake, + // `uploaded` once the detail image has drawn; the window applies after. + detail: { uploaded: detailDrawn(), window: appliedWindow() }, + }; + }, + destroy() { + if (destroyed) return; + destroyed = true; + awake = false; + offRender?.(); + offRender = null; + if (!primitives.isDestroyed?.() && primitives.contains(primitive)) + primitives.remove(primitive); + if (!primitive.isDestroyed()) primitive.destroy(); + // Primitive.destroy leaves the material and its texture alive. + if (!material.isDestroyed()) material.destroy(); + image = null; + detail = null; + pendingWindow = null; + ask(); + }, + }; +} + +/** A rectangle's place inside another, in the outer one's texture coordinates. */ +function placeIn(outer, inner) { + const x = outer.east - outer.west; + const y = outer.north - outer.south; + return { + west: (inner.west - outer.west) / x, + south: (inner.south - outer.south) / y, + east: (inner.east - outer.west) / x, + north: (inner.north - outer.south) / y, + }; +} + +/** Whether `ref` is drawn as it is, with no decode first. */ +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'); + const url = ref?.blob + ? URL.createObjectURL(ref.blob) + : ref?.svg + ? `data:image/svg+xml;charset=utf-8,${encodeURIComponent(ref.svg)}` + : String(ref); + try { + const image = new Image(); + image.crossOrigin = 'anonymous'; + image.src = url; + await image.decode(); + return image; + } finally { + if (ref?.blob) URL.revokeObjectURL(url); + } +} + +/** + * The fields part of a Cesium draw port. + * @param {{scene: object, report?: (error: unknown) => void, + * cesium?: object}} options `cesium` is for test doubles. + * @returns {{field: (spec: object) => object, has: (id: string) => boolean, + * dispose: () => void}} + */ +export function createCesiumFields({ + scene, + report = uncaught, + cesium = Cesium, +}) { + const fields = new Map(); + const live = () => !scene.isDestroyed?.(); + const requestRender = () => { + if (live()) scene.requestRender(); + }; + function rasterShell(spec) { + const id = spec.id; + // The frame a change was put on the surface, so 'drawn' waits for the + // render after it. Scenes without a frame state count this field's + // renders. + let renders = 0; + const frameNumber = () => scene.frameState?.frameNumber ?? renders; + let content = { + image: spec.image, + rectangle: { ...spec.rectangle }, + heightM: Number(spec.heightM) || 0, + detail: spec.detail ? { ...spec.detail } : null, + }; + let liftM = Number(spec.liftM) || 0; + let alpha = spec.alpha ?? 1; + let shown = true; + let disposed = false; + // The surface drawn, and one being built for a new rectangle or height. + let drawing = null; + let staged = null; + // Each content change, so a late decode of an older one is dropped. + let contentSeq = 0; + let placedSeq = -1; + // 'drawn' is owed for the latest change, put on the surface at `placedAt`. + let owed = true; + let placedAt = Infinity; + let offRender = null; + const drawnListeners = listenerList(report); + + const keyOf = (c) => + `${c.rectangle.west},${c.rectangle.south},${c.rectangle.east},${c.rectangle.north}|${c.heightM}`; + + function make(c) { + const entry = { key: keyOf(c), rectangle: c.rectangle, surface: null }; + const { west, south, east, north } = c.rectangle; + entry.surface = createShellSurface({ + scene, + cesium, + rectangle: cesium.Rectangle.fromDegrees(west, south, east, north), + height: c.heightM, + onSettled: () => settled(entry), + onWake: () => watch(), + }); + entry.surface.setLift(liftM); + // Staged surfaces draw, invisibly, even while the field is hidden, so + // the new content is ready when it shows. + return entry; + } + function drop(entry) { + entry?.surface.destroy(); + return null; + } + // A staged surface takes the drawn one's place once it has drawn. + function settled(entry) { + if (disposed) return; + if (entry === staged) { + drop(drawing); + drawing = staged; + staged = null; + drawing.surface.setAlpha(alpha); + drawing.surface.setShow(shown); + // It has drawn already, invisibly, so it shows from the next frame on, + // the frame the one it replaces stops: told now, so nothing comes + // between the swap and 'drawn'. + if (owed && shown && placedSeq === contentSeq) { + owed = false; + drawnListeners.fire(); + return; + } + placed(); + return; + } + // What it last applied (a detail window, say) draws in the next frame. + if (entry === drawing) placed(); + else watch(); + } + function placed() { + placedAt = frameNumber(); + watch(); + } + function put(entry, c, image, detailImage) { + entry.surface.setImage(image); + if (c.detail && detailImage) + entry.surface.setDetail( + detailImage, + placeIn(entry.rectangle, c.detail.rectangle), + ); + else entry.surface.setDetail(null); + } + /** Draw `c` with its images decoded. */ + function place(c, image, detailImage) { + const key = keyOf(c); + if (drawing?.key === key) { + staged = drop(staged); + put(drawing, c, image, detailImage); + placed(); + return; + } + if (staged?.key !== key) { + staged = drop(staged); + staged = make(c); + // Invisible until it takes the drawn one's place. + staged.surface.setAlpha(0); + } + put(staged, c, image, detailImage); + // Its own settling promotes it. + watch(); + } + function load(c) { + const seq = (contentSeq += 1); + const refs = [c.image, c.detail?.image]; + if (refs.every((ref) => ref == null || immediate(ref))) { + placedSeq = seq; + place(c, c.image.canvas, c.detail?.image.canvas ?? null); + return; + } + // A stage of older content must not take the drawn one's place while + // this decodes. + staged = drop(staged); + Promise.all( + refs.map((ref) => + ref == null ? null : immediate(ref) ? ref.canvas : decode(ref), + ), + ).then( + ([image, detailImage]) => { + if (disposed || seq !== contentSeq || !live()) return; + placedSeq = seq; + place(c, image, detailImage); + }, + (error) => { + // What it drew stays. + if (disposed || seq !== contentSeq) return; + report(error); + if (!busy()) unwatch(); + }, + ); + } + + // One listener runs the surfaces' frames and tells 'drawn'. + const busy = () => + Boolean(drawing?.surface.awake() || staged?.surface.awake()); + function notify() { + if (!owed || !shown || staged || placedSeq !== contentSeq || !drawing) + return; + if (!drawing.surface.isDrawn()) return; + // A frame number that has moved on (it wraps) has drawn the change. + if (frameNumber() === placedAt) { + requestRender(); + return; + } + owed = false; + drawnListeners.fire(); + } + function tick() { + renders += 1; + for (const entry of [drawing, staged]) + if (entry?.surface.awake()) entry.surface.tick(); + if (!disposed) notify(); + if (disposed || (!busy() && !(owed && shown))) unwatch(); + } + function watch() { + if (disposed || (!(owed && shown) && !busy())) return; + offRender ??= scene.postRender.addEventListener(tick); + requestRender(); + } + function unwatch() { + offRender?.(); + offRender = null; + } + + const handle = { + id, + get show() { + return shown; + }, + set show(value) { + const next = Boolean(value); + if (disposed || next === shown) return; + shown = next; + drawing?.surface.setShow(shown); + // A stage in progress keeps building, so it is ready when shown. + if (shown) watch(); + else if (!busy()) unwatch(); + requestRender(); + }, + update(patch = {}) { + if (disposed) return; + if (patch.kind !== undefined && patch.kind !== 'rasterShell') + throw new TypeError('a field keeps its kind'); + const next = { ...content }; + let reload = false; + if ('image' in patch && patch.image !== content.image) { + next.image = patch.image; + reload = true; + } + if (patch.rectangle && !sameEdges(patch.rectangle, content.rectangle)) { + next.rectangle = { ...patch.rectangle }; + reload = true; + } + if ('heightM' in patch && Number(patch.heightM) !== content.heightM) { + next.heightM = Number(patch.heightM) || 0; + reload = true; + } + if ('detail' in patch) { + const was = content.detail; + const now = patch.detail ? { ...patch.detail } : null; + if ( + (was === null) !== (now === null) || + (now && + (now.image !== was.image || + !sameEdges(now.rectangle, was.rectangle))) + ) { + next.detail = now; + reload = true; + } + } + if ('liftM' in patch) { + liftM = Number(patch.liftM) || 0; + drawing?.surface.setLift(liftM); + staged?.surface.setLift(liftM); + } + if ('alpha' in patch) { + alpha = patch.alpha ?? 1; + drawing?.surface.setAlpha(alpha); + } + owed = true; + content = next; + if (reload) load(content); + else placed(); + requestRender(); + }, + on(event, cb) { + if (event !== 'drawn') return () => {}; + return drawnListeners.on(cb); + }, + dispose() { + if (disposed) return; + disposed = true; + unwatch(); + drawnListeners.clear(); + drawing = drop(drawing); + staged = drop(staged); + if (fields.get(id) === handle) fields.delete(id); + }, + }; + fields.set(id, handle); + load(content); + return handle; + } + + return { + field(spec) { + if (fields.has(spec?.id)) + throw new Error(`a field with id ${spec.id} is live`); + if (spec?.kind === 'rasterShell') return rasterShell(spec); + throw new TypeError( + `the Cesium renderer draws no ${spec?.kind} fields yet`, + ); + }, + has: (id) => fields.has(id), + dispose() { + for (const handle of [...fields.values()]) handle.dispose(); + }, + }; +} diff --git a/src/render/cesium/drawFields.test.mjs b/src/render/cesium/drawFields.test.mjs new file mode 100644 index 000000000..ededeaacd --- /dev/null +++ b/src/render/cesium/drawFields.test.mjs @@ -0,0 +1,645 @@ +import test from 'node:test'; +import assert from 'node:assert/strict'; +import * as Cesium from 'cesium'; +import { + createCesiumFields, + createShellSurface, + orderShells, +} from './drawFields.js'; +import { + createShellCesium, + createShellScene, + renderShells, +} from '../../layers/weather/shellFixture.mjs'; + +// The detail window uniform; NONE is the empty window. +const NONE = { x: 0, y: 0, z: -1, w: -1 }; +const windowOf = (primitive) => { + const { x, y, z, w } = primitive.appearance.material.uniforms.window; + return { x, y, z, w }; +}; + +test('surface builds a flat raised rectangle drawn in primitive order without depth writes', () => { + const cesium = createShellCesium(); + const scene = createShellScene(); + const rectangle = Cesium.Rectangle.fromDegrees(-130, 20, -60, 55); + const surface = createShellSurface({ + scene, + cesium, + rectangle, + height: 6_200, + }); + const template = cesium.templates.get('DrawRasterShell'); + assert.ok(!(template instanceof cesium.Material), 'plain template'); + assert.deepEqual(template.fabric.uniforms, { + image: Cesium.Material.DefaultImageId, + detail: Cesium.Material.DefaultImageId, + alpha: 1, + window: { type: 'vec4', x: 0, y: 0, z: -1, w: -1 }, + }); + const { source } = template.fabric; + assert.match( + source, + /material\.alpha = c\.a \* alpha \* step\(1\.5, float\(imageDimensions\.x\)\);/, + 'nothing draws before the full-extent image', + ); + assert.match( + source, + /float useDetail = inside \* step\(1\.5, float\(detailDimensions\.x\)\);/, + 'the detail image is sampled only once it has arrived', + ); + assert.match( + source, + /all\(greaterThanEqual\(st, window\.xy\)\) && all\(lessThanEqual\(st, window\.zw\)\)/, + ); + assert.match( + source, + /mix\(coarse, texture\(detail, clamp\(dst, 0\.0, 1\.0\)\), useDetail\)/, + ); + assert.match(source, /material\.diffuse = czm_gammaCorrect\(c\.rgb\);/); + const [primitive] = scene.primitives.items; + const appearance = primitive.appearance; + assert.equal(appearance.material.options.translucent, false); + assert.deepEqual( + { ...appearance.options, material: undefined }, + { + aboveGround: true, + flat: true, + translucent: false, + material: undefined, + }, + ); + assert.deepEqual(appearance.getRenderState(), { + depthTest: { enabled: true }, + depthMask: false, + blending: Cesium.BlendingState.ALPHA_BLEND, + }); + const geometry = primitive.options.geometryInstances.geometry.options; + assert.equal(geometry.rectangle, rectangle); + assert.equal(geometry.height, 6_200); + assert.equal(geometry.granularity, Cesium.Math.toRadians(0.5)); + assert.equal( + geometry.vertexFormat, + Cesium.EllipsoidSurfaceAppearance.VERTEX_FORMAT, + ); + assert.equal(primitive.options.asynchronous, true); + assert.equal(primitive.options.allowPicking, false); + const lower = createShellSurface({ + scene, + cesium, + rectangle, + height: 5_000, + }); + assert.equal(cesium.templates.size, 1, 'the template registers once'); + assert.deepEqual( + scene.primitives.items.map( + (item) => item.options.geometryInstances.geometry.options.height, + ), + [5_000, 6_200], + ); + lower.destroy(); + surface.destroy(); +}); + +test('a surface applies a new detail window only once its image has drawn; the same window swaps only the image', () => { + const cesium = createShellCesium(); + const scene = createShellScene(); + const surface = createShellSurface({ + scene, + cesium, + rectangle: Cesium.Rectangle.fromDegrees(-130, 20, -60, 55), + height: 6_200, + }); + const [primitive] = scene.primitives.items; + const { uniforms } = primitive.appearance.material; + const render = (count) => renderShells(cesium, scene, count); + const image = () => ({ width: 4096, height: 2048 }); + surface.setImage(image()); + render(); + assert.deepEqual(surface.getDiagnostics().detail, { + uploaded: false, + window: null, + }); + const a = { west: 0.25, south: 0.5, east: 0.5, north: 0.75 }; + const first = image(); + surface.setDetail(first, a); + assert.equal(uniforms.detail, first); + assert.deepEqual(windowOf(primitive), NONE, 'the full-extent image covers'); + assert.equal(scene.postRender.size, 1, 'renders until the detail has drawn'); + render(2); + assert.deepEqual(windowOf(primitive), NONE); + render(1); + assert.deepEqual(windowOf(primitive), { x: 0.25, y: 0.5, z: 0.5, w: 0.75 }); + assert.ok(uniforms.window instanceof Cesium.Cartesian4); + assert.deepEqual(surface.getDiagnostics().detail, { + uploaded: true, + window: a, + }); + assert.equal(scene.postRender.size, 0); + + // A time change in the same window: Cesium keeps drawing the previous + // texture until the new one is uploaded, so the window stays. + const applied = uniforms.window; + const second = image(); + surface.setDetail(second, { ...a }); + assert.equal(uniforms.detail, second); + assert.equal(uniforms.window, applied, 'only the image is written'); + assert.equal(surface.getDiagnostics().detail.uploaded, false); + render(); + assert.equal(surface.getDiagnostics().detail.uploaded, true); + assert.equal(uniforms.window, applied); + const renders = scene.renders; + surface.setDetail(second, { ...a }); + assert.equal(scene.renders, renders, 'an unchanged detail costs nothing'); + assert.equal(scene.postRender.size, 0); + + // A different window empties at once and applies once its image has drawn. + const b = { west: 0.5, south: 0.25, east: 0.75, north: 0.5 }; + surface.setDetail(image(), b); + assert.deepEqual(windowOf(primitive), NONE); + render(2); + assert.deepEqual(windowOf(primitive), NONE); + render(1); + assert.deepEqual(windowOf(primitive), { x: 0.5, y: 0.25, z: 0.75, w: 0.5 }); + + surface.setDetail(null); + assert.equal(uniforms.detail, Cesium.Material.DefaultImageId); + assert.deepEqual(windowOf(primitive), NONE); + assert.deepEqual(surface.getDiagnostics().detail, { + uploaded: false, + window: null, + }); + render(); + assert.deepEqual( + { ...uniforms.detailDimensions }, + { type: 'ivec3', x: 1, y: 1 }, + ); + // Counted renders alone are not enough: the bound texture must be this image. + surface.setDetail(image(), a); + for (let i = 0; i < 4; i++) scene.postRender.emit(); + assert.deepEqual(windowOf(primitive), NONE, 'still the 1×1 default'); + render(1); + assert.deepEqual(windowOf(primitive), { x: 0.25, y: 0.5, z: 0.5, w: 0.75 }); + surface.destroy(); + surface.setDetail(image(), b); + assert.deepEqual(windowOf(primitive), { x: 0.25, y: 0.5, z: 0.5, w: 0.75 }); + assert.equal(scene.postRender.size, 0); +}); + +test("a surface rises by a uniform scale about the Earth's centre", () => { + const scene = { + primitives: new Cesium.PrimitiveCollection(), + postRender: new Cesium.Event(), + requestRender() {}, + }; + const surface = createShellSurface({ + scene, + cesium: Cesium, + rectangle: Cesium.Rectangle.fromDegrees(-130, 20, -60, 55), + height: 5_800, + }); + const primitive = scene.primitives.get(0); + const identity = primitive.modelMatrix; + surface.setLift(0); + assert.equal(primitive.modelMatrix, identity, 'no lift, no new matrix'); + surface.setLift(32_000); + const radius = Cesium.Ellipsoid.WGS84.maximumRadius; + assert.ok( + Math.abs(primitive.modelMatrix[0] * radius - (radius + 32_000)) < 1e-3, + ); + const lifted = primitive.modelMatrix; + surface.setLift(32_000); + assert.equal(primitive.modelMatrix, lifted, 'the same lift keeps the matrix'); + surface.destroy(); +}); + +test('real Cesium builds the two-texture material, the opaque-pass appearance and the rectangle primitive', () => { + const scene = { + primitives: new Cesium.PrimitiveCollection(), + postRender: new Cesium.Event(), + requestRender() {}, + }; + const surface = createShellSurface({ + scene, + cesium: Cesium, + rectangle: Cesium.Rectangle.fromDegrees(-130, 20, -60, 55), + height: 6_600, + }); + const cached = Cesium.Material._materialCache.getMaterial('DrawRasterShell'); + assert.ok(cached && !(cached instanceof Cesium.Material)); + const primitive = scene.primitives.get(0); + const material = primitive.appearance.material; + assert.ok(primitive instanceof Cesium.Primitive); + assert.equal(material.type, 'DrawRasterShell'); + assert.equal(material.isTranslucent(), false); + assert.equal(primitive.appearance.isTranslucent(), false, 'opaque pass'); + assert.equal(primitive.appearance.getRenderState().depthMask, false); + assert.equal( + Cesium.Appearance.prototype.getRenderState.call(primitive.appearance) + .depthMask, + true, + 'the default opaque render state would write depth', + ); + assert.deepEqual( + [material.uniforms.imageDimensions.x, material.uniforms.detailDimensions.x], + [1, 1], + 'Cesium tracks both bound texture sizes', + ); + const shader = material.shaderSource; + for (const declaration of [ + /uniform sampler2D image_\d+;/, + /uniform sampler2D detail_\d+;/, + /uniform float alpha_\d+;/, + /uniform vec4 window_\d+;/, + /uniform ivec3 imageDimensions_\d+;/, + /uniform ivec3 detailDimensions_\d+;/, + ]) + assert.match(shader, declaration); + assert.match(shader, /texture\(image_\d+, st\)/); + assert.match(shader, /texture\(detail_\d+, clamp\(dst, 0\.0, 1\.0\)\)/); + assert.match(shader, /lessThanEqual\(st, window_\d+\.zw\)/); + assert.match(shader, /step\(1\.5, float\(detailDimensions_\d+\.x\)\)/); + assert.match( + shader, + /material\.alpha = c\.a \* alpha_\d+ \* step\(1\.5, float\(imageDimensions_\d+\.x\)\);/, + 'the uniform is renamed, the material field is not', + ); + assert.match(shader, /float useDetail = inside \* step/, 'locals keep names'); + const detail = { width: 4096, height: 2048 }; + surface.setDetail(detail, { west: 0.1, south: 0.2, east: 0.3, north: 0.4 }); + assert.equal(material.uniforms.detail, detail); + assert.deepEqual( + [material.uniforms.window.z, material.uniforms.window.w], + [-1, -1], + 'no window before the image has drawn', + ); + surface.setDetail(null); + assert.equal(material.uniforms.detail, Cesium.Material.DefaultImageId); + surface.setAlpha(0.4); + assert.equal(material.uniforms.alpha, 0.4); + surface.destroy(); + assert.equal(scene.primitives.length, 0); + assert.equal(primitive.isDestroyed(), true); + assert.equal(material.isDestroyed(), true); + assert.equal(scene.postRender.numberOfListeners, 0); +}); + +test('shells draw first, in height order, regardless of add order', () => { + const scene = createShellScene(); + const other = { name: 'other' }; + scene.primitives.add(other); + const add = (name, height) => { + const primitive = { name }; + scene.primitives.add(primitive); + orderShells(scene.primitives, primitive, height); + return primitive; + }; + add('lightning', 6_600); + add('radar', 6_200); + add('wind', 5_000); + const later = { name: 'later' }; + scene.primitives.add(later); + add('regional', 5_800); + assert.deepEqual( + scene.primitives.items.map(({ name }) => name), + ['wind', 'regional', 'radar', 'lightning', 'other', 'later'], + ); + const primitives = new Cesium.PrimitiveCollection({ + destroyPrimitives: false, + }); + const real = (name) => ({ name, update() {}, isDestroyed: () => false }); + const tileset = primitives.add(real('tileset')); + const lightning = primitives.add(real('lightning')); + orderShells(primitives, lightning, 6_600); + const radar = primitives.add(real('radar')); + orderShells(primitives, radar, 6_200); + assert.deepEqual( + [0, 1, 2].map((i) => primitives.get(i).name), + ['radar', 'lightning', 'tileset'], + 'real Cesium collection order', + ); + assert.equal(tileset.name, 'tileset'); +}); + +test('hidden frames do not count towards a pending detail window', () => { + const cesium = createShellCesium(); + const scene = createShellScene(); + const surface = createShellSurface({ + scene, + cesium, + rectangle: Cesium.Rectangle.fromDegrees(-130, 20, -60, 55), + height: 6_200, + }); + const [primitive] = scene.primitives.items; + const render = (count) => renderShells(cesium, scene, count); + const image = () => ({ width: 4096, height: 2048 }); + surface.setImage(image()); + const a = { west: 0.25, south: 0.5, east: 0.5, north: 0.75 }; + surface.setDetail(image(), a); + render(); + assert.deepEqual(windowOf(primitive), { x: 0.25, y: 0.5, z: 0.5, w: 0.75 }); + // A different window with a same-sized image: the dimensions alone cannot + // tell the textures apart, so only shown frames may count. + const b = { west: 0.5, south: 0.25, east: 0.75, north: 0.5 }; + surface.setDetail(image(), b); + assert.deepEqual(windowOf(primitive), NONE); + for (let i = 0; i < 3; i++) { + surface.setShow(false); + scene.postRender.emit(); + surface.setShow(true); + } + assert.deepEqual(windowOf(primitive), NONE, 'hidden frames counted nothing'); + render(2); + assert.deepEqual(windowOf(primitive), NONE); + render(1); + assert.deepEqual(windowOf(primitive), { x: 0.5, y: 0.25, z: 0.75, w: 0.5 }); +}); + +function fieldHarness() { + const cesium = createShellCesium(); + const scene = createShellScene(); + const fields = createCesiumFields({ scene, cesium }); + const image = () => ({ canvas: { width: 64, height: 32 }, key: 'k' }); + const render = (count = 4) => renderShells(cesium, scene, count); + const live = () => scene.primitives.items.filter((p) => !p.destroyed); + return { cesium, scene, fields, image, render, live }; +} +const RECT = { west: -100, south: 20, east: -60, north: 40 }; + +test("a raster shell tells 'drawn' once its content is drawn, once per change", () => { + const h = fieldHarness(); + const field = h.fields.field({ + kind: 'rasterShell', + id: 'shell', + image: h.image(), + rectangle: RECT, + heightM: 6_000, + alpha: 0.5, + }); + let drawn = 0; + field.on('drawn', () => (drawn += 1)); + const [primitive] = h.live(); + const { uniforms } = primitive.appearance.material; + assert.equal(uniforms.alpha, 0, 'invisible until drawable'); + h.render(); + assert.equal(drawn, 1); + assert.equal(uniforms.alpha, 0.5); + assert.equal(h.scene.postRender.size, 0, 'no frames once drawn'); + field.update({ alpha: 0.3, liftM: 1_000 }); + assert.equal(uniforms.alpha, 0.3); + assert.notEqual(primitive.modelMatrix, undefined, 'lifted'); + assert.deepEqual(h.live(), [primitive], 'alpha and lift never rebuild'); + h.render(); + assert.equal(drawn, 2); + field.show = false; + field.update({ alpha: 0.4 }); + h.render(); + assert.equal(drawn, 2, 'never while hidden'); + field.show = true; + h.render(); + assert.equal(drawn, 3, 'told once shown'); + h.render(); + assert.equal(drawn, 3); + field.dispose(); + assert.equal(h.live().length, 0); + assert.equal(h.scene.postRender.size, 0); +}); + +test('a raster shell keeps drawing its rectangle until a new one is drawn whole', () => { + const h = fieldHarness(); + const first = h.image(); + const field = h.fields.field({ + kind: 'rasterShell', + id: 'shell', + image: first, + rectangle: RECT, + heightM: 6_000, + }); + let drawn = 0; + field.on('drawn', () => (drawn += 1)); + h.render(); + const [old] = h.live(); + const second = h.image(); + field.update({ + image: second, + rectangle: { west: -120, south: 10, east: -50, north: 50 }, + }); + const [, staged] = h.live(); + assert.equal(old.appearance.material.uniforms.alpha, 1, 'the old one draws'); + assert.equal(staged.appearance.material.uniforms.alpha, 0); + assert.equal(staged.appearance.material.uniforms.image, second.canvas); + h.render(); + assert.equal(old.destroyed, true, 'swapped in one frame'); + assert.deepEqual(h.live(), [staged]); + assert.equal(staged.appearance.material.uniforms.alpha, 1); + assert.equal(drawn, 2); + // Back to the drawn rectangle before a staged one is drawn: it goes. + field.update({ rectangle: RECT }); + assert.equal(h.live().length, 2); + field.update({ rectangle: { west: -120, south: 10, east: -50, north: 50 } }); + assert.deepEqual(h.live(), [staged]); + field.dispose(); +}); + +test('a raster shell draws its detail in its own rectangle, in texture coordinates', () => { + const h = fieldHarness(); + const field = h.fields.field({ + kind: 'rasterShell', + id: 'shell', + image: h.image(), + rectangle: RECT, + heightM: 6_000, + }); + h.render(); + const [primitive] = h.live(); + const detail = h.image(); + field.update({ + detail: { + image: detail, + rectangle: { west: -90, south: 25, east: -80, north: 30 }, + }, + }); + assert.deepEqual(windowOf(primitive), NONE, 'the full image covers it'); + h.render(); + assert.equal(primitive.appearance.material.uniforms.detail, detail.canvas); + assert.deepEqual(windowOf(primitive), { + x: 0.25, + y: 0.25, + z: 0.5, + w: 0.5, + }); + field.update({ detail: null }); + assert.deepEqual(windowOf(primitive), NONE); + field.dispose(); +}); + +test('a raster shell hidden while a new rectangle stages still swaps it in', () => { + const h = fieldHarness(); + const field = h.fields.field({ + kind: 'rasterShell', + id: 'shell', + image: h.image(), + rectangle: RECT, + heightM: 6_000, + }); + let drawn = 0; + field.on('drawn', () => (drawn += 1)); + h.render(); + const [old] = h.live(); + field.show = false; + field.update({ + image: h.image(), + rectangle: { west: -120, south: 10, east: -50, north: 50 }, + }); + h.render(); + const [staged] = h.live(); + assert.equal(old.destroyed, true, 'drawn invisibly and swapped in'); + assert.notEqual(staged, old); + assert.equal(staged.show, false, 'and kept hidden'); + assert.equal(drawn, 1, 'never told while hidden'); + field.show = true; + h.render(); + assert.equal(staged.show, true); + assert.equal(drawn, 2); + field.dispose(); +}); + +test("a raster shell tells 'drawn' for a detail only once its window is placed", () => { + const h = fieldHarness(); + const field = h.fields.field({ + kind: 'rasterShell', + id: 'shell', + image: h.image(), + rectangle: RECT, + heightM: 6_000, + }); + h.render(); + const [primitive] = h.live(); + const windows = []; + field.on('drawn', () => windows.push(windowOf(primitive))); + field.update({ + detail: { + image: h.image(), + rectangle: { west: -90, south: 25, east: -80, north: 30 }, + }, + }); + h.render(); + assert.deepEqual(windows, [{ x: 0.25, y: 0.25, z: 0.5, w: 0.5 }]); + field.dispose(); +}); + +test("a raster shell tells 'drawn' in the frame its new rectangle replaces the old", () => { + const h = fieldHarness(); + const field = h.fields.field({ + kind: 'rasterShell', + id: 'shell', + image: h.image(), + rectangle: RECT, + heightM: 6_000, + }); + h.render(); + const [old] = h.live(); + let drawnAt = null; + let render = 0; + field.on('drawn', () => (drawnAt = render)); + field.update({ rectangle: { west: -120, south: 10, east: -50, north: 50 } }); + let swappedAt = null; + for (render = 1; render <= 6; render++) { + h.render(1); + if (old.destroyed && swappedAt === null) swappedAt = render; + } + assert.ok(swappedAt > 1, 'staged while uploading'); + assert.equal(drawnAt, swappedAt, 'nothing comes between the swap and drawn'); + field.dispose(); +}); + +test('a raster shell hidden after a new rectangle stages still builds and swaps it', () => { + const h = fieldHarness(); + const field = h.fields.field({ + kind: 'rasterShell', + id: 'shell', + image: h.image(), + rectangle: RECT, + heightM: 6_000, + }); + let drawn = 0; + field.on('drawn', () => (drawn += 1)); + h.render(); + const [old] = h.live(); + field.update({ rectangle: { west: -120, south: 10, east: -50, north: 50 } }); + field.show = false; + h.render(); + const [staged] = h.live(); + assert.equal(old.destroyed, true); + assert.notEqual(staged, old); + assert.equal(staged.show, false); + assert.equal(h.scene.postRender.size, 0, 'no frames once built'); + assert.equal(drawn, 1); + field.show = true; + h.render(); + assert.equal(drawn, 2); + field.dispose(); +}); + +test('a raster shell never swaps in a stage superseded by content still decoding', async (t) => { + const pending = []; + const Image = globalThis.Image; + globalThis.Image = class { + decode() { + return new Promise((resolve, reject) => + pending.push({ resolve, reject }), + ); + } + }; + t.after(() => (globalThis.Image = Image)); + const reported = []; + const cesium = createShellCesium(); + const scene = createShellScene(); + const fields = createCesiumFields({ + scene, + cesium, + report: (error) => reported.push(error), + }); + const live = () => scene.primitives.items.filter((p) => !p.destroyed); + const field = fields.field({ + kind: 'rasterShell', + id: 'shell', + image: { canvas: { width: 64, height: 32 } }, + rectangle: RECT, + heightM: 6_000, + }); + renderShells(cesium, scene); + const [old] = live(); + field.update({ + image: { canvas: { width: 64, height: 32 } }, + rectangle: { west: -120, south: 10, east: -50, north: 50 }, + }); + assert.equal(live().length, 2); + field.update({ image: 'https://example.test/next.png' }); + assert.deepEqual(live(), [old], 'the superseded stage goes'); + pending[0].reject(new Error('no image')); + await new Promise((resolve) => setTimeout(resolve, 0)); + renderShells(cesium, scene); + assert.deepEqual(live(), [old], 'what it drew stays'); + assert.equal(reported.length, 1); + field.dispose(); +}); + +test('the Cesium fields refuse kinds they cannot draw and live ids', () => { + const h = fieldHarness(); + assert.throws( + () => h.fields.field({ kind: 'scalarRaster', id: 'x' }), + /no scalarRaster fields/, + ); + const spec = { + kind: 'rasterShell', + id: 'shell', + image: h.image(), + rectangle: RECT, + heightM: 1, + }; + const field = h.fields.field(spec); + assert.throws(() => h.fields.field(spec), /is live/); + field.dispose(); + h.fields.field(spec).dispose(); +}); diff --git a/src/render/cesium/harness.js b/src/render/cesium/harness.js index dedc020e7..53ded5cff 100644 --- a/src/render/cesium/harness.js +++ b/src/render/cesium/harness.js @@ -40,6 +40,7 @@ export const CESIUM_CHECKS = new Set([ 'draw.columns.shown', 'draw.drawOrder', 'draw.drillPick', + 'draw.field.rasterShell', 'draw.icons.distance', 'draw.icons.update', 'draw.lines.depthFailDash', diff --git a/src/render/cesium/ports.js b/src/render/cesium/ports.js index 2a115b3f7..1747fb371 100644 --- a/src/render/cesium/ports.js +++ b/src/render/cesium/ports.js @@ -66,6 +66,8 @@ export function cesiumCapabilities(scene, only) { 'models', 'quads', 'meshes', + // Raster shells; other field kinds are refused. + 'fields', 'followFrame', 'cameraChangeThreshold', ...GPU_ICON_CAPABILITIES, diff --git a/src/render/cesium/ports.test.mjs b/src/render/cesium/ports.test.mjs index 722b96208..6a8b3d995 100644 --- a/src/render/cesium/ports.test.mjs +++ b/src/render/cesium/ports.test.mjs @@ -29,7 +29,7 @@ test('capabilities follow what the scene supports', () => { 'surfaceShading', ]; const globe = { show: true }; - const draw = ['models', 'quads', 'meshes']; + const draw = ['models', 'quads', 'meshes', 'fields']; assert.deepEqual(cesiumCapabilities({}), [...draw, ...effects]); // A scene with a globe reads its visibility back. assert.deepEqual(cesiumCapabilities({ globe }), [ diff --git a/src/render/cesiumAllowList.json b/src/render/cesiumAllowList.json index 6198d24d7..5b7efdead 100644 --- a/src/render/cesiumAllowList.json +++ b/src/render/cesiumAllowList.json @@ -5,7 +5,6 @@ "src/app/scene.js", "src/app/viewer.js", "src/data/geoImportPins.js", - "src/layers/weather/shellRendering.js", "src/layers/wind/gpuRendering.js", "src/layers/wind/relief.js", "src/layers/wind/rendering.js", From fcd1c0956535192a53a47d966d95c45939864b62 Mon Sep 17 00:00:00 2001 From: Sameh Khamis Date: Mon, 9 Nov 2026 07:38:06 -0800 Subject: [PATCH 2/3] render: Cesium draws wind-streamline fields; the wind layer's flow uses the draw port The Cesium draw port now implements draw.field for the windStreamlines kind (src/render/cesium/drawStreamlines.js). It carries the flow shader, the 30-degree cells, horizon and frustum culling and the path tracing over from the wind layer. It moves the highlight on the page's own frames, at most every 32 ms, and only while the field shows, is unpaused, has alpha and some cell is in view on a visible page. A grid no path runs through, or one short of the whole globe, is refused. A rebuild that fails draws nothing and is never told drawn. The wind layer's GPU flow (src/layers/wind/gpuRendering.js) now builds the spec, fades it by camera height and pauses it through the draw, camera and frame ports, and no longer reaches Cesium, so it leaves the Cesium allow list. The layer runs no animation loop of its own while the renderer draws the flow; the canvas fallback is unchanged and still takes over wherever the field is refused. A new conformance check covers the field's 'drawn' events. --- scripts/format-scope.json | 2 + scripts/package-boundaries.json | 11 + src/layers/wind/gpuRendering.js | 340 +++++-------- src/layers/wind/gpuRendering.test.mjs | 517 ++++++------------- src/layers/wind/rendering.js | 41 +- src/layers/wind/rendering.test.mjs | 103 ++-- src/render/cesium/drawFields.js | 25 +- src/render/cesium/drawStreamlines.js | 469 ++++++++++++++++++ src/render/cesium/drawStreamlines.test.mjs | 547 +++++++++++++++++++++ src/render/cesium/harness.js | 1 + src/render/cesiumAllowList.json | 1 - src/render/conformance/checks/ports.js | 58 +++ 12 files changed, 1414 insertions(+), 701 deletions(-) create mode 100644 src/render/cesium/drawStreamlines.js create mode 100644 src/render/cesium/drawStreamlines.test.mjs diff --git a/scripts/format-scope.json b/scripts/format-scope.json index 07f8d9110..e998893e2 100644 --- a/scripts/format-scope.json +++ b/scripts/format-scope.json @@ -873,6 +873,8 @@ "src/layers/weather/shellRendering.test.mjs", "src/render/cesium/drawFields.js", "src/render/cesium/drawFields.test.mjs", + "src/render/cesium/drawStreamlines.js", + "src/render/cesium/drawStreamlines.test.mjs", "src/layers/weather/infraredAlpha.js", "src/layers/weather/infraredAlpha.test.mjs", "src/layers/weather/infraredImage.js", diff --git a/scripts/package-boundaries.json b/scripts/package-boundaries.json index 5b9bbd12a..1a4e5ca21 100644 --- a/scripts/package-boundaries.json +++ b/scripts/package-boundaries.json @@ -1071,6 +1071,9 @@ "src/queries/heights.js", "src/render/cesium/draw.js", "src/render/cesium/drawFields.js", + "src/render/cesium/drawStreamlines.js", + "src/layers/wind/streamlines.js", + "src/layers/wind/model.js", "src/render/cesium/drawQuads.js", "src/render/cesium/drawMeshes.js", "src/render/cesium/drawModels.js", @@ -1856,6 +1859,9 @@ "src/render/cesium/screenModulation.js", "src/render/cesium/draw.js", "src/render/cesium/drawFields.js", + "src/render/cesium/drawStreamlines.js", + "src/layers/wind/streamlines.js", + "src/layers/wind/model.js", "src/render/cesium/drawQuads.js", "src/render/cesium/drawMeshes.js", "src/render/cesium/drawModels.js", @@ -3059,6 +3065,9 @@ "src/render/cesium/tileRequests.js", "src/render/cesium/draw.js", "src/render/cesium/drawFields.js", + "src/render/cesium/drawStreamlines.js", + "src/layers/wind/streamlines.js", + "src/layers/wind/model.js", "src/render/cesium/drawQuads.js", "src/render/cesium/drawMeshes.js", "src/render/cesium/drawModels.js", @@ -3300,6 +3309,7 @@ "src/render/cesium/drawHit.js", "src/render/cesium/draw.js", "src/render/cesium/drawFields.js", + "src/render/cesium/drawStreamlines.js", "src/render/cesium/drawMeshes.js", "src/render/cesium/drawQuads.js", "src/render/cesium/drawModels.js", @@ -4313,6 +4323,7 @@ "src/render/cesium/heights.js", "src/render/cesium/draw.js", "src/render/cesium/drawFields.js", + "src/render/cesium/drawStreamlines.js", "src/render/cesium/drawQuads.js", "src/render/cesium/drawMeshes.js", "src/render/cesium/drawModels.js", diff --git a/src/layers/wind/gpuRendering.js b/src/layers/wind/gpuRendering.js index 0873fa63b..ec9ea018d 100644 --- a/src/layers/wind/gpuRendering.js +++ b/src/layers/wind/gpuRendering.js @@ -1,266 +1,172 @@ import { - bakeWindStreamlines, - groupWindPaths, WIND_DISPLAY_HEIGHT_METERS, - WIND_PATH_LIMIT, WIND_NARROW_PATH_LIMIT, + WIND_PATH_LIMIT, + WIND_PATH_STEPS, } from './streamlines.js'; +import { + canvasOf, + findCamera, + findDraw, + findFrame, + rendererOf, +} from '../../render/rendererOf.js'; const WIND_FADE_LOW_METERS = 15000; const WIND_FADE_HIGH_METERS = 60000; +// The streamlines' colour: the ghost and the trail; the moving tip brightens it. +const WIND_STREAMLINE_COLOR = '#80c9e6'; +const WIND_STREAMLINE_WIDTH_PX = 2.4; -// Original material: a persistent fine curve plus a moving, tapered highlight. -// The integer part of s identifies a path; its fractional part follows the wind. -const FLOW_MATERIAL = ` -in float v_windFacing; -czm_material czm_getMaterial(czm_materialInput materialInput) -{ - czm_material material = czm_getDefaultMaterial(materialInput); - float pathId = floor(materialInput.st.s); - float along = fract(materialInput.st.s); - float offset = fract((pathId + 1.0) * 0.61803398875); - float behind = fract(phaseTime * 0.16 + offset - along); - float tail = (1.0 - smoothstep(0.0, 0.32, behind)); - float tip = 1.0 - smoothstep(0.0, 0.045, behind); - float ends = smoothstep(0.0, 0.055, along) * (1.0 - smoothstep(0.945, 1.0, along)); - float edge = 1.0 - smoothstep(0.26, 0.5, abs(materialInput.st.t - 0.5)); - float horizon = smoothstep(0.0, 0.065, v_windFacing); - material.diffuse = mix(vec3(0.50, 0.79, 0.90), vec3(0.91, 0.99, 1.0), tip); - material.alpha = (ghostAlpha + 0.64 * tail + 0.16 * tip) * ends * edge * horizon * heightFade; - return material; -}`; +let fieldIds = 0; -/** Native Cesium geometry/material owner. No animation loop or DOM ownership. */ -export function createWindGpuRendering({ cesium: C, getViewer }) { - const cells = []; - let occluder = null; - let collection = null; - let material = null; +/** The streamline fade for a camera this high: none low down, full from 60 km. */ +export function windHeightFade(height) { + return Math.max( + 0, + Math.min( + 1, + (height - WIND_FADE_LOW_METERS) / + (WIND_FADE_HIGH_METERS - WIND_FADE_LOW_METERS), + ), + ); +} + +/** + * A wind grid as the draw port's `windStreamlines` field: samples are + * points, the first column at `lo1` and the first row at `la1`, rows + * running south; a grid that wraps the globe spans 360° of longitude. + */ +export function windStreamlineSpec(field, { id, pathBudget, alpha, paused }) { + const span = field.nx * field.dx; + const wraps = span >= 360 - 1e-9; + const west = field.lo1; + const north = field.la1; + return { + kind: 'windStreamlines', + id, + u: field.u, + v: field.v, + width: field.nx, + height: field.ny, + rectangle: { + west, + south: north - (field.ny - 1) * field.dy, + east: west + (wraps ? span : (field.nx - 1) * field.dx), + north, + }, + pathBudget, + steps: WIND_PATH_STEPS, + style: { color: WIND_STREAMLINE_COLOR, widthPx: WIND_STREAMLINE_WIDTH_PX }, + heightM: WIND_DISPLAY_HEIGHT_METERS, + alpha, + paused, + }; +} + +/** + * Streamlines through the draw port's `windStreamlines` field (capability + * `fields`): the renderer traces, draws, culls and animates them; this + * fades them by camera height and pauses them. Where the renderer has no + * such field, or refuses this one, `setField` answers false and the layer + * paints on its canvas instead. No animation loop or DOM ownership. + */ +export function createWindGpuRendering({ + getViewer, + drawOf = findDraw, + cameraOf = findCamera, + frameOf = findFrame, +} = {}) { + let handle = null; let paused = false; let destroyed = false; + let heightFade = 0; + let drawn = false; const emptyDiagnostics = () => ({ pathCount: 0, - vertexCount: 0, buildMs: 0, error: null, - cellCount: 0, - visibleCells: 0, - visibleVertexCount: 0, heightFade: 0, }); let diagnostics = emptyDiagnostics(); + const viewer = () => getViewer?.() ?? null; function supported() { - const scene = getViewer?.()?.scene; - return ( - !destroyed && - Boolean( - scene?.primitives && - C?.Primitive && - C?.GeometryInstance && - C?.GeometryInstanceAttribute && - C?.ComponentDatatype?.FLOAT !== undefined && - C?.PolylineGeometry && - C?.PolylineMaterialAppearance && - C?.Material && - C?.BoundingSphere?.fromPoints && - C?.Occluder && - C?.Ellipsoid?.WGS84 && - C?.Intersect && - C?.Cartesian3?.fromDegrees, - ) && - (C.SceneMode?.SCENE3D === undefined || - scene.mode === undefined || - scene.mode === C.SceneMode.SCENE3D) - ); + const host = viewer(); + if (destroyed || !host) return false; + const capabilities = rendererOf(host)?.capabilities; + if (capabilities && !capabilities.has('fields')) return false; + return typeof drawOf(host)?.field === 'function'; } function clear() { - for (const cell of cells) { - collection?.remove(cell.primitive); - if (!cell.primitive.isDestroyed?.()) cell.primitive.destroy?.(); - } - cells.length = 0; - occluder = null; - collection = null; - material?.destroy?.(); - material = null; + handle?.dispose(); + handle = null; + drawn = false; diagnostics = emptyDiagnostics(); } + function readFade() { + const height = cameraOf(viewer())?.pose?.().height; + return Number.isFinite(height) ? windHeightFade(height) : heightFade; + } + function setField(field) { clear(); if (!supported() || !field) return false; const started = globalThis.performance?.now?.() ?? Date.now(); + const width = canvasOf(viewer())?.clientWidth; + const pathBudget = + width > 0 && width < 700 ? WIND_NARROW_PATH_LIMIT : WIND_PATH_LIMIT; + heightFade = readFade(); try { - const width = getViewer().scene.canvas?.clientWidth; - const budget = - width > 0 && width < 700 ? WIND_NARROW_PATH_LIMIT : WIND_PATH_LIMIT; - const paths = bakeWindStreamlines(field, { count: budget }); - if (!paths.length) return false; - let vertexCount = 0; - material = new C.Material({ - fabric: { - type: 'GevWindStreamline', - uniforms: { - phaseTime: 0, - ghostAlpha: paused ? 0.34 : 0.25, - heightFade: 0, - }, - source: FLOW_MATERIAL, - }, - translucent: () => true, - }); - const base = new C.PolylineMaterialAppearance({ material }); - // Extend the public default shader rather than duplicate Cesium's polyline - // expansion/precision code. Explicit facing also masks the far hemisphere - // when a scene chooses not to preserve globe depth for translucent objects. - const source = base.vertexShaderSource; - if ( - !/void\s+main\s*\(\s*\)/.test(source) || - !/v_st\.s\s*=\s*st\.s\s*;/.test(source) - ) - throw new Error('Wind polyline shader entry unavailable'); - const seededSource = source.replace( - /v_st\.s\s*=\s*st\.s\s*;/, - 'v_st.s = st.s * 0.999 + czm_batchTable_windSeed(batchId);', + handle = drawOf(viewer()).field( + windStreamlineSpec(field, { + id: `wind-streamlines:${(fieldIds += 1)}`, + pathBudget, + alpha: heightFade, + paused, + }), ); - const vertexShaderSource = - `out float v_windFacing;\n${seededSource}`.replace( - /void\s+main\s*\(\s*\)\s*\{/, - `void main() {\nvec3 windWorld = (czm_model * vec4(position3DHigh + position3DLow, 1.0)).xyz;\nv_windFacing = dot(normalize(windWorld), normalize(czm_viewerPositionWC - windWorld));\n`, - ); - const scene = getViewer().scene; - collection = scene.primitives; - // EllipsoidalOccluder only tests points. Use Cesium's sphere occluder - // with an inscribed Earth sphere, independent of scene.globe.show. - occluder = new C.Occluder( - new C.BoundingSphere( - C.Cartesian3.ZERO, - C.Ellipsoid.WGS84.minimumRadius, - ), - scene.camera.positionWC, - ); - for (const group of groupWindPaths(paths)) { - const cellPositions = []; - let cellVertexCount = 0; - const instances = group.paths.map((path) => { - const positions = path.coordinates.map(([lon, lat]) => - C.Cartesian3.fromDegrees(lon, lat, WIND_DISPLAY_HEIGHT_METERS), - ); - // Pass the native description to Cesium's worker. Per-instance seed - // attributes avoid touching the expanded vertex buffer on the UI thread. - const geometry = new C.PolylineGeometry({ - positions, - width: 2.4, - arcType: C.ArcType?.NONE, - vertexFormat: C.PolylineMaterialAppearance.VERTEX_FORMAT, - }); - cellPositions.push(...positions); - cellVertexCount += positions.length * 4 - 4; - return new C.GeometryInstance({ - geometry, - attributes: { - windSeed: new C.GeometryInstanceAttribute({ - componentDatatype: C.ComponentDatatype.FLOAT, - componentsPerAttribute: 1, - value: [path.seed], - }), - }, - }); - }); - const appearance = new C.PolylineMaterialAppearance({ - material, - vertexShaderSource, - translucent: true, - renderState: { depthTest: { enabled: true }, depthMask: false }, - }); - const primitive = new C.Primitive({ - show: false, - geometryInstances: instances, - appearance, - asynchronous: true, - allowPicking: false, - releaseGeometryInstances: true, - compressVertices: false, - }); - const cell = { - primitive, - sphere: C.BoundingSphere.fromPoints(cellPositions), - vertexCount: cellVertexCount, - }; - cells.push(cell); - collection.add(primitive); - vertexCount += cellVertexCount; - } - diagnostics = { - ...emptyDiagnostics(), - cellCount: cells.length, - pathCount: paths.length, - vertexCount, - buildMs: (globalThis.performance?.now?.() ?? Date.now()) - started, - error: null, - }; - return true; } catch (error) { - clear(); + handle = null; diagnostics.error = // i18n-ignore: GPU diagnostics only; the panel never shows this field error instanceof Error ? error.message : 'Wind geometry unavailable'; return false; } + handle.on('drawn', () => { + drawn = true; + // One more frame, so a still scene shows the layer ready. + frameOf(viewer())?.requestRender?.('wind'); + }); + diagnostics = { + ...emptyDiagnostics(), + pathCount: pathBudget, + buildMs: (globalThis.performance?.now?.() ?? Date.now()) - started, + heightFade, + }; + return true; } - // Cesium reuses its frustum culling volume and the occluder's scratch vectors. - // This loop creates no positions, spheres, appearances or per-cell temporaries. - function updateVisibility(camera) { - const height = camera.positionCartographic.height; - const heightFade = Math.max( - 0, - Math.min( - 1, - (height - WIND_FADE_LOW_METERS) / - (WIND_FADE_HIGH_METERS - WIND_FADE_LOW_METERS), - ), - ); - diagnostics.heightFade = heightFade; - if (material) material.uniforms.heightFade = heightFade; - diagnostics.visibleCells = 0; - diagnostics.visibleVertexCount = 0; - let volume; - if (heightFade > 0 && cells.length) { - occluder.cameraPosition = camera.positionWC; - volume = camera.frustum.computeCullingVolume( - camera.positionWC, - camera.directionWC, - camera.upWC, - ); - } - for (let i = 0; i < cells.length; i++) { - const cell = cells[i]; - cell.primitive.show = - heightFade > 0 && - occluder.isBoundingSphereVisible(cell.sphere) && - volume.computeVisibility(cell.sphere) !== C.Intersect.OUTSIDE; - if (cell.primitive.show) { - diagnostics.visibleCells++; - diagnostics.visibleVertexCount += cell.vertexCount; - } - } - return diagnostics.visibleCells > 0 && heightFade > 0; + /** Fade by camera height; whether anything can draw. */ + function updateVisibility() { + const fade = readFade(); + diagnostics.heightFade = fade; + if (handle && fade !== heightFade) handle.update({ alpha: fade }); + heightFade = fade; + return Boolean(handle) && fade > 0; } return { supported, setField, updateVisibility, - tick(elapsedSeconds) { - if (material && !paused && Number.isFinite(elapsedSeconds)) - material.uniforms.phaseTime = Math.max(0, elapsedSeconds) % 10000; - }, setOptions(options = {}) { - if (typeof options.paused === 'boolean') paused = options.paused; - if (material) material.uniforms.ghostAlpha = paused ? 0.34 : 0.25; + if (typeof options.paused !== 'boolean' || options.paused === paused) + return; + paused = options.paused; + handle?.update({ paused }); }, clear, destroy() { @@ -270,7 +176,7 @@ export function createWindGpuRendering({ cesium: C, getViewer }) { getParticleCount: () => diagnostics.pathCount, getDiagnostics: () => ({ ...diagnostics, - ready: cells.length > 0 && cells.every((cell) => cell.primitive.ready), + ready: Boolean(handle) && drawn, mode: 'gpu-streamlines', displayHeightMeters: WIND_DISPLAY_HEIGHT_METERS, }), diff --git a/src/layers/wind/gpuRendering.test.mjs b/src/layers/wind/gpuRendering.test.mjs index 1a420e23b..0723c1711 100644 --- a/src/layers/wind/gpuRendering.test.mjs +++ b/src/layers/wind/gpuRendering.test.mjs @@ -1,147 +1,18 @@ import test from 'node:test'; import assert from 'node:assert/strict'; -import { createWindGpuRendering } from './gpuRendering.js'; import { - BoundingSphere, - Cartesian3, - Ellipsoid, - Intersect, - Occluder, - PerspectiveFrustum, -} from 'cesium'; -import { bakeWindStreamlines } from './streamlines.js'; + createWindGpuRendering, + windHeightFade, + windStreamlineSpec, +} from './gpuRendering.js'; +import { + WIND_DISPLAY_HEIGHT_METERS, + WIND_NARROW_PATH_LIMIT, + WIND_PATH_LIMIT, + WIND_PATH_STEPS, +} from './streamlines.js'; -function harness({ width = 1000 } = {}) { - const members = new Set(); - let geometryBuilds = 0; - const spheres = []; - const visibility = { - horizon: () => true, - frustum: () => Intersect.INSIDE, - horizonTests: 0, - frustumTests: 0, - }; - let occluderBuilds = 0; - class Material { - constructor(options) { - this.uniforms = options.fabric.uniforms; - this.source = options.fabric.source; - } - destroy() { - assert.ok(!this.destroyed, 'owned resource destroyed once'); - this.destroyed = true; - } - } - class Appearance { - static VERTEX_FORMAT = {}; - constructor(options) { - Object.assign(this, options); - this.vertexShaderSource ??= - 'in vec3 position3DHigh; in vec3 position3DLow; void main() { gl_Position = vec4(0.0); v_st.s = st.s; }'; - } - } - class Polyline { - constructor(options) { - Object.assign(this, options); - } - static createGeometry(options) { - geometryBuilds++; - const st = new Float32Array(options.positions.length * 2); - for (let i = 0; i < options.positions.length; i++) - st[i * 2] = i / (options.positions.length - 1); - return { attributes: { st: { values: st } } }; - } - } - class Primitive { - constructor(options) { - Object.assign(this, options); - this.ready = true; - } - destroy() { - assert.ok(!this.destroyed, 'owned resource destroyed once'); - this.destroyed = true; - } - isDestroyed() { - return Boolean(this.destroyed); - } - } - const C = { - ComponentDatatype: { FLOAT: 5126 }, - GeometryInstanceAttribute: class { - constructor(options) { - Object.assign(this, options); - } - }, - Material, - PolylineMaterialAppearance: Appearance, - PolylineGeometry: Polyline, - Primitive, - GeometryInstance: class { - constructor(options) { - Object.assign(this, options); - } - }, - Cartesian3, - Ellipsoid, - Intersect, - BoundingSphere: class extends BoundingSphere { - static fromPoints(points) { - const sphere = BoundingSphere.fromPoints(points); - spheres.push({ sphere, points }); - return sphere; - } - }, - Occluder: class { - constructor(sphere, cameraPosition) { - occluderBuilds++; - this.cameraPosition = cameraPosition; - } - isBoundingSphereVisible(sphere) { - visibility.horizonTests++; - return visibility.horizon(sphere, this.cameraPosition); - } - }, - ArcType: { NONE: 0 }, - }; - const volume = { - computeVisibility(sphere) { - visibility.frustumTests++; - return visibility.frustum(sphere); - }, - }; - const scene = { - globe: { show: false }, - camera: { - positionWC: Cartesian3.fromDegrees(0, 0, 1e7), - positionCartographic: { height: 1e7 }, - directionWC: new Cartesian3(-1, 0, 0), - upWC: new Cartesian3(0, 0, 1), - frustum: { computeCullingVolume: () => volume }, - }, - canvas: { clientWidth: width }, - primitives: { - add(item) { - members.add(item); - }, - remove(item) { - const removed = members.delete(item); - if (removed) item.destroy(); - return removed; - }, - }, - }; - return { - C, - scene, - members, - builds: () => geometryBuilds, - spheres, - visibility, - occluderBuilds: () => occluderBuilds, - owner: createWindGpuRendering({ cesium: C, getViewer: () => ({ scene }) }), - }; -} -const field = () => ({ +const wind = () => ({ nx: 4, ny: 3, lo1: -180, @@ -152,248 +23,152 @@ const field = () => ({ v: new Float32Array(12), }); -test('GPU owner builds regional native batches; ticks update uniforms without rebuilding geometry', () => { - const h = harness(); - assert.equal(h.owner.setField(field()), true); - assert.equal(h.members.size, 72); - const batch = [...h.members][0]; - assert.equal(batch.allowPicking, false); - assert.equal(batch.asynchronous, true); - assert.ok(batch.appearance.vertexShaderSource.includes('v_windFacing = dot')); - assert.ok( - batch.appearance.material.source.includes( - 'smoothstep(0.0, 0.065, v_windFacing)', - ), - ); - const builds = h.builds(); - assert.equal(builds, 0, 'expanded geometry is deferred to Cesium workers'); - assert.ok( - batch.appearance.vertexShaderSource.includes( - 'czm_batchTable_windSeed(batchId)', - ), - ); - h.owner.tick(3); - assert.equal(batch.appearance.material.uniforms.phaseTime, 3); - h.owner.setOptions({ paused: true }); - h.owner.tick(8); - assert.equal(batch.appearance.material.uniforms.phaseTime, 3); - h.owner.setOptions({ paused: false }); - h.owner.tick(9); - assert.equal(batch.appearance.material.uniforms.phaseTime, 9); - assert.equal(h.builds(), builds); - const diagnostics = h.owner.getDiagnostics(); - assert.ok(diagnostics.pathCount <= 7200); - assert.ok( - diagnostics.pathCount > 7000, - 'desktop retains the requested doubled global density', - ); - assert.ok(diagnostics.vertexCount > 0); - assert.ok( - diagnostics.vertexCount <= 7200 * 128, - 'expanded geometry remains bounded', - ); - assert.equal(diagnostics.ready, true); - assert.equal(diagnostics.displayHeightMeters, 12000); - assert.equal(diagnostics.cellCount, 72); - assert.equal(h.spheres.length, 72); - assert.equal(new Set([...h.members].map((p) => p.appearance)).size, 72); - for (const cell of h.members) { - assert.equal(cell.appearance.material, batch.appearance.material); - assert.equal(cell.appearance.material.uniforms.phaseTime, 9); - assert.equal(cell.appearance.material.uniforms.ghostAlpha, 0.25); - assert.equal(cell.compressVertices, false); - assert.equal(cell.releaseGeometryInstances, true); - } - batch.ready = false; - assert.equal( - h.owner.getDiagnostics().ready, - false, - 'every cell must be ready', - ); - batch.ready = true; - const instances = [...h.members].flatMap((p) => p.geometryInstances); - const baked = bakeWindStreamlines(field()); - assert.equal(instances.length, baked.length); - const bySeed = new Map( - instances.map((i) => [i.attributes.windSeed.value[0], i]), - ); - for (const path of baked) { - assert.deepEqual( - bySeed.get(path.seed).geometry.positions, - path.coordinates.map(([lon, lat]) => - Cartesian3.fromDegrees(lon, lat, 12000), - ), - ); - } - for (const { sphere, points } of h.spheres) { - assert.deepEqual(sphere, BoundingSphere.fromPoints(points)); - for (const point of points) - assert.ok( - Cartesian3.distance(point, sphere.center) <= sphere.radius + 1e-6, - ); - } - for (const instance of instances) { - assert.ok(instance.geometry instanceof h.C.PolylineGeometry); - assert.equal(instance.geometry.width, 2.4); - assert.equal(instance.attributes.windSeed.componentsPerAttribute, 1); - assert.ok(Number.isInteger(instance.attributes.windSeed.value[0])); - } +// A draw port whose fields record what they were asked, a camera at +// `height` and a canvas `width` wide. +function harness({ width = 1000, height = 2_000_000, refuse = null } = {}) { + const fields = []; + const camera = { height }; + const viewer = { canvas: { clientWidth: width } }; + const draw = { + field(spec) { + if (refuse) throw refuse; + const listeners = []; + const handle = { + spec, + updates: [], + disposed: false, + show: true, + update(patch) { + this.updates.push(patch); + }, + on(event, cb) { + assert.equal(event, 'drawn'); + listeners.push(cb); + return () => {}; + }, + dispose() { + assert.equal(this.disposed, false, 'disposed once'); + this.disposed = true; + }, + tell: () => listeners.forEach((cb) => cb()), + }; + fields.push(handle); + return handle; + }, + }; + const frames = []; + const owner = createWindGpuRendering({ + getViewer: () => viewer, + drawOf: () => draw, + cameraOf: () => ({ pose: () => ({ height: camera.height }) }), + frameOf: () => ({ requestRender: (reason) => frames.push(reason) }), + }); + return { owner, fields, camera, viewer, draw, frames }; +} + +test('the fade by camera height is none below 15 km and full from 60 km', () => { + assert.equal(windHeightFade(10_000), 0); + assert.equal(windHeightFade(15_000), 0); + assert.equal(windHeightFade(37_500), 0.5); + assert.equal(windHeightFade(60_000), 1); + assert.equal(windHeightFade(2e7), 1); }); -test('replacement, clear and destroy dispose every owned cell and the shared material', () => { - const h = harness(); - const assertDisposed = (batches) => { - assert.equal(batches.length, 72); - for (const batch of batches) { - assert.equal(batch.destroyed, true); - assert.equal(batch.appearance.material.destroyed, true); - } - }; - h.owner.setField(field()); - const first = [...h.members]; - h.owner.setField(field()); - assertDisposed(first); - const second = [...h.members]; +test('a wind grid becomes a windStreamlines spec over the rectangle its samples span', () => { + const field = wind(); + const spec = windStreamlineSpec(field, { + id: 'w', + pathBudget: 100, + alpha: 0.5, + paused: true, + }); + assert.equal(spec.kind, 'windStreamlines'); + assert.deepEqual(spec.rectangle, { + west: -180, + south: -90, + east: 180, + north: 90, + }); + assert.equal(spec.width, 4); + assert.equal(spec.height, 3); + assert.equal(spec.steps, WIND_PATH_STEPS); + assert.equal(spec.heightM, WIND_DISPLAY_HEIGHT_METERS); + assert.equal(spec.alpha, 0.5); + assert.equal(spec.paused, true); + assert.equal(spec.u, field.u); + assert.equal(spec.v, field.v); + const regional = windStreamlineSpec( + { ...field, nx: 4, ny: 4, lo1: -100, la1: 50, dx: 10, dy: 10 }, + { id: 'r', pathBudget: 1 }, + ); + assert.deepEqual( + regional.rectangle, + { west: -100, south: 20, east: -70, north: 50 }, + 'a regional grid spans its samples and does not wrap', + ); +}); + +test('streamlines draw through the port, faded by height, paused and ready once drawn', () => { + const h = harness({ height: 37_500 }); + assert.equal(h.owner.supported(), true); + assert.equal(h.owner.setField(wind()), true); + const [field] = h.fields; + assert.equal(field.spec.pathBudget, WIND_PATH_LIMIT); + assert.equal(field.spec.alpha, 0.5); + assert.equal(field.spec.paused, false); + assert.equal(h.owner.getDiagnostics().ready, false); + assert.equal(h.owner.getDiagnostics().mode, 'gpu-streamlines'); + assert.equal(h.owner.getParticleCount(), WIND_PATH_LIMIT); + field.tell(); + assert.equal(h.owner.getDiagnostics().ready, true); + assert.deepEqual(h.frames, ['wind'], 'a still scene draws the ready state'); + assert.equal(h.owner.updateVisibility(), true); + assert.deepEqual(field.updates, [], 'an unchanged fade asks nothing'); + h.camera.height = 10_000; + assert.equal(h.owner.updateVisibility(), false, 'nothing draws low down'); + assert.deepEqual(field.updates, [{ alpha: 0 }]); + assert.equal(h.owner.getDiagnostics().heightFade, 0); + h.camera.height = 100_000; + assert.equal(h.owner.updateVisibility(), true); + h.owner.setOptions({ paused: true }); + h.owner.setOptions({ paused: true }); + h.owner.setOptions({ overlay: 'speed' }); + assert.deepEqual(field.updates, [ + { alpha: 0 }, + { alpha: 1 }, + { paused: true }, + ]); + h.owner.setField(wind()); + assert.equal(field.disposed, true, 'a new grid replaces the field'); + assert.equal(h.fields[1].spec.paused, true, 'and keeps the pause'); + assert.notEqual(h.fields[1].spec.id, field.spec.id); h.owner.clear(); - assertDisposed(second); - assert.equal(h.members.size, 0); + assert.equal(h.fields[1].disposed, true); assert.equal(h.owner.getParticleCount(), 0); assert.equal(h.owner.getDiagnostics().ready, false); - h.owner.setField(field()); - const third = [...h.members]; h.owner.destroy(); - assertDisposed(third); - assert.equal(h.members.size, 0); assert.equal(h.owner.supported(), false); - assert.equal(h.owner.setField(field()), false); -}); - -test('unsupported or failed geometry cleanly requests the existing fallback', () => { - const missing = createWindGpuRendering({ - cesium: {}, - getViewer: () => ({ scene: {} }), - }); - assert.equal(missing.setField(field()), false); - const h = harness(); - h.C.PolylineGeometry = class { - constructor() { - throw new Error('test build failure'); - } - }; - assert.equal(h.owner.setField(field()), false); - assert.equal(h.members.size, 0); - assert.match(h.owner.getDiagnostics().error, /test build failure/); + assert.equal(h.owner.setField(wind()), false); }); test('narrow canvases use a lower bounded path budget', () => { - const h = harness({ width: 390 }); - assert.equal(h.owner.setField(field()), true); - assert.ok(h.owner.getParticleCount() <= 1200); - assert.ok(h.owner.getParticleCount() > 1000); + const h = harness({ width: 600 }); + assert.equal(h.owner.setField(wind()), true); + assert.equal(h.fields[0].spec.pathBudget, WIND_NARROW_PATH_LIMIT); }); -test('cell visibility combines horizon, frustum and height with shared fade uniforms', () => { - const h = harness(); - h.owner.setField(field()); - const batches = [...h.members]; - const camera = h.scene.camera; - h.visibility.horizon = (sphere) => - h.spheres.findIndex((s) => s.sphere === sphere) % 2 === 0; - h.visibility.frustum = (sphere) => - h.spheres.findIndex((s) => s.sphere === sphere) % 3 === 0 - ? Intersect.INTERSECTING - : Intersect.OUTSIDE; - assert.equal(h.owner.updateVisibility(camera), true); - assert.equal(h.owner.getDiagnostics().visibleCells, 12); - let vertices = 0; - for (let i = 0; i < batches.length; i++) { - assert.equal(batches[i].show, i % 6 === 0); - if (batches[i].show) - vertices += batches[i].geometryInstances.reduce( - (sum, p) => sum + p.geometry.positions.length * 4 - 4, - 0, - ); - } - assert.equal(h.owner.getDiagnostics().visibleVertexCount, vertices); - assert.equal(h.visibility.horizonTests, 72); - assert.equal(h.visibility.frustumTests, 36); - for (const [height, fade] of [ - [60000, 1], - [37500, 0.5], - [15000, 0], - [1200, 0], - ]) { - camera.positionCartographic.height = height; - assert.equal(h.owner.updateVisibility(camera), fade > 0); - assert.equal(h.owner.getDiagnostics().heightFade, fade); - for (const batch of batches) { - assert.equal(batch.appearance.material.uniforms.heightFade, fade); - assert.match(batch.appearance.material.source, /horizon \* heightFade/); - if (!fade) assert.equal(batch.show, false); - } - } - assert.equal(h.owner.getDiagnostics().visibleVertexCount, 0); - assert.equal(h.owner.getDiagnostics().visibleCells, 0); - assert.equal( - h.visibility.horizonTests, - 216, - 'zero fade skips all sphere tests', - ); - assert.equal(h.visibility.frustumTests, 108); - assert.equal( - h.occluderBuilds(), - 1, - 'occluder is reused across camera updates', - ); -}); - -test('real Cesium sphere culling hides far hemisphere with globe hidden and rejects a sky-facing view', () => { - const h = harness(); - h.C.Occluder = Occluder; - h.owner.setField(field()); - const camera = h.scene.camera; - camera.frustum = new PerspectiveFrustum({ - fov: Math.PI / 3, - aspectRatio: 1.5, - near: 1, - far: 5e7, +test('a refused or missing field falls back to the canvas', () => { + const refused = harness({ refuse: new TypeError('no streamlines here') }); + assert.equal(refused.owner.setField(wind()), false); + assert.equal(refused.owner.getDiagnostics().error, 'no streamlines here'); + assert.equal(refused.owner.getParticleCount(), 0); + const none = createWindGpuRendering({ + getViewer: () => ({}), + drawOf: () => ({}), + cameraOf: () => null, }); - assert.equal(h.owner.updateVisibility(camera), true); - const facingEarth = h.owner.getDiagnostics(); - assert.ok(facingEarth.visibleCells > 0 && facingEarth.visibleCells < 72); - for (let i = 0; i < h.spheres.length; i++) { - const sphere = h.spheres[i].sphere; - if (sphere.center.x < -5e6) assert.equal([...h.members][i].show, false); - } - camera.directionWC.x = 1; - assert.equal(h.owner.updateVisibility(camera), false); - assert.equal(h.owner.getDiagnostics().visibleCells, 0); - camera.positionWC = Cartesian3.fromDegrees(180, 0, 1e7); - assert.equal( - h.owner.updateVisibility(camera), - true, - 'camera position updates the owned horizon test', - ); - h.owner.destroy(); -}); - -test('a failed later cell build releases already installed cells and shared material', () => { - const h = harness(); - const NativePrimitive = h.C.Primitive; - const built = []; - h.C.Primitive = class extends NativePrimitive { - constructor(options) { - if (built.length === 2) throw new Error('later cell failed'); - super(options); - built.push(this); - } - }; - assert.equal(h.owner.setField(field()), false); - assert.equal(h.members.size, 0); - assert.equal(built.length, 2); - for (const batch of built) { - assert.equal(batch.destroyed, true); - assert.equal(batch.appearance.material.destroyed, true); - } - assert.match(h.owner.getDiagnostics().error, /later cell failed/); + assert.equal(none.supported(), false); + assert.equal(none.setField(wind()), false); + const absent = createWindGpuRendering({ getViewer: () => null }); + assert.equal(absent.supported(), false); }); diff --git a/src/layers/wind/rendering.js b/src/layers/wind/rendering.js index cfcf324dc..050bbf362 100644 --- a/src/layers/wind/rendering.js +++ b/src/layers/wind/rendering.js @@ -159,12 +159,10 @@ export function createWindRendering({ let bounds = null; let cameraChanged = true; let painted = 0; - const gpu = createGpuRendering({ cesium, getViewer }); + const gpu = createGpuRendering({ getViewer, drawOf }); let gpuActive = false; - let gpuVisible = false; let reportedGpuReady = null; let gpuNarrow = false; - let flowTime = 0; const relief = createWindRelief({ cesium, getViewer }); const signature = Array(8).fill(null); const wind = { u: 0, v: 0 }; @@ -202,7 +200,7 @@ export function createWindRendering({ canvas && !hidden() && !still() && - (!gpuActive || gpuVisible) && + !gpuActive && frame === null ) frame = globalThis.requestAnimationFrame(draw); @@ -507,14 +505,8 @@ export function createWindRendering({ motionChanged(); visibilityUpdated = true; } - if (gpuActive && viewer && !visibilityUpdated) { - gpuVisible = gpu.updateVisibility(viewer.scene.camera); - if (gpuVisible) schedule(); - else { - cancel(); - lastTime = null; - } - } + // The renderer culls and animates the streamlines; this fades them. + if (gpuActive && viewer && !visibilityUpdated) gpu.updateVisibility(); const ready = gpuActive ? gpu.getDiagnostics().ready : null; if (ready !== reportedGpuReady) { reportedGpuReady = ready; @@ -542,12 +534,7 @@ export function createWindRendering({ const viewer = viewerReady(); if (gpuActive) { if (viewer) updateImageryFade(viewer.scene.camera); - gpuVisible = viewer ? gpu.updateVisibility(viewer.scene.camera) : false; - if (gpuVisible) { - gpu.tick(flowTime); - viewer.scene.requestRender(); - schedule(); - } + if (viewer) gpu.updateVisibility(); return; } if (still() && viewer) paint(viewer, 0, true); @@ -705,26 +692,17 @@ export function createWindRendering({ function draw(time) { frame = null; - if (!running || !field || hidden() || still()) return; - if (gpuActive && !gpuVisible) { - lastTime = null; - return; - } + if (!running || !field || hidden() || still() || gpuActive) return; const viewer = viewerReady(); if (!viewer) return; try { - const resized = !gpuActive && resize(viewer); + const resized = resize(viewer); if (resized) cameraChanged = true; const elapsed = lastTime === null ? 1 / 60 : Math.max(0, (time - lastTime) / 1000); // Limit full particle paints to 30 Hz while preserving elapsed-time motion/fading. if (lastTime === null || elapsed >= 0.032 || cameraChanged) { - if (gpuActive) { - flowTime += elapsed; - gpu.tick(flowTime); - viewer.scene.requestRender(); - cameraChanged = false; - } else paint(viewer, Math.min(0.1, elapsed), false, elapsed); + paint(viewer, Math.min(0.1, elapsed), false, elapsed); lastTime = time; } } catch (error) { @@ -773,7 +751,6 @@ export function createWindRendering({ if (!reuseGeometry) { gpuActive = gpu.supported() && gpu.setField(field); reportedGpuReady = gpuActive ? gpu.getDiagnostics().ready : null; - flowTime = 0; } clearPixels(); particles = []; @@ -827,9 +804,7 @@ export function createWindRendering({ gpu.clear(); relief.clear(); gpuActive = false; - gpuVisible = false; reportedGpuReady = null; - flowTime = 0; removeImagery(); imageryError = null; clearPixels(); diff --git a/src/layers/wind/rendering.test.mjs b/src/layers/wind/rendering.test.mjs index 815f8c90a..2006cecbc 100644 --- a/src/layers/wind/rendering.test.mjs +++ b/src/layers/wind/rendering.test.mjs @@ -453,11 +453,11 @@ test('scalar imagery builds once, survives pause, replaces cleanly, and releases for (const overlay of ['speed', 'pressure', 'temperature']) { test(`${overlay} imagery fades with log camera height and resumes from idle`, () => { + let camera = null; const gpu = { supported: () => true, setField: () => true, - updateVisibility: (camera) => camera.positionCartographic.height > 15000, - tick() {}, + updateVisibility: () => camera.positionCartographic.height > 15000, setOptions() {}, clear() {}, destroy() {}, @@ -465,7 +465,7 @@ for (const overlay of ['speed', 'pressure', 'temperature']) { getDiagnostics: () => ({ ready: true }), }; const h = harness({ createGpuRendering: () => gpu }); - const camera = h.viewer.scene.camera; + camera = h.viewer.scene.camera; const baseAlpha = overlay === 'temperature' ? 1 : 0.85; const snapshot = { grid: FIELD, @@ -673,11 +673,11 @@ test('world-anchored wind glyphs remain readable at low FPS without accelerating h.rendering.destroy(); }); -test('GPU flow uses one scheduler, rebuilds only across viewport budgets, and pauses cleanly', () => { +test('GPU flow leaves animation to the renderer, rebuilds only across viewport budgets, and pauses cleanly', () => { let builds = 0, - ticks = 0, cleared = 0, destroyed = 0; + const options = []; const gpu = { supported: () => true, updateVisibility: () => true, @@ -686,10 +686,9 @@ test('GPU flow uses one scheduler, rebuilds only across viewport budgets, and pa builds++; return true; }, - tick() { - ticks++; + setOptions(value) { + options.push(value.paused); }, - setOptions() {}, clear() { cleared++; }, @@ -700,16 +699,12 @@ test('GPU flow uses one scheduler, rebuilds only across viewport budgets, and pa getDiagnostics: () => ({ ready: true, pathCount: 1 }), }; const h = harness({ createGpuRendering: () => gpu }); - let renders = 0; - h.viewer.scene.requestRender = () => { - renders++; - }; h.rendering.attach(); h.rendering.setField({ grid: FIELD, u: FIELD.u, v: FIELD.v }); h.rendering.start(); - h.callbacks.shift()(16); assert.equal(h.rendering.getDiagnostics().renderMode, 'gpu-streamlines'); - assert.ok(ticks > 0 && renders > 0); + assert.equal(h.pending.size, 0, 'the renderer moves the highlight'); + assert.equal(options.at(-1), false); assert.equal(h.strokes.length, 0); h.viewer.scene.camera.positionWC.x = 10; h.preRender.emit(); @@ -719,7 +714,7 @@ test('GPU flow uses one scheduler, rebuilds only across viewport budgets, and pa 'camera changes project geometry without rebuilding paths', ); h.rendering.setOptions({ paused: true }); - assert.equal(h.pending.size, 0); + assert.equal(options.at(-1), true, 'the pause reaches the renderer'); h.canvas.clientWidth = 390; h.preRender.emit(); assert.equal(builds, 2, 'crossing the narrow viewport boundary rebakes once'); @@ -744,7 +739,6 @@ for (const paused of [false, true]) { ready = false; return true; }, - tick() {}, setOptions() {}, clear() {}, destroy() {}, @@ -796,9 +790,8 @@ for (const paused of [false, true]) { }); } -test('scalar snapshots retain identical GPU wind geometry and animation phase', () => { +test('scalar snapshots retain identical GPU wind geometry, and so its animation phase', () => { let builds = 0; - const times = []; const gpu = { supported: () => true, updateVisibility: () => true, @@ -806,9 +799,6 @@ test('scalar snapshots retain identical GPU wind geometry and animation phase', builds++; return true; }, - tick(time) { - times.push(time); - }, setOptions() {}, clear() {}, destroy() {}, @@ -833,9 +823,6 @@ test('scalar snapshots retain identical GPU wind geometry and animation phase', h.rendering.attach(); h.rendering.setField(snapshot()); h.rendering.start(); - h.callbacks.shift()(16); - h.callbacks.shift()(1016); - const phase = times.at(-1); h.rendering.setOptions({ overlay: 'temperature' }); h.rendering.setField( snapshot({ @@ -852,11 +839,6 @@ test('scalar snapshots retain identical GPU wind geometry and animation phase', 'freshly decoded equal arrays reuse the worker-built primitive', ); assert.equal(h.imagery.length, 1, 'new scalar field is still installed'); - h.callbacks.shift()(1032); - assert.ok( - times.at(-1) >= phase, - 'scalar acquisition does not reset travelling highlights', - ); h.rendering.setField( snapshot({ scalar: { @@ -899,7 +881,6 @@ for (const [label, change] of Object.entries({ builds++; return true; }, - tick() {}, setOptions() {}, clear() {}, destroy() {}, @@ -927,25 +908,25 @@ for (const [label, change] of Object.entries({ } for (const eventName of ['preRender', 'moveEnd']) { - test(`GPU height suspension resumes from camera ${eventName} without preRender`, () => { - const times = []; + test(`GPU height fade follows camera ${eventName} with no frames of its own`, () => { let visible = false; - let inFrustum = true; + let fades = 0; + const options = []; const gpu = { supported: () => true, setField: () => true, - updateVisibility(camera) { - visible = camera.positionCartographic.height > 15000 && inFrustum; + updateVisibility() { + fades++; + visible = camera.positionCartographic.height > 15000; return visible; }, - tick(time) { - times.push(time); + setOptions(value) { + options.push(value.paused); }, - setOptions() {}, clear() {}, destroy() {}, getParticleCount: () => 1, - getDiagnostics: () => ({ ready: true, visibleCells: Number(visible) }), + getDiagnostics: () => ({ ready: true }), }; const h = harness({ createGpuRendering: () => gpu }); const camera = h.viewer.scene.camera; @@ -958,52 +939,27 @@ for (const eventName of ['preRender', 'moveEnd']) { h.preRender.emit(); assert.equal(h.pending.size, 0); assert.equal(renders, 0); - assert.equal(times.length, 0); + assert.equal(visible, false); assert.equal(camera.percentageChanged, 0.5); assert.equal(camera.changed.size, 0); camera.positionCartographic.height = 60000; + const before = fades; (eventName === 'preRender' ? h.preRender : camera.moveEnd).emit(); + assert.ok(fades > before, 'the fade follows the camera'); + assert.equal(visible, true); assert.equal( renders, eventName === 'preRender' ? 0 : 1, 'moveEnd wakes the parked scene', ); - assert.equal(h.pending.size, 1); - h.callbacks.shift()(16); - assert.equal(times.length, 1); - const phase = times.at(-1); - const queued = h.callbacks.shift(); - camera.positionCartographic.height = 15000; - h.preRender.emit(); - const parkedRenders = renders; - queued(100000); - assert.equal(h.pending.size, 0); - assert.equal(renders, parkedRenders); - assert.equal(times.length, 1, 'parked draw cannot tick or advance phase'); - - camera.positionCartographic.height = 60000; - (eventName === 'preRender' ? h.preRender : camera.moveEnd).emit(); - h.callbacks.shift()(200000); - assert.ok( - times.at(-1) - phase < 0.1, - 'idle time does not jump animation phase', - ); - inFrustum = false; - h.preRender.emit(); - assert.equal(h.pending.size, 0, 'frustum-hidden cells also park'); - inFrustum = true; + assert.equal(h.pending.size, 0, 'the renderer animates, not the layer'); h.rendering.setOptions({ paused: true }); - (eventName === 'preRender' ? h.preRender : camera.moveEnd).emit(); - assert.equal(h.pending.size, 0, 'camera events respect pause'); + assert.equal(options.at(-1), true); h.rendering.setOptions({ paused: false }); - globalThis.document.hidden = true; - h.visibility.emit(); - (eventName === 'preRender' ? h.preRender : camera.moveEnd).emit(); - assert.equal(h.pending.size, 0, 'camera events respect hidden documents'); - globalThis.document.hidden = false; - h.visibility.emit(); - assert.equal(h.pending.size, 1); + assert.equal(options.at(-1), false); + h.rendering.stop(); + assert.equal(options.at(-1), true, 'a stopped layer holds the flow still'); h.rendering.destroy(); assert.equal(h.pending.size, 0); assert.equal(camera.changed.size, 0); @@ -1107,7 +1063,6 @@ for (const overlay of ['speed', 'temperature', 'pressure']) { supported: () => true, setField: () => true, updateVisibility: () => true, - tick() {}, setOptions() {}, clear() {}, destroy() {}, diff --git a/src/render/cesium/drawFields.js b/src/render/cesium/drawFields.js index 4d95244b4..5a44f8dc4 100644 --- a/src/render/cesium/drawFields.js +++ b/src/render/cesium/drawFields.js @@ -1,10 +1,11 @@ /** * @module render/cesium/drawFields - * @description The Cesium draw port's `field` handles. It draws one kind: - * `rasterShell`, a raster on a rectangle raised above the ellipsoid, drawn - * flat in the opaque pass in the scene's primitive order (ascending height), - * alpha-blended, without depth writes and never picked. Other kinds are - * refused loudly. + * @description The Cesium draw port's `field` handles. It draws two kinds: + * `windStreamlines` (drawStreamlines.js) and `rasterShell`, a raster on a + * rectangle raised above the ellipsoid, drawn flat in the opaque pass in + * the scene's primitive order (ascending height), alpha-blended, without + * depth writes and never picked. Other kinds (`scalarRaster`) are refused + * loudly. * * Choices the contract leaves open, taken conservatively: * - An image is read when it is first named, as a Cesium material reads @@ -25,6 +26,7 @@ */ import * as Cesium from 'cesium'; import { listenerList, uncaught } from './common.js'; +import { createWindStreamlines } from './drawStreamlines.js'; const MATERIAL_TYPE = 'DrawRasterShell'; // Renders after an image swap: one queues the upload, one uploads and draws, one spare. @@ -632,6 +634,19 @@ export function createCesiumFields({ if (fields.has(spec?.id)) throw new Error(`a field with id ${spec.id} is live`); if (spec?.kind === 'rasterShell') return rasterShell(spec); + if (spec?.kind === 'windStreamlines') { + const handle = createWindStreamlines({ + scene, + spec, + report, + cesium, + onDispose: () => { + if (fields.get(spec.id) === handle) fields.delete(spec.id); + }, + }); + fields.set(spec.id, handle); + return handle; + } throw new TypeError( `the Cesium renderer draws no ${spec?.kind} fields yet`, ); diff --git a/src/render/cesium/drawStreamlines.js b/src/render/cesium/drawStreamlines.js new file mode 100644 index 000000000..d39e4b9b7 --- /dev/null +++ b/src/render/cesium/drawStreamlines.js @@ -0,0 +1,469 @@ +/** + * @module render/cesium/drawStreamlines + * @description The Cesium draw port's `windStreamlines` fields: paths + * traced once through the wind grid (`bakeWindStreamlines`), drawn as + * polylines at `heightM` in 30° cells, each a primitive of its own. A + * highlight moves along each path in the wind's direction; a faint ghost + * of the whole path stays. Cells the eye cannot see (behind the Earth or + * outside the view) are not drawn, and nothing animates while no cell is. + * + * Choices the contract leaves open, taken conservatively: + * - The grid's samples are points: the first column at `rectangle.west` + * and the first row at `rectangle.north`, rows running south. A grid + * whose rectangle spans 360° of longitude wraps (`width` columns over + * the whole circle); any other is `width - 1` steps from west to east. + * - `style.color` is the ghost's and the trail's colour; the moving tip + * brightens it towards white. `speedFactor` scales how fast the tip + * moves (1 by default). + * - The highlight moves on the page's own clock, at most 30 times a + * second, asking for the frames it needs; `paused` holds it where it is + * and raises the ghost. `alpha` scales everything, and 0 draws nothing. + * - Without `heightM` the paths are drawn at the ellipsoid's surface. + * - Any change but `alpha`, `paused` and `style` traces the paths again. + * - Scenes not in 3D refuse the field, as does a grid no path runs through. + */ +import * as Cesium from 'cesium'; +import { + bakeWindStreamlines, + groupWindPaths, +} from '../../layers/wind/streamlines.js'; +import { listenerList, uncaught } from './common.js'; + +// How fast the highlight runs along a path, in path lengths per second. +const TIP_SPEED = 0.16; +const GHOST_ALPHA = 0.25; +const GHOST_ALPHA_PAUSED = 0.34; +// The highlight moves at most this often (seconds between frames). +const STEP_SECONDS = 0.032; + +// A persistent fine curve plus a moving, tapered highlight. The integer part +// of s identifies a path; its fractional part follows the wind. +const FLOW_MATERIAL = ` +in float v_windFacing; +czm_material czm_getMaterial(czm_materialInput materialInput) +{ + czm_material material = czm_getDefaultMaterial(materialInput); + float pathId = floor(materialInput.st.s); + float along = fract(materialInput.st.s); + float offset = fract((pathId + 1.0) * 0.61803398875); + float behind = fract(phaseTime * tipSpeed + offset - along); + float tail = (1.0 - smoothstep(0.0, 0.32, behind)); + float tip = 1.0 - smoothstep(0.0, 0.045, behind); + float ends = smoothstep(0.0, 0.055, along) * (1.0 - smoothstep(0.945, 1.0, along)); + float edge = 1.0 - smoothstep(0.26, 0.5, abs(materialInput.st.t - 0.5)); + float horizon = smoothstep(0.0, 0.065, v_windFacing); + material.diffuse = mix(baseColor.rgb, vec3(0.91, 0.99, 1.0), tip); + material.alpha = (ghostAlpha + 0.64 * tail + 0.16 * tip) * ends * edge * horizon * heightFade; + return material; +}`; + +const DEFAULT_COLOR = '#80c9e6'; + +/** A contract colour as Cesium's; one Cesium cannot read is the default. */ +function toColor(C, color) { + const Color = C.Color ?? Cesium.Color; + if (Array.isArray(color)) + return new Color(color[0], color[1], color[2], color[3] ?? 1); + return ( + Color.fromCssColorString(String(color ?? DEFAULT_COLOR)) ?? + Color.fromCssColorString(DEFAULT_COLOR) + ); +} + +/** + * The spec's grid as the wind sampler reads it. A rectangle across the + * antimeridian (west east of east) runs east past 180°. + */ +export function windGridOf(spec) { + const { west, south, north } = spec.rectangle; + let { east } = spec.rectangle; + if (east < west) east += 360; + const span = east - west; + const wraps = span >= 360 - 1e-9; + return { + u: spec.u, + v: spec.v, + nx: spec.width, + ny: spec.height, + lo1: west, + la1: north, + dx: span / (wraps ? spec.width : spec.width - 1), + dy: (north - south) / (spec.height - 1), + }; +} + +/** + * One `windStreamlines` field over `scene`. + * @param {{scene: object, spec: object, report?: (error: unknown) => void, + * cesium?: object, + * requestFrame?: (cb: (time: number) => void) => number, + * cancelFrame?: (id: number) => void, onDispose?: () => void}} options + */ +export function createWindStreamlines({ + scene, + spec, + report = uncaught, + cesium: C = Cesium, + requestFrame = (cb) => globalThis.requestAnimationFrame(cb), + cancelFrame = (id) => globalThis.cancelAnimationFrame(id), + onDispose = () => {}, +}) { + if ( + C.SceneMode?.SCENE3D !== undefined && + scene.mode !== undefined && + scene.mode !== C.SceneMode.SCENE3D + ) + throw new TypeError( + 'the Cesium renderer draws wind streamlines in 3D only', + ); + + const live = () => !scene.isDestroyed?.(); + const requestRender = () => { + if (live()) scene.requestRender(); + }; + let current = { ...spec, style: { ...spec.style } }; + let alpha = spec.alpha ?? 1; + let paused = spec.paused === true; + let shown = true; + let disposed = false; + const cells = []; + let material = null; + let occluder = null; + let phaseTime = 0; + let visibleCells = 0; + let diagnostics = { pathCount: 0, vertexCount: 0, buildMs: 0, cellCount: 0 }; + // The animation frame asked for, and when the highlight last moved. + let frameId = null; + let lastTime = null; + // 'drawn' is owed for the latest change, made at `changedAt`. + let owed = true; + let renders = 0; + let changedAt = 0; + const frameNumber = () => scene.frameState?.frameNumber ?? renders; + const drawnListeners = listenerList(report); + + function clear() { + for (const cell of cells) { + if (live() && scene.primitives && !scene.primitives.isDestroyed?.()) + scene.primitives.remove(cell.primitive); + if (!cell.primitive.isDestroyed?.()) cell.primitive.destroy?.(); + } + cells.length = 0; + if (material && !material.isDestroyed?.()) material.destroy?.(); + material = null; + occluder = null; + visibleCells = 0; + } + + function styleUniforms() { + if (!material) return; + const color = toColor(C, current.style?.color); + material.uniforms.baseColor = color; + material.uniforms.tipSpeed = TIP_SPEED * (current.style?.speedFactor ?? 1); + material.uniforms.ghostAlpha = paused ? GHOST_ALPHA_PAUSED : GHOST_ALPHA; + material.uniforms.heightFade = alpha; + } + + /** Trace and build; a failure leaves nothing built and throws. */ + function build() { + try { + buildCells(); + } catch (error) { + clear(); + diagnostics = { pathCount: 0, vertexCount: 0, buildMs: 0, cellCount: 0 }; + throw error; + } + } + function buildCells() { + clear(); + const started = performance.now(); + // The paths are traced round the whole globe, the wind wrapping east and + // west: a grid that does not span it is refused, not drawn wrapped. + const grid = windGridOf(current); + const { west, east } = current.rectangle; + if ((east < west ? east + 360 : east) - west < 360 - 1e-9) + throw new RangeError( + 'the Cesium renderer draws wind streamlines over the whole globe only', + ); + const paths = bakeWindStreamlines(grid, { + count: current.pathBudget, + steps: current.steps, + }); + // A grid no path runs through is refused, so its caller can draw it + // some other way. + if (!paths.length) + throw new RangeError('no wind streamlines run through this grid'); + let vertexCount = 0; + material = new C.Material({ + fabric: { + type: 'DrawWindStreamline', + uniforms: { + phaseTime, + ghostAlpha: GHOST_ALPHA, + heightFade: 0, + tipSpeed: TIP_SPEED, + baseColor: toColor(C, DEFAULT_COLOR), + }, + source: FLOW_MATERIAL, + }, + translucent: () => true, + }); + styleUniforms(); + const base = new C.PolylineMaterialAppearance({ material }); + // Extend Cesium's own polyline shader rather than duplicate its + // expansion and precision code. Explicit facing also masks the far + // hemisphere when a scene keeps no globe depth for translucent objects. + const source = base.vertexShaderSource; + if ( + !/void\s+main\s*\(\s*\)/.test(source) || + !/v_st\.s\s*=\s*st\.s\s*;/.test(source) + ) + throw new Error('Wind polyline shader entry unavailable'); + const seededSource = source.replace( + /v_st\.s\s*=\s*st\.s\s*;/, + 'v_st.s = st.s * 0.999 + czm_batchTable_windSeed(batchId);', + ); + const vertexShaderSource = + `out float v_windFacing;\n${seededSource}`.replace( + /void\s+main\s*\(\s*\)\s*\{/, + `void main() {\nvec3 windWorld = (czm_model * vec4(position3DHigh + position3DLow, 1.0)).xyz;\nv_windFacing = dot(normalize(windWorld), normalize(czm_viewerPositionWC - windWorld));\n`, + ); + // EllipsoidalOccluder only tests points: a sphere occluder with an + // inscribed Earth sphere, whether or not the globe shows. + occluder = new C.Occluder( + new C.BoundingSphere(C.Cartesian3.ZERO, C.Ellipsoid.WGS84.minimumRadius), + scene.camera.positionWC, + ); + const height = Number(current.heightM) || 0; + const width = current.style?.widthPx ?? 2.4; + for (const group of groupWindPaths(paths)) { + const cellPositions = []; + let cellVertexCount = 0; + const instances = group.paths.map((path) => { + const positions = path.coordinates.map(([lon, lat]) => + C.Cartesian3.fromDegrees(lon, lat, height), + ); + // Cesium's worker expands the lines; per-instance seeds keep the + // expanded vertex buffer off the main thread. + const geometry = new C.PolylineGeometry({ + positions, + width, + arcType: C.ArcType?.NONE, + vertexFormat: C.PolylineMaterialAppearance.VERTEX_FORMAT, + }); + cellPositions.push(...positions); + cellVertexCount += positions.length * 4 - 4; + return new C.GeometryInstance({ + geometry, + attributes: { + windSeed: new C.GeometryInstanceAttribute({ + componentDatatype: C.ComponentDatatype.FLOAT, + componentsPerAttribute: 1, + value: [path.seed], + }), + }, + }); + }); + const appearance = new C.PolylineMaterialAppearance({ + material, + vertexShaderSource, + translucent: true, + renderState: { depthTest: { enabled: true }, depthMask: false }, + }); + const primitive = new C.Primitive({ + show: false, + geometryInstances: instances, + appearance, + asynchronous: true, + allowPicking: false, + releaseGeometryInstances: true, + compressVertices: false, + }); + cells.push({ + primitive, + sphere: C.BoundingSphere.fromPoints(cellPositions), + vertexCount: cellVertexCount, + }); + scene.primitives.add(primitive); + vertexCount += cellVertexCount; + } + diagnostics = { + pathCount: paths.length, + vertexCount, + buildMs: performance.now() - started, + cellCount: cells.length, + }; + } + + // Which cells the eye can see, before each frame draws. + function cull() { + visibleCells = 0; + const camera = scene.camera; + const draws = shown && alpha > 0 && cells.length > 0 && camera; + let volume; + if (draws) { + occluder.cameraPosition = camera.positionWC; + volume = camera.frustum.computeCullingVolume( + camera.positionWC, + camera.directionWC, + camera.upWC, + ); + } + for (const cell of cells) { + cell.primitive.show = Boolean( + draws && + occluder.isBoundingSphereVisible(cell.sphere) && + volume.computeVisibility(cell.sphere) !== C.Intersect.OUTSIDE, + ); + if (cell.primitive.show) visibleCells += 1; + } + } + const page = globalThis.document; + const animating = () => + !disposed && + shown && + !paused && + alpha > 0 && + visibleCells > 0 && + page?.hidden !== true; + function step(time) { + frameId = null; + if (!animating()) { + lastTime = null; + return; + } + const elapsed = lastTime === null ? null : (time - lastTime) / 1000; + // A first frame (after a pause, a hidden page or nothing in view) moves + // one tick; otherwise the highlight moves by the time passed, and a frame + // is drawn, at most every STEP_SECONDS. + let moved = true; + if (elapsed === null) phaseTime += 1 / 60; + else if (elapsed >= STEP_SECONDS) phaseTime += elapsed; + else moved = false; + if (moved) { + lastTime = time; + if (material) material.uniforms.phaseTime = phaseTime % 10000; + requestRender(); + } + frameId = requestFrame(step); + } + function animate() { + if (animating()) frameId ??= requestFrame(step); + else if (frameId !== null) { + cancelFrame(frameId); + frameId = null; + lastTime = null; + } + } + + const ready = () => cells.every((cell) => cell.primitive.ready); + function changed() { + owed = true; + changedAt = frameNumber(); + requestRender(); + } + // A field that cannot be built is refused, holding nothing. + build(); + const offPreRender = scene.preRender.addEventListener(() => { + cull(); + animate(); + }); + // A hidden page stops the highlight; shown again, it starts afresh rather + // than jumping by the time it was hidden. + const onVisibility = () => { + lastTime = null; + animate(); + }; + page?.addEventListener?.('visibilitychange', onVisibility); + const offPostRender = scene.postRender.addEventListener(() => { + renders += 1; + // Nothing built (a rebuild failed) is never told drawn. + if (!owed || !shown || disposed || !cells.length) return; + if (!ready() || frameNumber() <= changedAt) { + requestRender(); + return; + } + owed = false; + drawnListeners.fire(); + }); + + changed(); + + return { + id: spec.id, + get show() { + return shown; + }, + set show(value) { + const next = Boolean(value); + if (disposed || next === shown) return; + shown = next; + if (!shown) { + for (const cell of cells) cell.primitive.show = false; + visibleCells = 0; + animate(); + } + changedAt = frameNumber(); + requestRender(); + }, + update(patch = {}) { + if (disposed) return; + if (patch.kind !== undefined && patch.kind !== 'windStreamlines') + throw new TypeError('a field keeps its kind'); + const retrace = + ['u', 'v', 'width', 'height', 'pathBudget', 'steps', 'heightM'].some( + (key) => key in patch && patch[key] !== current[key], + ) || + (patch.rectangle !== undefined && + ['west', 'south', 'east', 'north'].some( + (edge) => patch.rectangle[edge] !== current.rectangle?.[edge], + )); + const restroke = + patch.style?.widthPx !== undefined && + patch.style.widthPx !== current.style?.widthPx; + current = { + ...current, + ...patch, + style: { ...current.style, ...patch.style }, + }; + if ('alpha' in patch) alpha = patch.alpha ?? 1; + if ('paused' in patch) paused = patch.paused === true; + if (retrace || restroke) + try { + build(); + } catch (error) { + // It draws nothing until a change builds again. + report(error); + } + else styleUniforms(); + cull(); + animate(); + changed(); + }, + on(event, cb) { + if (event !== 'drawn') return () => {}; + return drawnListeners.on(cb); + }, + dispose() { + if (disposed) return; + disposed = true; + if (frameId !== null) cancelFrame(frameId); + frameId = null; + offPreRender(); + offPostRender(); + page?.removeEventListener?.('visibilitychange', onVisibility); + drawnListeners.clear(); + clear(); + requestRender(); + onDispose(); + }, + /** For tests and diagnostics: what it built and draws. */ + diagnostics: () => ({ + ...diagnostics, + visibleCells, + ready: ready(), + animating: frameId !== null, + phaseTime, + }), + }; +} diff --git a/src/render/cesium/drawStreamlines.test.mjs b/src/render/cesium/drawStreamlines.test.mjs new file mode 100644 index 000000000..58d8e3aeb --- /dev/null +++ b/src/render/cesium/drawStreamlines.test.mjs @@ -0,0 +1,547 @@ +import test from 'node:test'; +import assert from 'node:assert/strict'; +import { + BoundingSphere, + Cartesian3, + Ellipsoid, + Event, + Intersect, + Occluder, + PerspectiveFrustum, +} from 'cesium'; +import { createWindStreamlines, windGridOf } from './drawStreamlines.js'; +import { createCesiumFields } from './drawFields.js'; +import { bakeWindStreamlines } from '../../layers/wind/streamlines.js'; + +const grid = () => ({ + nx: 4, + ny: 3, + lo1: -180, + la1: 90, + dx: 90, + dy: 90, + u: new Float32Array(12).fill(15), + v: new Float32Array(12), +}); +// The grid above as a field spec: 4 columns wrapping the globe, 3 rows. +const SPEC = Object.freeze({ + kind: 'windStreamlines', + id: 'wind', + u: new Float32Array(12).fill(15), + v: new Float32Array(12), + width: 4, + height: 3, + rectangle: { west: -180, south: -90, east: 180, north: 90 }, + pathBudget: 7200, + steps: 16, + style: { color: '#80c9e6', widthPx: 2.4 }, + heightM: 12000, +}); + +function harness() { + const members = new Set(); + let geometryBuilds = 0; + const spheres = []; + const visibility = { + horizon: () => true, + frustum: () => Intersect.INSIDE, + horizonTests: 0, + frustumTests: 0, + }; + let occluderBuilds = 0; + class Material { + constructor(options) { + this.uniforms = options.fabric.uniforms; + this.source = options.fabric.source; + } + destroy() { + assert.ok(!this.destroyed, 'owned resource destroyed once'); + this.destroyed = true; + } + } + class Appearance { + static VERTEX_FORMAT = {}; + constructor(options) { + Object.assign(this, options); + this.vertexShaderSource ??= + 'in vec3 position3DHigh; in vec3 position3DLow; void main() { gl_Position = vec4(0.0); v_st.s = st.s; }'; + } + } + class Polyline { + constructor(options) { + Object.assign(this, options); + } + static createGeometry(options) { + geometryBuilds++; + const st = new Float32Array(options.positions.length * 2); + for (let i = 0; i < options.positions.length; i++) + st[i * 2] = i / (options.positions.length - 1); + return { attributes: { st: { values: st } } }; + } + } + class Primitive { + constructor(options) { + Object.assign(this, options); + this.ready = true; + } + destroy() { + assert.ok(!this.destroyed, 'owned resource destroyed once'); + this.destroyed = true; + } + isDestroyed() { + return Boolean(this.destroyed); + } + } + const C = { + ComponentDatatype: { FLOAT: 5126 }, + GeometryInstanceAttribute: class { + constructor(options) { + Object.assign(this, options); + } + }, + Material, + PolylineMaterialAppearance: Appearance, + PolylineGeometry: Polyline, + Primitive, + GeometryInstance: class { + constructor(options) { + Object.assign(this, options); + } + }, + Cartesian3, + Ellipsoid, + Intersect, + BoundingSphere: class extends BoundingSphere { + static fromPoints(points) { + const sphere = BoundingSphere.fromPoints(points); + spheres.push({ sphere, points }); + return sphere; + } + }, + Occluder: class { + constructor(sphere, cameraPosition) { + occluderBuilds++; + this.cameraPosition = cameraPosition; + } + isBoundingSphereVisible(sphere) { + visibility.horizonTests++; + return visibility.horizon(sphere, this.cameraPosition); + } + }, + ArcType: { NONE: 0 }, + }; + const volume = { + computeVisibility(sphere) { + visibility.frustumTests++; + return visibility.frustum(sphere); + }, + }; + const frames = []; + const preRender = new Event(); + const postRender = new Event(); + let renders = 0; + const scene = { + preRender, + postRender, + requestRender() { + renders += 1; + }, + get renders() { + return renders; + }, + globe: { show: false }, + camera: { + positionWC: Cartesian3.fromDegrees(0, 0, 1e7), + positionCartographic: { height: 1e7 }, + directionWC: new Cartesian3(-1, 0, 0), + upWC: new Cartesian3(0, 0, 1), + frustum: { computeCullingVolume: () => volume }, + }, + primitives: { + add(item) { + members.add(item); + }, + remove(item) { + const removed = members.delete(item); + if (removed) item.destroy(); + return removed; + }, + }, + }; + return { + C, + scene, + members, + builds: () => geometryBuilds, + spheres, + visibility, + occluderBuilds: () => occluderBuilds, + frames, + make: (patch = {}) => + createWindStreamlines({ + scene, + cesium: C, + spec: { ...SPEC, ...patch }, + requestFrame: (cb) => { + frames.push(cb); + return frames.length; + }, + cancelFrame: (id) => { + frames[id - 1] = null; + }, + }), + /** One render: the frame events around it. */ + render() { + preRender.raiseEvent(); + postRender.raiseEvent(); + }, + }; +} +const field = () => ({ + nx: 4, + ny: 3, + lo1: -180, + la1: 90, + dx: 90, + dy: 90, + u: new Float32Array(12).fill(15), + v: new Float32Array(12), +}); + +test('the spec reads back as the wind grid it came from', () => { + const { u, v, ...rest } = windGridOf(SPEC); + const { u: gu, v: gv, ...want } = grid(); + assert.deepEqual(rest, want); + assert.deepEqual([...u], [...gu]); + const regional = windGridOf({ + ...SPEC, + rectangle: { west: -100, south: 20, east: -70, north: 50 }, + }); + assert.equal(regional.dx, 10, 'a regional grid does not wrap'); + assert.equal(regional.dy, 15); + const across = windGridOf({ + ...SPEC, + rectangle: { west: 170, south: 20, east: -170, north: 50 }, + }); + assert.equal(across.lo1, 170); + assert.equal(across.dx, 20 / 3, 'across the antimeridian it runs east'); +}); + +test('streamlines build native cells; the highlight moves without rebuilding', () => { + const h = harness(); + const field = h.make(); + assert.equal(h.members.size, 72); + const batch = [...h.members][0]; + assert.equal(batch.allowPicking, false); + assert.equal(batch.asynchronous, true); + assert.ok(batch.appearance.vertexShaderSource.includes('v_windFacing = dot')); + assert.ok( + batch.appearance.vertexShaderSource.includes( + 'czm_batchTable_windSeed(batchId)', + ), + ); + const { uniforms, source } = batch.appearance.material; + assert.ok(source.includes('smoothstep(0.0, 0.065, v_windFacing)')); + assert.ok(source.includes('mix(baseColor.rgb')); + assert.equal( + h.builds(), + 0, + 'expanded geometry is deferred to Cesium workers', + ); + const diagnostics = field.diagnostics(); + assert.ok(diagnostics.pathCount > 7000 && diagnostics.pathCount <= 7200); + assert.ok(diagnostics.vertexCount > 0); + assert.equal(diagnostics.cellCount, 72); + const instances = [...h.members].flatMap((p) => p.geometryInstances); + const baked = bakeWindStreamlines(grid()); + assert.equal(instances.length, baked.length); + const bySeed = new Map( + instances.map((i) => [i.attributes.windSeed.value[0], i]), + ); + for (const path of baked) + assert.deepEqual( + bySeed.get(path.seed).geometry.positions, + path.coordinates.map(([lon, lat]) => + Cartesian3.fromDegrees(lon, lat, 12000), + ), + ); + for (const instance of instances) assert.equal(instance.geometry.width, 2.4); + for (const cell of h.members) { + assert.equal(cell.appearance.material, batch.appearance.material); + assert.equal(cell.compressVertices, false); + assert.equal(cell.releaseGeometryInstances, true); + } + assert.equal(uniforms.ghostAlpha, 0.25); + assert.equal(uniforms.heightFade, 1); + assert.ok(Math.abs(uniforms.tipSpeed - 0.16) < 1e-12); + // A render culls the cells and starts the highlight on the page's frames. + h.render(); + assert.equal(h.frames.length, 1); + h.frames.at(-1)(1000); + const first = uniforms.phaseTime; + assert.ok(first > 0); + const asked = h.scene.renders; + h.frames.at(-1)(1010); + assert.equal(uniforms.phaseTime, first, 'at most 30 steps a second'); + assert.equal(h.scene.renders, asked, 'and no frame drawn between them'); + h.frames.at(-1)(1040); + assert.ok(Math.abs(uniforms.phaseTime - first - 0.04) < 1e-9); + assert.equal(h.scene.renders, asked + 1); + field.update({ paused: true }); + assert.equal(uniforms.ghostAlpha, 0.34, 'paused raises the ghost'); + const held = uniforms.phaseTime; + assert.equal(h.frames.at(-1), null, 'paused stops the frames'); + field.update({ paused: false, alpha: 0.5, style: { speedFactor: 2 } }); + assert.equal(uniforms.heightFade, 0.5); + assert.ok(Math.abs(uniforms.tipSpeed - 0.32) < 1e-12); + assert.equal(uniforms.phaseTime, held); + assert.equal(h.members.size, 72, 'style, alpha and pause never rebuild'); + field.dispose(); + assert.equal(h.members.size, 0); + assert.equal(h.scene.preRender.numberOfListeners, 0); + assert.equal(h.scene.postRender.numberOfListeners, 0); +}); + +test("streamlines tell 'drawn' once every cell is ready, never while hidden", () => { + const h = harness(); + const field = h.make(); + let drawn = 0; + field.on('drawn', () => (drawn += 1)); + const [batch] = h.members; + batch.ready = false; + h.render(); + h.render(); + assert.equal(drawn, 0, 'every cell must be ready'); + batch.ready = true; + h.render(); + assert.equal(drawn, 1); + h.render(); + assert.equal(drawn, 1); + field.show = false; + field.update({ alpha: 0.4 }); + h.render(); + h.render(); + assert.equal(drawn, 1, 'never while hidden'); + assert.equal(batch.show, false); + field.show = true; + h.render(); + h.render(); + assert.equal(drawn, 2, 'told once shown'); + field.update({ u: new Float32Array(12).fill(10) }); + assert.equal(batch.destroyed, true, 'a new grid traces again'); + h.render(); + h.render(); + assert.equal(drawn, 3); + field.dispose(); +}); + +test('a failed build is refused, holding nothing', () => { + const h = harness(); + const NativePrimitive = h.C.Primitive; + const built = []; + h.C.Primitive = class extends NativePrimitive { + constructor(options) { + if (built.length === 2) throw new Error('later cell failed'); + super(options); + built.push(this); + } + }; + assert.throws(() => h.make(), /later cell failed/); + assert.equal(h.members.size, 0); + for (const batch of built) { + assert.equal(batch.destroyed, true); + assert.equal(batch.appearance.material.destroyed, true); + } + assert.equal(h.scene.preRender.numberOfListeners, 0); +}); + +test('a grid no path runs through is refused, holding nothing', () => { + const h = harness(); + assert.throws( + () => h.make({ u: new Float32Array(12), v: new Float32Array(12) }), + /no wind streamlines/, + ); + assert.equal(h.members.size, 0); + assert.equal(h.scene.preRender.numberOfListeners, 0); +}); + +test('the Cesium fields draw wind streamlines under their id until disposed', () => { + const h = harness(); + const fields = createCesiumFields({ scene: h.scene, cesium: h.C }); + const field = fields.field({ ...SPEC }); + assert.ok(h.members.size > 0); + assert.equal(fields.has('wind'), true); + assert.throws(() => fields.field({ ...SPEC }), /is live/); + field.dispose(); + assert.equal(fields.has('wind'), false); + assert.equal(h.members.size, 0); + fields.field({ ...SPEC }); + fields.dispose(); + assert.equal(fields.has('wind'), false); + assert.equal(h.members.size, 0); +}); + +test('a grid short of the whole globe is refused, not drawn wrapped', () => { + const h = harness(); + for (const rectangle of [ + { west: -100, south: -90, east: 80, north: 90 }, + // Four columns over 300°: its samples nearly span the globe; it does not. + { west: -150, south: -90, east: 150, north: 90 }, + ]) + assert.throws(() => h.make({ rectangle }), /whole globe only/); + assert.equal(h.members.size, 0); + const across = h.make({ + rectangle: { west: 0, south: -90, east: -0.000000000001, north: 90 }, + }); + assert.ok(h.members.size > 0, 'a rectangle across the antimeridian wraps'); + across.dispose(); +}); + +test('a rebuild that fails draws nothing and is never told drawn', () => { + const reported = []; + const h = harness(); + const field = createWindStreamlines({ + scene: h.scene, + cesium: h.C, + spec: { ...SPEC }, + report: (error) => reported.push(error), + requestFrame: () => 1, + cancelFrame() {}, + }); + let drawn = 0; + field.on('drawn', () => (drawn += 1)); + h.render(); + h.render(); + assert.equal(drawn, 1); + const asked = h.scene.renders; + field.update({ u: new Float32Array(12), v: new Float32Array(12) }); + assert.equal(reported.length, 1); + assert.equal(h.members.size, 0); + h.render(); + h.render(); + assert.equal(drawn, 1, 'nothing drawn is never told'); + assert.ok(h.scene.renders - asked <= 1, 'and asks no frames for it'); + field.dispose(); +}); + +test('the highlight stops when hidden, transparent or out of view, and starts again', () => { + const h = harness(); + const field = h.make(); + const live = () => h.frames.filter(Boolean).length; + h.render(); + assert.equal(live(), 1); + field.show = false; + assert.equal(live(), 0, 'hidden'); + field.show = true; + h.render(); + assert.equal(live(), 1); + field.update({ alpha: 0 }); + assert.equal(live(), 0, 'transparent'); + field.update({ alpha: 1 }); + h.render(); + assert.equal(live(), 1); + h.visibility.horizon = () => false; + h.render(); + assert.equal(live(), 0, 'every cell behind the Earth'); + h.visibility.horizon = () => true; + h.render(); + assert.equal(live(), 1, 'the next render in view starts it'); + field.dispose(); + assert.equal(live(), 0, 'dispose cancels the frame it asked for'); +}); + +test('a hidden page stops the highlight; shown again, it starts afresh', () => { + const listeners = new Set(); + const document = globalThis.document; + const page = { + hidden: false, + addEventListener: (type, cb) => listeners.add(cb), + removeEventListener: (type, cb) => listeners.delete(cb), + }; + globalThis.document = page; + try { + const h = harness(); + const field = h.make(); + // Whether the frame asked for last is still pending. + const pending = () => h.frames.at(-1) !== null; + const { uniforms } = [...h.members][0].appearance.material; + h.render(); + h.frames.at(-1)(1000); + h.frames.at(-1)(1100); + const before = uniforms.phaseTime; + assert.ok(Math.abs(before - 1 / 60 - 0.1) < 1e-9, 'time passed moves it'); + h.frames.at(-1)(1400); + assert.ok( + Math.abs(uniforms.phaseTime - before - 0.3) < 1e-9, + 'a stall still moves it by the time passed', + ); + page.hidden = true; + for (const cb of listeners) cb(); + assert.equal(pending(), false, 'a hidden page asks no frames'); + page.hidden = false; + for (const cb of listeners) cb(); + assert.equal(pending(), true); + const shown = uniforms.phaseTime; + h.frames.at(-1)(60_000); + assert.ok(Math.abs(uniforms.phaseTime - shown - 1 / 60) < 1e-9); + field.dispose(); + assert.equal(listeners.size, 0); + } finally { + globalThis.document = document; + } +}); + +test('a scene not in 3D refuses streamlines', () => { + const h = harness(); + h.C.SceneMode = { SCENE3D: 3 }; + h.scene.mode = 2; + assert.throws(() => h.make(), /3D only/); +}); + +test('cell visibility combines horizon, frustum and alpha', () => { + const h = harness(); + const field = h.make(); + const batches = [...h.members]; + h.visibility.horizon = (sphere) => + h.spheres.findIndex((s) => s.sphere === sphere) % 2 === 0; + h.visibility.frustum = (sphere) => + h.spheres.findIndex((s) => s.sphere === sphere) % 3 === 0 + ? Intersect.INTERSECTING + : Intersect.OUTSIDE; + h.render(); + assert.equal(field.diagnostics().visibleCells, 12); + for (let i = 0; i < batches.length; i++) + assert.equal(batches[i].show, i % 6 === 0); + assert.equal(h.visibility.horizonTests, 72); + assert.equal(h.visibility.frustumTests, 36); + field.update({ alpha: 0 }); + h.render(); + assert.equal(field.diagnostics().visibleCells, 0); + for (const batch of batches) assert.equal(batch.show, false); + assert.equal(h.visibility.horizonTests, 72, 'alpha 0 tests nothing'); + assert.equal(h.occluderBuilds(), 1, 'the occluder is reused'); + field.dispose(); +}); + +test('real Cesium sphere culling hides the far hemisphere and a sky-facing view', () => { + const h = harness(); + h.C.Occluder = Occluder; + const field = h.make(); + const camera = h.scene.camera; + camera.frustum = new PerspectiveFrustum({ + fov: Math.PI / 3, + aspectRatio: 1.5, + near: 1, + far: 5e7, + }); + h.render(); + const facing = field.diagnostics().visibleCells; + assert.ok(facing > 0 && facing < 72); + for (let i = 0; i < h.spheres.length; i++) + if (h.spheres[i].sphere.center.x < -5e6) + assert.equal([...h.members][i].show, false); + camera.directionWC.x = 1; + h.render(); + assert.equal(field.diagnostics().visibleCells, 0); + field.dispose(); +}); diff --git a/src/render/cesium/harness.js b/src/render/cesium/harness.js index 53ded5cff..7b7c5e0d4 100644 --- a/src/render/cesium/harness.js +++ b/src/render/cesium/harness.js @@ -41,6 +41,7 @@ export const CESIUM_CHECKS = new Set([ 'draw.drawOrder', 'draw.drillPick', 'draw.field.rasterShell', + 'draw.field.windStreamlines', 'draw.icons.distance', 'draw.icons.update', 'draw.lines.depthFailDash', diff --git a/src/render/cesiumAllowList.json b/src/render/cesiumAllowList.json index 5b7efdead..0473f91a3 100644 --- a/src/render/cesiumAllowList.json +++ b/src/render/cesiumAllowList.json @@ -5,7 +5,6 @@ "src/app/scene.js", "src/app/viewer.js", "src/data/geoImportPins.js", - "src/layers/wind/gpuRendering.js", "src/layers/wind/relief.js", "src/layers/wind/rendering.js", "src/maps/catalog.js", diff --git a/src/render/conformance/checks/ports.js b/src/render/conformance/checks/ports.js index 450abc3d2..258fc71df 100644 --- a/src/render/conformance/checks/ports.js +++ b/src/render/conformance/checks/ports.js @@ -786,6 +786,64 @@ export function portChecks() { }, { capability: 'fields' }, ), + check( + 'draw.field.windStreamlines', + "streamlines' 'drawn' comes once per change, never while hidden", + async (h, r) => { + await overAustin(h, r, 2000000); + const width = 8; + const height = 5; + const errors = []; + const offError = r.on('error', (e) => errors.push(e)); + const field = r.draw.field({ + kind: 'windStreamlines', + id: 'conf:wind', + u: new Float32Array(width * height).fill(12), + v: new Float32Array(width * height).fill(4), + width, + height, + rectangle: { west: -180, south: -80, east: 180, north: 80 }, + pathBudget: 200, + steps: 8, + style: { color: '#80c9e6', widthPx: 2 }, + heightM: 12000, + alpha: 1, + }); + let drawnCount = 0; + const off = field.on('drawn', () => (drawnCount += 1)); + // Frames until 'drawn' has come `want` times, for at most 20 s. + const until = async (want) => { + const deadline = Date.now() + 20000; + while (drawnCount < want && Date.now() < deadline) + await drawn(h, r, 1); + }; + try { + await until(1); + equal(drawnCount, 1, 'drawn once made'); + await drawn(h, r, 4); + equal(drawnCount, 1, 'not again while nothing changes'); + field.update({ alpha: 0.5 }); + await until(2); + equal(drawnCount, 2, 'drawn after a new alpha'); + field.update({ paused: true }); + await until(3); + equal(drawnCount, 3, 'drawn once paused'); + field.show = false; + field.update({ alpha: 0.4 }); + await drawn(h, r, 6); + equal(drawnCount, 3, 'never while hidden'); + field.show = true; + await until(4); + equal(drawnCount, 4, 'drawn once shown again'); + deepEqual(errors, [], 'no errors'); + } finally { + off(); + offError(); + field.dispose(); + } + }, + { capability: 'fields' }, + ), check( 'draw.drawOrder', 'of sets drawn over depth, the higher draw order is on top and picked', From 2a26d13fff721fb3e105f68cebc9a3bb3fcf9a5a Mon Sep 17 00:00:00 2001 From: Sameh Khamis Date: Mon, 9 Nov 2026 08:13:04 -0800 Subject: [PATCH 3/3] render: wind relief is the globe port's hillshade; the wind layer no longer reaches Cesium The wind relief now asks the globe port for hillshade surface shading at 0.28 instead of building a globe material itself; the Cesium globe port draws the same view-directed shading, over terrain normals or the globe's curvature, and the unbound provider now lists surfaceShading. The wind layer's canvas flow, bounds, imagery fade and render requests go through the camera, frame and query ports, so src/layers/wind/rendering.js and relief.js leave the Cesium allow list. A refused shading request is taken back so it never shows after Wind is off, and a camera height that is not a number falls back as before. The application layers and standalone catalog entries no longer load the unbound factories themselves: a viewer with no renderer bound needs render/cesium/unbound loaded first. The contract and current-state docs say what the Cesium adapter's fields and surface shading do now. --- CHANGELOG.md | 8 + docs/CURRENT-STATE.md | 7 +- docs/RENDERER-CONTRACT.md | 8 +- src/layers/wind/relief.js | 115 +++++---------- src/layers/wind/relief.test.mjs | 168 ++++++++++----------- src/layers/wind/rendering.js | 225 +++++++++++++---------------- src/layers/wind/rendering.test.mjs | 78 +++++----- src/render/cesium/globe.js | 2 + src/render/cesiumAllowList.json | 2 - src/render/unboundCamera.test.mjs | 5 + 10 files changed, 294 insertions(+), 324 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 5f1d1211e..7bca0a38e 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -2,6 +2,14 @@ ## [Unreleased] +- `gods-eye-view/application/layers` and `gods-eye-view/standalone/catalog` + no longer reach Cesium: the weather shells and the wind layer's colour + shell and flow draw through the renderer's `draw.field` (`rasterShell` and + `windStreamlines`, which the Cesium renderer now draws), and the wind + relief is the globe port's `hillshade` surface shading. The flow animates + as before, and still falls back to the canvas where the renderer refuses + it. A viewer with no renderer bound needs + `gods-eye-view/render/cesium/unbound` loaded once first (samehkhamis). - `gods-eye-view/input` no longer reaches Cesium: the dispatcher takes its pointer events from the renderer's input port and its picks from the query port. A click's `hit`, `topHit`, `drawHit` and `drill()` hits, and diff --git a/docs/CURRENT-STATE.md b/docs/CURRENT-STATE.md index c4476d2bd..f765849d7 100644 --- a/docs/CURRENT-STATE.md +++ b/docs/CURRENT-STATE.md @@ -363,9 +363,10 @@ resources and subscriptions. The globe relief helper is enabled with Wind and released when Wind is disabled. It uses terrain vertex normals for view-directed shading, falling back to global globe-curvature shading when normals are unavailable; the fallback does not show local hillshade. Neither mode -adds elevation data or represents sunlight. Relief declines to replace an -existing globe material, restores the prior empty material only while still -owning it, and leaves later owners intact. +adds elevation data or represents sunlight. Relief is the globe port's +`hillshade` surface shading: the renderer never replaces a globe material +someone else holds (it waits until that one is gone), gives the globe back +when Wind is disabled, and leaves later owners intact. Source acquisition retains deadlines, body budgets, disconnect cancellation, per-model/field singleflight caching and one-minute failure backoff. Application catalog construction owns each instance. diff --git a/docs/RENDERER-CONTRACT.md b/docs/RENDERER-CONTRACT.md index 5cbaf5e09..2b8fee12b 100644 --- a/docs/RENDERER-CONTRACT.md +++ b/docs/RENDERER-CONTRACT.md @@ -65,8 +65,12 @@ optional, so a renderer written before it still conforms: one, and says how shells stack, blend and update. `FieldHandle.on('drawn')` says once per spec or `update` that it is drawn, never while hidden. These change `fields` itself rather than add to it, so the renderer follows - `fields` before must follow them; only the stub lists it, and the Cesium - adapter has no `fields` yet. + `fields` before must follow them. The Cesium adapter lists `fields` and + draws `rasterShell` and `windStreamlines`; it refuses `scalarRaster`. It + draws streamlines only over the whole globe: it reads the grid's samples + as points, the first column at `rectangle.west` and the first row at + `rectangle.north`, rows running south, and traces paths that wrap east + and west, so it refuses a grid short of 360° of longitude. - `ModulationSector` gains `radius` and `floor` and says what it modulates: icons, points and models dimmed toward `floor` outside the band, the map, lines and shapes as they are, picks unchanged. Its pass is named diff --git a/src/layers/wind/relief.js b/src/layers/wind/relief.js index 5d80e3b8d..3ef1cf721 100644 --- a/src/layers/wind/relief.js +++ b/src/layers/wind/relief.js @@ -1,98 +1,63 @@ -// View-directed display lighting over existing terrain normals. This does not -// represent the Sun, change terrain geometry, or supply missing elevation data. -function reliefSource(terrainNormals) { - const normal = terrainNormals - ? 'vec3 normal = normalize(materialInput.normalEC);' - : `vec3 worldPosition = (czm_inverseView * vec4(-materialInput.positionToEyeEC, 1.0)).xyz; - vec3 geodeticNormal = normalize(worldPosition * czm_ellipsoidInverseRadii * czm_ellipsoidInverseRadii); - vec3 normal = normalize(czm_viewRotation * geodeticNormal);`; - return ` -czm_material czm_getMaterial(czm_materialInput materialInput) -{ - czm_material material = czm_getDefaultMaterial(materialInput); - ${normal} - vec3 displayLight = normalize(vec3(-0.45, 0.55, 0.8)); - float shade = clamp((1.0 - dot(normal, displayLight)) * 0.32, 0.0, 0.28); - material.diffuse = vec3(0.0); - material.alpha = shade; - return material; -} -`; -} +import { findGlobe } from '../../render/rendererOf.js'; -/** Optional, exclusive globe-material owner; no animation or source acquisition. */ -export function createWindRelief({ cesium, getViewer } = {}) { +/** The darkest the relief shading gets, as an opacity. */ +export const WIND_RELIEF_STRENGTH = 0.28; + +/** + * View-directed display shading of the globe's relief while the wind layer + * shows: the globe port's `hillshade` surface shading (capability + * `surfaceShading`), over the terrain's own normals or, without them, the + * ellipsoid's curvature. It stands for no sun, changes no geometry and asks + * for no data. The renderer owns the material: it never takes one someone + * else holds, and gives it back when cleared. No animation or source + * acquisition. + */ +export function createWindRelief({ getViewer, globeOf = findGlobe } = {}) { + // The globe port shading for this layer, and the viewer it belongs to. let globe = null; - let scene = null; - let owned = null; - let previous = undefined; + let viewer = null; let destroyed = false; let reason = 'Not attached'; - let mode = null; const alive = (value) => value && !value.isDestroyed?.(); - const active = () => - Boolean(owned && alive(globe) && globe.material === owned); function clear() { - const changed = active(); - if (changed) globe.material = previous; - if (owned && !owned.isDestroyed?.()) owned.destroy?.(); - if (changed && alive(scene)) scene.requestRender?.(); - owned = null; - mode = null; + if (globe && alive(viewer)) globe.setSurfaceShading(null); globe = null; - scene = null; - previous = undefined; + viewer = null; reason = destroyed ? 'Destroyed' : 'Not attached'; } return { attach() { if (destroyed) return false; - const viewer = getViewer?.(); - const nextScene = alive(viewer) ? viewer.scene : null; - const nextGlobe = nextScene?.globe; - const nextMode = - nextGlobe?.terrainProvider?.hasVertexNormals === true - ? 'terrain relief' - : 'globe curvature'; - if (active() && globe === nextGlobe && mode === nextMode) return true; + const next = getViewer?.(); + const port = alive(next) ? globeOf(next) : null; + if (globe && globe === port) return true; clear(); - if (!alive(nextGlobe) || typeof cesium?.Material !== 'function') { + if (typeof port?.setSurfaceShading !== 'function') { reason = 'Globe material unavailable'; return false; } - if (nextGlobe.material != null) { - reason = 'Globe material already owned'; - return false; - } - // Cesium excludes normal-dependent materials without terrain normals. - // The fallback uses existing position/ellipsoid uniforms: curvature only, - // never an invented terrain normal or an additional provider request. try { - owned = new cesium.Material({ - fabric: { - type: - nextMode === 'terrain relief' - ? 'GEVWindTerrainRelief' - : 'GEVWindGlobeCurvature', - source: reliefSource(nextMode === 'terrain relief'), - }, - translucent: true, + port.setSurfaceShading({ + kind: 'hillshade', + strength: WIND_RELIEF_STRENGTH, }); - mode = nextMode; - globe = nextGlobe; - scene = nextScene; - previous = globe.material; - globe.material = owned; - scene.requestRender?.(); - reason = null; - return true; } catch { - clear(); + // The port may hold the request even though it could not draw it; + // take it back so it never shows up later, after Wind is off. + try { + port.setSurfaceShading(null); + } catch { + // Nothing was kept. + } reason = 'Relief material unavailable'; return false; } + globe = port; + viewer = next; + reason = null; + return true; }, clear, destroy() { @@ -102,11 +67,11 @@ export function createWindRelief({ cesium, getViewer } = {}) { }, getDiagnostics() { return { - active: active(), - reason: owned && !active() ? 'Globe material replaced' : reason, + active: globe !== null, + reason, lighting: 'View-directed display shading', - mode: active() ? mode : null, - maxOpacity: 0.28, + mode: globe ? 'hillshade' : null, + maxOpacity: WIND_RELIEF_STRENGTH, }; }, }; diff --git a/src/layers/wind/relief.test.mjs b/src/layers/wind/relief.test.mjs index 9e1b94b33..448aee21a 100644 --- a/src/layers/wind/relief.test.mjs +++ b/src/layers/wind/relief.test.mjs @@ -1,101 +1,103 @@ import test from 'node:test'; import assert from 'node:assert/strict'; -import { createWindRelief } from './relief.js'; +import { createWindRelief, WIND_RELIEF_STRENGTH } from './relief.js'; -function fixture({ material = undefined, normals = true } = {}) { - const materials = []; - class Material { - constructor(options) { - this.options = options; - this.destroyed = false; - materials.push(this); - } - isDestroyed() { - return this.destroyed; - } - destroy() { - assert.equal(this.destroyed, false); - this.destroyed = true; - } - } - let renders = 0; - const globe = { material, terrainProvider: { hasVertexNormals: normals } }; - const scene = { globe, requestRender: () => renders++ }; - const viewer = { scene }; - const relief = createWindRelief({ - cesium: { Material }, - getViewer: () => viewer, +// A viewer whose globe port records the shading it is asked for. +function fixture({ shading = true } = {}) { + const calls = []; + const port = (name) => ({ + name, + ...(shading + ? { + setSurfaceShading(next) { + calls.push([name, next]); + }, + } + : {}), }); - return { relief, globe, scene, viewer, materials, renders: () => renders }; + const ports = new Map(); + const viewer = { isDestroyed: () => false }; + ports.set(viewer, port('first')); + let current = viewer; + const relief = createWindRelief({ + getViewer: () => current, + globeOf: (given) => ports.get(given) ?? null, + }); + return { + relief, + calls, + viewer, + ports, + port, + use: (next) => (current = next), + }; } -test('relief acquires once and restores the exact prior empty material on clear', () => { - for (const material of [null, undefined]) { - const f = fixture({ material }); - f.globe.material = material; - assert.equal(f.relief.attach(), true); - assert.equal(f.relief.attach(), true); - assert.equal(f.materials.length, 1); - assert.equal(f.globe.material, f.materials[0]); - assert.equal(f.relief.getDiagnostics().active, true); - f.relief.clear(); - assert.equal(f.globe.material, material); - assert.equal(f.materials[0].destroyed, true); - assert.equal(f.renders(), 2); - f.relief.clear(); - assert.equal(f.renders(), 2); - assert.equal(f.relief.attach(), true); - f.relief.destroy(); - assert.equal(f.materials[1].destroyed, true); - assert.equal(f.relief.attach(), false); - } -}); - -test('pre-existing and replacement material owners are never overwritten', () => { - const other = { name: 'other-owner' }; - const f = fixture({ material: other }); - assert.equal(f.relief.attach(), false); - assert.equal(f.globe.material, other); - assert.equal(f.materials.length, 0); - f.globe.material = undefined; +test('relief asks the globe port for hillshade once and gives it back on clear', () => { + const f = fixture(); assert.equal(f.relief.attach(), true); - f.globe.material = other; - assert.equal(f.relief.getDiagnostics().reason, 'Globe material replaced'); + assert.equal(f.relief.attach(), true); + assert.deepEqual(f.calls, [ + ['first', { kind: 'hillshade', strength: WIND_RELIEF_STRENGTH }], + ]); + assert.equal(WIND_RELIEF_STRENGTH, 0.28); + assert.equal(f.relief.getDiagnostics().active, true); + assert.equal(f.relief.getDiagnostics().maxOpacity, 0.28); f.relief.clear(); - assert.equal(f.globe.material, other); - assert.equal(f.materials[0].destroyed, true); + assert.deepEqual(f.calls.at(-1), ['first', null]); + f.relief.clear(); + assert.equal(f.calls.length, 2, 'a second clear asks nothing'); + assert.equal(f.relief.getDiagnostics().active, false); + assert.equal(f.relief.attach(), true); + f.relief.destroy(); + assert.deepEqual(f.calls.at(-1), ['first', null]); assert.equal(f.relief.attach(), false); - f.relief.destroy(); - assert.equal(f.globe.material, other); + assert.equal(f.relief.getDiagnostics().reason, 'Destroyed'); }); -test('missing terrain normals uses curvature only and upgrades when normals exist', () => { - const f = fixture({ normals: false }); - assert.equal(f.relief.attach(), true); - assert.equal(f.relief.getDiagnostics().mode, 'globe curvature'); - const source = f.materials[0].options.fabric.source; - assert.doesNotMatch(source, /normalEC|slope/); - assert.match(source, /materialInput.positionToEyeEC/); - assert.match(source, /czm_ellipsoidInverseRadii/); - f.globe.terrainProvider.hasVertexNormals = true; - assert.equal(f.relief.attach(), true); - assert.equal(f.materials[0].destroyed, true); - assert.equal(f.relief.getDiagnostics().mode, 'terrain relief'); - assert.match(f.materials[1].options.fabric.source, /materialInput.normalEC/); - f.relief.destroy(); - assert.equal(f.globe.material, undefined); +test('a globe with no surface shading, or one that refuses it, is reported', () => { + const f = fixture({ shading: false }); + assert.equal(f.relief.attach(), false); + assert.equal(f.relief.getDiagnostics().reason, 'Globe material unavailable'); + const refusing = fixture(); + const asked = []; + refusing.ports.get(refusing.viewer).setSurfaceShading = (next) => { + asked.push(next); + if (next) throw new TypeError('no hillshade'); + }; + assert.equal(refusing.relief.attach(), false); + assert.equal( + refusing.relief.getDiagnostics().reason, + 'Relief material unavailable', + ); + assert.equal(refusing.relief.getDiagnostics().active, false); + assert.deepEqual( + asked.at(-1), + null, + 'a refused request is taken back so it never shows later', + ); }); -test('moving to a new viewer releases the old globe and owns only the new one', () => { +test('moving to a new viewer releases the old globe and shades only the new one', () => { const f = fixture(); f.relief.attach(); - const old = f.globe; - const next = { material: null, terrainProvider: { hasVertexNormals: true } }; - f.viewer.scene = { globe: next, requestRender() {} }; + const next = { isDestroyed: () => false }; + f.ports.set(next, f.port('second')); + f.use(next); assert.equal(f.relief.attach(), true); - assert.equal(old.material, undefined); - assert.equal(f.materials[0].destroyed, true); - assert.equal(next.material, f.materials[1]); + assert.deepEqual(f.calls, [ + ['first', { kind: 'hillshade', strength: 0.28 }], + ['first', null], + ['second', { kind: 'hillshade', strength: 0.28 }], + ]); f.relief.destroy(); - assert.equal(next.material, null); + assert.deepEqual(f.calls.at(-1), ['second', null]); +}); + +test('a destroyed viewer is never asked to give the shading back', () => { + const f = fixture(); + f.relief.attach(); + f.viewer.isDestroyed = () => true; + f.relief.clear(); + assert.equal(f.calls.length, 1); }); diff --git a/src/layers/wind/rendering.js b/src/layers/wind/rendering.js index 050bbf362..c18f931c4 100644 --- a/src/layers/wind/rendering.js +++ b/src/layers/wind/rendering.js @@ -1,16 +1,19 @@ -import * as Cesium from 'cesium'; -// The renderer drapes through `findGlobe`, and the layer's inspection marker -// reads `findQuery` and `findFrame`; a viewer with no renderer bound gets -// those ports from the factories these modules provide. -import '../../render/cesium/globe.js'; -import '../../render/cesium/camera.js'; import { followShellLift, + globeImageryHost, WEATHER_SHELL_HEIGHTS, } from '../weather/shellRendering.js'; import { createWindRelief } from './relief.js'; import { WEATHER_IMAGERY_Z } from '../weather/imageryOrder.js'; -import { findDraw, findGlobe } from '../../render/rendererOf.js'; +import { + canvasOf, + findCamera, + findDraw, + findFrame, + findGlobe, + findQuery, +} from '../../render/rendererOf.js'; +import { fromDegreesInto } from '../../geo/ellipsoid.js'; import { NO_IMAGERY_HOST } from '../weather/imageryHost.js'; import { msg } from '../../i18n/index.js'; import { createWindGpuRendering } from './gpuRendering.js'; @@ -67,7 +70,7 @@ let windShells = 0; /** The colour field as a raised shell over the whole globe, through the * draw port's raster-shell field; it rises with the camera. */ -function createWindShell(viewer, draw, texture, alpha) { +function createWindShell(viewer, draw, texture, alpha, ports) { const seq = (windShells += 1); const height = WEATHER_SHELL_HEIGHTS.wind; const field = draw.field({ @@ -85,10 +88,14 @@ function createWindShell(viewer, draw, texture, alpha) { drawn = true; owed = false; }); - const offLift = followShellLift(viewer, (liftM) => { - owed = true; - field.update({ liftM }); - }); + const offLift = followShellLift( + viewer, + (liftM) => { + owed = true; + field.update({ liftM }); + }, + ports, + ); return { setAlpha(value) { if (value === shownAlpha) return; @@ -118,7 +125,6 @@ function createWindShell(viewer, draw, texture, alpha) { /** Globe-projected surface flow plus one owned, static colour field: globe * imagery on the globe host, a raised shell on the 3D Tiles host. */ export function createWindRendering({ - cesium = Cesium, container, getViewer, getHost: hostOf, @@ -126,15 +132,13 @@ export function createWindRendering({ createGpuRendering = createWindGpuRendering, globeOf = findGlobe, drawOf = findDraw, + cameraOf = findCamera, + frameOf = findFrame, + queryOf = findQuery, onStatusChange, } = {}) { // The host the shell names, else the viewer's globe imagery. - const getHost = () => - hostOf?.() ?? { - collection: - getViewer?.()?.imageryLayers ?? getViewer?.()?.scene?.imageryLayers, - kind: 'globe', - }; + const getHost = () => hostOf?.() ?? globeImageryHost(getViewer?.()); let canvas = null; let context = null; let snapshot = null; @@ -163,16 +167,11 @@ export function createWindRendering({ let gpuActive = false; let reportedGpuReady = null; let gpuNarrow = false; - const relief = createWindRelief({ cesium, getViewer }); + const relief = createWindRelief({ getViewer, globeOf }); const signature = Array(8).fill(null); const wind = { u: 0, v: 0 }; const before = { lon: 0, lat: 0 }; - const world = - typeof cesium.Cartesian3 === 'function' ? new cesium.Cartesian3() : {}; - const screenA = - typeof cesium.Cartesian2 === 'function' ? new cesium.Cartesian2() : {}; - const screenB = - typeof cesium.Cartesian2 === 'function' ? new cesium.Cartesian2() : {}; + const world = { x: 0, y: 0, z: 0 }; const degree = Math.PI / 180; const hidden = () => globalThis.document?.hidden === true; const still = () => paused || reducedMotion; @@ -188,6 +187,19 @@ export function createWindRendering({ const viewer = getViewer?.(); return viewer && !viewer.isDestroyed?.() ? viewer : null; }; + const poseOf = (viewer) => cameraOf(viewer)?.pose?.() ?? null; + // The camera's height, or undefined where there is none (or the eye sits + // at the earth's centre and it is not a number). + const heightOf = (viewer) => { + const height = viewer ? poseOf(viewer)?.height : undefined; + return Number.isFinite(height) ? height : undefined; + }; + const requestRender = (viewer) => frameOf(viewer)?.requestRender?.('wind'); + // What a paint projects with: the query port and the eye's position. + const viewOf = (viewer) => ({ + query: queryOf(viewer), + eye: poseOf(viewer)?.position ?? null, + }); function cancel() { if (frame !== null) globalThis.cancelAnimationFrame(frame); @@ -211,10 +223,9 @@ export function createWindRendering({ function resize(viewer) { const ratio = Math.min(2, globalThis.devicePixelRatio || 1); - cssWidth = - viewer?.scene?.canvas?.clientWidth || container?.clientWidth || 1; - cssHeight = - viewer?.scene?.canvas?.clientHeight || container?.clientHeight || 1; + const surface = canvasOf(viewer); + cssWidth = surface?.clientWidth || container?.clientWidth || 1; + cssHeight = surface?.clientHeight || container?.clientHeight || 1; const width = Math.max(1, Math.floor(cssWidth * ratio)); const height = Math.max(1, Math.floor(cssHeight * ratio)); // Assigning even unchanged dimensions erases a real canvas. @@ -227,16 +238,16 @@ export function createWindRendering({ return true; } - function checkCamera(scene) { - const camera = scene.camera; - const position = camera?.positionWC; + function checkCamera(viewer) { + const pose = poseOf(viewer); + const position = pose?.position; const values = [ position?.x, position?.y, position?.z, - camera?.heading, - camera?.pitch, - camera?.roll, + pose?.heading, + pose?.pitch, + pose?.roll, cssWidth, cssHeight, ]; @@ -248,16 +259,17 @@ export function createWindRendering({ return changed; } - function updateBounds(scene) { + function updateBounds(viewer) { bounds = null; - if (!scene.camera?.computeViewRectangle || !cesium.Ellipsoid) return; + const camera = cameraOf(viewer); + if (!camera?.viewRectangle) return; try { - const rect = scene.camera.computeViewRectangle(cesium.Ellipsoid.WGS84); + const rect = camera.viewRectangle(); if (!rect) return; - const west = rect.west / degree; - let east = rect.east / degree; - const south = Math.max(-89, rect.south / degree); - const north = Math.min(89, rect.north / degree); + const west = rect.west; + let east = rect.east; + const south = Math.max(-89, rect.south); + const north = Math.min(89, rect.north); if (east < west) east += 360; if ( [west, east, south, north].every(Number.isFinite) && @@ -275,34 +287,12 @@ export function createWindRendering({ } } - function makeOccluder(scene) { - if ( - !cesium.EllipsoidalOccluder || - !cesium.Ellipsoid || - !scene.camera?.positionWC - ) + function project(view, lon, lat) { + if (!Number.isFinite(lon) || !Number.isFinite(lat) || !view.query) return null; - return new cesium.EllipsoidalOccluder( - cesium.Ellipsoid.WGS84, - scene.camera.positionWC, - ); - } - - function project(scene, occluder, lon, lat, result) { - if (!Number.isFinite(lon) || !Number.isFinite(lat)) return null; - const point = cesium.Cartesian3.fromDegrees( - lon, - lat, - 0, - cesium.Ellipsoid?.WGS84, - world, - ); - if (occluder && !occluder.isPointVisible(point)) return null; - const projected = cesium.SceneTransforms.worldToWindowCoordinates( - scene, - point, - result, - ); + const point = fromDegreesInto(lon, lat, 0, world); + if (view.eye && view.query.isOccluded?.(point)) return null; + const projected = view.query.project(point); if ( !projected || !Number.isFinite(projected.x) || @@ -310,7 +300,7 @@ export function createWindRendering({ ) return null; // A perspective surface normal dims the limb instead of accumulating a bright rim. - const camera = scene.camera?.positionWC; + const camera = view.eye; const dx = camera?.x - point.x; const dy = camera?.y - point.y; const dz = camera?.z - point.z; @@ -332,7 +322,7 @@ export function createWindRendering({ point.x <= cssWidth && point.y <= cssHeight; - function spawn(particle, scene, occluder) { + function spawn(particle, view) { for (let attempt = 0; attempt < 6; attempt++) { const west = bounds?.west ?? -180; const east = bounds?.east ?? 180; @@ -342,17 +332,16 @@ export function createWindRendering({ particle.lat = Math.asin(low + Math.random() * (high - low)) / degree; particle.age = 1 + Math.random() * 7; particle.life = 8 + Math.random() * 4; - if (inView(project(scene, occluder, particle.lon, particle.lat, screenA))) - return; + if (inView(project(view, particle.lon, particle.lat))) return; } } - function seed(scene, occluder) { + function seed(viewer, view = viewOf(viewer)) { const count = budget(); if (particles.length > count) particles.length = count; while (particles.length < count) particles.push({ lon: 0, lat: 0, age: 0, life: 10 }); - updateBounds(scene); - for (const particle of particles) spawn(particle, scene, occluder); + updateBounds(viewer); + for (const particle of particles) spawn(particle, view); } function removeImagery() { @@ -364,16 +353,15 @@ export function createWindRendering({ shell = null; imageryKind = null; } - function updateImageryFade(camera, settled = false) { + function updateImageryFade(height, settled = false) { // The tileset shell keeps the quantised move-end fade; globe imagery keeps // its smooth per-frame fade. if ( (!imagery && !shell) || - !camera?.positionCartographic || + !Number.isFinite(height) || (imageryKind === 'tileset' && !settled) ) return; - const height = camera.positionCartographic.height; const fade = !gpuActive ? 1 : height <= WIND_FIELD_FADE_LOW_METERS @@ -432,10 +420,11 @@ export function createWindRendering({ draw, texture, overlay === 'temperature' ? 1 : 0.85, + { cameraOf, frameOf }, ); imageryKind = kind; - updateImageryFade(viewer.scene.camera, true); - viewer.scene?.requestRender?.(); + updateImageryFade(heightOf(viewer), true); + requestRender(viewer); return; } imagery = globe.imagery.add({ @@ -449,11 +438,11 @@ export function createWindRendering({ // Temperature colors carry quantitative meaning; double transparency // blends orange heat into blue ocean and obscures useful gradients. imagery.alpha = overlay === 'temperature' ? 1 : 0.85; - if (gpuActive) updateImageryFade(viewer.scene.camera, true); + if (gpuActive) updateImageryFade(heightOf(viewer), true); imageryErrorRemove = imagery.on('tileError', () => { imageryError = msg('Globe field image unavailable'); }); - viewer.scene?.requestRender?.(); + requestRender(viewer); } catch { removeImagery(); imageryError = msg('Globe field image unavailable'); @@ -476,10 +465,10 @@ export function createWindRendering({ const show = kind !== 'none' && imagery?.alpha > 0; if (imagery && imagery.show !== show) { imagery.show = show; - viewerReady()?.scene?.requestRender?.(); + requestRender(viewerReady()); } if ((gpuActive || kind === 'tileset') && kind !== 'none') - updateImageryFade(viewerReady()?.scene?.camera, true); + updateImageryFade(heightOf(viewerReady()), true); if (kind === 'none') imageryError = NO_IMAGERY_HOST; else if (wasHidden) { imageryError = null; @@ -492,15 +481,15 @@ export function createWindRendering({ function viewChanged() { if (gpuActive) { const viewer = viewerReady(); - if (viewer) updateImageryFade(viewer.scene.camera); - const narrow = (viewer?.scene?.canvas?.clientWidth || 800) < 700; + if (viewer) updateImageryFade(heightOf(viewer)); + const narrow = (canvasOf(viewer)?.clientWidth || 800) < 700; let visibilityUpdated = false; if (running && field && !hidden() && narrow !== gpuNarrow) { gpuNarrow = narrow; gpuActive = gpu.setField(field); if (!gpuActive && viewer) { resize(viewer); - seed(viewer.scene, makeOccluder(viewer.scene)); + seed(viewer); } motionChanged(); visibilityUpdated = true; @@ -512,13 +501,13 @@ export function createWindRendering({ reportedGpuReady = ready; onStatusChange?.(); } - return; // Cesium projects persistent curves; only a responsive budget change rebuilds them. + return; // The renderer projects persistent curves; only a responsive budget change rebuilds them. } if (!running || !field || hidden() || !canvas) return; const viewer = viewerReady(); if (!viewer) return; const resized = resize(viewer); - if (resized || checkCamera(viewer.scene)) { + if (resized || checkCamera(viewer)) { cameraChanged = true; if (still()) paint(viewer, 0, true); else schedule(); @@ -533,7 +522,7 @@ export function createWindRendering({ if (!running || !field || hidden()) return; const viewer = viewerReady(); if (gpuActive) { - if (viewer) updateImageryFade(viewer.scene.camera); + if (viewer) updateImageryFade(heightOf(viewer)); if (viewer) gpu.updateVisibility(); return; } @@ -547,23 +536,18 @@ export function createWindRendering({ } function cameraSettled() { if (gpuActive || imageryKind === 'tileset') - updateImageryFade(viewerReady()?.scene?.camera, true); + updateImageryFade(heightOf(viewerReady()), true); cameraMoved(); } function cameraMoved() { viewChanged(); // A parked request-render scene may never run preRender until we wake it. if (gpuActive && running && field && !hidden()) - viewerReady()?.scene?.requestRender?.(); + requestRender(viewerReady()); } - function listenScene(event, callback) { - if (!event?.addEventListener) return; - const remove = event.addEventListener(callback); - removers.push( - typeof remove === 'function' - ? remove - : () => event.removeEventListener(callback), - ); + function listenPort(port, event, callback) { + const off = port?.on?.(event, () => callback()); + if (typeof off === 'function') removers.push(off); } function attachListeners() { if (removers.length) return; @@ -574,9 +558,9 @@ export function createWindRendering({ listen(globalThis, 'resize', cameraMoved); listen(eventTarget, 'gev:map-stack-changed', rehome); const viewer = viewerReady(); - const camera = viewer?.scene?.camera; - listenScene(viewer?.scene?.preRender, viewChanged); - listenScene(camera?.moveEnd, cameraSettled); + if (!viewer) return; + listenPort(frameOf(viewer), 'preRender', viewChanged); + listenPort(cameraOf(viewer), 'moveEnd', cameraSettled); } function detachListeners() { for (const remove of removers) remove(); @@ -585,16 +569,15 @@ export function createWindRendering({ } function paint(viewer, dt, staticFrame, fadeSeconds = dt) { - const scene = viewer.scene; const resized = resize(viewer); - const changed = checkCamera(scene) || cameraChanged || resized; - const occluder = makeOccluder(scene); + const changed = checkCamera(viewer) || cameraChanged || resized; + const view = viewOf(viewer); if (changed) { clearPixels(); - updateBounds(scene); + updateBounds(viewer); cameraChanged = false; } - if (particles.length !== budget()) seed(scene, occluder); + if (particles.length !== budget()) seed(viewer, view); if (staticFrame) clearPixels(); context.globalAlpha = 1; context.globalCompositeOperation = 'destination-out'; @@ -602,7 +585,7 @@ export function createWindRendering({ context.fillRect(0, 0, cssWidth, cssHeight); context.globalCompositeOperation = 'source-over'; context.lineCap = 'round'; - const cameraHeight = scene.camera?.positionCartographic?.height ?? 1e6; + const cameraHeight = heightOf(viewer) ?? 1e6; const speedScale = Math.max(0.002, Math.min(4000, cameraHeight / 400)); const advection = { speedScale }; // Stroke length is a display sample of the local field, not frame travel. @@ -616,27 +599,21 @@ export function createWindRendering({ advectParticle(particle, wind, dt, advection); particle.age += dt; } - let point = project(scene, occluder, particle.lon, particle.lat, screenB); + let point = project(view, particle.lon, particle.lat); if (changed && !inView(point)) { // Refill newly exposed regions while retaining world anchors still in view. - spawn(particle, scene, occluder); + spawn(particle, view); sampleWind(field, particle.lon, particle.lat, wind); - point = project(scene, occluder, particle.lon, particle.lat, screenB); + point = project(view, particle.lon, particle.lat); } if (particle.age > particle.life || !inView(point)) { - spawn(particle, scene, occluder); + spawn(particle, view); continue; } before.lon = particle.lon; before.lat = particle.lat; advectParticle(before, wind, -strokeSeconds, advection); - const previous = project( - scene, - occluder, - before.lon, - before.lat, - screenA, - ); + const previous = project(view, before.lon, before.lat); if (!inView(previous)) continue; const startX = previous.x; const startY = previous.y; @@ -735,7 +712,7 @@ export function createWindRendering({ ? { ...next.grid, u: next.u, v: next.v } : next; const viewer = viewerReady(); - const nextNarrow = (viewer?.scene?.canvas?.clientWidth || 800) < 700; + const nextNarrow = (canvasOf(viewer)?.clientWidth || 800) < 700; const reuseGeometry = gpuActive && gpuNarrow === nextNarrow && @@ -756,7 +733,7 @@ export function createWindRendering({ particles = []; if (viewer && !gpuActive) { resize(viewer); - seed(viewer.scene, makeOccluder(viewer.scene)); + seed(viewer); } installImagery(); relief.attach(); diff --git a/src/layers/wind/rendering.test.mjs b/src/layers/wind/rendering.test.mjs index 2006cecbc..0976da15e 100644 --- a/src/layers/wind/rendering.test.mjs +++ b/src/layers/wind/rendering.test.mjs @@ -1,7 +1,5 @@ import test from 'node:test'; import assert from 'node:assert/strict'; -import * as Cesium from 'cesium'; - import { createWindRendering } from './rendering.js'; import { NO_IMAGERY_HOST } from '../weather/imageryHost.js'; import { WEATHER_IMAGERY_Z } from '../weather/imageryOrder.js'; @@ -11,6 +9,7 @@ import { renderShells, } from '../weather/shellFixture.mjs'; import { createCesiumFields } from '../../render/cesium/drawFields.js'; +import { toLonLatH } from '../../geo/ellipsoid.js'; function event() { const listeners = new Set(); @@ -179,6 +178,7 @@ function harness({ const viewer = { container, imageryLayers, + canvas, scene: { canvas, camera: { @@ -200,40 +200,48 @@ function harness({ isDestroyed: () => false, }; const shellCesium = shell ? createShellCesium() : null; - const cesium = { - ...(shellCesium ?? {}), - GeographicTilingScheme: Cesium.GeographicTilingScheme, - Credit: Cesium.Credit, - Event: Cesium.Event, - Cartesian3: { fromDegrees: (lon, lat) => ({ lon, lat }) }, - Ellipsoid: { WGS84: {} }, - Rectangle: { MAX_VALUE: {} }, - EllipsoidalOccluder: class { - isPointVisible() { - return !occluded; - } - }, - SceneTransforms: { - worldToWindowCoordinates: projected ?? (() => ({ x: 100, y: 100 })), - }, - SingleTileImageryProvider: class { - constructor(options) { - this.options = options; - this.errorEvent = event(); - } + // The camera, frame and query ports over the doubles above, read live. + const cameraPort = { + pose() { + const camera = viewer.scene.camera; + return { + position: camera.positionWC, + heading: camera.heading, + pitch: camera.pitch, + roll: camera.roll, + height: camera.positionCartographic?.height, + }; }, + viewRectangle: () => viewer.scene.camera.viewRectangle?.() ?? null, + on: (name, cb) => + name === 'moveEnd' + ? viewer.scene.camera.moveEnd.addEventListener(cb) + : () => {}, + }; + const framePort = { + on: (name, cb) => + name === 'preRender' ? preRender.addEventListener(cb) : () => {}, + requestRender: () => viewer.scene.requestRender(), + }; + // Projections see the point as degrees, as the doubles above were written. + const project = projected ?? (() => ({ x: 100, y: 100 })); + const queryPort = { + isOccluded: () => occluded, + project: (point) => project(viewer.scene, toLonLatH(point)), }; const fields = shellCesium ? createCesiumFields({ scene: viewer.scene, cesium: shellCesium }) : null; const draw = fields && { field: (spec) => fields.field(spec) }; const rendering = createWindRendering({ - cesium, container, getViewer: () => viewer, globeOf: (given) => (given === viewer ? globe : null), // The Cesium draw port's raster shells, over the doubles. drawOf: (given) => (given === viewer ? draw : null), + cameraOf: (given) => (given === viewer ? cameraPort : null), + frameOf: (given) => (given === viewer ? framePort : null), + queryOf: (given) => (given === viewer ? queryPort : null), createGpuRendering, onStatusChange, getHost, @@ -254,7 +262,7 @@ function harness({ motion, preRender, viewer, - cesium: shellCesium ?? cesium, + cesium: shellCesium, imagery, removed, primitives: () => shellScene?.primitives.items ?? [], @@ -595,11 +603,11 @@ test('a large camera move immediately refills the newly visible region', () => { y: 300 + point.lat * 20, }), }); - h.viewer.scene.camera.computeViewRectangle = () => ({ - west: ((center - 10) * Math.PI) / 180, - east: ((center + 10) * Math.PI) / 180, - south: (-10 * Math.PI) / 180, - north: (10 * Math.PI) / 180, + h.viewer.scene.camera.viewRectangle = () => ({ + west: center - 10, + east: center + 10, + south: -10, + north: 10, }); h.rendering.attach(); h.rendering.setField(FIELD); @@ -624,11 +632,11 @@ test('world-anchored wind glyphs remain readable at low FPS without accelerating y: 300 + point.lat * 20, }), }); - h.viewer.scene.camera.computeViewRectangle = () => ({ - west: (-5 * Math.PI) / 180, - east: (5 * Math.PI) / 180, - south: (-0.001 * Math.PI) / 180, - north: (0.001 * Math.PI) / 180, + h.viewer.scene.camera.viewRectangle = () => ({ + west: -5, + east: 5, + south: -0.001, + north: 0.001, }); h.rendering.attach(); h.rendering.setField(FIELD); diff --git a/src/render/cesium/globe.js b/src/render/cesium/globe.js index 8f59ccd12..00ef48dd7 100644 --- a/src/render/cesium/globe.js +++ b/src/render/cesium/globe.js @@ -639,6 +639,8 @@ provideUnboundGlobe((viewer) => { ]); if (typeof viewer.scene.globe?.show === 'boolean') capabilities.add('globeVisibility'); + // The globe's surface shading needs a globe to shade. + if (viewer.scene.globe) capabilities.add('surfaceShading'); const { port, dispose } = createCesiumGlobe(viewer, { capabilities, requestRender: () => viewer.scene.requestRender?.(), diff --git a/src/render/cesiumAllowList.json b/src/render/cesiumAllowList.json index 0473f91a3..3a7a147d0 100644 --- a/src/render/cesiumAllowList.json +++ b/src/render/cesiumAllowList.json @@ -5,8 +5,6 @@ "src/app/scene.js", "src/app/viewer.js", "src/data/geoImportPins.js", - "src/layers/wind/relief.js", - "src/layers/wind/rendering.js", "src/maps/catalog.js", "src/maps/controller.js", "src/maps/google3d.js", diff --git a/src/render/unboundCamera.test.mjs b/src/render/unboundCamera.test.mjs index 808235462..67a73aaf7 100644 --- a/src/render/unboundCamera.test.mjs +++ b/src/render/unboundCamera.test.mjs @@ -133,6 +133,11 @@ const DRAW_FROM_CALLER = new Set([ // It configures the sources of layers, the traffic layer's among them, // that draw and read the surface through the ports alone. './application/sources', + // The layer catalog and the standalone catalog over it: their layers, the + // weather shells and the wind flow and relief among them, draw, read the + // eye and shade the globe through the ports alone. + './application/layers', + './standalone/catalog', ]); /**