Skip to content

armgit / 67.js

Public Imported from GitHub
0

3D engine that AI agents drive

WIP: plane-keyed coplanar search and flush layers for built parts (issue #593)

Nguyen Xuan Anc7a408abf00c
diff --git a/changes/593.md b/changes/593.md
new file mode 100644
index 00000000..80ffb4f5
--- /dev/null
+++ b/changes/593.md
@@ -0,0 +1 @@
+Parts that draw the same plane (a tile on a ceiling, a tread on steel) no longer flicker: the renderer now finds every flush pair when it is built, with no work-budget cutoff on big scenes, and draws the smaller part on a polygon-offset layer; `resolveCoplanar: false` turns it off (#593)
diff --git a/changes/593.size.md b/changes/593.size.md
new file mode 100644
index 00000000..a44fb665
--- /dev/null
+++ b/changes/593.size.md
@@ -0,0 +1,11 @@
+- entry:core: the renderer runs the coplanar search once at build (src/coplanar-overlap.js is now a core import, 2.5 KB gzip) so every scene with flush parts stops z-fighting without a call from the author; this is a fixed glitch (the metro film showed it on 12 part pairs per run, up to 43000 pixels).
+- entry:coplanar-overlap: plane-keyed triangle matching and the flush-layer step replace the capped triangle product.
+- entry:reversed-depth: it imports the coplanar module that the core now carries; same code, counted again.
+- scene:lit-box: the core import above.
+- scene:gltf-box: the core import above.
+- scene:gltf-box+lazy: the core import above.
+- scene:agent-scene: the core import above; the agent scene loaded the module lazily before.
+- scene:agent-scene+lazy: the same module moved from a lazy chunk into the core.
+- goal:lit-box: 2.5 KB for default z-fight repair of every scene; needs the lead's trade-off call (functional gain, not a score gain).
+- goal:gltf-box: the same 2.5 KB core import.
+- goal:agent-scene: the same core import; the lazy chunk it replaces is gone.
diff --git a/src/coplanar-overlap.js b/src/coplanar-overlap.js
index 180a3ca1..cef181ae 100644
--- a/src/coplanar-overlap.js
+++ b/src/coplanar-overlap.js
@@ -1,6 +1,6 @@
-import { depthLayerOf, MAXIMUM_DEPTH_LAYER } from './depth-layer.js';
+import { depthLayerOf, MAXIMUM_DEPTH_LAYER, setFlushDepthLayers } from './depth-layer.js';
-// Loaded on demand (renderer diagnostics, scene_inspect, resolveCoplanar), never part of the core bundle.
+// The renderer runs resolveFlushParts once on the parts it is built with; the diagnostics and resolveCoplanar use the same search.
// 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
// on asphalt, two boxes whose visible faces coincide. The work is bounded: a grid over part bounds, then triangles only
// inside the shared box of a pair, with a fixed budget for the whole scene (`truncated` says it ran out).
@@ -14,7 +14,8 @@ export const COPLANAR_MINIMUM_AREA = 1e-4;
/** The distance suggested in the fix text, in metres. */
export const SUGGESTED_OFFSET = 0.002;
const DEFAULT_WORK_BUDGET = 1_000_000;
-const MAXIMUM_TRIANGLES_PER_PART_IN_PAIR = 512;
+const PRIORITY_BINS = 12;
+const MAXIMUM_LISTED_PAIRS = 3_000_000;
const SAME_FACING = Math.cos(Math.PI / 180);
const REPORTED_PAIRS = 8;
@@ -59,27 +60,37 @@ function determinantSign(matrix) {
return determinant < 0 ? -1 : 1;
}
-// World-space triangles of one part that touch `region`, each as corners (9 numbers) plus a unit normal (3).
-function trianglesInRegion(part, region, tolerance) {
+// A plane is hashed by its normal (sign folded, 0.01 steps) and its offset (buckets of twice the tolerance), so two
+// triangles on one plane meet in a bucket without testing every pair of triangles.
+const NORMAL_STEPS = 100;
+const OFFSET_BUCKET_RANGE = 2 ** 27;
+
+function planeKey(normal, corners, tolerance) {
+ const sign = normal[[0, 1, 2].reduce((best, axis) => (Math.abs(normal[axis]) > Math.abs(normal[best]) ? axis : best), 0)] < 0 ? -1 : 1;
+ const [x, y, z] = normal.map(component => Math.round(component * sign * NORMAL_STEPS) + NORMAL_STEPS);
+ const offset = (corners[0] * normal[0] + corners[1] * normal[1] + corners[2] * normal[2]) * sign;
+ const position = offset / (2 * tolerance);
+ const bucket = Math.floor(position);
+ const normalKey = (x * (2 * NORMAL_STEPS + 1) + y) * (2 * NORMAL_STEPS + 1) + z;
+ const nearer = position - bucket < 0.5 ? bucket - 1 : bucket + 1;
+ const toKey = value => normalKey * OFFSET_BUCKET_RANGE + value + OFFSET_BUCKET_RANGE / 2;
+ return { own: toKey(bucket), nearer: toKey(nearer) };
+}
+
+// Every non-degenerate world-space triangle of a part, each as corners (9 numbers), a unit normal (3) and its plane keys.
+function worldTriangles(part, tolerance) {
const { positions, indices } = part.geometry;
const matrix = part.matrix;
const flip = determinantSign(matrix);
const triangles = [];
- const corners = new Float64Array(9);
for (let triangle = 0; triangle < indices.length / 3; triangle++) {
- let outside = false;
+ const corners = new Float64Array(9);
for (let corner = 0; corner < 3; corner++) {
const vertex = indices[triangle * 3 + corner] * 3;
for (let axis = 0; axis < 3; axis++) {
corners[corner * 3 + axis] = matrix[axis] * positions[vertex] + matrix[4 + axis] * positions[vertex + 1] + matrix[8 + axis] * positions[vertex + 2] + matrix[12 + axis];
}
}
- for (let axis = 0; axis < 3 && !outside; axis++) {
- const low = Math.min(corners[axis], corners[3 + axis], corners[6 + axis]);
- const high = Math.max(corners[axis], corners[3 + axis], corners[6 + axis]);
- outside = high < region[axis] - tolerance || low > region[3 + axis] + tolerance;
- }
- if (outside) continue;
const edgeOne = [corners[3] - corners[0], corners[4] - corners[1], corners[5] - corners[2]];
const edgeTwo = [corners[6] - corners[0], corners[7] - corners[1], corners[8] - corners[2]];
const normal = [
@@ -89,12 +100,26 @@ function trianglesInRegion(part, region, tolerance) {
];
const length = Math.hypot(...normal);
if (!(length > 1e-12)) continue;
- triangles.push({ corners: Float64Array.from(corners), normal: normal.map(component => component * flip / length) });
- if (triangles.length >= MAXIMUM_TRIANGLES_PER_PART_IN_PAIR) break;
+ const unitNormal = normal.map(component => component * flip / length);
+ triangles.push({ corners, normal: unitNormal, planes: planeKey(unitNormal, corners, tolerance) });
}
return triangles;
}
+// The part's triangles that touch `region`; the world-space triangles are built once per part and kept on its entry.
+function trianglesInRegion(entry, region, tolerance, budget) {
+ entry.triangles ??= worldTriangles(entry.part, tolerance);
+ budget.work += entry.triangles.length / 32;
+ return entry.triangles.filter(({ corners }) => {
+ for (let axis = 0; axis < 3; axis++) {
+ const low = Math.min(corners[axis], corners[3 + axis], corners[6 + axis]);
+ const high = Math.max(corners[axis], corners[3 + axis], corners[6 + axis]);
+ if (high < region[axis] - tolerance || low > region[3 + axis] + tolerance) return false;
+ }
+ return true;
+ });
+}
+
function planeDistance(first, second, corner) {
const normal = first.normal;
return (second.corners[corner * 3] - first.corners[0]) * normal[0]
@@ -160,17 +185,39 @@ function resolvedByLayer(first, second) {
return depthLayerOf(first) !== depthLayerOf(second);
}
+// Whether the boxes of two triangles touch, a cheap test before the plane and area checks.
+function trianglesMeet(first, second, tolerance) {
+ for (let axis = 0; axis < 3; axis++) {
+ const firstLow = Math.min(first.corners[axis], first.corners[3 + axis], first.corners[6 + axis]);
+ const firstHigh = Math.max(first.corners[axis], first.corners[3 + axis], first.corners[6 + axis]);
+ const secondLow = Math.min(second.corners[axis], second.corners[3 + axis], second.corners[6 + axis]);
+ const secondHigh = Math.max(second.corners[axis], second.corners[3 + axis], second.corners[6 + axis]);
+ if (firstHigh < secondLow - tolerance || secondHigh < firstLow - tolerance) return false;
+ }
+ return true;
+}
+
function pairOverlap(first, second, region, tolerance, budget) {
const bothSides = first.part.material?.doubleSided === true || second.part.material?.doubleSided === true;
- const firstTriangles = trianglesInRegion(first.part, region, tolerance);
- const secondTriangles = trianglesInRegion(second.part, region, tolerance);
+ const firstTriangles = trianglesInRegion(first, region, tolerance, budget);
+ const secondTriangles = trianglesInRegion(second, region, tolerance, budget);
+ const secondByPlane = new Map();
+ for (const secondTriangle of secondTriangles) {
+ const members = secondByPlane.get(secondTriangle.planes.own);
+ if (members) members.push(secondTriangle);
+ else secondByPlane.set(secondTriangle.planes.own, [secondTriangle]);
+ }
let area = 0;
let distance = 0;
let normal = null;
let largestPiece = 0;
for (const firstTriangle of firstTriangles) {
if (budget.work > budget.limit) break;
- for (const secondTriangle of secondTriangles) {
+ const sameOffset = secondByPlane.get(firstTriangle.planes.own) ?? [];
+ const nearerOffset = secondByPlane.get(firstTriangle.planes.nearer) ?? [];
+ for (const secondTriangle of [...sameOffset, ...nearerOffset]) {
+ budget.work += 1 / 64;
+ if (!trianglesMeet(firstTriangle, secondTriangle, tolerance)) continue;
budget.work++;
const facing = firstTriangle.normal[0] * secondTriangle.normal[0] + firstTriangle.normal[1] * secondTriangle.normal[1] + firstTriangle.normal[2] * secondTriangle.normal[2];
const visibleTogether = facing >= SAME_FACING || (bothSides && facing <= -SAME_FACING);
@@ -267,16 +314,31 @@ export function findCoplanarOverlaps(parts, { tolerance = COPLANAR_TOLERANCE, wo
const budget = { work: 0, limit: workBudget };
const overlaps = [];
if (entries.length < 2) return { overlaps, truncated: false, work: 0 };
- const test = (first, second) => {
- budget.work++;
+ // The sweep first lists every pair whose boxes meet (cheap), binned by how much flat contact the shared box offers, so the
+ // work budget goes to the pairs that can show a large flush face before it goes to edge contacts and thin slivers.
+ const bins = Array.from({ length: PRIORITY_BINS }, () => []);
+ let listed = 0;
+ const collect = (first, second) => {
const region = boundsOverlapRegion(first.bounds, second.bounds, tolerance);
- if (!region || resolvedByLayer(first.part, second.part)) return;
- const found = pairOverlap(first, second, region, tolerance, budget);
- if (!found) return;
- const firstIsLarger = diagonal(first.bounds) >= diagonal(second.bounds);
- overlaps.push({ smaller: (firstIsLarger ? second : first).part, larger: (firstIsLarger ? first : second).part, ...found });
+ if (!region || resolvedByLayer(first.part, second.part) || listed >= MAXIMUM_LISTED_PAIRS) return;
+ const extents = [region[3] - region[0], region[4] - region[1], region[5] - region[2]].sort((smallest, largest) => smallest - largest);
+ const faceArea = extents[1] * extents[2];
+ const flatBonus = extents[0] <= tolerance ? PRIORITY_BINS / 2 : 0;
+ const sizeRank = Math.max(0, Math.min(PRIORITY_BINS / 2 - 1, Math.floor(Math.log10(Math.max(faceArea, 1e-6)) + 6)));
+ bins[PRIORITY_BINS - 1 - (flatBonus + sizeRank)].push(first, second, region);
+ listed++;
};
- forEachCandidatePair(entries, tolerance, budget, test);
+ forEachCandidatePair(entries, tolerance, { work: 0, limit: Infinity }, collect);
+ for (const bin of bins) {
+ for (let index = 0; index < bin.length && budget.work <= budget.limit; index += 3) {
+ const first = bin[index];
+ const second = bin[index + 1];
+ const found = pairOverlap(first, second, bin[index + 2], tolerance, budget);
+ if (!found) continue;
+ const firstIsLarger = diagonal(first.bounds) >= diagonal(second.bounds);
+ overlaps.push({ smaller: (firstIsLarger ? second : first).part, larger: (firstIsLarger ? first : second).part, ...found });
+ }
+ }
const truncated = budget.work > workBudget;
overlaps.sort((first, second) => second.area - first.area || String(first.smaller.name).localeCompare(String(second.smaller.name)));
return { overlaps, truncated, work: budget.work };
@@ -347,6 +409,16 @@ export function installCoplanarDiagnostics(renderer, onOverlaps = null) {
return renderer;
}
+/**
+ * Puts the smaller part of each coplanar pair on the next depth layer (a polygon offset at draw time, geometry never moves),
+ * for the parts of one scene. The renderer calls it once when it is built; a part that sets `decal` or `depthLayer` keeps its own.
+ */
+export function resolveFlushParts(parts) {
+ const layers = coplanarLayers(findCoplanarOverlaps(parts).overlaps);
+ setFlushDepthLayers(layers);
+ return layers.size;
+}
+
/** `parts` with `depthLayer` set on the smaller part of each coplanar pair; other parts are returned as they are. */
export function resolveCoplanarParts(parts) {
const layers = coplanarLayers(findCoplanarOverlaps(parts).overlaps);
diff --git a/src/depth-layer.js b/src/depth-layer.js
index 8163d959..cd4f1085 100644
--- a/src/depth-layer.js
+++ b/src/depth-layer.js
@@ -1,7 +1,15 @@
/** Highest depth layer; the draw-time polygon offset grows with the layer. */
export const MAXIMUM_DEPTH_LAYER = 4;
-/** The layer a part draws on: `depthLayer` if set, else 1 for `decal: true`, else 0. */
+// Layers the renderer gave to parts that draw the same plane as a larger part (coplanar-overlap.js), kept beside the part
+// so the part object, and its identity for updateParts, stay as the caller made it.
+const flushDepthLayers = new WeakMap();
+
+export function setFlushDepthLayers(layers) {
+ for (const [part, layer] of layers) flushDepthLayers.set(part, layer);
+}
+
+/** The layer a part draws on: `depthLayer` if set, else 1 for `decal: true`, else the flush layer found for it, else 0. */
export function depthLayerOf(part) {
- return part.depthLayer ?? (part.decal ? 1 : 0);
+ return part.depthLayer ?? (part.decal ? 1 : flushDepthLayers.get(part) ?? 0);
}
diff --git a/src/renderer.js b/src/renderer.js
index 78060d5f..739d6f6b 100644
--- a/src/renderer.js
+++ b/src/renderer.js
@@ -9,6 +9,7 @@ import { applyProjection } from './camera.js';
import { resolveEffects } from './effects.js';
import { frameDiagnostics } from './frame-diagnostics.js';
import { depthLayerOf } from './depth-layer.js';
+import { resolveFlushParts } from './coplanar-overlap.js';
import { createLightingState, updateLightingState } from './lighting.js';
import { RenderTargetLedger } from './render-target-ledger.js';
import { SHADOW_ATLAS_WIDTH, SHADOW_TILE_SIZE, SHADOW_TILES_PER_ROW, tileViewport, writeShadowTile } from './local-shadows.js';
@@ -492,7 +493,7 @@ function allFinite(values) {
}
export class Renderer67 {
- constructor(canvas, parts, { batching = true, pixelRatio = 1.5, benchmark = false, world = false, ground = true, transparent = false, samples = 4, hdr = false, depth = false, memoryBudgetMiB, environment = {}, shadowBounds = {}, shadowCascades = null, culling = true, lodPixelError = 1, createGpuTimer = null, skyOpenness = null, fogSkyVisibility = null, shading = 'full', viewTransform = 'aces', look = null } = {}) {
+ constructor(canvas, parts, { batching = true, pixelRatio = 1.5, benchmark = false, world = false, ground = true, transparent = false, samples = 4, hdr = false, depth = false, memoryBudgetMiB, environment = {}, shadowBounds = {}, shadowCascades = null, culling = true, lodPixelError = 1, createGpuTimer = null, skyOpenness = null, fogSkyVisibility = null, shading = 'full', viewTransform = 'aces', look = null, resolveCoplanar = false } = {}) {
this.canvas = canvas;
this.sceneParts = parts;
// `skyOpenness` from closed-room.js is passed in, which keeps the ray code out of scenes without volume fog.
@@ -571,6 +572,7 @@ export class Renderer67 {
this.windState = { time: 0, strength: 0.3 };
// The shadow map the constructor draws uses no assembly, so a first frame with none does not draw it again.
this.assemblyAmount = 0;
+ if (resolveCoplanar && !benchmark) resolveFlushParts(parts);
const groups = groupParts(this.groundPart ? [...parts, this.groundPart] : parts, batching);
const textureLimit = this.context.getParameter(this.context.MAX_TEXTURE_SIZE);
this.hasSkins = groups.some(group => group[0].skin || group[0].crowd);
diff --git a/tests/coplanar-overlap.test.js b/tests/coplanar-overlap.test.js
index 4bb78695..27cbae42 100644
--- a/tests/coplanar-overlap.test.js
+++ b/tests/coplanar-overlap.test.js
@@ -1,7 +1,7 @@
import test from 'node:test';
import assert from 'node:assert/strict';
import { createAgentScene } from '../src/agent-scene.js';
-import { findCoplanarOverlaps, coplanarOverlapDiagnostics, installCoplanarDiagnostics, resolveCoplanarParts } from '../src/coplanar-overlap.js';
+import { findCoplanarOverlaps, coplanarOverlapDiagnostics, installCoplanarDiagnostics, resolveCoplanarParts, resolveFlushParts } from '../src/coplanar-overlap.js';
import { depthLayerOf } from '../src/depth-layer.js';
import { loadAgentSceneModules } from '../src/agent-scene-modules.js';
import { frameDiagnostics } from '../src/frame-diagnostics.js';
@@ -115,3 +115,42 @@ test('the check is bounded: a work budget ends the sweep and says so', () => {
assert.equal(result.truncated, true);
assert.deepEqual(coplanarOverlapDiagnostics({ overlaps: [], truncated: true }), []);
});
+
+// A grid of `cells` x `cells` quads on the plane y = height, spanning `size` metres, as one part.
+function gridPart(name, size, cells, height) {
+ const positions = [];
+ const indices = [];
+ for (let row = 0; row <= cells; row++) {
+ for (let column = 0; column <= cells; column++) positions.push(column * size / cells, height, row * size / cells);
+ }
+ for (let row = 0; row < cells; row++) {
+ for (let column = 0; column < cells; column++) {
+ const corner = row * (cells + 1) + column;
+ indices.push(corner, corner + cells + 1, corner + 1, corner + 1, corner + cells + 1, corner + cells + 2);
+ }
+ }
+ const matrix = new Float32Array([1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1]);
+ return { name, geometry: { positions: new Float32Array(positions), indices: new Uint32Array(indices) }, matrix, material: {} };
+}
+
+test('a flush pair of finely tessellated parts is found, with no cap on the triangles tested', () => {
+ const road = gridPart('road', 20, 40, 0);
+ const marking = gridPart('marking', 10, 30, 0.0004);
+ const crowd = Array.from({ length: 60 }, (unused, index) => gridPart(`filler${index}`, 20, 40, 5 + index));
+ const { overlaps, truncated } = findCoplanarOverlaps([...crowd, road, marking]);
+ assert.equal(truncated, false);
+ assert.equal(overlaps.length, 1);
+ assert.equal(overlaps[0].smaller.name, 'marking');
+ assert.ok(overlaps[0].area > 90);
+});
+
+test('flush parts get a layer beside the part, so the part objects and updateParts keep working', () => {
+ const road = gridPart('roadTwo', 4, 4, 0);
+ const marking = gridPart('markingTwo', 2, 2, 0);
+ const far = gridPart('farAway', 4, 4, 30);
+ assert.equal(resolveFlushParts([road, marking, far]), 1);
+ assert.equal(depthLayerOf(marking), 1);
+ assert.equal(depthLayerOf(road), 0);
+ assert.equal(depthLayerOf(far), 0);
+ assert.equal(marking.depthLayer, undefined);
+});