diff --git a/docs/RENDERER-CONTRACT.md b/docs/RENDERER-CONTRACT.md index 50c24bbfe..ef692e542 100644 --- a/docs/RENDERER-CONTRACT.md +++ b/docs/RENDERER-CONTRACT.md @@ -61,6 +61,11 @@ optional, so a renderer written before it still conforms: 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. +- `ModulationSector` gains `radius` and `floor` and says what it modulates: + icons, points and models dimmed toward `floor` outside the band, the map, + lines and shapes as they are, picks unchanged. Its pass is named + `screenModulation`. This changes `screenModulation` itself; only the stub + lists it, and the Cesium adapter does not draw it 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 7580d252b..06b52b18d 100644 --- a/src/render/conformance/checks/ports.js +++ b/src/render/conformance/checks/ports.js @@ -879,6 +879,78 @@ export function portChecks() { }, { capability: 'styles' }, ), + check( + 'effects.screenModulation', + 'a sector draws its pass, asks for a frame, and leaves picks alone', + async (h, r) => { + await overAustin(h, r); + const set = r.draw.icons({ id: 'conf:pick-swept' }); + const pos = h.toEcef({ + lon: AUSTIN.lon + 0.004, + lat: AUSTIN.lat, + height: 0, + }); + const passes = () => r.effects.diagnostics().passes; + // The sweep stands 100 px left of the icon and points up, so the + // icon is outside the band, dimmed all the way. + const sector = (s) => ({ + center: { x: s.x - 100, y: s.y }, + angle: 0, + width: 0.3, + radius: 400, + floor: 0, + strength: 0.6, + color: '#00ff88', + }); + // Whether one tick after `change`, with nothing else asked of it, + // draws: from idle, which is asserted first. + const drawsOnItsOwn = async (change) => { + deepEqual(await idleWatch(h, r, 1), [['u', false]], 'idle first'); + let rendered = false; + const off = r.frame.on('postRender', () => (rendered = true)); + try { + change(); + await h.frame(r); + } finally { + off(); + } + return rendered; + }; + const demand = r.frame.mode() !== 'continuous'; + try { + set.set([{ id: 'one', pos, image: DOT, size: [24, 24] }]); + await drawn(h, r); + await settled(r); + const s = r.query.project(pos); + ok(s, 'the icon projects'); + const before = r.query.pick(s.x, s.y); + equal(before?.id, 'one', 'the icon picks'); + equal(passes().includes('screenModulation'), false, 'off at first'); + const setSector = () => r.effects.screenModulation(sector(s)); + if (demand) + ok(await drawsOnItsOwn(setSector), 'setting asks for a frame'); + else setSector(); + await drawn(h, r); + ok(passes().includes('screenModulation'), 'the pass draws'); + const hit = r.query.pick(s.x, s.y); + deepEqual( + [hit?.set, hit?.id], + [before.set, before.id], + 'a dimmed icon picks as before', + ); + const clear = () => r.effects.screenModulation(null); + if (demand) + ok(await drawsOnItsOwn(clear), 'clearing asks for a frame'); + else clear(); + await drawn(h, r); + equal(passes().includes('screenModulation'), false, 'gone on null'); + } finally { + r.effects.screenModulation(null); + set.dispose(); + } + }, + { capability: 'screenModulation' }, + ), check( 'draw.motion', 'icons move by their segments on the set\u2019s motion clock', diff --git a/src/render/contract/effects.d.ts b/src/render/contract/effects.d.ts index c126fa4b3..0795e2d5e 100644 --- a/src/render/contract/effects.d.ts +++ b/src/render/contract/effects.d.ts @@ -40,7 +40,17 @@ export interface StyleDefinition extends StyleDescriptor { shader: StyleShader; } -/** A sweeping sector drawn over the frame (a sonar band), or null. */ +/** + * `screenModulation`: a sweeping band over the drawn markers (a sonar). + * Icons, points and models are dimmed toward `floor` and brought back to + * full inside the band, each by where its anchor is on screen; the map, + * lines and shapes draw as they are, and picks are unchanged. A radius of 0 + * dims every marker to `floor` (the theme on, the sweep off). Setting a + * sector, or clearing it, asks for one frame; the app sets it again at + * `sonarCadenceHz`. + * `diagnostics().passes` lists `'screenModulation'` while it draws, so a + * sector set but not listed is unsupported. + */ export interface ModulationSector { /** Centre of the sweep, CSS pixels. */ center: { x: number; y: number }; @@ -48,7 +58,11 @@ export interface ModulationSector { angle: number; /** Width of the band, radians. */ width: number; - /** 0..1. */ + /** Reach of the band from `center`, CSS pixels. */ + radius: number; + /** Alpha factor outside the band, 0..1. */ + floor: number; + /** 0..1: how far a marker's colour is pulled toward `color`. */ strength: number; color: string; } diff --git a/src/render/stub/index.js b/src/render/stub/index.js index 0d0e2e1ad..7d02093ae 100644 --- a/src/render/stub/index.js +++ b/src/render/stub/index.js @@ -1368,7 +1368,7 @@ export function createStubRenderer(options = {}) { .map((s) => `style:${s.id}`), ...(effectState.bloom?.enabled ? ['bloom'] : []), ...(effectState.sharpen?.enabled ? ['sharpen'] : []), - ...(effectState.modulation ? ['modulation'] : []), + ...(effectState.modulation ? ['screenModulation'] : []), ], }), on(event, cb) {