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

+14
View File
@@ -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
+52
View File
@@ -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",
+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',
);
});
+258
View File
@@ -26,6 +26,11 @@ const DOT = {
svg: '<svg xmlns="http://www.w3.org/2000/svg" width="16" height="16"><circle cx="8" cy="8" r="8" fill="#fff"/></svg>',
};
/** A white square, solid to its edges. */
const SQUARE = {
svg: '<svg xmlns="http://www.w3.org/2000/svg" width="16" height="16"><rect width="16" height="16" fill="#fff"/></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(
+11
View File
@@ -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
+4 -2
View File
@@ -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}`),
]);
});