Files
gods-eye-view/src/render/cesium/screenModulation.js
T
Sameh Khamis 85a04b1367 Cesium effects port draws screenModulation, the marker sweep
The adapter's effects port now has screenModulation: a contract sector
shades points, billboards (labels among them) and icon sets in their own
vertex shaders, swapped into this scene's command list as the primitives
update, and tints models on the CPU after every owner has written its
colour. Geometry and picks are unchanged. It is the sweep the cyber HUD
already draws, carried into src/render/cesium/screenModulation.js and
driven by a sector instead of document settings; nothing is installed
until a sector is set, and disposal gives everything back.

The capability is advertised on the Cesium version the command swap is
tested against; diagnostics list the pass while it draws, and listeners
hear when it starts or stops (a native shader it cannot take stops it).
A set asks for a frame unless it changes nothing drawn: the same sector,
or only the angle of a sweep while no shaded marker was in view.

cyberSonarSector() gives the sector for the cyber sweep; the app switches
to the port in the next commit.

Conformance: the screenModulation check runs on Cesium; new checks read
the pixels (in the band an icon draws, outside it and at radius 0 it dims
to the floor, strength 1 draws it in the colour, clearing restores it) and
check the member is absent without the capability.
2026-11-09 05:27:54 -08:00

673 lines
24 KiB
JavaScript

/**
* @module render/cesium/screenModulation
* @description The Cesium effects port's `screenModulation`
* (`src/render/contract/effects.d.ts`): a sweeping band over the drawn
* markers. It is not a full-screen stage, since the map, lines and shapes
* must draw as they are: each marker is shaded by where its anchor is on
* screen.
*
* - Points, billboards (labels among them) and icon sets: their draw
* commands in this scene's command list are swapped, as the scene's
* primitives update, for derived commands whose vertex shader runs the
* native one and then scales the colour by the band. `gl_Position` is
* left alone, so geometry and picks are unchanged (pick passes keep the
* native commands). Cesium has no public shader hook for these
* collections, so the swap is tested against one Cesium version
* (`SCREEN_MODULATION_CESIUM_VERSION`); on any other, or once a native
* shader it does not know turns up, it draws nothing and the pass is not
* listed.
* - Models: their colour is set each drawn frame, after every owner has
* written its own (the walk is the last `preRender` listener), and the
* owner's colour is given back when the sector goes.
*
* The band: full at `angle`, fading over the last part of `width` (at most
* 10 degrees, at most 42% of it) clockwise from there, and full inside a
* small disc at `center` (2.5% of `radius`). A marker's colour is pulled by
* `strength` toward a cool grey outside the band and toward `color` inside
* it; at a radius of 0 every marker is pulled toward `color`. Labels keep
* half of what the band takes away, and their backgrounds keep their
* colour.
*
* Render demand: a set asks for a frame, except one that changes nothing
* drawn: the same sector again, or one that only moves the angle (of a
* sweeping band) while the last drawn frame had no shaded marker in view.
* The sweep then needs no frames of its own; a frame drawn for anything
* else draws the latest sector.
*/
import * as Cesium from 'cesium';
import { IconSetPrimitive } from './iconSetPrimitive.js';
/** The Cesium version the command swap is tested against. */
export const SCREEN_MODULATION_CESIUM_VERSION = '1.138.0';
/** Whether this Cesium can draw the pass at all. */
export const screenModulationSupported = () =>
Cesium.VERSION === SCREEN_MODULATION_CESIUM_VERSION;
/** The colour markers outside the band are pulled toward. */
const DIM_TINT = Object.freeze([0.62, 0.68, 0.72]);
const FEATHER_DEG = 10;
const FEATHER_SHARE = 0.42;
/** The full disc at the centre, as a share of the radius. */
const CORE_SHARE = 0.025;
const DEG = 180 / Math.PI;
const clamp01 = (value) => Math.min(1, Math.max(0, value));
const finite = (value, fallback = 0) =>
Number.isFinite(Number(value)) ? Number(value) : fallback;
/**
* A contract sector as the pass uses it: degrees, the colour as channels.
* @param {import('../contract/effects').ModulationSector} sector
*/
export function normalizeSector(sector) {
const color =
Cesium.Color.fromCssColorString(String(sector.color ?? '')) ??
Cesium.Color.WHITE;
return {
cx: finite(sector.center?.x),
cy: finite(sector.center?.y),
angle: (((finite(sector.angle) * DEG) % 360) + 360) % 360,
width: Math.max(0, finite(sector.width) * DEG),
radius: Math.max(0, finite(sector.radius)),
floor: clamp01(finite(sector.floor, 1)),
strength: clamp01(finite(sector.strength)),
rgb: [color.red, color.green, color.blue],
};
}
/** Whether two normalized sectors differ in more than their angle. */
const differsBeyondAngle = (a, b) =>
!a ||
!b ||
a.cx !== b.cx ||
a.cy !== b.cy ||
a.width !== b.width ||
a.radius !== b.radius ||
a.floor !== b.floor ||
a.strength !== b.strength ||
a.rgb.some((c, i) => c !== b.rgb[i]);
/**
* The band's factor and tint at CSS pixels, for what is shaded on the CPU
* (models). The GPU pass computes the same in its vertex shader.
* @param {ReturnType<typeof normalizeSector>} s
*/
export function sectorSampler(s) {
const radiusSquared = s.radius * s.radius;
const feather = Math.min(FEATHER_DEG, s.width * FEATHER_SHARE);
const sweeping = s.radius > 0;
return {
floor: s.floor,
/** Equal for samplers that tint alike (the angle aside). */
key: `${s.floor}|${s.strength}|${s.rgb.join(',')}|${sweeping}`,
at(x, y) {
if (!Number.isFinite(x) || !Number.isFinite(y)) return 1;
if (!sweeping) return s.floor;
const dx = x - s.cx;
const dy = y - s.cy;
const distanceSquared = dx * dx + dy * dy;
if (distanceSquared > radiusSquared) return s.floor;
if (distanceSquared < radiusSquared * CORE_SHARE * CORE_SHARE) return 1;
const delta = (((Math.atan2(dx, -dy) * DEG - s.angle) % 360) + 360) % 360;
if (delta > s.width) return s.floor;
return (
s.floor +
(1 - s.floor) * Math.min(1, (s.width - delta) / (feather || 1))
);
},
/** How far toward `color` (from the grey) a factor tints. */
coverage(factor) {
if (!sweeping || s.floor >= 0.9999) return 1;
return clamp01((factor - s.floor) / (1 - s.floor));
},
tint(base, factor, out) {
const c = this.coverage(factor);
const k = s.strength;
out.red =
base.red * (1 - k) + (DIM_TINT[0] + (s.rgb[0] - DIM_TINT[0]) * c) * k;
out.green =
base.green * (1 - k) + (DIM_TINT[1] + (s.rgb[1] - DIM_TINT[1]) * c) * k;
out.blue =
base.blue * (1 - k) + (DIM_TINT[2] + (s.rgb[2] - DIM_TINT[2]) * c) * k;
return out;
},
};
}
// Follow every public DrawCommand setter, including pick/shadow/culling flags.
// Copying native.dirty would keep derived pipelines dirty forever: the scene
// consumes our command, so it never clears that flag on the native command.
const commandProperties = Object.entries(
Object.getOwnPropertyDescriptors(Cesium.DrawCommand.prototype),
)
.filter(
([key, descriptor]) =>
descriptor.set && key !== 'shaderProgram' && key !== 'uniformMap',
)
.map(([key]) => key);
/**
* The derived command for `native`, kept in `record` across frames: every
* native field followed, its own program and the pass's uniforms.
*/
export function syncModulatedCommand(
native,
record,
program,
uniforms,
labelBackground,
) {
if (!record.command) {
record.command = new Cesium.DrawCommand();
record.uniformMap = {
...uniforms,
u_gevSonarLabelBackground: () => record.labelBackground,
};
}
const command = record.command;
record.labelBackground = labelBackground;
// Uniform values (angle/viewport/etc.) change through stable callbacks, not
// new maps/functions. Owner callback replacement and removal still propagate.
for (const key in record.uniformMap) {
if (
!(key in uniforms) &&
key !== 'u_gevSonarLabelBackground' &&
!(key in native.uniformMap)
) {
delete record.uniformMap[key];
command.dirty = true;
}
}
for (const key in native.uniformMap) {
if (record.uniformMap[key] !== native.uniformMap[key]) {
record.uniformMap[key] = native.uniformMap[key];
command.dirty = true;
}
}
for (const key of commandProperties) command[key] = native[key];
command.shaderProgram = program;
command.uniformMap = record.uniformMap;
return command;
}
/**
* The native vertex shader with the band applied after it, or null for a
* shader the pass does not know.
* @param {object} source A Cesium ShaderSource.
* @param {'point'|'billboard'|'icon'} kind
*/
export function modulationVertexSource(source, kind) {
const text = source.sources.join('\n');
const attribute =
kind === 'point' ? 'positionHighAndSize' : 'positionHighAndScale';
const lowAttribute =
kind === 'point' ? 'positionLowAndOutline' : 'positionLowAndRotation';
// Icon sets move rows on the GPU, so their shader publishes the anchor itself.
const anchorSource =
kind === 'icon'
? 'iconAnchorClip'
: `czm_modelViewProjectionRelativeToEye * czm_translateRelativeToEye(${attribute}.xyz, ${lowAttribute}.xyz)`;
if (
(kind === 'icon'
? !text.includes('iconAnchorClip')
: !text.includes(attribute) || !text.includes(lowAttribute)) ||
!text.includes('v_color') ||
!/void\s+main\s*\(\s*\)/.test(text)
)
return null;
const next = source.clone();
next.sources = [
text.replace(/void\s+main\s*\(\s*\)/, 'void gev_sonar_main()'),
`
uniform vec4 u_gevSonar; // angle, radius, opacity floor, sweep enabled
uniform vec2 u_gevSonarViewport;
uniform vec2 u_gevSonarCenter;
uniform float u_gevSonarSector;
uniform vec4 u_gevSonarTint; // colour, strength
uniform float u_gevSonarLabelBackground;
void main() {
gev_sonar_main();
// All corners/glyphs share the contact anchor, before native screen offsets.
// Leave gl_Position untouched so appearance never changes geometry or picks.
vec4 anchor = ${anchorSource};
if (anchor.w <= 0.0) return;
vec2 pixel = anchor.xy / anchor.w * u_gevSonarViewport * 0.5 - u_gevSonarCenter;
float floorValue = u_gevSonar.z;
float factor = floorValue;
if (u_gevSonar.w > 0.5) {
float distanceSquared = dot(pixel, pixel);
float radiusSquared = u_gevSonar.y * u_gevSonar.y;
float delta = mod(degrees(atan(pixel.x, pixel.y)) - u_gevSonar.x + 360.0, 360.0);
if (delta > 359.9999) delta = 0.0;
if (distanceSquared < radiusSquared * ${(CORE_SHARE * CORE_SHARE).toFixed(6)}) factor = 1.0;
else if (distanceSquared <= radiusSquared && delta <= u_gevSonarSector)
factor += (1.0 - floorValue) * min(1.0, (u_gevSonarSector - delta) / max(min(${FEATHER_DEG.toFixed(1)}, u_gevSonarSector * ${FEATHER_SHARE}), 1e-4));
}
#ifdef SDF
factor = (1.0 + factor) * 0.5;
#else
if (u_gevSonarLabelBackground > 0.5) factor = (1.0 + factor) * 0.5;
#endif
float coverage = (u_gevSonar.w < 0.5 || floorValue >= 0.9999) ? 1.0 : clamp((factor - floorValue) / (1.0 - floorValue), 0.0, 1.0);
if (u_gevSonarLabelBackground < 0.5)
v_color.rgb = v_color.rgb * (1.0 - u_gevSonarTint.a) + mix(vec3(${DIM_TINT.join(', ')}), u_gevSonarTint.rgb, coverage) * u_gevSonarTint.a;
// Apply before native fragment pass classification, never after main().
v_color.a *= factor;
${kind === 'point' ? 'v_outlineColor.a *= factor;' : kind === 'icon' ? '' : '#ifdef SDF\n v_outlineColor.a *= factor;\n #endif'}
}
`,
];
return next;
}
/**
* Whether a command's batch may be in view: its bounds against the frame's
* culling planes (the far plane left out, as Cesium's frustum builder does,
* since a batch fits several frusta) and the horizon.
*/
export function isModulatedCommandVisible(command, frameState, culling) {
const bounds = command.boundingVolume;
if (!bounds || !command.cull) return true;
culling ??= new Cesium.CullingVolume(
frameState.cullingVolume.planes.slice(0, 5),
);
if (culling.computeVisibility(bounds) === Cesium.Intersect.OUTSIDE)
return false;
return !(
frameState.mode === Cesium.SceneMode.SCENE3D &&
frameState.occluder &&
command.occlude &&
bounds.isOccluded(frameState.occluder)
);
}
const alive = (value) => value && !value.isDestroyed?.();
/**
* Calls `visit(model, visible)` for each model under `primitive`, nested
* collections included, without walking the markers of any collection.
*/
export function visitModels(primitive, visit, visible = true) {
if (!alive(primitive)) return;
visible = visible && primitive.show !== false;
if (primitive instanceof Cesium.PrimitiveCollection) {
for (let i = 0; i < primitive.length; i++)
visitModels(primitive.get(i), visit, visible);
} else if (primitive instanceof Cesium.Model) {
visit(primitive, visible && primitive.ready);
}
}
const sameColor = (a, b) =>
a &&
b &&
a.red === b.red &&
a.green === b.green &&
a.blue === b.blue &&
a.alpha === b.alpha;
/**
* Model colours set by the pass, each over its owner's: a colour the owner
* writes since is the new base, and the owner's comes back on restore.
*/
export function createModelTint() {
const states = new Map();
return {
get size() {
return states.size;
},
/** Shades `model` by `factor` (models stay opaque: RGB dims, not alpha). */
apply(model, factor, sampler) {
const current = model.color;
let state = states.get(model);
const owns = state && sameColor(current, state.applied);
if (!owns) {
const base = current
? Cesium.Color.clone(current)
: new Cesium.Color(1, 1, 1, 1);
state = {
base,
undefinedBase: current === undefined,
applied: null,
factor: Number.NaN,
key: null,
};
states.set(model, state);
} else if (
Math.abs(factor - state.factor) <= 0.002 &&
state.key === sampler.key
) {
return;
}
const next = sampler.tint(state.base, factor, new Cesium.Color());
next.red *= factor;
next.green *= factor;
next.blue *= factor;
// Keep models in their owner's opaque/translucent render pass.
next.alpha = state.base.alpha;
model.color = next;
// Cesium copies on set; compare against what it holds.
state.applied = Cesium.Color.clone(model.color ?? next);
state.factor = factor;
state.key = sampler.key;
},
/** Gives `model` its owner's colour back, unless the owner wrote since. */
restore(model) {
const state = states.get(model);
if (!state) return;
states.delete(model);
if (!alive(model)) return;
if (sameColor(model.color, state.applied))
model.color = state.undefinedBase ? undefined : state.base;
},
restoreAll() {
for (const model of [...states.keys()]) this.restore(model);
},
keys: () => states.keys(),
};
}
/**
* @param {object} scene A Cesium scene.
* @param {{
* frame: {requestRender: (reason?: string) => void},
* onChange: () => void,
* }} options `onChange` runs when whether the pass draws changes on its own
* (a native shader it cannot take turns up).
*/
export function createCesiumScreenModulation(scene, { frame, onChange }) {
let sector = null;
let sampler = null;
let disposed = false;
let installed = null;
/** Whether the last drawn frame modulated a marker in view. */
let lastVisible = false;
const stats = {
commands: 0,
visibleCommands: 0,
models: 0,
programs: 0,
supported: screenModulationSupported(),
error: null,
};
const uniforms = new Cesium.Cartesian4();
const viewport = new Cesium.Cartesian2();
const center = new Cesium.Cartesian2();
const tint = new Cesium.Cartesian4();
let width = 24;
const passUniforms = {
u_gevSonar: () => uniforms,
u_gevSonarViewport: () => viewport,
u_gevSonarCenter: () => center,
u_gevSonarSector: () => width,
u_gevSonarTint: () => tint,
};
const draws = () => !disposed && stats.supported && sector !== null;
/** Installs the command swap and the model walk on first use. */
function install() {
const root = scene.primitives;
const original = root.update;
const programs = new Map();
let commands = new WeakMap();
const culling = new Cesium.CullingVolume();
const used = new Set();
const replaced = [];
const models = createModelTint();
const matrix = new Cesium.Matrix4();
const position = new Cesium.Cartesian3();
const release = () => {
for (const { program } of programs.values())
if (!program.isDestroyed()) program.destroy();
programs.clear();
commands = new WeakMap();
used.clear();
replaced.length = 0;
stats.programs = 0;
};
function fail(error) {
stats.supported = false;
stats.commands = 0;
stats.visibleCommands = 0;
stats.error = String(error?.message || error);
release();
// The frame drawing now has shaded models; the next one gives them back.
frame.requestRender('effects-modulation');
onChange();
}
const wrapped = function (frameState) {
const start = frameState.commandList.length;
original.call(this, frameState);
stats.commands = 0;
stats.visibleCommands = 0;
if (!frameState.passes.render || frameState.passes.pick) return;
if (!draws()) {
if (programs.size) release();
return;
}
const ratioX =
scene.drawingBufferWidth / (scene.canvas?.clientWidth || 1) || 1;
const ratioY =
scene.drawingBufferHeight / (scene.canvas?.clientHeight || 1) || 1;
viewport.x = scene.drawingBufferWidth;
viewport.y = scene.drawingBufferHeight;
center.x = sector.cx * ratioX - viewport.x / 2;
center.y = viewport.y / 2 - sector.cy * ratioY;
uniforms.x = sector.angle;
uniforms.y = sector.radius * ratioX;
uniforms.z = sector.floor;
uniforms.w = sector.radius > 0 ? 1 : 0;
width = sector.width;
tint.x = sector.rgb[0];
tint.y = sector.rgb[1];
tint.z = sector.rgb[2];
tint.w = sector.strength;
used.clear();
replaced.length = 0;
if (frameState.cullingVolume)
for (let i = 0; i < 5; i++)
culling.planes[i] = frameState.cullingVolume.planes[i];
try {
for (let i = start; i < frameState.commandList.length; i++) {
const native = frameState.commandList[i];
const kind =
native.owner instanceof Cesium.PointPrimitiveCollection
? 'point'
: native.owner instanceof Cesium.BillboardCollection
? 'billboard'
: native.owner instanceof IconSetPrimitive
? 'icon'
: null;
if (!kind || !native.shaderProgram || !native.uniformMap) continue;
const source = native.shaderProgram;
// Label backgrounds are non-SDF billboard batches. The version-tested
// engine pick association distinguishes them without enumerating
// labels or reaching into EntityCluster. One representative per draw
// batch; Cesium's label glyph/background collections are homogeneous.
const labelBackground =
kind === 'billboard' &&
!source.vertexShaderSource.defines.includes('SDF') &&
native.owner.length > 0 &&
native.owner.get(0).pickPrimitive instanceof Cesium.Label
? 1
: 0;
let entry = programs.get(source);
if (!entry) {
const vertex = modulationVertexSource(
source.vertexShaderSource,
kind,
);
if (!vertex) throw new Error('Unsupported native contact shader');
const attributes = Object.fromEntries(
Object.entries(source.vertexAttributes).map(([name, value]) => [
name,
value.index,
]),
);
const program = Cesium.ShaderProgram.fromCache({
context: frameState.context,
vertexShaderSource: vertex,
fragmentShaderSource: source.fragmentShaderSource,
attributeLocations: attributes,
});
// Compile while errors can still leave the whole native command
// slice intact, rather than stopping the render loop at draw time.
try {
void program.allUniforms;
} catch (error) {
program.destroy();
throw error;
}
programs.set(source, (entry = { program }));
}
used.add(source);
let record = commands.get(native);
if (!record) commands.set(native, (record = {}));
const derived = syncModulatedCommand(
native,
record,
entry.program,
passUniforms,
labelBackground,
);
replaced.push(i, native);
frameState.commandList[i] = derived;
stats.commands++;
if (isModulatedCommandVisible(native, frameState, culling))
stats.visibleCommands++;
}
for (const [source, entry] of programs)
if (!used.has(source)) {
if (!entry.program.isDestroyed()) entry.program.destroy();
programs.delete(source);
}
stats.programs = programs.size;
} catch (error) {
// Recover the original commands already replaced in this slice.
for (let i = 0; i < replaced.length; i += 2)
frameState.commandList[replaced[i]] = replaced[i + 1];
fail(error);
}
};
root.update = wrapped;
let epoch = 0;
const epochs = new WeakMap();
const shadeModels = () => {
if (!draws()) {
models.restoreAll();
stats.models = 0;
return;
}
const cssWidth = scene.canvas?.clientWidth ?? 0;
const cssHeight = scene.canvas?.clientHeight ?? 0;
Cesium.Matrix4.multiply(
scene.camera.frustum.projectionMatrix,
scene.camera.viewMatrix,
matrix,
);
epoch++;
let count = 0;
visitModels(scene.primitives, (model, visible) => {
if (!visible) {
models.restore(model);
return;
}
const p = Cesium.Matrix4.getTranslation(model.modelMatrix, position);
const w =
matrix[3] * p.x + matrix[7] * p.y + matrix[11] * p.z + matrix[15];
const x =
(matrix[0] * p.x + matrix[4] * p.y + matrix[8] * p.z + matrix[12]) /
w;
const y =
(matrix[1] * p.x + matrix[5] * p.y + matrix[9] * p.z + matrix[13]) /
w;
if (w <= 0 || Math.abs(x) > 1.1 || Math.abs(y) > 1.1) return;
epochs.set(model, epoch);
models.apply(
model,
sampler.at((x + 1) * cssWidth * 0.5, (1 - y) * cssHeight * 0.5),
sampler,
);
count++;
});
// Out of view or gone since the last frame: the owner's colour back.
for (const model of [...models.keys()])
if (epochs.get(model) !== epoch) models.restore(model);
stats.models = count;
};
// Owners write model colours in preRender (some after this was
// installed): shade after all of them and before the draw uploads,
// by taking the last preRender place again at every postUpdate.
let offShade = null;
const offUpdate = scene.postUpdate.addEventListener(() => {
offShade?.();
offShade = scene.preRender.addEventListener(shadeModels);
});
const offRendered = scene.postRender.addEventListener(() => {
lastVisible = draws() && (stats.visibleCommands > 0 || stats.models > 0);
});
return {
models,
dispose() {
offUpdate();
offShade?.();
offRendered();
if (root.update === wrapped && !root.isDestroyed?.())
root.update = original;
release();
models.restoreAll();
},
};
}
return {
stats,
draws,
/**
* Sets or clears the sector.
* @param {import('../contract/effects').ModulationSector | null} next
*/
set(next) {
if (disposed || scene.isDestroyed?.()) return;
const previous = sector;
sector = next ? normalizeSector(next) : null;
sampler = sector ? sectorSampler(sector) : null;
if (sector && !installed && stats.supported) installed = install();
if (!sector) {
lastVisible = false;
installed?.models.restoreAll();
stats.models = 0;
if (previous) frame.requestRender('effects-modulation');
return;
}
// The angle moves only a band that sweeps, and only shaded markers.
if (
differsBeyondAngle(previous, sector) ||
(lastVisible && sector.radius > 0 && sector.angle !== previous.angle)
)
frame.requestRender('effects-modulation');
},
dispose() {
if (disposed) return;
disposed = true;
const had = sector;
sector = null;
if (installed && !scene.isDestroyed?.()) {
installed.dispose();
// The last shaded frame is still on screen.
if (had) frame.requestRender('effects-modulation');
}
installed = null;
},
};
}