/**
* @module render/cesium/credits
* @description The Cesium renderer's credits port over a Cesium credit
* display: every credit Cesium owes (its logo, static credits and each
* frame's imagery, terrain and tile credits) and every credit the page adds, as
* the contract's plain data (`src/render/contract/credits.d.ts`).
*
* Until the page renders the credit DOM, a credit the page adds is shown through
* Cesium's own display, so attribution stays on screen: `inline` credits on
* the credit line, the rest in its expandable list. Its markup is built
* here from the plain data, every value escaped.
*
* `change` fires when a page credit is added or removed, and after a drawn
* frame whose Cesium credits differ from the last one's.
*
* Cesium keeps one static credit per markup and placement: a page credit
* and another caller's of the same markup share one entry in the display,
* which goes when the one added first is removed.
*/
import * as Cesium from 'cesium';
import {
LINK_SCHEMES,
LOGO_SCHEMES,
creditFromMarkup,
safeUrl,
} from '../creditMarkup.js';
import { provideUnboundCredits } from '../rendererOf.js';
import { listenerList, uncaught } from './common.js';
import { creditDisplayContents } from './internals.js';
const CREDIT_KEYS = new Set(['text', 'href', 'logoUrl', 'inline']);
/** Readings kept per Cesium credit id; past this many, the cache restarts. */
const READINGS_KEPT = 512;
const escape = (value) =>
String(value).replace(
/[&<>"']/g,
(char) =>
({
'&': '&',
'<': '<',
'>': '>',
'"': '"',
"'": ''',
})[char],
);
/**
* A credit's markup for Cesium's display: the logo, then the text, linked
* when it has a web link. A link or logo of any other scheme is left out.
* @param {import('../contract/credits').Credit} credit
* @returns {string}
*/
export function creditMarkup(credit) {
const logo = credit.logoUrl && safeUrl(credit.logoUrl, LOGO_SCHEMES);
const body = [
logo &&
`
`,
credit.text && escape(credit.text),
]
.filter(Boolean)
.join(' ');
const href = credit.href && safeUrl(credit.href, LINK_SCHEMES);
return href
? `${body}`
: `${body}`;
}
/** The credit as given, its known fields only, in their given order. */
function copyCredit(credit) {
if (typeof credit?.text !== 'string')
throw new TypeError('A credit needs its text');
const copy = {};
for (const [key, value] of Object.entries(credit))
if (CREDIT_KEYS.has(key) && value !== undefined) copy[key] = value;
return copy;
}
/**
* @param {{display: object|undefined, scene: object,
* report: (error: unknown) => void, requestRender: () => void}} options
* `display`: the widget's Cesium CreditDisplay; without one, only the page's
* credits are listed. `requestRender` draws the display once a page
* credit comes or goes.
* @returns {{port: import('../contract/credits').CreditsPort,
* dispose: () => void}}
*/
export function createCesiumCredits({ display, scene, report, requestRender }) {
const listeners = listenerList(report);
// A viewer may be destroyed before the code holding credits lets
// them go; a destroyed display throws on every call.
const displayLive = () => Boolean(display) && !display.isDestroyed?.();
/** The page's credits, in the order added: each `{credit, markup}`. */
const added = [];
/** The page's credits as Cesium shows them, by markup: `{credit, count}`. */
const shown = new Map();
/** Cesium credit id → its text, link and logo. */
const readings = new Map();
const reading = (credit) => {
let read = readings.get(credit.id);
if (!read) {
if (readings.size >= READINGS_KEPT) readings.clear();
read = creditFromMarkup(credit.html);
readings.set(credit.id, read);
}
return { ...read, inline: Boolean(credit.showOnScreen) };
};
// The display shows a frame's credits most frequent first, sorting them
// in place as the frame ends, after postRender: the same stable sort,
// so the order is the same before and after.
const byCount = (elements) => [...elements].sort((a, b) => b.count - a.count);
/** The Cesium credits made for the page's, while shown. */
const coreCredits = new Set();
/**
* Every credit shown now, in display order, each a Cesium credit or
* (`core`) the Cesium credit made for the page's: the logo, then on the
* credit line and then in the expanded list, the static credits in the
* order added and the last frame's own, most frequent first. A second
* credit of the same markup and placement is left out, as the display
* leaves it out.
*/
function shownCredits() {
const { statics, screen, lightbox, logo } = creditDisplayContents(
displayLive() ? display : undefined,
);
const out = [];
const seen = new Set();
const take = (credit) => {
if (!credit) return;
const key = `${credit.id}:${credit.showOnScreen ? 1 : 0}`;
if (seen.has(key)) return;
seen.add(key);
out.push(credit);
};
take(logo);
for (const [inline, elements] of [
[true, screen],
[false, lightbox],
]) {
for (const credit of statics)
// The display shows an ion credit as its logo.
if (
Boolean(credit.showOnScreen) === inline &&
!(logo && credit.isIon?.())
)
take(credit);
for (const element of byCount(elements))
// A static credit counts Number.MAX_VALUE; those are listed above,
// and one removed since the frame is not owed any more.
if (element.count !== Number.MAX_VALUE) take(element.credit);
}
return out;
}
/** Cesium's own credits only, for the per-frame diff. */
const engineCredits = () =>
shownCredits().filter((credit) => !coreCredits.has(credit));
/**
* Cesium's credits read as plain data, with the page's listed as the page gave
* them where the display shows them; any the display does not show (no
* display, or one it already had) after.
*/
function list() {
const out = [];
const listed = new Set();
for (const credit of shownCredits()) {
if (!coreCredits.has(credit)) {
out.push(reading(credit));
continue;
}
for (const entry of added)
if (shown.get(entry.key)?.credit === credit) {
out.push({ ...entry.credit });
listed.add(entry);
}
}
for (const entry of added)
if (!listed.has(entry)) out.push({ ...entry.credit });
return out;
}
const changed = () => {
if (listeners.size > 0) listeners.fire(list());
};
// What Cesium owed after the last frame, as credit ids and placements.
const signature = () =>
engineCredits()
.map((credit) => `${credit.id}:${credit.showOnScreen ? 1 : 0}`)
.join(',');
let lastSignature = signature();
const afterFrame = () => {
const now = signature();
if (now === lastSignature) return;
lastSignature = now;
changed();
};
const offFrame = scene.postRender.addEventListener(afterFrame);
// Cesium shows one static credit per markup and placement, so the page's
// credits of the same markup and placement share one.
function show(markup, inline) {
const key = `${inline ? 'inline' : 'listed'}:${markup}`;
let entry = shown.get(key);
if (!entry) {
entry = { credit: new Cesium.Credit(markup, inline), count: 0 };
shown.set(key, entry);
coreCredits.add(entry.credit);
if (displayLive()) display.addStaticCredit(entry.credit);
}
entry.count += 1;
return key;
}
function hide(key) {
const entry = shown.get(key);
if (!entry) return;
entry.count -= 1;
if (entry.count > 0) return;
shown.delete(key);
coreCredits.delete(entry.credit);
if (displayLive()) display.removeStaticCredit(entry.credit);
}
let disposed = false;
const port = {
addStatic(credit) {
const copy = copyCredit(credit);
const entry = { credit: copy, key: null };
added.push(entry);
if (!disposed) {
entry.key = show(creditMarkup(copy), Boolean(copy.inline));
requestRender();
}
changed();
return () => {
const i = added.indexOf(entry);
if (i < 0) return;
added.splice(i, 1);
if (entry.key !== null && !disposed) {
hide(entry.key);
requestRender();
}
changed();
};
},
list,
on(event, cb) {
if (event !== 'change') return () => {};
return listeners.on(cb);
},
};
return {
port,
/** Detach from the scene and take the page's credits off the display. */
dispose() {
disposed = true;
offFrame();
listeners.clear();
if (displayLive())
for (const { credit } of shown.values())
display.removeStaticCredit(credit);
shown.clear();
coreCredits.clear();
},
/**
* Detach from the scene only: the credits added stay shown until their
* own Off, for a port another one supersedes.
*/
release() {
offFrame();
listeners.clear();
},
};
}
// A Cesium viewer with no renderer bound to it gets a
// credits port over its credit display when code first asks `findCredits`
// for one. `camera.js` loads this module, so the entries that load the
// unbound camera load this too.
provideUnboundCredits((viewer) =>
// By shape, not `instanceof`: the viewer may come from another
// copy of Cesium.
typeof viewer.creditDisplay?.addStaticCredit === 'function' &&
typeof viewer.scene?.postRender?.addEventListener === 'function'
? createCesiumCredits({
display: viewer.creditDisplay,
scene: viewer.scene,
report: uncaught,
requestRender: () => {
if (!viewer.scene.isDestroyed?.()) viewer.scene.requestRender?.();
},
})
: null,
);