fix(render): wheel zoom no longer stalls with an icon under the canvas centre

Below 150 km Cesium sizes a zoom step from the depth it picks at the canvas
centre. Since #1835 an icon drawn over depth wrote a depth just past the near
plane, which that pick took for a surface a near plane's distance from the
camera: zooming in returned early and zooming out moved by centimetres.

Over-depth rows now write a depth of exactly 0 in the fragment shader. It is
never discarded (the flicker #1835 fixed stays fixed) and the depth pick
reads it as nothing drawn, keeping the ground under the icon.

Adds scripts/qa-zoom-under-icon.mjs (real browser) and a source-level unit
test.
This commit is contained in:
Said Turksever committed 2026-11-19 19:18:31 +00:00
1 parent 2796c2547b
commit 8b122dc259
5 files changed
+268 -9

No files matched your search

+10
View File
@@ -93,6 +93,16 @@ settling. Oblique views below 300 km are left alone.
`QA_BASE_URL=http://localhost:4173 node scripts/qa-zoom-out-guard.mjs` exercises
the real browser controller at desktop and phone widths with keyless fixtures.
Below 150 km Cesium sizes a wheel or pinch zoom step from the depth it picks at
the canvas centre. Icons drawn over depth (aircraft, vessels and most markers:
`disableDepthTest: Infinity`) sit on the near plane and write a depth of
exactly 0 there (`src/render/cesium/iconSetPrimitive.js`), which that pick
reads as nothing drawn, so it keeps the ground under the icon. Any depth past
the near plane would be taken for a surface a near plane's distance from the
camera, and the zoom would stop while an icon is under the centre.
`QA_BASE_URL=http://localhost:5173 node scripts/qa-zoom-under-icon.mjs` checks
this against a dev server (`npm run dev`).
Cesium's free look (Shift+drag, which turns the camera in place) works only
below 1,000 km. Above that height a few drags could turn the whole planet out of
frame and leave only stars, so Shift+drag does nothing there. Cesium also turns
+1
View File
@@ -1290,6 +1290,7 @@
"src/render/cesium/zoomOutGuard.test.mjs",
"src/app/controls.test.mjs",
"scripts/qa-zoom-out-guard.mjs",
"scripts/qa-zoom-under-icon.mjs",
"src/hudSummaryGate.test.mjs",
"src/hudSummaryLine.test.mjs",
"src/testSupport/stubMgrs.mjs",
+214
View File
@@ -0,0 +1,214 @@
#!/usr/bin/env node
/**
* Real-app regression: the wheel zooms with an over-depth icon under the
* centre of the canvas. Start a dev server (`npm run dev`), then run this
* file with QA_BASE_URL set to it.
*
* Below 150 km Cesium sizes a zoom step from the depth it picks at the canvas
* centre. An icon drawn over depth must leave nothing there for that pick, or
* the camera takes the icon (a metre away, on the near plane) for the ground
* and stops zooming.
*/
import assert from 'node:assert/strict';
import puppeteer from 'puppeteer';
const origin = process.env.QA_BASE_URL || 'http://localhost:4173';
const CAMERA_HEIGHT_M = 15_000;
const browser = await puppeteer.launch({
headless: true,
args: [
'--no-sandbox',
...(process.platform === 'darwin'
? ['--use-angle=metal', '--enable-gpu']
: [
'--use-gl=angle',
'--use-angle=swiftshader',
'--enable-unsafe-swiftshader',
]),
],
protocolTimeout: 120_000,
});
const errors = [];
try {
const page = await browser.newPage();
page.on('pageerror', (error) => errors.push(error.message));
const viewport = { width: 1200, height: 800 };
await page.setViewport(viewport);
await page.goto(`${origin}/?welcome=0`, { waitUntil: 'domcontentloaded' });
await page.waitForFunction(
() =>
window.__godsEyeView?.viewer &&
window.__godsEyeView.viewer.scene.screenSpaceCameraController
.enableInputs &&
document.getElementById('loading-screen')?.classList.contains('hidden'),
{ timeout: 90_000 },
);
const setup = await page.evaluate(async (cameraHeight) => {
const C = await import('/node_modules/cesium/Build/Cesium/index.js');
const { drawOf } = await import('/src/render/rendererOf.js');
const viewer = window.__godsEyeView.viewer;
const scene = viewer.scene;
viewer.camera.cancelFlight();
viewer.trackedEntity = undefined;
// Explicit real renders make each gesture independent of host frame rate.
viewer.useDefaultRenderLoop = false;
const controller = scene.screenSpaceCameraController;
controller.inertiaZoom = 0;
controller.inertiaSpin = 0;
const lon = -30;
const lat = 40; // open Atlantic: nothing else of the app's draws here
const icons = drawOf(viewer).icons({ id: 'qa-zoom-under-icon' });
const item = {
id: 'qa-icon',
pos: C.Cartesian3.fromDegrees(lon, lat, 100),
// Held in place on the GPU, as a live aircraft or vessel icon is.
motion: { kind: 'hold', courseDeg: 0 },
image: `data:image/svg+xml;charset=utf-8,${encodeURIComponent(
'<svg xmlns="http://www.w3.org/2000/svg" width="64" height="64"><rect width="64" height="64" fill="#f0f"/></svg>',
)}`,
size: [64, 64],
disableDepthTest: Infinity,
};
const centre = () =>
new C.Cartesian2(
scene.canvas.clientWidth / 2,
scene.canvas.clientHeight / 2,
);
const frame = () => {
scene.requestRender();
viewer.render();
};
const qa = {
height: () => viewer.camera.positionCartographic.height,
setIcon(shown) {
icons.set(shown ? [item] : []);
},
reset() {
viewer.camera.cancelFlight();
viewer.camera.lookAtTransform(C.Matrix4.IDENTITY);
viewer.camera.setView({
destination: C.Cartesian3.fromDegrees(lon, lat, cameraHeight),
orientation: { heading: 0, pitch: -C.Math.PI_OVER_TWO, roll: 0 },
});
frame();
},
async frames(count) {
for (let i = 0; i < count; i++) {
frame();
await new Promise((resolve) => setTimeout(resolve, 0));
}
return qa.height();
},
/** Whether the icon is what a click at the canvas centre picks. */
iconAtCentre() {
const picked = scene.pick(centre());
return JSON.stringify(picked?.id ?? null).includes('qa-icon');
},
/** Metres from the camera to what the depth pick finds at the centre. */
centreDepthM() {
frame();
const point = scene.pickPositionWorldCoordinates(centre());
return point
? C.Cartesian3.distance(point, viewer.camera.positionWC)
: null;
},
};
window.__zoomUnderIconQa = qa;
const gl = scene.context._gl;
const debug = gl.getExtension('WEBGL_debug_renderer_info');
return {
renderer: gl.getParameter(
debug ? debug.UNMASKED_RENDERER_WEBGL : gl.RENDERER,
),
logDepth: scene.logarithmicDepthBuffer,
pickPosition: scene.pickPositionSupported,
};
}, CAMERA_HEIGHT_M);
console.log(
`[INFO] WebGL renderer: ${setup.renderer}; log depth ${setup.logDepth}`,
);
assert.ok(setup.pickPosition, 'the context must support depth picks');
const qa = (method, ...args) =>
page.evaluate(
(name, rest) => window.__zoomUnderIconQa[name](...rest),
method,
args,
);
const x = viewport.width / 2;
const y = viewport.height / 2;
await page.mouse.move(x, y);
/** Wheel `deltaY` at the canvas centre, then the settled camera height. */
const wheel = async (deltaY) => {
await qa('reset');
await page.evaluate(
({ x, y, deltaY }) => {
window.__godsEyeView.viewer.canvas.dispatchEvent(
new WheelEvent('wheel', {
deltaY,
clientX: x,
clientY: y,
bubbles: true,
cancelable: true,
}),
);
},
{ x, y, deltaY },
);
return qa('frames', 40);
};
// The ground alone: what the icon must not change.
await qa('setIcon', false);
await qa('reset');
await qa('frames', 10);
const groundDepth = await qa('centreDepthM');
const groundIn = await wheel(-600);
const groundOut = await wheel(600);
console.log(
`[INFO] no icon: centre depth ${groundDepth?.toFixed(1)} m, wheel in to ${groundIn.toFixed(0)} m, out to ${groundOut.toFixed(0)} m`,
);
assert.ok(groundIn < CAMERA_HEIGHT_M * 0.95, 'control: wheel in zooms in');
assert.ok(groundOut > CAMERA_HEIGHT_M * 1.05, 'control: wheel out zooms out');
await qa('setIcon', true);
await qa('reset');
await page.waitForFunction(
async () => {
await window.__zoomUnderIconQa.frames(1);
return window.__zoomUnderIconQa.iconAtCentre();
},
{ timeout: 30_000 },
);
console.log('[PASS] the icon draws under the canvas centre');
const depth = await qa('centreDepthM');
const zoomedIn = await wheel(-600);
const zoomedOut = await wheel(600);
console.log(
`[INFO] icon at centre: depth pick ${depth === null ? 'finds nothing' : `${depth.toFixed(3)} m away`}, wheel in to ${zoomedIn.toFixed(0)} m, out to ${zoomedOut.toFixed(0)} m`,
);
assert.ok(
depth === null || depth > 100,
`the depth pick must not land on the icon (${depth} m from the camera)`,
);
console.log('[PASS] the depth pick at the centre ignores the icon');
assert.ok(
zoomedIn < CAMERA_HEIGHT_M * 0.95,
`wheel in must zoom in under an icon (height ${zoomedIn.toFixed(1)} m)`,
);
console.log('[PASS] wheel in zooms in');
assert.ok(
zoomedOut > CAMERA_HEIGHT_M * 1.05,
`wheel out must zoom out under an icon (height ${zoomedOut.toFixed(1)} m)`,
);
console.log('[PASS] wheel out zooms out');
assert.ok(await qa('iconAtCentre'), 'the icon must still pick by click');
console.log('[PASS] the icon still picks by click');
assert.deepEqual(errors, [], 'no JavaScript page errors');
console.log('[PASS] no JavaScript page errors');
} finally {
await browser.close();
}
+16 -9
View File
@@ -92,6 +92,7 @@ out vec2 v_uv;
out vec4 v_color;
out vec4 v_pickColor;
out float v_proxy;
out float v_overDepth; // 1 for a row drawn over depth, on the near plane
// The row's anchor in clip space before screen offsets, for effects that wrap
// main() (sonar) and must not change geometry or picks.
@@ -125,6 +126,7 @@ void main() {
v_uv = vec2(0.0);
v_color = vec4(0.0);
v_proxy = 0.0;
v_overDepth = 0.0;
gl_Position = vec4(0.0, 0.0, 2.0, 1.0); // outside the clip volume: not drawn
float flags = style1.z;
@@ -260,14 +262,9 @@ void main() {
distanceSq < style3.w * style3.w;
if (overDepth && zclip >= -1.0 && zclip <= 1.0) {
gl_Position.z = -gl_Position.w;
#ifdef LOG_DEPTH
// Just past the near plane, not on it: czm_writeLogDepth discards a
// fragment at or below 0.9999999, and 1.0 interpolated across the quad
// can arrive a rounding step or two under that, dropping the icon for a
// frame as it moves (flicker). 1e-4 m past the near plane is still in
// front of everything the scene draws.
v_depthFromNearPlusOne = 1.0001;
#endif
// With a log depth buffer the fragment shader writes the near plane's
// depth itself.
v_overDepth = 1.0;
}
v_uv = mix(rect.xy, rect.zw, vec2(corner.x * 0.5 + 0.5, 0.5 - corner.y * 0.5));
@@ -282,6 +279,7 @@ in vec2 v_uv;
in vec4 v_color;
in vec4 v_pickColor;
in float v_proxy;
in float v_overDepth;
void main() {
vec4 color = czm_gammaCorrect(texture(u_atlas, v_uv));
@@ -296,7 +294,16 @@ void main() {
#endif
out_FragColor = color;
#ifdef LOG_DEPTH
czm_writeLogDepth(v_depthFromNearPlusOne);
// Over depth: exactly the near plane's depth, written here and not through
// czm_writeLogDepth. That function discards a fragment whose interpolated
// depth arrives a rounding step under the near plane (the icon drops for a
// frame as it moves), and any depth past the near plane is a surface to
// Cesium's depth pick: the camera controller then sizes a zoom step from an
// icon under the canvas centre, a near plane's distance away, and the wheel
// stops zooming. The pick reads a depth of 0 as nothing drawn, and keeps
// the depth of the ground under the icon.
if (v_overDepth > 0.5) gl_FragDepth = 0.0;
else czm_writeLogDepth(v_depthFromNearPlusOne);
#endif
}
`;
@@ -1,5 +1,6 @@
import assert from 'node:assert/strict';
import test from 'node:test';
import fs from 'node:fs';
import * as Cesium from 'cesium';
import { createIconSet } from '../../data/iconSet.js';
import { IconSetPrimitive } from './iconSetPrimitive.js';
@@ -58,3 +59,29 @@ test('by default the set draws an opaque pass and a translucent one, and draws n
assert.equal(translucent.renderState.depthMask, false);
assert.equal(primitive.drawsBlend('translucent'), false);
});
test('an over-depth row writes a depth of exactly 0, which a depth pick ignores', () => {
// Shaders do not compile under node: this reads the fragment shader's
// source. A depth past the near plane (as 1.0001 through
// czm_writeLogDepth was) is a surface to Cesium's depth pick, a near
// plane's distance from the camera, and the wheel stops zooming with an
// icon under the canvas centre (scripts/qa-zoom-under-icon.mjs).
const source = fs.readFileSync(
new URL('./iconSetPrimitive.js', import.meta.url),
'utf8',
);
const [vertex, fragment] = source
.slice(source.indexOf('const VERTEX_SHADER'))
.split('const FRAGMENT_SHADER')
.map((shader) => shader.replace(/\/\/.*$/gm, '')); // comments out
assert.match(
fragment,
/if \(v_overDepth > 0\.5\) gl_FragDepth = 0\.0;\s+else czm_writeLogDepth\(v_depthFromNearPlusOne\);/,
);
// The vertex shader flags the row and leaves its log depth alone.
assert.match(
vertex,
/gl_Position\.z = -gl_Position\.w;[^}]*v_overDepth = 1\.0;/,
);
assert.doesNotMatch(vertex, /v_depthFromNearPlusOne\s*=/);
});