diff --git a/changelog.d/1892-line-age-fade.md b/changelog.d/1892-line-age-fade.md new file mode 100644 index 0000000000..7f12993956 --- /dev/null +++ b/changelog.d/1892-line-age-fade.md @@ -0,0 +1,4 @@ +- Lines can fade with the age of their points (`LineItem.ageFade`, capability + `lineAgeFade`), drawn by the renderer on the GPU on the scene clock, so a + moving trail is not re-sent each frame; the Cesium renderer draws it, draped + or not (samehkhamis, #1892). diff --git a/docs/RENDERER-CONTRACT.md b/docs/RENDERER-CONTRACT.md index b9a38608d5..960419e248 100644 --- a/docs/RENDERER-CONTRACT.md +++ b/docs/RENDERER-CONTRACT.md @@ -122,6 +122,23 @@ optional: - A line item's `depthFail` style, solid or dashed, draws the parts behind the surface (the Draw tool's rubber band is dashed there too); without one they are hidden. +- `LineItem.ageFade` (capability `lineAgeFade`, `LineAgeFade`) fades a + line with the age of its points on the scene clock (`frame.setTime`): + each position has a time, a point's recency is + `1 - clamp((now - time) / windowMs, 0, 1)`, running evenly between + positions, and the line's colour (its style's or a segment's) draws at its + alpha times `mix(alphaFloor, 1, smoothstep(0, 1, recency))`, times + `mix(squaredAlphaFloor, 1, recency²)` with `squaredAlphaFloor`, and + `widthPx` times `mix(widthFloor, 1, recency)` wide with `widthFloor`. Time + passing changes the drawing, not the line, so a trail whose points stay + put is never sent again; new times with new positions are an ordinary + update. A renderer without the capability draws the line unfaded. The + Cesium port lists it where its context has floating-point textures: an + aged line's material reads its points' times from a small texture and the + scene's time from a uniform set each frame, per fragment (draped lines + 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. - 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/scripts/format-scope.json b/scripts/format-scope.json index 5f9943f711..44f152694b 100644 --- a/scripts/format-scope.json +++ b/scripts/format-scope.json @@ -80,6 +80,7 @@ "src/render/cesium/tileRequests.test.mjs", "src/queries/heights.test.mjs", "src/render/cesium/heights.test.mjs", + "src/render/cesium/drawLineAges.test.mjs", "docs/CODE-BOUNDARIES.md", "src/main.js", "docs/APPLICATION.md", diff --git a/src/render/cesium/draw.js b/src/render/cesium/draw.js index 9c55c72d00..b5fb61f450 100644 --- a/src/render/cesium/draw.js +++ b/src/render/cesium/draw.js @@ -401,6 +401,185 @@ export function revealUniform(fraction, positions) { return at ? (at.index + at.t) / (positions.length - 1) : 2; } +/** + * The material a line's style draws with, inside the age and reveal + * materials wrapped round it. + */ +function styleMaterial(material) { + let drawn = material; + while (drawn.materials?.aged || drawn.materials?.revealed) + drawn = drawn.materials.aged ?? drawn.materials.revealed; + return drawn; +} + +/** A line's material inside its age material: the one a reveal is set on. */ +const unaged = (material) => material.materials?.aged ?? material; + +/** The prefix of an age-faded line's material types (`LineItem.ageFade`). */ +const AGE_MATERIAL = 'DrawAgedLine'; + +/** Points an age texture's row holds; a longer line takes more rows. */ +const AGE_TEXTURE_WIDTH = 1024; + +/** + * A line faded with the age of its points (`LineItem.ageFade`), in its own + * style otherwise. `ages` holds a texel a drawn point: where along the + * line's texture it lies (`st.s`) and its time, seconds after `ageNow`'s + * zero. A polyline's texture runs evenly per vertex, so its point is found + * at once; a ground polyline's runs along its length (`ageByLength`), so + * its point is searched for. Its time runs evenly to the next point's, and + * 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). + */ +const AGE_SOURCE = ` +vec4 drawAgeTexel(float i) { + float row = floor(i / ageWidth); + return texture(ages, vec2((i - row * ageWidth + 0.5) / ageWidth, (row + 0.5) / ageRows)); +} + +czm_material czm_getMaterial(czm_materialInput materialInput) { + float s = clamp(materialInput.st.s, 0.0, 1.0); + float last = max(ageCount - 1.0, 0.0); + float lo = 0.0; + float hi = last; + float u = 0.0; + if (ageByLength > 0.5) { + for (int k = 0; k < 24; k++) { + if (hi - lo <= 1.0) break; + float mid = floor((lo + hi) * 0.5); + if (drawAgeTexel(mid).r <= s) lo = mid; + else hi = mid; + } + vec2 a = drawAgeTexel(lo).rg; + vec2 b = drawAgeTexel(hi).rg; + u = b.r > a.r ? clamp((s - a.r) / (b.r - a.r), 0.0, 1.0) : 0.0; + } else { + float f = s * last; + lo = min(floor(f), max(last - 1.0, 0.0)); + hi = min(lo + 1.0, last); + u = clamp(f - lo, 0.0, 1.0); + } + float when = mix(drawAgeTexel(lo).g, drawAgeTexel(hi).g, u); + 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) + fade *= mix(ageSquaredFloor, 1.0, recency * recency); + float width = max(mix(ageWidthFloor, 1.0, recency), 0.001); + float across = (materialInput.st.t - 0.5) / width; + if (abs(across) > 0.5) discard; + materialInput.st.t = across + 0.5; + czm_material m = aged; + m.alpha *= fade; + + return m; +}`; + +/** + * What an age-faded line's material draws from: a texel a drawn point (see + * `AGE_SOURCE`), packed four floats each (where along the line, its time in + * seconds after `base`, and two unused), `width` to a row; and the fade's + * uniforms. `points` are the line as drawn and `times` theirs; a polyline + * drops a point at the place of the one before it, as Cesium does, and + * 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. + * @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] + */ +export function lineAgeData(points, times, fade, byLength = false) { + let kept = Array.from(times); + let along = points; + if (!byLength) { + const removed = []; + Cesium.arrayRemoveDuplicates( + points, + Cesium.Cartesian3.equalsEpsilon, + false, + removed, + ); + if (removed.length) { + const gone = new Set(removed); + kept = kept.filter((_, i) => !gone.has(i)); + along = points.filter((_, i) => !gone.has(i)); + } + } + const count = kept.length; + const fractions = new Float64Array(count); + if (byLength) { + let total = 0; + let previous = null; + for (let i = 0; i < count; i++) { + const here = Cesium.Cartographic.fromCartesian(along[i]); + if (previous && here) + total += new Cesium.EllipsoidGeodesic(previous, here).surfaceDistance; + fractions[i] = total; + if (here) previous = here; + } + for (let i = 0; i < count; i++) + fractions[i] = total > 0 ? fractions[i] / total : 0; + } else + for (let i = 0; i < count; i++) + fractions[i] = count > 1 ? i / (count - 1) : 0; + let base = -Infinity; + for (const time of kept) if (time > base) base = time; + if (!Number.isFinite(base)) base = 0; + const width = Math.max(1, Math.min(count, AGE_TEXTURE_WIDTH)); + const rows = Math.max(1, Math.ceil(count / width)); + const data = new Float32Array(width * rows * 4); + for (let i = 0; i < count; i++) { + data[i * 4] = fractions[i]; + data[i * 4 + 1] = (kept[i] - base) / 1000; + } + return { + data, + width, + rows, + count, + base, + uniforms: { + ageCount: count, + ageWidth: width, + ageRows: rows, + ageByLength: byLength ? 1 : 0, + ageWindow: fade.windowMs / 1000, + ageAlphaFloor: fade.alphaFloor, + ageSquaredFloor: fade.squaredAlphaFloor ?? -1, + ageWidthFloor: fade.widthFloor ?? 1, + }, + }; +} + +/** + * A line's `ageFade`, checked: one finite time a position, over a positive + * window, its floors from 0 to 1. Refused otherwise. + * @param {import('../contract/draw').LineItem} item + */ +function checkAgeFade(item) { + const fade = item.ageFade; + if (fade == null) return; + const count = + item.positions instanceof Float64Array + ? item.positions.length / 3 + : item.positions.length; + const floor = (value) => value === undefined || (value >= 0 && value <= 1); + if ( + !fade.times || + fade.times.length !== count || + !Array.prototype.every.call(fade.times, Number.isFinite) || + !(fade.windowMs > 0 && Number.isFinite(fade.windowMs)) || + !(fade.alphaFloor >= 0 && fade.alphaFloor <= 1) || + !floor(fade.squaredAlphaFloor) || + !floor(fade.widthFloor) + ) + throw new TypeError( + 'a line fades with one finite time a position, over a positive window, with floors from 0 to 1', + ); +} + /** * The `flow` lines' clock, seconds, for a line flowing at `speed` cells a * second: wrapped to one cell's time, which draws the same dashes, so the @@ -477,6 +656,8 @@ export function createCesiumDraw({ now = () => performance.now(), }) { const sets = new Map(); + // Lines fade with the age of their points (`LineItem.ageFade`). + const ageFades = capabilities.has('lineAgeFade'); // Fields share the sets' ids. const fieldPart = createCesiumFields({ scene, @@ -562,9 +743,11 @@ export function createCesiumDraw({ // changes. const checkPulses = (list) => { if (kind === 'lines') - for (const item of list) + for (const item of list) { if (item.style?.kind === 'split' && item.mode !== 'draped') throw new TypeError('a split line is draped'); + if (ageFades) checkAgeFade(item); + } if (kind !== 'shapes') return; for (const item of list) pulseOf(item); if (list.some((item) => item.animate)) record.mayPulse = true; @@ -2309,32 +2492,47 @@ export function createCesiumDraw({ * (the route annotations' dashes, which run toward the line's end on the * clock `flowTime` keeps) is noted for the frame clock. */ - function lineMaterial(record, style, reveal) { + function lineMaterial(record, style, reveal, age) { const fabric = lineFabric(style); // Built from its type, then given its values, as `fromType` does: // values in the fabric would be merged into copies of the type's. const template = ({ type, source, uniforms }) => source ? { type, source, uniforms } : { type }; - // A pattern's image carries its own alpha, and a split line's colours - // may each have one: drawn in the translucent pass, whatever its colour. + // A pattern's image carries its own alpha, a split line's colours may + // each have one, and an aged line fades: drawn in the translucent pass, + // whatever its colour. const translucent = - style.kind === 'pattern' || style.kind === 'split' + style.kind === 'pattern' || style.kind === 'split' || age ? { translucent: true } : {}; - const material = - reveal === undefined - ? new Cesium.Material({ fabric: template(fabric), ...translucent }) - : new Cesium.Material({ - fabric: { - type: `${REVEAL_MATERIAL}_${style.kind}`, - materials: { revealed: template(fabric) }, - uniforms: { reveal }, - source: REVEAL_SOURCE, - }, - ...translucent, - }); - const drawn = reveal === undefined ? material : material.materials.revealed; + let built = template(fabric); + if (reveal !== undefined) + built = { + type: `${REVEAL_MATERIAL}_${style.kind}`, + materials: { revealed: built }, + uniforms: { reveal }, + source: REVEAL_SOURCE, + }; + if (age) + built = { + type: `${AGE_MATERIAL}_${reveal === undefined ? '' : 'revealed_'}${style.kind}`, + materials: { aged: built }, + uniforms: { + ...age.uniforms, + ages: Cesium.Material.DefaultImageId, + ageNow: 0, + }, + source: AGE_SOURCE, + }; + const material = new Cesium.Material({ fabric: built, ...translucent }); + const drawn = styleMaterial(material); Object.assign(drawn.uniforms, fabric.uniforms); + if (age) { + // Translucent whatever its style's colour: a composite material is + // translucent only where all of its parts are. + material.translucent = true; + noteAge(record, material, age); + } const flow = flowOf(material, style); if (flow) record.flowMaterials.push(flow); if (style.kind === 'pattern') holdImage(material, style.image); @@ -2346,11 +2544,7 @@ export function createCesiumDraw({ * line draws), for the frame clock; null for other styles. */ const flowOf = (material, style) => - style.kind !== 'flow' - ? null - : material.type === FLOW_MATERIAL - ? material - : material.materials.revealed; + style.kind !== 'flow' ? null : styleMaterial(material); /** Stop running the clock of a line material that no longer draws. */ function dropFlow(record, material, style) { @@ -2362,6 +2556,125 @@ export function createCesiumDraw({ /** Whether a line draws only the first part of its length. */ const revealed = (item) => item.revealFraction !== undefined; + /** + * Note an age-faded line's material, which takes the scene's time each + * frame (`runAges`) and its points' times as a texture. `owner`, the + * primitive drawing it where that is not a polyline collection's (which + * destroys the materials of the lines it lets go): the material goes with + * it (`claimAges`). + */ + function noteAge(record, material, age) { + (record.ages ??= new Map()).set(material, { + age, + texture: null, + dirty: true, + owner: null, + }); + (record.unclaimedAges ??= []).push(material); + material.uniforms.ageNow = (sceneMs() - age.base) / 1000; + } + + /** The aged materials made since the last claim are `owner`'s. */ + function claimAges(record, owner) { + for (const material of record.unclaimedAges?.splice(0) ?? []) { + const entry = record.ages.get(material); + if (entry && owner) entry.owner = owner; + } + } + + /** An aged line's material takes its line's new points and times. */ + function writeAge(record, material, age) { + const entry = record.ages?.get(material); + if (!entry) return; + const was = entry.age; + Object.assign(material.uniforms, age.uniforms); + entry.age = age; + material.uniforms.ageNow = (sceneMs() - age.base) / 1000; + if ( + was.width === age.width && + was.rows === age.rows && + was.data.every((value, i) => Object.is(value, age.data[i])) + ) + return; + entry.dirty = true; + requestRender(); + } + + /** The scene's time now, epoch ms: the frame's, once one has drawn. */ + const sceneMs = () => + Cesium.JulianDate.toDate( + scene.frameState?.time ?? Cesium.JulianDate.now(), + ).getTime(); + + /** + * Each frame, before it draws: every aged line's material takes the + * scene's time, and its points' times where they changed (written into + * its texture, or a new one where it changed size). A material whose + * line is gone goes, with its texture. + */ + function runAges() { + let ms = null; + for (const record of sets.values()) { + if (!record.ages?.size) continue; + ms ??= sceneMs(); + for (const [material, entry] of record.ages) { + if (dropAge(record, material, entry)) continue; + material.uniforms.ageNow = (ms - entry.age.base) / 1000; + if (entry.dirty && scene.context) uploadAge(material, entry); + } + } + } + + /** Let an aged material go if its line is gone; true if it went. */ + function dropAge(record, material, entry) { + if (!material.isDestroyed() && !entry.owner?.isDestroyed()) return false; + if (!material.isDestroyed()) material.destroy(); + // One handed over but never taken is no one's. + if (entry.texture && !entry.texture.isDestroyed()) entry.texture.destroy(); + record.ages.delete(material); + return true; + } + + /** Write an aged material's times into its texture, made as needed. */ + function uploadAge(material, entry) { + const { data, width, rows } = entry.age; + const source = { width, height: rows, arrayBufferView: data }; + entry.dirty = false; + const texture = entry.texture; + if ( + texture && + !texture.isDestroyed() && + texture.width === width && + texture.height === rows + ) { + texture.copyFrom({ source }); + return; + } + if ( + texture && + !texture.isDestroyed() && + materialTexture(material, 'ages') !== texture + ) + texture.destroy(); + entry.texture = new Cesium.Texture({ + context: scene.context, + width, + height: rows, + pixelFormat: Cesium.PixelFormat.RGBA, + pixelDatatype: Cesium.PixelDatatype.FLOAT, + flipY: false, + source, + sampler: new Cesium.Sampler({ + wrapS: Cesium.TextureWrap.CLAMP_TO_EDGE, + wrapT: Cesium.TextureWrap.CLAMP_TO_EDGE, + minificationFilter: Cesium.TextureMinificationFilter.NEAREST, + magnificationFilter: Cesium.TextureMagnificationFilter.NEAREST, + }), + }); + // The material destroys the texture it held once it takes this one. + material.uniforms.ages = entry.texture; + } + /** The fabric of a line style's material. */ function lineFabric(style) { switch (style.kind) { @@ -2440,7 +2753,12 @@ export function createCesiumDraw({ } } - function linePositions(item) { + /** + * A line's positions as drawn: a geodesic one cut along its arc. With + * `times` (one a position), `timesOut` takes the time of each point drawn, + * running evenly between the positions'. + */ + function linePositions(item, times = null, timesOut = null) { const flat = item.positions instanceof Float64Array; const points = []; const n = flat ? item.positions.length / 3 : item.positions.length; @@ -2454,7 +2772,10 @@ export function createCesiumDraw({ ) : toCartesian(item.positions[i]), ); - if (item.mode !== 'geodesic') return points; + if (item.mode !== 'geodesic') { + if (timesOut) for (let i = 0; i < n; i++) timesOut.push(times[i]); + return points; + } const dense = []; for (let i = 0; i + 1 < points.length; i++) { const a = Cesium.Cartographic.fromCartesian(points[i]); @@ -2469,6 +2790,7 @@ export function createCesiumDraw({ ); for (let k = 0; k < steps; k++) { const s = k / steps; + if (timesOut) timesOut.push(times[i] + (times[i + 1] - times[i]) * s); const at = geodesic.interpolateUsingFraction(s); dense.push( Cesium.Cartesian3.fromRadians( @@ -2480,9 +2802,31 @@ export function createCesiumDraw({ } } dense.push(points.at(-1)); + if (timesOut) timesOut.push(times[n - 1]); return dense; } + /** Whether a line fades with age here: it asks, and the port lists it. */ + const aged = (item) => ageFades && item.ageFade != null; + + /** + * What an age-faded line's material draws from (`lineAgeData`), for the + * line drawn along `positions` (as `linePositions` made them from it, by + * default); undefined for a line that does not fade. A draped line, and + * one drawn over the surface for it, lies along its texture by length. + */ + function ageOf(item, positions) { + if (!aged(item)) return undefined; + const times = []; + const drawn = linePositions(item, item.ageFade.times, times); + return lineAgeData( + positions ?? drawn, + times, + item.ageFade, + item.mode === 'draped' || item.overlaid === true, + ); + } + /** * Whether `positions` make a line: two or more of them, not all at one * place. @@ -2503,8 +2847,9 @@ export function createCesiumDraw({ const reveal = revealed(item) ? revealUniform(item.revealFraction, positions) : undefined; - const material = lineMaterial(record, item.style, reveal); - return new Cesium.Primitive({ + const age = ageOf(item, positions); + const material = lineMaterial(record, item.style, reveal, age); + const primitive = new Cesium.Primitive({ geometryInstances: new Cesium.GeometryInstance({ geometry: new Cesium.PolylineGeometry({ positions, @@ -2522,7 +2867,7 @@ export function createCesiumDraw({ appearance: new Cesium.PolylineMaterialAppearance({ material }), depthFailAppearance: item.depthFail ? new Cesium.PolylineMaterialAppearance({ - material: lineMaterial(record, item.depthFail, reveal), + material: lineMaterial(record, item.depthFail, reveal, age), }) : undefined, show: item.show !== false, @@ -2530,6 +2875,8 @@ export function createCesiumDraw({ // A set that never picks keeps these out of the pick pass too. allowPicking: record.spec.pickable !== false, }); + claimAges(record, primitive); + return primitive; } /** @@ -2562,7 +2909,10 @@ export function createCesiumDraw({ * colours only, so an outlined line draws by its own material. */ const batchable = (item) => - item.style.kind === 'solid' && !item.style.outline && !revealed(item); + item.style.kind === 'solid' && + !item.style.outline && + !revealed(item) && + !aged(item); /** * A ground primitive of a draped line's own, drawn by a material (a @@ -2582,18 +2932,21 @@ export function createCesiumDraw({ record, item.style, revealed(item) ? revealUniform(item.revealFraction) : undefined, + ageOf(item, positions), ); appearance = new Cesium.PolylineMaterialAppearance({ material: part.material, }); } - return new Cesium.GroundPolylinePrimitive({ + const primitive = new Cesium.GroundPolylinePrimitive({ geometryInstances: [drapedInstance(item, part, solid, positions)], appearance, classificationType: classificationOf(part.clampTo), allowPicking: record.spec.pickable !== false, asynchronous: !sync, }); + claimAges(record, primitive); + return primitive; } /** @@ -2666,7 +3019,8 @@ export function createCesiumDraw({ item.mode === 'draped' && item.style.kind === 'solid' && !item.style.outline && - !revealed(item) + !revealed(item) && + !aged(item) )) || (item.frame === 'inertial' && item.mode !== 'draped' && item.depthFail); @@ -2699,6 +3053,7 @@ export function createCesiumDraw({ look: lineLook(item), id, from: flatPositions(item.positions), + ageFrom: aged(item) ? Array.from(item.ageFade.times) : null, reveal: item.revealFraction, pieces: [], }; @@ -2739,6 +3094,15 @@ export function createCesiumDraw({ positions, style: pieceStyle(item, j, j === spans.length - 1), ...(revealed(item) && shown < 1 ? { revealFraction: shown } : {}), + // Its own points' times. + ...(aged(item) + ? { + ageFade: { + ...item.ageFade, + times: Array.prototype.slice.call(item.ageFade.times, a, b + 1), + }, + } + : {}), }; if (!(revealed(item) && shown < 1)) delete sub.revealFraction; const draped = item.mode === 'draped'; @@ -2779,7 +3143,7 @@ export function createCesiumDraw({ const reveal = revealed(item) ? revealUniform(item.revealFraction) : undefined; - return new Cesium.GroundPolylinePrimitive({ + const primitive = new Cesium.GroundPolylinePrimitive({ geometryInstances: [ new Cesium.GeometryInstance({ geometry: new Cesium.GroundPolylineGeometry({ @@ -2792,13 +3156,15 @@ export function createCesiumDraw({ }), ], appearance: new Cesium.PolylineMaterialAppearance({ - material: lineMaterial(record, item.style, reveal), + material: lineMaterial(record, item.style, reveal, ageOf(item)), }), classificationType: classificationOf( item.clampTo ?? record.spec.clampTo ?? 'both', ), allowPicking: record.spec.pickable !== false, }); + claimAges(record, primitive); + return primitive; } /** A pieced line's colours and shows, written in place. */ @@ -2807,8 +3173,7 @@ export function createCesiumDraw({ if (!piece || piece.primitive.isDestroyed()) continue; const style = pieceStyle(item, piece.j, piece.last); const material = piece.primitive.appearance.material; - if (style.kind !== 'pattern') - paintLine(material.materials?.revealed ?? material, style); + if (style.kind !== 'pattern') paintLine(material, style); const show = pieceShows(item, piece.j, piece.shown); if (!piece.draped) piece.primitive.show = show; else if (piece.primitive.ready) { @@ -2842,8 +3207,18 @@ export function createCesiumDraw({ const first = segmentShow.indexOf(true); const last = segmentShow.lastIndexOf(true); if (first < 0) line.show = false; - else if (first > 0 || last < segmentShow.length - 1) + else if (first > 0 || last < segmentShow.length - 1) { line.positions = linePositions(item).slice(first, last + 2); + if (item.ageFade) + line.ageFade = { + ...item.ageFade, + times: Array.prototype.slice.call( + item.ageFade.times, + first, + last + 2, + ), + }; + } } return line; } @@ -2855,11 +3230,12 @@ export function createCesiumDraw({ */ function overlayRecoloured(record, part, item) { const deep = part.deep; - if (!item.overlaid || !deep || revealed(item)) return false; + // An aged one may have new times: built anew. + if (!item.overlaid || !deep || revealed(item) || aged(item)) return false; if (!flatEquals(item.positions, part.overlayFrom)) return false; // Only its colour may have changed (`patchLines` checked its look). paintLine(deep.appearance.material, item.style); - deep.depthFailAppearance.material.uniforms.color = toColor( + styleMaterial(deep.depthFailAppearance.material).uniforms.color = toColor( item.style.color, ); const line = record.overlayLines.find((entry) => entry.part === part); @@ -3016,7 +3392,7 @@ export function createCesiumDraw({ draped.get(clampTo).push(...instances); continue; } - if (item.style.kind === 'glow' && !revealed(item)) { + if (item.style.kind === 'glow' && !revealed(item) && !aged(item)) { if (!glows.has(part.look)) glows.set(part.look, []); glows.get(part.look).push({ item, part }); continue; @@ -3087,8 +3463,8 @@ export function createCesiumDraw({ shape: settled ? looks.shape(item) : null, positions: settled ? flatPositions(item.positions) : null, // An outlined line, which never settles, takes its colours in - // place too: how it draws but for them. - outlined: item.style.outline ? looks.shape(item) : null, + // place too: how it draws but for them; and so does an aged one. + outlined: item.style.outline || aged(item) ? looks.shape(item) : null, id, polyline, reveal, @@ -3192,6 +3568,7 @@ export function createCesiumDraw({ /** Give a line's material its style's colours, its outline's too. */ function paintLine(material, style) { + material = styleMaterial(material); material.uniforms.color = toColor(style.color); if (style.outline && 'outlineColor' in material.uniforms) material.uniforms.outlineColor = toColor(style.outline.color); @@ -3223,6 +3600,15 @@ export function createCesiumDraw({ item.segmentShow != null, revealed(item), item.frame, + // How it fades with age (its times change with its positions). + aged(item) + ? [ + item.ageFade.windowMs, + item.ageFade.alphaFloor, + item.ageFade.squaredAlphaFloor, + item.ageFade.widthFloor, + ] + : null, ]); /** @@ -3238,7 +3624,22 @@ export function createCesiumDraw({ (a.segmentColors != null) === (b.segmentColors != null) && (a.segmentShow != null) === (b.segmentShow != null) && revealed(a) === revealed(b) && - a.frame === b.frame; + a.frame === b.frame && + sameAgeLook(a, b); + + /** Whether two lines fade with age alike, but for their times. */ + const sameAgeLook = (a, b) => { + if (aged(a) !== aged(b)) return false; + if (!aged(a)) return true; + const x = a.ageFade; + const y = b.ageFade; + return ( + x.windowMs === y.windowMs && + x.alphaFloor === y.alphaFloor && + x.squaredAlphaFloor === y.squaredAlphaFloor && + x.widthFloor === y.widthFloor + ); + }; /** * `lineLook`, kept for the last item asked for: within one upsert, lines @@ -3277,6 +3678,16 @@ export function createCesiumDraw({ return flat; } + /** Whether a line's age times are `times` (null: it does not fade). */ + const sameTimes = (item, times) => + aged(item) + ? times !== null && + item.ageFade.times.length === times.length && + Array.prototype.every.call(item.ageFade.times, (time, i) => + Object.is(time, times[i]), + ) + : times === null; + const samePositions = (a, b) => a === b || (a.length === b.length && a.every((value, i) => Object.is(value, b[i]))); @@ -3423,6 +3834,7 @@ export function createCesiumDraw({ !piecewise(item) || lookOf.look(item) !== was.look || !flatEquals(item.positions, was.from) || + !sameTimes(item, was.ageFrom) || item.revealFraction !== was.reveal || was.pieces.some((piece) => piece?.primitive.isDestroyed()) ) @@ -3446,6 +3858,9 @@ export function createCesiumDraw({ if (was.deep !== undefined && record.deepLines?.isDestroyed()) return false; if (!was.clampTo) continue; + // A draped line that fades with age is built anew: its times may + // have changed with or without its positions. + if (aged(item)) return false; const flat = flatEquals(item.positions, was.positions) ? was.positions : flatPositions(item.positions); @@ -3515,7 +3930,9 @@ export function createCesiumDraw({ continue; } if (was.material && revealed(item)) - was.material.uniforms.reveal = revealUniform(item.revealFraction); + unaged(was.material).uniforms.reveal = revealUniform( + item.revealFraction, + ); if (was.solo) { // Not yet drawn, it is built again showing as asked. if (was.ground && was.ground.ready) showPart(was, show); @@ -3549,7 +3966,12 @@ export function createCesiumDraw({ const reveal = revealed(item) ? revealUniform(item.revealFraction, positions) : undefined; - const material = lineMaterial(record, item.style, reveal); + const material = lineMaterial( + record, + item.style, + reveal, + ageOf(item, positions), + ); const polyline = polylines.add({ positions, width: item.widthPx, @@ -3557,9 +3979,11 @@ export function createCesiumDraw({ show: item.show !== false, id, }); + // The collection destroys the material when it lets the line go. + claimAges(record, null); return { polyline, - reveal: reveal === undefined ? null : material, + reveal: reveal === undefined ? null : unaged(material), parked: false, }; } @@ -3573,6 +3997,8 @@ export function createCesiumDraw({ item.mode !== 'draped' && item.frame !== 'inertial' && !item.depthFail && + // A batch draws one colour per line, unfaded. + !aged(item) && item.style.kind === 'solid' && // A batch draws one colour per line, no outline. !item.style.outline && @@ -3680,6 +4106,9 @@ export function createCesiumDraw({ if (!unmoved) was.polyline.positions = positions; was.polyline.show = show; if (recolour) paintLine(was.polyline.material, item.style); + // Its points' times, with its points. + if (aged(item)) + writeAge(record, was.polyline.material, ageOf(item, positions)); if (was.reveal) was.reveal.uniforms.reveal = revealUniform( item.revealFraction, @@ -5451,6 +5880,7 @@ export function createCesiumDraw({ cullHorizon(); clusterIcons(); runFlows(); + runAges(); for (const record of sets.values()) { if (record.inertialLines || record.inertialPieces?.length) turnInertial(record); @@ -5501,6 +5931,10 @@ export function createCesiumDraw({ fieldPart.dispose(); // Part shaders and their textures go with it too. modelSets.dispose(); + // Aged lines' materials whose lines are gone, with their textures. + for (const record of sets.values()) + for (const [material, entry] of record.ages ?? []) + dropAge(record, material, entry); // Late model loads find no host and destroy themselves. for (const record of sets.values()) { if (removeHosts && !scene.isDestroyed?.()) { diff --git a/src/render/cesium/drawLineAges.test.mjs b/src/render/cesium/drawLineAges.test.mjs new file mode 100644 index 0000000000..a2769da0fc --- /dev/null +++ b/src/render/cesium/drawLineAges.test.mjs @@ -0,0 +1,326 @@ +import assert from 'node:assert/strict'; +import * as Cesium from 'cesium'; +import test, { after } from 'node:test'; +import { createCesiumDraw, lineAgeData } from './draw.js'; + +// Node has no WebGL context to report line-width limits. +Cesium.ContextLimits._minimumAliasedLineWidth = 1; +Cesium.ContextLimits._maximumAliasedLineWidth = 10; + +// A material's texture uniform is told from the browser's image classes, which +// Node lacks. +const IMAGE_CLASSES = [ + 'HTMLCanvasElement', + 'HTMLImageElement', + 'ImageBitmap', + 'OffscreenCanvas', +]; +const realClasses = IMAGE_CLASSES.map((name) => globalThis[name]); +for (const name of IMAGE_CLASSES) globalThis[name] ??= class {}; +after(() => + IMAGE_CLASSES.forEach((name, i) => (globalThis[name] = realClasses[i])), +); + +/** A scene with what a line set touches: primitives, its events and its time. */ +function fakeScene(ms = Date.UTC(2026, 0, 1)) { + const added = []; + return { + added, + postRender: new Cesium.Event(), + preRender: new Cesium.Event(), + camera: { positionWC: new Cesium.Cartesian3(2e7, 0, 0) }, + frameState: { + mode: Cesium.SceneMode.SCENE3D, + time: Cesium.JulianDate.fromDate(new Date(ms)), + }, + updateHeight: () => () => {}, + getHeight: () => undefined, + primitives: { + add: (primitive) => (added.push(primitive), primitive), + remove: (primitive) => { + const at = added.indexOf(primitive); + if (at >= 0) added.splice(at, 1); + return at >= 0; + }, + length: 0, + }, + requestRender() {}, + isDestroyed: () => false, + }; +} + +const T0 = Date.UTC(2026, 0, 1); + +/** A port that fades lines with age, over `scene`, and its frames at a scene time. */ +function agedDraw(scene = fakeScene(), capabilities = ['lineAgeFade']) { + const part = createCesiumDraw({ + scene, + report: (error) => assert.fail(error), + capabilities: new Set(capabilities), + }); + return { + part, + scene, + frameAt(ms) { + scene.frameState.time = Cesium.JulianDate.fromDate(new Date(ms)); + part.beforeRender(); + part.afterRender(); + }, + }; +} + +const along = (n, lat = 10) => + Array.from({ length: n }, (_, i) => + Cesium.Cartesian3.fromDegrees(i * 0.01, lat, 100), + ); + +const trail = (positions, times, extra = {}) => ({ + id: 'trail', + positions, + widthPx: 3, + mode: '3d', + style: { kind: 'solid', color: [0.2, 0.8, 1, 0.9] }, + ageFade: { times, windowMs: 60_000, alphaFloor: 0.06, ...extra }, + pickable: false, +}); + +/** The polylines a line set's host draws in its collection. */ +function collectionOf(scene) { + const host = scene.added.at(-1); + if (host instanceof Cesium.PolylineCollection) return host; + for (let i = 0; i < host.length; i++) + if (host.get(i) instanceof Cesium.PolylineCollection) return host.get(i); + return null; +} + +test('a polyline’s age texels: a point at the place of the one before it is dropped, the rest even along it, times in seconds before the newest', () => { + const [a, b, c] = along(3); + const age = lineAgeData([a, a, b, c], [T0, T0 + 1000, T0 + 2000, T0 + 4000], { + times: [], + windowMs: 30_000, + alphaFloor: 0.06, + squaredAlphaFloor: 0.14, + }); + assert.equal(age.count, 3); + assert.equal(age.base, T0 + 4000); + const texel = (i) => [age.data[i * 4], age.data[i * 4 + 1]]; + assert.deepEqual(texel(0), [0, -4]); + assert.deepEqual(texel(1), [0.5, -2]); + assert.deepEqual(texel(2), [1, 0]); + assert.deepEqual(age.uniforms, { + ageCount: 3, + ageWidth: 3, + ageRows: 1, + ageByLength: 0, + ageWindow: 30, + ageAlphaFloor: 0.06, + ageSquaredFloor: 0.14, + ageWidthFloor: 1, + }); +}); + +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), + Cesium.Cartesian3.fromDegrees(1, 0), + Cesium.Cartesian3.fromDegrees(4, 0), + ]; + const age = lineAgeData( + points, + [0, 1000, 2000], + { times: [], windowMs: 1, alphaFloor: 0 }, + true, + ); + assert.equal(age.uniforms.ageByLength, 1); + assert.equal(age.data[0], 0); + assert.ok( + Math.abs(age.data[4] - 0.25) < 1e-6, + `a quarter along (${age.data[4]})`, + ); + assert.equal(age.data[8], 1); + const long = along(2500); + const many = lineAgeData( + long, + long.map((_, i) => i), + { times: [], windowMs: 1, alphaFloor: 0 }, + ); + assert.equal(many.width, 1024); + assert.equal(many.rows, 3); + assert.equal(many.data.length, 1024 * 3 * 4); +}); + +test('an aged line fades on the scene clock: time passing changes its material, never its line', () => { + const { part, scene, frameAt } = agedDraw(); + const set = part.port.lines({ id: 'trails' }); + const positions = along(4); + const times = [T0 - 30_000, T0 - 20_000, T0 - 10_000, T0]; + set.set([ + trail(positions, times, { squaredAlphaFloor: 0.14, widthFloor: 0.3 }), + ]); + const polylines = collectionOf(scene); + const polyline = polylines.get(0); + const material = polyline.material; + assert.equal(material.type, 'DrawAgedLine_solid'); + assert.ok(material.isTranslucent(), 'drawn in the translucent pass'); + assert.equal(material.uniforms.ageWindow, 60); + assert.equal(material.uniforms.ageAlphaFloor, 0.06); + assert.equal(material.uniforms.ageSquaredFloor, 0.14); + assert.equal(material.uniforms.ageWidthFloor, 0.3); + assert.equal(material.uniforms.ageCount, 4); + assert.ok( + Cesium.Color.equals( + material.materials.aged.uniforms.color, + new Cesium.Color(0.2, 0.8, 1, 0.9), + ), + 'its style’s colour inside', + ); + for (let k = 1; k <= 120; k++) { + frameAt(T0 + k * 1000); + assert.equal( + material.uniforms.ageNow, + k, + `seconds after its newest point, frame ${k}`, + ); + } + assert.equal(collectionOf(scene), polylines, 'the same collection'); + assert.equal(polylines.length, 1); + assert.equal(polylines.get(0), polyline, 'the same line'); + assert.equal(polyline.material, material, 'the same material'); +}); + +test('an aged line given new points and times moves in place and takes the new times', () => { + const { part, scene, frameAt } = agedDraw(); + const set = part.port.lines({ id: 'trails' }); + const positions = along(5); + const times = [0, 1, 2, 3, 4].map((i) => T0 + i * 10_000); + set.set([trail(positions.slice(0, 4), times.slice(0, 4))]); + const polyline = collectionOf(scene).get(0); + const material = polyline.material; + frameAt(T0 + 40_000); + assert.equal(material.uniforms.ageNow, 10); + set.upsert([trail(positions.slice(1), times.slice(1))]); + assert.equal(collectionOf(scene).get(0), polyline, 'moved in place'); + assert.equal(polyline.material, material); + frameAt(T0 + 45_000); + assert.equal(material.uniforms.ageNow, 5, 'from its new newest point'); + assert.ok(Cesium.Cartesian3.equals(polyline.positions[0], positions[1])); + // A new colour is taken in place too, inside the fade. + set.upsert([ + { + ...trail(positions.slice(1), times.slice(1)), + style: { kind: 'solid', color: '#ff0000' }, + }, + ]); + assert.equal(collectionOf(scene).get(0), polyline, 'recoloured in place'); + assert.ok( + Cesium.Color.equals( + material.materials.aged.uniforms.color, + Cesium.Color.RED, + ), + ); +}); + +test('segment colours fade with age too, each segment with its own two times', () => { + const { part, scene, frameAt } = agedDraw(); + const set = part.port.lines({ id: 'trails' }); + const times = [T0, T0 + 1000, T0 + 2000]; + set.set([ + { + ...trail(along(3), times), + segmentColors: ['#ff0000', '#00ff00'], + }, + ]); + const pieces = []; + const visit = (primitive) => { + if (primitive instanceof Cesium.Primitive) pieces.push(primitive); + else if (primitive?.length !== undefined && primitive.get) + for (let i = 0; i < primitive.length; i++) visit(primitive.get(i)); + }; + visit(scene.added.at(-1)); + assert.equal(pieces.length, 2); + frameAt(T0 + 3000); + const [first, second] = pieces.map((piece) => piece.appearance.material); + assert.equal(first.type, 'DrawAgedLine_solid'); + assert.equal( + first.uniforms.ageNow, + 2, + 'its newer point a second after the first', + ); + assert.equal(second.uniforms.ageNow, 1); + assert.ok( + Cesium.Color.equals(first.materials.aged.uniforms.color, Cesium.Color.RED), + ); + assert.ok( + Cesium.Color.equals( + second.materials.aged.uniforms.color, + Cesium.Color.LIME, + ), + ); +}); + +test('a draped aged line draws by a ground primitive of its own, its times along its length', () => { + const { part, scene } = agedDraw(); + const set = part.port.lines({ id: 'trails' }); + const ground = [0, 1, 2].map((i) => + Cesium.Cartesian3.fromDegrees(i * 0.01, 10), + ); + set.set([{ ...trail(ground, [T0, T0 + 1, T0 + 2]), mode: 'draped' }]); + const host = scene.added.at(-1); + const primitives = []; + const visit = (primitive) => { + if (primitive instanceof Cesium.GroundPolylinePrimitive) + primitives.push(primitive); + else if (primitive?.length !== undefined && primitive.get) + for (let i = 0; i < primitive.length; i++) visit(primitive.get(i)); + }; + visit(host); + assert.equal(primitives.length, 1); + const material = primitives[0].appearance.material; + assert.equal(material.type, 'DrawAgedLine_solid'); + assert.equal(material.uniforms.ageByLength, 1); +}); + +test('an aged line built anew lets its old material go once its primitive is gone', () => { + const { part, scene, frameAt } = agedDraw(); + const set = part.port.lines({ id: 'trails' }); + const deep = (times) => ({ + ...trail(along(3), times), + depthFail: { kind: 'solid', color: '#ffffff' }, + }); + set.set([deep([T0, T0 + 1, T0 + 2])]); + const record = part.sets.get('trails'); + assert.equal(record.ages.size, 2, 'its line and the part behind the surface'); + const [old] = record.ages.keys(); + set.upsert([deep([T0 + 1, T0 + 2, T0 + 3])]); + frameAt(T0 + 10); + assert.ok(old.isDestroyed(), 'the old material went with its primitive'); + assert.equal(record.ages.size, 2); + void scene; +}); + +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' }); + lines.set([trail(along(3), [T0])]); + const material = collectionOf(plain.scene).get(0).material; + assert.equal(material.type, 'Color', 'drawn as its style alone'); + + const { part } = agedDraw(); + const set = part.port.lines({ id: 'trails' }); + assert.throws( + () => set.set([trail(along(3), [T0, T0])]), + TypeError, + 'one time a position', + ); + assert.throws( + () => set.set([trail(along(2), [T0, T0], { windowMs: 0 })]), + TypeError, + 'a positive window', + ); + assert.throws( + () => set.set([trail(along(2), [T0, T0], { widthFloor: 2 })]), + TypeError, + 'floors from 0 to 1', + ); + assert.equal(set.size(), 0, 'nothing changed'); +}); diff --git a/src/render/cesium/harness.js b/src/render/cesium/harness.js index d09773aa53..472d4f4595 100644 --- a/src/render/cesium/harness.js +++ b/src/render/cesium/harness.js @@ -72,6 +72,7 @@ export const CESIUM_CHECKS = new Set([ 'draw.lines.drape', 'draw.lines.split', 'draw.lines.outlineDraped', + 'draw.lines.ageFade', 'draw.lines.segments', 'draw.lines.segmentStyles', 'draw.sets.blend', diff --git a/src/render/cesium/ports.js b/src/render/cesium/ports.js index 3519711030..491f278cf6 100644 --- a/src/render/cesium/ports.js +++ b/src/render/cesium/ports.js @@ -83,6 +83,9 @@ export function cesiumCapabilities(scene, only) { 'meshes', // Raster shells; other field kinds are refused. 'fields', + // Lines faded with age in their material, from a floating-point + // texture of their points' times (`draw.js`). + ...(scene?.context?.floatingPointTexture ? ['lineAgeFade'] : []), '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 c40e0209fd..f167082aad 100644 --- a/src/render/conformance/checks/ports.js +++ b/src/render/conformance/checks/ports.js @@ -3453,6 +3453,99 @@ export function portChecks() { } }, ), + check( + 'draw.lines.ageFade', + 'a line, draped or not, fades with the age of its points as scene 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-age-fade' }); + 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] }, + // Its west end a minute old at t0, its east end new. + ageFade: { + times: [t0 - 60_000, t0], + windowMs: 60_000, + alphaFloor: 0, + }, + }); + // Unfaded but narrowed to a quarter of its width where it is old. + const narrowed = { + ...line('narrowed', 0.0035, '3d'), + ageFade: { + times: [t0 - 60_000, t0], + windowMs: 60_000, + alphaFloor: 1, + widthFloor: 0.25, + }, + }; + lines.set([ + line('air', 0.002, '3d'), + line('ground', -0.002, 'draped'), + narrowed, + ]); + // Whether the line at `dLon` is drawn green there, strongly, `dy` + // pixels off its middle. + const green = (dLon, dLat, dy = 0) => { + 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) + dy, + 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], + ]) { + ok(green(0.0035, dLat), `${what}: its new end drawn`); + ok(!green(-0.0035, dLat), `${what}: its old end faded`); + } + ok(green(-0.0035, 0.0035), 'narrowed: its old end drawn, unfaded'); + ok(green(0.0035, 0.0035, 6), 'narrowed: its new end full width'); + ok( + !green(-0.0035, 0.0035, 6), + 'narrowed: its old end a quarter as wide', + ); + // Two minutes on, all of it is old; back at t0 its new end is new. + r.frame.setTime(t0 + 120_000); + await drawn(h, r); + ok(!green(0.0035, 0.002), '3d: faded as time moved on'); + ok(!green(0.0035, -0.002), 'draped: faded as time moved on'); + r.frame.setTime(t0); + await drawn(h, r); + ok(green(0.0035, 0.002), '3d: new again back at t0'); + ok(green(0.0035, -0.002), 'draped: new again back at t0'); + equal(lines.size(), 3, 'never sent again'); + } finally { + lines.dispose(); + } + }, + { capability: 'lineAgeFade' }, + ), 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 58b4e502d3..0c1153d830 100644 --- a/src/render/contract/common.d.ts +++ b/src/render/contract/common.d.ts @@ -207,6 +207,8 @@ export type Capability = | 'fields' /** Rate-limited course easing (`IconItem.courseGlide`). */ | 'courseGlide' + /** Lines that fade with the age of their points (`LineItem.ageFade`). */ + | 'lineAgeFade' /** 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 5372aba3db..29139795da 100644 --- a/src/render/contract/draw.d.ts +++ b/src/render/contract/draw.d.ts @@ -295,6 +295,34 @@ export type LineStyle = rim?: { shade: number; widthFraction: number }; }; +/** + * `lineAgeFade`: a line that fades with the age of its points, drawn by the + * renderer on the scene clock (`frame.setTime`), so a line whose points stay + * where they are is not sent again as time passes. A point's recency is + * `1 - clamp((now - time) / windowMs, 0, 1)`, its time running evenly + * between neighbouring positions, so the fade is smooth along the line, not + * stepped at its points. The line's colour (its style's, or a segment's from + * `segmentColors`) draws at its alpha times + * `mix(alphaFloor, 1, smoothstep(0, 1, recency))`, and with + * `squaredAlphaFloor` times `mix(squaredAlphaFloor, 1, recency²)` as well; + * with `widthFloor` it draws `widthPx` times `mix(widthFloor, 1, recency)` + * 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. + */ +export interface LineAgeFade { + /** Each position's time, epoch ms on the scene clock: one per position. */ + times: number[] | Float64Array; + /** The age a point fades over, ms; positive. */ + windowMs: number; + /** A fully aged point's alpha multiplier, 0..1. */ + alphaFloor: number; + /** A second alpha multiplier's floor, eased by recency squared, 0..1. */ + squaredAlphaFloor?: number; + /** A fully aged point's width multiplier, 0..1 [1, no narrowing]. */ + widthFloor?: number; +} + export interface LineItem { id: string; /** ECEF positions, or packed `x, y, z` triples. */ @@ -321,6 +349,8 @@ export interface LineItem { segmentShow?: boolean[]; /** Draw only the first fraction of the line, 0..1. */ revealFraction?: number; + /** `lineAgeFade`: fade the line with the age of its points (`LineAgeFade`). */ + ageFade?: LineAgeFade; /** Positions are in a frame rotating with the sky (orbits). */ frame?: 'fixed' | 'inertial'; meta?: Meta; diff --git a/src/render/contract/index.js b/src/render/contract/index.js index de2a712ac9..66ec77688f 100644 --- a/src/render/contract/index.js +++ b/src/render/contract/index.js @@ -41,6 +41,7 @@ export const CAPABILITIES = Object.freeze([ 'meshes', 'fields', 'courseGlide', + 'lineAgeFade', 'cluster', 'styles', 'bloom', diff --git a/src/render/stub/stub.test.mjs b/src/render/stub/stub.test.mjs index 04517dd6fe..5965124fdc 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 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 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', @@ -29,6 +29,7 @@ test('the stub passes the conformance suite', async () => { 'draw.sets.blend', 'draw.lines.split', 'draw.lines.outlineDraped', + 'draw.lines.ageFade', 'draw.models.blend', 'draw.models.paint', 'globe.imagery.video',