From 03a7d8827ac3aa31c52024a32dff684303742c82 Mon Sep 17 00:00:00 2001 From: Sameh Khamis Date: Sat, 14 Nov 2026 01:43:13 -0800 Subject: [PATCH] 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). --- docs/RENDERER-CONTRACT.md | 9 ++++--- src/app/panelRendering.js | 6 +++-- src/app/panelRendering.test.mjs | 9 +++++-- src/render/cesium/frame.js | 20 +++++++++------- src/render/cesium/frame.test.mjs | 33 ++++++++++++++++++++++++-- src/render/cesium/ports.js | 2 +- src/render/conformance/checks/ports.js | 16 +++++++++++++ src/render/contract/frame.d.ts | 9 +++++-- src/render/stub/index.js | 4 ++-- 9 files changed, 86 insertions(+), 22 deletions(-) diff --git a/docs/RENDERER-CONTRACT.md b/docs/RENDERER-CONTRACT.md index 227473ecc..b3538d2a1 100644 --- a/docs/RENDERER-CONTRACT.md +++ b/docs/RENDERER-CONTRACT.md @@ -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. diff --git a/src/app/panelRendering.js b/src/app/panelRendering.js index 66b3305ea..18a342fd3 100644 --- a/src/app/panelRendering.js +++ b/src/app/panelRendering.js @@ -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]. diff --git a/src/app/panelRendering.test.mjs b/src/app/panelRendering.test.mjs index bab5b5a1e..7d504d011 100644 --- a/src/app/panelRendering.test.mjs +++ b/src/app/panelRendering.test.mjs @@ -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); diff --git a/src/render/cesium/frame.js b/src/render/cesium/frame.js index 91340b1be..510b20596 100644 --- a/src/render/cesium/frame.js +++ b/src/render/cesium/frame.js @@ -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) => { diff --git a/src/render/cesium/frame.test.mjs b/src/render/cesium/frame.test.mjs index f191512ca..e8b69447a 100644 --- a/src/render/cesium/frame.test.mjs +++ b/src/render/cesium/frame.test.mjs @@ -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); +}); diff --git a/src/render/cesium/ports.js b/src/render/cesium/ports.js index 3d448a357..0dff25cf6 100644 --- a/src/render/cesium/ports.js +++ b/src/render/cesium/ports.js @@ -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; diff --git a/src/render/conformance/checks/ports.js b/src/render/conformance/checks/ports.js index 0ada84320..b0ef99b5f 100644 --- a/src/render/conformance/checks/ports.js +++ b/src/render/conformance/checks/ports.js @@ -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)); diff --git a/src/render/contract/frame.d.ts b/src/render/contract/frame.d.ts index 77b038a1d..d24b1b112 100644 --- a/src/render/contract/frame.d.ts +++ b/src/render/contract/frame.d.ts @@ -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; /** Cap the loop's rate; 0 is the display's rate. */ diff --git a/src/render/stub/index.js b/src/render/stub/index.js index 9d89df2a4..eee2d54d0 100644 --- a/src/render/stub/index.js +++ b/src/render/stub/index.js @@ -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 } = {}) {