From c87bd38d184b6508ecef648512f59d66b3475e1e Mon Sep 17 00:00:00 2001 From: Sameh Khamis Date: Sun, 8 Nov 2026 14:19:52 -0800 Subject: [PATCH] Add fields' alpha, paused, shell detail and a drawn event, in the contract and the stub windStreamlines takes alpha and paused; rasterShell replaces detailWindow with a detail image and rectangle and says how shells stack, blend and update; FieldHandle.on('drawn') says once per change that it is drawn, never while hidden. The stub fires it on the render after a change, and a conformance check covers it. The Cesium adapter has no fields yet. --- docs/RENDERER-CONTRACT.md | 8 ++++ src/render/conformance/checks/ports.js | 65 ++++++++++++++++++++++++++ src/render/contract/draw.d.ts | 26 +++++++++-- src/render/stub/index.js | 31 +++++++++++- 4 files changed, 126 insertions(+), 4 deletions(-) diff --git a/docs/RENDERER-CONTRACT.md b/docs/RENDERER-CONTRACT.md index 3fd1941ec..50c24bbfe 100644 --- a/docs/RENDERER-CONTRACT.md +++ b/docs/RENDERER-CONTRACT.md @@ -53,6 +53,14 @@ optional, so a renderer written before it still conforms: normals) that only darkens, at most `strength` opacity. The Cesium port draws it as a globe material it takes only while no one else holds the globe's material; it has no `relief` kind. +- Fields: `windStreamlines` takes `alpha` (changed without a rebuild) and + `paused`; `rasterShell` replaces `detailWindow` with + `detail: {image, rectangle}`, a sharper image drawn in place of the base + 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. - `camera.on('changed', cb, { threshold })` measures each listener by its own threshold under the capability `cameraChangeThreshold`; a renderer without it fires every `changed` listener at 0.5. diff --git a/src/render/conformance/checks/ports.js b/src/render/conformance/checks/ports.js index b7bacfe75..7580d252b 100644 --- a/src/render/conformance/checks/ports.js +++ b/src/render/conformance/checks/ports.js @@ -721,6 +721,71 @@ export function portChecks() { stack.dispose(); }, ), + check( + 'draw.field.rasterShell', + "a shell's 'drawn' comes once per change, never while hidden", + async (h, r) => { + await overAustin(h, r, 20000); + const svg = (fill) => ({ + svg: ``, + }); + const errors = []; + const offError = r.on('error', (e) => errors.push(e)); + const field = r.draw.field({ + kind: 'rasterShell', + id: 'conf:shell', + image: svg('#0a84ff'), + rectangle: { west: -98.5, south: 29.5, east: -97, north: 31 }, + heightM: 8000, + alpha: 0.6, + }); + 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({ image: svg('#ff3b30') }); + await until(2); + equal(drawnCount, 2, 'drawn after a new image'); + field.update({ alpha: 0.3 }); + await until(3); + equal(drawnCount, 3, 'drawn after a new alpha'); + field.show = false; + field.update({ liftM: 500 }); + await drawn(h, r, 6); + equal(drawnCount, 3, 'never while hidden'); + field.show = true; + await until(4); + equal(drawnCount, 4, 'drawn once shown again'); + await drawn(h, r, 4); + equal(drawnCount, 4, 'and only once'); + deepEqual(errors, [], 'no errors'); + await listenerRules( + r, + "field.on('drawn')", + (cb) => field.on('drawn', cb), + async () => { + const want = drawnCount + 1; + field.update({ alpha: drawnCount % 2 ? 0.4 : 0.5 }); + await until(want); + }, + ); + } finally { + off(); + offError(); + field.dispose(); + } + }, + { capability: 'fields' }, + ), check( 'draw.drawOrder', 'of sets drawn over depth, the higher draw order is on top and picked', diff --git a/src/render/contract/draw.d.ts b/src/render/contract/draw.d.ts index cc96a7ceb..6378fb212 100644 --- a/src/render/contract/draw.d.ts +++ b/src/render/contract/draw.d.ts @@ -407,6 +407,10 @@ export type FieldSpec = style: { color: Color; widthPx: number; speedFactor?: number }; /** Draw height, metres; omitted drapes on the surface. */ heightM?: number; + /** 0..1, changeable without a rebuild (fade by height). */ + alpha?: number; + /** Draw the paths still, dimmed. */ + paused?: boolean; } | { kind: 'scalarRaster'; @@ -420,20 +424,36 @@ export type FieldSpec = alpha?: number; } | { + /** + * A raster on a sphere raised above the ground. Shells draw in + * ascending `heightM`, alpha-blended and unlit; they are never picked + * and never in height queries. Changing `liftM` or `alpha` never + * rebuilds. An `update` that changes `image`, `rectangle` or `detail` + * keeps drawing what it drew until the new content can be drawn whole. + */ kind: 'rasterShell'; id: string; - /** A raster on a sphere raised above the ground. */ image: ImageRef; rectangle: GeoRect; heightM: number; liftM?: number; - /** Full detail inside this rectangle only. */ - detailWindow?: GeoRect; + /** + * A sharper image drawn in place of `image` inside its own + * `rectangle`, never blended with it; null or omitted: none. + */ + detail?: { image: ImageRef; rectangle: GeoRect } | null; alpha?: number; }; export interface FieldHandle extends Handle { update(patch: Partial): void; + /** + * `fields`: what the spec or the last `update` asked for is drawn now. + * Once per such change; never while hidden. Changes made before one is + * drawn (the spec and updates, or updates while hidden) are told once, + * when the latest is drawn. + */ + on(event: 'drawn', cb: () => void): Off; } export type CelestialSpec = diff --git a/src/render/stub/index.js b/src/render/stub/index.js index 8f058fd77..0d0e2e1ad 100644 --- a/src/render/stub/index.js +++ b/src/render/stub/index.js @@ -509,10 +509,39 @@ export function createStubRenderer(options = {}) { if (capabilities.has('fields')) draw.field = (spec) => { const handle = simpleHandle('field', spec); + const record = sets.get(spec.id); + // 'drawn': once the next render after the spec or an update has drawn + // it, while it shows. + const drawnListeners = []; + let owed = true; + const key = { field: spec.id }; + frameFlushes.set(key, () => { + if (!owed || !record.show || sets.get(spec.id) !== record) return; + owed = false; + deliver(drawnListeners); + }); + const dispose = handle.dispose; + handle.dispose = () => { + frameFlushes.delete(key); + for (const entry of drawnListeners) entry.live = false; + drawnListeners.length = 0; + dispose(); + }; handle.update = (patch) => { - Object.assign(sets.get(spec.id).spec, patch); + Object.assign(record.spec, patch); + owed = true; requestRender('draw'); }; + handle.on = (event, cb) => { + if (event !== 'drawn') return () => {}; + const entry = { cb, live: true }; + drawnListeners.push(entry); + return () => { + entry.live = false; + const i = drawnListeners.indexOf(entry); + if (i >= 0) drawnListeners.splice(i, 1); + }; + }; return handle; }; if (capabilities.has('celestial'))