diff --git a/scripts/package-boundaries.json b/scripts/package-boundaries.json index 981ebe787..fbe31383c 100644 --- a/scripts/package-boundaries.json +++ b/scripts/package-boundaries.json @@ -1063,6 +1063,8 @@ "src/render/cesium/heights.js", "src/queries/heights.js", "src/render/cesium/draw.js", + "src/render/cesium/drawQuads.js", + "src/render/cesium/drawMeshes.js", "src/render/cesium/drawModels.js", "src/geo/polyline.js", "src/render/cesium/gpuIcons.js", @@ -1836,6 +1838,8 @@ "src/queries/heights.js", "src/render/cesium/effects.js", "src/render/cesium/draw.js", + "src/render/cesium/drawQuads.js", + "src/render/cesium/drawMeshes.js", "src/render/cesium/drawModels.js", "src/geo/polyline.js", "src/render/cesium/gpuIcons.js", @@ -1927,6 +1931,8 @@ "src/render/cesium/credits.js", "src/render/creditMarkup.js", "src/render/cesium/draw.js", + "src/render/cesium/drawQuads.js", + "src/render/cesium/drawMeshes.js", "src/render/cesium/drawModels.js", "src/geo/polyline.js", "src/render/cesium/gpuIcons.js", @@ -2022,6 +2028,8 @@ "src/render/cesium/heights.js", "src/queries/heights.js", "src/render/cesium/draw.js", + "src/render/cesium/drawQuads.js", + "src/render/cesium/drawMeshes.js", "src/render/cesium/drawModels.js", "src/geo/polyline.js", "src/render/cesium/gpuIcons.js", @@ -2091,6 +2099,8 @@ "src/render/cesium/heights.js", "src/queries/heights.js", "src/render/cesium/draw.js", + "src/render/cesium/drawQuads.js", + "src/render/cesium/drawMeshes.js", "src/render/cesium/drawModels.js", "src/geo/polyline.js", "src/render/cesium/gpuIcons.js", @@ -2178,6 +2188,8 @@ "src/render/cesium/heights.js", "src/queries/heights.js", "src/render/cesium/draw.js", + "src/render/cesium/drawQuads.js", + "src/render/cesium/drawMeshes.js", "src/render/cesium/drawModels.js", "src/geo/polyline.js", "src/render/cesium/gpuIcons.js", @@ -2383,6 +2395,8 @@ "src/render/cesium/drawHit.js", "src/render/cesium/cameraInput.js", "src/render/cesium/draw.js", + "src/render/cesium/drawQuads.js", + "src/render/cesium/drawMeshes.js", "src/render/cesium/drawModels.js", "src/geo/polyline.js", "src/render/cesium/gpuIcons.js", @@ -2517,6 +2531,8 @@ "src/render/cesium/heights.js", "src/queries/heights.js", "src/render/cesium/draw.js", + "src/render/cesium/drawQuads.js", + "src/render/cesium/drawMeshes.js", "src/render/cesium/drawModels.js", "src/geo/polyline.js", "src/render/cesium/gpuIcons.js", @@ -2806,6 +2822,8 @@ "src/render/cesium/heights.js", "src/queries/heights.js", "src/render/cesium/draw.js", + "src/render/cesium/drawMeshes.js", + "src/render/cesium/drawQuads.js", "src/render/cesium/drawModels.js", "src/geo/polyline.js", "src/render/cesium/gpuIcons.js", @@ -2984,6 +3002,8 @@ "src/render/cesium/credits.js", "src/render/cesium/tileRequests.js", "src/render/cesium/draw.js", + "src/render/cesium/drawQuads.js", + "src/render/cesium/drawMeshes.js", "src/render/cesium/drawModels.js", "src/geo/polyline.js", "src/render/cesium/gpuIcons.js", @@ -3214,6 +3234,8 @@ "src/render/cesium/globe.js", "src/render/cesium/drawHit.js", "src/render/cesium/draw.js", + "src/render/cesium/drawMeshes.js", + "src/render/cesium/drawQuads.js", "src/render/cesium/drawModels.js", "src/geo/polyline.js", "src/render/cesium/quality.js", @@ -4221,6 +4243,8 @@ "src/render/cesium/query.js", "src/render/cesium/heights.js", "src/render/cesium/draw.js", + "src/render/cesium/drawQuads.js", + "src/render/cesium/drawMeshes.js", "src/render/cesium/drawModels.js", "src/geo/polyline.js", "src/render/cesium/gpuIcons.js", @@ -4909,6 +4933,8 @@ "src/render/cesium/heights.js", "src/render/cesium/drawHit.js", "src/render/cesium/draw.js", + "src/render/cesium/drawQuads.js", + "src/render/cesium/drawMeshes.js", "src/render/cesium/drawModels.js", "src/geo/polyline.js", "src/render/cesium/gpuIcons.js", @@ -5586,6 +5612,8 @@ "src/render/cesium/query.js", "src/render/cesium/heights.js", "src/render/cesium/draw.js", + "src/render/cesium/drawQuads.js", + "src/render/cesium/drawMeshes.js", "src/render/cesium/drawModels.js", "src/geo/polyline.js", "src/render/cesium/gpuIcons.js", @@ -5737,6 +5765,8 @@ "src/render/cesium/credits.js", "src/render/creditMarkup.js", "src/render/cesium/draw.js", + "src/render/cesium/drawQuads.js", + "src/render/cesium/drawMeshes.js", "src/render/cesium/drawModels.js", "src/geo/polyline.js", "src/render/cesium/gpuIcons.js", @@ -5996,6 +6026,8 @@ "src/render/cesium/query.js", "src/render/cesium/heights.js", "src/render/cesium/draw.js", + "src/render/cesium/drawQuads.js", + "src/render/cesium/drawMeshes.js", "src/render/cesium/drawModels.js", "src/geo/polyline.js", "src/render/cesium/gpuIcons.js", diff --git a/src/render/cesium/draw.js b/src/render/cesium/draw.js index bc93c9692..ab5573ede 100644 --- a/src/render/cesium/draw.js +++ b/src/render/cesium/draw.js @@ -37,6 +37,8 @@ import { provideUnboundDraw } from '../rendererOf.js'; import { listenerList, toCartesian, uncaught } from './common.js'; import { createGpuIcons, GPU_ICON_CAPABILITIES } from './gpuIcons.js'; import { createModelSets } from './drawModels.js'; +import { createMeshSets } from './drawMeshes.js'; +import { createQuadSets } from './drawQuads.js'; /** The contract's colour as Cesium's. */ export function toColor(color, alpha = 1) { @@ -395,7 +397,9 @@ export function createCesiumDraw({ if ( patchLines(record, list) || patchShapes(record, list) || - (kind === 'models' && modelSets.upsert(record, list)) + (kind === 'models' && modelSets.upsert(record, list)) || + (kind === 'quads' && quadSets.upsert(record, list)) || + (kind === 'meshes' && meshSets.upsert(record, list)) ) { for (const item of list) items.set(item.id, item); if (kind === 'lines') noteFlows(record); @@ -449,7 +453,10 @@ export function createCesiumDraw({ if ( (kind !== 'models' && spec.clampTo !== clampTo) || ((kind === 'points' || kind === 'icons') && spec.blend !== blend) || - ((kind === 'shapes' || kind === 'lines') && + ((kind === 'shapes' || + kind === 'lines' || + kind === 'quads' || + kind === 'meshes') && (spec.pickable !== false) !== pickable) ) rebuild(); @@ -2994,6 +3001,24 @@ export function createCesiumDraw({ requestRender, }); const buildModels = (record) => modelSets.build(record); + const lineWidth = (px) => + typeof scene.clampLineWidth === 'function' + ? scene.clampLineWidth(px) + : Math.min(px, scene.maximumAliasedLineWidth ?? 1); + const quadSets = createQuadSets({ + toColor, + toImage, + pickId, + replaceHost, + lineWidth, + requestRender, + }); + const meshSets = createMeshSets({ + toColor, + pickId, + replaceHost, + requestRender, + }); /** The 3D tilesets in the scene, shown or not. */ function tilesets() { @@ -3032,6 +3057,10 @@ export function createCesiumDraw({ lines: (spec) => makeSet('lines', { ...spec }, buildLines), shapes: (spec) => makeSet('shapes', { ...spec }, buildShapes), models: (spec) => makeSet('models', { ...spec }, buildModels), + quads: (spec) => + makeSet('quads', { ...spec }, (record) => quadSets.build(record)), + meshes: (spec) => + makeSet('meshes', { ...spec }, (record) => meshSets.build(record)), clampState, on(event, cb) { if (event !== 'clampState') return () => {}; @@ -3075,6 +3104,7 @@ export function createCesiumDraw({ cullHorizon(); runFlows(); modelSets.beforeRender(sets.values()); + quadSets.beforeRender(sets.values()); }, /** Each frame, after it drew: clamp state, and ground swaps. */ afterRender() { @@ -3091,9 +3121,11 @@ export function createCesiumDraw({ } // Rows moving on a live clock, and flowing lines, draw on in the // frames that follow. + const playing = quadSets.afterRender(sets.values()); if ( [...sets.values()].some((record) => record.gpu?.animating()) || - flowing() + flowing() || + playing ) requestRender(); }, diff --git a/src/render/cesium/draw.test.mjs b/src/render/cesium/draw.test.mjs index 98870e9c6..f717e05a6 100644 --- a/src/render/cesium/draw.test.mjs +++ b/src/render/cesium/draw.test.mjs @@ -5163,3 +5163,268 @@ test('a raised polygon outlines its holes as well as its outer ring', () => } set.dispose(); })); + +test('quads draw a posed plane and its outline, changed in place', () => + withImageClasses(() => { + const scene = fakeScene(); + const part = createCesiumDraw({ + scene, + report: (error) => assert.fail(error), + }); + const set = part.port.quads({ id: 'monitors' }); + const canvas = { width: 4, height: 4 }; + const other = { width: 4, height: 4 }; + const center = { x: 6378137, y: 10, z: 20 }; + const quad = (extra = {}) => ({ + id: 'q', + center, + orientation: { x: 0, y: 0, z: 0, w: 1 }, + size: [40, 20], + source: { canvas }, + alpha: 0.95, + outline: { color: [0.4, 0.9, 1, 0.55], widthPx: 1 }, + meta: { camera: 'c1' }, + ...extra, + }); + set.set([quad()]); + const host = scene.added[0]; + assert.equal(host.length, 2, 'the plane and its outline'); + const [fill, outline] = [host.get(0), host.get(1)]; + assert.ok(fill.geometryInstances.geometry instanceof Cesium.PlaneGeometry); + assert.ok( + outline.geometryInstances.geometry instanceof Cesium.PlaneOutlineGeometry, + ); + assert.deepEqual(fill.geometryInstances.id, { + set: 'monitors', + id: 'q', + meta: { camera: 'c1' }, + lodGroup: undefined, + }); + // Scaled to its size about its centre, as a plane entity's matrix is. + const scale = Cesium.Matrix4.getScale( + fill.modelMatrix, + new Cesium.Cartesian3(), + ); + assert.deepEqual([scale.x, scale.y, scale.z], [40, 20, 1]); + const at = Cesium.Matrix4.getTranslation( + fill.modelMatrix, + new Cesium.Cartesian3(), + ); + assert.deepEqual({ x: at.x, y: at.y, z: at.z }, center); + const material = fill.appearance.material; + assert.equal(material.type, 'Image'); + assert.equal(material.uniforms.image, canvas); + assert.ok(Math.abs(material.uniforms.color.alpha - 0.95) < 1e-12); + assert.equal(fill.appearance.translucent, true); + + // Moved, resized, faded, hidden and given another canvas: the same plane. + set.upsert([ + quad({ + center: { x: 6378137, y: 30, z: 20 }, + size: [80, 45], + alpha: 0.5, + show: false, + source: { canvas: other }, + meta: { camera: 'c2' }, + }), + ]); + assert.equal(host.get(0), fill, 'changed where it is'); + Cesium.Matrix4.getScale(fill.modelMatrix, scale); + assert.deepEqual([scale.x, scale.y], [80, 45]); + assert.ok( + Cesium.Matrix4.equals(fill.modelMatrix, outline.modelMatrix), + 'the outline follows', + ); + assert.equal(fill.show, false); + assert.equal(outline.show, false); + assert.equal(material.uniforms.image, other, 'the new canvas is read'); + assert.ok(Math.abs(material.uniforms.color.alpha - 0.5) < 1e-12); + assert.deepEqual(fill.geometryInstances.id.meta, { camera: 'c2' }); + + // Unpickable, or without an outline: built anew. + set.upsert([quad({ outline: null, pickable: false })]); + assert.equal(host.length, 1, 'no outline'); + assert.notEqual(host.get(0), fill); + assert.equal(host.get(0).allowPicking, false); + set.remove(['q']); + assert.equal(host.length, 0); + set.dispose(); + assert.equal(scene.added.length, 0); + })); + +test('a video quad keeps frames coming while it plays, read anew at a new size', () => + withImageClasses(() => { + const realVideo = globalThis.HTMLVideoElement; + globalThis.HTMLVideoElement = class extends EventTarget {}; + try { + const scene = fakeScene(); + let renders = 0; + scene.requestRender = () => (renders += 1); + const part = createCesiumDraw({ + scene, + report: (error) => assert.fail(error), + }); + const set = part.port.quads({ id: 'feeds' }); + const video = Object.assign(new globalThis.HTMLVideoElement(), { + readyState: 4, + paused: false, + ended: false, + videoWidth: 640, + videoHeight: 360, + }); + set.set([ + { + id: 'v', + center: { x: 6378137, y: 0, z: 0 }, + orientation: { x: 0, y: 0, z: 0, w: 1 }, + size: [16, 9], + source: { video }, + alpha: 0.95, + }, + ]); + const fill = scene.added[0].get(0); + const first = fill.appearance.material; + assert.equal(first.uniforms.image, video); + part.beforeRender(); + renders = 0; + part.afterRender(); + assert.ok(renders > 0, 'a playing video asks for the next frame'); + // Past the frames a new image needs, a paused video asks for none. + part.afterRender(); + part.afterRender(); + video.paused = true; + renders = 0; + part.afterRender(); + assert.equal(renders, 0, 'a paused video draws no more frames'); + // A new size: a new material reads it, the old one freed once drawn. + video.videoWidth = 1280; + video.videoHeight = 720; + part.beforeRender(); + assert.notEqual(fill.appearance.material, first); + assert.equal(fill.appearance.material.uniforms.image, video); + assert.equal(first.isDestroyed(), false, 'kept until the frame drew'); + part.afterRender(); + assert.equal(first.isDestroyed(), true); + // Paused, it draws again as it plays, with no frame asked for. + renders = 0; + video.dispatchEvent(new Event('playing')); + assert.equal(renders, 1, 'playing again asks for a frame'); + // From the video to a canvas: a material of its own. + const sized = fill.appearance.material; + const canvas = { width: 4, height: 4 }; + const quad = { + id: 'v', + center: { x: 6378137, y: 0, z: 0 }, + orientation: { x: 0, y: 0, z: 0, w: 1 }, + size: [16, 9], + source: { canvas }, + alpha: 0.95, + }; + set.upsert([{ ...quad, show: false }]); + assert.notEqual(fill.appearance.material, sized); + assert.equal(fill.appearance.material.uniforms.image, canvas); + renders = 0; + video.dispatchEvent(new Event('playing')); + assert.equal(renders, 0, 'the video it left is no longer heard'); + // Hidden, the frames its image needs wait until it shows. + part.afterRender(); + part.afterRender(); + part.afterRender(); + set.upsert([quad]); + renders = 0; + part.afterRender(); + assert.ok(renders > 0, 'shown, it asks for the frames its image needs'); + set.dispose(); + } finally { + globalThis.HTMLVideoElement = realVideo; + } + })); + +test('meshes draw their triangles in the frame at their origin', () => + withImageClasses(() => { + const scene = fakeScene(); + const part = createCesiumDraw({ + scene, + report: (error) => assert.fail(error), + }); + const set = part.port.meshes({ id: 'volumes', pickable: false }); + const positions = new Float32Array([0, 0, 0, 10, 0, 0, 0, 10, 0, 0, 0, 10]); + const indices = new Uint16Array([0, 1, 2, 0, 1, 3]); + const origin = Cesium.Cartesian3.fromDegrees(-97.74, 30.27, 200); + const mesh = (extra = {}) => ({ + id: 'm', + origin: { x: origin.x, y: origin.y, z: origin.z }, + positions, + indices, + color: [0.2, 0.8, 1, 0.2], + flat: true, + ...extra, + }); + set.set([mesh()]); + const host = scene.added[0]; + assert.equal(host.length, 1); + const primitive = host.get(0); + const geometry = primitive.geometryInstances.geometry; + assert.equal( + geometry.attributes.position.componentDatatype, + Cesium.ComponentDatatype.DOUBLE, + ); + // In the Earth-fixed frame: the east-north-up offsets about the origin. + const frame = Cesium.Transforms.eastNorthUpToFixedFrame(origin); + const values = geometry.attributes.position.values; + for (let i = 0; i < positions.length; i += 3) { + const want = Cesium.Matrix4.multiplyByPoint( + frame, + new Cesium.Cartesian3(positions[i], positions[i + 1], positions[i + 2]), + new Cesium.Cartesian3(), + ); + assert.ok( + Cesium.Cartesian3.equalsEpsilon( + new Cesium.Cartesian3(values[i], values[i + 1], values[i + 2]), + want, + 0, + 1e-6, + ), + `vertex ${i / 3} in place`, + ); + } + assert.equal(geometry.indices, indices); + assert.equal(primitive.allowPicking, false, 'an unpickable set'); + assert.equal(primitive.appearance.flat, true); + assert.equal(primitive.appearance.translucent, true); + assert.equal( + primitive.appearance.renderState.cull.enabled, + false, + 'both faces', + ); + // Hidden: the same primitive. + set.upsert([mesh({ show: false })]); + assert.equal(host.get(0), primitive); + assert.equal(primitive.show, false); + // Moved: built anew where it now is. + const moved = Cesium.Cartesian3.fromDegrees(-97.73, 30.27, 200); + set.upsert([mesh({ origin: { x: moved.x, y: moved.y, z: moved.z } })]); + assert.equal(host.length, 1); + const rebuilt = host.get(0); + assert.notEqual(rebuilt, primitive); + const first = rebuilt.geometryInstances.geometry.attributes.position.values; + assert.ok( + Cesium.Cartesian3.equalsEpsilon( + new Cesium.Cartesian3(first[0], first[1], first[2]), + moved, + 0, + 1e-6, + ), + 'its origin vertex is the new origin', + ); + // A new colour builds it anew. + set.upsert([mesh({ color: '#ff0000' })]); + assert.equal(host.length, 1); + assert.notEqual(host.get(0), rebuilt); + // Lit meshes are closed: their back faces culled. + set.upsert([mesh({ flat: false })]); + assert.equal(host.get(0).appearance.closed, true); + set.clear(); + assert.equal(host.length, 0); + set.dispose(); + })); diff --git a/src/render/cesium/drawMeshes.js b/src/render/cesium/drawMeshes.js new file mode 100644 index 000000000..6119adc78 --- /dev/null +++ b/src/render/cesium/drawMeshes.js @@ -0,0 +1,182 @@ +/** + * @module render/cesium/drawMeshes + * @description The Cesium draw port's `meshes` sets: each item one + * primitive of its triangles, in the east-north-up frame at its `origin`, + * in its colour. `flat` draws it unlit with both faces (a translucent + * volume seen from inside or behind); otherwise it is lit by its own + * normals and its back faces are culled. Its vertices are placed in the + * Earth-fixed frame when it is built (a primitive whose own vertices sit at + * its frame's origin cannot be projected for the 2D views Cesium prepares), + * so any change but `show` builds it anew, at once, and it draws in the + * frame it replaces the old one. `positions` and `indices` are compared by + * identity: give new arrays to change a shape. + */ +import * as Cesium from 'cesium'; + +/** A colour as a key: a CSS string as it is, an RGBA array joined. */ +const colorKey = (color) => + typeof color === 'string' ? color : Array.from(color).join(','); + +/** + * The meshes part of a Cesium draw port. + * @param {{toColor: Function, pickId: Function, replaceHost: Function, + * requestRender: () => void}} options From the draw port. + */ +export function createMeshSets({ + toColor, + pickId, + replaceHost, + requestRender, +}) { + /** The set's host, made once: its meshes are changed where they are. */ + function hostOf(record) { + if (record.host && !record.host.isDestroyed?.()) return record.host; + const host = new Cesium.PrimitiveCollection(); + record.meshes = new Map(); + replaceHost(record, host); + return host; + } + + function notePickIds(record) { + record.pickIds = []; + for (const entry of record.meshes.values()) + record.pickIds.push(entry.pickId); + } + + const pickableOf = (record, item) => + record.spec.pickable !== false && item.pickable !== false; + + const scratchFrame = new Cesium.Matrix4(); + const scratchPoint = new Cesium.Cartesian3(); + + /** The item's east-north-up positions, in the Earth-fixed frame. */ + function fixedPositions(item) { + const { origin, positions } = item; + const frame = Cesium.Transforms.eastNorthUpToFixedFrame( + new Cesium.Cartesian3(origin.x, origin.y, origin.z), + Cesium.Ellipsoid.WGS84, + scratchFrame, + ); + const out = new Float64Array(positions.length); + for (let i = 0; i + 2 < positions.length; i += 3) { + scratchPoint.x = positions[i]; + scratchPoint.y = positions[i + 1]; + scratchPoint.z = positions[i + 2]; + Cesium.Matrix4.multiplyByPoint(frame, scratchPoint, scratchPoint); + out[i] = scratchPoint.x; + out[i + 1] = scratchPoint.y; + out[i + 2] = scratchPoint.z; + } + return out; + } + + /** What an entry's primitive is built from: equal keys need no rebuild. */ + const shapeKey = (record, item) => ({ + origin: `${item.origin.x},${item.origin.y},${item.origin.z}`, + positions: item.positions, + indices: item.indices, + color: colorKey(item.color), + flat: item.flat === true, + pickable: pickableOf(record, item), + }); + + const sameShape = (a, b) => + a.origin === b.origin && + a.positions === b.positions && + a.indices === b.indices && + a.color === b.color && + a.flat === b.flat && + a.pickable === b.pickable; + + function primitiveOf(record, item, entry) { + const values = fixedPositions(item); + const geometry = new Cesium.Geometry({ + attributes: { + position: new Cesium.GeometryAttribute({ + componentDatatype: Cesium.ComponentDatatype.DOUBLE, + componentsPerAttribute: 3, + values, + }), + }, + indices: item.indices, + primitiveType: Cesium.PrimitiveType.TRIANGLES, + boundingSphere: Cesium.BoundingSphere.fromVertices(Array.from(values)), + }); + const flat = item.flat === true; + if (!flat) Cesium.GeometryPipeline.computeNormal(geometry); + const color = toColor(item.color); + return new Cesium.Primitive({ + geometryInstances: new Cesium.GeometryInstance({ + geometry, + attributes: { + color: Cesium.ColorGeometryInstanceAttribute.fromColor(color), + }, + id: entry.pickId, + }), + appearance: new Cesium.PerInstanceColorAppearance({ + flat, + translucent: color.alpha < 1, + // Flat: both faces. Lit: a closed shape, its back faces culled. + closed: !flat, + ...(flat ? { renderState: { cull: { enabled: false } } } : {}), + }), + allowPicking: pickableOf(record, item), + asynchronous: false, + show: item.show !== false, + }); + } + + function put(record, item) { + const host = record.host; + let entry = record.meshes.get(item.id); + if (!entry) { + entry = { + item, + pickId: pickId(record, item), + key: null, + primitive: null, + }; + record.meshes.set(item.id, entry); + } + entry.item = item; + entry.pickId.meta = item.meta; + const key = shapeKey(record, item); + if (entry.primitive && entry.key && sameShape(entry.key, key)) { + entry.primitive.show = item.show !== false; + return; + } + const next = host.add(primitiveOf(record, item, entry)); + if (entry.primitive) host.remove(entry.primitive); + entry.primitive = next; + entry.key = key; + } + + function drop(record, id) { + const entry = record.meshes.get(id); + if (!entry) return; + record.meshes.delete(id); + const host = record.host; + if (entry.primitive && host && !host.isDestroyed()) + host.remove(entry.primitive); + } + + /** Add or change items, by id; true once handled (always, for meshes). */ + 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: meshes gone dropped, the rest kept. */ + function build(record) { + hostOf(record); + for (const id of [...record.meshes.keys()]) + if (!record.items.has(id)) drop(record, id); + for (const item of record.items.values()) put(record, item); + notePickIds(record); + } + + return { build, upsert }; +} diff --git a/src/render/cesium/drawQuads.js b/src/render/cesium/drawQuads.js new file mode 100644 index 000000000..190f49f20 --- /dev/null +++ b/src/render/cesium/drawQuads.js @@ -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 }; +} diff --git a/src/render/cesium/ports.js b/src/render/cesium/ports.js index c8b98cec0..273eefc59 100644 --- a/src/render/cesium/ports.js +++ b/src/render/cesium/ports.js @@ -60,6 +60,8 @@ const GLOBE_CAPABILITIES = [ export function cesiumCapabilities(scene, only) { const all = [ 'models', + 'quads', + 'meshes', 'followFrame', ...GPU_ICON_CAPABILITIES, 'styles', diff --git a/src/render/cesium/ports.test.mjs b/src/render/cesium/ports.test.mjs index 14bd66327..395bcd9aa 100644 --- a/src/render/cesium/ports.test.mjs +++ b/src/render/cesium/ports.test.mjs @@ -24,15 +24,16 @@ test('capabilities follow what the scene supports', () => { 'imageHooks', ]; const globe = { show: true }; - assert.deepEqual(cesiumCapabilities({}), ['models', ...effects]); + const draw = ['models', 'quads', 'meshes']; + assert.deepEqual(cesiumCapabilities({}), [...draw, ...effects]); // A scene with a globe reads its visibility back. assert.deepEqual(cesiumCapabilities({ globe }), [ - 'models', + ...draw, ...effects, 'globeVisibility', ]); assert.deepEqual(cesiumCapabilities({ pickPositionSupported: true }), [ - 'models', + ...draw, ...effects, 'pickPosition', ]); @@ -43,7 +44,7 @@ test('capabilities follow what the scene supports', () => { sampleHeightSupported: true, }), [ - 'models', + ...draw, ...effects, 'globeVisibility', 'pickPosition',