Make quality settings detail only and fold ctrl-wheel zoom into the camera's zoom inputs

Quality no longer switches clouds or water (their ports are gone) and its
atmosphere and post-processing settings are low or high detail; whether the
sky or a pass shows stays with globe.sky and effects. The separate
input.ctrlWheelZoom switch is gone: 'ctrlWheel' in the camera's zoomInputs
also relays trackpad pinches, which the application turns on.
This commit is contained in:
Sameh Khamis committed 2026-11-10 03:35:35 -08:00
1 parent 46cdeba7fa
commit 7a376ebefc
15 files changed
+87 -114

No files matched your search

+6 -7
View File
@@ -2,7 +2,7 @@ import test from 'node:test';
import assert from 'node:assert/strict';
import { spawnSync } from 'node:child_process';
import { createApplication } from './application.js';
import { installTrackpadPinchZoom } from '../render/cesium/ctrlWheelZoom.js';
import { installTrackpadPinchRelay } from '../render/cesium/ctrlWheelZoom.js';
import { KEYHOLE_OUTER_RADIUS } from '../celestialRing.js';
import * as Cesium from 'cesium';
import { installFreeLookHeightLimit } from '../render/cesium/freeLookLimit.js';
@@ -354,14 +354,13 @@ function pinchFixture({ zoomEventTypes } = {}) {
return { viewer, controller, container, handlers, relayed, createEvent };
}
test('trackpad pinch adds the Ctrl+wheel binding without replacing Cesium inputs', () => {
test('the trackpad pinch relay leaves the zoom bindings and plain or line-mode wheels alone', () => {
const original = [1, 2, 3];
const f = pinchFixture({ zoomEventTypes: original });
const dispose = installTrackpadPinchZoom(f.viewer, {
const dispose = installTrackpadPinchRelay(f.viewer, {
createWheelEvent: (_type, init) => f.createEvent(init),
});
assert.deepEqual(f.controller.zoomEventTypes.slice(0, 3), original);
assert.equal(f.controller.zoomEventTypes.length, 4);
assert.equal(f.controller.zoomEventTypes, original);
const plain = f.createEvent({ deltaY: 2 });
f.container.emit(plain);
@@ -379,7 +378,7 @@ test('trackpad pinch adds the Ctrl+wheel binding without replacing Cesium inputs
test('trackpad pinch relays pixel deltas once with bounded amplification', () => {
const f = pinchFixture({ zoomEventTypes: [1, 2, 3] });
installTrackpadPinchZoom(f.viewer, {
installTrackpadPinchRelay(f.viewer, {
createWheelEvent: (_type, init) => f.createEvent(init),
});
@@ -399,7 +398,7 @@ test('trackpad pinch relays pixel deltas once with bounded amplification', () =>
test('trackpad pinch falls back to the original event when relay construction fails', () => {
const f = pinchFixture({ zoomEventTypes: [1, 2, 3] });
installTrackpadPinchZoom(f.viewer, {
installTrackpadPinchRelay(f.viewer, {
createWheelEvent() {
throw new Error('unsupported');
},
+3 -1
View File
@@ -94,7 +94,9 @@ export async function createApplicationScene({
const input = inputFor(viewer);
defer(() => input.destroy());
// Ctrl+wheel and trackpad pinches zoom the globe, not the page.
renderer.input.ctrlWheelZoom = true;
const { controls } = renderer.camera;
if (!controls.zoomInputs.includes('ctrlWheel'))
controls.zoomInputs = [...controls.zoomInputs, 'ctrlWheel'];
defer(
followWorldTime(viewer, worldTimeFor('sky'), {
subscribe: worldClock.subscribe,
+1 -1
View File
@@ -129,7 +129,7 @@ export function createCesiumCamera({
})
: null;
const controlsPart = createCesiumControls({ scene });
const controlsPart = createCesiumControls({ scene, widget });
// Camera commands: hooks run before each one, so an owner can yield.
const commandHooks = listenerList(report);
+25 -3
View File
@@ -23,10 +23,13 @@
* 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.
* 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`).
*/
import * as Cesium from 'cesium';
import { acquireCameraInput } from './cameraInput.js';
import { installTrackpadPinchRelay } from './ctrlWheelZoom.js';
import { followZoomBase, setFollowZoomBase } from './follow.js';
const HALF_PI = Math.PI / 2;
@@ -84,11 +87,18 @@ export const controllerDefaults = () => ({
});
/**
* @param {{scene: {screenSpaceCameraController?: object}}} options
* @param {{scene: {screenSpaceCameraController?: object}, widget?: object,
* pinchRelay?: typeof installTrackpadPinchRelay}} options `widget`, the
* Viewer or CesiumWidget, takes the trackpad pinch relay; without one
* `ctrlWheel` binds Ctrl+wheel alone.
* @returns {{controls: import('../contract/camera').CameraControls,
* dispose: () => void}}
*/
export function createCesiumControls({ scene }) {
export function createCesiumControls({
scene,
widget,
pinchRelay = installTrackpadPinchRelay,
}) {
const ownController = scene.screenSpaceCameraController;
const controller = ownController ?? controllerDefaults();
@@ -102,6 +112,16 @@ export function createCesiumControls({ scene }) {
};
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;
@@ -227,12 +247,14 @@ export function createCesiumControls({ scene }) {
return typeof binding === 'object' ? { ...binding } : binding;
}),
];
relayPinches(value.includes('ctrlWheel'));
},
};
return {
controls,
dispose() {
relayPinches(false);
disposed = true;
cameraInput?.release();
cameraInput = null;
+22
View File
@@ -135,6 +135,28 @@ test('zoomInputs name the zoom bindings and keep unnamed ones', () => {
assert.throws(() => (controls.zoomInputs = ['scroll']), TypeError);
});
test('ctrlWheel relays trackpad pinches while it is bound, and not after', () => {
const scene = sceneWithController();
const relays = [];
const { controls, dispose } = createCesiumControls({
scene,
widget: { container: {} },
pinchRelay: () => {
relays.push('on');
return () => relays.push('off');
},
});
controls.zoomInputs = ['wheel', 'ctrlWheel'];
controls.zoomInputs = ['ctrlWheel', 'pinch'];
assert.deepEqual(relays, ['on'], 'installed once');
controls.zoomInputs = ['wheel'];
assert.deepEqual(relays, ['on', 'off']);
controls.zoomInputs = ['ctrlWheel'];
dispose();
controls.zoomInputs = ['ctrlWheel'];
assert.deepEqual(relays, ['on', 'off', 'on', 'off'], 'none after dispose');
});
test('suspend shares the scene’s holds with other users', () => {
const scene = sceneWithController();
const c = scene.screenSpaceCameraController;
+11 -34
View File
@@ -1,11 +1,9 @@
/**
* @module render/cesium/ctrlWheelZoom
* @description Ctrl+wheel zoom on a Cesium scene: a Ctrl+wheel binding among
* the camera controller's zoom inputs, and browser trackpad pinches (small
* pixel-mode Ctrl+wheel events) relayed at a usable speed.
* @description Browser trackpad pinches (small pixel-mode Ctrl+wheel
* events) relayed to a Cesium scene at a usable speed, while the camera
* controls' zoom inputs hold `ctrlWheel` (`cameraControls.js`).
*/
import * as Cesium from 'cesium';
import { bindingList, zoomInputName } from './cameraControls.js';
const PINCH_ZOOM_MULTIPLIER = 8;
const MAX_PINCH_PIXEL_DELTA = 120;
@@ -19,35 +17,19 @@ function boundedPinchDelta(delta) {
}
/**
* Add browser trackpad pinch to Cesium's zoom inputs and return its disposer.
* Browsers expose this gesture as a small pixel-mode Ctrl+wheel event.
* Relay browser trackpad pinches to the canvas, amplified and bounded, so
* the camera controller's Ctrl+wheel binding zooms at a usable speed;
* returns its disposer. Browsers expose this gesture as a small pixel-mode
* Ctrl+wheel event. The binding itself is the controls' (`zoomInputs`).
*/
export function installTrackpadPinchZoom(
export function installTrackpadPinchRelay(
viewer,
{ createWheelEvent = (type, init) => new WheelEvent(type, init) } = {},
) {
const controller = viewer?.scene?.screenSpaceCameraController;
const container = viewer?.container;
const canvas = viewer?.canvas;
if (!controller || !container || !canvas)
throw new TypeError('A complete Cesium viewer is required');
const originalZoomEventTypes = controller.zoomEventTypes;
const zoomEventTypes = bindingList(originalZoomEventTypes);
const alreadyHandlesControlWheel = zoomEventTypes.some(
(binding) => zoomInputName(binding) === 'ctrlWheel',
);
const configuredZoomEventTypes = alreadyHandlesControlWheel
? originalZoomEventTypes
: [
...zoomEventTypes,
{
eventType: Cesium.CameraEventType.WHEEL,
modifier: Cesium.KeyboardEventModifier.CTRL,
},
];
if (!alreadyHandlesControlWheel)
controller.zoomEventTypes = configuredZoomEventTypes;
if (!container || !canvas)
throw new TypeError('A viewer with a container and a canvas is required');
const relayedEvents = new WeakSet();
const relayPinch = (event) => {
@@ -76,7 +58,7 @@ export function installTrackpadPinchZoom(
view: globalThis.window,
});
} catch {
// The registered Ctrl+wheel binding can still consume the original.
// The Ctrl+wheel binding can still consume the original.
return;
}
relayedEvents.add(relayed);
@@ -94,10 +76,5 @@ export function installTrackpadPinchZoom(
if (!active) return;
active = false;
container.removeEventListener('wheel', relayPinch, true);
if (
!alreadyHandlesControlWheel &&
controller.zoomEventTypes === configuredZoomEventTypes
)
controller.zoomEventTypes = originalZoomEventTypes;
};
}
+3 -16
View File
@@ -10,8 +10,9 @@
* the modifier it was bound with). The DOM event under each one, seen
* first on the document, gives the full modifiers and the pointer type.
* - Wheel comes from the canvas's own `wheel` event, which this never
* cancels: the page keeps its Ctrl+wheel zoom unless `ctrlWheelZoom` is
* on. Pinch comes from the handler's two-finger events.
* cancels: Ctrl+wheel zooms the globe only while the camera controls'
* `zoomInputs` hold `ctrlWheel`. Pinch comes from the handler's
* two-finger events.
* - A click is picked lazily and once, through the query port, and shared
* by every subscriber.
* - The viewer's stock select (left click) and follow (double-click) are
@@ -25,7 +26,6 @@
import * as Cesium from 'cesium';
import { createInputRouter } from '../input/router.js';
import { acquireCameraInput } from './cameraInput.js';
import { installTrackpadPinchZoom } from './ctrlWheelZoom.js';
import { wheelLines } from '../input/wheel.js';
import { provideUnboundInput } from '../rendererOf.js';
@@ -113,7 +113,6 @@ export const cesiumInputOf = (scene) => inputs.get(scene) ?? null;
* @param {(canvas: object) => object} [options.createHandler]
* @param {() => number} [options.now] Event time, ms.
* @param {object} [options.document] Where the DOM events are watched.
* @param {typeof installTrackpadPinchZoom} [options.ctrlWheelZoom]
* @param {boolean} [options.takeStock] False leaves the viewer's stock
* actions on its own handler, taken off only while suppressed, for a
* viewer that is not this renderer's: its owner may still rebind them.
@@ -129,7 +128,6 @@ export function createCesiumInput(
createHandler = (canvas) => new Cesium.ScreenSpaceEventHandler(canvas),
now = () => performance.now(),
document: dom = globalThis.document,
ctrlWheelZoom = installTrackpadPinchZoom,
takeStock = true,
},
) {
@@ -170,20 +168,11 @@ export function createCesiumInput(
}
const cameraInput = acquireCameraInput(scene);
let uninstallCtrlWheel = null;
const router = createInputRouter({
report,
suspendCamera: (reason) => cameraInput.suspend(reason),
supported: { select: has.select, dblclickFollow: has.dblclickFollow },
onBehaviour: borrowStock,
onCtrlWheelZoom(on) {
if (disposed) return;
if (on && !uninstallCtrlWheel) uninstallCtrlWheel = ctrlWheelZoom(widget);
else if (!on && uninstallCtrlWheel) {
uninstallCtrlWheel();
uninstallCtrlWheel = null;
}
},
});
const { behaviours } = router.port;
@@ -464,8 +453,6 @@ export function createCesiumInput(
for (const type of DOM_EVENTS)
dom?.removeEventListener?.(type, record, { capture: true });
if (!handler.isDestroyed?.()) handler.destroy?.();
uninstallCtrlWheel?.();
uninstallCtrlWheel = null;
cameraInput.release();
for (const name of Object.keys(borrowed)) giveBack(name);
if (stockHandler && !stockHandler.isDestroyed?.())
-18
View File
@@ -78,7 +78,6 @@ function setup({ stock = true, document = null, takeStock = true } = {}) {
};
const handler = fakeHandler();
const errors = [];
const wheelZoom = [];
let clock = 0;
const input = createCesiumInput(widget, {
query,
@@ -87,10 +86,6 @@ function setup({ stock = true, document = null, takeStock = true } = {}) {
now: () => clock,
document,
takeStock,
ctrlWheelZoom: () => {
wheelZoom.push('on');
return () => wheelZoom.push('off');
},
});
const at = (x, y) => new Cesium.Cartesian2(x, y);
const press = (x, y, modifier) => {
@@ -109,7 +104,6 @@ function setup({ stock = true, document = null, takeStock = true } = {}) {
canvas,
passes,
errors,
wheelZoom,
press,
at,
tick: (ms) => (clock += ms),
@@ -230,16 +224,6 @@ test('camera holds turn the controller’s input off until the last release', ()
assert.equal(s.controller.enableInputs, true, 'dispose gives them back');
});
test('ctrlWheelZoom installs the zoom and takes it out again', () => {
const s = setup();
s.port.ctrlWheelZoom = true;
s.port.ctrlWheelZoom = true;
s.port.ctrlWheelZoom = false;
s.port.ctrlWheelZoom = true;
s.input.dispose();
assert.deepEqual(s.wheelZoom, ['on', 'off', 'on', 'off']);
});
test('wheel is in lines as the reference counts them, where the pointer is over the canvas', () => {
const s = setup();
const wheels = [];
@@ -360,8 +344,6 @@ test('a subscriber that disposes the port stops the rest of the click', () => {
s.press(5, 6);
assert.deepEqual(heard, ['first']);
assert.equal(s.selected.length, 1, 'the stock select had run first');
s.port.ctrlWheelZoom = true;
assert.deepEqual(s.wheelZoom, [], 'nothing installs after dispose');
});
test('a double-tap is a touch; a click on Cesium’s timer ends no press', () => {
+3 -3
View File
@@ -132,10 +132,10 @@ test('set applies supported keys, asks for a frame and returns the rest', () =>
msaa: 0,
shadows: true,
targetFps: 30,
clouds: 'high',
water: 'off',
atmosphere: 'high',
milkyWay: 'low',
});
assert.deepEqual(ignored, ['clouds', 'water']);
assert.deepEqual(ignored, ['atmosphere', 'milkyWay']);
assert.equal(scene.msaaSamples, 1, 'off is Cesium’s 1');
assert.equal(scene.shadowMap.enabled, true);
assert.equal(quality.get().targetFps, 30);
+5 -1
View File
@@ -195,7 +195,11 @@ export interface CameraControls {
zoomFactor: number;
/** Pitch the user may tilt between, radians (−π/2 straight down). */
pitchRange: [min: number, max: number];
/** Input bindings that zoom. */
/**
* Input bindings that zoom. `ctrlWheel`: Ctrl+wheel, and a trackpad
* pinch (which browsers send as Ctrl+wheel), zoom the globe rather than
* the page.
*/
zoomInputs: Array<'wheel' | 'pinch' | 'rightDrag' | 'ctrlWheel'>;
}
-3
View File
@@ -68,9 +68,7 @@ export const QUALITY_KEYS = Object.freeze([
'terrainDetail',
'imageryDetail',
'tilesCacheBytes',
'clouds',
'shadows',
'water',
'atmosphere',
'milkyWay',
'particles',
@@ -237,7 +235,6 @@ export const PORTS = deepFreeze({
'behaviours.dblclickFollow',
'behaviours.dblclickFollow.enabled',
'behaviours.dblclickFollow.suppress',
'ctrlWheelZoom',
),
),
effects: Object.fromEntries([
-2
View File
@@ -121,6 +121,4 @@ export interface InputPort {
readonly dblclickFollow: StockBehaviour;
readonly [name: string]: StockBehaviour;
};
/** Ctrl+wheel zooms (rather than the page). */
ctrlWheelZoom: boolean;
}
+8 -5
View File
@@ -1,7 +1,9 @@
/**
* Adaptive quality. A governor above the contract decides a level; each
* renderer reports its frame signals, lists the settings it supports and
* applies them. Nothing here is engine-specific.
* applies them. Nothing here is engine-specific. Quality sets only how
* detailed a thing is drawn; switching it on or off is the port's that
* draws it (`globe.sky`, `effects`).
*/
import type { Off } from './common';
@@ -14,15 +16,16 @@ export interface QualitySettings {
terrainDetail: number;
imageryDetail: number;
tilesCacheBytes: number;
clouds: 'off' | 'low' | 'medium' | 'high' | 'ultra';
shadows: boolean;
water: 'off' | 'low' | 'high';
atmosphere: 'off' | 'low' | 'high';
/** Detail of the atmosphere; whether it shows is `globe.sky`'s. */
atmosphere: 'low' | 'high';
/** Detail of the Milky Way; its brightness is `globe.sky`'s. */
milkyWay: 'low' | 'high';
/** 0..1 density of particle fields (wind, weather). */
particles: number;
models: { maxInstances: number; maxDistance: number };
postFx: { bloom: boolean; sharpen: boolean; style: 'low' | 'high' };
/** Detail of the post-processing passes; bloom and sharpen are switched in `effects`. */
postFx: 'low' | 'high';
/** Updates per second of a screen modulation sweep. */
sonarCadenceHz: number;
targetFps: number;
-11
View File
@@ -20,8 +20,6 @@ const near = (a, b) => Math.hypot(a.x - b.x, a.y - b.y) <= 4;
* has, beyond `select` and `dblclickFollow` (always listed).
* @param {(name: string, enabled: boolean) => void} [options.onBehaviour]
* Told when a behaviour turns off (first hold) or back on (last release).
* @param {(enabled: boolean) => void} [options.onCtrlWheelZoom] Told when
* `ctrlWheelZoom` is set.
* @param {Record<string, boolean>} [options.supported] Behaviours the
* renderer cannot do, as `false`: listed, but reported disabled.
*/
@@ -30,7 +28,6 @@ export function createInputRouter({
suspendCamera,
behaviours: extra = [],
onBehaviour = () => {},
onCtrlWheelZoom = () => {},
supported = {},
}) {
const listeners = [];
@@ -88,7 +85,6 @@ export function createInputRouter({
const leaseOf = (entry) =>
typeof entry.lease === 'function' ? entry.lease() : entry.lease;
let ctrlWheelZoom = false;
const port = {
on(type, cb, opts = {}) {
const entry = { type, cb, lease: opts.lease ?? null, live: true };
@@ -121,13 +117,6 @@ export function createInputRouter({
isPointerFree: () => currentLease === null,
suspendCameraControls: (reason) => suspendCamera(String(reason)),
behaviours,
get ctrlWheelZoom() {
return ctrlWheelZoom;
},
set ctrlWheelZoom(value) {
ctrlWheelZoom = Boolean(value);
onCtrlWheelZoom(ctrlWheelZoom);
},
};
/** Who a new press belongs to, decided from its `down`. */
-9
View File
@@ -75,15 +75,6 @@ test('an unsupported behaviour is never told; a throwing hook is reported', () =
assert.equal(errors.length, 2);
});
test('ctrlWheelZoom is told to the renderer', () => {
const told = [];
const { port } = router({ onCtrlWheelZoom: (on) => told.push(on) });
assert.equal(port.ctrlWheelZoom, false);
port.ctrlWheelZoom = 1;
assert.equal(port.ctrlWheelZoom, true);
assert.deepEqual(told, [true]);
});
test('dispatch says who an event went to', () => {
const { port, dispatch, listenerCount } = router();
const off = port.on('down', () => {});