Files
gods-eye-view/src/render/cesium/quality.js
T
Sameh Khamis 0ed6cde956 Idle frame rate in the app, timed line batching, KEY REQUIRED status
Three fixes to how the globe draws and reports loading.

**The idle frame rate is the app's rule.** The Cesium frame port capped the loop at `IDLE_FRAME_RATE` whenever nothing held it, so the rule lived inside the renderer. The render governor now sets the rate: the display's own while the loop is held, `IDLE_FRAME_RATE` while not. The frame port gains `onHeldChange(cb)`, which says when its first hold is taken and its last released (animated visual styles included), so the governor hears every hold. The quality setting's frame-rate cap is kept apart from the governor's rate, and the loop draws at the lower of the two, so neither overwrites the other.

**Line batching is timed.** A line set waited 30 drawn frames before its unchanged lines settled into a static batch (300 for the long wait), so the batch built twice as fast at 120 Hz as at 60 Hz, and took seconds at the idle rate. It now waits `SETTLE_MS` (500 ms) and `LONG_SETTLE_MS` (5 s), and moved shapes go back into their batches on the same timing.

**KEY REQUIRED.** A layer that cannot load without a provider key ended the global status chip LOAD FAILED. The chip now has a KEY REQUIRED outcome, ranked below a real failure: a layer whose stats say `keyRequired` ends KEY REQUIRED, any other failure still ends LOAD FAILED. Vessels report a missing AISStream key as `keyRequired` and name the key in the panel; a later outage clears it, as it is no longer the key that is missing.

Checked: the full suite (new tests for `onHeldChange`, the quality cap against the governor's rate, timed settling, and the chip with and without a key), format, boundaries, build, the stub renderer boot and the Cesium conformance run; in the browser, the idle and held frame rates; and the first-run check now asserts that with no keys set the chip never says LOAD FAILED.
2026-11-16 14:10:01 -08:00

464 lines
15 KiB
JavaScript

/**
* @module render/cesium/quality
* @description The Cesium renderer's quality port
* (`src/render/contract/quality.d.ts`) over a widget or viewer someone else
* made and configured. It supports the settings Cesium has a knob for:
*
* - `pixelRatio`: the widget's `resolutionScale` at the browser's
* recommended resolution, which Cesium takes as one pixel per CSS pixel,
* so 0 (browser recommended) is a scale of 1.
* - `msaa`: the scene's `msaaSamples` (0 is Cesium's 1, off), listed only
* when the context can multisample.
* - `shadows`: the scene's shadow map, on or off.
* - `tiles3dDetail` and `terrainDetail`: each 3D tileset's and the globe's
* `maximumScreenSpaceError`, as their own value at 1 and up to 8 times it
* at 0. While tile detail is lowered, a tileset added later is brought
* to it on the next drawn frame; an error is written only when it
* changes, since each write resets the tileset's memory-adjusted error.
* - `targetFps`: a cap on the loop's frame rate, 0 for none (`fpsCap`: by
* default the frame port's own `setTargetFps`; the renderer's ports keep
* it apart from the rate the application sets there, and draw at the
* lower of the two).
*
* Building the port changes nothing in the scene; each setting is applied
* when it is first set, and a detail set back to 1 hands each tileset and
* the globe the error it had (or was given since). Frame signals carry the
* CPU time of each drawn tick, from the tick's start (before any frame
* listener) to the end of its draw. Where the context has
* `EXT_disjoint_timer_query_webgl2` (the `gpuTiming` capability), each drawn
* frame is timed on the GPU too, from `preRender` to `postRender`, while
* anyone listens; a frame's GPU time comes back a frame or more later, so a
* signal carries `gpuMs` of the latest frame whose timing has come back (none
* until the first does, and a timing the GPU marks disjoint is dropped).
*/
import * as Cesium from 'cesium';
import { listenerList } from './common.js';
import { webglContext } from './internals.js';
/** Timer queries kept waiting at most: past it, the oldest is dropped. */
const MAX_PENDING_QUERIES = 8;
/**
* The context's GPU timer extension, or null where it has none (WebGL 1, or
* a GPU or browser without timer queries).
* @param {WebGL2RenderingContext|object|undefined} gl
*/
export function gpuTimerOf(gl) {
if (typeof gl?.createQuery !== 'function') return null;
try {
return gl.getExtension?.('EXT_disjoint_timer_query_webgl2') ?? null;
} catch {
return null;
}
}
/**
* Times frames on the GPU with timer queries: `begin()` before a frame's
* draw, `end()` after it, and `latest()` the milliseconds of the newest frame
* whose timing has come back.
*/
function createGpuTimer(gl, ext) {
const pending = [];
const free = [];
let active = null;
let latestMs;
function poll() {
while (pending.length > 0) {
const query = pending[0];
if (!gl.getQueryParameter(query, gl.QUERY_RESULT_AVAILABLE)) break;
pending.shift();
const ns = gl.getQueryParameter(query, gl.QUERY_RESULT);
if (!gl.getParameter(ext.GPU_DISJOINT_EXT)) latestMs = ns / 1e6;
free.push(query);
}
}
return {
begin() {
if (active) this.end();
active = free.pop() ?? gl.createQuery();
gl.beginQuery(ext.TIME_ELAPSED_EXT, active);
},
end() {
if (!active) return;
gl.endQuery(ext.TIME_ELAPSED_EXT);
pending.push(active);
active = null;
if (pending.length > MAX_PENDING_QUERIES) gl.deleteQuery(pending.shift());
poll();
},
latest: () => latestMs,
dispose() {
if (active) gl.endQuery(ext.TIME_ELAPSED_EXT);
for (const query of [active, ...pending, ...free])
if (query) gl.deleteQuery(query);
active = null;
pending.length = 0;
free.length = 0;
},
};
}
const MSAA_OPTIONS = Object.freeze([0, 2, 4, 8]);
/** Screen-space error at detail 0, as a multiple of the error at detail 1. */
const COARSEST = 8;
const MAX_PIXEL_RATIO = 4;
const MAX_FPS = 240;
const clamp = (value, min, max) => Math.min(max, Math.max(min, value));
/** `value` as a number in range, or null when it is not a number. */
const inRange = (value, min, max) => {
const n = Number(value);
return Number.isFinite(n) ? clamp(n, min, max) : null;
};
/** The screen-space error multiplier for a detail, 0..1. */
export const errorFactor = (detail) => COARSEST ** (1 - clamp(detail, 0, 1));
/**
* The 3D tilesets in a primitive collection, nested collections included.
* @param {object} collection
* @param {(p: object) => boolean} isTileset
* @param {(p: object) => boolean} isCollection
* @param {object[]} [out]
*/
function tilesetsIn(collection, isTileset, isCollection, out = []) {
for (let i = 0; i < collection.length; i++) {
const primitive = collection.get(i);
if (isTileset(primitive)) out.push(primitive);
else if (isCollection(primitive))
tilesetsIn(primitive, isTileset, isCollection, out);
}
return out;
}
/**
* @param {object} widget A Cesium `CesiumWidget` or `Viewer`.
* @param {{
* frame: import('../contract/frame').FramePort,
* report: (error: unknown) => void,
* isTileset?: (p: object) => boolean,
* isCollection?: (p: object) => boolean,
* limits?: {maximumTextureSize: number, maximumSamples: number},
* tickStarted?: () => number,
* gl?: object,
* }} options `gl` is the WebGL context GPU timing reads (the scene's by
* default). `tickStarted` is when the tick under way started, on the
* `performance.now()` clock; without it the port times from its own
* preUpdate listener. Tests pass the predicates and limits; they default
* to Cesium's classes and context limits.
* @returns {{port: import('../contract/quality').QualityPort,
* dispose: () => void}}
*/
export function createCesiumQuality(
widget,
{
frame,
report,
isTileset = (p) => p instanceof Cesium.Cesium3DTileset,
isCollection = (p) => p instanceof Cesium.PrimitiveCollection,
limits = Cesium.ContextLimits,
tickStarted = null,
gl = webglContext(widget.scene),
fpsCap = {
get: () => frame.diagnostics?.().targetFps ?? 0,
set: (fps) => frame.setTargetFps(fps),
},
},
) {
const scene = widget.scene;
const timerExt = gpuTimerOf(gl);
const gpuTimer = timerExt ? createGpuTimer(gl, timerExt) : null;
let disposed = false;
const gone = () => disposed || scene.isDestroyed?.() === true;
/** The multisample counts the context can draw with; 0 is off. */
const msaaOptions = () =>
scene.msaaSupported
? MSAA_OPTIONS.filter((n) => n <= limits.maximumSamples)
: [];
// What the scene had before the port first changed it: the defaults.
const builtFps = fpsCap.get();
let msaaAtBuild = null;
let shadowsAtBuild = null;
// Cesium clamps the count to the context's only when it is set.
const toContractMsaa = (samples) =>
samples > 1 ? Math.min(samples, limits.maximumSamples) : 0;
const builtMsaa = () => msaaAtBuild ?? toContractMsaa(scene.msaaSamples);
const builtShadows = () =>
shadowsAtBuild ?? Boolean(scene.shadowMap?.enabled);
let pixelRatio = 0;
// Each detail and the errors it was applied over.
const detail = { tiles: 1, terrain: 1 };
/** Tileset (or the globe) → {own, applied}. */
const errors = new Map();
let offWatch = null;
/** Brings `target`'s error to `factor` times its own. */
function applyError(target, factor) {
let entry = errors.get(target);
const current = target.maximumScreenSpaceError;
// A value someone set since is its own from then on.
if (!entry || current !== entry.applied)
entry = { own: current, applied: current };
entry.applied = entry.own * factor;
if (target.maximumScreenSpaceError !== entry.applied)
target.maximumScreenSpaceError = entry.applied;
errors.set(target, entry);
}
/** Hands `target` back its own error, unless someone set one since. */
function restoreError(target) {
const entry = errors.get(target);
if (entry && target.maximumScreenSpaceError === entry.applied)
target.maximumScreenSpaceError = entry.own;
errors.delete(target);
}
/** Brings every tileset in the scene to the tile detail. */
function applyTiles() {
if (gone()) return;
const tilesets = scene.primitives
? tilesetsIn(scene.primitives, isTileset, isCollection)
: [];
const live = new Set(tilesets);
// One taken out of the scene gets its own error back.
for (const target of [...errors.keys()])
if (target === scene.globe) continue;
else if (target.isDestroyed?.()) {
errors.delete(target);
} else if (!live.has(target)) restoreError(target);
for (const tileset of tilesets)
if (detail.tiles === 1) restoreError(tileset);
else applyError(tileset, errorFactor(detail.tiles));
// Tilesets come and go: while tile detail is lowered, each drawn frame
// looks, before the tilesets update.
const lowered = detail.tiles !== 1;
if (lowered && !offWatch)
offWatch = scene.preRender.addEventListener(applyTiles);
else if (!lowered && offWatch) {
offWatch();
offWatch = null;
}
}
function applyTerrain() {
if (gone() || !scene.globe) return;
if (detail.terrain === 1) restoreError(scene.globe);
else applyError(scene.globe, errorFactor(detail.terrain));
}
function knobs() {
const list = [
{
key: 'pixelRatio',
kind: 'number',
min: 0,
max: MAX_PIXEL_RATIO,
default: 0,
cost: 1,
},
];
const msaa = msaaOptions();
if (msaa.length > 1)
list.push({
key: 'msaa',
kind: 'enum',
options: msaa,
default: builtMsaa(),
cost: 0.4,
});
if (scene.shadowMap)
list.push({
key: 'shadows',
kind: 'boolean',
default: builtShadows(),
cost: 0.6,
});
list.push(
{
key: 'tiles3dDetail',
kind: 'number',
min: 0,
max: 1,
default: 1,
cost: 0.8,
couples: ['lower detail lowers height accuracy'],
},
{
key: 'terrainDetail',
kind: 'number',
min: 0,
max: 1,
default: 1,
cost: 0.4,
couples: ['lower detail lowers height accuracy'],
},
{
key: 'targetFps',
kind: 'number',
min: 0,
max: MAX_FPS,
default: builtFps,
cost: 0.2,
},
);
return list;
}
const setters = {
pixelRatio(value) {
const ratio = inRange(value, 0, MAX_PIXEL_RATIO);
if (ratio === null) return;
pixelRatio = ratio;
widget.useBrowserRecommendedResolution = true;
widget.resolutionScale = ratio || 1;
},
msaa(value) {
const options = msaaOptions();
if (options.length <= 1) return false;
msaaAtBuild ??= toContractMsaa(scene.msaaSamples);
// The most samples the context has, up to the count asked for.
const asked = inRange(value, 0, Infinity);
if (asked === null) return;
const samples = options.filter((n) => n <= asked).pop() ?? 0;
scene.msaaSamples = samples || 1;
},
shadows(value) {
if (!scene.shadowMap) return false;
shadowsAtBuild ??= Boolean(scene.shadowMap.enabled);
scene.shadowMap.enabled = Boolean(value);
},
tiles3dDetail(value) {
detail.tiles = inRange(value, 0, 1) ?? detail.tiles;
applyTiles();
},
terrainDetail(value) {
detail.terrain = inRange(value, 0, 1) ?? detail.terrain;
applyTerrain();
},
targetFps(value) {
const fps = inRange(value, 0, MAX_FPS);
if (fps !== null) fpsCap.set(fps);
},
};
function get() {
const settings = {
pixelRatio,
tiles3dDetail: detail.tiles,
terrainDetail: detail.terrain,
targetFps: fpsCap.get(),
};
if (scene.shadowMap) settings.shadows = Boolean(scene.shadowMap.enabled);
if (msaaOptions().length > 1)
settings.msaa = toContractMsaa(scene.msaaSamples);
return settings;
}
function device() {
return {
backend: scene.context?.webgl2 ? 'webgl2' : 'webgl1',
maxTextureSize: limits.maximumTextureSize,
msaaSamples: scene.msaaSupported ? msaaOptions() : [0],
gpuTimer: Boolean(gpuTimer),
};
}
// --- Frame signals ---------------------------------------------------------
const signalListeners = listenerList(report);
let tickStart = 0;
let requested = false;
let mode = 'demand';
const removers = [
...(tickStarted
? []
: [
scene.preUpdate.addEventListener(() => {
tickStart = performance.now();
}),
]),
scene.preRender.addEventListener(() => {
if (signalListeners.size === 0) return;
gpuTimer?.begin();
const pending = frame.diagnostics?.().pendingReasons ?? [];
requested = pending.length > 0;
mode = scene.requestRenderMode ? 'demand' : 'continuous';
}),
scene.postRender.addEventListener(() => {
if (signalListeners.size === 0) return;
gpuTimer?.end();
const gpuMs = gpuTimer?.latest();
signalListeners.fire({
cpuMs: performance.now() - (tickStarted ? tickStarted() : tickStart),
...(gpuMs === undefined ? {} : { gpuMs }),
pixelRatio: scene.pixelRatio ?? 1,
width: scene.drawingBufferWidth ?? scene.canvas?.width ?? 0,
height: scene.drawingBufferHeight ?? scene.canvas?.height ?? 0,
mode,
requested,
holds: frame.diagnostics?.().holds ?? [],
});
}),
];
const port = {
knobs,
get,
set(settings) {
const ignored = [];
if (gone()) return Object.keys(settings ?? {});
for (const [key, value] of Object.entries(settings ?? {})) {
const apply = Object.hasOwn(setters, key) ? setters[key] : null;
if (!apply || apply(value) === false) ignored.push(key);
}
frame.requestRender('quality');
return ignored;
},
device,
probe() {
const nav = globalThis.navigator;
const media = (query) => globalThis.matchMedia?.(query).matches === true;
return {
device: device(),
browser: {
devicePixelRatio: globalThis.devicePixelRatio ?? 1,
screen: {
width: globalThis.screen?.width ?? 0,
height: globalThis.screen?.height ?? 0,
},
hardwareConcurrency: nav?.hardwareConcurrency,
deviceMemory: nav?.deviceMemory,
touchOnly:
media('(pointer: coarse)') && !media('(any-pointer: fine)'),
},
knobs: knobs(),
};
},
signals: {
gpuTiming: gpuTimer ? 'frame' : 'none',
on(event, cb) {
if (event !== 'frame') return () => {};
return signalListeners.on(cb);
},
},
};
return {
port,
/** Stops the signals and the detail watch; settings stay as set. */
dispose() {
if (disposed) return;
disposed = true;
signalListeners.clear();
for (const off of removers) off();
gpuTimer?.dispose();
offWatch?.();
offWatch = null;
},
};
}