Merge origin/main: shipwrecks, news, transit fronts, signal-lost trails and uncredited photos on the renderer's ports

Upstream's layers and changes are carried onto the ports, with no Cesium
outside src/render and no reach into the viewer:

- Shipwrecks draw as one icon set, clicked through the input dispatcher.
- News draws through draw sets, the camera port and the input dispatcher;
  its beacons pulse each frame through the frame port.
- The scene occlusion probe moves into src/render/cesium and reaches
  detection through a new application hook, createOcclusionProbe; its
  private Cesium reads go through internals.js.
- Flight and military trails, the stale and SIGNAL LOST cue, coasting and
  following the world clock run on the draw and frame ports. GPU icons
  follow the scene clock while the world clock is followed, and fade when
  stale. A report that holds is not planned again every tick.
- Vessels are keyed by their record id.

The stub boot now enables military, shipwrecks and news as well.
This commit is contained in:
Sameh Khamis committed 2026-11-10 20:03:28 -08:00
commit a755f63638
331 files changed
+40654 -1666

No files matched your search

+5
View File
@@ -17,6 +17,11 @@
* itself (Cockpit asks whether the aircraft it flies still draws).
* - `installZoomOutGuard(options)`: keeps outward user zooms bounded and the
* Earth framed; returns its disposer.
* - `createOcclusionProbe()`: a probe that tests depth-tested contacts
* (street vehicles) against what the frame drew, so the detection overlay
* leaves out those something stands in front of (`SurfaceOcclusion` in
* `src/data/detectionOcclusion.js` says what it answers); without one,
* every such contact is drawn.
* - `qaHandles`: values QA scripts read from `window.__godsEyeView`.
* - `ownCreditDisplay`: true when the renderer shows its credits in a
* display of its own; otherwise the application shows what its credits
+4
View File
@@ -35,6 +35,7 @@ import { installFreeLookHeightLimit } from './freeLookLimit.js';
import { keepPanelRendering } from './panelRendering.js';
import { trimStaleSceneCommands } from './sceneCommandRelease.js';
import { installZoomOutGuard } from './zoomOutGuard.js';
import { createViewerOcclusionProbe } from './sceneOcclusionProbe.js';
import { configureCreditKeyboardAccess } from './creditKeyboard.js';
import { onLocaleChange } from '../../i18n/index.js';
import { cesiumViewerOf, recordViewer } from './viewers.js';
@@ -183,6 +184,9 @@ export function createCesiumRendererPlugin({
// Keeps outward user zooms bounded and the Earth framed; returns its
// disposer (see zoomOutGuard.js).
installZoomOutGuard: (options) => installZoomOutGuard(viewer, options),
// Tests depth-tested contacts (street vehicles) against the frame's
// own depth, for the detection overlay (see sceneOcclusionProbe.js).
createOcclusionProbe: () => createViewerOcclusionProbe(viewer),
// QA scripts drive and read the viewer itself.
qaHandles: { viewer },
});
+34 -14
View File
@@ -5987,7 +5987,8 @@ test('a draped line moved while its set rebuilds is no longer drawn where it was
));
test('a contact trail draws its history and moving head as depth-fail geodesic lines on a viewer of its own', async () => {
const { createTrail } = await import('../../data/trailRenderer.js');
const { CHUNK_POINTS, createTrail } =
await import('../../data/trailRenderer.js');
withImageClasses(() => {
const scene = fakeScene();
const viewer = { scene, isDestroyed: () => false };
@@ -5998,11 +5999,30 @@ test('a contact trail draws its history and moving head as depth-fail geodesic l
Cesium.Cartesian3.fromDegrees(-97 + i * 0.01, 30, 10000),
);
trail.setPositions(fixes);
const host = scene.added[0];
const deep = host.get(1);
const body = deep.get(0);
// The lines drawn now: a set that loses a line is built again.
const lines = () => {
const deep = scene.added[0].get(1);
return Array.from({ length: deep.length }, (_, i) => deep.get(i));
};
const positions = (line) => line.geometryInstances.geometry._positions;
// The history is cut into lines of CHUNK_POINTS fixes that share their
// boundary points, so the trail has no seam; the newest line grows.
const cut = lines();
const body = cut[0];
assert.ok(body instanceof Cesium.Primitive);
assert.equal(body.geometryInstances.geometry._positions.length, 400);
assert.equal(cut.length, 4, 'three full lines and the newest');
for (const line of cut.slice(0, 3))
assert.equal(positions(line).length, CHUNK_POINTS);
for (let i = 1; i < cut.length; i++)
assert.ok(
Cesium.Cartesian3.equalsEpsilon(
positions(cut[i - 1]).at(-1),
positions(cut[i])[0],
0,
1e-6,
),
'adjacent lines share their boundary point',
);
assert.ok(
Cesium.Color.equals(
body.depthFailAppearance.material.uniforms.color,
@@ -6014,19 +6034,19 @@ test('a contact trail draws its history and moving head as depth-fail geodesic l
Cesium.Cartesian3.fromDegrees(-150, 20, 10000),
Cesium.Cartesian3.fromDegrees(-120, 30, 10000),
]);
const long = deep.get(0);
const arc = long.geometryInstances.geometry._positions;
assert.equal(arc.length, 65, 'a lone leg in 64 steps');
// A long leg among short ones still takes a step a degree.
assert.equal(lines().length, 1);
assert.equal(positions(lines()[0]).length, 65, 'a lone leg in 64 steps');
// A long leg among short ones still takes a step a degree: the newest
// line's 18 short legs take their share of 64 steps, its long one more.
trail.setPositions([
...fixes,
Cesium.Cartesian3.fromDegrees(-63, 30, 10000),
]);
const mixed = deep.get(0).geometryInstances.geometry._positions;
assert.ok(
mixed.length > 400 + 25 && mixed.length < 400 + 40,
`${mixed.length}`,
);
const newest = positions(lines().at(-1)).length - 1;
const longSteps = newest - 18 * Math.ceil(64 / 19);
assert.ok(longSteps > 25 && longSteps < 40, `${longSteps}`);
// A history of one line, so the head is the set's second.
trail.setPositions(fixes.slice(0, 10));
// The head moves every frame alone, under one pick id.
const head = (lon) => [
Cesium.Cartesian3.fromDegrees(-120, 30, 10000),
@@ -0,0 +1,354 @@
/**
* A stand-in scene and WebGL context for tests of the occlusion probe: just
* the members `sceneOcclusionProbe.js` uses, with depth images the test
* controls.
*
* The fake context cannot run GLSL. When the probe draws a point inside a
* query, the fake decides whether the point draws by applying the same rule
* to the same inputs the vertex shader gets (the uploaded attributes, the
* bound depth textures and the uniforms), using the CPU decode from
* `detectionOcclusion.js`. That checks everything around the shader; the
* shader itself is checked against `scene.pickPosition` in a real browser.
*/
import * as Cesium from 'cesium';
import {
depthToViewDistance,
unpackDepth,
} from '../../../data/detectionOcclusion.js';
/** Inverse of `unpackDepth`: four base-255 digits, most significant first. */
export function packDepth(depth) {
const bytes = [];
let rest = Math.min(Math.max(depth, 0), 1);
for (let i = 0; i < 4; i++) {
rest *= 255;
const digit = Math.min(255, Math.floor(rest));
bytes.push(digit);
rest -= digit;
}
return bytes;
}
/** Inverse of `depthToViewDistance`. */
export function viewDistanceToDepth(distance, near, far, logDepth) {
if (logDepth)
return Math.log2(distance - near + 1) / Math.log2(far - near + 1);
return (far * (distance - near)) / (distance * (far - near));
}
/**
* An RGBA8 depth image filled from a function of the texel.
* @param {number} width
* @param {number} height
* @param {(column: number, row: number) => number} depthAt Window depth; rows
* count from the bottom.
*/
export function depthImage(width, height, depthAt) {
const data = new Uint8Array(width * height * 4);
for (let row = 0; row < height; row++)
for (let column = 0; column < width; column++)
data.set(packDepth(depthAt(column, row)), (row * width + column) * 4);
return { width, height, data };
}
const GL = {
FRAMEBUFFER: 0x8d40,
READ_FRAMEBUFFER: 0x8ca8,
DRAW_FRAMEBUFFER: 0x8ca9,
FRAMEBUFFER_BINDING: 0x8ca6,
DRAW_FRAMEBUFFER_BINDING: 0x8ca6,
READ_FRAMEBUFFER_BINDING: 0x8caa,
TEXTURE_BINDING_2D: 0x8069,
TEXTURE_2D: 0x0de1,
TEXTURE0: 0x84c0,
ACTIVE_TEXTURE: 0x84e0,
COLOR_ATTACHMENT0: 0x8ce0,
FRAMEBUFFER_COMPLETE: 0x8cd5,
ARRAY_BUFFER: 0x8892,
ARRAY_BUFFER_BINDING: 0x8894,
VERTEX_ARRAY_BINDING: 0x85b5,
CURRENT_PROGRAM: 0x8b8d,
STREAM_DRAW: 0x88e0,
SCISSOR_TEST: 0x0c11,
VIEWPORT: 0x0ba2,
POINTS: 0x0000,
FLOAT: 0x1406,
RGBA: 0x1908,
RGBA8: 0x8058,
UNSIGNED_BYTE: 0x1401,
VERTEX_SHADER: 0x8b31,
FRAGMENT_SHADER: 0x8b30,
COMPILE_STATUS: 0x8b81,
LINK_STATUS: 0x8b82,
ANY_SAMPLES_PASSED_CONSERVATIVE: 0x8d6a,
QUERY_RESULT: 0x8866,
QUERY_RESULT_AVAILABLE: 0x8867,
};
/**
* A recording WebGL context. `webgl2: false` leaves out queries, vertex
* arrays and immutable textures, as a WebGL 1 context does. Query results
* stay unavailable until `finishGpu()`.
*/
export function createFakeGl({ webgl2 = true } = {}) {
const state = {
read: null,
draw: null,
units: [null, null, null, null, null, null, null, null],
unit: 0,
array: null,
vertexArray: null,
program: null,
scissor: false,
viewport: [0, 0, 1920, 1080],
lost: false,
/** Whether a point that should draw does (false: a broken draw path). */
drawsLand: true,
/** Whether shaders compile: a boolean, or a function of the shader type. */
compiles: true,
};
const counts = {
readPixels: 0,
queries: 0,
draws: 0,
resultReads: 0,
deleted: 0,
};
const liveQueries = new Set();
const liveShaders = new Set();
let activeQuery = null;
const gl = {
...GL,
state,
counts,
liveQueries,
liveShaders,
isContextLost: () => state.lost,
getParameter(name) {
if (name === GL.READ_FRAMEBUFFER_BINDING) return state.read;
if (name === GL.DRAW_FRAMEBUFFER_BINDING) return state.draw;
if (name === GL.TEXTURE_BINDING_2D) return state.units[state.unit];
if (name === GL.ACTIVE_TEXTURE) return GL.TEXTURE0 + state.unit;
if (name === GL.ARRAY_BUFFER_BINDING) return state.array;
if (name === GL.VERTEX_ARRAY_BINDING) return state.vertexArray;
if (name === GL.CURRENT_PROGRAM) return state.program;
if (name === GL.VIEWPORT) return Int32Array.from(state.viewport);
return null;
},
isEnabled: (cap) => cap === GL.SCISSOR_TEST && state.scissor,
enable(cap) {
if (cap === GL.SCISSOR_TEST) state.scissor = true;
},
disable(cap) {
if (cap === GL.SCISSOR_TEST) state.scissor = false;
},
createFramebuffer: () => ({ image: null }),
createTexture: () => ({ image: null }),
createBuffer: () => ({ data: null }),
deleteFramebuffer() {
counts.deleted++;
},
deleteTexture() {
counts.deleted++;
},
deleteBuffer() {
counts.deleted++;
},
activeTexture(unit) {
state.unit = unit - GL.TEXTURE0;
},
bindTexture(_target, texture) {
state.units[state.unit] = texture;
},
bindFramebuffer(target, framebuffer) {
if (target !== GL.DRAW_FRAMEBUFFER) state.read = framebuffer;
if (target !== GL.READ_FRAMEBUFFER) state.draw = framebuffer;
},
bindBuffer(_target, buffer) {
state.array = buffer;
},
readPixels(x, y, width, height, _format, _type, destination) {
counts.readPixels++;
const image = state.read.image;
for (let row = 0; row < height; row++) {
const from = ((y + row) * image.width + x) * 4;
destination.set(
image.data.subarray(from, from + width * 4),
row * width * 4,
);
}
},
};
if (webgl2) {
Object.assign(gl, {
texStorage2D(_target, _levels, _format, width, height) {
state.units[state.unit].image = {
width,
height,
data: new Uint8Array(width * height * 4),
};
},
framebufferTexture2D(_target, _attachment, _kind, texture) {
state.draw.image = texture.image;
},
checkFramebufferStatus: () => GL.FRAMEBUFFER_COMPLETE,
createShader(type) {
const shader = { type };
liveShaders.add(shader);
return shader;
},
shaderSource() {},
compileShader() {},
getShaderParameter: (shader) =>
typeof state.compiles === 'function'
? state.compiles(shader.type)
: state.compiles,
deleteShader(shader) {
liveShaders.delete(shader);
},
createProgram: () => ({ uniforms: {} }),
attachShader() {},
linkProgram() {},
getProgramParameter: () => true,
deleteProgram() {
counts.deleted++;
},
getUniformLocation: (_program, name) => name,
useProgram(program) {
state.program = program;
},
viewport(x, y, width, height) {
state.viewport = [x, y, width, height];
},
uniform1i(name, value) {
state.program.uniforms[name] = value;
},
uniform4f(name, x, y, z, w) {
state.program.uniforms[name] = [x, y, z, w];
},
createVertexArray: () => ({ buffer: null }),
deleteVertexArray() {
counts.deleted++;
},
bindVertexArray(vertexArray) {
state.vertexArray = vertexArray;
},
enableVertexAttribArray() {},
vertexAttribPointer() {
state.vertexArray.buffer = state.array;
},
bufferData(_target, data) {
state.array.data = Float32Array.from(data);
},
createQuery() {
const query = { drew: false, available: false, ended: false };
liveQueries.add(query);
return query;
},
deleteQuery(query) {
liveQueries.delete(query);
},
beginQuery(_target, query) {
counts.queries++;
query.drew = false;
query.available = false;
query.ended = false;
activeQuery = query;
},
endQuery() {
activeQuery.ended = true;
activeQuery = null;
},
/** The vertex shader's rule, applied to what the shader would be given. */
drawArrays(_mode, first) {
counts.draws++;
const uniforms = state.program.uniforms;
const data = state.vertexArray.buffer.data;
const u = data[first * 3];
const v = data[first * 3 + 1];
const threshold = data[first * 3 + 2];
let surface = -1;
for (let i = 0; i < uniforms.u_count && surface < 0; i++) {
const image = state.units[uniforms[`u_depth${i}`]].image;
const column = Math.min(image.width - 1, Math.floor(u * image.width));
const row = Math.min(image.height - 1, Math.floor(v * image.height));
const distance = depthToViewDistance(
unpackDepth(image.data, (row * image.width + column) * 4),
uniforms.u_near[i],
uniforms.u_far[i],
uniforms.u_logDepth === 1,
);
if (distance === distance) surface = distance;
}
const hidden = surface > 0 && surface < threshold;
// A point at the middle of the viewport lands only if that is the
// target's one pixel and the scissor test is not in the way. A
// sampler left on a unit with no texture fails the whole draw.
const samplersBound = [0, 1, 2, 3].every(
(i) => state.units[uniforms[`u_depth${i}`]]?.image,
);
const lands =
state.drawsLand &&
samplersBound &&
!state.scissor &&
state.draw?.image?.width === 1 &&
state.viewport.join() === '0,0,1,1';
if (activeQuery && !hidden && lands) activeQuery.drew = true;
},
getQueryParameter(query, name) {
if (name === GL.QUERY_RESULT_AVAILABLE) return query.available;
counts.resultReads++;
return query.available && query.drew ? 1 : 0;
},
});
}
/** Let every query issued so far finish. */
gl.finishGpu = () => {
for (const query of liveQueries) if (query.ended) query.available = true;
};
return gl;
}
/**
* A scene drawn in the given depth ranges, nearest first.
* @param {{
* gl?: object,
* ranges: Array<{near: number, far: number, image: object}>,
* logDepth?: boolean, fovy?: number, aspectRatio?: number,
* viewMatrix?: Cesium.Matrix4,
* }} options
*/
export function createFakeDepthScene({
gl = createFakeGl(),
ranges,
logDepth = true,
fovy = Math.PI / 2,
aspectRatio = 1,
viewMatrix = Cesium.Matrix4.clone(Cesium.Matrix4.IDENTITY),
}) {
return {
mode: Cesium.SceneMode.SCENE3D,
useDepthPicking: true,
opaqueFrustumNearOffset: 0.9999,
context: { _gl: gl, depthTexture: true, webgl2: !!gl.createQuery },
_environmentState: { useGlobeDepthFramebuffer: true },
frameState: { useLogDepth: logDepth },
camera: { frustum: { fovy, aspectRatio }, viewMatrix },
view: {
frustumCommandsList: ranges.map(({ near, far }) => ({ near, far })),
pickDepths: ranges.map(({ image }) => {
const texture = { image };
return {
framebuffer: {
_framebuffer: { image },
getColorTexture: () => ({
width: image.width,
height: image.height,
_texture: texture,
}),
},
};
}),
},
};
}
+28
View File
@@ -132,6 +132,34 @@ export function webglContext(scene) {
return scene?.context?._gl;
}
/**
* Whether the scene drew its globe depth into its own framebuffer this frame,
* the depth a direct read of the pick-depth textures relies on.
* @param {object} scene Cesium Scene.
* @returns {boolean|undefined}
*/
export function usesGlobeDepthFramebuffer(scene) {
return scene?._environmentState?.useGlobeDepthFramebuffer;
}
/**
* A Cesium Framebuffer's own WebGL framebuffer.
* @param {object} framebuffer Cesium Framebuffer.
* @returns {WebGLFramebuffer|undefined}
*/
export function rawFramebuffer(framebuffer) {
return framebuffer?._framebuffer;
}
/**
* A Cesium Texture's own WebGL texture.
* @param {object} texture Cesium Texture.
* @returns {WebGLTexture|undefined}
*/
export function rawTexture(texture) {
return texture?._texture;
}
/**
* The entity Cesium's EntityView tracks: set once tracking has started and
* framed its entity, which can be frames after `trackedEntity` is set.
+3
View File
@@ -46,6 +46,9 @@ test('every private field the app reaches is still declared by the installed Ces
[ENGINE, 'Widget/CesiumWidget.js', '_renderLoopRunning'],
[WIDGETS, 'Viewer/Viewer.js', '_cesiumWidget'],
[ENGINE, 'Renderer/Context.js', '_gl'],
[ENGINE, 'Scene/Scene.js', '_environmentState'],
[ENGINE, 'Renderer/Framebuffer.js', '_framebuffer'],
[ENGINE, 'Renderer/Texture.js', '_texture'],
[ENGINE, 'Scene/Camera.js', '_currentFlight'],
[ENGINE, 'Widget/CesiumWidget.js', '_entityView'],
[ENGINE, 'Scene/Scene.js', '_renderRequested'],
+837
View File
@@ -0,0 +1,837 @@
/**
* Asks the GPU, per contact, whether the scene drew something in front of it,
* without waiting for the answer.
*
* The scene already keeps the depth of the frame it has just drawn (for
* picking). `scene.pickPosition` reads one texel of it back and waits, a
* fraction of a millisecond to over a millisecond per call; asking once per
* labelled contact turns a 2 ms frame into a 40 ms one. Copying the whole
* depth image back instead is no better where it matters: Chromium answers
* `getBufferSubData` with a round trip to its GPU process even after a sync
* object has signalled, measured here at 1.5 ms on a quiet machine and 15 to
* 25 ms on a busy one.
*
* So nothing is read back at all. Each tested contact becomes one point drawn
* into a private 1x1 target, inside an occlusion query. The vertex shader looks
* up the frame's depth at the contact's pixel, decodes it, and throws the point
* away when the drawn surface is nearer than the contact's threshold (see
* `projectContact`). The query's "did anything draw" bit is the answer, and
* asking whether a query result is in is the one question WebGL 2 lets a page
* put to the GPU without waiting (Chromium publishes results to the page
* through shared memory between frames): `_collect` just looks.
*
* - `beginFrame(scene, now)` collects the answers that have arrived.
* - `add(contact, position)` queues a contact for testing against this frame.
* - `endFrame()` draws the queued points. Answers land a frame or two later.
*
* A WebGL 1 context has no queries. There the probe falls back to reading the
* frame's depth back synchronously, at most every `SYNC_READ_INTERVAL_MS`, and
* answering on the CPU; `mode` then reads `'sync'`. Where the scene keeps no
* pick depth, or is not a 3D perspective view, `mode` reads `'off'`, nothing
* is tested and callers carry on as if no contact were hidden.
*
* Every read of renderer internals is in `readSceneDepthSource` below; the
* rest of the file is plain WebGL on the handles that function returns.
*/
import * as Cesium from 'cesium';
import {
DepthSnapshot,
projectContact,
} from '../../data/detectionOcclusion.js';
import {
rawFramebuffer,
rawTexture,
usesGlobeDepthFramebuffer,
webglContext,
} from './internals.js';
/**
* Depth ranges tested, nearest first. Logarithmic depth draws nearly every
* view in one or two; anything past the fourth is beyond where depth-tested
* contacts are labelled.
*/
export const PROBE_MAX_FRUSTUMS = 4;
/** Contacts tested per frame; the rest wait for the next one. */
export const PROBE_MAX_PER_FRAME = 256;
/** Painted frames a batch of queries may stay unanswered before it is dropped. */
export const PROBE_MAX_PENDING_FRAMES = 120;
/** Batches in a row whose control point failed before the probe stands down. */
export const PROBE_MAX_CONTROL_FAILURES = 3;
/** How long the probe stands down after a failure before trying again. */
export const PROBE_RETRY_AFTER_MS = 10_000;
/** Shortest gap between two synchronous depth reads (WebGL 1 fallback). */
export const SYNC_READ_INTERVAL_MS = 125;
/**
* Everything this module takes from the renderer, in one place.
*
* RENDERER INTERNALS. Checked against cesium 1.138.0 (@cesium/engine 22.3.0);
* re-check on an engine upgrade. Undocumented members used, and what each is
* assumed to be:
*
* - `scene.context._gl`: the WebGL context. `scene.context.webgl2` says which.
* - `scene.view.frustumCommandsList[i].near` / `.far`: the depth ranges the
* last frame was drawn in, nearest first.
* - `scene.view.pickDepths[i].framebuffer`: one framebuffer per depth range,
* refreshed every frame while `scene.useDepthPicking` is on and
* `scene._environmentState.useGlobeDepthFramebuffer` is true, whose first
* colour attachment is an RGBA8 texture holding window-space depth packed
* four bytes to a texel (`czm_packDepth`; see `unpackDepth`).
* `framebuffer._framebuffer` is the raw WebGL framebuffer, and
* `framebuffer.getColorTexture(0)` the texture (`._texture` its raw handle).
* - Opaque geometry in every range but the nearest is drawn with its near
* plane pulled in by `scene.opaqueFrustumNearOffset` (public), exactly as
* `scene.pickPosition` assumes when it decodes the same textures.
* - `scene.frameState.useLogDepth`: whether depth is logarithmic (see
* `depthToViewDistance`). Anything but a boolean there is "no depth".
*
* Any of these missing or shaped differently returns null, which callers treat
* as "no depth".
*
* @param {Cesium.Scene} scene
* @param {Float64Array} [viewScratch] Sixteen numbers to write the view matrix
* into instead of allocating; the result's `view` is then this array.
* @returns {null | {
* gl: WebGLRenderingContext|WebGL2RenderingContext, webgl2: boolean,
* width: number, height: number, framebuffers: WebGLFramebuffer[],
* textures: WebGLTexture[],
* frustums: Array<{near: number, far: number}>, logDepth: boolean,
* view: Float64Array, tanHalfFovX: number, tanHalfFovY: number,
* }}
*/
export function readSceneDepthSource(scene, viewScratch) {
try {
if (!scene || scene.mode !== Cesium.SceneMode.SCENE3D) return null;
if (scene.useDepthPicking !== true) return null;
const context = scene.context;
const gl = webglContext(scene);
if (!gl || context.depthTexture !== true) return null;
if (usesGlobeDepthFramebuffer(scene) !== true) return null;
const camera = scene.camera;
const frustum = camera?.frustum;
const fovy = frustum?.fovy;
const aspectRatio = frustum?.aspectRatio;
if (!(fovy > 0 && fovy < Math.PI) || !(aspectRatio > 0)) return null;
if (frustum.xOffset || frustum.yOffset) return null;
const view = scene.view;
const ranges = view?.frustumCommandsList;
const pickDepths = view?.pickDepths;
if (!ranges?.length || !pickDepths?.length) return null;
const count = Math.min(
ranges.length,
pickDepths.length,
PROBE_MAX_FRUSTUMS,
);
const nearOffset = Number(scene.opaqueFrustumNearOffset) || 1;
const framebuffers = [];
const textures = [];
const frustums = [];
let width = 0;
let height = 0;
for (let i = 0; i < count; i++) {
const framebuffer = pickDepths[i]?.framebuffer;
const raw = rawFramebuffer(framebuffer);
const texture = framebuffer?.getColorTexture?.(0);
const near = ranges[i]?.near * (i === 0 ? 1 : nearOffset);
const far = ranges[i]?.far;
if (!raw || !rawTexture(texture) || !(near > 0) || !(far > near))
return null;
if (i === 0) {
width = texture.width;
height = texture.height;
} else if (texture.width !== width || texture.height !== height) {
return null;
}
framebuffers.push(raw);
textures.push(rawTexture(texture));
frustums.push({ near, far });
}
if (!(width > 0) || !(height > 0)) return null;
// Read as standard depth, logarithmic depth puts every surface a few
// metres from the camera and would hide every contact: unknown is "no".
const logDepth = scene.frameState?.useLogDepth;
if (typeof logDepth !== 'boolean') return null;
const tanHalfFovY = Math.tan(fovy / 2);
return {
gl,
webgl2: context.webgl2 === true,
width,
height,
framebuffers,
textures,
frustums,
logDepth,
view: Cesium.Matrix4.toArray(
camera.viewMatrix,
viewScratch || new Float64Array(16),
),
tanHalfFovX: tanHalfFovY * aspectRatio,
tanHalfFovY,
};
} catch {
return null;
}
}
/**
* One point per contact. `a_contact` is (u, v, threshold): where the contact
* is in the frame, and the view distance a drawn surface must be under to hide
* it. A hidden contact's point is moved outside the clip volume, so nothing is
* drawn and its query reports no samples. A visible one lands on the single
* pixel of the 1x1 target (the viewport is set to match while these draw).
*/
export const PROBE_VERTEX_SHADER = `#version 300 es
precision highp float;
precision highp sampler2D;
layout(location = 0) in vec3 a_contact;
uniform sampler2D u_depth0;
uniform sampler2D u_depth1;
uniform sampler2D u_depth2;
uniform sampler2D u_depth3;
uniform int u_count;
uniform bool u_logDepth;
uniform vec4 u_near;
uniform vec4 u_far;
float viewDistance(sampler2D depthTexture, float near, float far) {
ivec2 size = textureSize(depthTexture, 0);
ivec2 texel = min(ivec2(a_contact.xy * vec2(size)), size - 1);
float depth = dot(
texelFetch(depthTexture, texel, 0),
vec4(1.0, 1.0 / 255.0, 1.0 / 65025.0, 1.0 / 16581375.0));
if (depth <= 0.0 || depth >= 1.0) return -1.0;
if (u_logDepth) return near + exp2(depth * log2(far - near + 1.0)) - 1.0;
return near * far / (far - depth * (far - near));
}
void main() {
float surface = viewDistance(u_depth0, u_near.x, u_far.x);
if (surface < 0.0 && u_count > 1) surface = viewDistance(u_depth1, u_near.y, u_far.y);
if (surface < 0.0 && u_count > 2) surface = viewDistance(u_depth2, u_near.z, u_far.z);
if (surface < 0.0 && u_count > 3) surface = viewDistance(u_depth3, u_near.w, u_far.w);
bool hidden = surface > 0.0 && surface < a_contact.z;
gl_Position = hidden ? vec4(2.0, 2.0, 2.0, 1.0) : vec4(0.0, 0.0, 0.0, 1.0);
gl_PointSize = 1.0;
}
`;
const FRAGMENT_SHADER = `#version 300 es
precision mediump float;
out vec4 color;
void main() { color = vec4(1.0); }
`;
function canQuery(gl) {
return (
typeof gl.createQuery === 'function' &&
typeof gl.beginQuery === 'function' &&
typeof gl.getQueryParameter === 'function' &&
typeof gl.createVertexArray === 'function'
);
}
function compile(gl, type, source) {
const shader = gl.createShader(type);
gl.shaderSource(shader, source);
gl.compileShader(shader);
if (!gl.getShaderParameter(shader, gl.COMPILE_STATUS)) {
gl.deleteShader(shader);
return null;
}
return shader;
}
/** Owns the GPU objects and the query batches in flight. */
export class SceneOcclusionProbe {
/**
* @param {{
* now?: () => number,
* readSource?: typeof readSceneDepthSource,
* }} [options]
*/
constructor({
now = () => performance.now(),
readSource = readSceneDepthSource,
} = {}) {
this._clock = now;
this._readSource = readSource;
/** Most tests one frame takes; read by whoever schedules them. */
this.maxPerFrame = PROBE_MAX_PER_FRAME;
/** `'async'` (queries), `'sync'` (blocking read), or `'off'`. */
this.mode = 'off';
/** Milliseconds the last frame spent collecting answers and drawing. */
this.lastFrameMs = 0;
/** Contact tests started in the last frame. */
this.lastFrameTests = 0;
this._scene = null;
this._now = 0;
this._source = undefined;
this._gl = null;
/** A context the probe's shader failed to build on; never retried. */
this._unsupportedGl = null;
this._resources = null;
this._queryPool = [];
this._batches = [];
this._attributes = new Float32Array((PROBE_MAX_PER_FRAME + 1) * 3);
this._queued = [];
this._projected = { u: 0, v: 0, threshold: 0 };
this._controlFailures = 0;
this._retryAt = Number.NEGATIVE_INFINITY;
this._frame = 0;
this._view = new Float64Array(16);
this._snapshot = null;
this._snapshotAt = Number.NEGATIVE_INFINITY;
this._spent = 0;
}
/**
* Open a frame: take in the answers that have arrived. Call after the scene
* has rendered (a post-render listener), before `add`.
* @param {Cesium.Scene} scene
* @param {number} now The caller's clock, in milliseconds. Answers are
* dated by it, so it must be the clock the caller judges their age on.
*/
beginFrame(scene, now) {
const started = this._clock();
this._scene = scene;
this._now = now;
this._frame++;
this._source = undefined;
// A frame that never reached `endFrame` leaves its contacts untested.
this._release(this._queued);
this._queued.length = 0;
this.lastFrameTests = 0;
this._collect();
this._spent = this._clock() - started;
}
/**
* Queue a contact for testing against the frame just drawn.
* @param {{lastHiddenAt: number, pending: boolean, answered: boolean}}
* contact Updated when the answer arrives: `pending` cleared, `answered`
* set and, if the contact was hidden, `lastHiddenAt` set to the time of
* the frame it was tested against.
* @param {{x: number, y: number, z: number}} position
* @returns {boolean} False when the contact cannot be tested now.
*/
add(contact, position) {
if (this._source === undefined) this._openSource();
const source = this._source;
if (!source) return false;
if (this.mode === 'sync') {
const hidden = this._snapshot?.hides(position);
if (hidden === null || hidden === undefined) return false;
contact.answered = true;
if (hidden) contact.lastHiddenAt = this._now;
this.lastFrameTests++;
return true;
}
const queued = this._queued;
if (queued.length >= PROBE_MAX_PER_FRAME) return false;
const projected = this._projected;
if (
!projectContact(
source.view,
source.tanHalfFovX,
source.tanHalfFovY,
position,
projected,
)
)
return false;
// Slot 0 is the control point; contacts start at 1.
const at = (queued.length + 1) * 3;
const attributes = this._attributes;
attributes[at] = projected.u;
attributes[at + 1] = projected.v;
attributes[at + 2] = projected.threshold;
queued.push(contact);
contact.pending = true;
this.lastFrameTests++;
return true;
}
/** Close the frame: draw the queued contacts' queries. */
endFrame() {
const started = this._clock();
if (this._queued.length > 0 && this._source && this.mode === 'async') {
try {
this._draw(this._source);
} catch {
this._release(this._queued);
this._fail();
}
}
this._queued.length = 0;
this._source = undefined;
this.lastFrameMs = this._spent + (this._clock() - started);
}
/**
* Drop every test in flight but keep the GPU objects, so that switching the
* overlay off and on again does not compile the shader a second time.
*/
reset() {
const gl = this._gl;
for (const batch of this._batches) this._release(batch.contacts);
this._release(this._queued);
try {
if (gl && !gl.isContextLost?.()) {
for (const batch of this._batches)
for (let i = batch.cursor; i < batch.queries.length; i++)
this._queryPool.push(batch.queries[i]);
}
} catch {
// A context that is going away has already released them.
}
this._batches.length = 0;
this._queued.length = 0;
this._source = undefined;
this._snapshot = null;
this._snapshotAt = Number.NEGATIVE_INFINITY;
this._controlFailures = 0;
this._retryAt = Number.NEGATIVE_INFINITY;
this.mode = 'off';
}
/** Delete the GPU objects and drop every test in flight. */
destroy() {
this.reset();
const gl = this._gl;
try {
if (gl && !gl.isContextLost?.()) {
for (const query of this._queryPool) gl.deleteQuery(query);
const resources = this._resources;
if (resources) {
gl.deleteProgram(resources.program);
gl.deleteVertexArray(resources.vertexArray);
gl.deleteBuffer(resources.buffer);
gl.deleteFramebuffer(resources.framebuffer);
gl.deleteTexture(resources.texture);
}
}
} catch {
// A context that is going away has already released them.
}
this._queryPool.length = 0;
this._resources = null;
this._gl = null;
this._unsupportedGl = null;
}
/** Tests that will never be answered stop counting as in flight. */
_release(contacts) {
for (const contact of contacts) if (contact) contact.pending = false;
}
/**
* Something in the query path broke: stand down for a while and keep
* everything drawn, then try again in case the cause was passing.
*/
_fail() {
this._retryAt = this._now + PROBE_RETRY_AFTER_MS;
this._controlFailures = 0;
this.mode = 'off';
}
/** Read this frame's depth source, once, when the first contact asks. */
_openSource() {
this._source = null;
if (this._now < this._retryAt) return;
const source = this._readSource(this._scene, this._view);
if (!source) {
this.mode = 'off';
return;
}
if (source.gl !== this._gl) {
// A different context (a rebuilt viewer) orphans whatever was in flight.
this.destroy();
this._gl = source.gl;
}
try {
if (source.gl.isContextLost?.()) {
// Everything made on the lost context went with it.
this.reset();
this._queryPool.length = 0;
this._resources = null;
return;
}
if (source.gl === this._unsupportedGl) {
// The shader did not build on this context: nothing is tested here.
this.mode = 'off';
return;
}
if (source.webgl2 && canQuery(source.gl)) {
if (!this._resources && !this._createResources(source.gl)) {
this._fail();
return;
}
this.mode = 'async';
} else {
this.mode = 'sync';
if (this._now - this._snapshotAt >= SYNC_READ_INTERVAL_MS) {
this._snapshot = this._readSync(source);
this._snapshotAt = this._now;
}
}
this._source = source;
} catch {
this._fail();
}
}
/**
* Compile the shader and make the 1x1 target. This is the one place the
* probe does wait on the GPU process (compile, link and framebuffer status
* are answered synchronously): once per WebGL context, on the first frame a
* depth-tested contact is in view. `reset` keeps the result.
*/
_createResources(gl) {
const vertex = compile(gl, gl.VERTEX_SHADER, PROBE_VERTEX_SHADER);
const fragment = compile(gl, gl.FRAGMENT_SHADER, FRAGMENT_SHADER);
if (!vertex || !fragment) {
if (vertex) gl.deleteShader(vertex);
if (fragment) gl.deleteShader(fragment);
// The same source will not compile on this context next time either.
this._unsupportedGl = gl;
return false;
}
const program = gl.createProgram();
gl.attachShader(program, vertex);
gl.attachShader(program, fragment);
gl.linkProgram(program);
gl.deleteShader(vertex);
gl.deleteShader(fragment);
if (!gl.getProgramParameter(program, gl.LINK_STATUS)) {
gl.deleteProgram(program);
this._unsupportedGl = gl;
return false;
}
const uniform = (name) => gl.getUniformLocation(program, name);
const previousArray = gl.getParameter(gl.VERTEX_ARRAY_BINDING);
const previousBuffer = gl.getParameter(gl.ARRAY_BUFFER_BINDING);
const previousTexture = gl.getParameter(gl.TEXTURE_BINDING_2D);
const previousDraw = gl.getParameter(gl.DRAW_FRAMEBUFFER_BINDING);
const vertexArray = gl.createVertexArray();
const buffer = gl.createBuffer();
gl.bindVertexArray(vertexArray);
gl.bindBuffer(gl.ARRAY_BUFFER, buffer);
gl.enableVertexAttribArray(0);
gl.vertexAttribPointer(0, 3, gl.FLOAT, false, 0, 0);
gl.bindVertexArray(previousArray);
gl.bindBuffer(gl.ARRAY_BUFFER, previousBuffer);
const texture = gl.createTexture();
const framebuffer = gl.createFramebuffer();
gl.bindTexture(gl.TEXTURE_2D, texture);
gl.texStorage2D(gl.TEXTURE_2D, 1, gl.RGBA8, 1, 1);
gl.bindTexture(gl.TEXTURE_2D, previousTexture);
gl.bindFramebuffer(gl.DRAW_FRAMEBUFFER, framebuffer);
gl.framebufferTexture2D(
gl.DRAW_FRAMEBUFFER,
gl.COLOR_ATTACHMENT0,
gl.TEXTURE_2D,
texture,
0,
);
const complete =
gl.checkFramebufferStatus(gl.DRAW_FRAMEBUFFER) ===
gl.FRAMEBUFFER_COMPLETE;
gl.bindFramebuffer(gl.DRAW_FRAMEBUFFER, previousDraw);
if (!complete) {
// Leave nothing half-made behind, so a later retry starts from scratch.
gl.deleteProgram(program);
gl.deleteVertexArray(vertexArray);
gl.deleteBuffer(buffer);
gl.deleteFramebuffer(framebuffer);
gl.deleteTexture(texture);
return false;
}
this._resources = {
program,
vertexArray,
buffer,
texture,
framebuffer,
depth: [0, 1, 2, 3].map((i) => uniform(`u_depth${i}`)),
count: uniform('u_count'),
logDepth: uniform('u_logDepth'),
near: uniform('u_near'),
far: uniform('u_far'),
};
return true;
}
/**
* Draw one query per queued contact, preceded by a control point that must
* always draw. The renderer caches the framebuffer, viewport and scissor
* state it last set, so those are put back exactly as found, along with
* every binding touched here. Depth, stencil, blending and the colour mask
* need no care: the target has no depth or stencil attachment, and a query
* counts samples whether or not they are written.
*/
_draw(source) {
const gl = source.gl;
const resources = this._resources;
const contacts = this._queued.slice();
const count = contacts.length + 1;
const attributes = this._attributes;
// The control point: mid-frame, with a threshold nothing can be under.
attributes[0] = 0.5;
attributes[1] = 0.5;
attributes[2] = -1;
const layers = source.textures.length;
const frustums = source.frustums;
const previousProgram = gl.getParameter(gl.CURRENT_PROGRAM);
const previousArray = gl.getParameter(gl.VERTEX_ARRAY_BINDING);
const previousBuffer = gl.getParameter(gl.ARRAY_BUFFER_BINDING);
const previousDraw = gl.getParameter(gl.DRAW_FRAMEBUFFER_BINDING);
const previousUnit = gl.getParameter(gl.ACTIVE_TEXTURE);
const previousViewport = gl.getParameter(gl.VIEWPORT);
const previousTextures = [];
const scissor = gl.isEnabled(gl.SCISSOR_TEST);
const queries = [];
const pool = this._queryPool;
let open = false;
try {
for (let i = 0; i < layers; i++) {
gl.activeTexture(gl.TEXTURE0 + i);
previousTextures.push(gl.getParameter(gl.TEXTURE_BINDING_2D));
gl.bindTexture(gl.TEXTURE_2D, source.textures[i]);
}
if (scissor) gl.disable(gl.SCISSOR_TEST);
gl.bindFramebuffer(gl.DRAW_FRAMEBUFFER, resources.framebuffer);
gl.viewport(0, 0, 1, 1);
gl.useProgram(resources.program);
// Samplers past the ranges in use point at the first range's texture:
// every sampler a program declares must be drawable, read or not.
for (let i = 0; i < PROBE_MAX_FRUSTUMS; i++)
gl.uniform1i(resources.depth[i], i < layers ? i : 0);
gl.uniform1i(resources.count, layers);
gl.uniform1i(resources.logDepth, source.logDepth ? 1 : 0);
gl.uniform4f(
resources.near,
frustums[0].near,
frustums[1]?.near ?? 1,
frustums[2]?.near ?? 1,
frustums[3]?.near ?? 1,
);
gl.uniform4f(
resources.far,
frustums[0].far,
frustums[1]?.far ?? 2,
frustums[2]?.far ?? 2,
frustums[3]?.far ?? 2,
);
gl.bindVertexArray(resources.vertexArray);
gl.bindBuffer(gl.ARRAY_BUFFER, resources.buffer);
gl.bufferData(
gl.ARRAY_BUFFER,
attributes.subarray(0, count * 3),
gl.STREAM_DRAW,
);
for (let i = 0; i < count; i++) {
const query = pool.pop() || gl.createQuery();
queries.push(query);
gl.beginQuery(gl.ANY_SAMPLES_PASSED_CONSERVATIVE, query);
open = true;
gl.drawArrays(gl.POINTS, i, 1);
gl.endQuery(gl.ANY_SAMPLES_PASSED_CONSERVATIVE);
open = false;
}
} catch (error) {
// Leave no query open and none unaccounted for; the caller stands down.
try {
if (open) gl.endQuery(gl.ANY_SAMPLES_PASSED_CONSERVATIVE);
for (const query of queries) gl.deleteQuery(query);
} catch {
// Nothing more can be done for them.
}
throw error;
} finally {
gl.bindBuffer(gl.ARRAY_BUFFER, previousBuffer);
gl.bindVertexArray(previousArray);
gl.useProgram(previousProgram);
gl.bindFramebuffer(gl.DRAW_FRAMEBUFFER, previousDraw);
if (previousViewport)
gl.viewport(
previousViewport[0],
previousViewport[1],
previousViewport[2],
previousViewport[3],
);
if (scissor) gl.enable(gl.SCISSOR_TEST);
for (let i = previousTextures.length - 1; i >= 0; i--) {
gl.activeTexture(gl.TEXTURE0 + i);
gl.bindTexture(gl.TEXTURE_2D, previousTextures[i]);
}
gl.activeTexture(previousUnit);
}
this._batches.push({
queries,
contacts,
at: this._now,
frame: this._frame,
cursor: 0,
control: false,
});
}
/**
* Take in whatever answers have arrived, oldest batch first, without
* waiting for any that have not. An answer is dated to the frame its test
* was drawn on, so one that arrives late (the overlay was not painting for
* a while) is as stale as it is old.
*/
_collect() {
const batches = this._batches;
if (batches.length === 0) return;
const gl = this._gl;
try {
if (gl.isContextLost?.()) {
// Queries made on a lost context are gone with it.
this.reset();
this._queryPool.length = 0;
this._resources = null;
return;
}
while (batches.length > 0) {
const batch = batches[0];
const { queries, contacts } = batch;
while (batch.cursor < queries.length) {
const query = queries[batch.cursor];
if (!gl.getQueryParameter(query, gl.QUERY_RESULT_AVAILABLE)) break;
const drew = !!gl.getQueryParameter(query, gl.QUERY_RESULT);
if (batch.cursor === 0) {
batch.control = drew;
} else {
const contact = contacts[batch.cursor - 1];
contact.pending = false;
// Without the control point's yes the batch means nothing: not a
// "hidden", and not a first answer that ends a new contact's
// hold-back either.
if (batch.control) {
contact.answered = true;
if (!drew && batch.at > contact.lastHiddenAt)
contact.lastHiddenAt = batch.at;
}
}
this._queryPool.push(query);
batch.cursor++;
}
if (batch.cursor < queries.length) break;
batches.shift();
if (batch.control) {
this._controlFailures = 0;
} else if (++this._controlFailures >= PROBE_MAX_CONTROL_FAILURES) {
this._fail();
}
}
// Whatever is still unanswered after too many frames is dropped,
// wherever it stands in the queue, so its contacts can be tested again.
const overdue = this._frame - PROBE_MAX_PENDING_FRAMES;
for (let i = batches.length - 1; i >= 0; i--) {
const batch = batches[i];
if (batch.frame >= overdue) continue;
for (let k = batch.cursor; k < batch.queries.length; k++)
gl.deleteQuery(batch.queries[k]);
for (
let k = Math.max(0, batch.cursor - 1);
k < batch.contacts.length;
k++
)
batch.contacts[k].pending = false;
batches.splice(i, 1);
}
} catch {
for (const batch of batches) this._release(batch.contacts);
batches.length = 0;
this._fail();
}
}
/**
* No queries (WebGL 1): read each depth range at full size and wait for it.
* Costs milliseconds per read; used only where nothing better exists.
*/
_readSync(source) {
const gl = source.gl;
const { width, height } = source;
const layers = source.framebuffers.length;
const layerBytes = width * height * 4;
const byteLength = layerBytes * layers;
const bytes =
this._snapshot?.bytes.length === byteLength
? this._snapshot.bytes
: new Uint8Array(byteLength);
const previous = gl.getParameter(gl.FRAMEBUFFER_BINDING);
for (let i = 0; i < layers; i++) {
gl.bindFramebuffer(gl.FRAMEBUFFER, source.framebuffers[i]);
gl.readPixels(
0,
0,
width,
height,
gl.RGBA,
gl.UNSIGNED_BYTE,
bytes.subarray(i * layerBytes, (i + 1) * layerBytes),
);
}
gl.bindFramebuffer(gl.FRAMEBUFFER, previous);
return new DepthSnapshot({
width,
height,
bytes,
frustums: source.frustums,
logDepth: source.logDepth,
// The source's matrix is a scratch array the next frame overwrites.
view: Float64Array.from(source.view),
tanHalfFovX: source.tanHalfFovX,
tanHalfFovY: source.tanHalfFovY,
});
}
}
/**
* A probe bound to `viewer`'s scene: what the application's detection
* overlay is handed (the `createOcclusionProbe` application hook). Its
* `beginFrame(now)` reads the scene itself; the rest is the probe's.
* @param {Cesium.Viewer} viewer
* @returns {object}
*/
export function createViewerOcclusionProbe(viewer) {
const probe = new SceneOcclusionProbe();
return {
get mode() {
return probe.mode;
},
get maxPerFrame() {
return probe.maxPerFrame;
},
get lastFrameMs() {
return probe.lastFrameMs;
},
get lastFrameTests() {
return probe.lastFrameTests;
},
beginFrame(now) {
probe.beginFrame(viewer.isDestroyed?.() ? null : viewer.scene, now);
},
add: (contact, position) => probe.add(contact, position),
endFrame: () => probe.endFrame(),
reset: () => probe.reset(),
destroy: () => probe.destroy(),
};
}
@@ -0,0 +1,688 @@
import test from 'node:test';
import assert from 'node:assert/strict';
import * as Cesium from 'cesium';
import {
PROBE_MAX_CONTROL_FAILURES,
PROBE_MAX_FRUSTUMS,
PROBE_MAX_PENDING_FRAMES,
PROBE_MAX_PER_FRAME,
PROBE_RETRY_AFTER_MS,
PROBE_VERTEX_SHADER,
SYNC_READ_INTERVAL_MS,
SceneOcclusionProbe,
readSceneDepthSource,
} from './sceneOcclusionProbe.js';
import {
createFakeDepthScene,
createFakeGl,
depthImage,
viewDistanceToDepth,
} from './fixtures/fakeDepthScene.mjs';
const NEAR = 1;
const FAR = 100_000;
/** Left half a wall 400 m away, right half ground 500 m away. */
function wallImage(width, height, logDepth = true, wall = 400) {
return depthImage(width, height, (column) =>
viewDistanceToDepth(column < width / 2 ? wall : 500, NEAR, FAR, logDepth),
);
}
function wallScene({ width = 64, height = 32, logDepth = true, gl } = {}) {
return createFakeDepthScene({
gl,
logDepth,
aspectRatio: width / height,
ranges: [
{ near: NEAR, far: FAR, image: wallImage(width, height, logDepth) },
],
});
}
const behindWall = { x: -250, y: 0, z: -500 };
const onStreet = { x: 250, y: 0, z: -500 };
const contact = () => ({
lastHiddenAt: Number.NEGATIVE_INFINITY,
pending: false,
});
/** One frame: collect, queue the given contacts, draw. */
function frame(probe, scene, now, tests = []) {
probe.beginFrame(scene, now);
const accepted = tests.map(([entry, position]) => probe.add(entry, position));
probe.endFrame();
return accepted;
}
test('a test is drawn at once and answered on a later frame, without anything being read back', () => {
const scene = wallScene();
const gl = scene.context._gl;
const probe = new SceneOcclusionProbe();
const hidden = contact();
const shown = contact();
assert.equal(probe.mode, 'off');
assert.deepEqual(
frame(probe, scene, 1000, [
[hidden, behindWall],
[shown, onStreet],
]),
[true, true],
);
assert.equal(probe.mode, 'async');
assert.equal(probe.lastFrameTests, 2);
assert.equal(hidden.pending, true);
assert.equal(
gl.counts.queries,
3,
'the control point and one query per contact',
);
assert.equal(gl.counts.draws, 3);
// Frames pass before the GPU has answered: nothing changes, nothing waits.
frame(probe, scene, 1016);
frame(probe, scene, 1032);
assert.equal(hidden.pending, true);
assert.equal(hidden.lastHiddenAt, Number.NEGATIVE_INFINITY);
assert.equal(gl.counts.resultReads, 0);
assert.equal(gl.counts.readPixels, 0);
gl.finishGpu();
frame(probe, scene, 1048);
assert.equal(hidden.pending, false);
assert.equal(shown.pending, false);
assert.equal(hidden.answered, true);
assert.equal(shown.answered, true);
assert.equal(hidden.lastHiddenAt, 1000, 'dated to its test frame');
assert.equal(shown.lastHiddenAt, Number.NEGATIVE_INFINITY);
assert.equal(gl.counts.readPixels, 0, 'depth never leaves the GPU');
});
test('queries are reused, and every depth range is tested nearest first', () => {
const width = 64;
const height = 32;
const farNear = 900;
const farFar = 5_000_000;
const scene = createFakeDepthScene({
aspectRatio: 2,
ranges: [
// Near range: the wall on the left, nothing drawn on the right.
{
near: NEAR,
far: 1000,
image: depthImage(width, height, (column) =>
column < width / 2 ? viewDistanceToDepth(400, NEAR, 1000, true) : 1,
),
},
// Far range: ground 20 km away, drawn with its near plane pulled in.
{
near: farNear,
far: farFar,
image: depthImage(width, height, () =>
viewDistanceToDepth(20_000, farNear * 0.9999, farFar, true),
),
},
],
});
const gl = scene.context._gl;
const probe = new SceneOcclusionProbe();
const cases = [
[contact(), { x: -7500, y: 0, z: -15_000 }, true], // behind the near wall
[contact(), { x: 7500, y: 0, z: -15_000 }, false], // above the far ground
[contact(), { x: 15_000, y: 0, z: -30_000 }, true], // under the far ground
[contact(), { x: -150, y: 0, z: -300 }, false], // in front of the wall
];
for (let round = 0; round < 3; round++) {
frame(
probe,
scene,
round * 100,
cases.map(([entry, position]) => [entry, position]),
);
gl.finishGpu();
frame(probe, scene, round * 100 + 16);
for (const [entry, , hidden] of cases) {
assert.equal(entry.pending, false);
assert.equal(entry.lastHiddenAt === round * 100, hidden);
}
}
assert.equal(gl.liveQueries.size, 5, 'five queries serve every round');
const source = readSceneDepthSource(scene);
assert.equal(source.frustums[1].near, farNear * 0.9999);
});
test('standard depth scenes are tested too', () => {
const scene = wallScene({ logDepth: false });
const probe = new SceneOcclusionProbe();
const hidden = contact();
const shown = contact();
frame(probe, scene, 0, [
[hidden, behindWall],
[shown, onStreet],
]);
scene.context._gl.finishGpu();
frame(probe, scene, 16);
assert.equal(hidden.lastHiddenAt, 0);
assert.equal(shown.lastHiddenAt, Number.NEGATIVE_INFINITY);
});
test('every binding the renderer relies on is left as found', () => {
const scene = wallScene();
const gl = scene.context._gl;
const found = {
read: { image: null },
draw: { image: null },
units: [{}, {}, {}, {}, {}, {}, {}, {}],
unit: 5,
array: {},
vertexArray: {},
program: { uniforms: {} },
scissor: true,
viewport: [12, 34, 640, 480],
};
Object.assign(gl.state, found, { units: [...found.units] });
const probe = new SceneOcclusionProbe();
const hidden = contact();
frame(probe, scene, 0, [[hidden, behindWall]]);
for (const key of [
'read',
'draw',
'unit',
'array',
'vertexArray',
'program',
'scissor',
])
assert.equal(gl.state[key], found[key], key);
assert.deepEqual(gl.state.units, found.units);
assert.deepEqual(gl.state.viewport, [12, 34, 640, 480]);
// The scissor test and the offset viewport would both have kept the points
// off the target, so neither was in force for them: the control point drew,
// and the answer counts.
gl.finishGpu();
frame(probe, scene, 16);
assert.equal(hidden.lastHiddenAt, 0);
assert.equal(gl.state.scissor, true);
});
test('a contact outside the frame, or past the frame budget, is not taken', () => {
const scene = wallScene();
const probe = new SceneOcclusionProbe();
probe.beginFrame(scene, 0);
const outside = contact();
assert.equal(probe.add(outside, { x: -1100, y: 0, z: -500 }), false);
assert.equal(probe.add(outside, { x: 0, y: 0, z: 500 }), false);
assert.equal(outside.pending, false);
const taken = [];
for (let i = 0; i < PROBE_MAX_PER_FRAME + 10; i++)
taken.push(probe.add(contact(), onStreet));
probe.endFrame();
assert.equal(taken.filter(Boolean).length, PROBE_MAX_PER_FRAME);
assert.equal(taken.lastIndexOf(true), PROBE_MAX_PER_FRAME - 1);
assert.equal(scene.context._gl.counts.queries, PROBE_MAX_PER_FRAME + 1);
});
test('a frame with nothing to test touches nothing', () => {
let reads = 0;
const probe = new SceneOcclusionProbe({
readSource: () => {
reads++;
return null;
},
});
frame(probe, {}, 0);
frame(probe, {}, 16);
assert.equal(reads, 0);
assert.equal(probe.lastFrameTests, 0);
});
test('no depth source: nothing is tested and nothing is in flight', () => {
const broken = [
null,
{},
{ ...wallScene(), mode: Cesium.SceneMode.SCENE2D },
{ ...wallScene(), mode: Cesium.SceneMode.COLUMBUS_VIEW },
{ ...wallScene(), useDepthPicking: false },
{ ...wallScene(), _environmentState: { useGlobeDepthFramebuffer: false } },
{ ...wallScene(), view: { frustumCommandsList: [], pickDepths: [] } },
{ ...wallScene(), view: undefined },
(() => {
const scene = wallScene();
scene.context.depthTexture = false;
return scene;
})(),
(() => {
const scene = wallScene();
scene.camera.frustum = { width: 1000, aspectRatio: 2 }; // orthographic
return scene;
})(),
(() => {
const scene = wallScene();
scene.camera.frustum.xOffset = 10;
return scene;
})(),
(() => {
const scene = wallScene();
scene.view.pickDepths[0].framebuffer = undefined; // not drawn yet
return scene;
})(),
// Whether depth is logarithmic, unknown: decoding it the wrong way would
// put every surface in front of every contact.
{ ...wallScene(), frameState: {} },
{ ...wallScene(), frameState: { useLogDepth: 1 } },
{ ...wallScene(), frameState: undefined },
(() => {
const scene = wallScene();
Object.defineProperty(scene, 'view', {
get() {
throw new Error('renderer changed shape');
},
});
return scene;
})(),
];
for (const scene of broken) {
assert.equal(readSceneDepthSource(scene), null);
const probe = new SceneOcclusionProbe();
const entry = contact();
assert.deepEqual(frame(probe, scene, 0, [[entry, behindWall]]), [false]);
assert.equal(probe.mode, 'off');
assert.equal(entry.pending, false);
}
});
test('depth that comes and goes is picked up frame by frame', () => {
const scene = wallScene();
const gl = scene.context._gl;
const probe = new SceneOcclusionProbe();
const entry = contact();
scene.useDepthPicking = false;
assert.deepEqual(frame(probe, scene, 0, [[entry, behindWall]]), [false]);
assert.equal(probe.mode, 'off');
scene.useDepthPicking = true;
assert.deepEqual(frame(probe, scene, 16, [[entry, behindWall]]), [true]);
assert.equal(probe.mode, 'async');
gl.finishGpu();
frame(probe, scene, 32);
assert.equal(entry.lastHiddenAt, 16);
});
test('depth ranges past the limit are left out, nearest kept', () => {
const image = wallImage(8, 8);
const ranges = [];
for (let i = 0; i < PROBE_MAX_FRUSTUMS + 2; i++)
ranges.push({ near: 10 ** i, far: 10 ** (i + 1), image });
const source = readSceneDepthSource(createFakeDepthScene({ ranges }));
assert.equal(source.frustums.length, PROBE_MAX_FRUSTUMS);
assert.equal(source.textures.length, PROBE_MAX_FRUSTUMS);
assert.equal(source.frustums[0].near, 1);
});
test('a control point that does not draw voids its batch; a run of them stands the probe down for a while', () => {
const scene = wallScene();
const gl = scene.context._gl;
const probe = new SceneOcclusionProbe();
// Something outside the probe's reach stops every point from drawing, so
// every query reads "nothing drew", which would otherwise mean "hidden".
gl.state.drawsLand = false;
let now = 0;
for (let i = 0; i < PROBE_MAX_CONTROL_FAILURES; i++) {
const entry = contact();
assert.deepEqual(frame(probe, scene, now, [[entry, behindWall]]), [true]);
gl.finishGpu();
now += 16;
frame(probe, scene, now);
assert.equal(entry.pending, false);
assert.equal(entry.lastHiddenAt, Number.NEGATIVE_INFINITY, 'not believed');
assert.notEqual(entry.answered, true, 'and not a first answer either');
now += 16;
}
assert.equal(probe.mode, 'off');
const stoodDownAt = now - 16;
assert.deepEqual(frame(probe, scene, now, [[contact(), behindWall]]), [
false,
]);
assert.deepEqual(
frame(probe, scene, stoodDownAt + PROBE_RETRY_AFTER_MS - 1, [
[contact(), behindWall],
]),
[false],
);
// The cause has passed: the probe picks up where it left off.
gl.state.drawsLand = true;
const entry = contact();
const retryAt = stoodDownAt + PROBE_RETRY_AFTER_MS;
assert.deepEqual(frame(probe, scene, retryAt, [[entry, behindWall]]), [true]);
assert.equal(probe.mode, 'async');
gl.finishGpu();
frame(probe, scene, retryAt + 16);
assert.equal(entry.lastHiddenAt, retryAt);
assert.equal(entry.answered, true);
// One good batch in between resets the count.
const healthy = new SceneOcclusionProbe();
const other = wallScene();
for (let i = 0; i < 6; i++) {
other.context._gl.state.drawsLand = i % 2 === 1;
frame(healthy, other, i * 32, [[contact(), onStreet]]);
other.context._gl.finishGpu();
frame(healthy, other, i * 32 + 16);
}
assert.equal(healthy.mode, 'async');
});
test('a shader that does not compile, or a WebGL call that throws, stands the probe down cleanly', () => {
let scene = wallScene();
// Only the fragment shader fails: the vertex shader that did compile must
// not be left behind.
scene.context._gl.state.compiles = (type) =>
type !== scene.context._gl.FRAGMENT_SHADER;
let probe = new SceneOcclusionProbe();
let entry = contact();
assert.deepEqual(frame(probe, scene, 0, [[entry, behindWall]]), [false]);
assert.equal(probe.mode, 'off');
assert.equal(entry.pending, false);
// Nothing half-made is kept, and the same context is never asked again:
// compiling is a wait on the GPU process and would fail the same way.
let gl = scene.context._gl;
assert.equal(gl.liveShaders.size, 0, 'no shader left behind');
let shaderCalls = 0;
const createShader = gl.createShader;
gl.createShader = (...args) => {
shaderCalls++;
return createShader(...args);
};
for (const now of [PROBE_RETRY_AFTER_MS + 16, 5 * PROBE_RETRY_AFTER_MS])
assert.deepEqual(frame(probe, scene, now, [[entry, behindWall]]), [false]);
assert.equal(shaderCalls, 0);
assert.equal(probe.mode, 'off');
// A draw that throws part-way: bindings restored, no query left behind.
scene = wallScene();
gl = scene.context._gl;
const found = {
draw: { image: null },
program: { uniforms: {} },
viewport: [0, 0, 800, 600],
};
Object.assign(gl.state, found, { scissor: true });
let draws = 0;
const drawArrays = gl.drawArrays;
gl.drawArrays = (...args) => {
if (++draws === 2) throw new Error('driver');
return drawArrays(...args);
};
probe = new SceneOcclusionProbe();
entry = contact();
const other = contact();
assert.deepEqual(
frame(probe, scene, 0, [
[entry, behindWall],
[other, onStreet],
]),
[true, true],
);
assert.equal(entry.pending, false, 'released when the draw failed');
assert.equal(other.pending, false);
assert.equal(probe.mode, 'off');
assert.equal(gl.state.draw, found.draw);
assert.equal(gl.state.program, found.program);
assert.deepEqual(gl.state.viewport, found.viewport);
assert.equal(gl.state.scissor, true);
assert.equal(gl.liveQueries.size, 0);
assert.deepEqual(frame(probe, scene, 16, [[entry, behindWall]]), [false]);
scene = wallScene();
gl = scene.context._gl;
probe = new SceneOcclusionProbe();
entry = contact();
frame(probe, scene, 0, [[entry, behindWall]]);
gl.getQueryParameter = () => {
throw new Error('driver');
};
frame(probe, scene, 16);
assert.equal(entry.pending, false);
assert.equal(probe.mode, 'off');
});
test('a frame that never reaches its end leaves no contact waiting for an answer', () => {
const scene = wallScene();
const probe = new SceneOcclusionProbe();
const entry = contact();
probe.beginFrame(scene, 0);
assert.equal(probe.add(entry, behindWall), true);
assert.equal(entry.pending, true);
// The painter threw before endFrame; the next frame starts clean.
probe.beginFrame(scene, 16);
assert.equal(entry.pending, false);
assert.equal(probe.add(entry, behindWall), true);
probe.endFrame();
assert.equal(
scene.context._gl.counts.queries,
2,
'only the second frame drew',
);
});
test('an answer collected late is dated to its test, not to its arrival', () => {
const scene = wallScene();
const gl = scene.context._gl;
const probe = new SceneOcclusionProbe();
const entry = contact();
frame(probe, scene, 1000, [[entry, behindWall]]);
gl.finishGpu();
// The overlay paints nothing for 20 seconds, then resumes.
frame(probe, scene, 21_000);
assert.equal(entry.pending, false);
assert.equal(entry.lastHiddenAt, 1000);
// An older answer never overwrites a newer one.
entry.lastHiddenAt = 30_000;
frame(probe, scene, 22_000, [[entry, behindWall]]);
gl.finishGpu();
frame(probe, scene, 22_016);
assert.equal(entry.lastHiddenAt, 30_000);
});
test('samplers for depth ranges not in use point at a texture that is bound', () => {
const scene = wallScene();
const gl = scene.context._gl;
// Whatever the renderer left on the other units is not the probe's to read.
gl.state.units = [null, null, null, null, null, null, null, null];
const probe = new SceneOcclusionProbe();
const entry = contact();
frame(probe, scene, 0, [[entry, behindWall]]);
gl.finishGpu();
frame(probe, scene, 16);
assert.equal(
entry.lastHiddenAt,
0,
'the draw was valid, so the answer counts',
);
assert.deepEqual(gl.state.units, [
null,
null,
null,
null,
null,
null,
null,
null,
]);
});
test('reset drops tests in flight but keeps the GPU objects for next time', () => {
const scene = wallScene();
const gl = scene.context._gl;
const probe = new SceneOcclusionProbe();
const entry = contact();
frame(probe, scene, 0, [[entry, behindWall]]);
probe.reset();
assert.equal(entry.pending, false);
assert.equal(probe.mode, 'off');
assert.equal(gl.counts.deleted, 0);
gl.finishGpu();
frame(probe, scene, 16);
assert.equal(
entry.lastHiddenAt,
Number.NEGATIVE_INFINITY,
'the dropped answer is not applied',
);
frame(probe, scene, 32, [[entry, behindWall]]);
assert.equal(probe.mode, 'async');
assert.equal(gl.liveQueries.size, 2, 'queries are reused, not recreated');
});
test('a lost context drops what was in flight and starts over when it returns', () => {
const scene = wallScene();
const gl = scene.context._gl;
const probe = new SceneOcclusionProbe();
const entry = contact();
frame(probe, scene, 0, [[entry, behindWall]]);
gl.state.lost = true;
assert.deepEqual(frame(probe, scene, 16, [[contact(), behindWall]]), [false]);
assert.equal(entry.pending, false);
assert.equal(probe.mode, 'off');
gl.state.lost = false;
assert.deepEqual(frame(probe, scene, 32, [[entry, behindWall]]), [true]);
gl.finishGpu();
frame(probe, scene, 48);
assert.equal(entry.lastHiddenAt, 32);
});
test('queries that are never answered are abandoned', () => {
const scene = wallScene();
const gl = scene.context._gl;
const probe = new SceneOcclusionProbe();
const entry = contact();
frame(probe, scene, 0, [[entry, behindWall]]);
for (let i = 1; i <= PROBE_MAX_PENDING_FRAMES; i++)
frame(probe, scene, i * 16);
assert.equal(entry.pending, true);
frame(probe, scene, (PROBE_MAX_PENDING_FRAMES + 1) * 16);
assert.equal(entry.pending, false);
assert.equal(entry.lastHiddenAt, Number.NEGATIVE_INFINITY);
assert.equal(gl.liveQueries.size, 0);
assert.equal(probe.mode, 'async', 'and the next contact is tested as usual');
});
test('every batch times out on its own, however many are queued ahead of it', () => {
const scene = wallScene();
const gl = scene.context._gl;
const probe = new SceneOcclusionProbe();
const entries = [];
// Ten frames each start a batch; the GPU answers none of them.
for (let i = 0; i < 10; i++) {
const entry = contact();
entries.push(entry);
frame(probe, scene, i * 16, [[entry, behindWall]]);
}
for (let i = 10; i <= PROBE_MAX_PENDING_FRAMES; i++)
frame(probe, scene, i * 16);
assert.ok(entries.every((entry) => entry.pending));
// Ten more frames and all ten have been dropped, not one every 120 frames.
for (let i = 1; i <= 10; i++)
frame(probe, scene, (PROBE_MAX_PENDING_FRAMES + i) * 16);
assert.ok(entries.every((entry) => !entry.pending));
assert.equal(gl.liveQueries.size, 0);
});
test('a target that cannot be made leaves nothing behind, and the next try starts from scratch', () => {
const scene = wallScene();
const gl = scene.context._gl;
const complete = gl.checkFramebufferStatus;
gl.checkFramebufferStatus = () => 0;
const probe = new SceneOcclusionProbe();
const entry = contact();
assert.deepEqual(frame(probe, scene, 0, [[entry, behindWall]]), [false]);
assert.equal(probe.mode, 'off');
assert.equal(gl.counts.deleted, 5, 'program, array, buffer, target');
// Memory pressure passes; after the stand-down the probe builds it all again.
gl.checkFramebufferStatus = complete;
assert.deepEqual(
frame(probe, scene, PROBE_RETRY_AFTER_MS, [[entry, behindWall]]),
[true],
);
assert.equal(probe.mode, 'async');
gl.finishGpu();
frame(probe, scene, PROBE_RETRY_AFTER_MS + 16);
assert.equal(entry.lastHiddenAt, PROBE_RETRY_AFTER_MS);
});
test('a new WebGL context, or destroy, releases everything', () => {
const probe = new SceneOcclusionProbe();
const first = wallScene();
const entry = contact();
frame(probe, first, 0, [[entry, behindWall]]);
const second = wallScene();
const again = contact();
assert.deepEqual(frame(probe, second, 16, [[again, behindWall]]), [true]);
assert.equal(entry.pending, false, 'the first context will never answer');
assert.equal(first.context._gl.liveQueries.size, 0);
assert.equal(
first.context._gl.counts.deleted,
5,
'program, array, buffer, target',
);
probe.destroy();
assert.equal(again.pending, false);
assert.equal(second.context._gl.liveQueries.size, 0);
assert.equal(probe.mode, 'off');
});
test('without queries (WebGL 1) depth is read back synchronously, at most every interval, and the mode says so', () => {
const gl = createFakeGl({ webgl2: false });
const scene = wallScene({ gl });
assert.equal(scene.context.webgl2, false);
const sceneFramebuffer = { image: null };
gl.state.read = sceneFramebuffer;
gl.state.draw = sceneFramebuffer;
const probe = new SceneOcclusionProbe();
const hidden = contact();
const shown = contact();
assert.deepEqual(
frame(probe, scene, 1000, [
[hidden, behindWall],
[shown, onStreet],
[contact(), { x: -1100, y: 0, z: -500 }],
]),
[true, true, false],
);
assert.equal(probe.mode, 'sync');
assert.equal(gl.counts.readPixels, 1);
assert.equal(gl.state.read, sceneFramebuffer);
assert.equal(gl.state.draw, sceneFramebuffer);
assert.equal(hidden.lastHiddenAt, 1000, 'answered on the spot');
assert.equal(hidden.pending, false);
assert.equal(shown.answered, true);
assert.equal(shown.lastHiddenAt, Number.NEGATIVE_INFINITY);
// Frames inside the interval answer from the read already made.
frame(probe, scene, 1000 + SYNC_READ_INTERVAL_MS - 1, [[hidden, behindWall]]);
assert.equal(gl.counts.readPixels, 1);
assert.equal(hidden.lastHiddenAt, 1000 + SYNC_READ_INTERVAL_MS - 1);
frame(probe, scene, 1000 + SYNC_READ_INTERVAL_MS, [[hidden, behindWall]]);
assert.equal(gl.counts.readPixels, 2);
});
test('the shader decodes depth the way the CPU decode does', () => {
// The fake context stands in for the shader, so pin the parts of the source
// the two must agree on: the unpack weights, both depth formulas, the
// nearest-range-first order and the comparison.
const source = PROBE_VERTEX_SHADER.replace(/\s+/g, ' ');
assert.match(
source,
/vec4\(1\.0, 1\.0 \/ 255\.0, 1\.0 \/ 65025\.0, 1\.0 \/ 16581375\.0\)/,
);
assert.match(source, /if \(depth <= 0\.0 \|\| depth >= 1\.0\) return -1\.0;/);
assert.match(
source,
/near \+ exp2\(depth \* log2\(far - near \+ 1\.0\)\) - 1\.0/,
);
assert.match(source, /near \* far \/ \(far - depth \* \(far - near\)\)/);
assert.match(
source,
/bool hidden = surface > 0\.0 && surface < a_contact\.z;/,
);
assert.ok(
source.indexOf('u_depth0, u_near.x') < source.indexOf('u_depth1, u_near.y'),
);
});