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.
This commit is contained in:
Sameh Khamis committed 2026-11-11 16:49:27 -08:00
1 parent a4a4366b13
commit b741b0d5f5
11 files changed
+674 -15

No files matched your search

+16 -2
View File
@@ -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();
+1 -6
View File
@@ -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.
+3 -5
View File
@@ -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);
});
+2
View File
@@ -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',
+139
View File
@@ -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;
}
+174
View File
@@ -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',
);
});