From b741b0d5f5ca77258ce8ee5be36ddbc7c6122f2b Mon Sep 17 00:00:00 2001 From: Sameh Khamis Date: Wed, 11 Nov 2026 16:49:27 -0800 Subject: [PATCH] Every set blends as its blend says on the Cesium renderer Each frame drawn, a set's host turns the draw commands it gave to the set's blend before the scene sorts them: opaque draws every command in the opaque pass unblended with depth writes; translucent alpha-blends every command without depth writes; additive adds colour times alpha without depth writes, still depth-tested, after the opaque commands and before the order-independent translucent pass. Ground commands only blend differently. Lines, shapes, models, quads, meshes and GPU icons take every blend, live through setOptions (models do not load again); GPU icons no longer refuse opaque or additive. The contract documents the semantics and the checks draw.sets.blend and draw.models.blend read the pixels. The package boundaries own setBlend.js and screenCluster.js. --- docs/RENDERER-CONTRACT.md | 14 ++ scripts/package-boundaries.json | 52 +++++ src/render/cesium/draw.js | 18 +- src/render/cesium/gpuIcons.js | 7 +- src/render/cesium/gpuIcons.test.mjs | 8 +- src/render/cesium/harness.js | 2 + src/render/cesium/setBlend.js | 139 +++++++++++++ src/render/cesium/setBlend.test.mjs | 174 +++++++++++++++++ src/render/conformance/checks/ports.js | 258 +++++++++++++++++++++++++ src/render/contract/draw.d.ts | 11 ++ src/render/stub/stub.test.mjs | 6 +- 11 files changed, 674 insertions(+), 15 deletions(-) create mode 100644 src/render/cesium/setBlend.js create mode 100644 src/render/cesium/setBlend.test.mjs diff --git a/docs/RENDERER-CONTRACT.md b/docs/RENDERER-CONTRACT.md index 67cfb876b..22a29abc4 100644 --- a/docs/RENDERER-CONTRACT.md +++ b/docs/RENDERER-CONTRACT.md @@ -178,6 +178,20 @@ members' billboards; a set on the GPU (`columns`, or moving, receding, proxy-picked or level-of-detail icons) refuses clustering. The check `draw.icons.cluster` draws a cluster, picks it, and parts it by moving in. +A set's `blend` holds for every kind of set: omitted, opaque parts draw +opaque with depth writes and translucent ones blend without; `opaque` draws +every item opaque, its alpha ignored, with depth writes; `translucent` blends +every item without depth writes, even at alpha 1; `additive` adds each item's +colour times its alpha, without depth writes and still depth-tested. It +changes live (`setOptions`, from the next frame; models do not load again). +The Cesium port builds billboards and points in Cesium's blend options, and +turns every set's draw commands to its blend each frame before the scene +sorts them (`src/render/cesium/setBlend.js`): additive ones draw after every +opaque command and before the translucent pass, which blends +order-independently and would undo the addition; ground commands keep their +pass and stencil and only blend differently. The checks `draw.sets.blend` +(points, icons, lines, shapes) and `draw.models.blend` read the pixels. + The Cesium port also draws `pattern` line styles (the image repeated `repeat` times along the line, in the translucent pass; draped too), lines in the `inertial` frame (turned each frame by the set's motion clock, a depth-fail diff --git a/scripts/package-boundaries.json b/scripts/package-boundaries.json index 1e2577436..8b4a2adcd 100644 --- a/scripts/package-boundaries.json +++ b/scripts/package-boundaries.json @@ -23,6 +23,8 @@ "src/render/cesium/frame.js", "src/render/cesium/query.js", "src/render/cesium/draw.js", + "src/render/cesium/setBlend.js", + "src/geo/screenCluster.js", "src/render/cesium/drawModels.js", "src/geo/polyline.js", "src/render/cesium/gpuIcons.js", @@ -1035,6 +1037,8 @@ "src/render/cesium/heights.js", "src/queries/heights.js", "src/render/cesium/draw.js", + "src/render/cesium/setBlend.js", + "src/geo/screenCluster.js", "src/render/cesium/drawModels.js", "src/geo/polyline.js", "src/render/cesium/gpuIcons.js", @@ -1224,6 +1228,8 @@ "src/render/cesium/heights.js", "src/queries/heights.js", "src/render/cesium/draw.js", + "src/render/cesium/setBlend.js", + "src/geo/screenCluster.js", "src/render/cesium/drawFields.js", "src/render/cesium/drawStreamlines.js", "src/layers/wind/streamlines.js", @@ -1579,6 +1585,8 @@ "src/render/cesium/heights.js", "src/queries/heights.js", "src/render/cesium/draw.js", + "src/render/cesium/setBlend.js", + "src/geo/screenCluster.js", "src/render/cesium/gpuIcons.js", "src/render/motion/iconMotion.js", "src/render/cesium/cameraControls.js", @@ -1746,6 +1754,8 @@ "src/render/cesium/heights.js", "src/queries/heights.js", "src/render/cesium/draw.js", + "src/render/cesium/setBlend.js", + "src/geo/screenCluster.js", "src/render/cesium/drawModels.js", "src/geo/polyline.js", "src/render/cesium/gpuIcons.js", @@ -1876,6 +1886,8 @@ "src/render/cesium/heights.js", "src/queries/heights.js", "src/render/cesium/draw.js", + "src/render/cesium/setBlend.js", + "src/geo/screenCluster.js", "src/render/cesium/drawModels.js", "src/geo/polyline.js", "src/render/cesium/gpuIcons.js", @@ -2072,6 +2084,8 @@ "src/queries/heights.js", "src/render/creditMarkup.js", "src/render/cesium/draw.js", + "src/render/cesium/setBlend.js", + "src/geo/screenCluster.js", "src/render/cesium/gpuIcons.js", "src/render/motion/iconMotion.js", "src/render/cesium/frame.js", @@ -2119,6 +2133,8 @@ "src/render/cesium/effects.js", "src/render/cesium/screenModulation.js", "src/render/cesium/draw.js", + "src/render/cesium/setBlend.js", + "src/geo/screenCluster.js", "src/render/cesium/drawFields.js", "src/render/cesium/drawStreamlines.js", "src/layers/wind/streamlines.js", @@ -2252,6 +2268,8 @@ "src/render/cesium/credits.js", "src/render/creditMarkup.js", "src/render/cesium/draw.js", + "src/render/cesium/setBlend.js", + "src/geo/screenCluster.js", "src/render/cesium/drawQuads.js", "src/render/cesium/drawMeshes.js", "src/render/cesium/drawModels.js", @@ -2361,6 +2379,8 @@ "src/render/cesium/heights.js", "src/queries/heights.js", "src/render/cesium/draw.js", + "src/render/cesium/setBlend.js", + "src/geo/screenCluster.js", "src/render/cesium/drawQuads.js", "src/render/cesium/drawMeshes.js", "src/render/cesium/drawModels.js", @@ -2448,6 +2468,8 @@ "src/render/cesium/heights.js", "src/queries/heights.js", "src/render/cesium/draw.js", + "src/render/cesium/setBlend.js", + "src/geo/screenCluster.js", "src/render/cesium/drawQuads.js", "src/render/cesium/drawMeshes.js", "src/render/cesium/drawModels.js", @@ -2545,6 +2567,8 @@ "src/render/cesium/heights.js", "src/queries/heights.js", "src/render/cesium/draw.js", + "src/render/cesium/setBlend.js", + "src/geo/screenCluster.js", "src/render/cesium/drawQuads.js", "src/render/cesium/drawMeshes.js", "src/render/cesium/drawModels.js", @@ -2653,6 +2677,8 @@ "src/layers/awareness/focus.js", "src/render/cesium/camera.js", "src/render/cesium/draw.js", + "src/render/cesium/setBlend.js", + "src/geo/screenCluster.js", "src/render/cesium/cameraControls.js", "src/render/cesium/cameraInput.js", "src/render/cesium/credits.js", @@ -2773,6 +2799,8 @@ "src/render/cesium/drawHit.js", "src/render/cesium/cameraInput.js", "src/render/cesium/draw.js", + "src/render/cesium/setBlend.js", + "src/geo/screenCluster.js", "src/render/cesium/drawQuads.js", "src/render/cesium/drawMeshes.js", "src/render/cesium/drawModels.js", @@ -2928,6 +2956,8 @@ "src/render/cesium/heights.js", "src/queries/heights.js", "src/render/cesium/draw.js", + "src/render/cesium/setBlend.js", + "src/geo/screenCluster.js", "src/render/cesium/drawQuads.js", "src/render/cesium/drawMeshes.js", "src/render/cesium/drawModels.js", @@ -3027,6 +3057,8 @@ "src/render/cesium/query.js", "src/render/cesium/heights.js", "src/render/cesium/draw.js", + "src/render/cesium/setBlend.js", + "src/geo/screenCluster.js", "src/render/cesium/gpuIcons.js", "src/render/motion/iconMotion.js", "src/geo/index.js", @@ -3145,6 +3177,8 @@ "src/render/cesium/query.js", "src/render/cesium/heights.js", "src/render/cesium/draw.js", + "src/render/cesium/setBlend.js", + "src/geo/screenCluster.js", "src/render/cesium/cameraControls.js", "src/render/cesium/credits.js", "src/render/creditMarkup.js", @@ -3246,6 +3280,7 @@ "src/render/cesium/heights.js", "src/queries/heights.js", "src/render/cesium/draw.js", + "src/render/cesium/setBlend.js", "src/render/cesium/drawMeshes.js", "src/render/cesium/drawQuads.js", "src/render/cesium/drawModels.js", @@ -3331,6 +3366,8 @@ "src/render/cesium/heights.js", "src/queries/heights.js", "src/render/cesium/draw.js", + "src/render/cesium/setBlend.js", + "src/geo/screenCluster.js", "src/render/cesium/cameraControls.js", "src/render/cesium/credits.js", "src/render/creditMarkup.js", @@ -3446,6 +3483,8 @@ "src/render/cesium/credits.js", "src/render/cesium/tileRequests.js", "src/render/cesium/draw.js", + "src/render/cesium/setBlend.js", + "src/geo/screenCluster.js", "src/render/cesium/drawFields.js", "src/render/cesium/drawStreamlines.js", "src/layers/wind/streamlines.js", @@ -3716,6 +3755,7 @@ "src/render/baseTilesets.js", "src/render/cesium/drawHit.js", "src/render/cesium/draw.js", + "src/render/cesium/setBlend.js", "src/render/cesium/drawFields.js", "src/render/cesium/drawStreamlines.js", "src/render/cesium/drawMeshes.js", @@ -4865,6 +4905,7 @@ "src/render/cesium/query.js", "src/render/cesium/heights.js", "src/render/cesium/draw.js", + "src/render/cesium/setBlend.js", "src/render/cesium/drawFields.js", "src/render/cesium/drawStreamlines.js", "src/render/cesium/drawQuads.js", @@ -5649,6 +5690,8 @@ "src/render/cesium/heights.js", "src/render/cesium/drawHit.js", "src/render/cesium/draw.js", + "src/render/cesium/setBlend.js", + "src/geo/screenCluster.js", "src/render/cesium/drawQuads.js", "src/render/cesium/drawMeshes.js", "src/render/cesium/drawModels.js", @@ -5796,6 +5839,8 @@ "src/queries/heights.js", "src/render/cesium/drawHit.js", "src/render/cesium/draw.js", + "src/render/cesium/setBlend.js", + "src/geo/screenCluster.js", "src/render/cesium/gpuIcons.js", "src/render/motion/iconMotion.js", "src/render/cesium/cameraControls.js", @@ -6415,6 +6460,8 @@ "src/render/cesium/query.js", "src/render/cesium/heights.js", "src/render/cesium/draw.js", + "src/render/cesium/setBlend.js", + "src/geo/screenCluster.js", "src/render/cesium/drawQuads.js", "src/render/cesium/drawMeshes.js", "src/render/cesium/drawModels.js", @@ -6584,6 +6631,8 @@ "src/render/cesium/credits.js", "src/render/creditMarkup.js", "src/render/cesium/draw.js", + "src/render/cesium/setBlend.js", + "src/geo/screenCluster.js", "src/render/cesium/drawQuads.js", "src/render/cesium/drawMeshes.js", "src/render/cesium/drawModels.js", @@ -6873,6 +6922,8 @@ "src/render/cesium/query.js", "src/render/cesium/heights.js", "src/render/cesium/draw.js", + "src/render/cesium/setBlend.js", + "src/geo/screenCluster.js", "src/render/cesium/drawQuads.js", "src/render/cesium/drawMeshes.js", "src/render/cesium/drawModels.js", @@ -7263,6 +7314,7 @@ "modules": [ "src/render/contract/index.js", "src/render/stub/index.js", + "src/geo/screenCluster.js", "src/render/occlusion/index.js", "src/render/occlusion/depthProbe.js", "src/data/detectionOcclusion.js", diff --git a/src/render/cesium/draw.js b/src/render/cesium/draw.js index c85ee15d0..6cf84b3d5 100644 --- a/src/render/cesium/draw.js +++ b/src/render/cesium/draw.js @@ -38,6 +38,7 @@ import { clusterScreenPoints } from '../../geo/screenCluster.js'; import { provideUnboundDraw } from '../rendererOf.js'; import { blobUrl, listenerList, toCartesian, uncaught } from './common.js'; import { createGpuIcons, GPU_ICON_CAPABILITIES } from './gpuIcons.js'; +import { blendHost } from './setBlend.js'; import { createModelSets } from './drawModels.js'; import { materialTexture } from './internals.js'; import { createMeshSets } from './drawMeshes.js'; @@ -127,11 +128,15 @@ const displayConditionOf = (range) => ? new Cesium.DistanceDisplayCondition(range[0], range[1]) : undefined; -/** Cesium's point blending for a set's `blend`. */ +/** + * Cesium's point blending for a set's `blend`: additive ones are built + * translucent, a command a set, and added where they draw (`setBlend.js`). + */ const pointBlendOf = (blend) => ({ opaque: Cesium.BlendOption.OPAQUE, translucent: Cesium.BlendOption.TRANSLUCENT, + additive: Cesium.BlendOption.TRANSLUCENT, })[blend] ?? Cesium.BlendOption.OPAQUE_AND_TRANSLUCENT; /** @@ -560,7 +565,8 @@ export function createCesiumDraw({ Object.assign(spec, options); // What clamped items clamp to, how points blend, and whether ground // primitives pick, are built into them. Models clamp nothing, only - // points and icons build in the blend, and only shapes and lines have ground + // points and icons build in the blend (every set's commands are + // turned to it each frame, `setBlend.js`), and only shapes and lines have ground // primitives: other kinds are not rebuilt for those (models would // load again). if ( @@ -710,6 +716,8 @@ export function createCesiumDraw({ // Named for code that finds a set's host among the scene's primitives // (`uploadProbe.js`). host.drawSetId = record.spec.id; + // `blend`: its commands turned to the set's blend each frame drawn. + blendSetHost(record, host); // Only old ground primitives wait for the new ones: the rest of the old // host goes now, as the new host's own parts draw at once. if ( @@ -743,6 +751,11 @@ export function createCesiumDraw({ if (!old) orderHosts(); } + /** A set's host drawn in the set's `blend`, as it is each frame. */ + function blendSetHost(record, host) { + blendHost(host, () => record.spec.blend ?? undefined); + } + /** * `SetSpec.drawOrder`: the sets' hosts stacked in the scene's primitives * by their draw order. Of opaque billboards and points that skip the @@ -1002,6 +1015,7 @@ export function createCesiumDraw({ blendOption: pointBlendOf(record.spec.blend), }); record.clusterHost = host; + blendSetHost(record, host); scene.primitives.add(host); } host.removeAll(); diff --git a/src/render/cesium/gpuIcons.js b/src/render/cesium/gpuIcons.js index 2f3d1239c..0dee1f58d 100644 --- a/src/render/cesium/gpuIcons.js +++ b/src/render/cesium/gpuIcons.js @@ -13,8 +13,7 @@ * an item first needs it (or it first takes columns), and stays one. They * refuse loudly what billboards draw and they do not: clamped heights, * `fadeByDistance`, `displayRange`, pixel offsets, anchors other than the - * centre, axis and screen rotations, opaque and additive blends, and - * clustering. Their + * centre, axis and screen rotations, and clustering. Their * images (URLs, SVG, blobs, keyed canvases and atlas slots of those) * are rasterised square into the icon atlas every GPU icon set shares, and * refused when it has no room left for them: an SVG at its own size (its @@ -202,10 +201,6 @@ export function createGpuIcons({ /** Refuse what a GPU icon set cannot draw, before anything changes. */ function check(items, spec = {}) { - if (spec.blend === 'opaque' || spec.blend === 'additive') - throw new Error( - `the Cesium renderer's GPU icons have no ${spec.blend} blend`, - ); if (spec.cluster) throw new Error("the Cesium renderer's GPU icons have no clustering"); // Atlas slots these items would take anew: they must all fit. diff --git a/src/render/cesium/gpuIcons.test.mjs b/src/render/cesium/gpuIcons.test.mjs index c319ece88..e1b81398d 100644 --- a/src/render/cesium/gpuIcons.test.mjs +++ b/src/render/cesium/gpuIcons.test.mjs @@ -502,12 +502,10 @@ test('an icon set stays on billboards until an item needs the GPU', () => { const stays = draw.icons({ id: 'gpu:stays' }); stays.set([icon('a', { anchor: 'bottom' })]); assert.equal(part.sets.get('gpu:stays').gpu, undefined, 'billboards'); - // A blend GPU icons do not draw is refused, not ignored. + // Every blend moves over: it is turned where the commands are drawn. const additive = draw.icons({ id: 'gpu:additive', blend: 'additive' }); - assert.throws( - () => additive.set([icon('a', { motion: { kind: 'hold' } })]), - /additive blend/, - ); + additive.set([icon('a', { motion: { kind: 'hold' } })]); + assert.ok(part.sets.get('gpu:additive').gpu, 'on the GPU'); assert.ok(scene.added.length >= 1); }); diff --git a/src/render/cesium/harness.js b/src/render/cesium/harness.js index bdd80ea4d..401222831 100644 --- a/src/render/cesium/harness.js +++ b/src/render/cesium/harness.js @@ -55,10 +55,12 @@ export const CESIUM_CHECKS = new Set([ 'draw.lines.drape', 'draw.lines.segments', 'draw.lines.segmentStyles', + 'draw.sets.blend', 'draw.ids', 'draw.models', 'draw.models.loadFailed', 'draw.models.tint', + 'draw.models.blend', 'draw.models.update', 'draw.motion', 'draw.motion.arc', diff --git a/src/render/cesium/setBlend.js b/src/render/cesium/setBlend.js new file mode 100644 index 000000000..131649620 --- /dev/null +++ b/src/render/cesium/setBlend.js @@ -0,0 +1,139 @@ +/** + * @module render/cesium/setBlend + * @description `SetSpec.blend` on the Cesium renderer: a set's host draws + * its commands as it always has, and each frame drawn, the commands it gave + * are turned to the set's blend before the scene sorts them into passes. + * + * - none: as drawn (opaque parts opaque with depth writes; translucent ones + * blended without). + * - `opaque`: every command in the opaque pass, unblended (alpha ignored) + * with depth writes: billboards and points are built so (every fragment + * Cesium keeps, above an alpha of 0.005), and a GPU icon set's solid and + * translucent commands both drawn so here. + * - `translucent`: every command alpha-blended in the translucent pass, + * without depth writes, even where its alpha is 1. + * - `additive`: every command's colour times its alpha added to what is + * drawn, without depth writes and still depth-tested. They draw after + * every opaque command and before the translucent pass (in the pass + * Cesium keeps for Gaussian splats, back to front): the translucent pass + * blends order-independently, which would undo the addition. + * + * Ground (classification) commands keep their pass, stencil and depth: only + * their blending is turned. Picks are untouched: only render passes are. + * A command keeps what it was given, so a set whose blend changes is turned + * again from it on the next frame, without being rebuilt. + */ + +import * as Cesium from 'cesium'; + +const { Pass, BlendingState } = Cesium; + +/** Passes drawn in colour, with depth: the ones a blend moves between. */ +const COLOUR_PASSES = new Set([Pass.OPAQUE, Pass.TRANSLUCENT]); +/** Ground passes: classification draws through the stencil. */ +const GROUND_PASSES = new Set([ + Pass.TERRAIN_CLASSIFICATION, + Pass.CESIUM_3D_TILE_CLASSIFICATION, + Pass.CESIUM_3D_TILE_CLASSIFICATION_IGNORE_SHOW, +]); +/** Where additive commands draw: after opaque ones, before translucent. */ +export const ADDITIVE_PASS = Pass.GAUSSIAN_SPLATS; + +const WRAPPED = Symbol('setBlend.wrapped'); +const GIVEN = Symbol('setBlend.given'); + +/** Render states made from another, by blend and whether it moves passes. */ +const turned = new WeakMap(); + +function turnedState(given, blend, colour) { + let byBlend = turned.get(given); + if (!byBlend) turned.set(given, (byBlend = new Map())); + const key = `${blend}|${colour}`; + let state = byBlend.get(key); + if (state) return state; + const description = Cesium.RenderState.getState(given); + if (blend === 'opaque') { + description.blending = BlendingState.DISABLED; + if (colour) description.depthMask = true; + } else if (blend === 'translucent') { + if (!description.blending?.enabled) + description.blending = BlendingState.ALPHA_BLEND; + if (colour) description.depthMask = false; + } else { + description.blending = BlendingState.ADDITIVE_BLEND; + if (colour) description.depthMask = false; + } + state = Cesium.RenderState.fromCache(description); + byBlend.set(key, state); + return state; +} + +/** + * Turn the commands `list` holds from `start` on to `blend`. + * @param {object[]} list A frame's command list. + * @param {number} start + * @param {'opaque'|'translucent'|'additive'|undefined} blend + */ +export function blendCommands(list, start, blend) { + for (let i = start; i < list.length; i++) { + const command = list[i]; + const given = command[GIVEN]; + // What the command was given: kept while it still holds what this made. + let renderState = command.renderState; + let pass = command.pass; + if (given && renderState === given.made) { + renderState = given.renderState; + pass = given.pass; + } + if (blend === undefined || !renderState) { + if (given) { + command.renderState = renderState; + command.pass = pass; + command[GIVEN] = undefined; + } + continue; + } + const colour = COLOUR_PASSES.has(pass); + if (!colour && !GROUND_PASSES.has(pass)) continue; + const made = turnedState(renderState, blend, colour); + const to = !colour + ? pass + : blend === 'opaque' + ? Pass.OPAQUE + : blend === 'translucent' + ? Pass.TRANSLUCENT + : command.boundingVolume?.center + ? ADDITIVE_PASS + : Pass.TRANSLUCENT; + command[GIVEN] = { renderState, pass, made }; + // Assigned only when changed: a command that changes is derived again. + if (command.renderState !== made) command.renderState = made; + if (command.pass !== to) command.pass = to; + } +} + +/** + * Make `host` draw its commands in the blend `blendOf()` answers each frame. + * @param {{update: (frameState: object) => void}} host + * @param {() => ('opaque'|'translucent'|'additive'|undefined)} blendOf + * @returns {object} `host`. + */ +export function blendHost(host, blendOf) { + if (!host || host[WRAPPED] || typeof host.update !== 'function') return host; + host[WRAPPED] = true; + const update = host.update; + // Once turned, commands are turned back when the blend is gone. + let turnedAny = false; + host.update = function (frameState) { + const list = frameState.commandList; + const start = list.length; + const result = update.call(this, frameState); + if (!frameState.passes?.render) return result; + const blend = blendOf(); + if (blend === undefined && !turnedAny) return result; + if (blend !== undefined) turnedAny = true; + blendCommands(list, start, blend); + return result; + }; + return host; +} diff --git a/src/render/cesium/setBlend.test.mjs b/src/render/cesium/setBlend.test.mjs new file mode 100644 index 000000000..7a1b0d1ad --- /dev/null +++ b/src/render/cesium/setBlend.test.mjs @@ -0,0 +1,174 @@ +import assert from 'node:assert/strict'; +import * as Cesium from 'cesium'; +import test from 'node:test'; +import { ADDITIVE_PASS, blendCommands, blendHost } from './setBlend.js'; + +const { Pass, BlendingState, RenderState } = Cesium; + +// Node has no WebGL context to report line-width limits. +Cesium.ContextLimits._minimumAliasedLineWidth = 1; +Cesium.ContextLimits._maximumAliasedLineWidth = 10; + +const opaqueState = RenderState.fromCache({ + depthTest: { enabled: true }, + depthMask: true, +}); +const translucentState = RenderState.fromCache({ + depthTest: { enabled: true }, + depthMask: false, + blending: BlendingState.ALPHA_BLEND, +}); +const groundState = RenderState.fromCache({ + stencilTest: { enabled: true }, + depthMask: false, + blending: BlendingState.ALPHA_BLEND, +}); + +const bounds = new Cesium.BoundingSphere(Cesium.Cartesian3.ZERO, 1); +const commands = () => [ + new Cesium.DrawCommand({ + pass: Pass.OPAQUE, + renderState: opaqueState, + boundingVolume: bounds, + }), + new Cesium.DrawCommand({ + pass: Pass.TRANSLUCENT, + renderState: translucentState, + boundingVolume: bounds, + }), + new Cesium.DrawCommand({ + pass: Pass.TERRAIN_CLASSIFICATION, + renderState: groundState, + }), +]; + +const drawn = (list) => + list.map((c) => ({ + pass: c.pass, + blending: c.renderState.blending.enabled + ? c.renderState.blending.functionDestinationRgb === + Cesium.BlendFunction.ONE + ? 'add' + : 'alpha' + : 'none', + depthMask: c.renderState.depthMask, + depthTest: c.renderState.depthTest.enabled, + stencil: c.renderState.stencilTest.enabled, + })); + +test('no blend draws commands as given', () => { + const list = commands(); + const before = drawn(list); + blendCommands(list, 0, undefined); + assert.deepEqual(drawn(list), before); +}); + +test('opaque: every command opaque, unblended, with depth writes; ground keeps its pass', () => { + const list = commands(); + blendCommands(list, 0, 'opaque'); + assert.deepEqual( + drawn(list).map(({ pass, blending, depthMask }) => [ + pass, + blending, + depthMask, + ]), + [ + [Pass.OPAQUE, 'none', true], + [Pass.OPAQUE, 'none', true], + [Pass.TERRAIN_CLASSIFICATION, 'none', false], + ], + ); + assert.equal(list[2].renderState.stencilTest.enabled, true, 'stencil kept'); +}); + +test('translucent: alpha-blended without depth writes, even opaque ones', () => { + const list = commands(); + blendCommands(list, 0, 'translucent'); + assert.deepEqual( + drawn(list).map(({ pass, blending, depthMask }) => [ + pass, + blending, + depthMask, + ]), + [ + [Pass.TRANSLUCENT, 'alpha', false], + [Pass.TRANSLUCENT, 'alpha', false], + [Pass.TERRAIN_CLASSIFICATION, 'alpha', false], + ], + ); +}); + +test('additive: added after opaque commands, without depth writes, still depth-tested', () => { + const list = commands(); + blendCommands(list, 0, 'additive'); + assert.deepEqual( + drawn(list).map(({ pass, blending, depthMask, depthTest }) => [ + pass, + blending, + depthMask, + depthTest, + ]), + [ + [ADDITIVE_PASS, 'add', false, true], + [ADDITIVE_PASS, 'add', false, true], + [Pass.TERRAIN_CLASSIFICATION, 'add', false, false], + ], + ); +}); + +test('a changed blend turns commands again from what they were given', () => { + const list = commands(); + const kept = list.slice(); + blendCommands(list, 0, 'additive'); + blendCommands(kept.slice(), 0, 'opaque'); + assert.equal(kept[1].pass, Pass.OPAQUE); + blendCommands(kept.slice(), 0, undefined); + assert.deepEqual( + kept.map((c) => [c.pass, c.renderState]), + [ + [Pass.OPAQUE, opaqueState], + [Pass.TRANSLUCENT, translucentState], + [Pass.TERRAIN_CLASSIFICATION, groundState], + ], + 'back as given', + ); + // A state the host gives anew is what it now has. + const fresh = RenderState.fromCache({ + depthMask: true, + cull: { enabled: true }, + }); + blendCommands(kept.slice(), 0, 'translucent'); + kept[0].renderState = fresh; + blendCommands(kept.slice(0, 1), 0, undefined); + assert.equal(kept[0].renderState, fresh); +}); + +test('a blended host turns only its own commands, in render passes, each frame', () => { + const [mine, ,] = commands(); + const other = new Cesium.DrawCommand({ + pass: Pass.OPAQUE, + renderState: opaqueState, + boundingVolume: bounds, + }); + let blend = 'translucent'; + const host = blendHost( + { update: (fs) => fs.commandList.push(mine) }, + () => blend, + ); + const frame = (render = true) => { + const frameState = { commandList: [other], passes: { render } }; + host.update(frameState); + return frameState.commandList; + }; + assert.equal(frame(false)[1].pass, Pass.OPAQUE, 'picks untouched'); + const list = frame(); + assert.equal(list[0].pass, Pass.OPAQUE, 'not its own'); + assert.equal(list[1].pass, Pass.TRANSLUCENT); + blend = undefined; + assert.equal(frame()[1].pass, Pass.OPAQUE, 'the next frame, as given'); + assert.equal( + blendHost(host, () => 'opaque'), + host, + 'wrapped once', + ); +}); diff --git a/src/render/conformance/checks/ports.js b/src/render/conformance/checks/ports.js index 2f0ab7ac8..19c02da95 100644 --- a/src/render/conformance/checks/ports.js +++ b/src/render/conformance/checks/ports.js @@ -26,6 +26,11 @@ const DOT = { svg: '', }; +/** A white square, solid to its edges. */ +const SQUARE = { + svg: '', +}; + async function fresh(h) { return h.create({ viewport: SCRIPT_VIEWPORT }); } @@ -2356,6 +2361,175 @@ export function portChecks() { ); }, ), + check( + 'draw.sets.blend', + 'a set’s blend draws its items as it says, changed live: none blends translucent items; opaque ignores alpha; translucent blends; additive adds colour, still behind what is nearer', + async (h, r) => { + if (h.pixels === false) + return { skip: 'this harness reads no drawn pixels' }; + await overAustin(h, r); + const rect = (dLon, dLat, d) => ({ + west: AUSTIN.lon + dLon - d, + south: AUSTIN.lat + dLat - d, + east: AUSTIN.lon + dLon + d, + north: AUSTIN.lat + dLat + d, + }); + // Green under it all; blue nearer the eye over the second spot. + const under = r.draw.shapes({ id: 'conf:blend-under' }); + under.set([ + { + id: 'green', + geometry: { kind: 'rectangle', rect: rect(0, 0, 0.003), height: 0 }, + fill: '#00ff00', + height: 'absolute', + }, + { + id: 'blue', + geometry: { + kind: 'rectangle', + rect: rect(0.0015, 0, 0.0004), + height: 300, + }, + fill: '#0000ff', + height: 'absolute', + }, + ]); + const spotA = h.toEcef({ ...AUSTIN, height: 50 }); + const spotB = h.toEcef({ + lon: AUSTIN.lon + 0.0015, + lat: AUSTIN.lat, + height: 50, + }); + const pixel = (pos) => { + r.frame.renderNow(); + const s = r.query.project(pos); + const image = r.readPixels({ + crop: { + x: Math.round(s.x) - 1, + y: Math.round(s.y) - 1, + width: 3, + height: 3, + }, + }); + const i = (1 * image.width + 1) * 4; + return [...image.data.slice(i, i + 3)]; + }; + const kinds = { + points: (alpha) => [ + { id: 'a', pos: spotA, pixelSize: 24, color: [1, 0, 0, alpha] }, + { id: 'b', pos: spotB, pixelSize: 24, color: [1, 0, 0, alpha] }, + ], + icons: (alpha) => [ + { + id: 'a', + pos: spotA, + image: SQUARE, + size: [24, 24], + color: [1, 0, 0, alpha], + }, + { + id: 'b', + pos: spotB, + image: SQUARE, + size: [24, 24], + color: [1, 0, 0, alpha], + }, + ], + lines: (alpha) => [ + { + id: 'l', + positions: [ + h.toEcef({ + lon: AUSTIN.lon - 0.001, + lat: AUSTIN.lat, + height: 50, + }), + h.toEcef({ + lon: AUSTIN.lon + 0.0025, + lat: AUSTIN.lat, + height: 50, + }), + ], + widthPx: 24, + mode: '3d', + style: { kind: 'solid', color: [1, 0, 0, alpha] }, + }, + ], + shapes: (alpha) => + [ + ['a', 0], + ['b', 0.0015], + ].map(([id, dLon]) => ({ + id, + geometry: { + kind: 'rectangle', + rect: rect(dLon, 0, 0.0002), + height: 50, + }, + fill: [1, 0, 0, alpha], + height: 'absolute', + })), + }; + await drawn(h, r); + await settled(r); + const [, green] = pixel(spotA); + ok(green > 150, `the green under it draws (${green})`); + const show = (rgb) => `(${rgb.join(', ')})`; + try { + for (const [kind, items] of Object.entries(kinds)) { + const set = r.draw[kind]({ id: `conf:blend-${kind}` }); + try { + set.set(items(0.5)); + await drawn(h, r); + await settled(r); + let a = pixel(spotA); + ok( + a[0] > 60 && a[1] > 40 && a[1] < green - 30, + `${kind}, no blend: half red over green ${show(a)}`, + ); + set.setOptions({ blend: 'opaque' }); + await drawn(h, r); + a = pixel(spotA); + ok( + a[0] > 150 && a[1] < 60, + `${kind}, opaque: red, its alpha ignored ${show(a)}`, + ); + set.setOptions({ blend: 'translucent' }); + await drawn(h, r); + a = pixel(spotA); + ok( + a[0] > 60 && a[1] > 40 && a[1] < green - 30, + `${kind}, translucent: half red over green ${show(a)}`, + ); + set.setOptions({ blend: 'additive' }); + await drawn(h, r); + a = pixel(spotA); + ok( + a[0] > 60 && a[1] > green - 30, + `${kind}, additive: red added to green ${show(a)}`, + ); + const b = pixel(spotB); + ok( + b[0] < 60 && b[2] > 150, + `${kind}, additive: behind the nearer blue ${show(b)}`, + ); + set.set(items(1)); + set.setOptions({ blend: 'translucent' }); + await drawn(h, r); + a = pixel(spotA); + ok( + a[0] > 150 && a[1] < 60, + `${kind}, translucent at alpha 1: red ${show(a)}`, + ); + } finally { + set.dispose(); + } + } + } finally { + under.dispose(); + } + }, + ), check( 'draw.lines.drape', 'draped glow, dash and arrow lines draw and pick; a revealed line draws only its first part; a draped line and a clamped point that move every frame are drawn where they now are in the next frame', @@ -3004,6 +3178,90 @@ export function portChecks() { }, { capability: 'models' }, ), + check( + 'draw.models.blend', + 'a model set’s blend changes live, without loading again: additive adds the model’s colour to what is under it', + async (h, r) => { + if (!h.assets?.model) return { skip: 'no model asset in this harness' }; + if (h.pixels === false) + return { skip: 'this harness reads no drawn pixels' }; + await overAustin(h, r); + const d = 0.003; + const under = r.draw.shapes({ id: 'conf:models.blend-under' }); + under.set([ + { + id: 'green', + geometry: { + kind: 'rectangle', + rect: { + west: AUSTIN.lon - d, + south: AUSTIN.lat - d, + east: AUSTIN.lon + d, + north: AUSTIN.lat + d, + }, + height: 0, + }, + fill: '#00ff00', + height: 'absolute', + }, + ]); + const set = r.draw.models({ id: 'conf:models.blend' }); + const ready = []; + set.on('ready', (id) => ready.push(id)); + const pos = h.toEcef({ ...AUSTIN, height: 50 }); + set.set([ + { + id: 'm', + pos, + url: h.assets.model, + orientation: { heading: 0, pitch: 0, roll: 0 }, + minPixelSize: 160, + environmentMap: false, + shading: 'unlit', + tint: '#ff0000', + colorBlend: { mode: 'replace' }, + }, + ]); + try { + for (let i = 0; i < 600 && !ready.length; i++) await drawn(h, r, 1); + deepEqual(ready, ['m'], 'ready'); + const s = r.query.project(pos); + const count = async (like) => { + await drawn(h, r, 3); + await settled(r); + r.frame.renderNow(); + const image = r.readPixels({ + crop: { + x: Math.round(s.x) - 4, + y: Math.round(s.y) - 4, + width: 9, + height: 9, + }, + }); + let n = 0; + for (let i = 0; i < image.data.length; i += 4) + if (like(image.data[i], image.data[i + 1], image.data[i + 2])) + n++; + return n; + }; + const red = (r0, g, b) => r0 > 180 && g < 70 && b < 70; + const yellow = (r0, g, b) => r0 > 180 && g > 150 && b < 70; + ok((await count(red)) >= 40, 'no blend: red over green'); + set.setOptions({ blend: 'additive' }); + ok((await count(yellow)) >= 40, 'additive: red added to green'); + equal(await count(red), 0, 'additive: none red alone'); + set.setOptions({ blend: 'translucent' }); + ok((await count(red)) >= 40, 'translucent at alpha 1: red'); + set.setOptions({ blend: 'opaque' }); + ok((await count(red)) >= 40, 'opaque: red'); + deepEqual(ready, ['m'], 'never loaded again'); + } finally { + set.dispose(); + under.dispose(); + } + }, + { capability: 'models' }, + ), // --- Query ------------------------------------------------------------- check( diff --git a/src/render/contract/draw.d.ts b/src/render/contract/draw.d.ts index 1f990d6ca..fa0148fd8 100644 --- a/src/render/contract/draw.d.ts +++ b/src/render/contract/draw.d.ts @@ -66,6 +66,17 @@ export interface SetSpec { horizonCull?: boolean; /** `cluster`: screen-space clustering (icons only; see `ClusterSpec`). */ cluster?: ClusterSpec | null; + /** + * How the set's items blend with what is drawn. Omitted: opaque parts + * opaque with depth writes, items with alpha under 1 alpha-blended without + * depth writes. `opaque`: every item opaque, its alpha ignored (taken as + * 1), with depth writes (icons and points keep every part they draw, + * unblended). `translucent`: every item alpha-blended without depth + * writes, even at alpha 1. `additive`: each item's colour times its alpha + * added to what is drawn, without depth writes and still depth-tested. + * For every kind of set; `setOptions({blend})` takes effect from the next + * frame, and models do not load again. + */ blend?: 'opaque' | 'translucent' | 'additive'; /** * Among sets that do not depth-test against each other (items drawn with diff --git a/src/render/stub/stub.test.mjs b/src/render/stub/stub.test.mjs index 13dfc6f1c..164a820df 100644 --- a/src/render/stub/stub.test.mjs +++ b/src/render/stub/stub.test.mjs @@ -19,12 +19,14 @@ test('the stub passes the conformance suite', async () => { const skipped = report.results .filter((r) => r.status === 'skip') .map((r) => r.id); - // It draws only models into pixels, so the sweep's and a line outline's - // pixels go unread; its camera takes no user gestures: the drag and wheel scripts are for a + // It draws only models into pixels, so the sweep's, a line outline's and + // the blends' pixels (over a drawn shape) go unread; its camera takes no user gestures: the drag and wheel scripts are for a // camera that does (a controller over it, say). assert.deepEqual(skipped, [ 'effects.screenModulation.pixels', 'draw.lines.outline', + 'draw.sets.blend', + 'draw.models.blend', ...CAMERA_SCRIPTS.filter(usesInput).map((s) => `camera.trace.${s.name}`), ]); });