3D engine that AI agents drive
Keep reversed-Z out of the coplanar addon and add its package entry (part of #310)
Nguyen Xuan An74e2b0dd3490
diff --git a/bench/reference/README.md b/bench/reference/README.mdindex a3308d1c..e00436fa 100644--- a/bench/reference/README.md+++ b/bench/reference/README.md@@ -1537,7 +1537,7 @@ Fix: `harness.js` renders the reference frame with `wind: 0`. Re-run with 67js o## Reversed-Z depth (2026-11-03, issue #310)-`installReversedDepth(renderer, mode)` (`src/reversed-depth.js`, an addon: the renderer core carries none of it, so a scene that does not install it pays nothing in size) makes the colour pass draw with reversed-Z where `EXT_clip_control` exists. `mode` is `true` (on at once), `false` (off) or `'auto'`, which switches it on, once, at the start of a frame, when that frame's far / near passes 10,000, or when `renderer.requestReversedDepth()` is called; `installCoplanarDiagnostics(renderer, { reversedDepth })` installs it and calls that request when the coplanar check finds a flush pair more than 40 units from the eye (a 24-bit buffer with a 0.1 near plane cannot separate a 1 mm gap much beyond that). Switching on respecifies the two depth stores as float and adds one stage that turns the resolved depth back to standard depth for the passes that read it. What it does: clip depth 0 to 1 with the near plane at 1, depth cleared to 0, `GREATER`, and a `DEPTH_COMPONENT32F` multisample buffer and scene depth texture. Everything else keeps the standard path: shadow maps (the sun, cascades and the local atlas), the sky and environment backgrounds and the post passes switch clip control back before they draw, so their projections do not change. The reversed projection is the standard one with its third row replaced by `(w - z) / 2` (`src/reversed-depth.js`), used only by the draw (`renderer.rasterProjection`, `rasterViewProjection`); culling, fog, inverse matrices and the CPU rasterizer keep the standard matrices. The passes that read the depth texture (ambient occlusion, depth of field and the other camera effects, volume fog, line art outlines and lines) are unchanged: a stage right after the resolve copies the depth and writes `1 - depth` back with `gl_FragDepth`, which is exactly the standard 0 to 1 value. The water mirror, render passes (their depth pass is eye distance, not buffer depth), liquid and foam, blended parts and Gaussian splats run inside the reversed window. A decal's polygon offset flips sign with it. `installReversedDepth(renderer, false)`, benchmark mode and a browser without the extension keep the old path (`renderer.reversedDepth` and `renderer.capabilities.reversedDepth` say which one is in use).+`installReversedDepth(renderer, mode)` (`src/reversed-depth.js`, an addon: the renderer core carries none of it, so a scene that does not install it pays nothing in size) makes the colour pass draw with reversed-Z where `EXT_clip_control` exists. `mode` is `true` (on at once), `false` (off) or `'auto'`, which switches it on, once, at the start of a frame, when that frame's far / near passes 10,000, or when `renderer.requestReversedDepth()` is called; `installDepthPrecision(renderer, { reversedDepth })` installs it together with the coplanar warning and calls that request when the coplanar check finds a flush pair more than 40 units from the eye (a 24-bit buffer with a 0.1 near plane cannot separate a 1 mm gap much beyond that). Switching on respecifies the two depth stores as float and adds one stage that turns the resolved depth back to standard depth for the passes that read it. What it does: clip depth 0 to 1 with the near plane at 1, depth cleared to 0, `GREATER`, and a `DEPTH_COMPONENT32F` multisample buffer and scene depth texture. Everything else keeps the standard path: shadow maps (the sun, cascades and the local atlas), the sky and environment backgrounds and the post passes switch clip control back before they draw, so their projections do not change. The reversed projection is the standard one with its third row replaced by `(w - z) / 2` (`src/reversed-depth.js`), used only by the draw (`renderer.rasterProjection`, `rasterViewProjection`); culling, fog, inverse matrices and the CPU rasterizer keep the standard matrices. The passes that read the depth texture (ambient occlusion, depth of field and the other camera effects, volume fog, line art outlines and lines) are unchanged: a stage right after the resolve copies the depth and writes `1 - depth` back with `gl_FragDepth`, which is exactly the standard 0 to 1 value. The water mirror, render passes (their depth pass is eye distance, not buffer depth), liquid and foam, blended parts and Gaussian splats run inside the reversed window. A decal's polygon offset flips sign with it. `installReversedDepth(renderer, false)`, benchmark mode and a browser without the extension keep the old path (`renderer.reversedDepth` and `renderer.capabilities.reversedDepth` say which one is in use).Measured by `node bench/reference/depth-precision.mjs [gpu|cpu]` (scene in `depth-precision.js`): two 2.2-times-distance-wide planes at 1, 50 and 500 m, the near one `gap` closer (0, 0.1 and 1 mm), seen at about 30 degrees from their normal with the default near 0.1 and far 600, 8 camera positions about 1 to 10 cm apart per case. The number is the share of the red or blue pixels where the far (blue) plane wins, mean of the 8; 0 is right. Before is the renderer as it is, after is `installReversedDepth(renderer, true)`, same build. GPU is the RTX 3060 through Chrome (ANGLE), where the extension is present; the run was made without the GPU queue lock because it was busy and takes seconds, and is to be repeated through `gpu-lock.sh`.diff --git a/bench/size/budgets.json b/bench/size/budgets.jsonindex e202d2eb..ad5dd2ec 100644--- a/bench/size/budgets.json+++ b/bench/size/budgets.json@@ -53,6 +53,7 @@"scene:agent-scene": 112573,"scene:agent-scene+lazy": 300582,"entry:coplanar-overlap": 2960,+ "entry:reversed-depth": 10600,"entry:view-transform": 2120,"entry:view-transform-shader": 21213,"entry:liquid-shader": 16892,diff --git a/changes/310.md b/changes/310.mdindex 23a88486..89460ea3 100644--- a/changes/310.md+++ b/changes/310.md@@ -1,2 +1,2 @@- Stop z-fighting on flush surfaces (part of #310): `renderer.diagnostics` and `scene_inspect` warn `coplanar-overlap` with both part names, the shared area and a fix, and a node's `decal: true` or `depthLayer` (0 to 4), or `environment.resolveCoplanar: 'offset'`, draws the smaller part with a scoped polygon offset in the colour pass and render passes without moving geometry.-- Add reversed-Z depth as an addon (part of #310): `installReversedDepth(renderer, mode)` in `src/reversed-depth.js` draws the colour pass with depth 1 at the near plane, a 32-bit float depth buffer and `GREATER` where `EXT_clip_control` exists, and leaves the shadow maps, backgrounds and post passes on the standard range. `mode` is `true`, `false` or `'auto'`, which switches it on when a frame's far / near passes 10,000 or the coplanar check (`installCoplanarDiagnostics`) finds a flush pair more than 40 units from the eye. The renderer core is unchanged, so a scene that does not install it pays no bytes. On the RTX 3060 the share of pixels where the far plane of a pair wins falls from 0.15 to 0.009 (50 m, 0.1 mm gap), 0.079 to 0 (50 m, 1 mm) and 0.188 to 0.015 (500 m, 1 mm); 500 m with 0.1 mm stays at 0.13 (`bench/reference/README.md`).+- Add reversed-Z depth as an addon (part of #310): `installReversedDepth(renderer, mode)` in `src/reversed-depth.js` draws the colour pass with depth 1 at the near plane, a 32-bit float depth buffer and `GREATER` where `EXT_clip_control` exists, and leaves the shadow maps, backgrounds and post passes on the standard range. `mode` is `true`, `false` or `'auto'`, which switches it on when a frame's far / near passes 10,000 or the coplanar check (`installDepthPrecision`, which also installs the warning) finds a flush pair more than 40 units from the eye. The renderer core is unchanged, so a scene that does not install it pays no bytes (lit-box +0). On the RTX 3060 the share of pixels where the far plane of a pair wins falls from 0.15 to 0.009 (50 m, 0.1 mm gap), 0.079 to 0 (50 m, 1 mm) and 0.188 to 0.015 (500 m, 1 mm); 500 m with 0.1 mm stays at 0.13 (`bench/reference/README.md`).diff --git a/package.json b/package.jsonindex 78baa54c..b73779e7 100644--- a/package.json+++ b/package.json@@ -87,6 +87,7 @@"./addons/render-passes": "./build/render-passes.js","./addons/line-art": "./build/line-art.js","./addons/coplanar-overlap": "./build/coplanar-overlap.js",+ "./addons/reversed-depth": "./build/reversed-depth.js","./addons/material-layer-shaders": "./build/material-layer-shaders.js","./addons/view-transform-shader": "./build/view-transform-shader.js","./addons/view-transform": "./build/view-transform.js",diff --git a/scripts/agent-preview-browser.js b/scripts/agent-preview-browser.jsindex ec22598e..93225bc6 100644--- a/scripts/agent-preview-browser.js+++ b/scripts/agent-preview-browser.js@@ -5,7 +5,7 @@ import { skyOpenness } from '../src/closed-room.js';import { fogSkyVisibility } from '../src/fog-sky-visibility.js';import { installCameraEffects } from '../src/camera-effects.js';import { installRenderPasses } from '../src/render-passes.js';-import { installCoplanarDiagnostics } from '../src/coplanar-overlap.js';+import { installDepthPrecision } from '../src/reversed-depth.js';import { applyProjection } from '../src/camera.js';import { mat4 } from 'gl-matrix';import { resolveAgentShadow, agentEnvironmentMap } from '../src/agent-look.js';@@ -240,7 +240,7 @@ function cascadesFor(scene) {function initializeRenderer(scene, { memoryBudgetMiB, backend }) {const placement = agentGroundPlacement(scene.parts, scene.environment);- const renderer = installCoplanarDiagnostics(installRenderPasses(installCameraEffects(new Renderer67(canvas, scene.parts, {+ const renderer = installDepthPrecision(installRenderPasses(installCameraEffects(new Renderer67(canvas, scene.parts, {ground: placement ? createAgentGround(placement) : false,hdr: true,depth: true,diff --git a/src/coplanar-overlap.js b/src/coplanar-overlap.jsindex fca7b2a3..180a3ca1 100644--- a/src/coplanar-overlap.js+++ b/src/coplanar-overlap.js@@ -1,5 +1,4 @@import { depthLayerOf, MAXIMUM_DEPTH_LAYER } from './depth-layer.js';-import { installReversedDepth } from './reversed-depth.js';// Loaded on demand (renderer diagnostics, scene_inspect, resolveCoplanar), never part of the core bundle.// Finds pairs of parts that draw the same plane in the same place, which z-fight: a sign flush with a wall, a road marking@@ -329,37 +328,19 @@ function diagonalOfPart(part) {return diagonal(worldBounds(part));}-// A 24-bit depth buffer with a 0.1 near plane cannot tell a 1 mm gap apart much beyond this many units from the eye.-export const REVERSED_DEPTH_PAIR_DISTANCE = 40;--/** Whether the smaller part of any pair is farther from the eye than a 24-bit depth buffer can separate it from the larger one. */-export function hasFarOverlap(overlaps, view, distanceLimit = REVERSED_DEPTH_PAIR_DISTANCE) {- if (!view) return false;- return overlaps.some(({ smaller }) => {- const [x, y, z] = smaller.matrix.slice(12, 15);- const viewX = view[0] * x + view[4] * y + view[8] * z + view[12];- const viewY = view[1] * x + view[5] * y + view[9] * z + view[13];- const viewZ = view[2] * x + view[6] * y + view[10] * z + view[14];- return Math.hypot(viewX, viewY, viewZ) > distanceLimit;- });-}-/*** Adds the coplanar-overlap warning to `renderer.diagnostics`. The check is bounded (see findCoplanarOverlaps) and runs once* per layout, when the renderer's batches change, not per frame, so parts that move later are not rechecked.- * It also installs reversed-Z depth (reversed-depth.js): `reversedDepth` is `true` (always), `false` (never) or `'auto'`, which- * switches it on for a very long lens (far / near over 10,000) or for a flush pair far from the eye.*/-export function installCoplanarDiagnostics(renderer, { reversedDepth = 'auto' } = {}) {+export function installCoplanarDiagnostics(renderer, onOverlaps = null) {let checkedBatches = null;let problems = null;- installReversedDepth(renderer, reversedDepth);renderer.coplanarDiagnostics = batches => {if (batches !== checkedBatches) {checkedBatches = batches;- const { overlaps, truncated } = findCoplanarOverlaps(batches.flatMap(batch => batch.parts));- problems = coplanarOverlapDiagnostics({ overlaps, truncated });- if (hasFarOverlap(overlaps, renderer.view)) renderer.requestReversedDepth?.();+ const found = findCoplanarOverlaps(batches.flatMap(batch => batch.parts));+ problems = coplanarOverlapDiagnostics(found);+ onOverlaps?.(found.overlaps);}return problems;};diff --git a/src/reversed-depth.js b/src/reversed-depth.jsindex 29d80f99..b4eed936 100644--- a/src/reversed-depth.js+++ b/src/reversed-depth.js@@ -7,6 +7,7 @@// FAR_TO_NEAR_LIMIT or `renderer.requestReversedDepth()` is called (the coplanar check does, for a flush pair far from the eye).// Switching on reallocates the frame targets once, at the start of a frame.import { mat4 } from 'gl-matrix';+import { installCoplanarDiagnostics } from './coplanar-overlap.js';import { compileProgram, fullscreenVertex } from './gl-program.js';export const FAR_TO_NEAR_LIMIT = 1e4;@@ -219,3 +220,29 @@ export function installReversedDepth(renderer, mode = 'auto') {if (requested) enable();return renderer;}++// A 24-bit depth buffer with a 0.1 near plane cannot tell a 1 mm gap apart much beyond this many units from the eye.+export const REVERSED_DEPTH_PAIR_DISTANCE = 40;++/** Whether the smaller part of any coplanar pair is farther from the eye (the view matrix) than the distance limit. */+export function hasFarOverlap(overlaps, view, distanceLimit = REVERSED_DEPTH_PAIR_DISTANCE) {+ if (!view) return false;+ return overlaps.some(({ smaller }) => {+ const [x, y, z] = smaller.matrix.slice(12, 15);+ const viewX = view[0] * x + view[4] * y + view[8] * z + view[12];+ const viewY = view[1] * x + view[5] * y + view[9] * z + view[13];+ const viewZ = view[2] * x + view[6] * y + view[10] * z + view[14];+ return Math.hypot(viewX, viewY, viewZ) > distanceLimit;+ });+}++/**+ * The coplanar-overlap warning (coplanar-overlap.js) together with reversed-Z: `reversedDepth` is `true`, `false` or `'auto'`, which+ * also switches it on when the coplanar check finds a flush pair far from the eye, besides the far / near rule.+ */+export function installDepthPrecision(renderer, { reversedDepth = 'auto' } = {}) {+ installReversedDepth(renderer, reversedDepth);+ return installCoplanarDiagnostics(renderer, overlaps => {+ if (hasFarOverlap(overlaps, renderer.view)) renderer.requestReversedDepth?.();+ });+}diff --git a/tests/reversed-depth.test.js b/tests/reversed-depth.test.jsindex c483bf99..6dc3d64b 100644--- a/tests/reversed-depth.test.js+++ b/tests/reversed-depth.test.js@@ -1,8 +1,8 @@import test from 'node:test';import assert from 'node:assert/strict';import { mat4, vec4 } from 'gl-matrix';-import { exceedsFarToNearLimit, installReversedDepth, reverseProjectionDepth } from '../src/reversed-depth.js';-import { hasFarOverlap } from '../src/coplanar-overlap.js';+import { exceedsFarToNearLimit, hasFarOverlap, installReversedDepth, reverseProjectionDepth } from '../src/reversed-depth.js';+function depthAt(projection, eyeDistance) {const clip = vec4.transformMat4(vec4.create(), [0, 0, -eyeDistance, 1], projection);diff --git a/tests/support/preview-harness.mjs b/tests/support/preview-harness.mjsindex 8f3abba3..70310435 100644--- a/tests/support/preview-harness.mjs+++ b/tests/support/preview-harness.mjs@@ -82,7 +82,7 @@ export function previewHarness() {// The fault-injected renderer has no floor part; the automatic floor is covered by agent-ground.test.js and the live smokes.agentGroundPlacement: () => null, createAgentGround: () => null, placeAgentGround: () => {}, FLOOR_COLOR: [0.22, 0.22, 0.21], groundBounceEnvironment: (parts, environment) => environment,// The optional addons only plug stages into a real renderer; the fault-injected one needs none.- installCameraEffects: renderer => renderer, installRenderPasses: renderer => renderer, installCoplanarDiagnostics: renderer => renderer,+ installCameraEffects: renderer => renderer, installRenderPasses: renderer => renderer, installDepthPrecision: renderer => renderer,});// Evaluate only trusted repository adapter code; inject the driver boundary for failure cases.new Script(source).runInContext(context);diff --git a/vite.lib.config.js b/vite.lib.config.jsindex 8879d7d9..9ab697f0 100644--- a/vite.lib.config.js+++ b/vite.lib.config.js@@ -55,6 +55,7 @@ export default defineConfig({'render-passes': 'src/render-passes.js','line-art': 'src/line-art.js','coplanar-overlap': 'src/coplanar-overlap.js',+ 'reversed-depth': 'src/reversed-depth.js','material-layer-shaders': 'src/material-layer-shaders.js','view-transform-shader': 'src/view-transform-shader.js','view-transform': 'src/view-transform.js',