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}`),
]);
});