Skip to content

armgit / 67.js

Public Imported from GitHub
0

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.mjs
index 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.mjs
new file mode 100644
index 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.mjs
new file mode 100644
index 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.mjs
index 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.mjs
index 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.mjs
index 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, sample
const 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.js
index 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 wavelet
diff --git a/scripts/agent-runtime.mjs b/scripts/agent-runtime.mjs
index 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', brow
let 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.js
index 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.js
new file mode 100644
index 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.js
index 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.js
new file mode 100644
index 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));
+});