Merge main (663b56f62, #1755) into the renderer branch

This commit is contained in:
Sameh Khamis committed 2026-11-15 16:34:05 -08:00
commit a0d299523d
91 files changed
+1793 -396

No files matched your search

+3
View File
@@ -29,6 +29,7 @@ import { bindRenderer } from '../rendererOf.js';
import { FREE_LOOK_MAX_HEIGHT_METERS } from '../../globeInView.js';
import { createCesiumInput } from './input.js';
import { cesiumCapabilities, createCesiumPorts } from './ports.js';
import { IDLE_FRAME_RATE } from '../../renderGovernor.js';
import { cesiumMapEngine } from './mapEngine.js';
import { installFreeLookHeightLimit } from './freeLookLimit.js';
import { trimStaleSceneCommands } from './sceneCommandRelease.js';
@@ -112,6 +113,8 @@ export function createCesiumRendererPlugin({
capabilities = new ReadonlySet(cesiumCapabilities(viewer.scene));
ports = createCesiumPorts(viewer, {
capabilities,
// Ticking at the display's rate only while anything moves.
idleFps: IDLE_FRAME_RATE,
credentials: { googleApiKey, googleTokens, worldDataToken },
...(cameraController ? { cameraController } : {}),
});
+25
View File
@@ -3,6 +3,7 @@ import test from 'node:test';
import * as Cesium from 'cesium';
import { CONTRACT_VERSION, checkRendererShape } from '../contract/index.js';
import { rendererOf } from '../rendererOf.js';
import { IDLE_FRAME_RATE } from '../../renderGovernor.js';
import { cesiumMapEngine } from './mapEngine.js';
import {
ReadonlySet,
@@ -168,6 +169,30 @@ test('the plugin wraps the viewer it is given, behind the accessor only', async
assert.deepEqual(log, ['resize', 'destroy'], 'destroying twice is safe');
});
test('the application’s loop ticks at the idle rate while nothing moves, and at the display’s while anything does', async (t) => {
withDocument(t, fakeDocument());
let viewer;
const plugin = createCesiumRendererPlugin({
createViewer() {
viewer = fakeViewer([]);
// The viewer starts at the idle rate (createApplicationViewer).
viewer.targetFrameRate = IDLE_FRAME_RATE;
return viewer;
},
});
const renderer = await plugin.create({
container: {},
signal: new AbortController().signal,
});
assert.equal(viewer.targetFrameRate, IDLE_FRAME_RATE);
assert.equal(renderer.frame.diagnostics().targetFps, 0, 'no cap');
const release = renderer.frame.holdContinuous('flights');
assert.equal(viewer.targetFrameRate, undefined);
release();
assert.equal(viewer.targetFrameRate, IDLE_FRAME_RATE);
renderer.destroy();
});
test('work pending at destroy settles and lets go of the scene', async (t) => {
withDocument(t, fakeDocument());
const viewers = [];
+4 -1
View File
@@ -1,5 +1,6 @@
import * as Cesium from 'cesium';
import { applyModelAtmosphereWorkaround } from '../../app/atmosphereCompat.js';
import { IDLE_FRAME_RATE } from '../../renderGovernor.js';
import { preloadImageryAhead } from './imageryLookAhead.js';
import { StarrySky } from './starrySky.js';
@@ -95,7 +96,9 @@ export function createApplicationViewer({
applicationViewerOptions(creditContainer, { showRenderLoopErrors }),
);
try {
viewer.targetFrameRate = 60;
// Until the frame port takes over (appRenderer.js), tick at the idle
// rate so the startup load does not compete with drawing at 240 fps.
viewer.targetFrameRate = IDLE_FRAME_RATE;
// No double-click follow or zoom: the Viewer's own (it tracked or
// zoomed to the entity picked) is off. Following is a layer's click.
viewer.screenSpaceEventHandler.removeInputAction(
+3 -2
View File
@@ -2365,8 +2365,9 @@ test('the GNSS layer draws its cells as ground fills that stay out of the pick p
assert.equal(fill.allowPicking, false);
assert.equal(fill.classificationType, Cesium.ClassificationType.BOTH);
const [instance] = fill.geometryInstances;
assert.ok(instance.geometry instanceof Cesium.RectangleGeometry);
assert.equal(instance.id.id, 'gnss-integrity:280:420');
// An H3 hexagon, drawn as a polygon.
assert.ok(instance.geometry instanceof Cesium.PolygonGeometry);
assert.equal(instance.id.id, 'gnss-integrity:841e631ffffffff');
// A ground primitive draws its stencil in the pick pass even unpickable,
// erasing picks of ground geometry under it; these skip that pass.
let updates = 0;
+10 -7
View File
@@ -16,6 +16,7 @@
* so an autodetect `viewFrom` is renderer-specific.
*/
import * as Cesium from 'cesium';
import { createFrameWait } from '../../time/frameWait.js';
import { toCartesian } from './common.js';
import { trackedEntityViewEntity } from './internals.js';
import {
@@ -24,7 +25,8 @@ import {
} from '../camera/followTransition.js';
/** Frames to wait for a target's first position before giving up framing. */
const MAX_FRAME_ATTEMPTS = 120;
/** Drawn time (ms) to wait for the followed target's first position. */
const MAX_POSITION_WAIT_MS = 2_000;
const TRANSPARENT = new Cesium.Color(0, 0, 0, 0);
const ZOOM_STATES = new WeakMap();
/** Each helper entity's FollowTarget. */
@@ -220,7 +222,8 @@ export function createCesiumFollow({
target.position(msOf(time));
/** @type {null | {target: object, helper: object, framed: boolean,
* attempts: number, previous: Cesium.Cartesian3, releaseZoom: () => void}} */
* positionWait: {tick: () => boolean}, previous: Cesium.Cartesian3,
* releaseZoom: () => void}} */
let current = null;
let removePreUpdate = null;
/** What `followChanged` last announced: it fires only when that changes. */
@@ -312,7 +315,6 @@ export function createCesiumFollow({
*/
function frame(entry) {
const { target } = entry;
entry.attempts += 1;
const time = widget.clock.currentTime;
const at = positionOf(target, time);
if (target.frame !== 'enu') {
@@ -373,11 +375,12 @@ export function createCesiumFollow({
}
/**
* With no position to frame for MAX_FRAME_ATTEMPTS frames, the follow
* leaves the camera to Cesium: no framing, no zoom hold, no clamp.
* With no position to frame for MAX_POSITION_WAIT_MS of drawn frames (the
* same at any refresh rate), the follow leaves the camera to Cesium: no
* framing, no zoom hold, no clamp.
*/
function giveUpAfterWaiting(entry) {
if (entry.attempts >= MAX_FRAME_ATTEMPTS) giveUp(entry);
if (entry.positionWait.tick()) giveUp(entry);
}
function giveUp(entry) {
entry.gaveUp = true;
@@ -399,7 +402,7 @@ export function createCesiumFollow({
helper: helperFor(target),
framed: false,
gaveUp: false,
attempts: 0,
positionWait: createFrameWait(MAX_POSITION_WAIT_MS, now),
previous: new Cesium.Cartesian3(),
releaseZoom: () => {},
};
+21 -4
View File
@@ -11,7 +11,7 @@ import { headlessCamera } from './cameraGoldens.js';
import { createCesiumCamera } from './camera.js';
import { holdFollowZoom, pickThroughFollowHelper } from './follow.js';
function trackingHost() {
function trackingHost({ now } = {}) {
const { scene, camera } = headlessCamera();
for (const name of ['preUpdate', 'postUpdate', 'preRender', 'postRender'])
scene[name] = new Cesium.Event();
@@ -52,6 +52,7 @@ function trackingHost() {
report: (error) => {
throw error;
},
...(now ? { now } : {}),
});
return { widget, scene, camera, port: part.port, dispose: part.dispose };
}
@@ -207,12 +208,28 @@ test('targets are asked for their position at sub-millisecond scene time', () =>
h.dispose();
});
test('a target without a position gives up framing after 120 frames', () => {
const h = trackingHost();
test('a target without a position gives up framing after two seconds of drawn frames', () => {
let at = 0;
const h = trackingHost({ now: () => at });
const controller = h.scene.screenSpaceCameraController;
h.port.follow(target('a', { position: () => null, minRange: 150 }));
for (let i = 0; i < 119; i++) h.scene.preUpdate.raiseEvent(h.scene);
// 240 frames a second: a second of them is 240 frames, past the 120 a
// fixed frame count would wait, and not yet the wait.
for (let i = 0; i < 240; i++) {
h.scene.preUpdate.raiseEvent(h.scene);
at += 1000 / 240;
}
assert.equal(controller.inertiaZoom, 0, 'still waiting');
// A parked scene's gap counts at most one step, so it does not end it.
at += 60_000;
h.scene.preUpdate.raiseEvent(h.scene);
assert.equal(controller.inertiaZoom, 0, 'still waiting after a gap');
for (let i = 0; i < 200; i++) {
at += 1000 / 240;
h.scene.preUpdate.raiseEvent(h.scene);
}
assert.equal(controller.inertiaZoom, 0, 'still waiting');
at += 100;
h.scene.preUpdate.raiseEvent(h.scene);
assert.equal(h.port.followFramed, false);
assert.equal(controller.inertiaZoom, 0.8, 'the zoom hold let go');
+20 -3
View File
@@ -111,11 +111,17 @@ export function cesiumCapabilities(scene, only) {
/**
* @param {object} widget A Cesium `CesiumWidget` or `Viewer`.
* @param {{capabilities: ReadonlySet<string>, credentials?: object,
* cameraController?: Function, now?: () => number}} options
* cameraController?: Function, now?: () => number,
* idleFps?: number}} options
* The renderer's capabilities, which gate the members that need them, and
* the credentials its globe loads photoreal tiles and world data with
* (`googleApiKey`, `googleTokens`, `worldDataToken`). `now` is the clock
* each tick reads (`performance.now` by default; a test's virtual one).
* With `idleFps`, the loop ticks at most that often while no hold is out
* (Cesium ticks its clock and every update listener each animation frame
* even when it draws nothing), and at the display's rate while one is;
* `setTargetFps` then caps both, and the loop starts with no cap of its
* own. Without it, the widget's own rate is the cap.
* With
* `cameraController`, the camera port is that controller's over Cesium's
* camera (`controlledCamera.js`); the ports then have `attachInput` and
@@ -128,6 +134,7 @@ export function createCesiumPorts(
credentials = {},
cameraController,
now: clockNow = () => performance.now(),
idleFps = 0,
},
) {
const scene = widget.scene;
@@ -262,15 +269,25 @@ export function createCesiumPorts(
const holds = new Map();
function applyHolds() {
const continuous = holds.size > 0;
if (idleFps > 0) applyRate();
if (scene.requestRenderMode === !continuous) return;
scene.requestRenderMode = !continuous;
}
/** The loop's rate: the cap, and at most `idleFps` while nothing holds. */
function applyRate() {
const idle = holds.size === 0 && idleFps > 0;
const rate =
idle && !(targetFps > 0 && targetFps < idleFps) ? idleFps : targetFps;
widget.targetFrameRate = rate || undefined;
}
// On demand means drawn when asked, held or the view changed: never
// because scene time moved on by itself. With no holds yet, it starts so.
scene.maximumRenderTimeChange = Infinity;
scene.requestRenderMode = true;
let suspended = false;
let targetFps = widget.targetFrameRate > 0 ? widget.targetFrameRate : 0;
let targetFps =
idleFps <= 0 && widget.targetFrameRate > 0 ? widget.targetFrameRate : 0;
if (idleFps > 0) applyRate();
// Pending one-shot renders; disposal settles them rather than leave them
// attached to a scene that will not render again.
@@ -352,7 +369,7 @@ export function createCesiumPorts(
renderOnce: (options) => nextPostRender(options),
setTargetFps(fps) {
targetFps = fps > 0 ? fps : 0;
widget.targetFrameRate = targetFps || undefined;
applyRate();
},
/**
* Moves the clock to `ms` and draws it; in `preUpdate`, the frame under
+23
View File
@@ -507,6 +507,29 @@ test('suspend stops the loop at once and resumes it; target fps caps it', () =>
ports.dispose();
});
test('with an idle rate, idle ticks at it and anything held draws at the display rate', () => {
const { widget } = tickingWidget();
widget.targetFrameRate = 60;
const ports = createCesiumPorts(widget, { capabilities: all, idleFps: 60 });
assert.equal(widget.targetFrameRate, 60, 'idle: the idle rate');
assert.equal(ports.frame.diagnostics().targetFps, 0, 'no cap of its own');
const release = ports.frame.holdContinuous('flights');
assert.equal(widget.targetFrameRate, undefined, 'held: the display rate');
release();
assert.equal(widget.targetFrameRate, 60);
// A cap holds while held, and idle ticks at the lower of the two.
ports.frame.setTargetFps(30);
assert.equal(widget.targetFrameRate, 30);
const again = ports.frame.holdContinuous('flights');
assert.equal(widget.targetFrameRate, 30);
ports.frame.setTargetFps(120);
assert.equal(widget.targetFrameRate, 120);
again();
assert.equal(widget.targetFrameRate, 60);
assert.equal(ports.frame.diagnostics().targetFps, 120);
ports.dispose();
});
test('rendering holds the tick’s answer once the tick is over', () => {
const { widget, scene, raise } = tickingWidget();
const ports = createCesiumPorts(widget, { capabilities: all });