Skip to content

armgit / 67.js

Public Imported from GitHub
0

3D engine that AI agents drive

Keep copies of one geometry as instances in the trace scene (#896)

Nguyen Xuan An8c7a9efa8d38
diff --git a/bench/instancing/render-copies.mjs b/bench/instancing/render-copies.mjs
new file mode 100644
index 00000000..3a0cf89c
--- /dev/null
+++ b/bench/instancing/render-copies.mjs
@@ -0,0 +1,93 @@
+// Renders N copies of one small mesh through the native "cycles" kernel, either as shared instances or flattened into one
+// triangle soup, and writes the linear RGBA floats beside a JSON report. Usage:
+// node bench/instancing/render-copies.mjs <instanced|flattened> <output folder> [copies] [width] [height] [samples]
+import { mkdirSync, writeFileSync } from 'node:fs';
+import { buildNativeInputV2, traceNative } from '../../packages/render-native/index.mjs';
+import { createCamera } from '../../src/path-tracer.js';
+import { buildTraceScene } from '../../src/path-tracer-scene.js';
+
+const [mode, outputFolder, copiesText = '1000', widthText = '160', heightText = '120', samplesText = '64'] = process.argv.slice(2);
+if (mode !== 'instanced' && mode !== 'flattened') throw new RangeError('Pass "instanced" or "flattened" as the first argument.');
+const copyCount = Number(copiesText);
+const width = Number(widthText);
+const height = Number(heightText);
+const samples = Number(samplesText);
+
+function midpoint(positions, first, second) {
+ return [0, 1, 2].map(axis => (positions[first * 3 + axis] + positions[second * 3 + axis]) / 2);
+}
+
+// An icosphere: 20 triangles, each split in four per level, so level 2 has 320.
+function icosphere(levels) {
+ const golden = (1 + Math.sqrt(5)) / 2;
+ let positions = [-1, golden, 0, 1, golden, 0, -1, -golden, 0, 1, -golden, 0, 0, -1, golden, 0, 1, golden, 0, -1, -golden, 0, 1, -golden, golden, 0, -1, golden, 0, 1, -golden, 0, -1, -golden, 0, 1];
+ let indices = [0, 11, 5, 0, 5, 1, 0, 1, 7, 0, 7, 10, 0, 10, 11, 1, 5, 9, 5, 11, 4, 11, 10, 2, 10, 7, 6, 7, 1, 8, 3, 9, 4, 3, 4, 2, 3, 2, 6, 3, 6, 8, 3, 8, 9, 4, 9, 5, 2, 4, 11, 6, 2, 10, 8, 6, 7, 9, 8, 1];
+ for (let level = 0; level < levels; level++) {
+ const next = [];
+ const cache = new Map();
+ const middle = (first, second) => {
+ const key = first < second ? `${first}:${second}` : `${second}:${first}`;
+ if (!cache.has(key)) {
+ cache.set(key, positions.length / 3);
+ positions = positions.concat(midpoint(positions, first, second));
+ }
+ return cache.get(key);
+ };
+ for (let triangle = 0; triangle < indices.length; triangle += 3) {
+ const [a, b, c] = indices.slice(triangle, triangle + 3);
+ const ab = middle(a, b);
+ const bc = middle(b, c);
+ const ca = middle(c, a);
+ next.push(a, ab, ca, b, bc, ab, c, ca, bc, ab, bc, ca);
+ }
+ indices = next;
+ }
+ const unit = new Float32Array(positions.length);
+ for (let vertex = 0; vertex < positions.length / 3; vertex++) {
+ const length = Math.hypot(positions[vertex * 3], positions[vertex * 3 + 1], positions[vertex * 3 + 2]);
+ for (let axis = 0; axis < 3; axis++) unit[vertex * 3 + axis] = positions[vertex * 3 + axis] / length;
+ }
+ return { positions: unit, normals: Float32Array.from(unit), indices: Uint32Array.from(indices) };
+}
+
+const MATERIALS = [
+ { color: [0.8, 0.25, 0.2], roughness: 0.5 },
+ { color: [0.2, 0.6, 0.85], roughness: 0.3, metallic: 0.8 },
+ { color: [0.85, 0.8, 0.3], roughness: 0.7 },
+];
+
+function buildParts(geometry) {
+ const side = Math.ceil(Math.cbrt(copyCount));
+ return Array.from({ length: copyCount }, (_, index) => {
+ const column = index % side;
+ const row = Math.floor(index / side) % side;
+ const layer = Math.floor(index / (side * side));
+ const scale = 0.3 + 0.1 * ((index * 7) % 5) / 4;
+ // Every seventh copy is mirrored, which flips the winding and exercises the negative-scale flag.
+ const mirror = index % 7 === 0 ? -1 : 1;
+ const matrix = [scale * mirror, 0, 0, 0, 0, scale, 0, 0, 0, 0, scale, 0, (column - side / 2) * 1.1, (row - side / 2) * 1.1, -layer * 1.1, 1];
+ return { name: `copy-${index}`, geometry, matrix, material: MATERIALS[index % MATERIALS.length] };
+ });
+}
+
+const geometry = icosphere(2);
+const parts = buildParts(geometry);
+const environment = { keyColor: [3, 3, 3], lightDirection: [0.4, 0.8, 0.5] };
+const camera = createCamera({ eye: [0, 0, 14], target: [0, 0, -3], fov: 50 }, width, height);
+
+const packStarted = performance.now();
+const scene = buildTraceScene(parts, environment, { instancing: mode === 'instanced' });
+const input = buildNativeInputV2(scene, camera, { width, height, samples, seed: 1 });
+const packSeconds = (performance.now() - packStarted) / 1000;
+const traced = traceNative(input, { width, height, samples, kernel: 'cycles' });
+
+mkdirSync(outputFolder, { recursive: true });
+writeFileSync(`${outputFolder}/${mode}.f32`, Buffer.from(traced.rgba.buffer, traced.rgba.byteOffset, traced.rgba.byteLength));
+const report = {
+ mode, copyCount, width, height, samples, adapter: traced.adapter, packSeconds,
+ instanceCount: input.instanceCount, triangleCount: input.triangleCount, geometryTriangles: geometry.indices.length / 3,
+ trianglesBytes: input.triangles.byteLength, instancesBytes: input.instances.byteLength,
+ setupSeconds: traced.setupSeconds, accelerationBuildSeconds: traced.accelerationBuildSeconds, uploadSeconds: traced.uploadSeconds,
+};
+writeFileSync(`${outputFolder}/${mode}.json`, JSON.stringify(report, null, 2));
+console.log(JSON.stringify(report));
diff --git a/changes/896-instancing-scene.md b/changes/896-instancing-scene.md
new file mode 100644
index 00000000..7444ff54
--- /dev/null
+++ b/changes/896-instancing-scene.md
@@ -0,0 +1 @@
+- `buildTraceScene` takes `{ instancing: true }` to keep copies of one geometry as instances for the native "cycles" kernel, counting triangles once per shared geometry and allowing more parts than the flattened limit (#896)
diff --git a/docs/path-tracer.md b/docs/path-tracer.md
index a29a86f5..54a1a8ed 100644
--- a/docs/path-tracer.md
+++ b/docs/path-tracer.md
@@ -56,6 +56,15 @@ A part with a material `subsurface` weight above 0 sends that share of its diffu
Also checked before any ray is traced: samples times pixels times bounces at most 4 billion, 400,000 triangles, 1,024 parts, 32 lights, and finite numbers and 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.
+### 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.
+
+- Sharing is decided after the trace geometry is resolved. A skinned, flush-lifted or box-mapped part gets a geometry of its own, and a geometry with per-triangle materials is not shared either: those parts are moved into world space once and traced as instances with an identity matrix.
+- Limits: 400,000 triangles counted once per shared geometry, 1,024 distinct geometries (the part limit, counted on geometries) and 65,536 instances. An instanced scene has no world-space triangle arrays or CPU BVH, so only `buildNativeInputV2` reads it.
+- A part's material is its own entry in `materials`, so copies may differ in material; a multi-material mesh stays one geometry with the materials the part names.
+- `buildNativeInput` (the `legacy` kernel) refuses an instanced scene with an error; build the scene without `instancing` for that kernel. Render jobs still export flattened tables.
+
The same scene and options give the same bytes. Random numbers come from a hash of the pixel, the sample and the seed, never from `Math.random` or the clock, and a pixel does not depend on which thread drew it.
## Choosing a backend
diff --git a/packages/render-native/pack-input.mjs b/packages/render-native/pack-input.mjs
index fe7200b6..d063d98f 100644
--- a/packages/render-native/pack-input.mjs
+++ b/packages/render-native/pack-input.mjs
@@ -36,6 +36,9 @@ function writeParameters(scene, camera, options, lightCount, atlasWidth, subsurf
* `pack` is the module `src/path-tracer-gpu-pack.js`, passed in so this package never imports the engine's source.
*/
export function buildNativeInput(scene, camera, options, pack) {
+ if (scene.instances) {
+ throw new TypeError('buildNativeInput packs flattened scenes for kernel "legacy" and cannot read instances: build the scene without { instancing: true }, or pack it with buildNativeInputV2 and trace with kernel "cycles".');
+ }
const atlas = pack.packAtlas(scene.materials);
const lights = pack.packLights(scene.lights);
const environment = pack.packEnvironment(scene.environment);
diff --git a/src/path-tracer-scene.js b/src/path-tracer-scene.js
index efd57651..1ba8fac8 100644
--- a/src/path-tracer-scene.js
+++ b/src/path-tracer-scene.js
@@ -15,6 +15,8 @@ import { liftRankedTriangles } from './flush-lift.js';
export const MAX_TRACE_TRIANGLES = 400_000;
export const MAX_TRACE_PARTS = 1024;
+// An instanced trace counts triangles once per shared geometry and bounds the copies on their own.
+export const MAX_TRACE_INSTANCES = 65_536;
export const MAX_TRACE_LIGHTS = 32;
// A Blender sun of 1 degree, which is what the reference harness gives Cycles.
export const SUN_ANGULAR_RADIUS = Math.PI / 360;
@@ -160,9 +162,16 @@ function requireFiniteNumbers(values, expectedLength, label) {
}
}
-function validatePart(part, geometry) {
- const label = `Part ${part.name ?? ''}`.trim();
- requireFiniteNumbers(part.matrix ?? IDENTITY_MATRIX, 16, `${label} matrix`);
+function partLabel(part) {
+ return `Part ${part.name ?? ''}`.trim();
+}
+
+function validateMatrix(part) {
+ requireFiniteNumbers(part.matrix ?? IDENTITY_MATRIX, 16, `${partLabel(part)} matrix`);
+}
+
+function validateGeometry(part, geometry) {
+ const label = partLabel(part);
requireFiniteNumbers(geometry.positions, undefined, `${label} positions`);
if (geometry.positions.length % 3 !== 0 || geometry.indices.length % 3 !== 0) throw new RangeError(`${label} positions and indices must come in threes.`);
const vertexCount = geometry.positions.length / 3;
@@ -175,6 +184,11 @@ function validatePart(part, geometry) {
if (geometry.colors && geometry.colors.length !== vertexCount * 3) throw new RangeError(`${label} needs one colour for every position.`);
}
+function validatePart(part, geometry) {
+ validateMatrix(part);
+ validateGeometry(part, geometry);
+}
+
/**
* The geometry a part is traced with. A box-projected material has no UVs, so it gets the UVs of its projection (the
* ones the glTF export writes), and every map then reads them like those of an authored material.
@@ -189,55 +203,63 @@ function traceGeometry(part) {
return boxProjectedGeometry(geometry, columnLengths(part.matrix ?? IDENTITY_MATRIX), boxMapScale, boxMapAxis);
}
-function flattenParts(parts) {
+function allocateWorld(vertexTotal, indexTotal) {
+ return {
+ positions: new Float32Array(vertexTotal * 3),
+ normals: new Float32Array(vertexTotal * 3),
+ uvs: new Float32Array(vertexTotal * 2),
+ colors: new Float32Array(vertexTotal * 3).fill(1),
+ indices: new Uint32Array(indexTotal),
+ triangleMaterial: new Uint32Array(indexTotal / 3),
+ };
+}
+
+// Writes one part, moved by its matrix, into the world arrays at the given vertex and triangle offsets.
+function writeWorldPart(world, part, geometry, partIndex, vertexOffset, triangleOffset) {
+ const matrix = part.matrix ?? IDENTITY_MATRIX;
+ const normals = normalMatrix(matrix);
+ const vertexCount = geometry.positions.length / 3;
+ for (let vertex = 0; vertex < vertexCount; vertex++) {
+ const x = geometry.positions[vertex * 3];
+ const y = geometry.positions[vertex * 3 + 1];
+ const z = geometry.positions[vertex * 3 + 2];
+ const target = (vertexOffset + vertex) * 3;
+ world.positions[target] = matrix[0] * x + matrix[4] * y + matrix[8] * z + matrix[12];
+ world.positions[target + 1] = matrix[1] * x + matrix[5] * y + matrix[9] * z + matrix[13];
+ world.positions[target + 2] = matrix[2] * x + matrix[6] * y + matrix[10] * z + matrix[14];
+ const normalX = geometry.normals[vertex * 3];
+ const normalY = geometry.normals[vertex * 3 + 1];
+ const normalZ = geometry.normals[vertex * 3 + 2];
+ const worldX = normals[0] * normalX + normals[3] * normalY + normals[6] * normalZ;
+ const worldY = normals[1] * normalX + normals[4] * normalY + normals[7] * normalZ;
+ const worldZ = normals[2] * normalX + normals[5] * normalY + normals[8] * normalZ;
+ const length = Math.hypot(worldX, worldY, worldZ) || 1;
+ world.normals[target] = worldX / length;
+ world.normals[target + 1] = worldY / length;
+ world.normals[target + 2] = worldZ / length;
+ }
+ if (geometry.uvs) world.uvs.set(geometry.uvs, (vertexOffset) * 2);
+ if (geometry.colors) world.colors.set(geometry.colors, vertexOffset * 3);
+ for (let slot = 0; slot < geometry.indices.length; slot++) world.indices[triangleOffset * 3 + slot] = geometry.indices[slot] + vertexOffset;
+ world.triangleMaterial.fill(partIndex, triangleOffset, triangleOffset + geometry.indices.length / 3);
+}
+
+function flattenParts(parts, geometries = parts.map(traceGeometry)) {
let vertexTotal = 0;
let indexTotal = 0;
- const geometries = parts.map(traceGeometry);
parts.forEach((part, index) => validatePart(part, geometries[index]));
for (const geometry of geometries) {
vertexTotal += geometry.positions.length / 3;
indexTotal += geometry.indices.length;
}
if (indexTotal / 3 > MAX_TRACE_TRIANGLES) throw new RangeError(`A path trace takes at most ${MAX_TRACE_TRIANGLES} triangles in total.`);
- const world = {
- positions: new Float32Array(vertexTotal * 3),
- normals: new Float32Array(vertexTotal * 3),
- uvs: new Float32Array(vertexTotal * 2),
- colors: new Float32Array(vertexTotal * 3).fill(1),
- indices: new Uint32Array(indexTotal),
- triangleMaterial: new Uint32Array(indexTotal / 3),
- };
+ const world = allocateWorld(vertexTotal, indexTotal);
let vertexOffset = 0;
let triangleOffset = 0;
parts.forEach((part, partIndex) => {
const geometry = geometries[partIndex];
- const matrix = part.matrix ?? IDENTITY_MATRIX;
- const normals = normalMatrix(matrix);
- const vertexCount = geometry.positions.length / 3;
- for (let vertex = 0; vertex < vertexCount; vertex++) {
- const x = geometry.positions[vertex * 3];
- const y = geometry.positions[vertex * 3 + 1];
- const z = geometry.positions[vertex * 3 + 2];
- const target = (vertexOffset + vertex) * 3;
- world.positions[target] = matrix[0] * x + matrix[4] * y + matrix[8] * z + matrix[12];
- world.positions[target + 1] = matrix[1] * x + matrix[5] * y + matrix[9] * z + matrix[13];
- world.positions[target + 2] = matrix[2] * x + matrix[6] * y + matrix[10] * z + matrix[14];
- const normalX = geometry.normals[vertex * 3];
- const normalY = geometry.normals[vertex * 3 + 1];
- const normalZ = geometry.normals[vertex * 3 + 2];
- const worldX = normals[0] * normalX + normals[3] * normalY + normals[6] * normalZ;
- const worldY = normals[1] * normalX + normals[4] * normalY + normals[7] * normalZ;
- const worldZ = normals[2] * normalX + normals[5] * normalY + normals[8] * normalZ;
- const length = Math.hypot(worldX, worldY, worldZ) || 1;
- world.normals[target] = worldX / length;
- world.normals[target + 1] = worldY / length;
- world.normals[target + 2] = worldZ / length;
- }
- if (geometry.uvs) world.uvs.set(geometry.uvs, (vertexOffset) * 2);
- if (geometry.colors) world.colors.set(geometry.colors, vertexOffset * 3);
- for (let slot = 0; slot < geometry.indices.length; slot++) world.indices[triangleOffset * 3 + slot] = geometry.indices[slot] + vertexOffset;
- world.triangleMaterial.fill(partIndex, triangleOffset, triangleOffset + geometry.indices.length / 3);
- vertexOffset += vertexCount;
+ writeWorldPart(world, part, geometry, partIndex, vertexOffset, triangleOffset);
+ vertexOffset += geometry.positions.length / 3;
triangleOffset += geometry.indices.length / 3;
});
return world;
@@ -324,11 +346,146 @@ function resolveTraceLocalVolumes(input, parts) {
return { volumes, boundsOnlyParts: parts.filter(part => meshPartNames.has(part.name) && part.visible === false) };
}
-export function buildTraceScene(allParts, environment = {}) {
+// Camera rays skip a shadow-only part; every other ray kind still sees it (visibility bits 2, 4, 8, 16 and 32 of FORMAT-v2).
+const INSTANCE_VISIBILITY_WITHOUT_CAMERA = 2 | 4 | 8 | 16 | 32;
+
+/**
+ * True when the part keeps the geometry object it was authored with, so its copies can share one bottom-level structure.
+ * A skinned, flush-lifted or box-mapped part gets a geometry of its own from `traceGeometry`, and a geometry with
+ * per-triangle materials would be read differently by the instanced packer, so those stay baked into world space.
+ */
+function sharesAuthoredGeometry(part, traced) {
+ return traced === part.geometry && !traced.triangleMaterial;
+}
+
+function countSharedGeometries(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);
+ });
+ return [...useCounts.values()].filter(count => count > 1).length;
+}
+
+/** Validates each part's matrix, and each distinct geometry once, then returns the unique geometry and triangle totals. */
+function measureInstancedParts(parts, geometries) {
+ const seen = new Set();
+ let uniqueGeometries = 0;
+ let uniqueTriangles = 0;
+ parts.forEach((part, index) => {
+ const geometry = geometries[index];
+ validateMatrix(part);
+ if (sharesAuthoredGeometry(part, geometry)) {
+ if (seen.has(geometry)) return;
+ seen.add(geometry);
+ }
+ validateGeometry(part, geometry);
+ uniqueGeometries++;
+ uniqueTriangles += geometry.indices.length / 3;
+ });
+ return { uniqueGeometries, uniqueTriangles };
+}
+
+function requireInstancedCaps(parts, { uniqueGeometries, uniqueTriangles }) {
+ if (parts.length > MAX_TRACE_INSTANCES) {
+ throw new RangeError(`An instanced path trace takes at most ${MAX_TRACE_INSTANCES} instances, got ${parts.length}. Pass fewer parts, or merge small copies into one mesh.`);
+ }
+ if (uniqueGeometries > MAX_TRACE_PARTS) {
+ throw new RangeError(`An instanced path trace takes at most ${MAX_TRACE_PARTS} distinct geometries, got ${uniqueGeometries}. Share one geometry object between copies instead of building a new one per part.`);
+ }
+ if (uniqueTriangles > MAX_TRACE_TRIANGLES) {
+ throw new RangeError(`An instanced path trace takes at most ${MAX_TRACE_TRIANGLES} unique triangles, counted once per shared geometry, got ${uniqueTriangles}. Share geometry between copies or simplify the meshes.`);
+ }
+}
+
+// A part that cannot share its geometry is moved into world space once and traced with an identity matrix.
+function bakeWorldGeometry(part, geometry) {
+ const world = allocateWorld(geometry.positions.length / 3, geometry.indices.length);
+ writeWorldPart(world, part, geometry, 0, 0, 0);
+ delete world.triangleMaterial;
+ return world;
+}
+
+function instanceFor(part, geometry, partIndex, material) {
+ const shared = sharesAuthoredGeometry(part, geometry);
+ const instance = {
+ geometry: shared ? geometry : bakeWorldGeometry(part, geometry),
+ matrix: shared ? part.matrix ?? IDENTITY_MATRIX : IDENTITY_MATRIX,
+ materialIndex: partIndex,
+ objectId: partIndex,
+ lightMask: material.lightMask,
+ };
+ if (part.material?.lightMaskHi !== undefined) instance.lightMaskHi = part.material.lightMaskHi;
+ if (part.shadowOnly === true) instance.visibilityFlags = INSTANCE_VISIBILITY_WITHOUT_CAMERA;
+ return instance;
+}
+
+// The largest coordinate any instance reaches, from the corners of each geometry's box, so it never reads a whole copy.
+function instancedExtent(instances) {
+ const boxes = new Map();
+ let extent = 1e-3;
+ for (const { geometry, matrix } of instances) {
+ if (!boxes.has(geometry)) boxes.set(geometry, boundingBoxOf(geometry.positions));
+ const { low, high } = boxes.get(geometry);
+ for (let corner = 0; corner < 8; corner++) {
+ const x = corner & 1 ? high[0] : low[0];
+ const y = corner & 2 ? high[1] : low[1];
+ const z = corner & 4 ? high[2] : low[2];
+ extent = Math.max(extent,
+ Math.abs(matrix[0] * x + matrix[4] * y + matrix[8] * z + matrix[12]),
+ Math.abs(matrix[1] * x + matrix[5] * y + matrix[9] * z + matrix[13]),
+ Math.abs(matrix[2] * x + matrix[6] * y + matrix[10] * z + matrix[14]));
+ }
+ }
+ return extent;
+}
+
+function boundingBoxOf(positions) {
+ const low = [Infinity, Infinity, Infinity];
+ const high = [-Infinity, -Infinity, -Infinity];
+ for (let offset = 0; offset < positions.length; offset += 3) {
+ for (let axis = 0; axis < 3; axis++) {
+ low[axis] = Math.min(low[axis], positions[offset + axis]);
+ high[axis] = Math.max(high[axis], positions[offset + axis]);
+ }
+ }
+ return { low, high };
+}
+
+/**
+ * The scene with copies of one geometry kept as instances: `instances` (geometry, matrix, materialIndex, visibility) over
+ * the unique geometries, and `materials` indexed by part, with no world-space triangle arrays and no CPU BVH. Only
+ * `buildNativeInputV2` reads this shape, for the native "cycles" kernel.
+ */
+function buildInstancedTraceScene(parts, geometries, environment, localVolumes) {
+ requireInstancedCaps(parts, measureInstancedParts(parts, geometries));
+ const materials = parts.map(part => ({ ...(part.material ?? {}), ...resolveMaterial(part.material ?? {}) }));
+ const instances = parts.map((part, index) => instanceFor(part, geometries[index], index, materials[index]));
+ const extent = instancedExtent(instances);
+ return {
+ instances,
+ materials,
+ lights: resolveLights(environment),
+ environment: resolveEnvironment(environment.map),
+ volume: resolveTraceVolume(environment.volumeFog),
+ localVolumes,
+ surfaceOffset: extent * 1e-5,
+ farDistance: extent * 1e4,
+ };
+}
+
+/**
+ * Builds the scene a path trace reads. With `options.instancing` and at least one geometry shared by two parts, the result
+ * holds `instances` instead of flattened triangles (see `buildInstancedTraceScene`); with no shared geometry, or without the
+ * option, it is the flattened scene, unchanged.
+ */
+export function buildTraceScene(allParts, environment = {}, options = {}) {
const { volumes: localVolumes, boundsOnlyParts } = resolveTraceLocalVolumes(environment.localVolumes, allParts);
const parts = boundsOnlyParts.length ? allParts.filter(part => !boundsOnlyParts.includes(part)) : allParts;
+ const tryInstancing = options.instancing === true && Array.isArray(parts) && parts.length > 0;
+ const geometries = tryInstancing ? parts.map(traceGeometry) : undefined;
+ if (tryInstancing && countSharedGeometries(parts, geometries) > 0) return buildInstancedTraceScene(parts, geometries, environment, localVolumes);
if (!Array.isArray(parts) || parts.length < 1 || parts.length > MAX_TRACE_PARTS) throw new RangeError(`A path trace takes 1 to ${MAX_TRACE_PARTS} parts.`);
- const geometry = flattenParts(parts);
+ const geometry = flattenParts(parts, geometries);
const bvh = buildTriangleBvh(geometry.positions, geometry.indices);
let extent = 1e-3;
for (let index = 0; index < geometry.positions.length; index++) extent = Math.max(extent, Math.abs(geometry.positions[index]));
diff --git a/tests/path-tracer-instancing.test.js b/tests/path-tracer-instancing.test.js
new file mode 100644
index 00000000..b8bd38eb
--- /dev/null
+++ b/tests/path-tracer-instancing.test.js
@@ -0,0 +1,160 @@
+import assert from 'node:assert/strict';
+import test from 'node:test';
+import { buildNativeInput, buildNativeInputV2, STRUCT_STRIDES_V2 } from '../packages/render-native/index.mjs';
+import { createCamera } from '../src/path-tracer.js';
+import * as pack from '../src/path-tracer-gpu-pack.js';
+import { MAX_TRACE_INSTANCES, MAX_TRACE_PARTS, MAX_TRACE_TRIANGLES, buildTraceScene } from '../src/path-tracer-scene.js';
+
+function quadGeometry(z = 0) {
+ return {
+ positions: new Float32Array([-1, -1, z, 1, -1, z, 1, 1, z, -1, 1, z]),
+ normals: new Float32Array([0, 0, 1, 0, 0, 1, 0, 0, 1, 0, 0, 1]),
+ uvs: new Float32Array([0, 1, 1, 1, 1, 0, 0, 0]),
+ indices: new Uint32Array([0, 1, 2, 0, 2, 3]),
+ };
+}
+
+// A strip of `triangleCount` triangles on a few vertices: enough to hit a triangle cap without a large allocation.
+function heavyGeometry(triangleCount) {
+ const indices = new Uint32Array(triangleCount * 3);
+ for (let slot = 0; slot < indices.length; slot++) indices[slot] = slot % 3;
+ return {
+ positions: new Float32Array([0, 0, 0, 1, 0, 0, 0, 1, 0]),
+ normals: new Float32Array([0, 0, 1, 0, 0, 1, 0, 0, 1]),
+ indices,
+ };
+}
+
+function translation(x, y = 0, z = 0) {
+ return [1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1, 0, x, y, z, 1];
+}
+
+function copiesOf(geometry, count, material = { color: [0.5, 0.5, 0.5] }) {
+ return Array.from({ length: count }, (_, index) => ({ name: `copy-${index}`, geometry, matrix: translation(index * 3), material }));
+}
+
+const FLATTENED_FIELDS = ['positions', 'normals', 'uvs', 'colors', 'indices', 'triangleMaterial'];
+
+test('without the instancing option every scene is flattened, and a scene with no shared geometry is unchanged by the option', () => {
+ const parts = [
+ { name: 'a', geometry: quadGeometry(0), matrix: translation(0), material: { color: [1, 0, 0] } },
+ { name: 'b', geometry: quadGeometry(1), matrix: translation(4), material: { color: [0, 1, 0] }, shadowOnly: true },
+ ];
+ const plain = buildTraceScene(parts, {});
+ const optedIn = buildTraceScene(parts, {}, { instancing: true });
+ assert.equal(plain.instances, undefined);
+ assert.equal(optedIn.instances, undefined);
+ for (const field of FLATTENED_FIELDS) assert.deepEqual(optedIn[field], plain[field], field);
+ assert.deepEqual(optedIn.materials, plain.materials);
+ assert.deepEqual(optedIn.shadowOnlyParts, plain.shadowOnlyParts);
+ assert.equal(optedIn.surfaceOffset, plain.surfaceOffset);
+ assert.equal(optedIn.farDistance, plain.farDistance);
+
+ const shared = copiesOf(quadGeometry(), 3);
+ assert.equal(buildTraceScene(shared, {}).instances, undefined);
+ assert.equal(buildTraceScene(shared, {}, { instancing: false }).instances, undefined);
+});
+
+test('parts that share one geometry become instances of it, in part order', () => {
+ const geometry = quadGeometry();
+ const parts = copiesOf(geometry, 5);
+ const scene = buildTraceScene(parts, {}, { instancing: true });
+ assert.equal(scene.positions, undefined);
+ assert.equal(scene.bvh, undefined);
+ assert.equal(scene.instances.length, 5);
+ scene.instances.forEach((instance, index) => {
+ assert.equal(instance.geometry, geometry);
+ assert.deepEqual(instance.matrix, parts[index].matrix);
+ assert.equal(instance.materialIndex, index);
+ assert.equal(instance.objectId, index);
+ assert.equal(instance.visibilityFlags, undefined);
+ });
+ assert.equal(scene.materials.length, 5);
+ assert.deepEqual(scene.materials[0].color, [0.5, 0.5, 0.5]);
+});
+
+test('a part whose geometry is rebuilt for the trace stays flattened into world space beside the shared ones', () => {
+ const geometry = quadGeometry();
+ const boxMapped = { name: 'boxed', geometry, matrix: translation(10), material: { color: [1, 1, 1], boxMapScale: 1 } };
+ const parts = [...copiesOf(geometry, 2), boxMapped];
+ const scene = buildTraceScene(parts, {}, { instancing: true });
+ const [first, second, baked] = scene.instances;
+ assert.equal(first.geometry, geometry);
+ assert.equal(second.geometry, geometry);
+ assert.notEqual(baked.geometry, geometry);
+ assert.deepEqual(baked.matrix, [1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1]);
+ assert.equal(baked.geometry.triangleMaterial, undefined);
+ assert.equal(baked.geometry.positions[0], 9);
+});
+
+test('a shadow-only part is an instance the camera does not see', () => {
+ const parts = copiesOf(quadGeometry(), 2);
+ parts[1].shadowOnly = true;
+ const scene = buildTraceScene(parts, {}, { instancing: true });
+ assert.equal(scene.instances[0].visibilityFlags, undefined);
+ assert.equal(scene.instances[1].visibilityFlags, 2 | 4 | 8 | 16 | 32);
+});
+
+test('the extent that scales the ray offsets covers every instance', () => {
+ const parts = copiesOf(quadGeometry(), 3);
+ const flattened = buildTraceScene(parts, {});
+ const instanced = buildTraceScene(parts, {}, { instancing: true });
+ assert.equal(instanced.surfaceOffset, flattened.surfaceOffset);
+ assert.equal(instanced.farDistance, flattened.farDistance);
+});
+
+test('the triangle cap counts unique triangles, so shared copies pass where the flattened scene fails', () => {
+ const geometry = heavyGeometry(500);
+ const parts = copiesOf(geometry, 1000);
+ assert.throws(() => buildTraceScene(parts, {}), /triangles in total/);
+ assert.equal(buildTraceScene(parts, {}, { instancing: true }).instances.length, 1000);
+});
+
+test('the part cap bounds distinct geometries for an instanced scene, and copies have their own cap', () => {
+ const shared = quadGeometry();
+ const pastPartCap = copiesOf(shared, MAX_TRACE_PARTS + 76);
+ assert.throws(() => buildTraceScene(pastPartCap, {}), /1 to 1024 parts/);
+ assert.equal(buildTraceScene(pastPartCap, {}, { instancing: true }).instances.length, MAX_TRACE_PARTS + 76);
+
+ const manyGeometries = [...copiesOf(shared, 2), ...Array.from({ length: MAX_TRACE_PARTS }, () => ({ geometry: quadGeometry(), matrix: translation(0), material: { color: [1, 1, 1] } }))];
+ assert.throws(() => buildTraceScene(manyGeometries, {}, { instancing: true }), /at most 1024 distinct geometries, got 1025.*Share one geometry object/);
+
+ const tooManyCopies = copiesOf(shared, MAX_TRACE_INSTANCES + 1);
+ assert.throws(() => buildTraceScene(tooManyCopies, {}, { instancing: true }), /at most 65536 instances, got 65537.*fewer parts/);
+});
+
+test('unique triangles past the cap are refused with what to change', () => {
+ const half = MAX_TRACE_TRIANGLES / 2 + 1;
+ const parts = [...copiesOf(heavyGeometry(half), 2), ...copiesOf(heavyGeometry(half), 2)];
+ assert.throws(() => buildTraceScene(parts, {}, { instancing: true }), /at most 400000 unique triangles.*got 400002.*Share geometry/);
+});
+
+test('an invalid matrix or geometry in an instanced scene is named by its part', () => {
+ const parts = copiesOf(quadGeometry(), 2);
+ parts[1].matrix = translation(Number.NaN);
+ assert.throws(() => buildTraceScene(parts, {}, { instancing: true }), /Part copy-1 matrix must be finite/);
+ const brokenGeometry = quadGeometry();
+ brokenGeometry.indices = new Uint32Array([0, 1, 9]);
+ assert.throws(() => buildTraceScene(copiesOf(brokenGeometry, 2), {}, { instancing: true }), /index past its last vertex/);
+});
+
+test('N copies of one mesh pack as one geometry record set and N instance records', () => {
+ const camera = createCamera({ eye: [0, 0, 40], target: [0, 0, 0], fov: 45 }, 16, 16);
+ const copyCount = 200;
+ const parts = copiesOf(quadGeometry(), copyCount);
+ const instanced = buildNativeInputV2(buildTraceScene(parts, {}, { instancing: true }), camera, { width: 16, height: 16, samples: 1 });
+ const flattened = buildNativeInputV2(buildTraceScene(parts, {}), camera, { width: 16, height: 16, samples: 1 });
+ assert.equal(instanced.instanceCount, copyCount);
+ assert.equal(instanced.triangleCount, 2);
+ assert.equal(instanced.triangles.byteLength, 2 * STRUCT_STRIDES_V2.triangle);
+ assert.equal(instanced.instances.byteLength, copyCount * STRUCT_STRIDES_V2.instance);
+ assert.equal(flattened.instanceCount, copyCount);
+ assert.equal(flattened.triangleCount, copyCount * 2);
+ assert.ok(instanced.triangles.byteLength < flattened.triangles.byteLength);
+});
+
+test('the legacy v1 packer refuses an instanced scene and says what to use instead', () => {
+ const camera = createCamera({ eye: [0, 0, 40], target: [0, 0, 0], fov: 45 }, 16, 16);
+ const scene = buildTraceScene(copiesOf(quadGeometry(), 3), {}, { instancing: true });
+ assert.throws(() => buildNativeInput(scene, camera, { width: 16, height: 16, samples: 1, bounces: 2, seed: 1 }, pack), /cannot read instances.*buildNativeInputV2.*"cycles"/);
+});