fix(embed): an inline panel's timer frames move the camera, take input and run the clock again

When a host stops animation frames, the panel drew from a timer with the
viewer's render(): the camera's flight and input, the clock's tick, then a
draw if due. Through the frame port it called renderNow(), which on Cesium
only forced a draw, so flights stood still, drags and zooms did nothing
and the clock stopped. renderNow takes {ifDue: true}: one tick of the
loop as its own would run it, drawing only a frame that is due (the
widget's render() on Cesium; the stub's tick without a forced request).
This commit is contained in:
Sameh Khamis committed 2026-11-14 01:43:13 -08:00
1 parent f4beb676ae
commit 03a7d8827a
9 files changed
+86 -22

No files matched your search

+6 -3
View File
@@ -124,7 +124,9 @@ optional, so a renderer written before it still conforms:
- `RendererPlugin.applicationHooks(renderer)` hands the application what
only some renderers have (`ApplicationHooks`); see
[The application and its renderer](#the-application-and-its-renderer).
- `frame.renderNow()` throws when the frame fails to draw.
- `frame.renderNow()` throws when the frame fails to draw. With
`{ifDue: true}` it runs one tick of the loop now, as the loop's own would
(camera flight, input, clock), and draws only a frame that is due.
The Cesium port lists `gpuTiming` where its context has
`EXT_disjoint_timer_query_webgl2`: while anyone listens to frame signals,
@@ -525,8 +527,9 @@ on (no `renderer.id`, no engine type, no engine object's presence).
probe is `src/render/occlusion/depthProbe.js`, which Cesium's
`src/render/cesium/sceneOcclusionProbe.js` feeds; without it every such
vehicle's bracket shows); and an inline panel whose host stops animation
frames keeps drawing through `resize` and `frame.renderNow()`
(`src/app/panelRendering.js`), stopping at a frame that throws.
frames keeps running through `resize` and `frame.renderNow({ifDue: true})`
(`src/app/panelRendering.js`), so flights, input and the clock go on as
in the renderer's own loop, stopping at a frame that throws.
- **The map stacks** switch through the renderer's own map engine when its
plugin hands one, else through its globe port (`src/maps/globeEngine.js`);
see `docs/CURRENT-STATE.md` § Map source factories and coordination.
+4 -2
View File
@@ -25,7 +25,9 @@ function describeError(error) {
* Keep `renderer` drawing in an inline panel. Some hosts report a panel on
* screen as hidden, which stops the browser's animation frames and with them
* the renderer's own loop; while frames stop arriving, draw from a timer
* (`resize`, then `frame.renderNow()`). A frame that fails stops the timer,
* (`resize`, then a frame of the loop, `frame.renderNow({ifDue: true})`: the
* camera moves, input and the clock run, and it draws when due). A frame
* that fails stops the timer,
* its error reported in full. Returns a function that stops it.
* @param {import('../render/contract/renderer').Renderer} renderer
* @param {{windowRef?: Window, now?: () => number}} [options]
@@ -47,7 +49,7 @@ export function keepPanelRendering(
if (failed || now() - lastFrame < MISSED_FRAMES_MS) return;
try {
renderer.resize();
renderer.frame.renderNow();
renderer.frame.renderNow({ ifDue: true });
} catch (error) {
// Report the error in full: workers report plain objects, which
// would print as [object Object].
+7 -2
View File
@@ -19,7 +19,10 @@ test('a panel keeps drawing from a timer while animation frames stop', () => {
const drawn = [];
const renderer = {
resize: () => drawn.push('resize'),
frame: { renderNow: () => drawn.push('render') },
frame: {
renderNow: (options) =>
drawn.push(options?.ifDue ? 'loop frame' : 'forced frame'),
},
};
const stop = keepPanelRendering(renderer, {
windowRef: handles.windowRef,
@@ -33,7 +36,9 @@ test('a panel keeps drawing from a timer while animation frames stop', () => {
// Frames stop, as in a panel its host reports hidden: the timer draws.
clock = 400;
handles.tick();
assert.deepEqual(drawn, ['resize', 'render']);
// A frame of the loop, as the loop's own: the camera moves, input and
// the clock run, and it draws when due.
assert.deepEqual(drawn, ['resize', 'loop frame']);
stop();
assert.equal(handles.tick, null);
assert.equal(handles.frame, null);
+12 -8
View File
@@ -103,19 +103,23 @@ export function willDraw(scene, time) {
}
/**
* The contract's `renderNow` on `scene`: draw a frame at `time` even when
* nothing asked for one, and throw the error Cesium caught and raised on
* `renderError` when the frame failed.
* @param {object} scene
* @param {object} [time] A Cesium JulianDate.
* The contract's `renderNow` on `owner`'s scene: draw a frame at the
* clock's time even when nothing asked for one, or with `ifDue` run one
* frame of the widget's own loop (`render()`: the camera's flight and
* input, the clock's tick, then a draw if one is due); throw the error
* Cesium caught and raised on `renderError` when the frame failed.
* @param {object} owner A Cesium `Viewer` or `CesiumWidget`.
* @param {{ifDue?: boolean}} [options]
*/
export function renderNow(scene, time) {
export function renderNow(owner, { ifDue = false } = {}) {
const scene = owner.scene;
let failure = null;
const off = scene.renderError?.addEventListener((_scene, error) => {
failure ??= { error };
});
try {
scene.forceRender(time);
if (ifDue) owner.render();
else scene.forceRender(owner.clock?.currentTime);
} finally {
off?.();
}
@@ -259,7 +263,7 @@ export function createSceneFrame(viewer) {
viewer.useDefaultRenderLoop = suspended ? false : ownLoop;
if (!suspended && !gone()) scene.requestRender();
},
renderNow: () => renderNow(scene, viewer.clock?.currentTime),
renderNow: (options) => renderNow(viewer, options),
renderOnce({ timeoutMs } = {}) {
if (gone()) return Promise.resolve();
return new Promise((resolve, reject) => {
+31 -2
View File
@@ -202,8 +202,37 @@ test('renderNow throws the error Cesium raises on renderError', () => {
if (fail) for (const cb of listeners) cb(scene, failure);
},
};
renderNow(scene);
const owner = { scene, clock: { currentTime: 'now' } };
renderNow(owner);
fail = true;
assert.throws(() => renderNow(scene), failure);
assert.throws(() => renderNow(owner), failure);
assert.equal(listeners.size, 0, 'it stops listening either way');
});
test('renderNow ifDue runs a frame of the widget’s own loop, as its render() does', () => {
const listeners = new Set();
const failure = new Error('worker failed');
const calls = [];
let fail = false;
const scene = {
renderError: {
addEventListener: (cb) => (listeners.add(cb), () => listeners.delete(cb)),
},
forceRender: () => calls.push('forceRender'),
};
// The widget's render(): the camera's flight and input, the clock's
// tick, then a draw if one is due.
const owner = {
scene,
clock: { currentTime: 'now' },
render() {
calls.push('render');
if (fail) for (const cb of listeners) cb(scene, failure);
},
};
renderNow(owner, { ifDue: true });
assert.deepEqual(calls, ['render']);
fail = true;
assert.throws(() => renderNow(owner, { ifDue: true }), failure);
assert.equal(listeners.size, 0);
});
+1 -1
View File
@@ -348,7 +348,7 @@ export function createCesiumPorts(
if (!suspended) scene.requestRender();
},
// Draws even when nothing asked for a frame; throws when it fails.
renderNow: () => renderNow(scene, widget.clock.currentTime),
renderNow: (options) => renderNow(widget, options),
renderOnce: (options) => nextPostRender(options),
setTargetFps(fps) {
targetFps = fps > 0 ? fps : 0;
+16
View File
@@ -705,6 +705,22 @@ export function portChecks() {
equal(drawnFrames, before + 1, 'renderNow drew synchronously');
},
),
check(
'frame.renderNow.ifDue',
'renderNow({ifDue}) ticks the loop now and draws a frame that is due',
async (h, r) => {
let ticks = 0;
let drawnFrames = 0;
r.frame.on('preUpdate', () => (ticks += 1));
r.frame.on('postRender', () => (drawnFrames += 1));
await h.frame(r);
const [ticked, drawn] = [ticks, drawnFrames];
r.frame.requestRender('conformance');
r.frame.renderNow({ ifDue: true });
equal(ticks, ticked + 1, 'one tick, synchronously');
equal(drawnFrames, drawn + 1, 'the asked-for frame drawn');
},
),
check('frame.suspend', 'a suspended loop does not tick', async (h, r) => {
let ticks = 0;
r.frame.on('preUpdate', () => (ticks += 1));
+7 -2
View File
@@ -72,8 +72,13 @@ export interface FramePort {
diagnostics(): FrameDiagnostics;
/** Stop ticking while the page is hidden; resume on `false`. */
suspend(hidden: boolean): void;
/** Draw a frame now, synchronously; throws when the frame fails to draw. */
renderNow(): void;
/**
* Draw a frame now, synchronously; throws when the frame fails to draw.
* `ifDue`: run one tick of the loop now as its own would (camera flight,
* input, clock), drawing only if a frame is due, for a host that stops
* the animation frames the loop runs on.
*/
renderNow(options?: { ifDue?: boolean }): void;
/** Resolves after the next frame has been drawn and presented. */
renderOnce(options?: { timeoutMs?: number }): Promise<void>;
/** Cap the loop's rate; 0 is the display's rate. */
+2 -2
View File
@@ -346,8 +346,8 @@ export function createStubRenderer(options = {}) {
suspend(hidden) {
suspended = Boolean(hidden);
},
renderNow() {
requestRender('renderNow');
renderNow({ ifDue = false } = {}) {
if (!ifDue) requestRender('renderNow');
tick();
},
renderOnce({ timeoutMs } = {}) {