Files
gods-eye-view/src/render/cesium/drawQuads.js
T
Sameh Khamis 2a1e2d9c0b Cesium draw: a material or quad drawing a blob keeps it alive
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.
2026-11-11 20:25:55 -08:00

356 lines
12 KiB
JavaScript
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
/**
* @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 };
}