diff --git a/docs/RENDERER-CONTRACT.md b/docs/RENDERER-CONTRACT.md index 382b2c71a..54932663f 100644 --- a/docs/RENDERER-CONTRACT.md +++ b/docs/RENDERER-CONTRACT.md @@ -116,7 +116,11 @@ optional, so a renderer written before it still conforms: (`zoomOutGuard.js`). The application turns it on where a renderer has it. - `query.occlusionTest()` (capability `occlusionTest`) tests many points against the depth of the frames drawn without waiting for the GPU; the - detection overlay leaves out the street vehicles it finds hidden. + detection overlay leaves out the street vehicles it finds hidden. A WebGL + renderer that hands over its frame's depth gets one from + `@gods-eye-view/core/render/occlusion` (`createDepthOcclusionTest`, given a + `DepthSource`: depth packed into RGBA8 or a depth texture, standard or + logarithmic, with the view it was drawn from). - `RendererPlugin.applicationHooks(renderer)` hands the application what only some renderers have (`ApplicationHooks`); see [The application and its renderer](#the-application-and-its-renderer). @@ -243,8 +247,9 @@ on (no `renderer.id`, no engine type, no engine object's presence). stays framed (`camera.controls.keepEarthFramed`, which the scene turns on; Cesium's is `src/render/cesium/zoomOutGuard.js`); the detection overlay leaves out street vehicles something stands in front of through - `query.occlusionTest()` under the `occlusionTest` capability (Cesium's is - `src/render/cesium/sceneOcclusionProbe.js`; without it every such + `query.occlusionTest()` under the `occlusionTest` capability (the GPU + probe is `src/render/occlusion/depthProbe.js`, which Cesium's + `src/render/cesium/sceneOcclusionProbe.js` feeds; without it every such vehicle's bracket shows); and an inline panel whose host stops animation frames keeps drawing through `resize` and `frame.renderNow()` (`src/app/panelRendering.js`), stopping at a frame that throws. diff --git a/package.json b/package.json index e67c6972c..33b6d486a 100644 --- a/package.json +++ b/package.json @@ -308,6 +308,7 @@ "./geo": "./src/geo/index.js", "./render/contract": "./src/render/contract/index.js", "./render/stub": "./src/render/stub/index.js", + "./render/occlusion": "./src/render/occlusion/index.js", "./render/camera/events": "./src/render/camera/events.js", "./render/cesium/unbound": "./src/render/cesium/unbound.js", "./render/conformance": "./src/render/conformance/index.js", diff --git a/scripts/package-boundaries.json b/scripts/package-boundaries.json index 6e6e93068..c96416dc3 100644 --- a/scripts/package-boundaries.json +++ b/scripts/package-boundaries.json @@ -63,6 +63,7 @@ "src/geo/frustum.js", "src/render/cesium/zoomOutGuard.js", "src/render/cesium/sceneOcclusionProbe.js", + "src/render/occlusion/depthProbe.js", "src/data/detectionOcclusion.js" ], "external": ["cesium"] @@ -1107,6 +1108,7 @@ "src/geoDistance.js", "src/render/cesium/zoomOutGuard.js", "src/render/cesium/sceneOcclusionProbe.js", + "src/render/occlusion/depthProbe.js", "src/data/detectionOcclusion.js" ], "external": ["cesium"] @@ -1477,6 +1479,7 @@ "src/maps/engine.js", "src/render/cesium/zoomOutGuard.js", "src/render/cesium/sceneOcclusionProbe.js", + "src/render/occlusion/depthProbe.js", "src/data/detectionOcclusion.js" ], "external": ["cesium", "vue", "pinia", "vue-i18n"] @@ -1661,6 +1664,7 @@ "src/render/input/router.js", "src/render/cesium/zoomOutGuard.js", "src/render/cesium/sceneOcclusionProbe.js", + "src/render/occlusion/depthProbe.js", "src/data/detectionOcclusion.js" ], "external": ["cesium", "vue", "pinia", "vue-i18n"] @@ -1807,6 +1811,7 @@ "src/data/planespottersPhoto.js", "src/render/cesium/zoomOutGuard.js", "src/render/cesium/sceneOcclusionProbe.js", + "src/render/occlusion/depthProbe.js", "src/data/detectionOcclusion.js" ], "external": ["cesium"] @@ -1930,6 +1935,7 @@ "src/data/satelliteClassMask.js", "src/render/cesium/zoomOutGuard.js", "src/render/cesium/sceneOcclusionProbe.js", + "src/render/occlusion/depthProbe.js", "src/data/detectionOcclusion.js" ], "external": ["cesium"] @@ -2066,6 +2072,7 @@ "src/geoDistance.js", "src/render/cesium/zoomOutGuard.js", "src/render/cesium/sceneOcclusionProbe.js", + "src/render/occlusion/depthProbe.js", "src/data/detectionOcclusion.js" ], "external": ["cesium"] @@ -2147,6 +2154,7 @@ "src/render/cesium/viewers.js", "src/render/cesium/zoomOutGuard.js", "src/render/cesium/sceneOcclusionProbe.js", + "src/render/occlusion/depthProbe.js", "src/data/detectionOcclusion.js" ], "external": ["cesium"] @@ -2287,6 +2295,7 @@ "src/render/color.js", "src/render/cesium/zoomOutGuard.js", "src/render/cesium/sceneOcclusionProbe.js", + "src/render/occlusion/depthProbe.js", "src/data/detectionOcclusion.js" ], "external": ["cesium"] @@ -2388,6 +2397,7 @@ "src/data/retryableLoad.js", "src/render/cesium/zoomOutGuard.js", "src/render/cesium/sceneOcclusionProbe.js", + "src/render/occlusion/depthProbe.js", "src/data/detectionOcclusion.js" ], "external": ["cesium", "satellite.js"] @@ -2485,6 +2495,7 @@ "src/time/worldClock.js", "src/render/cesium/zoomOutGuard.js", "src/render/cesium/sceneOcclusionProbe.js", + "src/render/occlusion/depthProbe.js", "src/data/detectionOcclusion.js" ], "external": ["cesium"] @@ -2590,6 +2601,7 @@ "src/render/input/router.js", "src/render/cesium/zoomOutGuard.js", "src/render/cesium/sceneOcclusionProbe.js", + "src/render/occlusion/depthProbe.js", "src/data/detectionOcclusion.js" ], "external": ["cesium", "@mapbox/vector-tile", "pbf"] @@ -2780,6 +2792,7 @@ "src/render/cesium/viewers.js", "src/render/cesium/zoomOutGuard.js", "src/render/cesium/sceneOcclusionProbe.js", + "src/render/occlusion/depthProbe.js", "src/data/detectionOcclusion.js" ], "external": ["cesium", "pbf", "@mapbox/vector-tile"] @@ -2956,6 +2969,7 @@ "src/render/input/router.js", "src/render/cesium/zoomOutGuard.js", "src/render/cesium/sceneOcclusionProbe.js", + "src/render/occlusion/depthProbe.js", "src/data/detectionOcclusion.js" ], "external": ["hls.js", "cesium"] @@ -3077,6 +3091,7 @@ "src/time/worldClock.js", "src/render/cesium/zoomOutGuard.js", "src/render/cesium/sceneOcclusionProbe.js", + "src/render/occlusion/depthProbe.js", "src/data/detectionOcclusion.js" ], "external": ["cesium", "pbf", "@mapbox/vector-tile", "mapillary-js"] @@ -3157,6 +3172,7 @@ "src/queries/heights.js", "src/render/cesium/zoomOutGuard.js", "src/render/cesium/sceneOcclusionProbe.js", + "src/render/occlusion/depthProbe.js", "src/data/detectionOcclusion.js" ], "external": ["cesium", "@mapbox/vector-tile", "pbf"] @@ -3263,6 +3279,7 @@ "src/data/satelliteClassMask.js", "src/render/cesium/zoomOutGuard.js", "src/render/cesium/sceneOcclusionProbe.js", + "src/render/occlusion/depthProbe.js", "src/data/detectionOcclusion.js" ], "external": ["cesium"] @@ -3333,6 +3350,7 @@ "src/render/input/router.js", "src/render/cesium/zoomOutGuard.js", "src/render/cesium/sceneOcclusionProbe.js", + "src/render/occlusion/depthProbe.js", "src/data/detectionOcclusion.js" ], "external": ["cesium"] @@ -3460,6 +3478,7 @@ "src/render/cesium/viewers.js", "src/render/cesium/zoomOutGuard.js", "src/render/cesium/sceneOcclusionProbe.js", + "src/render/occlusion/depthProbe.js", "src/data/detectionOcclusion.js" ], "external": ["cesium"] @@ -3747,6 +3766,7 @@ "src/data/detectionPresentation.js", "src/data/detectionRenderDemand.js", "src/render/cesium/sceneOcclusionProbe.js", + "src/render/occlusion/depthProbe.js", "src/data/earthquakes.js", "src/data/fireAnchors.js", "src/data/firmsAdapt.js", @@ -5345,6 +5365,7 @@ "src/data/detectionPresentation.js", "src/data/detectionOcclusion.js", "src/render/cesium/sceneOcclusionProbe.js", + "src/render/occlusion/depthProbe.js", "src/data/modelEligibility.js", "src/app/layers/recentImagery.js", "src/layers/recentImagery/index.js", @@ -5667,6 +5688,7 @@ "src/render/cesium/viewers.js", "src/render/cesium/zoomOutGuard.js", "src/render/cesium/sceneOcclusionProbe.js", + "src/render/occlusion/depthProbe.js", "src/data/detectionOcclusion.js" ], "external": [ @@ -5768,6 +5790,7 @@ "src/data/entityRecords.js", "src/render/cesium/zoomOutGuard.js", "src/render/cesium/sceneOcclusionProbe.js", + "src/render/occlusion/depthProbe.js", "src/data/detectionOcclusion.js" ], "external": ["cesium"] @@ -6458,6 +6481,7 @@ "src/render/cesium/viewers.js", "src/render/cesium/zoomOutGuard.js", "src/render/cesium/sceneOcclusionProbe.js", + "src/render/occlusion/depthProbe.js", "src/data/detectionOcclusion.js" ], "external": ["cesium", "egm96-universal", "pbf"] @@ -6570,6 +6594,7 @@ "src/render/cesium/viewers.js", "src/render/cesium/zoomOutGuard.js", "src/render/cesium/sceneOcclusionProbe.js", + "src/render/occlusion/depthProbe.js", "src/data/detectionOcclusion.js" ], "external": ["cesium", "pbf"] @@ -6816,6 +6841,7 @@ "src/queries/heights.js", "src/render/cesium/zoomOutGuard.js", "src/render/cesium/sceneOcclusionProbe.js", + "src/render/occlusion/depthProbe.js", "src/data/detectionOcclusion.js" ], "external": ["cesium"] @@ -7165,12 +7191,16 @@ "exports": [ "./render/contract", "./render/stub", + "./render/occlusion", "./render/camera/events", "./render/conformance" ], "modules": [ "src/render/contract/index.js", "src/render/stub/index.js", + "src/render/occlusion/index.js", + "src/render/occlusion/depthProbe.js", + "src/data/detectionOcclusion.js", "src/render/color.js", "src/geo/polyline.js", "src/render/motion/iconMotion.js", diff --git a/src/data/detectionOcclusion.js b/src/data/detectionOcclusion.js index 138151699..25f212fdf 100644 --- a/src/data/detectionOcclusion.js +++ b/src/data/detectionOcclusion.js @@ -9,10 +9,10 @@ * The fix compares each such contact with what the renderer actually drew: if * the drawn surface along the contact's ray is nearer than the contact by more * than a small margin, something stands in front of it and its bracket and - * callout are not drawn. The renderer's occlusion probe (an application hook; - * the Cesium renderer's is `src/render/cesium/sceneOcclusionProbe.js`) runs - * that comparison on the GPU, against the frame's own depth, and hands back a yes or no per contact a - * frame or two later without ever waiting on the GPU. This file holds the + * callout are not drawn. The renderer's occlusion test (`query.occlusionTest`; + * the GPU probe is `src/render/occlusion/depthProbe.js`) runs that comparison + * on the GPU, against the frame's own depth, and hands back a yes or no per + * contact a frame or two later without ever waiting on the GPU. This file holds the * arithmetic both sides share and the per-contact memory of the answers. * * Only contacts that opt in with `depthTested: true` are tested: the ones whose @@ -120,9 +120,12 @@ export function unpackDepth(bytes, offset) { */ export function depthToViewDistance(depth, near, far, logDepth) { if (!(depth > 0) || !(depth < 1)) return Number.NaN; - if (!(near > 0) || !(far > near)) return Number.NaN; + if (!(near >= 0) || !(far > near)) return Number.NaN; if (logDepth) return near + Math.pow(2, depth * Math.log2(far - near + 1)) - 1; + // Standard depth needs a near plane in front of the eye; log depth does not + // (as WebGL log depth writes it, with none). + if (!(near > 0)) return Number.NaN; return (near * far) / (far - depth * (far - near)); } @@ -186,7 +189,7 @@ export function projectContact(view, tanHalfFovX, tanHalfFovY, position, out) { /** * One frame of depth read back to memory, with the camera it was drawn from. - * Only the synchronous fallback uses this (see `src/render/cesium/sceneOcclusionProbe.js`); the + * Only the synchronous fallback uses this (see `src/render/occlusion/depthProbe.js`); the * normal path never copies depth off the GPU. * * `bytes` holds `frustums.length` stacked images of `width` x `height` RGBA8 diff --git a/src/data/detectionOcclusion.test.mjs b/src/data/detectionOcclusion.test.mjs index 336602ea4..b5dcc1420 100644 --- a/src/data/detectionOcclusion.test.mjs +++ b/src/data/detectionOcclusion.test.mjs @@ -107,9 +107,19 @@ test('the ends of the depth range, and a bad range, mean nothing was drawn', () assert.ok(Number.isNaN(depthToViewDistance(0, 1, 100, log))); assert.ok(Number.isNaN(depthToViewDistance(1, 1, 100, log))); assert.ok(Number.isNaN(depthToViewDistance(Number.NaN, 1, 100, log))); - assert.ok(Number.isNaN(depthToViewDistance(0.5, 0, 100, log))); + assert.ok(Number.isNaN(depthToViewDistance(0.5, -1, 100, log))); assert.ok(Number.isNaN(depthToViewDistance(0.5, 100, 100, log))); } + // No near plane: standard depth has nothing to decode against. + assert.ok(Number.isNaN(depthToViewDistance(0.5, 0, 100, false))); +}); + +test('log depth with no near plane decodes as it is written with none', () => { + // Written as log2(1 + d) / log2(far + 1). + const depth = Math.log2(1 + 400) / Math.log2(100_000 + 1); + assert.ok( + Math.abs(depthToViewDistance(depth, 0, 100_000, true) - 400) < 1e-6, + ); }); const IDENTITY = [1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1]; diff --git a/src/render/cesium/fixtures/fakeDepthScene.mjs b/src/render/cesium/fixtures/fakeDepthScene.mjs index 4255fee53..f7956b1d0 100644 --- a/src/render/cesium/fixtures/fakeDepthScene.mjs +++ b/src/render/cesium/fixtures/fakeDepthScene.mjs @@ -1,7 +1,7 @@ /** - * 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. + * A stand-in scene and WebGL context for tests of the occlusion probe + * (`render/occlusion/depthProbe.js`): just the members it and + * `sceneOcclusionProbe.js` use, 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 @@ -29,6 +29,18 @@ export function packDepth(depth) { return bytes; } +/** + * A depth texture's image (the `'depth'` encoding) filled from a function of + * the texel, as `depthImage`. + */ +export function rawDepthImage(width, height, depthAt) { + const depth = new Float32Array(width * height); + for (let row = 0; row < height; row++) + for (let column = 0; column < width; column++) + depth[row * width + column] = depthAt(column, row); + return { width, height, depth }; +} + /** Inverse of `depthToViewDistance`. */ export function viewDistanceToDepth(distance, near, far, logDepth) { if (logDepth) @@ -272,8 +284,11 @@ export function createFakeGl({ webgl2 = true } = {}) { 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 texel = row * image.width + column; const distance = depthToViewDistance( - unpackDepth(image.data, (row * image.width + column) * 4), + uniforms.u_packed === 0 + ? image.depth[texel] + : unpackDepth(image.data, texel * 4), uniforms.u_near[i], uniforms.u_far[i], uniforms.u_logDepth === 1, diff --git a/src/render/cesium/sceneOcclusionProbe.js b/src/render/cesium/sceneOcclusionProbe.js index 4eaf22512..d210a7408 100644 --- a/src/render/cesium/sceneOcclusionProbe.js +++ b/src/render/cesium/sceneOcclusionProbe.js @@ -1,43 +1,17 @@ /** - * Asks the GPU, per contact, whether the scene drew something in front of it, - * without waiting for the answer. + * The Cesium scene's frame depth for the occlusion probe + * (`src/render/occlusion/depthProbe.js`): the query port's `occlusionTest` + * on Cesium. The scene already keeps the depth of the frame it has just drawn + * (for picking), packed four bytes to a texel, one texture per depth range. * - * 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. + * Every read of renderer internals is in `readSceneDepthSource` below. */ import * as Cesium from 'cesium'; import { - DepthSnapshot, - projectContact, -} from '../../data/detectionOcclusion.js'; + createDepthOcclusionTest, + DepthOcclusionProbe, + PROBE_MAX_FRUSTUMS, +} from '../occlusion/depthProbe.js'; import { rawFramebuffer, rawTexture, @@ -45,27 +19,15 @@ import { 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; +export { + 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, +} from '../occlusion/depthProbe.js'; /** * Everything this module takes from the renderer, in one place. @@ -181,626 +143,16 @@ export function readSceneDepthSource(scene, viewScratch) { } } -/** - * 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 { +/** The occlusion probe on a Cesium scene's depth (`readSceneDepthSource`). */ +export class SceneOcclusionProbe extends DepthOcclusionProbe { /** * @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, - }); + constructor({ now, readSource = readSceneDepthSource } = {}) { + super({ readSource, ...(now ? { now } : {}) }); } } @@ -812,26 +164,8 @@ export class SceneOcclusionProbe { * @returns {import('../contract/query').OcclusionTest} */ export function createSceneOcclusionTest(scene) { - 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(scene.isDestroyed?.() ? null : scene, now); - }, - add: (point, position) => probe.add(point, position), - endFrame: () => probe.endFrame(), - reset: () => probe.reset(), - destroy: () => probe.destroy(), - }; + return createDepthOcclusionTest({ + readSource: readSceneDepthSource, + target: () => (scene.isDestroyed?.() ? null : scene), + }); } diff --git a/src/render/occlusion/depthProbe.js b/src/render/occlusion/depthProbe.js new file mode 100644 index 000000000..ae044863e --- /dev/null +++ b/src/render/occlusion/depthProbe.js @@ -0,0 +1,747 @@ +/** + * @module render/occlusion + * @description Asks the GPU, per point, whether the frame just drawn has + * something in front of it, without waiting for the answer: the query port's + * `occlusionTest` on any WebGL renderer that can hand over its frame's depth. + * + * Reading depth back is what this avoids. One texel read waits a fraction of + * a millisecond to over a millisecond, so asking once per labelled contact + * turns a 2 ms frame into a 40 ms one; copying the whole depth image back is + * no better where it matters (Chromium answers `getBufferSubData` with a round + * trip to its GPU process even after a sync object has signalled: 1.5 ms on a + * quiet machine, 15 to 25 ms on a busy one). + * + * So nothing is read back at all. Each tested point becomes one point drawn + * into a private 1x1 target, inside an occlusion query. The vertex shader looks + * up the frame's depth at the point's pixel, decodes it, and throws the point + * away when the drawn surface is nearer than the point'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: `_collect` just looks. + * + * - `beginFrame(target, now)` collects the answers that have arrived. + * - `add(point, position)` queues a point for testing against this frame. + * - `endFrame()` draws the queued points. Answers land a frame or two later. + * + * The renderer supplies the frame's depth through `readSource` (a + * `DepthSource`): depth packed four bytes to an RGBA8 texel, or a depth + * texture. A WebGL 1 context has no queries; there packed depth is read back + * synchronously, at most every `SYNC_READ_INTERVAL_MS`, and answered on the + * CPU (`mode` reads `'sync'`). Without a source, `mode` reads `'off'`, nothing + * is tested and callers carry on as if no point were hidden. + */ +import { + DepthSnapshot, + projectContact, +} from '../../data/detectionOcclusion.js'; + +/** + * The depth of the frame just drawn, as a renderer hands it over. + * @typedef {{ + * gl: WebGLRenderingContext|WebGL2RenderingContext, webgl2: boolean, + * width: number, height: number, framebuffers: WebGLFramebuffer[], + * textures: WebGLTexture[], + * encoding?: 'packed' | 'depth', + * frustums: Array<{near: number, far: number}>, logDepth: boolean, + * view: Float64Array, tanHalfFovX: number, tanHalfFovY: number, + * }} DepthSource + * - `textures`: one per depth range, nearest first, all `width` x `height`. + * `encoding` `'packed'` (the default): RGBA8 holding window-space depth + * packed four bytes to a texel, and `framebuffers` the framebuffers they are + * attached to (the WebGL 1 fallback reads them). `'depth'`: depth textures, + * read on the GPU only. + * - `logDepth`: depth is `log2(1 + d - near) / log2(far - near + 1)` of the + * view distance `d`; otherwise standard perspective depth. + * - `view`: the view matrix in ECEF, column-major; `tanHalfFovX`/`Y` the + * frustum's half extents, with no offset. + */ + +/** + * 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; + +/** + * 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_packed; +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); + vec4 stored = texelFetch(depthTexture, texel, 0); + float depth = u_packed + ? dot(stored, vec4(1.0, 1.0 / 255.0, 1.0 / 65025.0, 1.0 / 16581375.0)) + : stored.r; + 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 DepthOcclusionProbe { + /** + * @param {{ + * readSource: (target: any, viewScratch: Float64Array) => DepthSource | null, + * now?: () => number, + * }} options `readSource` reads the depth of the frame just drawn from the + * target `beginFrame` is given, once a frame, when the first point asks. + */ + constructor({ readSource, now = () => performance.now() }) { + 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 frame + * has been drawn (a post-render listener), before `add`. + * @param {any} scene What `readSource` reads the depth from; null for none. + * @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 if (source.encoding === 'depth') { + // A depth texture is read on the GPU only. + this.mode = 'off'; + return; + } 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'), + packed: uniform('u_packed'), + 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.packed, source.encoding === 'depth' ? 0 : 1); + 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, + }); + } +} + +/** + * The query port's `occlusionTest()` over a renderer's frame depth: a probe + * whose `beginFrame(now)` reads `target()` (null once the renderer is gone); + * the rest is the probe's. + * @param {{ + * readSource: (target: any, viewScratch: Float64Array) => DepthSource | null, + * target: () => any, + * now?: () => number, + * }} options + * @returns {import('../contract/query').OcclusionTest} + */ +export function createDepthOcclusionTest({ readSource, target, now }) { + const probe = new DepthOcclusionProbe({ + readSource, + ...(now ? { now } : {}), + }); + return { + get mode() { + return probe.mode; + }, + get maxPerFrame() { + return probe.maxPerFrame; + }, + get lastFrameMs() { + return probe.lastFrameMs; + }, + get lastFrameTests() { + return probe.lastFrameTests; + }, + beginFrame(time) { + probe.beginFrame(target(), time); + }, + add: (point, position) => probe.add(point, position), + endFrame: () => probe.endFrame(), + reset: () => probe.reset(), + destroy: () => probe.destroy(), + }; +} diff --git a/src/render/occlusion/depthProbe.test.mjs b/src/render/occlusion/depthProbe.test.mjs new file mode 100644 index 000000000..e21cdf81c --- /dev/null +++ b/src/render/occlusion/depthProbe.test.mjs @@ -0,0 +1,95 @@ +import test from 'node:test'; +import assert from 'node:assert/strict'; +import { createDepthOcclusionTest } from './index.js'; +import { + createFakeGl, + rawDepthImage, + viewDistanceToDepth, +} from '../cesium/fixtures/fakeDepthScene.mjs'; + +const FAR = 100_000; +const WIDTH = 64; +const HEIGHT = 32; + +/** A depth texture of a frame drawn with three's log depth (near 0): left half a wall 400 m away, right half ground 500 m away. */ +function depthSource(gl, { webgl2 = true } = {}) { + const texture = gl.createTexture(); + texture.image = rawDepthImage(WIDTH, HEIGHT, (column) => + viewDistanceToDepth(column < WIDTH / 2 ? 400 : 500, 0, FAR, true), + ); + return { + gl, + webgl2, + width: WIDTH, + height: HEIGHT, + framebuffers: [], + textures: [texture], + encoding: 'depth', + frustums: [{ near: 0, far: FAR }], + logDepth: true, + // The eye at the origin looking down -z, y up. + view: Float64Array.from([1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1]), + tanHalfFovX: 1, + tanHalfFovY: 1, + }; +} + +const point = () => ({ + pending: false, + answered: false, + lastHiddenAt: Number.NEGATIVE_INFINITY, +}); + +test('a depth texture is read as depth: a point behind the wall is hidden, one on the street is not', () => { + const gl = createFakeGl(); + const source = depthSource(gl); + const set = {}; + const uniform1i = gl.uniform1i; + gl.uniform1i = (name, value) => { + set[name] = value; + uniform1i(name, value); + }; + const test = createDepthOcclusionTest({ + readSource: () => source, + target: () => ({}), + }); + const behindWall = point(); + const onStreet = point(); + test.beginFrame(10); + assert.equal(test.add(behindWall, { x: -250, y: 0, z: -500 }), true); + assert.equal(test.add(onStreet, { x: 250, y: 0, z: -500 }), true); + test.endFrame(); + assert.equal(test.mode, 'async'); + assert.equal(set.u_packed, 0, 'read as a depth texture'); + gl.finishGpu(); + test.beginFrame(20); + assert.equal(behindWall.answered, true); + assert.equal(behindWall.lastHiddenAt, 10); + assert.equal(onStreet.answered, true); + assert.equal(onStreet.lastHiddenAt, Number.NEGATIVE_INFINITY); + assert.equal(gl.counts.readPixels, 0, 'nothing read back'); + test.destroy(); +}); + +test('without queries a depth texture is not read back: nothing is tested', () => { + const gl = createFakeGl({ webgl2: false }); + const test = createDepthOcclusionTest({ + readSource: () => depthSource(gl, { webgl2: false }), + target: () => ({}), + }); + test.beginFrame(0); + assert.equal(test.add(point(), { x: -250, y: 0, z: -500 }), false); + test.endFrame(); + assert.equal(test.mode, 'off'); + assert.equal(gl.counts.readPixels, 0); +}); + +test('with no target nothing is tested', () => { + const test = createDepthOcclusionTest({ + readSource: (target) => (target ? depthSource(createFakeGl()) : null), + target: () => null, + }); + test.beginFrame(0); + assert.equal(test.add(point(), { x: 0, y: 0, z: -500 }), false); + assert.equal(test.mode, 'off'); +}); diff --git a/src/render/occlusion/index.js b/src/render/occlusion/index.js new file mode 100644 index 000000000..902b49f97 --- /dev/null +++ b/src/render/occlusion/index.js @@ -0,0 +1,6 @@ +/** + * @module render/occlusion + * @description The query port's `occlusionTest` for any WebGL renderer that + * hands over its frame's depth (`createDepthOcclusionTest`, `DepthSource`). + */ +export { createDepthOcclusionTest, DepthOcclusionProbe } from './depthProbe.js';