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'))