Skip to content

armgit / 67.js

Public Imported from GitHub
0

3D engine that AI agents drive

Warn when ambient occlusion is skipped because depth is off (#266)

Nguyen Xuan An8b645f486ad8
diff --git a/changes/266.md b/changes/266.md
new file mode 100644
index 00000000..75304f4e
--- /dev/null
+++ b/changes/266.md
@@ -0,0 +1 @@
+- Report a skipped ambient occlusion pass (issue #266). A frame with `effects.ambientOcclusion` above 0 on a renderer built without `depth: true` now sets a named `ambient-occlusion-without-depth` warning in `renderer.diagnostics`, which the preview's render info includes, instead of skipping the pass silently.
diff --git a/docs/agent-look.md b/docs/agent-look.md
index fa29db99..5cc01249 100644
--- a/docs/agent-look.md
+++ b/docs/agent-look.md
@@ -191,7 +191,7 @@ See [volume fog](https://67js.codepawl.com/volumetric.md) for renderer requireme
The controls reuse `resolveEffects` with a preview bloom strength of `0.12`.
Exposure remains independent and maps to `frame.exposure`.
Bloom strength zero disables bloom.
-Ambient occlusion reads the depth texture, so it needs the HDR depth target that previews use. The program compiles and its half-resolution target allocates on first use. On SwiftShader at 960 by 540 it adds about 16 ms to a 190 ms frame (measured, 8 percent). It is off by default: against Cycles on 10 reference scenes it improved no score by more than 0.002 and made most slightly worse, because the largest gaps are cast shadow shape and reflections, not contact darkening. Pixels that direct light already brightens keep less of it, because occlusion belongs to indirect light.
+Ambient occlusion reads the depth texture, so it needs the HDR depth target that previews use. A renderer built without `depth: true` skips the pass and lists an `ambient-occlusion-without-depth` warning in `renderer.diagnostics` (the preview's render info carries it too). The program compiles and its half-resolution target allocates on first use. On SwiftShader at 960 by 540 it adds about 16 ms to a 190 ms frame (measured, 8 percent). It is off by default: against Cycles on 10 reference scenes it improved no score by more than 0.002 and made most slightly worse, because the largest gaps are cast shadow shape and reflections, not contact darkening. Pixels that direct light already brightens keep less of it, because occlusion belongs to indirect light.
| Field | Default | Range |
| --- | --- | --- |
diff --git a/scripts/agent-preview-browser.js b/scripts/agent-preview-browser.js
index 81c44ca9..eb985371 100644
--- a/scripts/agent-preview-browser.js
+++ b/scripts/agent-preview-browser.js
@@ -71,6 +71,7 @@ function renderInfo(renderer) {
morphTextures: renderer.morphTextures?.size ?? 0,
gpuBuffers: renderer.buffers?.length ?? 0,
drawBatches: renderer.batches?.length ?? 0,
+ ...(renderer.diagnostics?.length ? { diagnostics: renderer.diagnostics } : {}),
};
}
diff --git a/src/frame-diagnostics.js b/src/frame-diagnostics.js
new file mode 100644
index 00000000..907c4c70
--- /dev/null
+++ b/src/frame-diagnostics.js
@@ -0,0 +1,17 @@
+/**
+ * Diagnostics for a frame that renders without error but not as asked. They use the shape of `agent-diagnostics.js`
+ * (kind, severity, target, message, fix) and are read from `renderer.diagnostics`.
+ */
+const NO_DIAGNOSTICS = Object.freeze([]);
+
+export function frameDiagnostics({ depth, effects }) {
+ const problems = [];
+ if (effects.ambientOcclusion > 0 && !depth) {
+ problems.push({
+ kind: 'ambient-occlusion-without-depth', severity: 'warning', target: 'effects.ambientOcclusion',
+ message: `effects.ambientOcclusion is ${effects.ambientOcclusion} but the renderer was built without depth, so the occlusion pass is skipped.`,
+ fix: 'Construct the renderer with depth: true, or set effects.ambientOcclusion to 0.',
+ });
+ }
+ return problems.length ? problems : NO_DIAGNOSTICS;
+}
diff --git a/src/renderer.js b/src/renderer.js
index 18492824..a6596908 100644
--- a/src/renderer.js
+++ b/src/renderer.js
@@ -6,6 +6,7 @@ import { ambientOcclusionFragment } from './ambient-occlusion.js';
import { planRenderSize, estimateTextureBytes, estimateFrameBytes } from './budget.js';
import { applyProjection } from './camera.js';
import { resolveEffects } from './effects.js';
+import { frameDiagnostics } from './frame-diagnostics.js';
import { createLightingState, updateLightingState } from './lighting.js';
import { SHADOW_ATLAS_WIDTH, SHADOW_ATLAS_HEIGHT, tileViewport, writeShadowTile } from './local-shadows.js';
import { resolveVolumeFog, volumeShadowAmbient } from './volumetric.js';
@@ -446,6 +447,8 @@ export class Renderer67 {
this.world = world;
this.environment = environment;
this.shadowBounds = shadowBounds;
+ /** Warnings about the last frame drawn, in the shape of `agent-diagnostics.js`; see `frame-diagnostics.js`. */
+ this.diagnostics = [];
this.activeLightDirection = environment.lightDirection ?? [-3, 6, 4];
this.shadowCascades = shadowCascades;
this.memoryBudgetMiB = memoryBudgetMiB;
@@ -2025,6 +2028,7 @@ export class Renderer67 {
// The shadow view follows the sun, so a moved sun redraws the map.
const lightChanged = String(this.activeLightDirection) !== String(environment.lightDirection);
this.activeLightDirection = environment.lightDirection;
+ this.diagnostics = frameDiagnostics({ depth: this.depth, effects });
const start = performance.now();
const context = this.context;
this.beginGpuTiming();
diff --git a/tests/frame-diagnostics.test.js b/tests/frame-diagnostics.test.js
new file mode 100644
index 00000000..eed686f0
--- /dev/null
+++ b/tests/frame-diagnostics.test.js
@@ -0,0 +1,17 @@
+import assert from 'node:assert/strict';
+import test from 'node:test';
+import { frameDiagnostics } from '../src/frame-diagnostics.js';
+import { resolveEffects } from '../src/effects.js';
+
+test('ambient occlusion on a renderer without depth gets a named warning', () => {
+ const problems = frameDiagnostics({ depth: false, effects: resolveEffects({ ambientOcclusion: 0.6 }) });
+ assert.equal(problems.length, 1);
+ assert.equal(problems[0].kind, 'ambient-occlusion-without-depth');
+ assert.equal(problems[0].severity, 'warning');
+ assert.match(problems[0].fix, /depth: true/);
+});
+
+test('ambient occlusion with depth, or switched off, is silent', () => {
+ assert.deepEqual(frameDiagnostics({ depth: true, effects: resolveEffects({ ambientOcclusion: 0.6 }) }), []);
+ assert.deepEqual(frameDiagnostics({ depth: false, effects: resolveEffects({ ambientOcclusion: 0 }) }), []);
+});