Draw quads and meshes through the Cesium draw port

The Cesium draw port now makes quads sets (a posed, textured plane with its
outline, drawn as a plane entity with a transparent image material draws it)
and meshes sets (triangles in the east-north-up frame at an origin, flat and
two-sided or lit and closed). Quads change in place as they move, resize,
fade or take a new canvas; a video quad keeps frames coming while it plays
and gets a new material when its size or source kind changes. Mesh vertices
are placed in the Earth-fixed frame, so Cesium can project them for its 2D
views. The capabilities list both kinds.
This commit is contained in:
Sameh Khamis committed 2026-11-08 07:23:54 -08:00
1 parent fa762f808e
commit 393f1686f2
7 files changed
+871 -7

No files matched your search

+350
View File
@@ -0,0 +1,350 @@
/**
* @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,
* pickId: Function, replaceHost: Function, lineWidth: (px: number) => number,
* requestRender: () => void}} options From the draw port.
*/
export function createQuadSets({
toColor,
toImage,
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);
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;
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 };
}