diff --git a/changelog.d/1894-line-time-window.md b/changelog.d/1894-line-time-window.md new file mode 100644 index 0000000000..83136a72a7 --- /dev/null +++ b/changelog.d/1894-line-time-window.md @@ -0,0 +1,5 @@ +- A line can show only the part of it within a span of the scene clock + (`LineAgeFade.showMs`, capability `lineTimeWindow`): the renderer cuts it by + time on the GPU as the clock moves, so a moving trail can be sent once as + its whole track; the Cesium renderer draws it, draped or not (samehkhamis, + #1894). diff --git a/docs/RENDERER-CONTRACT.md b/docs/RENDERER-CONTRACT.md index 960419e248..9ab8023f7d 100644 --- a/docs/RENDERER-CONTRACT.md +++ b/docs/RENDERER-CONTRACT.md @@ -139,6 +139,16 @@ optional: along their length, others per vertex), and an undraped one moves and recolours in place in its polyline collection. The check `draw.lines.ageFade` covers it, draped and not, narrowed too. +- `LineAgeFade.showMs` (capability `lineTimeWindow`) draws only the part of + an aged line within `showMs` of the scene clock: where its time, running + evenly between positions as the fade's does, is after now or before + `now - showMs`, it is not drawn (nor picked), cut there along the line, + not at a position. The cut follows `frame.setTime` as the fade does, so a + moving object's trail can be its whole track, sent once and drawn from + `showMs` ago up to where the object is now; `Infinity` cuts at now alone. + A renderer without the capability draws the whole line. The Cesium port + lists it with `lineAgeFade` and discards by time in the same material; + the check `draw.lines.timeWindow` covers it, draped and not. - A solid line's `outline.widthPx` is the outline's whole width, half on each side, inside the line's own width: an 8 px line with a 4 px outline is 2 px of outline, 4 px of colour and 2 px of outline, as Cesium draws diff --git a/src/render/cesium/draw.js b/src/render/cesium/draw.js index b5fb61f450..4be3e523fb 100644 --- a/src/render/cesium/draw.js +++ b/src/render/cesium/draw.js @@ -431,7 +431,9 @@ const AGE_TEXTURE_WIDTH = 1024; * its recency eases the alpha (smoothstep to `ageAlphaFloor`, recency * squared to `ageSquaredFloor` where that is not negative) and the width * (to `ageWidthFloor` of it, about its middle: outside it is discarded, so - * it neither draws nor picks). + * it neither draws nor picks). With a window (`ageShow`, `LineAgeFade.showMs`, + * seconds; negative, no older bound; 0, none) a fragment whose time is after + * now, or older than the window, is discarded too. */ const AGE_SOURCE = ` vec4 drawAgeTexel(float i) { @@ -462,6 +464,8 @@ czm_material czm_getMaterial(czm_materialInput materialInput) { u = clamp(f - lo, 0.0, 1.0); } float when = mix(drawAgeTexel(lo).g, drawAgeTexel(hi).g, u); + if (ageShow != 0.0 && (when > ageNow || (ageShow > 0.0 && ageNow - when > ageShow))) + discard; float recency = 1.0 - clamp((ageNow - when) / ageWindow, 0.0, 1.0); float fade = mix(ageAlphaFloor, 1.0, smoothstep(0.0, 1.0, recency)); if (ageSquaredFloor >= 0.0) @@ -485,12 +489,20 @@ czm_material czm_getMaterial(czm_materialInput materialInput) { * takes the rest evenly along its texture; `byLength`, the points lie along * it by their distance over the ellipsoid, as a ground polyline's texture * runs. `base` is the newest time, so the times a texel holds are small. + * `windowed`, the line draws only within its `showMs` of now (`ageShow`). * @param {Array<{x: number, y: number, z: number}>} points * @param {ArrayLike} times Epoch ms, one a point. * @param {import('../contract/draw').LineAgeFade} fade * @param {boolean} [byLength] + * @param {boolean} [windowed] */ -export function lineAgeData(points, times, fade, byLength = false) { +export function lineAgeData( + points, + times, + fade, + byLength = false, + windowed = false, +) { let kept = Array.from(times); let along = points; if (!byLength) { @@ -549,13 +561,23 @@ export function lineAgeData(points, times, fade, byLength = false) { ageAlphaFloor: fade.alphaFloor, ageSquaredFloor: fade.squaredAlphaFloor ?? -1, ageWidthFloor: fade.widthFloor ?? 1, + ageShow: showUniform(windowed ? fade.showMs : undefined), }, }; } +/** + * A window's `ageShow` uniform: its seconds; -1 for an endless one, cut at + * now alone; 0 for none. + * @param {number|undefined} showMs + */ +const showUniform = (showMs) => + showMs === undefined ? 0 : Number.isFinite(showMs) ? showMs / 1000 : -1; + /** * A line's `ageFade`, checked: one finite time a position, over a positive - * window, its floors from 0 to 1. Refused otherwise. + * window, its floors from 0 to 1, and a `showMs` positive where it has one. + * Refused otherwise. * @param {import('../contract/draw').LineItem} item */ function checkAgeFade(item) { @@ -573,10 +595,11 @@ function checkAgeFade(item) { !(fade.windowMs > 0 && Number.isFinite(fade.windowMs)) || !(fade.alphaFloor >= 0 && fade.alphaFloor <= 1) || !floor(fade.squaredAlphaFloor) || - !floor(fade.widthFloor) + !floor(fade.widthFloor) || + !(fade.showMs === undefined || fade.showMs > 0) ) throw new TypeError( - 'a line fades with one finite time a position, over a positive window, with floors from 0 to 1', + 'a line fades with one finite time a position, over a positive window, with floors from 0 to 1, shown over a positive span', ); } @@ -658,6 +681,8 @@ export function createCesiumDraw({ const sets = new Map(); // Lines fade with the age of their points (`LineItem.ageFade`). const ageFades = capabilities.has('lineAgeFade'); + // And draw only within a span of the scene clock (`LineAgeFade.showMs`). + const timeWindows = ageFades && capabilities.has('lineTimeWindow'); // Fields share the sets' ids. const fieldPart = createCesiumFields({ scene, @@ -2824,6 +2849,7 @@ export function createCesiumDraw({ times, item.ageFade, item.mode === 'draped' || item.overlaid === true, + timeWindows, ); } @@ -3607,6 +3633,7 @@ export function createCesiumDraw({ item.ageFade.alphaFloor, item.ageFade.squaredAlphaFloor, item.ageFade.widthFloor, + showUniform(timeWindows ? item.ageFade.showMs : undefined), ] : null, ]); @@ -3637,7 +3664,8 @@ export function createCesiumDraw({ x.windowMs === y.windowMs && x.alphaFloor === y.alphaFloor && x.squaredAlphaFloor === y.squaredAlphaFloor && - x.widthFloor === y.widthFloor + x.widthFloor === y.widthFloor && + (!timeWindows || x.showMs === y.showMs) ); }; diff --git a/src/render/cesium/drawLineAges.test.mjs b/src/render/cesium/drawLineAges.test.mjs index a2769da0fc..5a92233d24 100644 --- a/src/render/cesium/drawLineAges.test.mjs +++ b/src/render/cesium/drawLineAges.test.mjs @@ -116,9 +116,27 @@ test('a polyline’s age texels: a point at the place of the one before it is dr ageAlphaFloor: 0.06, ageSquaredFloor: 0.14, ageWidthFloor: 1, + ageShow: 0, }); }); +test('a windowed line’s age texels carry its span, in seconds; an endless one cuts at now alone', () => { + const points = along(2); + const fade = (showMs) => ({ + times: [], + windowMs: 30_000, + alphaFloor: 0.06, + showMs, + }); + const at = (showMs, windowed = true) => + lineAgeData(points, [T0, T0 + 1000], fade(showMs), false, windowed).uniforms + .ageShow; + assert.equal(at(45_000), 45); + assert.equal(at(Infinity), -1); + assert.equal(at(undefined), 0, 'no span, no cut'); + assert.equal(at(45_000, false), 0, 'not cut where the port does not'); +}); + test('a draped line’s age texels lie along it by distance, and a long line takes more rows', () => { const points = [ Cesium.Cartesian3.fromDegrees(0, 0), @@ -298,6 +316,49 @@ test('an aged line built anew lets its old material go once its primitive is gon void scene; }); +test('a windowed line is cut on the scene clock: time passing changes its material, never its line', () => { + const { part, scene, frameAt } = agedDraw(fakeScene(), [ + 'lineAgeFade', + 'lineTimeWindow', + ]); + const set = part.port.lines({ id: 'trails' }); + // A whole track, an hour of it, shown over its last minute. + const positions = along(61); + const times = positions.map((_, i) => T0 + i * 60_000); + set.set([trail(positions, times, { alphaFloor: 1, showMs: 60_000 })]); + const polylines = collectionOf(scene); + const polyline = polylines.get(0); + const material = polyline.material; + assert.equal(material.type, 'DrawAgedLine_solid'); + assert.equal(material.uniforms.ageShow, 60); + assert.equal(material.uniforms.ageCount, 61); + const before = polyline.positions; + for (let k = 1; k <= 120; k++) { + frameAt(T0 + k * 30_000); + assert.equal( + material.uniforms.ageNow, + (k * 30_000 - 3_600_000) / 1000, + `seconds after its newest point, frame ${k}`, + ); + } + assert.equal(collectionOf(scene), polylines, 'the same collection'); + assert.equal(polylines.get(0), polyline, 'the same line'); + assert.equal(polyline.material, material, 'the same material'); + assert.equal(polyline.positions, before, 'its points untouched'); + // A new span is a new look: drawn anew, with it. + set.upsert([trail(positions, times, { alphaFloor: 1, showMs: 120_000 })]); + assert.equal(collectionOf(scene).get(0).material.uniforms.ageShow, 120); +}); + +test('without the window’s capability a line ignores its span and draws whole', () => { + const { part, scene } = agedDraw(); + const set = part.port.lines({ id: 'trails' }); + set.set([trail(along(3), [T0, T0 + 1, T0 + 2], { showMs: 60_000 })]); + const material = collectionOf(scene).get(0).material; + assert.equal(material.type, 'DrawAgedLine_solid', 'still faded'); + assert.equal(material.uniforms.ageShow, 0, 'never cut'); +}); + test('without the capability a line ignores its age fade; with it a bad fade is refused', () => { const plain = agedDraw(fakeScene(), []); const lines = plain.part.port.lines({ id: 'trails' }); @@ -322,5 +383,11 @@ test('without the capability a line ignores its age fade; with it a bad fade is TypeError, 'floors from 0 to 1', ); + for (const showMs of [0, -1, Number.NaN]) + assert.throws( + () => set.set([trail(along(2), [T0, T0], { showMs })]), + TypeError, + 'a positive span', + ); assert.equal(set.size(), 0, 'nothing changed'); }); diff --git a/src/render/cesium/harness.js b/src/render/cesium/harness.js index 472d4f4595..d1aa061509 100644 --- a/src/render/cesium/harness.js +++ b/src/render/cesium/harness.js @@ -73,6 +73,7 @@ export const CESIUM_CHECKS = new Set([ 'draw.lines.split', 'draw.lines.outlineDraped', 'draw.lines.ageFade', + 'draw.lines.timeWindow', 'draw.lines.segments', 'draw.lines.segmentStyles', 'draw.sets.blend', diff --git a/src/render/cesium/ports.js b/src/render/cesium/ports.js index 491f278cf6..12ed24188d 100644 --- a/src/render/cesium/ports.js +++ b/src/render/cesium/ports.js @@ -85,7 +85,10 @@ export function cesiumCapabilities(scene, only) { 'fields', // Lines faded with age in their material, from a floating-point // texture of their points' times (`draw.js`). - ...(scene?.context?.floatingPointTexture ? ['lineAgeFade'] : []), + // And cut by time there, within a span of the scene clock. + ...(scene?.context?.floatingPointTexture + ? ['lineAgeFade', 'lineTimeWindow'] + : []), 'followFrame', 'pointVisibility', // Cesium's AUTODETECT tracking frame (`follow.js`). diff --git a/src/render/conformance/checks/ports.js b/src/render/conformance/checks/ports.js index f167082aad..2ce9e46746 100644 --- a/src/render/conformance/checks/ports.js +++ b/src/render/conformance/checks/ports.js @@ -3546,6 +3546,87 @@ export function portChecks() { }, { capability: 'lineAgeFade' }, ), + check( + 'draw.lines.timeWindow', + 'a line, draped or not, draws only its part within a span of scene time, cut as the time moves on, without being sent again', + async (h, r) => { + if (h.pixels === false) + return { skip: 'this harness reads no drawn pixels' }; + await overAustin(h, r); + const t0 = Date.UTC(2026, 0, 1, 18); + r.frame.setTime(t0); + // Off the row under the camera, where a ground line can leave a gap. + const at = (dLon, dLat, height) => + h.toEcef({ lon: AUSTIN.lon + dLon, lat: AUSTIN.lat + dLat, height }); + const lines = r.draw.lines({ id: 'conf:line-time-window' }); + // West to east over two minutes, t0 at its middle; shown over the + // last 30 s, unfaded. + const line = (id, dLat, mode) => ({ + id, + positions: [ + at(-0.004, dLat, mode === 'draped' ? 0 : 20), + at(0.004, dLat, mode === 'draped' ? 0 : 20), + ], + widthPx: 16, + mode, + style: { kind: 'solid', color: [0, 1, 0, 1] }, + ageFade: { + times: [t0 - 60_000, t0 + 60_000], + windowMs: 60_000, + alphaFloor: 1, + showMs: 30_000, + }, + }); + lines.set([line('air', 0.002, '3d'), line('ground', -0.002, 'draped')]); + // Whether the line at `dLon` is drawn green there, strongly. + const green = (dLon, dLat) => { + r.frame.renderNow(); + const s = r.query.project(at(dLon, dLat, dLat > 0 ? 20 : 0)); + const image = r.readPixels({ + crop: { + x: Math.round(s.x), + y: Math.round(s.y), + width: 1, + height: 1, + }, + }); + const [red, g, blue] = image.data; + return g > red + 80 && g > blue + 80; + }; + try { + await drawn(h, r); + await settled(r); + await drawn(h, r); + for (const [what, dLat] of [ + ['3d', 0.002], + ['draped', -0.002], + ]) { + // At t0 it shows from 30 s ago (a quarter along) to now (half). + ok(green(-0.001, dLat), `${what}: drawn within the span`); + ok(!green(0.002, dLat), `${what}: not drawn after now`); + ok(!green(-0.0035, dLat), `${what}: not drawn before the span`); + } + // 40 s on, it shows from 10 s to 40 s after t0. + r.frame.setTime(t0 + 40_000); + await drawn(h, r); + for (const [what, dLat] of [ + ['3d', 0.002], + ['draped', -0.002], + ]) { + ok(green(0.002, dLat), `${what}: drawn where now reached`); + ok(!green(-0.001, dLat), `${what}: cut as it grew old`); + } + r.frame.setTime(t0); + await drawn(h, r); + ok(green(-0.001, 0.002), '3d: drawn again back at t0'); + ok(!green(0.002, -0.002), 'draped: cut again back at t0'); + equal(lines.size(), 2, 'never sent again'); + } finally { + lines.dispose(); + } + }, + { capability: 'lineTimeWindow' }, + ), check( 'draw.lines.segments', 'a draped line takes segment colours and shows, changed every frame in place, without stopping the frame or picks', diff --git a/src/render/contract/common.d.ts b/src/render/contract/common.d.ts index 0c1153d830..f833be34f4 100644 --- a/src/render/contract/common.d.ts +++ b/src/render/contract/common.d.ts @@ -209,6 +209,8 @@ export type Capability = | 'courseGlide' /** Lines that fade with the age of their points (`LineItem.ageFade`). */ | 'lineAgeFade' + /** Lines drawn only within a span of the scene clock (`LineAgeFade.showMs`). */ + | 'lineTimeWindow' /** Screen-space clustering of icons. */ | 'cluster' /** Post-processing styles. */ diff --git a/src/render/contract/draw.d.ts b/src/render/contract/draw.d.ts index 29139795da..419a3152cb 100644 --- a/src/render/contract/draw.d.ts +++ b/src/render/contract/draw.d.ts @@ -309,6 +309,14 @@ export type LineStyle = * wide, about its path. A point at or past the window draws at the floors, a * point at or after now at full strength. New `times` with new positions are * an ordinary update. + * + * `lineTimeWindow`: with `showMs`, only the part of the line within `showMs` + * of now is drawn, cut along it where its interpolated time crosses: parts + * whose time is after now, or before `now - showMs`, are not drawn (nor + * picked). The cut follows the scene clock as the fade does, so a moving + * object's trail can be its whole track, sent once: drawn from `showMs` ago + * up to where the object is now. A renderer without the capability ignores + * `showMs` and draws the whole line. */ export interface LineAgeFade { /** Each position's time, epoch ms on the scene clock: one per position. */ @@ -321,6 +329,12 @@ export interface LineAgeFade { squaredAlphaFloor?: number; /** A fully aged point's width multiplier, 0..1 [1, no narrowing]. */ widthFloor?: number; + /** + * `lineTimeWindow`: draw only the part of the line from `showMs` before + * now up to now, ms; positive (`Infinity`: up to now, however old). + * [absent: the whole line] + */ + showMs?: number; } export interface LineItem { diff --git a/src/render/contract/index.js b/src/render/contract/index.js index 66ec77688f..718a07b547 100644 --- a/src/render/contract/index.js +++ b/src/render/contract/index.js @@ -42,6 +42,7 @@ export const CAPABILITIES = Object.freeze([ 'fields', 'courseGlide', 'lineAgeFade', + 'lineTimeWindow', 'cluster', 'styles', 'bloom', diff --git a/src/render/stub/stub.test.mjs b/src/render/stub/stub.test.mjs index 5965124fdc..d87972b8b9 100644 --- a/src/render/stub/stub.test.mjs +++ b/src/render/stub/stub.test.mjs @@ -20,7 +20,7 @@ test('the stub passes the conformance suite', async () => { .filter((r) => r.status === 'skip') .map((r) => r.id); // It draws only models into pixels, so the sweep's, a lit shape's, a line outline's, a - // split line's, a draped outlined line's, an aged line's and the blends' (over a drawn shape), video tiles', the weather's pixels (drawn, and by scene time) and an encoded capture go unread; its camera takes no user gestures: the drag and wheel scripts are for a + // split line's, a draped outlined line's, an aged line's, a time-windowed line's and the blends' (over a drawn shape), video tiles', the weather's pixels (drawn, and by scene time) and an encoded capture go unread; its camera takes no user gestures: the drag and wheel scripts are for a // camera that does (a controller over it, say). assert.deepEqual(skipped, [ 'effects.screenModulation.pixels', @@ -30,6 +30,7 @@ test('the stub passes the conformance suite', async () => { 'draw.lines.split', 'draw.lines.outlineDraped', 'draw.lines.ageFade', + 'draw.lines.timeWindow', 'draw.models.blend', 'draw.models.paint', 'globe.imagery.video',