3D engine that AI agents drive
Pack shared-mesh emissive offsets per emitting triangle and send instanced scenes to native jobs (#896)
Nguyen Xuan An933930273459
diff --git a/bench/instancing/copies-scene.mjs b/bench/instancing/copies-scene.mjsindex c2a1447d..924372da 100644--- a/bench/instancing/copies-scene.mjs+++ b/bench/instancing/copies-scene.mjs@@ -1,7 +1,8 @@// The scene of the instancing benches and the equivalence test: N copies of one small mesh placed on a grid.// A variant sets how the copies are placed: translate, rotscale (rotated, non-uniform scale), mirror (negative-// determinant), mirror-rotscale, or emissive (translate, with one emissive material).-export const COPY_VARIANTS = ['translate', 'rotscale', 'mirror', 'mirror-rotscale', 'emissive'];+// determinant), mirror-rotscale, emissive (translate, with one emissive material), emissive-rotscale (the same rotated and stretched), or+// emissive-degenerate (emissive, on a mesh whose first triangle has no area, so emissive entries skip it).+export const COPY_VARIANTS = ['translate', 'rotscale', 'mirror', 'mirror-rotscale', 'emissive', 'emissive-rotscale', 'emissive-degenerate'];function midpoint(positions, first, second) {return [0, 1, 2].map(axis => (positions[first * 3 + axis] + positions[second * 3 + axis]) / 2);@@ -80,7 +81,7 @@ function buildParts(geometry, variant, copyCount) {const layer = Math.floor(index / (side * side));const translation = [(column - side / 2) * 1.1, (row - side / 2) * 1.1, -layer * 1.1];const matrix = transformMatrix(scalesFor(variant, index), rotates ? 0.4 + index * 0.37 : 0, translation);- const material = variant === 'emissive' && index % 4 === 0 ? EMISSIVE_MATERIAL : MATERIALS[index % MATERIALS.length];+ const material = variant.startsWith('emissive') && index % 4 === 0 ? EMISSIVE_MATERIAL : MATERIALS[index % MATERIALS.length];return { name: `copy-${index}`, geometry, matrix, material };});}@@ -88,6 +89,7 @@ function buildParts(geometry, variant, copyCount) {export function buildCopyScene(variant, copyCount) {if (!COPY_VARIANTS.includes(variant)) throw new RangeError(`Pass one of ${COPY_VARIANTS.join(', ')} as the variant.`);- const geometry = icosphere(2);+ const sphere = icosphere(2);+ const geometry = variant === 'emissive-degenerate' ? { ...sphere, indices: Uint32Array.from([0, 0, 0, ...sphere.indices]) } : sphere;return { geometry, parts: buildParts(geometry, variant, copyCount), environment: { keyColor: [3, 3, 3], lightDirection: [0.4, 0.8, 0.5] } };}diff --git a/bench/instancing/image-compare.mjs b/bench/instancing/image-compare.mjsnew file mode 100644index 00000000..7e4823fe--- /dev/null+++ b/bench/instancing/image-compare.mjs@@ -0,0 +1,48 @@+// Image measures of the instancing equivalence test and bench: how far an instanced render sits from the flattened one.++/** Mean squared error over RGB, each term divided by the reference squared plus `epsilon` (0.01 keeps dark pixels from dominating). */+export function relativeMeanSquaredError(candidate, reference, pixelCount, epsilon = 0.01) {+ let total = 0;+ for (let pixel = 0; pixel < pixelCount; pixel++) {+ for (let channel = 0; channel < 3; channel++) {+ const expected = reference[pixel * 4 + channel];+ const difference = candidate[pixel * 4 + channel] - expected;+ total += (difference * difference) / (expected * expected + epsilon);+ }+ }+ return total / (pixelCount * 3);+}++/** Candidate sum over reference sum for each tile of a grid, leaving out tiles too dark to compare. */+export function tileMeanRatios(candidate, reference, width, height, tiles = 8) {+ const ratios = [];+ for (let tileRow = 0; tileRow < tiles; tileRow++) {+ for (let tileColumn = 0; tileColumn < tiles; tileColumn++) {+ let candidateSum = 0;+ let referenceSum = 0;+ for (let row = Math.floor(tileRow * height / tiles); row < Math.floor((tileRow + 1) * height / tiles); row++) {+ for (let column = Math.floor(tileColumn * width / tiles); column < Math.floor((tileColumn + 1) * width / tiles); column++) {+ for (let channel = 0; channel < 3; channel++) {+ candidateSum += candidate[(row * width + column) * 4 + channel];+ referenceSum += reference[(row * width + column) * 4 + channel];+ }+ }+ }+ if (referenceSum > 1e-3) ratios.push(candidateSum / referenceSum);+ }+ }+ return ratios;+}++/** Candidate mean over reference mean for each of R, G and B. */+export function meanRatioRgb(candidate, reference, pixelCount) {+ const candidateSums = [0, 0, 0];+ const referenceSums = [0, 0, 0];+ for (let pixel = 0; pixel < pixelCount; pixel++) {+ for (let channel = 0; channel < 3; channel++) {+ candidateSums[channel] += candidate[pixel * 4 + channel];+ referenceSums[channel] += reference[pixel * 4 + channel];+ }+ }+ return candidateSums.map((sum, channel) => sum / referenceSums[channel]);+}diff --git a/bench/instancing/instancing-checks.mjs b/bench/instancing/instancing-checks.mjsnew file mode 100644index 00000000..43f73d88--- /dev/null+++ b/bench/instancing/instancing-checks.mjs@@ -0,0 +1,119 @@+// Two checks of the instancing export, run from the root of one source tree:+// node bench/instancing/instancing-checks.mjs identity <output json>+// SHA-256 of every packed table and of the traced pixels for scenes without shared geometry (and of an instanced scene+// packed as before), so the same file from two trees can be compared. Pass `--pack-only` to skip the traces.+// node bench/instancing/instancing-checks.mjs equivalence <output json> [copies] [samples]+// Instanced against flattened renders: mean ratio, relative MSE (epsilon 0.01) and the 8x8 tiles within 5 percent.+import { createHash } from 'node:crypto';+import { writeFileSync } from 'node:fs';+import { buildNativeInputV2, findNativeAddon, traceNative } from '../../packages/render-native/index.mjs';+import { buildNativeInput } from '../../packages/render-native/pack-input.mjs';+import { buildCopyScene } from './copies-scene.mjs';+import { meanRatioRgb, relativeMeanSquaredError, tileMeanRatios } from './image-compare.mjs';+import { createCamera } from '../../src/path-tracer.js';+import * as pack from '../../src/path-tracer-gpu-pack.js';+import { buildTraceScene } from '../../src/path-tracer-scene.js';++const [mode, outputPath, ...rest] = process.argv.slice(2);+const packOnly = rest.includes('--pack-only');+const numbers = rest.filter(argument => !argument.startsWith('--')).map(Number);++function hashBytes(values) {+ return createHash('sha256').update(new Uint8Array(values.buffer, values.byteOffset, values.byteLength)).digest('hex');+}++function hashTables(input) {+ const hashes = {};+ for (const [name, value] of Object.entries(input)) {+ if (ArrayBuffer.isView(value)) hashes[name] = hashBytes(value);+ else if (typeof value === 'number') hashes[name] = value;+ }+ return hashes;+}++// The same copies, each on a geometry object of its own, so no geometry is shared.+function withDistinctGeometry(parts) {+ return parts.map(part => ({+ ...part,+ geometry: { ...part.geometry, positions: Float32Array.from(part.geometry.positions) },+ }));+}++function traceHash(input, kernel, width, height) {+ try {+ const traced = traceNative(input, { width, height, samples: 16, kernel });+ return { hash: hashBytes(traced.rgba), adapter: traced.adapter };+ } catch (error) {+ return { skipped: error.message.split('\n')[0] };+ }+}++function identityScenes() {+ const width = 48;+ const height = 32;+ const camera = createCamera({ eye: [0, 0, 14], target: [0, 0, -3], fov: 50 }, width, height);+ const options = { width, height, samples: 16, seed: 1 };+ const report = {};+ for (const variant of ['translate', 'rotscale', 'emissive']) {+ const { parts, environment } = buildCopyScene(variant, 12);+ const flattened = buildTraceScene(parts, environment);+ const unshared = buildTraceScene(withDistinctGeometry(parts), environment, { instancing: true });+ const instanced = buildTraceScene(parts, environment, { instancing: true });+ const inputs = {+ flattenedV1: buildNativeInput(flattened, camera, options, pack),+ flattenedV2: buildNativeInputV2(flattened, camera, options),+ unsharedV2: buildNativeInputV2(unshared, camera, options),+ instancedV2: buildNativeInputV2(instanced, camera, options),+ };+ const entry = { sceneWithoutSharing: unshared.instances === undefined };+ for (const [name, input] of Object.entries(inputs)) entry[name] = hashTables(input);+ if (!packOnly && findNativeAddon()) {+ entry.trace = {+ legacyFlattenedV1: traceHash(inputs.flattenedV1, 'legacy', width, height),+ cyclesFlattenedV1: traceHash(inputs.flattenedV1, 'cycles', width, height),+ cyclesFlattenedV2: traceHash(inputs.flattenedV2, 'cycles', width, height),+ cyclesInstancedV2: traceHash(inputs.instancedV2, 'cycles', width, height),+ };+ }+ report[variant] = entry;+ }+ return report;+}++function render(variant, instancing, copies, samples, width, height) {+ const { parts, environment } = buildCopyScene(variant, copies);+ const camera = createCamera({ eye: [0, 0, 14], target: [0, 0, -3], fov: 50 }, width, height);+ const scene = buildTraceScene(parts, environment, { instancing });+ const input = buildNativeInputV2(scene, camera, { width, height, samples, seed: 1 });+ const traced = traceNative(input, { width, height, samples, kernel: 'cycles' });+ return { rgba: traced.rgba, adapter: traced.adapter, triangleCount: input.triangleCount, instanceCount: input.instanceCount };+}++function equivalenceReport(copies, samples) {+ const width = 128;+ const height = 96;+ const report = {};+ for (const variant of ['translate', 'rotscale', 'emissive', 'emissive-rotscale', 'emissive-degenerate']) {+ const flattened = render(variant, false, copies, samples, width, height);+ const instanced = render(variant, true, copies, samples, width, height);+ const ratios = tileMeanRatios(instanced.rgba, flattened.rgba, width, height, 8);+ report[variant] = {+ adapter: instanced.adapter,+ copies,+ samples,+ flattenedTriangles: flattened.triangleCount,+ instancedTriangles: instanced.triangleCount,+ meanRatioRgb: meanRatioRgb(instanced.rgba, flattened.rgba, width * height).map(value => Number(value.toFixed(4))),+ relativeMse: Number(relativeMeanSquaredError(instanced.rgba, flattened.rgba, width * height, 0.01).toPrecision(3)),+ tilesWithin5Percent: ratios.filter(ratio => Math.abs(ratio - 1) <= 0.05).length,+ eligibleTiles: ratios.length,+ };+ }+ return report;+}++if (mode !== 'identity' && mode !== 'equivalence') throw new RangeError('Pass "identity" or "equivalence" as the first argument, then an output path.');+if (!outputPath) throw new RangeError('Pass the output JSON path as the second argument.');+const result = mode === 'identity' ? identityScenes() : equivalenceReport(numbers[0] ?? 200, numbers[1] ?? 1024);+writeFileSync(outputPath, JSON.stringify(result, null, 2));+console.log(JSON.stringify(result));diff --git a/packages/render-native/index.mjs b/packages/render-native/index.mjsindex f089ddcb..21063647 100644--- a/packages/render-native/index.mjs+++ b/packages/render-native/index.mjs@@ -86,7 +86,7 @@ export function traceNative(input, options = {}) {}if (input?.schemaVersion === FORMAT_V2_VERSION) {throw new TypeError(- 'Cannot pass a FORMAT-v2 scene input to kernel "legacy": pass kernel "cycles" or build a v1 input with buildNativeInput.'+ 'Cannot pass a FORMAT-v2 scene input to kernel "legacy": pass kernel "cycles" or build a v1 input with buildNativeInput (an instanced scene needs kernel "cycles"; build it without { instancing: true } for kernel "legacy").');}return addon.traceScene(input, { width, height, samples, maxSeconds, kernel: selectedKernel });diff --git a/packages/render-native/pack-input-v2.mjs b/packages/render-native/pack-input-v2.mjsindex 7a73d5a8..7694dcf9 100644--- a/packages/render-native/pack-input-v2.mjs+++ b/packages/render-native/pack-input-v2.mjs@@ -2078,6 +2078,25 @@ function appendWorldEmissiveIfActive({return emittedIndex;}+// Triangle records are shared by every copy of a mesh, so one `local_emissive_offset` per triangle has to fit every instance that+// emits: the instance's entries are the triangles that kept an area, in order, whichever material the instance resolves to.+// The first emitting instance sets the offsets; a later one must emit the same triangles.+function shareEmissiveOffsets(meshSlot, emittedLocalIndices, instanceIndex) {+ if (emittedLocalIndices.length === 0) return;+ if (!meshSlot.emissiveLocalIndices) {+ meshSlot.emissiveLocalIndices = emittedLocalIndices;+ emittedLocalIndices.forEach((localIdx, offset) => {+ meshSlot.ordered[localIdx].localEmissiveOffset = offset;+ });+ return;+ }+ const reference = meshSlot.emissiveLocalIndices;+ const matches = reference.length === emittedLocalIndices.length && reference.every((localIdx, offset) => localIdx === emittedLocalIndices[offset]);+ if (!matches) {+ throw new RangeError(`Instance[${instanceIndex}] scales some emissive triangles of its shared mesh to no area, so its emissive entries differ from the other copies. Give it a scale that keeps every triangle, or remove its emissive material.`);+ }+}+function packInstancedGeometry(instancesInput, rawMaterials, textureCollector) {const materialRecords = rawMaterials.map(mat => packMaterialRecordV2(mat, textureCollector));const materialsBuffer = new Uint8Array(Math.max(1, materialRecords.length) * STRUCT_STRIDES_V2.material);@@ -2140,14 +2159,10 @@ function packInstancedGeometry(instancesInput, rawMaterials, textureCollector) {const opaqueTriangleCount = opaque.length;const totalTriangleCount = ordered.length;- let localEmissiveCounter = 0;for (const item of ordered) {- if (materialRecords[item.materialIndex]?.isEmissive) {- item.localEmissiveOffset = localEmissiveCounter++;- }allTriangles.push(item);}- meshSlot = { blasIndex, defaultMaterialIndex, triangleOffset, opaqueTriangleCount, totalTriangleCount, ordered };+ meshSlot = { blasIndex, defaultMaterialIndex, triangleOffset, opaqueTriangleCount, totalTriangleCount, ordered, emissiveLocalIndices: null };meshCache.set(geometry, meshSlot);} else if (materialOverride === INVALID_INDEX_V2 &&@@ -2165,7 +2180,7 @@ function packInstancedGeometry(instancesInput, rawMaterials, textureCollector) {const visibilityFlags = (baseVisibility | (decomposed.negativeScale ? INSTANCE_FLAG_NEGATIVE_SCALE : 0)) >>> 0;let emissiveBaseOffset = INVALID_INDEX_V2;- let instanceEmissiveCount = 0;+ const emittedLocalIndices = [];for (let localIdx = 0; localIdx < meshSlot.ordered.length; localIdx++) {const triItem = meshSlot.ordered[localIdx];const globalTriIdx = meshSlot.triangleOffset + localIdx;@@ -2186,12 +2201,10 @@ function packInstancedGeometry(instancesInput, rawMaterials, textureCollector) {if (emissiveBaseOffset === INVALID_INDEX_V2) {emissiveBaseOffset = emittedIdx;}- if (triItem.localEmissiveOffset === INVALID_INDEX_V2) {- triItem.localEmissiveOffset = instanceEmissiveCount;- }- instanceEmissiveCount++;+ emittedLocalIndices.push(localIdx);}}+ shareEmissiveOffsets(meshSlot, emittedLocalIndices, instIdx);const objectId = (inst.objectId ?? instIdx) >>> 0;instanceItems.push({diff --git a/scripts/agent-native-trace.mjs b/scripts/agent-native-trace.mjsindex 4e4b3adc..95ffee23 100644--- a/scripts/agent-native-trace.mjs+++ b/scripts/agent-native-trace.mjs@@ -67,7 +67,24 @@ export async function chooseTraceBackend({ requested, runtimeBackend, locator })return { backend: fallback, note: `${found.reason} The ${fallback} backend ran instead.` };}+const V2_TABLE_TYPES = { Uint8Array, Uint32Array, Int32Array, Float32Array };++// The FORMAT-v2 input of an instanced scene: the page names each table's array type and sends the record counts.+function decodeTablesV2(exported) {+ const input = { schemaVersion: exported.schemaVersion, ...exported.counts };+ for (const [name, base64] of Object.entries(exported.tables)) {+ const View = V2_TABLE_TYPES[exported.types?.[name]];+ if (!View) throw new TypeError(`The exported native scene table "${name}" has an unknown array type ${JSON.stringify(exported.types?.[name])}.`);+ const bytes = Buffer.from(base64, 'base64');+ const copy = new Uint8Array(bytes.length);+ copy.set(bytes);+ input[name] = new View(copy.buffer, 0, copy.length / View.BYTES_PER_ELEMENT);+ }+ return input;+}+function decodeTables(exported) {+ if (exported.schemaVersion !== undefined) return decodeTablesV2(exported);const input = { triangleCount: exported.triangleCount };for (const name of TABLE_NAMES) {const bytes = Buffer.from(exported.tables[name], 'base64');@@ -173,7 +190,7 @@ export async function traceFrameNative({ tracer, exported, width, height, sampleconst report = { width, height, samples, bounces, seed, denoised: false, denoiser: 'none', threads: 1, backend: 'native',gpu: traced.adapter, nativeBackend: traced.backend, nativeFeatures: traced.features, setupSeconds: traced.setupSeconds, compileSeconds: traced.compileSeconds,uploadSeconds: traced.uploadSeconds, accelerationBuildSeconds: traced.accelerationBuildSeconds,- kernel, averageSamples: traced.averageSamples ?? samples, noiseThreshold, triangles: exported.triangles, tracedSeconds, ignored: exported.ignored };+ kernel, averageSamples: traced.averageSamples ?? samples, noiseThreshold, triangles: exported.triangles, ...(exported.instances === undefined ? {} : { instances: exported.instances }), tracedSeconds, ignored: exported.ignored };let linear = features.color;const denoiseStarted = performance.now();if (denoise === 'oidn') {diff --git a/scripts/agent-preview-browser.js b/scripts/agent-preview-browser.jsindex 19e2c261..dd938719 100644--- a/scripts/agent-preview-browser.js+++ b/scripts/agent-preview-browser.js@@ -1,4 +1,4 @@-import { encodeNativeTables, nativeTexelTracerIfAvailable } from './native-bake-page.js';+import { encodeNativeInputV2, encodeNativeTables, nativeTexelTracerIfAvailable } from './native-bake-page.js';import { buildWithKernels, kernelWorkersAvailable, kernelStats, resetKernelStats } from '../src/kernel-offload.js';import { createAgentScene, applyCameraFields, loadAllAgentSceneModules, allAgentSceneModulesLoaded, needsMeshBooleans, loadMeshBooleans, meshBooleansLoaded, setManifoldModuleLoader, needsPhysics, loadPhysicsEngine, physicsEngineLoaded, setPhysicsModuleLoader } from '../src/agent-scene.js';import { Renderer67 } from '../src/renderer.js';@@ -829,6 +829,15 @@ function paintLabels(context, labels, offsetX, offsetY) {}}+// An instanced scene as FORMAT-v2 tables: the unique triangles once and one record per copy. `types` names each table's typed+// array and `counts` carries the record counts, so the job runner can rebuild the input for the "cycles" kernel.+async function exportInstancedNativeScene(traceScene, camera, options, ignored) {+ const { buildNativeInputV2 } = await import('../packages/render-native/pack-input-v2.mjs');+ const { fireflyClamp, ...packOptions } = options;+ const input = buildNativeInputV2(traceScene, camera, packOptions);+ return { ...encodeNativeInputV2(input), triangleCount: input.triangleCount, triangles: input.triangleCount, instances: input.instanceCount, ignored };+}+window.__agentPreview = {reviewBegin({ width, height }) {reviewGrid = document.createElement('canvas');@@ -989,17 +998,20 @@ window.__agentPreview = {} else if (motionTime !== undefined) {record.scene.sampleMotion(motionTime);}+ const { instancing, ...packOptions } = options;const [{ createCamera, describeIgnoredFeatures }, { buildTraceScene, refuseLocalVolumes }, pack, { buildNativeInput }] = await Promise.all([import('../src/path-tracer.js'), import('../src/path-tracer-scene.js'), import('../src/path-tracer-gpu-pack.js'),import('../packages/render-native/pack-input.mjs'),]);const environment = { ...record.scene.environment, map: agentEnvironmentMap(record.scene.environment) };- const traceScene = buildTraceScene(record.scene.parts, environment);+ // Copies of one geometry stay instances only when the job traces with the "cycles" kernel; the legacy kernel reads flattened triangles.+ const traceScene = buildTraceScene(record.scene.parts, environment, { instancing: instancing === true });refuseLocalVolumes(traceScene, 'the native path tracer');const camera = createCamera(record.scene.camera, options.width, options.height);- const input = buildNativeInput(traceScene, camera, options, pack);- const tables = encodeNativeTables(input);const ignored = describeIgnoredFeatures(record.scene.parts, environment);+ if (traceScene.instances) return exportInstancedNativeScene(traceScene, camera, packOptions, ignored);+ const input = buildNativeInput(traceScene, camera, packOptions, pack);+ const tables = encodeNativeTables(input);return { tables, triangleCount: input.triangleCount, triangles: traceScene.indices.length / 3, ignored };},// The PNG of linear pixels (three floats each, base64) that a denoiser outside the page returned, or of the waveletdiff --git a/scripts/agent-runtime.mjs b/scripts/agent-runtime.mjsindex f20b7b5e..d9debc0b 100644--- a/scripts/agent-runtime.mjs+++ b/scripts/agent-runtime.mjs@@ -15,7 +15,7 @@ import { MATERIAL_SNIPPET_CAPABILITIES } from '../src/material-snippet.js';import { AGENT_SCENE_CAPABILITIES, AGENT_SCENE_DEFAULT_LIMITS, RENDER_PASS_NAMES, RENDER_PASS_DEPTH_RANGE, VIDEO_ENCODERS, MAXIMUM_VIDEO_SECONDS, MAXIMUM_JOB_SIDE, MAXIMUM_JOB_PIXELS, MAXIMUM_MEMORY_MIB, BAKE_WORKER_MAXIMUM_SECONDS } from '../src/agent-scene-capabilities.js';import { PATH_TRACER_CAPABILITIES } from '../src/path-tracer-capabilities.js';import { chooseDenoiser, finishWithOidn } from './agent-path-trace-denoise.mjs';-import { chooseTraceBackend, createNativeTracerLocator, isNativeTimeLimitError, traceFrameNative, traceTexelsNative } from './agent-native-trace.mjs';+import { chooseNativeKernel, chooseTraceBackend, createNativeTracerLocator, isNativeTimeLimitError, traceFrameNative, traceTexelsNative } from './agent-native-trace.mjs';import { createAgentAssetCatalog } from './agent-asset-catalog.mjs';import { geometryOnlyGlb } from './agent-query-asset.mjs';import { AGENT_ASSET_LIMITS, assertCombinedAssetBytes } from '../src/agent-asset-limits.js';@@ -565,7 +565,7 @@ export function createAgentRuntime({ kernelWorkers = true, backend = 'gpu', browlet backendNote = trace.note;if (trace.backend === 'native') {try {- const exported = await jobPage.evaluate(input => window.__agentPreview.exportNativeScene(input), { ...frameInput, options: { width, height, bounces: tracerOptions.bounces, seed: tracerOptions.seed, fireflyClamp: 20, noiseThreshold: tracerOptions.noiseThreshold } });+ const exported = await jobPage.evaluate(input => window.__agentPreview.exportNativeScene(input), { ...frameInput, options: { width, height, bounces: tracerOptions.bounces, seed: tracerOptions.seed, fireflyClamp: 20, noiseThreshold: tracerOptions.noiseThreshold, instancing: chooseNativeKernel() === 'cycles' } });traced = await traceFrameNative({ tracer: trace.tracer, exported, width, height, samples: tracerOptions.samples, bounces: tracerOptions.bounces,seed: tracerOptions.seed, denoise: choice.denoise === true ? 'wavelet' : choice.denoise === false ? 'none' : choice.denoise, denoiser: choice.denoiser,maxSeconds: tracerOptions.maxSeconds, noiseThreshold: tracerOptions.noiseThreshold });diff --git a/scripts/native-bake-page.js b/scripts/native-bake-page.jsindex 70a5d838..1680297a 100644--- a/scripts/native-bake-page.js+++ b/scripts/native-bake-page.js@@ -29,6 +29,20 @@ export function encodeNativeTables(input) {return tables;}+/**+ * A FORMAT-v2 input (an instanced scene) as the job export: the tables as base64, the array type of each table and the record+ * counts, which is all the job runner needs to rebuild the input for the "cycles" kernel.+ */+export function encodeNativeInputV2(input) {+ const counts = {};+ const types = {};+ for (const [name, value] of Object.entries(input)) {+ if (ArrayBuffer.isView(value)) types[name] = value.constructor.name;+ else if (typeof value === 'number') counts[name] = value;+ }+ return { schemaVersion: input.schemaVersion, tables: encodeNativeTables(input), types, counts };+}+function floatsFromBase64(data) {const bytes = bytesFromBase64(data);return new Float32Array(bytes.buffer, bytes.byteOffset, bytes.byteLength / Float32Array.BYTES_PER_ELEMENT);diff --git a/tests/native-instancing-emissive-offsets.test.js b/tests/native-instancing-emissive-offsets.test.jsnew file mode 100644index 00000000..5e843b88--- /dev/null+++ b/tests/native-instancing-emissive-offsets.test.js@@ -0,0 +1,94 @@+import assert from 'node:assert/strict';+import test from 'node:test';+import { buildNativeInputV2, STRUCT_STRIDES_V2 } from '../packages/render-native/index.mjs';+import { createCamera } from '../src/path-tracer.js';++const NO_INDEX = 0xffffffff;+const camera = createCamera({ eye: [0, 0, 6], target: [0, 0, 0], fov: 50 }, 16, 16);++// Four triangles over a strip; the second one has no area, so an emissive pass skips it.+const stripWithDegenerateTriangle = {+ positions: Float32Array.from([0, 0, 0, 1, 0, 0, 0, 1, 0, 1, 1, 0, 2, 0, 0, 2, 1, 0, 3, 0, 0, 3, 1, 0, 1, 1, 0]),+ normals: Float32Array.from([0, 0, 1, 0, 0, 1, 0, 0, 1, 0, 0, 1, 0, 0, 1, 0, 0, 1, 0, 0, 1, 0, 0, 1, 0, 0, 1]),+ indices: Uint32Array.from([0, 1, 2, 1, 3, 8, 1, 4, 3, 4, 5, 3, 3, 8, 8]),+};++const MATTE = { color: [0.7, 0.7, 0.7], roughness: 0.6 };+const WARM_LIGHT = { color: [1, 0.8, 0.6], emission: 4 };+const COOL_LIGHT = { color: [0.6, 0.8, 1], emission: 2 };++function pack(materials, instances) {+ return buildNativeInputV2({ materials, instances, lights: {} }, camera, { width: 16, height: 16, samples: 1 });+}++function words(bytes, stride, index) {+ return new Uint32Array(bytes.buffer, bytes.byteOffset + index * stride, stride / 4);+}++// Every emissive hit reads emissive_triangles[instance.emissive_base_offset + triangle.local_emissive_offset]; that entry must be the+// same instance and the same triangle as the hit.+function assertEmissiveLookups(input) {+ for (let instanceIndex = 0; instanceIndex < input.instanceCount; instanceIndex++) {+ const instance = words(input.instances, STRUCT_STRIDES_V2.instance, instanceIndex);+ const base = instance[32];+ if (base === NO_INDEX) continue;+ const triangleOffset = instance[25];+ let looked = 0;+ for (let local = 0; local < instance[27]; local++) {+ const localOffset = words(input.triangles, STRUCT_STRIDES_V2.triangle, triangleOffset + local)[7];+ if (localOffset === NO_INDEX) continue;+ const emitted = words(input.emissiveTriangles, STRUCT_STRIDES_V2.emissiveTriangle, base + localOffset);+ assert.equal(emitted[7], instanceIndex, `instance ${instanceIndex} triangle ${local} reads another instance's emissive entry`);+ assert.equal(emitted[11], triangleOffset + local, `instance ${instanceIndex} triangle ${local} reads another triangle's emissive entry`);+ looked++;+ }+ assert.ok(looked > 0, `instance ${instanceIndex} has an emissive base and no triangle that reaches it`);+ }+}++test('an emissive default material indexes its emissive entries past a degenerate triangle', () => {+ const input = pack([WARM_LIGHT], [+ { geometry: stripWithDegenerateTriangle, materialIndex: 0 },+ { geometry: stripWithDegenerateTriangle, materialIndex: 0, matrix: [1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1, 0, 0, -2, 0, 1] },+ ]);+ assert.equal(input.emissiveTriangleCount, 6);+ assertEmissiveLookups(input);+});++test('an instance whose override makes the shared mesh emissive gets lookups that match its own entries', () => {+ const input = pack([MATTE, WARM_LIGHT], [+ { geometry: stripWithDegenerateTriangle, materialIndex: 0 },+ { geometry: stripWithDegenerateTriangle, materialIndex: 1, matrix: [1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1, 0, 0, -2, 0, 1] },+ { geometry: stripWithDegenerateTriangle, materialIndex: 1, matrix: [1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1, 0, 0, -4, 0, 1] },+ ]);+ assert.equal(input.emissiveTriangleCount, 6);+ assertEmissiveLookups(input);+});++test('an override that switches emission off and another that switches it back on keep the lookups valid', () => {+ const input = pack([WARM_LIGHT, MATTE, COOL_LIGHT], [+ { geometry: stripWithDegenerateTriangle, materialIndex: 0 },+ { geometry: stripWithDegenerateTriangle, materialIndex: 1, matrix: [1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1, 0, 0, -2, 0, 1] },+ { geometry: stripWithDegenerateTriangle, materialIndex: 2, matrix: [1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1, 0, 0, -4, 0, 1] },+ ]);+ assert.equal(input.emissiveTriangleCount, 6);+ const middle = words(input.instances, STRUCT_STRIDES_V2.instance, 1);+ assert.equal(middle[32], NO_INDEX, 'the matte override has no emissive entries');+ assertEmissiveLookups(input);+});++test('a copy scaled so small that it drops an emissive triangle the others keep is refused with the instance named', () => {+ const bigAndSmall = {+ positions: Float32Array.from([0, 0, 0, 1, 0, 0, 0, 1, 0, 2, 0, 0, 2.05, 0, 0, 2, 0.04, 0]),+ normals: Float32Array.from([0, 0, 1, 0, 0, 1, 0, 0, 1, 0, 0, 1, 0, 0, 1, 0, 0, 1]),+ indices: Uint32Array.from([0, 1, 2, 3, 4, 5]),+ };+ const shrunk = [1e-5, 0, 0, 0, 0, 1e-5, 0, 0, 0, 0, 1e-5, 0, 0, 0, 0, 1];+ assert.throws(+ () => pack([WARM_LIGHT], [+ { geometry: bigAndSmall, materialIndex: 0 },+ { geometry: bigAndSmall, materialIndex: 0, matrix: shrunk },+ ]),+ /Instance\[1\] scales some emissive triangles/,+ );+});diff --git a/tests/native-instancing-equivalence.test.js b/tests/native-instancing-equivalence.test.jsindex 764c7e73..a64cc633 100644--- a/tests/native-instancing-equivalence.test.js+++ b/tests/native-instancing-equivalence.test.js@@ -2,6 +2,7 @@ import assert from 'node:assert/strict';import test from 'node:test';import { buildNativeInputV2, findNativeAddon, traceNative } from '../packages/render-native/index.mjs';import { buildCopyScene } from '../bench/instancing/copies-scene.mjs';+import { meanRatioRgb, relativeMeanSquaredError, tileMeanRatios } from '../bench/instancing/image-compare.mjs';import { createCamera } from '../src/path-tracer.js';import { buildTraceScene } from '../src/path-tracer-scene.js';@@ -22,41 +23,9 @@ function render(variant, instancing, seed) {return traceNative(input, { width: WIDTH, height: HEIGHT, samples: SAMPLES, kernel: 'cycles' }).rgba;}-function relativeMeanSquaredError(candidate, reference) {- let total = 0;- for (let pixel = 0; pixel < WIDTH * HEIGHT; pixel++) {- for (let channel = 0; channel < 3; channel++) {- const expected = reference[pixel * 4 + channel];- const difference = candidate[pixel * 4 + channel] - expected;- total += (difference * difference) / (expected * expected + 0.01);- }- }- return total / (WIDTH * HEIGHT * 3);-}--function tileMeanRatios(candidate, reference) {- const ratios = [];- for (let tileRow = 0; tileRow < TILES; tileRow++) {- for (let tileColumn = 0; tileColumn < TILES; tileColumn++) {- let candidateSum = 0;- let referenceSum = 0;- for (let row = Math.floor(tileRow * HEIGHT / TILES); row < Math.floor((tileRow + 1) * HEIGHT / TILES); row++) {- for (let column = Math.floor(tileColumn * WIDTH / TILES); column < Math.floor((tileColumn + 1) * WIDTH / TILES); column++) {- for (let channel = 0; channel < 3; channel++) {- candidateSum += candidate[(row * WIDTH + column) * 4 + channel];- referenceSum += reference[(row * WIDTH + column) * 4 + channel];- }- }- }- if (referenceSum > 1e-3) ratios.push(candidateSum / referenceSum);- }- }- return ratios;-}-const addonSkip = findNativeAddon() ? false : 'the native addon is not built';-for (const variant of ['translate', 'rotscale', 'emissive']) {+for (const variant of ['translate', 'rotscale', 'emissive', 'emissive-rotscale', 'emissive-degenerate']) {test(`instanced ${variant} copies render the flattened image within tolerance`, { skip: addonSkip }, t => {let flattened;try {@@ -66,7 +35,8 @@ for (const variant of ['translate', 'rotscale', 'emissive']) {throw error;}const instanced = render(variant, true, 1);- assert.ok(relativeMeanSquaredError(instanced, flattened) < 5e-4);- for (const ratio of tileMeanRatios(instanced, flattened)) assert.ok(ratio > 0.98 && ratio < 1.02, `tile mean ratio ${ratio}`);+ for (const ratio of meanRatioRgb(instanced, flattened, WIDTH * HEIGHT)) assert.ok(ratio > 0.98 && ratio < 1.02, `mean ratio ${ratio}`);+ assert.ok(relativeMeanSquaredError(instanced, flattened, WIDTH * HEIGHT) < 5e-4);+ for (const ratio of tileMeanRatios(instanced, flattened, WIDTH, HEIGHT, TILES)) assert.ok(ratio > 0.98 && ratio < 1.02, `tile mean ratio ${ratio}`);});}diff --git a/tests/native-instancing-transport.test.js b/tests/native-instancing-transport.test.jsnew file mode 100644index 00000000..ad784a97--- /dev/null+++ b/tests/native-instancing-transport.test.js@@ -0,0 +1,95 @@+import assert from 'node:assert/strict';+import test from 'node:test';+import { buildNativeInput } from '../packages/render-native/pack-input.mjs';+import { buildNativeInputV2, findNativeAddon, traceNative } from '../packages/render-native/index.mjs';+import { traceFrameNative } from '../scripts/agent-native-trace.mjs';+import { encodeNativeInputV2 } from '../scripts/native-bake-page.js';+import { buildCopyScene } from '../bench/instancing/copies-scene.mjs';+import { createCamera } from '../src/path-tracer.js';+import * as pack from '../src/path-tracer-gpu-pack.js';+import { buildTraceScene } from '../src/path-tracer-scene.js';++const WIDTH = 8;+const HEIGHT = 8;++function instancedInput(variant) {+ const { parts, environment } = buildCopyScene(variant, 6);+ const camera = createCamera({ eye: [0, 0, 14], target: [0, 0, -3], fov: 50 }, WIDTH, HEIGHT);+ const scene = buildTraceScene(parts, environment, { instancing: true });+ return { parts, environment, camera, scene, input: buildNativeInputV2(scene, camera, { width: WIDTH, height: HEIGHT, bounces: 4, seed: 3 }) };+}++function recordingTracer(received) {+ const pixels = WIDTH * HEIGHT;+ return {+ traceNative(input, options) {+ received.push({ input, options });+ return { rgba: new Float32Array(pixels * 4).fill(0.5), albedo: new Float32Array(pixels * 3), normal: new Float32Array(pixels * 3),+ depth: new Float32Array(pixels), variance: new Float32Array(pixels), adapter: 'test adapter', backend: 'test' };+ },+ };+}++test('an instanced scene crosses the page boundary as FORMAT-v2 tables and arrives byte for byte', async () => {+ const { input } = instancedInput('rotscale');+ const exported = JSON.parse(JSON.stringify({ ...encodeNativeInputV2(input), triangleCount: input.triangleCount, triangles: input.triangleCount,+ instances: input.instanceCount, ignored: [] }));+ const received = [];+ const traced = await traceFrameNative({ tracer: recordingTracer(received), exported, width: WIDTH, height: HEIGHT, samples: 4, denoise: 'none', kernel: 'cycles' });+ const arrived = received[0].input;+ assert.equal(arrived.schemaVersion, input.schemaVersion);+ for (const [name, value] of Object.entries(input)) {+ if (ArrayBuffer.isView(value)) {+ assert.ok(arrived[name] instanceof value.constructor, `${name} keeps its array type`);+ assert.deepEqual(Buffer.from(arrived[name].buffer, arrived[name].byteOffset, arrived[name].byteLength), Buffer.from(value.buffer, value.byteOffset, value.byteLength), name);+ } else if (typeof value === 'number') {+ assert.equal(arrived[name], value, name);+ }+ }+ assert.equal(traced.report.instances, 6);+ assert.equal(traced.report.triangles, input.triangleCount, 'the report counts unique triangles');+ assert.ok(input.triangleCount < 6 * 320, 'six copies of a 320 triangle mesh share one set of triangles');+});++test('a table with an unknown array type is refused with its name', async () => {+ const { input } = instancedInput('translate');+ const exported = { ...encodeNativeInputV2(input), triangleCount: 0, triangles: 0, ignored: [] };+ exported.types = { ...exported.types, instances: 'Float64Array' };+ await assert.rejects(+ traceFrameNative({ tracer: recordingTracer([]), exported, width: WIDTH, height: HEIGHT, samples: 4, denoise: 'none', kernel: 'cycles' }),+ /table "instances" has an unknown array type "Float64Array"/,+ );+});++test('the legacy packer refuses an instanced scene and a scene without shared geometry stays flattened', () => {+ const { parts, environment, camera, scene } = instancedInput('translate');+ assert.throws(() => buildNativeInput(scene, camera, { width: WIDTH, height: HEIGHT }, pack), /cannot read instances/);+ const distinct = parts.map(part => ({ ...part, geometry: { ...part.geometry, positions: Float32Array.from(part.geometry.positions) } }));+ const flattened = buildTraceScene(distinct, environment, { instancing: true });+ assert.equal(flattened.instances, undefined);+ assert.ok(flattened.indices.length > 0);+});++const addonSkip = findNativeAddon() ? false : 'the native addon is not built';++test('a job frame of an instanced scene equals the direct trace of the same input', { skip: addonSkip }, async t => {+ const { input } = instancedInput('rotscale');+ const exported = JSON.parse(JSON.stringify({ ...encodeNativeInputV2(input), triangleCount: input.triangleCount, triangles: input.triangleCount,+ instances: input.instanceCount, ignored: [] }));+ const real = await import('../packages/render-native/index.mjs');+ let direct;+ let viaJob;+ const capturingTracer = { ...real, traceNative(tables, options) {+ viaJob = real.traceNative(tables, options);+ return viaJob;+ } };+ try {+ direct = traceNative(input, { width: WIDTH, height: HEIGHT, samples: 8, kernel: 'cycles' });+ } catch (error) {+ if (/adapter|Vulkan|ray quer/i.test(error.message)) return t.skip(error.message);+ throw error;+ }+ const traced = await traceFrameNative({ tracer: capturingTracer, exported, width: WIDTH, height: HEIGHT, samples: 8, denoise: 'none', kernel: 'cycles' });+ assert.equal(traced.report.instances, 6);+ assert.deepEqual(Buffer.from(viaJob.rgba.buffer), Buffer.from(direct.rgba.buffer));+});