mirror of
https://github.com/bilawalsidhu/gods-eye-view.git
synced 2026-11-17 08:42:21 +00:00
484 lines
18 KiB
JavaScript
484 lines
18 KiB
JavaScript
/**
|
|
* @module render/rendererOf
|
|
* @description The renderer that draws a scene, found from the scene object
|
|
* the code already holds. It bridges the migration: code that still holds
|
|
* the scene reaches the renderer's ports through it, and the lookup goes
|
|
* once that code is handed the renderer itself.
|
|
*/
|
|
|
|
const renderers = new WeakMap();
|
|
|
|
/**
|
|
* Ports built for scene objects no renderer is bound to (a Cesium viewer
|
|
* made directly, say), per port: each `{port, dispose}` kept for as long
|
|
* as its scene object lives, or until a renderer is bound to it. The
|
|
* renderer adapter provides the factory each is built with as it loads.
|
|
*/
|
|
function unboundPorts(member) {
|
|
const built = new WeakMap();
|
|
/** Ports superseded while their holder still used them (`keep`). */
|
|
const keptPorts = new WeakMap();
|
|
let build = null;
|
|
return {
|
|
provide(factory) {
|
|
build = factory;
|
|
},
|
|
drop(host, port) {
|
|
const entry = built.get(host);
|
|
if (!entry || (port !== undefined && entry.port !== port)) {
|
|
// A port a renderer superseded but its holder kept: its holder's to
|
|
// let go of.
|
|
const kept = port !== undefined && keptPorts.get(port);
|
|
if (kept) {
|
|
keptPorts.delete(port);
|
|
kept.dispose();
|
|
}
|
|
return;
|
|
}
|
|
built.delete(host);
|
|
entry.dispose();
|
|
},
|
|
/**
|
|
* A renderer bound to `host` supersedes its built port: kept working
|
|
* for whoever holds it when it says so (`keep`, an input port a
|
|
* dispatcher listens on, let go of through `drop(host, port)`), else
|
|
* released when it can be (it stops working for new callers but keeps
|
|
* what it did), else disposed.
|
|
*/
|
|
supersede(host) {
|
|
const entry = built.get(host);
|
|
if (!entry) return;
|
|
built.delete(host);
|
|
if (entry.keep) keptPorts.set(entry.port, entry);
|
|
else if (entry.release) entry.release();
|
|
else entry.dispose();
|
|
},
|
|
/** `options` reach `build` only when it is the call that builds. */
|
|
find(host, options) {
|
|
const port = rendererOf(host)?.[member];
|
|
if (port) return port;
|
|
if (!host || typeof host !== 'object') return null;
|
|
if (host.isDestroyed?.()) {
|
|
// Gone with its scene: let the built port go with it.
|
|
this.drop(host);
|
|
return null;
|
|
}
|
|
let entry = built.get(host);
|
|
if (!entry && build) {
|
|
entry = build(host, options);
|
|
if (entry) built.set(host, entry);
|
|
}
|
|
return entry?.port ?? null;
|
|
},
|
|
};
|
|
}
|
|
|
|
const unboundCameras = unboundPorts('camera');
|
|
const unboundEffects = unboundPorts('effects');
|
|
const unboundGlobes = unboundPorts('globe');
|
|
/** Credits ports are `{port, dispose, release}`: see `bindRenderer`. */
|
|
const unboundCredits = unboundPorts('credits');
|
|
/** Draw ports are `{port, dispose, release}`, as credits ports are. */
|
|
const unboundDraws = unboundPorts('draw');
|
|
const unboundQueries = unboundPorts('query');
|
|
const unboundFrames = unboundPorts('frame');
|
|
const unboundInputs = unboundPorts('input');
|
|
|
|
/** What a click's raw engine picks are built with (`provideNativeClick`). */
|
|
let nativeClicks = null;
|
|
|
|
/**
|
|
* Provide the factory `cameraOf` builds a camera port with for a scene
|
|
* object no renderer is bound to. The renderer adapter provides it as it
|
|
* loads; a later call replaces it.
|
|
* @param {(host: object) => ({port: object, dispose: () => void} | null)} build
|
|
*/
|
|
export function provideUnboundCamera(build) {
|
|
unboundCameras.provide(build);
|
|
}
|
|
|
|
/**
|
|
* Provide the factory `findCredits` builds a credits port with for a scene
|
|
* object no renderer is bound to, as `provideUnboundCamera` does. `release`
|
|
* detaches a port a bound renderer supersedes, keeping its credits shown.
|
|
* @param {(host: object) => ({port: object, dispose: () => void,
|
|
* release: () => void} | null)} build
|
|
*/
|
|
export function provideUnboundCredits(build) {
|
|
unboundCredits.provide(build);
|
|
}
|
|
|
|
/**
|
|
* Provide the factory `findDraw` builds a draw port with for a scene object
|
|
* no renderer is bound to, as `provideUnboundCredits` does: a bound
|
|
* renderer releases it, and the sets made through it keep drawing until
|
|
* their owners dispose them.
|
|
* @param {(host: object) => ({port: object, dispose: () => void,
|
|
* release: () => void} | null)} build
|
|
*/
|
|
export function provideUnboundDraw(build) {
|
|
unboundDraws.provide(build);
|
|
}
|
|
|
|
/**
|
|
* Provide the factory `findQuery` builds a query port with for a scene
|
|
* object no renderer is bound to, as `provideUnboundCamera` does. It answers
|
|
* over the sets drawn through `findDraw` on the same scene object.
|
|
* @param {(host: object) => ({port: object, dispose: () => void} | null)} build
|
|
*/
|
|
export function provideUnboundQuery(build) {
|
|
unboundQueries.provide(build);
|
|
}
|
|
|
|
/**
|
|
* Provide the factory `findFrame` builds a frame port with for a scene
|
|
* object no renderer is bound to, as `provideUnboundCamera` does.
|
|
* @param {(host: object) => ({port: object, dispose: () => void} | null)} build
|
|
*/
|
|
export function provideUnboundFrame(build) {
|
|
unboundFrames.provide(build);
|
|
}
|
|
|
|
/**
|
|
* Provide the factory `findInput` builds an input port with for a scene
|
|
* object no renderer is bound to, as `provideUnboundCamera` does. It is
|
|
* given the `options` of the `findInput` call that builds, for test
|
|
* doubles. A renderer bound later does not take the port from whoever
|
|
* listens on it: it works until `releaseUnboundInput`.
|
|
* @param {(host: object, options?: object) => ({port: object, dispose: () => void, keep?: boolean} | null)} build
|
|
*/
|
|
export function provideUnboundInput(build) {
|
|
unboundInputs.provide(build);
|
|
}
|
|
|
|
/**
|
|
* Provide what `nativeClickOf` builds a click's raw engine picks with. Not
|
|
* part of the renderer contract: the renderer adapter provides it as it
|
|
* loads, for what the app still draws outside the draw port and for code that
|
|
* still reads the engine's own pick objects; a later call replaces it.
|
|
* @param {(host: object, position: {x: number, y: number}) => (NativeClick | null)} build
|
|
*/
|
|
export function provideNativeClick(build) {
|
|
nativeClicks = build;
|
|
}
|
|
|
|
/**
|
|
* Provide the factory `findEffects` builds an effects port with for a
|
|
* scene object no renderer is bound to, as `provideUnboundCamera` does.
|
|
* @param {(host: object) => ({port: object, dispose: () => void} | null)} build
|
|
*/
|
|
export function provideUnboundEffects(build) {
|
|
unboundEffects.provide(build);
|
|
}
|
|
|
|
/**
|
|
* Provide the factory `findGlobe` builds a globe port with for a scene
|
|
* object no renderer is bound to, as `provideUnboundCamera` does. A bound
|
|
* renderer supersedes it with `release`, as credits are.
|
|
* @param {(host: object) => ({port: object, dispose: () => void,
|
|
* release?: () => void} | null)} build
|
|
*/
|
|
export function provideUnboundGlobe(build) {
|
|
unboundGlobes.provide(build);
|
|
}
|
|
|
|
/**
|
|
* Let go of `port`, if it is the effects port `findEffects` built for
|
|
* `host`: its passes go and the scene's own settings come back. A
|
|
* renderer's own port, or one built later, is left alone.
|
|
* @param {object|null|undefined} host
|
|
* @param {object|null|undefined} port
|
|
*/
|
|
export function releaseUnboundEffects(host, port) {
|
|
if (host && typeof host === 'object' && port) unboundEffects.drop(host, port);
|
|
}
|
|
|
|
/**
|
|
* Bind a renderer to its scene object. A port `cameraOf` or `findEffects`
|
|
* built for it while it had no renderer is disposed: its listeners hear
|
|
* nothing more, and they answer with the renderer's ports from then on.
|
|
* A credits port `findCredits` built is released, not disposed: the
|
|
* credits added through it stay shown until their own Off. A globe port
|
|
* `findGlobe` built is released too: its imagery stays drawn, following the
|
|
* base, until its callers remove it. So is a draw port `findDraw` built: its
|
|
* sets keep drawing until disposed.
|
|
* @param {object} host The scene object callers hold.
|
|
* @param {object} renderer
|
|
* @returns {() => void} Unbinds, if the binding is still this one.
|
|
*/
|
|
export function bindRenderer(host, renderer) {
|
|
if (renderers.has(host)) throw new Error('This scene already has a renderer');
|
|
// The renderer's ports supersede ones built while there was none.
|
|
unboundCameras.drop(host);
|
|
unboundEffects.drop(host);
|
|
unboundGlobes.supersede(host);
|
|
unboundCredits.supersede(host);
|
|
unboundDraws.supersede(host);
|
|
unboundQueries.drop(host);
|
|
unboundFrames.drop(host);
|
|
unboundInputs.supersede(host);
|
|
renderers.set(host, renderer);
|
|
return () => {
|
|
if (renderers.get(host) === renderer) renderers.delete(host);
|
|
};
|
|
}
|
|
|
|
/**
|
|
* The scene object the application holds for `renderer`: what every layer
|
|
* and tool is handed, and reaches the renderer's ports through. It is the
|
|
* application's own: the element the renderer
|
|
* fills (`container`) and whether the scene is gone (`isDestroyed()`), and
|
|
* nothing of the engine.
|
|
* @param {object} renderer
|
|
* @param {{container: HTMLElement}} options
|
|
* @returns {{host: Readonly<{container: HTMLElement, isDestroyed: () => boolean}>,
|
|
* release: () => void}} `release` marks the scene gone and unbinds it.
|
|
*/
|
|
export function createSceneHost(renderer, { container }) {
|
|
let destroyed = false;
|
|
const host = Object.freeze({ container, isDestroyed: () => destroyed });
|
|
const unbind = bindRenderer(host, renderer);
|
|
return {
|
|
host,
|
|
release() {
|
|
destroyed = true;
|
|
unbind();
|
|
},
|
|
};
|
|
}
|
|
|
|
/**
|
|
* @param {object|null|undefined} host
|
|
* @returns {object|null} The renderer bound to `host`, or null.
|
|
*/
|
|
export const rendererOf = (host) => (host && renderers.get(host)) || null;
|
|
|
|
/**
|
|
* The canvas the renderer bound to `host` draws in; with none bound, the
|
|
* scene object's own `canvas` (a viewer's), the same element the default
|
|
* renderer reports. For sizing by it and listening on it as DOM.
|
|
* @param {object|null|undefined} host
|
|
* @returns {HTMLCanvasElement|null}
|
|
*/
|
|
export const canvasOf = (host) =>
|
|
rendererOf(host)?.canvas ?? host?.canvas ?? null;
|
|
|
|
/**
|
|
* The camera port of the renderer bound to `host`; with no renderer bound,
|
|
* one built over `host` by the provided factory and kept with it while
|
|
* `host` lives.
|
|
* @param {object|null|undefined} host
|
|
* @returns {import('./contract/camera').CameraPort | null} Null when `host`
|
|
* has no renderer and no camera can be built for it, or is destroyed.
|
|
*/
|
|
export function findCamera(host) {
|
|
return unboundCameras.find(host);
|
|
}
|
|
|
|
/**
|
|
* The effects port of the renderer bound to `host`; with no renderer bound,
|
|
* one built over `host` by the provided factory and kept with it while
|
|
* `host` lives.
|
|
* @param {object|null|undefined} host
|
|
* @returns {import('./contract/effects').EffectsPort | null} Null when
|
|
* `host` has no renderer and no effects can be built for it, or is
|
|
* destroyed.
|
|
*/
|
|
export function findEffects(host) {
|
|
return unboundEffects.find(host);
|
|
}
|
|
|
|
/**
|
|
* The globe port of the renderer bound to `host`; with no renderer bound,
|
|
* one built over `host` by the provided factory and kept with it while
|
|
* `host` lives, as `findCamera` does. Imagery added through a built port
|
|
* stays drawn once a renderer is bound; the renderer's port lists only
|
|
* its own.
|
|
* @param {object|null|undefined} host
|
|
* @returns {import('./contract/globe').GlobePort | null}
|
|
*/
|
|
export function findGlobe(host) {
|
|
return unboundGlobes.find(host);
|
|
}
|
|
|
|
/**
|
|
* The credits port of the renderer bound to `host`; with no renderer bound,
|
|
* one built over `host` by the provided factory and kept with it while
|
|
* `host` lives, as `findCamera` does.
|
|
* @param {object|null|undefined} host
|
|
* @returns {import('./contract/credits').CreditsPort | null}
|
|
*/
|
|
export function findCredits(host) {
|
|
return unboundCredits.find(host);
|
|
}
|
|
|
|
/**
|
|
* The draw port of the renderer bound to `host`; with no renderer bound,
|
|
* one built over `host` by the provided factory and kept with it while
|
|
* `host` lives, as `findCamera` does.
|
|
*
|
|
* This is how a layer that is handed the scene object (a viewer) draws:
|
|
* it asks once, as it starts (`init`), and keeps the sets it makes; it
|
|
* reaches the camera through `cameraOf` the same way. A layer whose
|
|
* package is exported must tell a caller whose viewer has no renderer and
|
|
* no adapter factory loaded that it cannot draw, rather than do nothing
|
|
* (`drawOf`).
|
|
*
|
|
* A port built for a viewer with no renderer is released when a renderer
|
|
* is bound to it later: the sets already made through it keep drawing
|
|
* until disposed, but the renderer's own ports (its picks, height queries,
|
|
* `whenSettled`) do not see them. Bind the renderer before anything draws.
|
|
* @param {object|null|undefined} host
|
|
* @returns {import('./contract/draw').DrawPort | null}
|
|
*/
|
|
export function findDraw(host) {
|
|
return unboundDraws.find(host);
|
|
}
|
|
|
|
/** Why `host` has no port to `what` (draw with, query). */
|
|
const noPort = (host, what) =>
|
|
new Error(
|
|
host?.isDestroyed?.()
|
|
? 'This scene has been destroyed'
|
|
: `This scene has no renderer to ${what}: bind one, or load the ` +
|
|
"Cesium adapter's factories (the ./render/cesium/unbound export) for a viewer " +
|
|
'with no renderer bound',
|
|
);
|
|
|
|
/**
|
|
* `findDraw`, for code that cannot start without one.
|
|
* @param {object} host
|
|
* @returns {import('./contract/draw').DrawPort}
|
|
* @throws When there is no draw port for `host`.
|
|
*/
|
|
export function drawOf(host) {
|
|
const draw = findDraw(host);
|
|
if (draw) return draw;
|
|
throw noPort(host, 'draw with');
|
|
}
|
|
|
|
/**
|
|
* The query port of the renderer bound to `host`; with no renderer bound,
|
|
* one built over `host` by the provided factory and kept with it while
|
|
* `host` lives, as `findCamera` does. A built one picks, and its height
|
|
* queries see through, the sets drawn through `findDraw` on `host`; one
|
|
* kept from before a renderer was bound answers as it did, while new
|
|
* callers get the renderer's.
|
|
* @param {object|null|undefined} host
|
|
* @returns {import('./contract/query').QueryPort | null}
|
|
*/
|
|
export function findQuery(host) {
|
|
return unboundQueries.find(host);
|
|
}
|
|
|
|
/**
|
|
* `findQuery`, for code that cannot start without one.
|
|
* @param {object} host
|
|
* @returns {import('./contract/query').QueryPort}
|
|
* @throws When there is no query port for `host`.
|
|
*/
|
|
export function queryOf(host) {
|
|
const query = findQuery(host);
|
|
if (query) return query;
|
|
throw noPort(host, 'query');
|
|
}
|
|
|
|
/**
|
|
* The frame port of the renderer bound to `host`; with no renderer bound,
|
|
* one built over `host` by the provided factory and kept with it while
|
|
* `host` lives, as `findCamera` does. A built one listens to the loop
|
|
* `host`'s owner runs, as they set it up. Bound later, a renderer's own
|
|
* replaces it: its listeners hear nothing more and its holds end.
|
|
* @param {object|null|undefined} host
|
|
* @returns {import('./contract/frame').FramePort | null}
|
|
*/
|
|
export function findFrame(host) {
|
|
return unboundFrames.find(host);
|
|
}
|
|
|
|
/**
|
|
* `findFrame`, for code that cannot start without one.
|
|
* @param {object} host
|
|
* @returns {import('./contract/frame').FramePort}
|
|
* @throws When there is no frame port for `host`.
|
|
*/
|
|
export function frameOf(host) {
|
|
const frame = findFrame(host);
|
|
if (frame) return frame;
|
|
throw noPort(host, 'run frames with');
|
|
}
|
|
|
|
/**
|
|
* The input port of the renderer bound to `host`; with no renderer bound,
|
|
* one built over `host` by the provided factory and kept with it while
|
|
* `host` lives, as `findCamera` does. Bound later, a renderer's own
|
|
* replaces it: its listeners hear nothing more.
|
|
* @param {object|null|undefined} host
|
|
* @param {object} [options] For the factory, when this call builds the
|
|
* port (test doubles: a fake event source, a clock).
|
|
* @returns {import('./contract/input').InputPort | null}
|
|
*/
|
|
export function findInput(host, options) {
|
|
return unboundInputs.find(host, options);
|
|
}
|
|
|
|
/**
|
|
* Let go of `port`, if it is the input port `findInput` built for `host`
|
|
* (even one a renderer bound since superseded): its listeners hear nothing
|
|
* more. A renderer's own port, or one built later, is left alone.
|
|
* @param {object|null|undefined} host
|
|
* @param {object|null|undefined} port
|
|
*/
|
|
export function releaseUnboundInput(host, port) {
|
|
if (host && typeof host === 'object' && port) unboundInputs.drop(host, port);
|
|
}
|
|
|
|
/**
|
|
* A click's raw engine picks, built by the adapter's `provideNativeClick`.
|
|
* @typedef {object} NativeClick
|
|
* @property {{pick: unknown, pickWindow: (width: number, height: number) => unknown,
|
|
* drill: (limit?: number, width?: number, height?: number) => unknown[]}} native
|
|
* The engine's own picks at the click, each made at most once, for code
|
|
* still bound to the engine.
|
|
* @property {(limit?: number, width?: number, height?: number) => import('./contract/query').Hit[]} drillHits
|
|
* `native.drill` read as hits: draw-set items as the query port gives
|
|
* them, the map as surface hits, and anything else as a hit with no set
|
|
* (its id null when it has none). For a touch's contact search, which
|
|
* stops at whatever is drawn over a contact.
|
|
* @property {(width?: number, height?: number) => ({id: string|null} | import('./contract/query').Hit | null)} foreign
|
|
* What is on top there as the engine sees it, read where the renderer's
|
|
* pick names nothing: something drawn outside the draw port by its id
|
|
* (null when it has none), a draw-set item the renderer's sets do not
|
|
* hold as its hit; null when the top is the map or nothing.
|
|
*/
|
|
|
|
/**
|
|
* The raw engine picks of a click at `position` (CSS pixels, in the pick
|
|
* buffer), from the factory the renderer adapter provided; null when there
|
|
* is none, or it has nothing for `host`.
|
|
* @param {object|null|undefined} host
|
|
* @param {{x: number, y: number}} position
|
|
* @returns {NativeClick | null}
|
|
*/
|
|
export function nativeClickOf(host, position) {
|
|
if (!nativeClicks || !host || typeof host !== 'object') return null;
|
|
if (host.isDestroyed?.()) return null;
|
|
return nativeClicks(host, position) ?? null;
|
|
}
|
|
|
|
/**
|
|
* `findCamera`, for code that needs the camera.
|
|
* @param {object} host
|
|
* @returns {import('./contract/camera').CameraPort}
|
|
* @throws When there is no camera for `host`.
|
|
*/
|
|
export function cameraOf(host) {
|
|
const camera = findCamera(host);
|
|
if (camera) return camera;
|
|
throw new Error(
|
|
host?.isDestroyed?.()
|
|
? 'This scene has been destroyed'
|
|
: 'This scene has no renderer camera',
|
|
);
|
|
}
|