From e4caf5d3afcb40041cfa6b167b4fda7bb9b393c5 Mon Sep 17 00:00:00 2001 From: Sameh Khamis Date: Sat, 21 Nov 2026 07:45:43 -0800 Subject: [PATCH] A line can show only the part of it within a time span of the scene clock (#1894) * A line can show only the part of it within a time span of the scene clock LineAgeFade.showMs (capability lineTimeWindow) draws only the part of an aged line whose time, interpolated along it, lies between showMs before the scene clock and the clock itself, cut as the clock moves without the line being sent again. A moving trail can then be sent once as its whole track. The Cesium port discards by time in its aged line material, draped or not, and the conformance check draw.lines.timeWindow pins it. Without showMs the fade is unchanged. * Changelog for line time window (#1894) --- changelog.d/1894-line-time-window.md | 5 ++ docs/RENDERER-CONTRACT.md | 10 +++ src/render/cesium/draw.js | 40 ++++++++++-- src/render/cesium/drawLineAges.test.mjs | 67 ++++++++++++++++++++ src/render/cesium/harness.js | 1 + src/render/cesium/ports.js | 5 +- src/render/conformance/checks/ports.js | 81 +++++++++++++++++++++++++ src/render/contract/common.d.ts | 2 + src/render/contract/draw.d.ts | 14 +++++ src/render/contract/index.js | 1 + src/render/stub/stub.test.mjs | 3 +- 11 files changed, 221 insertions(+), 8 deletions(-) create mode 100644 changelog.d/1894-line-time-window.md 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',