mirror of
https://github.com/bilawalsidhu/gods-eye-view.git
synced 2026-11-16 08:12:24 +00:00
An image material loads its image on its first draw, and an atlas slot given a new image no longer holds the old blob, so a hidden fill, pattern or quad built from a slot could lose its blob to collection, its URL revoked, before it was ever drawn. Each material built from a blob (shape and ground image fills, line patterns) and each quad now holds the blob it draws while it lives.
356 lines
12 KiB
JavaScript
356 lines
12 KiB
JavaScript
/**
|
||
* @module render/cesium/drawQuads
|
||
* @description The Cesium draw port's `quads` sets: each item a unit plane
|
||
* primitive scaled to its `size`, posed by its `center` and `orientation`
|
||
* (the plane lies in the orientation's local x–y plane, width along x,
|
||
* height along y, its face toward local +z), textured with its image,
|
||
* video or canvas, and its outline beside it, as a Cesium plane entity
|
||
* draws them. An update moves, turns, resizes, shows or retextures the
|
||
* plane where it is; only a change of pickability or of outline rebuilds
|
||
* it.
|
||
*
|
||
* Choices the contract leaves open, taken conservatively:
|
||
* - `orientation` turns the plane in the Earth-fixed frame.
|
||
* - A canvas is read when an item first names it, as a Cesium material
|
||
* reads one: to show new pixels, name another canvas (two canvases in
|
||
* turn, say). The material takes a new image on the frame after it is
|
||
* named, so the two drawn frames after a change are asked for (asked
|
||
* for again once a hidden quad shows).
|
||
* - A video is read every drawn frame, and keeps frames coming while it
|
||
* plays and its quad shows (starting again as it plays, seeks or has
|
||
* data again); a video whose size changes is read at its new size. A
|
||
* change between a video and another source makes a new material, so
|
||
* neither reads into the other's texture.
|
||
* - Quads are lit by the scene's light and always draw translucent, their
|
||
* image's own alpha read, as a plane entity's transparent image material
|
||
* does.
|
||
*/
|
||
import * as Cesium from 'cesium';
|
||
import { toCartesian } from './common.js';
|
||
|
||
const scratchQuaternion = new Cesium.Quaternion();
|
||
const scratchScale = new Cesium.Cartesian3();
|
||
|
||
/** What a quad's material shows: an element, or an image's URL. */
|
||
function sourceOf(source, toImage) {
|
||
if (source?.video) return source.video;
|
||
if (source?.canvas) return source.canvas;
|
||
if (source && 'image' in source) return toImage(source.image);
|
||
throw new Error('a quad takes an image, a video or a canvas');
|
||
}
|
||
|
||
/** An outline as a key; '' for none. */
|
||
const outlineKey = (outline) =>
|
||
outline
|
||
? `${typeof outline.color === 'string' ? outline.color : outline.color.join(',')}|${outline.widthPx}`
|
||
: '';
|
||
|
||
/**
|
||
* The quads part of a Cesium draw port.
|
||
* @param {{toColor: Function, toImage: Function, holdImage?: Function,
|
||
* pickId: Function, replaceHost: Function, lineWidth: (px: number) => number,
|
||
* requestRender: () => void}} options From the draw port.
|
||
*/
|
||
export function createQuadSets({
|
||
toColor,
|
||
toImage,
|
||
holdImage = () => {},
|
||
pickId,
|
||
replaceHost,
|
||
lineWidth,
|
||
requestRender,
|
||
}) {
|
||
/** Materials replaced this frame, destroyed once it has drawn. */
|
||
let retired = [];
|
||
|
||
/** Media events after which a video draws again, with no frame asked. */
|
||
const VIDEO_EVENTS = ['play', 'playing', 'canplay', 'loadeddata', 'seeked'];
|
||
|
||
/** Ask for frames on the entry's video's events, while it shows one. */
|
||
function watchVideo(entry) {
|
||
unwatchVideo(entry);
|
||
const video = entry.source;
|
||
if (!isVideo(video)) return;
|
||
const wake = () => requestRender();
|
||
for (const name of VIDEO_EVENTS) video.addEventListener?.(name, wake);
|
||
entry.unwatch = () => {
|
||
for (const name of VIDEO_EVENTS) video.removeEventListener?.(name, wake);
|
||
};
|
||
}
|
||
|
||
function unwatchVideo(entry) {
|
||
entry.unwatch?.();
|
||
entry.unwatch = null;
|
||
}
|
||
|
||
/** The set's host, made once: its quads are changed where they are. */
|
||
function hostOf(record) {
|
||
if (record.host && !record.host.isDestroyed?.()) return record.host;
|
||
const host = new Cesium.PrimitiveCollection();
|
||
const quads = new Map();
|
||
// Materials hold their textures, which primitives leave alone: the
|
||
// host destroys them as it goes.
|
||
const destroyHost = host.destroy.bind(host);
|
||
host.destroy = () => {
|
||
for (const entry of quads.values()) {
|
||
freeMaterial(entry.material);
|
||
unwatchVideo(entry);
|
||
}
|
||
quads.clear();
|
||
return destroyHost();
|
||
};
|
||
record.quads = quads;
|
||
replaceHost(record, host);
|
||
return host;
|
||
}
|
||
|
||
function freeMaterial(material) {
|
||
if (material && !material.isDestroyed()) material.destroy();
|
||
}
|
||
|
||
function imageMaterial(source, alpha) {
|
||
return Cesium.Material.fromType('Image', {
|
||
image: source,
|
||
color: Cesium.Color.WHITE.withAlpha(alpha),
|
||
});
|
||
}
|
||
|
||
/** Each live entry's pick id, for height queries to see through. */
|
||
function notePickIds(record) {
|
||
record.pickIds = [];
|
||
for (const entry of record.quads.values())
|
||
record.pickIds.push(entry.pickId);
|
||
}
|
||
|
||
function matrixOf(item, result) {
|
||
const q = item.orientation;
|
||
scratchQuaternion.x = q.x;
|
||
scratchQuaternion.y = q.y;
|
||
scratchQuaternion.z = q.z;
|
||
scratchQuaternion.w = q.w;
|
||
scratchScale.x = item.size[0];
|
||
scratchScale.y = item.size[1];
|
||
scratchScale.z = 1;
|
||
return Cesium.Matrix4.fromTranslationQuaternionRotationScale(
|
||
toCartesian(item.center),
|
||
scratchQuaternion,
|
||
scratchScale,
|
||
result,
|
||
);
|
||
}
|
||
|
||
const pickableOf = (record, item) =>
|
||
record.spec.pickable !== false && item.pickable !== false;
|
||
|
||
/** Build an entry's primitives anew (it is new, or picks or outline changed). */
|
||
function build(record, entry) {
|
||
const host = record.host;
|
||
const item = entry.item;
|
||
const allowPicking = pickableOf(record, item);
|
||
const modelMatrix = matrixOf(item, new Cesium.Matrix4());
|
||
entry.source = sourceOf(item.source, toImage);
|
||
// A blob it draws stays alive while the quad does: its material loads
|
||
// the image on its first draw.
|
||
holdImage(entry, item.source?.image);
|
||
entry.alpha = item.alpha ?? 1;
|
||
entry.material = imageMaterial(entry.source, entry.alpha);
|
||
entry.videoSize = null;
|
||
entry.fill = host.add(
|
||
new Cesium.Primitive({
|
||
geometryInstances: new Cesium.GeometryInstance({
|
||
geometry: new Cesium.PlaneGeometry({
|
||
vertexFormat:
|
||
Cesium.MaterialAppearance.MaterialSupport.TEXTURED.vertexFormat,
|
||
}),
|
||
id: entry.pickId,
|
||
}),
|
||
appearance: new Cesium.MaterialAppearance({
|
||
material: entry.material,
|
||
translucent: true,
|
||
closed: false,
|
||
}),
|
||
modelMatrix,
|
||
allowPicking,
|
||
asynchronous: false,
|
||
show: item.show !== false,
|
||
}),
|
||
);
|
||
entry.outline = null;
|
||
if (item.outline) {
|
||
const color = toColor(item.outline.color);
|
||
entry.outline = host.add(
|
||
new Cesium.Primitive({
|
||
geometryInstances: new Cesium.GeometryInstance({
|
||
geometry: new Cesium.PlaneOutlineGeometry(),
|
||
attributes: {
|
||
color: Cesium.ColorGeometryInstanceAttribute.fromColor(color),
|
||
},
|
||
id: entry.pickId,
|
||
}),
|
||
appearance: new Cesium.PerInstanceColorAppearance({
|
||
flat: true,
|
||
translucent: color.alpha < 1,
|
||
renderState: { lineWidth: lineWidth(item.outline.widthPx ?? 1) },
|
||
}),
|
||
modelMatrix: Cesium.Matrix4.clone(modelMatrix),
|
||
allowPicking,
|
||
asynchronous: false,
|
||
show: item.show !== false,
|
||
}),
|
||
);
|
||
}
|
||
entry.pickable = allowPicking;
|
||
entry.outlineKey = outlineKey(item.outline);
|
||
entry.uploadFrames = 2;
|
||
watchVideo(entry);
|
||
}
|
||
|
||
function drop(record, id) {
|
||
const entry = record.quads.get(id);
|
||
if (!entry) return;
|
||
record.quads.delete(id);
|
||
unbuild(record, entry);
|
||
}
|
||
|
||
function unbuild(record, entry) {
|
||
const host = record.host;
|
||
for (const primitive of [entry.fill, entry.outline])
|
||
if (primitive && host && !host.isDestroyed()) host.remove(primitive);
|
||
freeMaterial(entry.material);
|
||
unwatchVideo(entry);
|
||
entry.fill = entry.outline = entry.material = null;
|
||
}
|
||
|
||
/** A new material for an entry, the old one freed once the frame drew. */
|
||
function rebind(entry) {
|
||
const old = entry.material;
|
||
entry.material = imageMaterial(entry.source, entry.alpha);
|
||
entry.fill.appearance.material = entry.material;
|
||
entry.videoSize = null;
|
||
entry.uploadFrames = 2;
|
||
if (old) retired.push(old);
|
||
}
|
||
|
||
function put(record, item) {
|
||
let entry = record.quads.get(item.id);
|
||
if (!entry) {
|
||
entry = { item, pickId: pickId(record, item) };
|
||
record.quads.set(item.id, entry);
|
||
build(record, entry);
|
||
return;
|
||
}
|
||
entry.item = item;
|
||
// The pick id is the primitives' own object: changed where it is.
|
||
entry.pickId.meta = item.meta;
|
||
if (
|
||
entry.pickable !== pickableOf(record, item) ||
|
||
entry.outlineKey !== outlineKey(item.outline)
|
||
) {
|
||
unbuild(record, entry);
|
||
build(record, entry);
|
||
return;
|
||
}
|
||
const show = item.show !== false;
|
||
matrixOf(item, entry.fill.modelMatrix);
|
||
entry.fill.show = show;
|
||
if (entry.outline) {
|
||
Cesium.Matrix4.clone(entry.fill.modelMatrix, entry.outline.modelMatrix);
|
||
entry.outline.show = show;
|
||
}
|
||
const alpha = item.alpha ?? 1;
|
||
if (alpha !== entry.alpha) {
|
||
entry.alpha = alpha;
|
||
entry.material.uniforms.color = Cesium.Color.WHITE.withAlpha(alpha);
|
||
}
|
||
const source = sourceOf(item.source, toImage);
|
||
if (source !== entry.source) {
|
||
const video = isVideo(source) || isVideo(entry.source);
|
||
entry.source = source;
|
||
holdImage(entry, item.source?.image);
|
||
if (video) {
|
||
// To or from a video: a material of its own, so the video's frames
|
||
// are not copied into another source's texture, or the other way.
|
||
rebind(entry);
|
||
watchVideo(entry);
|
||
} else {
|
||
// Another canvas or URL: the material reads it anew.
|
||
entry.material.uniforms.image = source;
|
||
entry.uploadFrames = 2;
|
||
}
|
||
}
|
||
}
|
||
|
||
/** Add or change items, by id; true once handled (always, for quads). */
|
||
function upsert(record, list) {
|
||
hostOf(record);
|
||
for (const item of list) put(record, item);
|
||
notePickIds(record);
|
||
requestRender();
|
||
return true;
|
||
}
|
||
|
||
/** The set's items as they are now: quads gone dropped, the rest kept. */
|
||
function rebuild(record) {
|
||
hostOf(record);
|
||
for (const id of [...record.quads.keys()])
|
||
if (!record.items.has(id)) drop(record, id);
|
||
for (const item of record.items.values()) put(record, item);
|
||
notePickIds(record);
|
||
}
|
||
|
||
const isVideo = (source) =>
|
||
typeof globalThis.HTMLVideoElement === 'function' &&
|
||
source instanceof globalThis.HTMLVideoElement;
|
||
|
||
/**
|
||
* Each frame, before it draws: a video whose size changed since its
|
||
* texture was made is read at its new size.
|
||
*/
|
||
function beforeRender(sets) {
|
||
for (const record of sets) {
|
||
if (record.kind !== 'quads' || !record.quads) continue;
|
||
for (const entry of record.quads.values()) {
|
||
const video = entry.source;
|
||
if (!entry.fill || !isVideo(video) || video.readyState < 2) continue;
|
||
const size = `${video.videoWidth}x${video.videoHeight}`;
|
||
if (entry.videoSize === null) entry.videoSize = size;
|
||
else if (entry.videoSize !== size) rebind(entry);
|
||
}
|
||
}
|
||
}
|
||
|
||
/**
|
||
* After a frame drew: the materials it replaced go, and a playing video
|
||
* on a shown quad, or an image a material is still to take, asks for the
|
||
* next frame. True when one did.
|
||
*/
|
||
function afterRender(sets) {
|
||
for (const material of retired) freeMaterial(material);
|
||
retired = [];
|
||
let playing = false;
|
||
for (const record of sets) {
|
||
if (record.kind !== 'quads' || !record.quads) continue;
|
||
if (record.spec.show === false || record.host?.show === false) continue;
|
||
for (const entry of record.quads.values()) {
|
||
if (!entry.fill?.show) continue;
|
||
// Only a frame that drew the quad counts toward taking its image.
|
||
if (entry.uploadFrames > 0) {
|
||
entry.uploadFrames -= 1;
|
||
playing = true;
|
||
}
|
||
const video = entry.source;
|
||
if (
|
||
isVideo(video) &&
|
||
!video.paused &&
|
||
!video.ended &&
|
||
video.readyState >= 2
|
||
)
|
||
playing = true;
|
||
}
|
||
}
|
||
return playing;
|
||
}
|
||
|
||
return { build: rebuild, upsert, beforeRender, afterRender };
|
||
}
|