Files
gods-eye-view/src/globe/navara/look.js
T
German Khokhlov 7c7422e281 Merge migration/phase2-engine (4aaf9746) into migration/phase3-layers
The phase-2 review fixes: look internals in internals.js, the groundFloor
resample throttle, tile height selection, the sharpen mirror, QA tile
cache limits, engine.groundFloor diagnostics. In navara/index.js both
sides are kept: the look gets internals.js's luminance uniforms and reads
the sun's time from the engine clock's frame time, so engine.clock stays
the one time source for the sun.
2026-10-16 15:15:24 +04:00

234 lines
8.8 KiB
JavaScript

// Builds a Navara look (viewOptions.js navaraScenePlan) on an initialised
// view and keeps it current while the view renders: the sun follows `now`
// (the engine clock's frame time in the app: the app clock, which is the wall
// clock the HUD's SUN elevation reads unless QA moves it); the cinematic look
// lights the globe
// from the atmosphere when seen from space, shows its clouds only for low
// views over low ground and while the sun is up, brightens the atmosphere
// (createLuminanceScaler, uniforms from internals.js), compiles both
// night-side shader variants at startup and shows its stars only at night
// or from space. All of it runs only on frames the view draws anyway, so an
// idle view stays idle.
import {
cloudsSunlitAt,
cloudsVisibleAt,
globeLightingAt,
starsVisibleAt,
sunDateStale,
} from './viewOptions.js';
/**
* @param {object} view an initialised ThreeView with the default plugin
* @param {object} plugin its DefaultPlugin
* @param {ReturnType<import('./viewOptions.js').navaraScenePlan>} plan
* @returns {{ handles: object[], frame: (height: number, moving?: boolean, ground?: number, place?: { lat: number, lng: number } | null) => boolean }}
* `frame` is called before each frame with the camera height, whether the
* camera is moving, the height of the ground in view (metres above the
* ellipsoid, NaN when unknown) and the camera's place (degrees, for the
* sun's elevation there); it returns true when it changed the scene, so
* the caller draws one more frame. It allocates nothing on a frame that
* changes nothing.
* @param {() => number} [now] the sun's time (ms); the app passes the engine
* clock's frame time (index.js), the wall clock by default and in tests
* @param {{ forEachLuminanceUniform?: (handles: object, visit: (key: string, uniform: { value: object }, scaled: boolean) => void) => void }} [internals]
* the takram uniforms behind the atmosphere scale (internals.js); without
* it the scale does nothing.
*/
export function buildNavaraLook(
view,
plugin,
plan,
now = () => Date.now(),
{ forEachLuminanceUniform = null } = {},
) {
const handles = [];
if (plan.pluginDefault) {
const scene = plugin.addDefaultPhotorealScene();
handles.push(...Object.values(scene).filter(Boolean));
} else {
for (const desc of plan.meshes) handles.push(view.addMesh(desc));
for (const desc of plan.lights) handles.push(view.addLight(desc));
for (const desc of plan.effects) handles.push(view.addEffect(desc));
}
const effect = (name) => {
const at = plan.effects.findIndex((desc) => Object.hasOwn(desc, name));
return at < 0
? null
: handles[plan.meshes.length + plan.lights.length + at];
};
const mesh = (name) => {
const at = plan.meshes.findIndex((desc) => Object.hasOwn(desc, name));
return at < 0 ? null : handles[at];
};
const aerial = plan.globeLighting ? effect('aerialPerspective') : null;
const clouds = effect('clouds');
const stars = plan.daylightHidesStars ? mesh('stars') : null;
const brighten = createLuminanceScaler(
plan.atmosphereLuminance ?? 1,
forEachLuminanceUniform,
{
sky: mesh('sky'),
stars: mesh('stars'),
aerialPerspective: effect('aerialPerspective'),
clouds,
},
);
let globeLit = false;
// Both aerial-perspective variants (with and without the night side) are
// compiled on the first two frames, during startup, so a later switch
// finds its shader compiled (a cold switch stalled a frame for up to
// 0.8 s, mid-flight on the way down from space).
let warmUp = aerial ? 2 : 0;
let cloudsShown = true;
let cloudsSunlit = true;
let starsShown = true;
const frame = (height, moving = false, ground = Number.NaN, place = null) => {
// Every drawn frame: a material Navara rebuilds comes back unscaled.
let changed = brighten();
const atmosphere = view.atmosphere;
if (atmosphere && sunDateStale(atmosphere.date.getTime(), now())) {
atmosphere.date = new Date(now());
changed = true;
}
const elevation =
place && typeof atmosphere?.getSunElevation === 'function'
? atmosphere.getSunElevation(place)
: Number.NaN;
if (warmUp) {
warmUp -= 1;
aerial.update(warmUp ? IRRADIANCE_ON : IRRADIANCE_OFF);
return true;
}
if (aerial) {
const next = globeLightingAt(height, globeLit);
// Switching rebuilds the aerial perspective's shader (warmed up
// above): it switches on only at rest (a flight from city to city
// through space never switches) and off as soon as the camera comes
// down, before the tiles would show relit.
if (next !== globeLit && !(next && moving)) {
globeLit = next;
// Only the aerial perspective changes: the tiles already draw plain
// albedo, so view.lit stays (toggling it recompiles every tile
// material, a frame of about 0.8 s mid-flight).
aerial.update(next ? IRRADIANCE_ON : IRRADIANCE_OFF);
changed = true;
}
}
// Clouds only for a camera below them over low ground, and while the
// sun is up at the camera (after sunset they read as dark puffs);
// switching them costs no recompile, so it follows the camera in motion.
if (clouds) {
cloudsSunlit = cloudsSunlitAt(elevation, cloudsSunlit);
const next = cloudsSunlit && cloudsVisibleAt(height, ground, cloudsShown);
if (next !== cloudsShown) {
cloudsShown = next;
clouds.update(next ? VISIBLE : HIDDEN);
parkCloudLayers(view.atmosphere, next);
changed = true;
}
}
if (stars) {
const next = starsVisibleAt(height, elevation, starsShown);
if (next !== starsShown) {
starsShown = next;
stars.update(next ? VISIBLE : HIDDEN);
changed = true;
}
}
return changed;
};
return { handles, frame };
}
const IRRADIANCE_ON = Object.freeze({
aerialPerspective: Object.freeze({ irradiance: true }),
});
const IRRADIANCE_OFF = Object.freeze({
aerialPerspective: Object.freeze({ irradiance: false }),
});
const VISIBLE = Object.freeze({ visible: true });
const HIDDEN = Object.freeze({ visible: false });
/**
* The atmosphere scale (viewOptions.js ATMOSPHERE_LUMINANCE_SCALE): each
* luminance factor is set to `scale` times the base value recorded the
* first time it is seen, never multiplied in place, so a vector Navara
* shares between materials, or copies into a rebuilt one, is never scaled
* twice. The stars keep the base value: when they share the sky's vector,
* they get their own. Returns `apply()`, true when it changed a uniform.
*/
export function createLuminanceScaler(scale, forEachUniform, handles) {
if (scale === 1 || !forEachUniform) return () => false;
const bases = new Map(); // key -> { base, target }
const scaledVectors = new WeakSet();
let changed = false;
const entry = (key, value) => {
let found = bases.get(key);
if (!found) {
found = {
base: value.clone(),
target: value.clone().multiplyScalar(scale),
};
bases.set(key, found);
}
return found;
};
const record = (key, uniform) => entry(key, uniform.value);
const scaleOne = (key, uniform, scaled) => {
if (!scaled) return;
const { target } = entry(key, uniform.value);
scaledVectors.add(uniform.value);
if (uniform.value.equals(target)) return;
uniform.value.copy(target);
changed = true;
};
const keepBase = (key, uniform, scaled) => {
if (scaled) return;
const { base } = entry(key, uniform.value);
if (scaledVectors.has(uniform.value)) {
uniform.value = base.clone();
changed = true;
} else if (!uniform.value.equals(base)) {
uniform.value.copy(base);
changed = true;
}
};
return () => {
changed = false;
// Bases first, from the values as Navara built them.
forEachUniform(handles, record);
forEachUniform(handles, scaleOne);
forEachUniform(handles, keepBase);
return changed;
};
}
// The clouds hand the aerial perspective their last output through the
// atmosphere (overlay, shadow, shadow length) once, when they first draw.
// A hidden clouds pass leaves those in place, and the aerial perspective
// keeps compositing the last clouds as grey ghosts. Hiding parks them;
// showing puts them back.
const CLOUD_OUTPUTS = ['overlay', 'shadow', 'shadowLength'];
const parked = new WeakMap();
function parkCloudLayers(atmosphere, shown) {
if (!atmosphere) return;
if (!shown) {
const outputs = {};
for (const name of CLOUD_OUTPUTS) {
if (!atmosphere[name]) continue;
outputs[name] = atmosphere[name].value;
atmosphere[name].value = null;
}
parked.set(atmosphere, outputs);
return;
}
const outputs = parked.get(atmosphere);
if (!outputs) return;
parked.delete(atmosphere);
for (const [name, value] of Object.entries(outputs))
atmosphere[name].value = value;
}