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.mjsnew file mode 100644index 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.mdnew file mode 100644index 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.mdindex 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 diffuAlso 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 backenddiff --git a/packages/render-native/pack-input.mjs b/packages/render-native/pack-input.mjsindex 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.jsindex 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.jsnew file mode 100644index 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"/);+});