Skip to content

3D engine that AI agents drive

Name the instancing when a flattened path trace is over its triangle limit (#2228)

Nguyen Xuan An2e6a7dc12227
diff --git a/changes/2228.md b/changes/2228.md
new file mode 100644
index 00000000..dcf9fd51
--- /dev/null
+++ b/changes/2228.md
@@ -0,0 +1 @@
+- A path trace over its triangle limit now says how many triangles came from expanded instanced copies and how many are unique, and suggests fewer copies, a simpler GLB or the Glaze renderer (#2228).
diff --git a/docs/path-tracer.md b/docs/path-tracer.md
index 0e8c11b4..ba6caee6 100644
--- a/docs/path-tracer.md
+++ b/docs/path-tracer.md
@@ -101,6 +101,8 @@ The native `cycles` kernel reads an environment map as it is, as Blender Cycles
Also checked before any ray is traced: samples times pixels times bounces at most 4 billion, 400,000 triangles on the `cpu` backend, and on `gpu` and `webgpu` whatever the device holds up to 2,000,000 (`MAX_GPU_TRACE_TRIANGLES`): the triangle table takes 160 bytes a triangle (ten texels: both UV sets are kept), so a WebGL2 context with a 16384 texel `MAX_TEXTURE_SIZE` has room for 3,355,443 and one with 2048 for 419,430, and a WebGPU storage buffer of `maxStorageBufferBindingSize` bytes for that many over 160; the tracer asks the device and an oversized scene is refused with the count, the limit and what to do, the same text for a still, the real-time tracer (WebGL2 and WebGPU) and the GPU light bake (`backend: "gpu"` or `"webgpu"`; a bake with a `texelTracer` of its own keeps the default bound) (a scene exported to the native tracer takes more, see below), 1,024 parts (the CPU and WebGL tracers; a native trace takes more, see below), 32 lights, and finite numbers (positions, normals, uvs, colors) and whole-number, in-range indices in every part. A render job limits `maxSeconds` to 600: the job runs on workers without blocking the page, and its deadline is `maxSeconds` plus 60 seconds for the page and the PNG, so a trace that reaches its limit still ends before the job does.
+Instances count per copy on the `cpu`, `gpu` and `webgpu` backends: they copy every placed node into one triangle buffer, so nine nodes that share three 300,000 triangle GLBs count as 2.7 million triangles, not 0.9 million. Over the bound, the error says `N triangles after expanding M instanced nodes (U unique)` and suggests fewer copies, a simpler GLB or the Glaze renderer. Only the native Cook backend with instancing counts each shared geometry once. The submit-time estimate (`scripts/agent-render-estimate.mjs`) counts every placed node the same way.
+
### Instanced scenes for the native tracer
`buildTraceScene(parts, environment, { instancing: true })` keeps parts that share one geometry object as instances of it, and `buildNativeInputV2` packs them as one bottom-level structure per geometry plus one instance record per part, for `traceNative` with `kernel: "cycles"`. Without the option the scene is flattened as before, and a scene where no two parts share a geometry is flattened too, with output identical to the default.
diff --git a/src/path-tracer-scene.js b/src/path-tracer-scene.js
index dad3d1c1..346b9b49 100644
--- a/src/path-tracer-scene.js
+++ b/src/path-tracer-scene.js
@@ -397,14 +397,44 @@ function resolveInstanceLimit(options) {
return { native: true, count: requested };
}
-function flattenedLimitMessage(limits, triangleCount) {
+/**
+ * How many parts reuse a geometry another part also uses, and the triangles left when each shared geometry counts once.
+ * A flattened trace copies every instance into one triangle buffer, so the limit sees the first number's expansion.
+ */
+export function measureInstanceExpansion(parts, geometries) {
+ const useCounts = new Map();
+ parts.forEach((part, index) => {
+ if (sharesAuthoredGeometry(part, geometries[index])) useCounts.set(geometries[index], (useCounts.get(geometries[index]) ?? 0) + 1);
+ });
+ let instancedNodes = 0;
+ let uniqueTriangles = 0;
+ const counted = new Set();
+ parts.forEach((part, index) => {
+ const geometry = geometries[index];
+ const triangles = geometry.indices.length / 3;
+ const shared = useCounts.get(geometry) > 1;
+ if (shared) instancedNodes++;
+ if (shared && counted.has(geometry)) return;
+ counted.add(geometry);
+ uniqueTriangles += triangles;
+ });
+ return { instancedNodes, uniqueTriangles };
+}
+
+function instancingNote(triangleCount, expansion) {
+ if (!expansion || expansion.instancedNodes < 1) return '';
+ return ` That is ${triangleCount} triangles after expanding ${expansion.instancedNodes} instanced nodes (${expansion.uniqueTriangles} unique): this backend copies every instance into one triangle buffer. Use fewer copies, a simpler GLB, or the Glaze renderer.`;
+}
+
+function flattenedLimitMessage(limits, triangleCount, expansion) {
+ const note = instancingNote(triangleCount, expansion);
if (limits.native) {
- return `A native path trace takes at most ${limits.unique} triangles in total, got ${triangleCount}, ${triangleCount - limits.unique} too many. Share geometry between copies (they stay instances) or simplify the meshes.`;
+ return `A native path trace takes at most ${limits.unique} triangles in total, got ${triangleCount}, ${triangleCount - limits.unique} too many. Share geometry between copies (they stay instances) or simplify the meshes.${note}`;
}
if (limits.gpu) {
- return `This GPU path trace takes at most ${limits.unique} triangles in total (what the device's texture or buffer limits hold, up to ${MAX_GPU_TRACE_TRIANGLES}), got ${triangleCount}. Simplify or drop meshes (a crowd can use a lower detail level for the avatars far from the camera), or render the frame with the native Cook backend.`;
+ return `This GPU path trace takes at most ${limits.unique} triangles in total (what the device's texture or buffer limits hold, up to ${MAX_GPU_TRACE_TRIANGLES}), got ${triangleCount}. Simplify or drop meshes (a crowd can use a lower detail level for the avatars far from the camera), or render the frame with the native Cook backend.${note}`;
}
- return `A path trace takes at most ${MAX_TRACE_TRIANGLES} triangles in total, got ${triangleCount}. Simplify or drop meshes, or trace on the GPU backend, which holds more when the device allows it.`;
+ return `A path trace takes at most ${MAX_TRACE_TRIANGLES} triangles in total, got ${triangleCount}. Simplify or drop meshes, or trace on the GPU backend, which holds more when the device allows it.${note}`;
}
function flattenParts(parts, geometries = parts.map(traceGeometry), limits = resolveTriangleLimits()) {
@@ -416,7 +446,7 @@ function flattenParts(parts, geometries = parts.map(traceGeometry), limits = res
indexTotal += geometry.indices.length;
}
if (indexTotal / 3 > limits.unique) {
- throw new RangeError(flattenedLimitMessage(limits, indexTotal / 3));
+ throw new RangeError(flattenedLimitMessage(limits, indexTotal / 3, measureInstanceExpansion(parts, geometries)));
}
const world = allocateWorld(vertexTotal, indexTotal, geometries.some(geometry => geometry.lightUvs));
let vertexOffset = 0;
diff --git a/tests/path-tracer-instanced-triangle-count.test.js b/tests/path-tracer-instanced-triangle-count.test.js
new file mode 100644
index 00000000..ddd4d14e
--- /dev/null
+++ b/tests/path-tracer-instanced-triangle-count.test.js
@@ -0,0 +1,81 @@
+import assert from 'node:assert/strict';
+import test from 'node:test';
+
+import { buildTraceScene, measureInstanceExpansion } from '../src/path-tracer-scene.js';
+
+const QUADS_PER_SIDE = 10;
+const TRIANGLES_PER_MESH = QUADS_PER_SIDE * QUADS_PER_SIDE * 2;
+const MESH_COUNT = 3;
+const COPIES_PER_MESH = 3;
+const ENVIRONMENT = { keyColor: [1, 1, 1], lightDirection: [0, 1, 0] };
+
+function gridGeometry() {
+ const side = QUADS_PER_SIDE + 1;
+ const positions = new Float32Array(side * side * 3);
+ const normals = new Float32Array(side * side * 3);
+ for (let row = 0; row < side; row++) {
+ for (let column = 0; column < side; column++) {
+ positions.set([column * 0.1, row * 0.1, 0], (row * side + column) * 3);
+ normals.set([0, 0, 1], (row * side + column) * 3);
+ }
+ }
+ const indices = new Uint32Array(TRIANGLES_PER_MESH * 3);
+ let slot = 0;
+ for (let row = 0; row < QUADS_PER_SIDE; row++) {
+ for (let column = 0; column < QUADS_PER_SIDE; column++) {
+ const corner = row * side + column;
+ indices.set([corner, corner + 1, corner + side, corner + 1, corner + side + 1, corner + side], slot);
+ slot += 6;
+ }
+ }
+ return { positions, normals, indices };
+}
+
+// Nine nodes that share three geometries, like nine placed copies of three GLBs.
+function instancedNodes() {
+ const sharedGeometries = Array.from({ length: MESH_COUNT }, gridGeometry);
+ return sharedGeometries.flatMap((geometry, meshIndex) => Array.from({ length: COPIES_PER_MESH }, (_, copyIndex) => ({
+ name: `mesh-${meshIndex}-copy-${copyIndex}`,
+ geometry,
+ matrix: new Float32Array([1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1, 0, copyIndex * 2, meshIndex * 2, 0, 1]),
+ material: { color: [0.8, 0.7, 0.6] },
+ })));
+}
+
+const EXPANDED_TRIANGLES = MESH_COUNT * COPIES_PER_MESH * TRIANGLES_PER_MESH;
+const UNIQUE_TRIANGLES = MESH_COUNT * TRIANGLES_PER_MESH;
+
+test('the expansion counts the nodes that share geometry and the triangles once per shared geometry', () => {
+ const parts = instancedNodes();
+ const lone = { name: 'lone', geometry: gridGeometry(), material: { color: [1, 1, 1] } };
+ const geometries = [...parts, lone].map(part => part.geometry);
+ assert.deepEqual(measureInstanceExpansion([...parts, lone], geometries), {
+ instancedNodes: MESH_COUNT * COPIES_PER_MESH,
+ uniqueTriangles: UNIQUE_TRIANGLES + TRIANGLES_PER_MESH,
+ });
+});
+
+test('a gpu trace of instanced copies is refused with the expanded and the unique count and the way out', () => {
+ assert.ok(EXPANDED_TRIANGLES > UNIQUE_TRIANGLES * 2);
+ assert.throws(() => buildTraceScene(instancedNodes(), ENVIRONMENT, { gpuTriangleLimit: UNIQUE_TRIANGLES * 2 }), (error) => {
+ assert.equal(error.name, 'RangeError');
+ assert.match(error.message, new RegExp(`got ${EXPANDED_TRIANGLES}\\.`));
+ assert.match(error.message, new RegExp(`${EXPANDED_TRIANGLES} triangles after expanding 9 instanced nodes \\(${UNIQUE_TRIANGLES} unique\\)`));
+ assert.match(error.message, /fewer copies, a simpler GLB, or the Glaze renderer/);
+ return true;
+ });
+});
+
+test('a scene without shared geometry keeps its old message', () => {
+ const cpuParts = Array.from({ length: 2 }, (_, index) => ({ name: `big-${index}`, geometry: gridGeometry(), material: { color: [1, 1, 1] } }));
+ assert.doesNotThrow(() => buildTraceScene(cpuParts, ENVIRONMENT));
+ assert.throws(() => buildTraceScene(cpuParts, ENVIRONMENT, { gpuTriangleLimit: TRIANGLES_PER_MESH }), (error) => {
+ assert.doesNotMatch(error.message, /instanced nodes/);
+ return true;
+ });
+});
+
+test('the same copies are accepted when the limit holds every expanded triangle', () => {
+ const scene = buildTraceScene(instancedNodes(), ENVIRONMENT, { gpuTriangleLimit: EXPANDED_TRIANGLES });
+ assert.equal(scene.indices.length / 3, EXPANDED_TRIANGLES);
+});