Files
gods-eye-view/src/render/cesium/cameraControls.js
T
Sameh Khamis 619c19ea67 Application extras come from the renderer plugin; framing, occlusion and panel drawing are contract ports
A renderer plugin may supply applicationHooks(renderer) for what only its
renderer has (map engine, own credits, stale commands, QA handles). What every
renderer should do moves onto the contract: controls.keepEarthFramed (behind
the keepEarthFramed capability), query.occlusionTest (behind occlusionTest),
and panel drawing, which keepPanelRendering now does through resize and
frame.renderNow through the contract. renderNow throws when the frame fails to draw.

The Cesium port installs its zoom-out guard through keepEarthFramed (a setView
no longer cancels its turn) and answers occlusionTest with the scene's probe;
the stub answers it with a horizon test.
2026-11-10 21:17:56 -08:00

306 lines
11 KiB
JavaScript

/**
* @module render/cesium/cameraControls
* @description The Cesium camera port's `controls`: the contract's user
* camera settings mapped onto the scene's ScreenSpaceCameraController.
*
* - `suspend` and `enabled` are the scene's shared input holds
* (`cameraInput.js`), so a hold taken here, by the input port or by the
* dispatcher is counted with the rest and released on its own.
* - `coast` is Cesium's inertia: its speed falls as exp(-25 (1 - c) t), so a
* coast of s seconds is c = 1 - 1 / (25 s), and a coast of 0 is c = 1,
* which Cesium takes as no inertia at all. `drag` is `inertiaSpin`, which
* moves and tilts the globe in 3D (and `inertiaTranslate`, its pan in 2D);
* `zoom` is `inertiaZoom`.
* - `minDistance` and `coast.zoom` are the controller's own values: while a
* follow raises the zoom floor and stops zoom coasting, they read and set
* what the follow gives back when it ends.
* - `collision` is one switch in Cesium, `enableCollisionDetection`: the
* eye stays above the terrain and above every tileset that has its own
* `enableCollision` on. Any setting but 'none' turns it on, and reads
* back as set.
* - `pitchRange`'s upper end is Cesium's `maximumTiltAngle` (measured from
* straight down, so pitch + π/2); Cesium stops a user tilt short of
* straight down on its own, and has no other lower bound, so the lower
* end is kept and read back but not enforced.
* - `zoomInputs` are the controller's `zoomEventTypes`; a binding the
* contract has no name for is kept as it is when they are set. While
* they hold `ctrlWheel`, trackpad pinches (small pixel-mode Ctrl+wheel
* events) are relayed at a usable speed (`ctrlWheelZoom.js`).
* - `keepEarthFramed` installs the zoom-out guard (`zoomOutGuard.js`) on
* the widget, which reads the controller's own input; a camera command
* (`onCommand`) ends its easing. Without a widget whose scene has a
* controller, it only reads back.
*/
import * as Cesium from 'cesium';
import { acquireCameraInput } from './cameraInput.js';
import { installTrackpadPinchRelay } from './ctrlWheelZoom.js';
import { followZoomBase, setFollowZoomBase } from './follow.js';
import { installZoomOutGuard } from './zoomOutGuard.js';
const HALF_PI = Math.PI / 2;
const { WHEEL, PINCH, RIGHT_DRAG } = Cesium.CameraEventType;
const { CTRL } = Cesium.KeyboardEventModifier;
/** The contract's zoom inputs as Cesium bindings. */
const ZOOM_BINDINGS = Object.freeze({
wheel: WHEEL,
pinch: PINCH,
rightDrag: RIGHT_DRAG,
ctrlWheel: Object.freeze({ eventType: WHEEL, modifier: CTRL }),
});
/** A Cesium zoom binding's contract name, or null when it has none. */
export function zoomInputName(binding) {
const type = binding?.eventType ?? binding;
const modifier = binding?.modifier;
if (modifier === undefined) {
if (type === WHEEL) return 'wheel';
if (type === PINCH) return 'pinch';
if (type === RIGHT_DRAG) return 'rightDrag';
return null;
}
return type === WHEEL && modifier === CTRL ? 'ctrlWheel' : null;
}
/** Cesium's event-type setting, which may be one binding, as a list. */
export const bindingList = (types) =>
Array.isArray(types) ? types : types === undefined ? [] : [types];
/** Coast seconds as a Cesium inertia coefficient, and back. */
export const coastToInertia = (seconds) =>
seconds > 0 ? 1 - 1 / (25 * seconds) : 1;
export const inertiaToCoast = (c) =>
Number.isFinite(c) && c < 1 ? 1 / (25 * (1 - c)) : 0;
/**
* Cesium's controller defaults, for a scene that has no controller of its
* own: the settings then only read back. Also a headless scene's controller.
*/
export const controllerDefaults = () => ({
enableTilt: true,
enableRotate: true,
enableZoom: true,
inertiaSpin: 0.9,
inertiaTranslate: 0.9,
inertiaZoom: 0.8,
minimumZoomDistance: 1,
maximumZoomDistance: Number.POSITIVE_INFINITY,
zoomFactor: 5,
zoomEventTypes: [RIGHT_DRAG, WHEEL, PINCH],
enableCollisionDetection: true,
maximumTiltAngle: undefined,
});
/**
* @param {{scene: {screenSpaceCameraController?: object}, widget?: object,
* pinchRelay?: typeof installTrackpadPinchRelay,
* onCommand?: (cb: () => void) => () => void,
* zoomOutGuard?: typeof installZoomOutGuard}} options `widget`, the
* Viewer or CesiumWidget, takes the trackpad pinch relay and the zoom-out
* guard; without one `ctrlWheel` binds Ctrl+wheel alone. `onCommand`
* subscribes to the camera port's commands.
* @returns {{controls: import('../contract/camera').CameraControls,
* dispose: () => void}}
*/
export function createCesiumControls({
scene,
widget,
pinchRelay = installTrackpadPinchRelay,
onCommand,
zoomOutGuard = installZoomOutGuard,
}) {
const ownController = scene.screenSpaceCameraController;
const controller = ownController ?? controllerDefaults();
// The shared holds, taken on first use: until then the controller's
// `enableInputs` is left as it is.
let cameraInput = null;
let disposed = false;
const input = () => {
if (!cameraInput && !disposed) cameraInput = acquireCameraInput(scene);
return cameraInput;
};
let collision = controller.enableCollisionDetection ? 'both' : 'none';
// The trackpad pinch relay's disposer, while `ctrlWheel` is bound.
let uninstallPinch = null;
const relayPinches = (on) => {
if (on && !uninstallPinch && !disposed && widget?.container)
uninstallPinch = pinchRelay(widget);
else if (!on && uninstallPinch) {
uninstallPinch();
uninstallPinch = null;
}
};
// The pitch range as last set, read back while the controller still has
// the tilt limit it was given.
let pitchSet = null;
// `keepEarthFramed`, and the guard's disposer while it is installed.
let framed = false;
let releaseGuard = null;
const guardable = () =>
Boolean(
ownController && widget?.camera && widget?.canvas && scene.preRender,
);
const controls = {
// Read without taking over `enableInputs`: once any user holds input,
// the controller's own property counts every hold.
get enabled() {
if (ownController && !cameraInput)
return ownController.enableInputs !== false;
const held = input();
if (held && !held.enabled) return false;
return !ownController || ownController.enableInputs !== false;
},
suspend(reason) {
return input()?.suspend(reason) ?? (() => {});
},
get enableTilt() {
return Boolean(controller.enableTilt);
},
set enableTilt(value) {
controller.enableTilt = Boolean(value);
},
get enableRotate() {
return Boolean(controller.enableRotate);
},
set enableRotate(value) {
controller.enableRotate = Boolean(value);
},
get enableZoom() {
return Boolean(controller.enableZoom);
},
set enableZoom(value) {
controller.enableZoom = Boolean(value);
},
get minDistance() {
return followZoomBase(controller, 'minimumZoomDistance');
},
set minDistance(value) {
setFollowZoomBase(controller, 'minimumZoomDistance', value);
},
get maxDistance() {
return controller.maximumZoomDistance;
},
set maxDistance(value) {
controller.maximumZoomDistance = value;
},
get coast() {
return Object.freeze({
drag: inertiaToCoast(controller.inertiaSpin),
zoom: inertiaToCoast(followZoomBase(controller, 'inertiaZoom')),
});
},
set coast(value) {
for (const key of ['drag', 'zoom'])
if (!(Number.isFinite(value?.[key]) && value[key] >= 0))
throw new TypeError(`coast.${key} must be seconds, 0 or more`);
const drag = coastToInertia(value.drag);
controller.inertiaSpin = drag;
controller.inertiaTranslate = drag;
setFollowZoomBase(controller, 'inertiaZoom', coastToInertia(value.zoom));
},
get collision() {
return controller.enableCollisionDetection
? collision === 'none'
? 'both'
: collision
: 'none';
},
set collision(value) {
if (!['none', 'terrain', 'tiles', 'both'].includes(value))
throw new TypeError(`no collision setting '${value}'`);
collision = value;
controller.enableCollisionDetection = value !== 'none';
},
get zoomFactor() {
return controller.zoomFactor;
},
set zoomFactor(value) {
controller.zoomFactor = value;
},
get pitchRange() {
const tilt = controller.maximumTiltAngle;
if (pitchSet && pitchSet.tilt === tilt) return [...pitchSet.range];
const max =
tilt === undefined ? HALF_PI : Math.min(HALF_PI, tilt - HALF_PI);
const min = Math.min(pitchSet?.range[0] ?? -HALF_PI, max);
return [Math.max(-HALF_PI, min), Math.max(-HALF_PI, max)];
},
set pitchRange(value) {
const [min, max] = Array.isArray(value) ? value : [];
if (!(Number.isFinite(min) && Number.isFinite(max) && min <= max))
throw new RangeError('pitchRange must be [min, max] radians');
const range = [
Math.min(HALF_PI, Math.max(-HALF_PI, min)),
Math.min(HALF_PI, Math.max(-HALF_PI, max)),
];
const tilt = range[1] >= HALF_PI ? undefined : range[1] + HALF_PI;
controller.maximumTiltAngle = tilt;
pitchSet = { range, tilt };
},
get zoomInputs() {
const names = [];
for (const binding of bindingList(controller.zoomEventTypes)) {
const name = zoomInputName(binding);
if (name && !names.includes(name)) names.push(name);
}
return names;
},
set zoomInputs(value) {
if (!Array.isArray(value))
throw new TypeError('zoomInputs must be an array');
for (const name of value)
if (!Object.hasOwn(ZOOM_BINDINGS, name))
throw new TypeError(`no zoom input '${name}'`);
const kept = bindingList(controller.zoomEventTypes).filter(
(binding) => zoomInputName(binding) === null,
);
controller.zoomEventTypes = [
...kept,
...[...new Set(value)].map((name) => {
const binding = ZOOM_BINDINGS[name];
return typeof binding === 'object' ? { ...binding } : binding;
}),
];
relayPinches(value.includes('ctrlWheel'));
},
get keepEarthFramed() {
return framed;
},
set keepEarthFramed(value) {
framed = Boolean(value);
if (framed && !releaseGuard && !disposed && guardable())
releaseGuard = zoomOutGuard(widget, {
requestRender: () => scene.requestRender?.(),
// A command that places the eye ends the guard's easing; the
// step views a held key sends every frame do not (the guard
// lets go of a pose it did not make on its own).
subscribeCameraHandoff: (listener) =>
onCommand?.((command) => {
if (command?.kind !== 'setView') listener(command);
}),
});
else if (!framed && releaseGuard) {
releaseGuard();
releaseGuard = null;
}
},
};
// A controller that already binds Ctrl+wheel relays pinches from the start.
relayPinches(controls.zoomInputs.includes('ctrlWheel'));
return {
controls,
dispose() {
relayPinches(false);
releaseGuard?.();
releaseGuard = null;
disposed = true;
cameraInput?.release();
cameraInput = null;
},
};
}