Files
gods-eye-view/src/ui/visualEffects.js
T
German Khokhlov 97c4dc76ce Move scene effects and imported geometry behind the globe contract
Move Cesium viewer, map, sky, projection, trail and sonar internals into
its engine. Drive styles, bloom, sharpening and contact sonar through
engine.render. Count camera-input suspensions across all three engines
and migrate the feature callers. Preserve Cesium's effects and input
behaviour; fix transit lens clicks on Cesium and make zero sharpening on
Navara disable sharpening, as it does on Cesium.

Parse imported files into plain records and draw them through movers,
lines, ground and imagery on both engines. Follow Cesium's KML style
precedence, preserve local KMZ images and frame the drawable records.
Open overlays use imagery when the engine has no native map-overlay API.
Run every imported-display case on fake and headless Cesium engines.

The shared import path retains these known differences from Cesium's old
DataSources: wall fills, extruded prisms and gx:LatLonQuad are undrawn;
raised polygon fills drape while outlines retain altitude; GroundOverlay
rotation, altitude and RGB tint are not applied; rhumb lines become great
circles. Ground heights use the loaded surface synchronously instead of
waiting for most-detailed sampling. Supported KMZ ground overlays now
draw on Navara too. Document the limits rather than claiming full parity.

Combine batches B and C because their disjoint path manifests cannot
place the shared boundary and format files in a later commit while
keeping B independently valid. This combined commit owns the shared
docs, package boundaries, format scope, locale catalogs and coupling
baseline. Remove five obsolete import strings from all eleven catalogs.
Make the load-time source scan include new files and skip deleted paths
so the same checks work before and after recording the moves.

Coupling: Navara renderer lines fall from 1695 to 1294, Cesium import
files from 25 to 9, viewer lines from 1177 to 1026, SDK loads from 4 to 3
and engine-name lines from 62 to 42. No count grows.

The full unit suite and the boundary, format and coupling checks pass.
Browser validation remains to be run.

Browser checks to run
GOOGLE_MAPS_API_KEY= CESIUM_ION_TOKEN= npm run dev -- --port 4291
node scripts/qa-contract-suite.mjs http://localhost:4291
node scripts/qa-navara-visual-styles.mjs http://localhost:4291
node scripts/qa-navara-bloom.mjs http://localhost:4291
node scripts/qa-navara-sonar.mjs http://localhost:4291
QA_BASE_URL=http://localhost:4291 node scripts/qa-visual-effects.mjs
QA_BASE_URL=http://localhost:4291 node scripts/qa-zoom-out-guard.mjs
node scripts/qa-sky-model-lighting.mjs --url http://localhost:4291
node scripts/qa-geo-import.mjs http://localhost:4291
node scripts/qa-geo-import-regressions.mjs http://localhost:4291
node scripts/qa-geo-import-large.mjs http://localhost:4291
node scripts/qa-navara-geo-import.mjs http://localhost:4291

Use the keyless server for every check. Photoreal-only cases remain
unverified; do not enable paid tiles to run them.
2026-11-07 12:45:21 +04:00

284 lines
9.6 KiB
JavaScript

import {
bloomStrengthFromIntensity,
clampBloomIntensity,
BLOOM_INTENSITY_DEFAULT,
} from '../bloom.js';
import {
STYLES,
TRANSITION_DURATION_MS,
sharpenAmount,
} from './visualPresets.js';
/**
* A style stage drawn by the globe engine (render.setStyle), in a Cesium
* post stage's { uniforms, enabled } shape, so the owner of the stages
* writes its uniforms as it wrote a stage's; each write reaches the engine.
* A value the engine refuses (NaN from an old link, say) stays here and is
* reported.
*/
function engineStyleStage(render, name, shader) {
const values = { intensity: 0 };
if (shader.fragmentShader.includes('uniform float time')) values.time = 0;
for (const [uniform, meta] of Object.entries(shader.uniforms || {}))
values[uniform] = meta.default;
const { intensity, ...uniforms } = values;
render.setStyle(name, { intensity, uniforms });
const forward = (key, value) => {
try {
if (key === 'intensity') render.setStyle(name, { intensity: value });
else render.setStyle(name, { uniforms: { [key]: value } });
} catch (error) {
console.warn(`The ${name} style refused ${key}=${value}:`, error);
}
};
return {
name: `godsEyeView_${name}`,
enabled: false,
uniforms: new Proxy(values, {
set(target, key, value) {
target[key] = value;
if (typeof key === 'string' && Object.hasOwn(values, key))
forward(key, value);
return true;
},
}),
};
}
/**
* Own the visual styles, bloom and sharpening and their animation, without
* DOM dependencies, on the globe engine that draws them (render.setStyle,
* render.setBloom, render.setSharpen: Cesium through its post stages,
* Navara in its pipeline).
*/
export class VisualEffects {
/**
* @param {object} options - The globe engine, render ownership callbacks
* and optional clocks. The styles and bloom reach the engine when it has
* them (the visualStyles and bloom capabilities); without an engine the
* controls change nothing. Construction is inert; initStyles and
* initPostProcess retain startup ordering.
*/
constructor({
engine = null,
requestRender,
holdRender,
releaseRender,
requestFrame = (callback) => requestAnimationFrame(callback),
cancelFrame = (id) => cancelAnimationFrame(id),
now = () => performance.now(),
wallNow = () => Date.now(),
}) {
this.engine = engine;
const render = engine?.render;
this.engineRender =
typeof render?.setSharpen === 'function' ? render : null;
// The visualStyles and bloom capabilities of src/globe/contract.js
// engineCapabilities, read by member: this package stays engine-free.
this.engineStyles =
Array.isArray(render?.visualStyles) &&
typeof render.setStyle === 'function' &&
typeof render.style === 'function'
? render
: null;
this.engineBloom =
typeof render?.setBloom === 'function' &&
typeof render.bloom === 'function'
? render
: null;
this.requestRender = requestRender;
this.holdRender = holdRender;
this.releaseRender = releaseRender;
this.requestFrame = requestFrame;
this.cancelFrame = cancelFrame;
this.now = now;
this.wallNow = wallNow;
this.stages = {};
this.transitions = new Map();
this.startTime = wallNow();
this.bloomEnabled = false;
this.sharpenEnabled = false;
this.bloomIntensity = BLOOM_INTENSITY_DEFAULT;
this.sharpenIntensity = 0.49;
this.postProcessReady = false;
// What the engine was last told about the sharpening: it starts off.
this.sharpenShown = false;
this.frameId = null;
this.stopped = false;
this.destroyed = false;
this.stageEntries = [];
}
// The styles the engine draws get stand-in stages (engineStyleStage),
// which start every style at 0 on it; an engine without them gets none
// and the style controls change nothing.
initStyles() {
if (this.stopped || this.stageEntries.length || !this.engineStyles) return;
const drawn = this.engineStyles.visualStyles;
for (const [name, shader] of Object.entries(STYLES))
if (drawn.includes(name))
this.stages[name] = engineStyleStage(this.engineStyles, name, shader);
this.stageEntries = Object.entries(this.stages);
}
initPostProcess(sharpenIntensity = this.sharpenIntensity) {
if (this.stopped || this.postProcessReady) return;
this.postProcessReady = true;
// The engine starts from this owner's bloom and sharpening (off),
// whatever a previous owner left on it.
this.engineBloom?.setBloom({
enabled: false,
strength: bloomStrengthFromIntensity(this.bloomIntensity),
});
this.sharpenShown = false;
this.engineRender?.setSharpen({ enabled: false });
this.applySharpenIntensity(sharpenIntensity);
}
setStageIntensity(stage, value) {
if (this.stopped || !stage) return;
// The engine fades its stars with Anime (render.setStyle).
stage.uniforms.intensity = value;
stage.enabled = value > 0.001;
if (stage.enabled && stage.uniforms.time !== undefined)
this.startAnimationLoop();
this.requestRender('style-stage');
}
syncStagesEnabledFromIntensity() {
for (const [, stage] of this.stageEntries)
this.setStageIntensity(stage, stage.uniforms.intensity);
}
// The engine eases the strength above its 0.06 dead zone (Cesium's bloom
// stage); under it, nothing glows with the toggle on.
syncBloomEnabled() {
if (this.stopped) return;
const enabled =
this.bloomEnabled &&
bloomStrengthFromIntensity(this.bloomIntensity) > 0.06;
this.engineBloom?.setBloom({ enabled });
}
applyBloomIntensity(intensity) {
if (this.stopped) return;
this.bloomIntensity = clampBloomIntensity(intensity);
this.requestRender('bloom');
if (!this.engineBloom) return;
this.engineBloom.setBloom({
strength: bloomStrengthFromIntensity(this.bloomIntensity),
});
this.syncBloomEnabled();
}
setBloomEnabled(enabled) {
if (this.stopped) return;
this.bloomEnabled = !!enabled;
this.syncBloomEnabled();
this.requestRender('bloom');
}
/**
* Sharpen runs only when it is on and its slider is above 0, as the style
* stages do: the pass costs the same at any amount (~1.5 ms GPU per frame
* on the Arc, 2026-10-24), and `0.1 + value * 2` still sharpened at 0.
*/
syncSharpenEnabled() {
if (this.stopped) return;
const enabled = this.sharpenEnabled && this.sharpenIntensity > 0.001;
if (enabled === this.sharpenShown) return;
this.sharpenShown = enabled;
this.engineRender?.setSharpen({ enabled });
}
applySharpenIntensity(value) {
if (this.stopped) return;
this.sharpenIntensity = value;
this.engineRender?.setSharpen({ amount: sharpenAmount(value) });
this.syncSharpenEnabled();
this.requestRender('sharpen');
}
setSharpenEnabled(enabled) {
if (this.stopped) return;
this.sharpenEnabled = !!enabled;
this.syncSharpenEnabled();
this.requestRender('sharpen');
}
startTransition(styleName, from, to) {
if (this.stopped) return;
this.transitions.set(styleName, { start: this.now(), from, to });
this.startAnimationLoop();
}
startAnimationLoop() {
if (this.stopped || this.frameId !== null) return;
const update = () => {
if (this.stopped) return;
const now = this.now();
const elapsedSec = (this.wallNow() - this.startTime) / 1000.0;
for (const [name, transition] of this.transitions) {
const t = Math.min(
(now - transition.start) / TRANSITION_DURATION_MS,
1.0,
);
const eased = t < 0.5 ? 2 * t * t : 1 - Math.pow(-2 * t + 2, 2) / 2;
this.setStageIntensity(
this.stages[name],
transition.from + (transition.to - transition.from) * eased,
);
if (t >= 1.0) {
this.setStageIntensity(this.stages[name], transition.to);
this.transitions.delete(name);
}
}
let animatedStageVisible = false;
for (const [, stage] of this.stageEntries) {
if (stage.enabled && stage.uniforms.time !== undefined) {
stage.uniforms.time = elapsedSec;
if (stage.uniforms.intensity > 0.001) animatedStageVisible = true;
}
}
const needed = this.transitions.size > 0 || animatedStageVisible;
if (needed) this.holdRender('style-anim');
else this.releaseRender('style-anim');
this.frameId = needed ? this.requestFrame(update) : null;
};
this.frameId = this.requestFrame(update);
}
/** Revoke animation synchronously while callers finish releasing the stages. */
stop() {
if (this.stopped) return;
this.stopped = true;
if (this.frameId !== null) this.cancelFrame(this.frameId);
this.frameId = null;
this.releaseRender('style-anim');
this.transitions.clear();
}
/**
* Turn every style, the bloom and the sharpening off on the engine after
* callers release them, as removing Cesium's stages did: the engine keeps
* the frame of a later owner, which starts them again (initStyles,
* initPostProcess).
*/
destroy() {
if (this.destroyed) return;
this.stop();
this.destroyed = true;
if (!this.engine || this.engine.isDestroyed?.()) return;
for (const [name, stage] of this.stageEntries)
if (stage.uniforms.intensity !== 0) {
try {
this.engineStyles.setStyle(name, { intensity: 0 });
} catch {
// The engine went with its scene.
}
}
if (this.postProcessReady) this.engineBloom?.setBloom({ enabled: false });
if (this.sharpenShown) this.engineRender?.setSharpen({ enabled: false });
}
}