diff --git a/docs/RENDERER-CONTRACT.md b/docs/RENDERER-CONTRACT.md index bbe0c0e36..5cbaf5e09 100644 --- a/docs/RENDERER-CONTRACT.md +++ b/docs/RENDERER-CONTRACT.md @@ -207,8 +207,9 @@ renderer under test: - `tolerance` and `flightPaths`. Optional members widen what is checked: `pointer` for synthetic input, -`scriptHeights`, `assets.model`, and `assets.missingModel` (a model url -that fails to load, for the `loadFailed` check). +`cameraInput` (the camera answers that input: the drag and wheel traces +run), `scriptHeights`, `assets.model`, and `assets.missingModel` (a model +url that fails to load, for the `loadFailed` check). There are two layers of checks. @@ -232,6 +233,22 @@ match each recorded pose: screen; - with every flight ending within one frame of the recording. +Some scripts move the camera by user input: left, middle, Shift and Ctrl +drags, and wheels in pixel and line mode. The recorder runs those on +Cesium's own `ScreenSpaceCameraController`, fed the DOM events the script +describes, with `Date` on the virtual clock too (its coasting reads it). A +renderer under test gets them through its harness's `pointer`, a wheel as +the input port's lines. Only a harness with `cameraInput` runs them: the +stub's camera takes no gestures, so it skips them; a camera controller +over the stub would run them. `cameraPort.test.mjs` runs them on Cesium's +controls under the Cesium camera port, each wheel sent back as lines. + +A wheel's `delta` is lines as Cesium counts them: a pixel-mode wheel at +40 px a line and a page at 3 lines (`src/render/input/wheel.js`). Turning +lines back into pixels at 40 px a line gives Cesium's own wheel in every +mode, so a controller that does that zooms as Cesium does in Chrome (pixel +mode) and Firefox (line mode) alike. + `src/render/cesium/cameraGoldens.test.mjs` fails when the installed Cesium no longer records the committed traces. After a Cesium upgrade or a script change, run `node scripts/record-camera-goldens.mjs` and review the diff. diff --git a/scripts/package-boundaries.json b/scripts/package-boundaries.json index c32a26926..db798ef65 100644 --- a/scripts/package-boundaries.json +++ b/scripts/package-boundaries.json @@ -49,6 +49,7 @@ "src/render/cesium/common.js", "src/render/cesium/internals.js", "src/render/cesium/input.js", + "src/render/input/wheel.js", "src/render/cesium/ctrlWheelZoom.js", "src/render/input/router.js", "src/input/sensorPick.js", @@ -964,6 +965,7 @@ "src/render/cesium/drawHit.js", "src/render/cesium/cameraInput.js", "src/render/cesium/input.js", + "src/render/input/wheel.js", "src/render/cesium/ctrlWheelZoom.js", "src/render/input/router.js" ], @@ -1273,6 +1275,7 @@ "src/render/cesium/drawHit.js", "src/render/cesium/cameraInput.js", "src/render/cesium/input.js", + "src/render/input/wheel.js", "src/render/cesium/ctrlWheelZoom.js", "src/render/input/router.js" ], @@ -1448,6 +1451,7 @@ "src/render/cesium/drawHit.js", "src/render/cesium/cameraInput.js", "src/render/cesium/input.js", + "src/render/input/wheel.js", "src/render/cesium/ctrlWheelZoom.js", "src/render/input/router.js" ], @@ -1579,6 +1583,7 @@ "src/render/cesium/common.js", "src/render/rendererOf.js", "src/render/cesium/input.js", + "src/render/input/wheel.js", "src/render/cesium/ctrlWheelZoom.js", "src/render/input/router.js", "src/render/cesium/internals.js" @@ -1690,6 +1695,7 @@ "src/render/cesium/common.js", "src/render/rendererOf.js", "src/render/cesium/input.js", + "src/render/input/wheel.js", "src/render/cesium/ctrlWheelZoom.js", "src/render/input/router.js" ], @@ -1812,6 +1818,7 @@ "src/render/cesium/internals.js", "src/render/rendererOf.js", "src/render/cesium/input.js", + "src/render/input/wheel.js", "src/render/cesium/ctrlWheelZoom.js", "src/render/cesium/cameraControls.js", "src/render/input/router.js" @@ -1988,6 +1995,7 @@ "src/render/cesium/internals.js", "src/render/cesium/common.js", "src/render/cesium/input.js", + "src/render/input/wheel.js", "src/render/cesium/ctrlWheelZoom.js", "src/render/cesium/cameraControls.js", "src/render/input/router.js" @@ -2076,6 +2084,7 @@ "src/render/rendererOf.js", "src/render/cesium/internals.js", "src/render/cesium/input.js", + "src/render/input/wheel.js", "src/render/cesium/ctrlWheelZoom.js", "src/render/input/router.js" ], @@ -2167,6 +2176,7 @@ "src/render/cesium/drawHit.js", "src/render/cesium/cameraInput.js", "src/render/cesium/input.js", + "src/render/input/wheel.js", "src/render/cesium/ctrlWheelZoom.js", "src/render/input/router.js" ], @@ -2266,6 +2276,7 @@ "src/render/cesium/drawHit.js", "src/render/cesium/cameraInput.js", "src/render/cesium/input.js", + "src/render/input/wheel.js", "src/render/cesium/ctrlWheelZoom.js", "src/render/input/router.js" ], @@ -2488,6 +2499,7 @@ "src/render/cesium/internals.js", "src/render/cesium/common.js", "src/render/cesium/input.js", + "src/render/input/wheel.js", "src/render/cesium/ctrlWheelZoom.js", "src/render/cesium/cameraControls.js", "src/render/input/router.js", @@ -2604,6 +2616,7 @@ "src/render/cesium/drawHit.js", "src/render/cesium/cameraInput.js", "src/render/cesium/input.js", + "src/render/input/wheel.js", "src/render/cesium/ctrlWheelZoom.js", "src/render/input/router.js" ], @@ -2719,6 +2732,7 @@ "src/render/cesium/drawHit.js", "src/render/cesium/cameraInput.js", "src/render/cesium/input.js", + "src/render/input/wheel.js", "src/render/cesium/ctrlWheelZoom.js", "src/render/input/router.js", "src/queries/heights.js" @@ -2792,6 +2806,7 @@ "src/render/cesium/drawHit.js", "src/render/cesium/cameraInput.js", "src/render/cesium/input.js", + "src/render/input/wheel.js", "src/render/cesium/ctrlWheelZoom.js", "src/render/input/router.js", "src/queries/heights.js" @@ -2891,6 +2906,7 @@ "src/render/cesium/drawHit.js", "src/render/cesium/cameraInput.js", "src/render/cesium/input.js", + "src/render/input/wheel.js", "src/render/cesium/ctrlWheelZoom.js", "src/render/input/router.js", "src/render/cesium/internals.js" @@ -2957,6 +2973,7 @@ "src/render/cesium/drawHit.js", "src/render/cesium/cameraInput.js", "src/render/cesium/input.js", + "src/render/input/wheel.js", "src/render/cesium/ctrlWheelZoom.js", "src/render/input/router.js" ], @@ -4209,6 +4226,7 @@ "src/input/dispatcher.js", "src/render/cesium/cameraInput.js", "src/render/cesium/input.js", + "src/render/input/wheel.js", "src/render/input/router.js", "src/queries/heights.js", "src/render/cesium/internals.js", @@ -4891,6 +4909,7 @@ "src/render/cesium/drawHit.js", "src/render/cesium/cameraInput.js", "src/render/cesium/input.js", + "src/render/input/wheel.js", "src/render/cesium/ctrlWheelZoom.js", "src/render/input/router.js", "src/queries/heights.js", @@ -5047,6 +5066,7 @@ "src/render/cesium/internals.js", "src/render/cesium/common.js", "src/render/cesium/input.js", + "src/render/input/wheel.js", "src/render/cesium/ctrlWheelZoom.js", "src/render/cesium/cameraControls.js", "src/render/input/router.js", @@ -5357,6 +5377,7 @@ "src/render/cesium/common.js", "src/render/cesium/internals.js", "src/render/cesium/input.js", + "src/render/input/wheel.js", "src/render/cesium/ctrlWheelZoom.js", "src/render/cesium/cameraControls.js", "src/render/input/router.js" @@ -5733,6 +5754,7 @@ "src/render/cesium/drawHit.js", "src/render/cesium/cameraInput.js", "src/render/cesium/input.js", + "src/render/input/wheel.js", "src/render/cesium/ctrlWheelZoom.js", "src/render/input/router.js", "src/queries/heights.js", @@ -5834,6 +5856,7 @@ "src/render/cesium/cameraInput.js", "src/render/cesium/common.js", "src/render/cesium/input.js", + "src/render/input/wheel.js", "src/render/cesium/ctrlWheelZoom.js", "src/render/cesium/cameraControls.js", "src/render/input/router.js", @@ -5916,6 +5939,7 @@ "src/render/cesium/common.js", "src/render/cesium/internals.js", "src/render/cesium/input.js", + "src/render/input/wheel.js", "src/render/cesium/ctrlWheelZoom.js", "src/render/cesium/cameraControls.js", "src/render/input/router.js" @@ -6064,6 +6088,7 @@ "src/render/rendererOf.js", "src/data/entityRecords.js", "src/render/cesium/input.js", + "src/render/input/wheel.js", "src/render/cesium/ctrlWheelZoom.js", "src/render/cesium/cameraControls.js", "src/render/input/router.js", @@ -6359,6 +6384,7 @@ "src/render/conformance/cameraScripts.js", "src/render/conformance/visual.js", "src/render/conformance/cameraRunner.js", + "src/render/input/wheel.js", "src/render/conformance/expect.js", "src/render/conformance/checks/ports.js", "src/render/stub/math.js", diff --git a/src/data/infrastructure.test.mjs b/src/data/infrastructure.test.mjs index 8c2a4ec4c..f41240a05 100644 --- a/src/data/infrastructure.test.mjs +++ b/src/data/infrastructure.test.mjs @@ -227,6 +227,7 @@ test('consumer build includes only infrastructure code and resolves assets under 'stockFollow.js', 'styleStages.js', 'vector.js', + 'wheel.js', ]); assert.deepEqual( entry.imports, diff --git a/src/render/cesium/cameraGoldens.js b/src/render/cesium/cameraGoldens.js index 1197540d9..4b74e4ff0 100644 --- a/src/render/cesium/cameraGoldens.js +++ b/src/render/cesium/cameraGoldens.js @@ -10,11 +10,20 @@ * Cesium has one `changed` threshold per camera, where the contract has one * per listener, so a script that listens at several thresholds is run once * per threshold and each count is taken from its own run. + * + * A script with `input` steps runs a real `ScreenSpaceCameraController` + * over a stand-in canvas: its pointer and wheel events go to the + * controller's own event handler as the DOM would give them (mouse events, + * Cesium's choice where there are no pointer events), and the controller + * updates each frame where Cesium's scene updates it, after the tweens. + * `Date`, which the controller's inertia reads, runs on the virtual clock + * too. */ import * as Cesium from 'cesium'; import { CAMERA_SCRIPTS, SCRIPT_VIEWPORT, + usesInput, } from '../conformance/cameraScripts.js'; import { runCameraScript } from '../conformance/cameraRunner.js'; import { updateCameraChanged } from './internals.js'; @@ -36,23 +45,79 @@ const EASINGS = { /** One frame of the virtual clock, ms. */ export const FRAME_MS = 1000 / 60; -/** Run `fn` with `performance.now()` reading the virtual clock. */ +/** The epoch `Date` reads at virtual time 0. */ +const VIRTUAL_EPOCH_MS = Date.UTC(2026, 0, 1); + +/** Run `fn` with `performance.now()` and `Date` reading the virtual clock. */ export async function withVirtualClock(fn) { const real = Object.getOwnPropertyDescriptor(globalThis, 'performance'); + const RealDate = globalThis.Date; const clock = { now: 0 }; Object.defineProperty(globalThis, 'performance', { configurable: true, value: { now: () => clock.now, mark() {}, measure() {} }, }); + // A function, not a subclass: `Date()` called plainly still gives a + // string, and dates made before stay `instanceof Date`. + function VirtualDate(...args) { + if (!new.target) + return new RealDate(VIRTUAL_EPOCH_MS + clock.now).toString(); + return args.length + ? new RealDate(...args) + : new RealDate(VIRTUAL_EPOCH_MS + clock.now); + } + Object.setPrototypeOf(VirtualDate, RealDate); + VirtualDate.prototype = RealDate.prototype; + VirtualDate.now = () => VIRTUAL_EPOCH_MS + clock.now; + globalThis.Date = VirtualDate; try { return await fn(clock); } finally { + globalThis.Date = RealDate; if (real) Object.defineProperty(globalThis, 'performance', real); } } -/** A Cesium camera on a scene with no globe, sized as the scripts' viewport. */ -export function headlessCamera() { +/** + * A canvas for a controller's event handler: it keeps the listeners the + * handler adds, and `dispatch` calls them as the DOM would. Its root + * events stay on it (`disableRootEvents`), as there is no document; the + * handler still compares its element with one, so a `document` stands in + * while an event is handled, where there is none. + */ +function standInCanvas() { + const listeners = new Map(); + return { + clientWidth: SCRIPT_VIEWPORT.width, + clientHeight: SCRIPT_VIEWPORT.height, + disableRootEvents: true, + onwheel: null, + getBoundingClientRect: () => ({ left: 0, top: 0 }), + addEventListener(type, fn) { + if (!listeners.has(type)) listeners.set(type, new Set()); + listeners.get(type).add(fn); + }, + removeEventListener(type, fn) { + listeners.get(type)?.delete(fn); + }, + dispatch(type, event) { + const own = typeof globalThis.document === 'undefined'; + if (own) globalThis.document = {}; + try { + for (const fn of [...(listeners.get(type) ?? [])]) fn(event); + } finally { + if (own) delete globalThis.document; + } + }, + }; +} + +/** + * A Cesium camera on a scene with no globe, sized as the scripts' viewport. + * With `input`, the scene has a real controller over a stand-in canvas. + * @param {{input?: boolean}} [options] + */ +export function headlessCamera({ input = false } = {}) { const scene = { canvas: { clientWidth: SCRIPT_VIEWPORT.width, @@ -75,9 +140,58 @@ export function headlessCamera() { const camera = new Cesium.Camera(scene); scene.camera = camera; camera.frustum.aspectRatio = SCRIPT_VIEWPORT.width / SCRIPT_VIEWPORT.height; + if (input) { + scene.canvas = standInCanvas(); + // What the controller's update reads off a real scene. + scene.verticalExaggeration = 1; + scene.verticalExaggerationRelativeHeight = 0; + scene.screenSpaceCameraController = new Cesium.ScreenSpaceCameraController( + scene, + ); + } return { scene, camera }; } +/** + * Send a script pointer event (`ScriptPointer`, `cameraRunner.js`) to a + * scene made by `headlessCamera({ input: true })`, as the DOM mouse or + * wheel event Cesium reads. + */ +export function dispatchPointer(scene, ev) { + scene.canvas.dispatch(DOM_TYPES[ev.type], domEvent(ev)); +} + +function domEvent(ev) { + const at = ev.endPosition ?? ev.position; + return { + button: ev.button, + clientX: at.x, + clientY: at.y, + shiftKey: ev.modifiers.shift, + ctrlKey: ev.modifiers.ctrl, + altKey: ev.modifiers.alt, + metaKey: ev.modifiers.meta, + ...(ev.wheel + ? { + deltaX: 0, + deltaY: ev.wheel.deltaY, + deltaMode: ev.wheel.deltaMode, + DOM_DELTA_PIXEL: 0, + DOM_DELTA_LINE: 1, + DOM_DELTA_PAGE: 2, + } + : {}), + preventDefault() {}, + }; +} + +const DOM_TYPES = { + down: 'mousedown', + move: 'mousemove', + up: 'mouseup', + wheel: 'wheel', +}; + const cart = (p) => new Cesium.Cartesian3(p.x, p.y, p.z); const toEcef = (p) => 'lon' in p @@ -101,8 +215,9 @@ function orientationOf(orientation) { } /** A driver for {@link runCameraScript} over a headless Cesium camera. */ -function cesiumDriver(clock, threshold) { - const { scene, camera } = headlessCamera(); +function cesiumDriver(clock, threshold, input = false) { + const { scene, camera } = headlessCamera({ input }); + const controller = input ? scene.screenSpaceCameraController : null; let flying = false; let changedCount = 0; camera.percentageChanged = threshold ?? 0.5; @@ -223,8 +338,14 @@ function cesiumDriver(clock, threshold) { frame() { clock.now += FRAME_MS; scene.tweens.update(); + controller?.update(); updateCameraChanged(camera); }, + ...(input + ? { + pointer: (ev) => dispatchPointer(scene, ev), + } + : {}), listen: () => () => changedCount, pose() { const c = camera.positionCartographic; @@ -295,14 +416,15 @@ async function recordScript(script) { const thresholds = script.steps .filter((step) => step.do === 'listen') .map((step) => step.threshold); + const input = usesInput(script); const base = await withVirtualClock((clock) => - runCameraScript(cesiumDriver(clock, undefined), script), + runCameraScript(cesiumDriver(clock, undefined, input), script), ); if (!thresholds.length) return base; const counts = []; for (const threshold of thresholds) { const run = await withVirtualClock((clock) => - runCameraScript(cesiumDriver(clock, threshold), script), + runCameraScript(cesiumDriver(clock, threshold, input), script), ); const changed = run.records.find((r) => r.kind === 'changed'); counts.push({ threshold, count: changed.value[0].count }); diff --git a/src/render/cesium/cameraPort.test.mjs b/src/render/cesium/cameraPort.test.mjs index 327e2c842..92fd34773 100644 --- a/src/render/cesium/cameraPort.test.mjs +++ b/src/render/cesium/cameraPort.test.mjs @@ -11,8 +11,14 @@ import { CAMERA_SCRIPTS, DEFAULT_TOLERANCE, runConformance, + usesInput, } from '../conformance/index.js'; -import { FRAME_MS, headlessCamera, withVirtualClock } from './cameraGoldens.js'; +import { + FRAME_MS, + dispatchPointer, + headlessCamera, + withVirtualClock, +} from './cameraGoldens.js'; import { createCesiumCamera } from './camera.js'; import { createCesiumPorts } from './ports.js'; import { cameraOf } from '../rendererOf.js'; @@ -27,14 +33,20 @@ const QUERY_RECORDS = new Set([ /** Commands and records the port does not have yet. */ const MISSING = new Set([]); -const runnable = CAMERA_SCRIPTS.filter((script) => - script.steps.every( - (step) => - !MISSING.has(step.do) && - !MISSING.has(step.record) && - !QUERY_RECORDS.has(step.record), - ), +const runnable = CAMERA_SCRIPTS.filter( + (script) => + !usesInput(script) && + script.steps.every( + (step) => + !MISSING.has(step.do) && + !MISSING.has(step.record) && + !QUERY_RECORDS.has(step.record), + ), ).map((script) => `camera.trace.${script.name}`); +/** The scripts that drive the camera by pointer and wheel. */ +const INPUT_CHECKS = new Set( + CAMERA_SCRIPTS.filter(usesInput).map((s) => `camera.trace.${s.name}`), +); const CHECKS = new Set([ ...runnable, @@ -42,11 +54,11 @@ const CHECKS = new Set([ 'camera.controls.settings', ]); -function headlessHarness(clock) { +function headlessHarness(clock, { input = false } = {}) { return { name: 'cesium (headless camera)', async create() { - const { scene } = headlessCamera(); + const { scene } = headlessCamera({ input }); for (const name of ['preUpdate', 'postUpdate', 'preRender', 'postRender']) scene[name] = new Cesium.Event(); scene.primitives = { add() {}, remove() {} }; @@ -65,10 +77,30 @@ function headlessHarness(clock) { frameScene() { clock.now += FRAME_MS; scene.tweens.update(); + if (input) scene.screenSpaceCameraController.update(); scene.postUpdate.raiseEvent(scene); }, + scene, }; }, + ...(input + ? { + cameraInput: true, + // The contract's event back as the DOM's, a wheel in lines: at 40 + // px a line, Cesium reads the pixels the script scrolled. + pointer: (r, type, x, y, extra) => + dispatchPointer(r.scene, { + type, + position: { x, y }, + endPosition: extra.endPosition, + button: extra.button ?? 0, + modifiers: extra.modifiers, + ...(type === 'wheel' + ? { wheel: { deltaY: extra.delta, deltaMode: 1 } } + : {}), + }), + } + : {}), frame: async (r) => r.frameScene(), now: () => clock.now, toEcef: (p) => { @@ -96,6 +128,22 @@ test('the camera port retraces the reference flights, views and frames', async ( assert.equal(report.passed, CHECKS.size); }); +test('Cesium’s own controls under the camera port retrace the drags and wheels, each wheel sent back in the input port’s lines', async () => { + assert.ok(INPUT_CHECKS.size >= 4, `only ${INPUT_CHECKS.size} input scripts`); + const report = await withVirtualClock((clock) => + runConformance(headlessHarness(clock, { input: true }), { + only: (id) => INPUT_CHECKS.has(id), + }), + ); + assert.deepEqual( + report.results + .filter((r) => r.status !== 'pass') + .map((r) => `${r.id}: ${r.status} ${r.detail}`), + [], + ); + assert.equal(report.passed, INPUT_CHECKS.size); +}); + test('a cancelled flight has let go before its callbacks, so they can fly again', async () => { await withVirtualClock(async (clock) => { const { scene, camera } = headlessCamera(); diff --git a/src/render/cesium/input.js b/src/render/cesium/input.js index 22991cc8e..4caa644b2 100644 --- a/src/render/cesium/input.js +++ b/src/render/cesium/input.js @@ -26,6 +26,7 @@ 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'; const T = Cesium.ScreenSpaceEventType; const MODIFIERS = [ @@ -52,8 +53,6 @@ const DOM_EVENTS = [ 'touchcancel', 'dblclick', ]; -/** A wheel notch scrolls 100 px in Chrome, which it counts as three lines. */ -const PX_PER_LINE = 100 / 3; /** A drill is run at least this deep and sliced, so asks share one pass. */ const DRILL_DEPTH = 16; const NO_MODIFIERS = Object.freeze({ @@ -440,16 +439,11 @@ export function createCesiumInput( const onWheel = (event) => { const rect = canvas.getBoundingClientRect?.() ?? { left: 0, top: 0 }; - const lines = - event.deltaMode === 1 - ? event.deltaY - : event.deltaMode === 2 - ? (event.deltaY * (canvas.clientHeight || 0)) / PX_PER_LINE - : event.deltaY / PX_PER_LINE; deliver( 'wheel', { x: event.clientX - rect.left, y: event.clientY - rect.top }, - { delta: lines }, + // Lines as the reference counts them (`../input/wheel.js`). + { delta: wheelLines(event) }, event, ); }; diff --git a/src/render/cesium/input.test.mjs b/src/render/cesium/input.test.mjs index 2536d2e14..cb6192464 100644 --- a/src/render/cesium/input.test.mjs +++ b/src/render/cesium/input.test.mjs @@ -240,7 +240,7 @@ test('ctrlWheelZoom installs the zoom and takes it out again', () => { assert.deepEqual(s.wheelZoom, ['on', 'off', 'on', 'off']); }); -test('wheel is in lines, where the pointer is over the canvas', () => { +test('wheel is in lines as the reference counts them, where the pointer is over the canvas', () => { const s = setup(); const wheels = []; s.port.on('wheel', (ev) => @@ -259,10 +259,18 @@ test('wheel is in lines, where the pointer is over the canvas', () => { deltaY: -3, deltaMode: 1, }); + s.canvas.dispatch('wheel', { + clientX: 10, + clientY: 20, + deltaY: 1, + deltaMode: 2, + }); assert.deepEqual(wheels[0][0], { x: 100, y: 200 }); - assert.equal(wheels[0][1], 3); + // 40 px a line, 3 lines a page: Cesium's own 40 px a line and 120 a page. + assert.equal(wheels[0][1], 2.5); assert.equal(wheels[0][2].ctrl, true); assert.equal(wheels[1][1], -3); + assert.equal(wheels[2][1], 3); }); test('a pinch is the scale since the last event, at its midpoint', () => { diff --git a/src/render/conformance/cameraRunner.js b/src/render/conformance/cameraRunner.js index ba534c675..400c9d74b 100644 --- a/src/render/conformance/cameraRunner.js +++ b/src/render/conformance/cameraRunner.js @@ -5,6 +5,14 @@ * either a renderer through the contract ({@link contractDriver}) or the * reference recorder's own. */ +import { wheelLines } from '../input/wheel.js'; + +const NO_MODIFIERS = Object.freeze({ + shift: false, + ctrl: false, + alt: false, + meta: false, +}); /** * @typedef {object} CameraDriver @@ -18,6 +26,20 @@ * @property {(position: object) => boolean} occluded * @property {() => boolean} flying * @property {(position: object) => object} toEcef + * @property {(ev: ScriptPointer) => void|Promise} [pointer] For scripts with `input` steps. + */ + +/** + * A script's pointer event: `position` is where it happened (for a move, + * where the pointer was) and `endPosition` where a move went; a wheel has + * the DOM's `deltaY` and `deltaMode`. + * @typedef {object} ScriptPointer + * @property {'down'|'move'|'up'|'wheel'} type + * @property {{x: number, y: number}} position + * @property {{x: number, y: number}} [endPosition] + * @property {0|1|2} button + * @property {{shift: boolean, ctrl: boolean, alt: boolean, meta: boolean}} modifiers + * @property {{deltaY: number, deltaMode: number}} [wheel] */ /** The parts of a pose a trace keeps. */ @@ -47,8 +69,33 @@ export async function runCameraScript(driver, script) { const flights = []; const listeners = []; let frame = 0; + // Where the pointer is, for the next move's start, and the button held + // since the last press (a move carries it, as an input port reports it). + // Only a press or a move puts the pointer somewhere, as in the reference: + // a wheel or a release elsewhere leaves the next move starting where the + // pointer last went. + let pointerAt = null; + let held = null; for (const [index, step] of script.steps.entries()) { - if (step.do === 'frames') { + if (step.input) { + const at = { x: step.x, y: step.y }; + const ev = { + type: step.input, + position: step.input === 'move' ? (pointerAt ?? at) : at, + ...(step.input === 'move' ? { endPosition: at } : {}), + button: step.button ?? (step.input === 'move' ? held : null) ?? 0, + modifiers: { ...NO_MODIFIERS, ...(step.modifiers ?? {}) }, + ...(step.input === 'wheel' + ? { wheel: { deltaY: step.deltaY, deltaMode: step.deltaMode ?? 0 } } + : {}), + }; + if (step.input === 'down' || step.input === 'move') pointerAt = at; + if (step.input === 'down') held = ev.button; + else if (step.input === 'up') held = null; + if (!driver.pointer) + throw new Error('this driver takes no pointer input'); + await driver.pointer(ev); + } else if (step.do === 'frames') { for (let i = 0; i < step.count; i++) { frame += 1; await driver.frame(); @@ -143,7 +190,10 @@ function resolveArgs(driver, name, args) { /** * A driver over a renderer, through the contract only. * @param {import('../contract/renderer').Renderer} renderer - * @param {{frame: () => void|Promise, toEcef: (p: object) => object}} hooks + * `hooks.pointer(type, x, y, extra)` sends a pointer event the way a + * harness's `pointer` does; a wheel goes as the input port's lines. + * @param {{frame: () => void|Promise, toEcef: (p: object) => object, + * pointer?: (type: string, x: number, y: number, extra: object) => void|Promise}} hooks * @returns {CameraDriver} */ export function contractDriver(renderer, hooks) { @@ -167,5 +217,16 @@ export function contractDriver(renderer, hooks) { matrices: () => camera.matrices(), viewRectangle: () => camera.viewRectangle(), toEcef: hooks.toEcef, + ...(hooks.pointer + ? { + pointer: (ev) => + hooks.pointer(ev.type, ev.position.x, ev.position.y, { + button: ev.button, + modifiers: ev.modifiers, + ...(ev.endPosition ? { endPosition: ev.endPosition } : {}), + ...(ev.wheel ? { delta: wheelLines(ev.wheel) } : {}), + }), + } + : {}), }; } diff --git a/src/render/conformance/cameraRunner.test.mjs b/src/render/conformance/cameraRunner.test.mjs new file mode 100644 index 000000000..b5c9505b1 --- /dev/null +++ b/src/render/conformance/cameraRunner.test.mjs @@ -0,0 +1,50 @@ +import assert from 'node:assert/strict'; +import test from 'node:test'; + +import { runCameraScript } from './cameraRunner.js'; + +/** A driver that only keeps the pointer events the runner sends. */ +const pointerDriver = () => { + const events = []; + return { + events, + driver: { + pointer: async (ev) => { + events.push(ev); + }, + frame: async () => {}, + }, + }; +}; + +test('a move starts where the pointer last pressed or moved, not at a wheel or release', async () => { + const { events, driver } = pointerDriver(); + await runCameraScript(driver, { + name: 'origins', + steps: [ + { input: 'down', x: 10, y: 10, button: 1 }, + { input: 'wheel', x: 20, y: 20, deltaY: -100 }, + { input: 'move', x: 30, y: 30 }, + { input: 'up', x: 40, y: 40 }, + { input: 'move', x: 50, y: 50 }, + ], + }); + const [, wheel, held, up, free] = events; + assert.deepEqual(wheel.wheel, { deltaY: -100, deltaMode: 0 }); + assert.deepEqual(held.position, { x: 10, y: 10 }); + assert.deepEqual(held.endPosition, { x: 30, y: 30 }); + assert.equal(held.button, 1, 'a move carries the held button'); + assert.equal(up.button, 0); + assert.deepEqual(free.position, { x: 30, y: 30 }); + assert.equal(free.button, 0, 'nothing is held after the release'); +}); + +test('a first move with no earlier pointer starts where it ends', async () => { + const { events, driver } = pointerDriver(); + await runCameraScript(driver, { + name: 'first', + steps: [{ input: 'move', x: 5, y: 6 }], + }); + assert.deepEqual(events[0].position, { x: 5, y: 6 }); + assert.deepEqual(events[0].endPosition, { x: 5, y: 6 }); +}); diff --git a/src/render/conformance/cameraScripts.js b/src/render/conformance/cameraScripts.js index 31d224110..8aa408c61 100644 --- a/src/render/conformance/cameraScripts.js +++ b/src/render/conformance/cameraScripts.js @@ -19,6 +19,16 @@ * `{ record: 'pickEllipsoid', screen }`, `{ record: 'pickRay', screen }`, * `{ record: 'occluded', points }`, `{ record: 'changed' }`, * `{ record: 'flying' }`, `{ record: 'matrices' }`, `{ record: 'viewRectangle' }`. + * - `{ input: 'down' | 'move' | 'up', x, y, button?, modifiers? }`: the + * pointer, in CSS pixels; a move goes from where the pointer last was. + * - `{ input: 'wheel', x, y, deltaY, deltaMode?, modifiers? }`: a wheel as + * the DOM gives it (`deltaMode` 0 pixels, 1 lines, 2 pages); a renderer + * under test gets it as the input port's lines (`render/input/wheel.js`). + * + * A script with `input` steps moves the camera by user input, so it runs + * only where the renderer's camera answers pointer input (a harness with + * `pointer` and `cameraInput`). It starts with a frame, as a pointer event + * on the reference's clock at 0 would be dropped. */ /** Where the scripts, scenes and checks look: downtown Austin, degrees. */ @@ -60,9 +70,52 @@ const SCREEN_GRID = [ { x: 320, y: 540 }, ]; +/** A drag from `from` to `to` in `moves` moves, a frame after each. */ +const drag = ({ + from, + to, + moves = 10, + button = 0, + modifiers, + holdFrames = 0, +}) => { + const mods = modifiers ? { modifiers } : {}; + const steps = [{ input: 'down', ...from, button, ...mods }]; + for (let i = 1; i <= moves; i++) + steps.push( + { + input: 'move', + x: from.x + ((to.x - from.x) * i) / moves, + y: from.y + ((to.y - from.y) * i) / moves, + ...mods, + }, + { do: 'frames', count: 1 }, + ); + if (holdFrames) steps.push({ do: 'frames', count: holdFrames }); + steps.push({ input: 'up', ...to, button, ...mods }); + return steps; +}; + +/** + * `count` wheel notches at the centre, `frames` frames after each. The + * reference zooms towards where the pointer last moved, not where the wheel + * says it is, so a script moves the pointer to the centre first (`hover`). + */ +const notches = (count, deltaY, deltaMode, frames = 2) => + Array.from({ length: count }, () => [ + { input: 'wheel', x: 640, y: 360, deltaY, deltaMode }, + { do: 'frames', count: frames }, + ]).flat(); + +/** The pointer moves to the centre with nothing held. */ +const hover = { input: 'move', x: 640, y: 360 }; + /** The viewport every script runs in, CSS pixels. */ export const SCRIPT_VIEWPORT = Object.freeze({ width: 1280, height: 720 }); +/** Whether a script moves the camera by user input (`input` steps). */ +export const usesInput = (script) => script.steps.some((step) => step.input); + /** @type {ReadonlyArray<{name: string, steps: object[]}>} */ export const CAMERA_SCRIPTS = Object.freeze([ { @@ -442,6 +495,90 @@ export const CAMERA_SCRIPTS = Object.freeze([ { record: 'changed' }, ], }, + { + name: 'a left drag turns the globe under the pointer, then coasts', + steps: [ + city(5000, 0.2, -1.2), + { do: 'frames', count: 1 }, + ...drag({ from: { x: 640, y: 360 }, to: { x: 760, y: 420 } }), + { record: 'pose' }, + { do: 'frames', count: 20 }, + { record: 'pose' }, + { do: 'frames', count: 60 }, + { record: 'pose' }, + START, + { do: 'frames', count: 1 }, + ...drag({ from: { x: 600, y: 300 }, to: { x: 500, y: 360 } }), + { do: 'frames', count: 60 }, + { record: 'pose' }, + ], + }, + { + name: 'thirty pixel-mode wheel notches from 5 km, then out again', + steps: [ + city(5000, 0.2, -1.2), + { do: 'frames', count: 1 }, + hover, + ...notches(10, -100, 0), + { record: 'pose' }, + ...notches(10, -100, 0), + { record: 'pose' }, + ...notches(10, -100, 0), + { record: 'pose' }, + { do: 'frames', count: 60 }, + { record: 'pose' }, + ...notches(5, 100, 0), + { do: 'frames', count: 60 }, + { record: 'pose' }, + ], + }, + { + name: 'thirty line-mode wheel notches from 5 km', + steps: [ + city(5000, 0.2, -1.2), + { do: 'frames', count: 1 }, + hover, + ...notches(10, -3, 1), + { record: 'pose' }, + ...notches(20, -3, 1), + { do: 'frames', count: 60 }, + { record: 'pose' }, + ], + }, + { + name: 'a middle drag tilts about the centre, then coasts', + steps: [ + city(2000, 0.3, -1.0), + { do: 'frames', count: 1 }, + ...drag({ from: { x: 640, y: 360 }, to: { x: 640, y: 300 }, button: 1 }), + { record: 'pose' }, + { do: 'frames', count: 60 }, + { record: 'pose' }, + ], + }, + { + name: 'modified drags: Shift looks, Ctrl tilts, held too long to coast', + steps: [ + city(2000, 0.3, -0.5), + { do: 'frames', count: 1 }, + ...drag({ + from: { x: 640, y: 360 }, + to: { x: 700, y: 330 }, + modifiers: { shift: true }, + holdFrames: 30, + }), + { do: 'frames', count: 10 }, + { record: 'pose' }, + ...drag({ + from: { x: 640, y: 360 }, + to: { x: 640, y: 320 }, + modifiers: { ctrl: true }, + holdFrames: 30, + }), + { do: 'frames', count: 10 }, + { record: 'pose' }, + ], + }, { name: 'projection, picks and the horizon', steps: [ diff --git a/src/render/conformance/checks/camera.js b/src/render/conformance/checks/camera.js index 3976005a8..6a14d5dd7 100644 --- a/src/render/conformance/checks/camera.js +++ b/src/render/conformance/checks/camera.js @@ -3,7 +3,11 @@ * view rules the traces cannot show. */ import goldens from '../goldens/camera.json' with { type: 'json' }; -import { CAMERA_SCRIPTS, SCRIPT_VIEWPORT } from '../cameraScripts.js'; +import { + CAMERA_SCRIPTS, + SCRIPT_VIEWPORT, + usesInput, +} from '../cameraScripts.js'; import { contractDriver, runCameraScript } from '../cameraRunner.js'; import { deepEqual, equal, near, nearAngle, nearVec, ok } from '../expect.js'; @@ -136,6 +140,11 @@ export function cameraChecks() { async run(h) { const expected = goldens.scripts[script.name]; ok(expected, `no reference trace for ${script.name}`); + const input = usesInput(script); + if (input && h.cameraInput && !h.pointer) + throw new Error('a harness with cameraInput needs pointer'); + if (input && !h.cameraInput) + return { skip: 'the harness has no camera that answers pointer input' }; const r = await fresh(h); try { if (script.capability && !r.capabilities.has(script.capability)) @@ -144,6 +153,12 @@ export function cameraChecks() { contractDriver(r, { frame: () => h.frame(r), toEcef: lonLatToEcef(h), + ...(input + ? { + pointer: (type, x, y, extra) => + h.pointer(r, type, x, y, extra), + } + : {}), }), script, ); diff --git a/src/render/conformance/goldens/camera.json b/src/render/conformance/goldens/camera.json index a4261d14e..3c14b6a32 100644 --- a/src/render/conformance/goldens/camera.json +++ b/src/render/conformance/goldens/camera.json @@ -2312,6 +2312,496 @@ ], "flights": [] }, + "a left drag turns the globe under the pointer, then coasts": { + "records": [ + { + "step": 24, + "kind": "pose", + "value": { + "position": { + "x": -743874.2827583898, + "y": -5467123.5663921, + "z": 3198867.771901153 + }, + "direction": { + "x": 0.20397712796409123, + "y": 0.9652906415976404, + "z": -0.1631174684438692 + }, + "up": { + "x": 0.2033249113752558, + "y": 0.12121518562266298, + "z": 0.9715790545234638 + }, + "right": { + "x": 0.9576284831195057, + "y": -0.2313457499468691, + "z": -0.17154250872525903 + }, + "heading": 0.19995498090715547, + "pitch": -1.1999997631348354, + "roll": 6.283185067768231, + "height": 5001.202022602089, + "frameIsIdentity": true + } + }, + { + "step": 26, + "kind": "pose", + "value": { + "position": { + "x": -744179.2414489042, + "y": -5466945.298349385, + "z": 3199101.5023454726 + }, + "direction": { + "x": 0.2040230499283474, + "y": 0.9652742041266187, + "z": -0.1631573042975954 + }, + "up": { + "x": 0.20331111154933998, + "y": 0.12125033636499621, + "z": 0.971577556272245 + }, + "right": { + "x": 0.9576216304044657, + "y": -0.231395909166732, + "z": -0.1715131079608628 + }, + "heading": 0.199925453927559, + "pitch": -1.199999607856077, + "roll": 6.2831849106714515, + "height": 5001.990172385319, + "frameIsIdentity": true + } + }, + { + "step": 28, + "kind": "pose", + "value": { + "position": { + "x": -744372.9914909918, + "y": -5466832.025336116, + "z": 3199249.992913194 + }, + "direction": { + "x": 0.20405222591363384, + "y": 0.9652637587817955, + "z": -0.1631826126832485 + }, + "up": { + "x": 0.20330234482603304, + "y": 0.1212726692625212, + "z": 0.9715766034020066 + }, + "right": { + "x": 0.9576172751616003, + "y": -0.23142777636313006, + "z": -0.171494427430424 + }, + "heading": 0.19990669247367698, + "pitch": -1.19999950921419, + "roll": 6.283184810827273, + "height": 5002.490919151834, + "frameIsIdentity": true + } + }, + { + "step": 54, + "kind": "pose", + "value": { + "position": { + "x": 7805906.904869736, + "y": -14670498.917206015, + "z": 13440141.433819043 + }, + "direction": { + "x": -0.3655537074410778, + "y": 0.6843524703919436, + "z": -0.6308979182439318 + }, + "up": { + "x": 0.110917768366866, + "y": 0.7050070428413021, + "z": 0.7004729246763767 + }, + "right": { + "x": 0.9241578521208361, + "y": 0.18608268541862594, + "z": -0.3336247870749348 + }, + "heading": 0.443475027365972, + "pitch": -1.5693855130982848, + "roll": 0, + "height": 15003040.278641503, + "frameIsIdentity": true + } + } + ], + "flights": [] + }, + "thirty pixel-mode wheel notches from 5 km, then out again": { + "records": [ + { + "step": 23, + "kind": "pose", + "value": { + "position": { + "x": -742628.7924789503, + "y": -5463700.648822847, + "z": 3197887.172893453 + }, + "direction": { + "x": 0.20390710151866062, + "y": 0.9653157014443385, + "z": -0.1630567094457735 + }, + "up": { + "x": 0.2033459565896657, + "y": 0.12116157542641381, + "z": 0.971581337088575 + }, + "right": { + "x": 0.9576389277221831, + "y": -0.23126925689597005, + "z": -0.17158733906058854 + }, + "heading": 0.20002548249494634, + "pitch": -1.1997833418598227, + "roll": 6.283184995415831, + "height": 1432.7693523452285, + "frameIsIdentity": true + } + }, + { + "step": 44, + "kind": "pose", + "value": { + "position": { + "x": -742405.2309695639, + "y": -5462642.287276622, + "z": 3197708.399305835 + }, + "direction": { + "x": 0.20390710151866057, + "y": 0.9653157014443385, + "z": -0.1630567094457731 + }, + "up": { + "x": 0.20334595658966526, + "y": 0.12116157542641454, + "z": 0.9715813370885751 + }, + "right": { + "x": 0.9576389277221832, + "y": -0.2312692568959699, + "z": -0.17158733906058796 + }, + "heading": 0.20003278999578278, + "pitch": -1.1997212353912805, + "roll": 6.283184906110748, + "height": 410.9902001027421, + "frameIsIdentity": true + } + }, + { + "step": 65, + "kind": "pose", + "value": { + "position": { + "x": -742341.2056470874, + "y": -5462339.185282548, + "z": 3197657.2007044787 + }, + "direction": { + "x": 0.20390710151866076, + "y": 0.9653157014443386, + "z": -0.16305670944577244 + }, + "up": { + "x": 0.20334595658966534, + "y": 0.121161575426415, + "z": 0.971581337088575 + }, + "right": { + "x": 0.9576389277221832, + "y": -0.23126925689596994, + "z": -0.17158733906058796 + }, + "heading": 0.20003488343521703, + "pitch": -1.199703445182633, + "roll": 6.28318488053483, + "height": 118.36954505315934, + "frameIsIdentity": true + } + }, + { + "step": 67, + "kind": "pose", + "value": { + "position": { + "x": -742333.1507133974, + "y": -5462301.052456831, + "z": 3197650.759482114 + }, + "direction": { + "x": 0.20390710151866143, + "y": 0.9653157014443386, + "z": -0.16305670944577194 + }, + "up": { + "x": 0.20334595658966512, + "y": 0.12116157542641479, + "z": 0.9715813370885751 + }, + "right": { + "x": 0.9576389277221832, + "y": -0.23126925689597047, + "z": -0.1715873390605877 + }, + "heading": 0.20003514682861567, + "pitch": -1.199701206906512, + "roll": 6.283184877317159, + "height": 81.55550603363947, + "frameIsIdentity": true + } + }, + { + "step": 79, + "kind": "pose", + "value": { + "position": { + "x": -742361.5559644367, + "y": -5462435.52562931, + "z": 3197673.474074843 + }, + "direction": { + "x": 0.2039071015186621, + "y": 0.9653157014443386, + "z": -0.1630567094457709 + }, + "up": { + "x": 0.2033459565896656, + "y": 0.12116157542641448, + "z": 0.971581337088575 + }, + "right": { + "x": 0.957638927722183, + "y": -0.23126925689597097, + "z": -0.17158733906058815 + }, + "heading": 0.2000342180079615, + "pitch": -1.199709099940855, + "roll": 6.283184888664081, + "height": 211.37819848930863, + "frameIsIdentity": true + } + } + ], + "flights": [] + }, + "thirty line-mode wheel notches from 5 km": { + "records": [ + { + "step": 23, + "kind": "pose", + "value": { + "position": { + "x": -742556.7099509701, + "y": -5463359.40324807, + "z": 3197829.5312530524 + }, + "direction": { + "x": 0.20390710151866023, + "y": 0.9653157014443386, + "z": -0.1630567094457732 + }, + "up": { + "x": 0.203345956589666, + "y": 0.12116157542641305, + "z": 0.9715813370885751 + }, + "right": { + "x": 0.9576389277221831, + "y": -0.2312692568959697, + "z": -0.17158733906058904 + }, + "heading": 0.20002783824820192, + "pitch": -1.1997633191576402, + "roll": 6.283184966621368, + "height": 1103.3162549917931, + "frameIsIdentity": true + } + }, + { + "step": 65, + "kind": "pose", + "value": { + "position": { + "x": -742322.8917203792, + "y": -5462252.485403653, + "z": 3197642.555757815 + }, + "direction": { + "x": 0.20390710151865987, + "y": 0.9653157014443383, + "z": -0.16305670944577555 + }, + "up": { + "x": 0.20334595658966786, + "y": 0.12116157542641243, + "z": 0.9715813370885749 + }, + "right": { + "x": 0.9576389277221826, + "y": -0.23126925689597005, + "z": -0.17158733906059095 + }, + "heading": 0.20003548230067558, + "pitch": -1.1996983561368815, + "roll": 6.2831848732190485, + "height": 34.668143935951555, + "frameIsIdentity": true + } + } + ], + "flights": [] + }, + "a middle drag tilts about the centre, then coasts": { + "records": [ + { + "step": 24, + "kind": "pose", + "value": { + "position": { + "x": -743241.7317811222, + "y": -5464487.455673964, + "z": 3195978.047404553 + }, + "direction": { + "x": 0.3675783291212823, + "y": 0.81316539817522, + "z": 0.4512739823776041 + }, + "up": { + "x": 0.08270178763465089, + "y": -0.5119037171950899, + "z": 0.8550526291661131 + }, + "right": { + "x": 0.9263080407091582, + "y": -0.27697765168400346, + "z": -0.2554149451092779 + }, + "heading": 0.3008134433902425, + "pitch": -0.5367351449364697, + "roll": 6.282589696577563, + "height": 1215.0821198795002, + "frameIsIdentity": true + } + }, + { + "step": 26, + "kind": "pose", + "value": { + "position": { + "x": -743241.80671276, + "y": -5463765.475245942, + "z": 3195201.3342659683 + }, + "direction": { + "x": 0.36760985348731867, + "y": 0.5094221457939676, + "z": 0.7780437474806298 + }, + "up": { + "x": -0.0855345107763599, + "y": -0.8145571574843389, + "z": 0.5737425247071049 + }, + "right": { + "x": 0.9260382514158263, + "y": -0.2774629967503845, + "z": -0.2558660633007341 + }, + "heading": 0.3012445916881008, + "pitch": -0.08686439532730006, + "roll": 6.282451156320272, + "height": 205.77116965382524, + "frameIsIdentity": true + } + } + ], + "flights": [] + }, + "modified drags: Shift looks, Ctrl tilts, held too long to coast": { + "records": [ + { + "step": 26, + "kind": "pose", + "value": { + "position": { + "x": -743060.1500720647, + "y": -5464827.966102482, + "z": 3196999.1724985815 + }, + "direction": { + "x": 0.3198554534385449, + "y": 0.8196936321897058, + "z": 0.4751787434779361 + }, + "up": { + "x": 0.07739593213172483, + "y": -0.5224541754567694, + "z": 0.8491475161815223 + }, + "right": { + "x": 0.9442999304220479, + "y": -0.2348275620437983, + "z": -0.23055076991734758 + }, + "heading": 0.2406372218166659, + "pitch": -0.5226924574159404, + "roll": 0.028997148507913906, + "height": 2000.0000000013995, + "frameIsIdentity": true + } + }, + { + "step": 51, + "kind": "pose", + "value": { + "position": { + "x": -743061.3004932855, + "y": -5464044.082279529, + "z": 3196047.0359984883 + }, + "direction": { + "x": 0.3201424713636519, + "y": 0.6241229075555551, + "z": 0.712726731849994 + }, + "up": { + "x": -0.02221334720207947, + "y": -0.7471697869219248, + "z": 0.66426190370751 + }, + "right": { + "x": 0.9471089510902393, + "y": -0.22849049384043377, + "z": -0.22533692327113536 + }, + "heading": 0.2408776874059173, + "pitch": -0.21383964601254024, + "roll": 0.028905924656936755, + "height": 849.3858537714274, + "frameIsIdentity": true + } + } + ], + "flights": [] + }, "projection, picks and the horizon": { "records": [ { diff --git a/src/render/conformance/index.js b/src/render/conformance/index.js index c071b121a..810a62167 100644 --- a/src/render/conformance/index.js +++ b/src/render/conformance/index.js @@ -19,7 +19,8 @@ * ``` * * Optional harness members widen what is checked: `pointer(r, type, x, y)` - * (synthetic input), `scriptHeights(r, fn)` (heights from a function), + * (synthetic input; with `cameraInput`, the camera scripts' drags and + * wheels too), `scriptHeights(r, fn)` (heights from a function), * `wallTime(r)` (the wall clock a `live` motion clock reads), * `assets.model` (a glTF URL). `create` may return null when it cannot * make a renderer with fewer capabilities; those checks are then skipped. @@ -46,6 +47,10 @@ import { portChecks } from './checks/ports.js'; * @property {ConformanceTolerance} tolerance * @property {'trace'|'endpoints'} flightPaths Whether flight paths are compared frame by frame, or only where flights end. * @property {(r: object, type: string, x: number, y: number, extra?: object) => void|Promise} [pointer] + * A move's `x, y` is where it started and `extra.endPosition` where it + * went; `extra` also has `button` (a move's the one held), `modifiers` + * and, for a wheel, `delta` in the input port's lines. + * @property {boolean} [cameraInput] The renderer's camera moves on pointer input sent through `pointer` (its own gestures, or a camera controller's): the camera scripts with `input` steps run. * @property {(r: object, fn: (point: {lon: number, lat: number}, against?: string) => number|null) => void} [scriptHeights] * @property {(r: object) => number} [wallTime] Epoch ms the renderer's `live` motion clock reads. * @property {{model?: string}} [assets] @@ -111,7 +116,7 @@ export async function runConformance(harness, options = {}) { }; } -export { CAMERA_SCRIPTS, SCRIPT_VIEWPORT } from './cameraScripts.js'; +export { CAMERA_SCRIPTS, SCRIPT_VIEWPORT, usesInput } from './cameraScripts.js'; export { CALIBRATION_PATH, REFERENCE_SCENES, sceneSupport } from './scenes.js'; export { VISUAL_TOLERANCE, diff --git a/src/render/contract/input.d.ts b/src/render/contract/input.d.ts index 742377581..c2dd8b6ea 100644 --- a/src/render/contract/input.d.ts +++ b/src/render/contract/input.d.ts @@ -57,7 +57,12 @@ export interface PointerEv { pointerType: 'mouse' | 'touch' | 'pen'; /** `click`: how far the pointer travelled and how long the press lasted. */ gesture?: { travelPx: number; durationMs: number }; - /** `wheel`: lines scrolled; `pinch`: scale since the last event. */ + /** + * `wheel`: lines scrolled, down positive, counted as the reference + * renderer counts them: a pixel-mode wheel at 40 px a line, a page at 3 + * lines (so 40 px a line turns either back into the reference's pixels); + * `pinch`: scale since the last event. + */ delta?: number; /** `click` and `dblclick`: the hit under the pointer, picked once for every subscriber. */ pick?(): Hit | null; diff --git a/src/render/input/wheel.js b/src/render/input/wheel.js new file mode 100644 index 000000000..41e0eed4c --- /dev/null +++ b/src/render/input/wheel.js @@ -0,0 +1,29 @@ +/** + * @module render/input/wheel + * @description A DOM wheel event as the input port's `wheel` delta: lines + * scrolled, counted as the reference renderer counts them, so a camera + * controller that turns lines back into pixels at `WHEEL_PX_PER_LINE` + * zooms exactly as the reference does in every browser. + * + * The reference takes a pixel-mode wheel as its pixels, a line-mode one at + * 40 px a line and a page-mode one at 120 px a page. Lines are those + * pixels over 40: a line-mode wheel is its own lines, a page is 3 lines, + * and a pixel-mode wheel (Chrome's notch is 100 px) is its pixels over 40 + * (2.5 lines a notch). + */ + +/** Pixels a wheel line stands for: the reference renderer's own count. */ +export const WHEEL_PX_PER_LINE = 40; +/** Lines a wheel page stands for: the reference's 120 px a page. */ +export const WHEEL_LINES_PER_PAGE = 3; + +/** + * Lines scrolled by a DOM wheel event, down positive (as `deltaY`). + * @param {{deltaY: number, deltaMode?: number}} event + * @returns {number} + */ +export function wheelLines({ deltaY, deltaMode = 0 }) { + if (deltaMode === 1) return deltaY; + if (deltaMode === 2) return deltaY * WHEEL_LINES_PER_PAGE; + return deltaY / WHEEL_PX_PER_LINE; +} diff --git a/src/render/stub/stub.test.mjs b/src/render/stub/stub.test.mjs index 547fbc148..09b34b0fd 100644 --- a/src/render/stub/stub.test.mjs +++ b/src/render/stub/stub.test.mjs @@ -2,7 +2,11 @@ import { test } from 'node:test'; import assert from 'node:assert/strict'; import { createStubRenderer } from './index.js'; import { createStubHarness } from './harness.js'; -import { runConformance } from '../conformance/index.js'; +import { + CAMERA_SCRIPTS, + runConformance, + usesInput, +} from '../conformance/index.js'; import { toEcef } from './math.js'; test('the stub passes the conformance suite', async () => { @@ -15,7 +19,12 @@ test('the stub passes the conformance suite', async () => { const skipped = report.results .filter((r) => r.status === 'skip') .map((r) => r.id); - assert.deepEqual(skipped, []); + // Its camera takes no user gestures: the drag and wheel scripts are for + // a camera that does (a controller over it, say). + assert.deepEqual( + skipped, + CAMERA_SCRIPTS.filter(usesInput).map((s) => `camera.trace.${s.name}`), + ); }); test('a frame runs the contract’s steps in order', () => {