diff --git a/changelog.d/1806-renderer-engine-hook.md b/changelog.d/1806-renderer-engine-hook.md new file mode 100644 index 0000000000..4ef5551801 --- /dev/null +++ b/changelog.d/1806-renderer-engine-hook.md @@ -0,0 +1,3 @@ +- Renderer plugins can hand the application their own engine (`ApplicationHooks.engine`, + Cesium's is `{kind: 'cesium', viewer}`) for drawing beside the contract + (samehkhamis, #1806). diff --git a/docs/RENDERER-CONTRACT.md b/docs/RENDERER-CONTRACT.md index f07abae89f..b216b7236e 100644 --- a/docs/RENDERER-CONTRACT.md +++ b/docs/RENDERER-CONTRACT.md @@ -614,7 +614,10 @@ on (no `renderer.id`, no engine type, no engine object's presence). (`ownCreditDisplay`; otherwise the application's own line, `src/ui/creditsView.js`, shows the credits port's list), and what QA scripts read from `window.__godsEyeView` (Cesium's viewer there, for the - scripts that drive it). Each is optional, none is a contract member, and + scripts that drive it), and its own engine (`engine`, whose `kind` names + it: Cesium's is `{kind: 'cesium', viewer}`) for an application that draws + with that engine directly beside the contract, only with engines whose + kind it knows, adding, updating and removing what it draws. Each is optional, none is a contract member, and a renderer without them runs the application without that behaviour. - **What the renderer should do is in the ports**, each through the application's own code: outward zooms stop at a whole-Earth view that diff --git a/src/render/applicationHooks.js b/src/render/applicationHooks.js index c989d4801f..450b47eddd 100644 --- a/src/render/applicationHooks.js +++ b/src/render/applicationHooks.js @@ -14,6 +14,11 @@ * - `viewerDrawsEntity(entity)`: whether an entity is one the renderer draws * itself (Cockpit asks whether the aircraft it flies still draws). * - `qaHandles`: values QA scripts read from `window.__godsEyeView`. + * - `engine`: the renderer's own engine, for an application that draws with + * it directly beside the contract: `kind` names it (`'cesium'`, with + * `viewer`, Cesium's `Viewer`). An application draws only with engines + * whose kind it knows; what it draws there is its own to add, update and + * remove. * - `ownCreditDisplay`: true when the renderer shows its credits in a * display of its own; otherwise the application shows what its credits * port lists (`src/ui/creditsView.js`). diff --git a/src/render/cesium/appRenderer.js b/src/render/cesium/appRenderer.js index a3a51375d7..6e649d8345 100644 --- a/src/render/cesium/appRenderer.js +++ b/src/render/cesium/appRenderer.js @@ -218,6 +218,8 @@ export function createCesiumRendererPlugin({ // Whether an entity is one of the viewer's own (Cockpit asks whether // the aircraft it flies still draws). viewerDrawsEntity: (entity) => viewer.entities.contains(entity), + // An application drawing with Cesium itself beside the contract. + engine: Object.freeze({ kind: 'cesium', viewer }), // QA scripts drive and read the viewer itself. qaHandles: { viewer, diff --git a/src/render/cesium/appRenderer.test.mjs b/src/render/cesium/appRenderer.test.mjs index dccc1ff3e7..a9c16aff37 100644 --- a/src/render/cesium/appRenderer.test.mjs +++ b/src/render/cesium/appRenderer.test.mjs @@ -156,6 +156,8 @@ test('the plugin wraps the viewer it is given, behind the accessor only', async ); assert.equal(hooks.ownCreditDisplay, true, 'Cesium shows its own credits'); assert.equal(hooks.qaHandles.viewer, viewer, 'QA scripts read the viewer'); + assert.equal(hooks.engine.kind, 'cesium', 'the engine says what it is'); + assert.equal(hooks.engine.viewer, viewer, 'an application may draw with it'); assert.equal(hooks.viewerDrawsEntity({ own: true }), true); assert.equal(hooks.viewerDrawsEntity({}), false); assert.equal(typeof hooks.trimStaleCommands, 'function'); diff --git a/src/render/contract/renderer.d.ts b/src/render/contract/renderer.d.ts index 5d8da3c440..522228f386 100644 --- a/src/render/contract/renderer.d.ts +++ b/src/render/contract/renderer.d.ts @@ -58,6 +58,14 @@ export interface ApplicationHooks { viewerDrawsEntity?(entity: unknown): boolean; /** Values QA scripts read from the page's debug handle. */ qaHandles?: Readonly>; + /** + * The renderer's own engine, for an application that draws with it + * directly beside the contract: `kind` names the engine (`'cesium'` for + * Cesium, whose `Cesium.Viewer` is `viewer`) and the rest is that engine's + * own. An application draws only with engines whose kind it knows, and + * whatever it draws there is its own to add, update and remove. + */ + engine?: Readonly<{ kind: string; [key: string]: unknown }>; /** * Show a recoverable notice when the renderer stops drawing (an error, a * lost context), with Retry and, if `allowReload`, Reset, by publishing it