3D engine that AI agents drive
Reduce instanced job materials like flattened ones and export flattened when the instanced packer refuses a scene (#896)
Nguyen Xuan An07aadd76a1ae
diff --git a/bench/instancing/instancing-checks.mjs b/bench/instancing/instancing-checks.mjsindex 43f73d88..a5bf1e7e 100644--- a/bench/instancing/instancing-checks.mjs+++ b/bench/instancing/instancing-checks.mjs@@ -7,7 +7,7 @@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 { buildNativeInput, buildNativeTexelInput } 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';@@ -67,6 +67,8 @@ function identityScenes() {};const entry = { sceneWithoutSharing: unshared.instances === undefined };for (const [name, input] of Object.entries(inputs)) entry[name] = hashTables(input);+ // The light bake shares the v1 material tables.+ entry.texelV1 = hashTables(buildNativeTexelInput(flattened, { texelCount: 64, samples: 4, bounces: 3, seed: 1, fireflyClamp: 20 }, pack));if (!packOnly && findNativeAddon()) {entry.trace = {legacyFlattenedV1: traceHash(inputs.flattenedV1, 'legacy', width, height),diff --git a/bench/instancing/native-job-scenes.mjs b/bench/instancing/native-job-scenes.mjsindex 7971c2c3..ab219b65 100644--- a/bench/instancing/native-job-scenes.mjs+++ b/bench/instancing/native-job-scenes.mjs@@ -18,6 +18,10 @@ function repeatedRecipe() {}nodes.push({ id: 'lamp-left', geometry: 'panel', material: 'glow', translation: [-5, 0, 4], scale: [0.2, 2, 2] });nodes.push({ id: 'lamp-right', geometry: 'panel', material: 'glow', translation: [5, 0, 4], scale: [0.2, 2, 2] });+ // Parts with a geometry of their own and a material field the v1 job tables drop: a blend pane, a sheen sphere, a glass sphere.+ nodes.push({ id: 'pane', geometry: 'pane-box', material: 'pane', translation: [0, 0, 8], scale: [3, 2, 0.05] });+ nodes.push({ id: 'velvet', geometry: 'velvet-ball', material: 'velvet', translation: [-2.5, -2.5, 6], scale: [0.6, 0.6, 0.6] });+ nodes.push({ id: 'glass', geometry: 'glass-ball', material: 'glass', translation: [2.5, -2.5, 6], scale: [0.6, 0.6, 0.6] });nodes.push({ id: 'gobo', geometry: 'panel', material: 'red', translation: [0, 4, 3], scale: [3, 0.1, 1], shadowOnly: true });return nodes;}@@ -42,10 +46,14 @@ export function recipeFor(scene) {{ id: 'blue', color: [0.15, 0.4, 0.85], roughness: 0.3, metallic: 0.8 },{ id: 'gold', color: [0.9, 0.75, 0.25], roughness: 0.6 },{ id: 'glow', color: [1, 0.7, 0.4], roughness: 0.7, emission: 4 },+ { id: 'pane', color: [0.5, 0.75, 1], roughness: 0.1, opacity: 0.3 },+ { id: 'velvet', color: [0.45, 0.1, 0.55], roughness: 0.8, sheenColor: [1, 1, 1], sheenRoughness: 0.4 },+ { id: 'glass', color: [1, 1, 1], roughness: 0.05, transmission: 0.9, ior: 1.45, attenuationColor: [0.5, 0.8, 0.6], attenuationDistance: 2 },];const camera = { eye: [0, 0, 14], target: [0, 0, -2], fov: 50, near: 0.1, far: 60 };const geometries = scene === 'repeated'- ? [{ id: 'ball', type: 'sphere', segments: 16, rings: 8 }, { id: 'panel', type: 'box', bevel: 0 }]+ ? [{ id: 'ball', type: 'sphere', segments: 16, rings: 8 }, { id: 'panel', type: 'box', bevel: 0 },+ { id: 'pane-box', type: 'box', bevel: 0 }, { id: 'velvet-ball', type: 'sphere', segments: 20, rings: 10 }, { id: 'glass-ball', type: 'sphere', segments: 24, rings: 12 }]: Array.from({ length: 12 }, (_, index) => ({ id: `solid-${index}`, type: index % 2 ? 'box' : 'sphere', ...(index % 2 ? { bevel: 0 } : { segments: 12 + index, rings: 8 }) }));return { format: '67js.scene', schemaVersion: 1, geometries, materials, nodes: scene === 'repeated' ? repeatedRecipe() : distinctRecipe(), camera };}diff --git a/docs/path-tracer.md b/docs/path-tracer.mdindex 9c538fb2..e51a3c35 100644--- a/docs/path-tracer.md+++ b/docs/path-tracer.md@@ -65,6 +65,8 @@ Also checked before any ray is traced: samples times pixels times bounces at mos- 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. `traceNative` with `kernel: "legacy"` refuses a FORMAT-v2 input the same way.- Render jobs with `renderer.backend: "native"` keep repeated geometry as instances when the job traces with the `cycles` kernel (the default): the job page exports FORMAT-v2 tables of the unique triangles and one record per part, the job runner rebuilds the input for `traceNative`, and the report names the `instances` and counts `triangles` once per shared geometry. With `JS67_NATIVE_KERNEL=legacy`, `JS67_NATIVE_INSTANCING=off` (flattened triangles on the `cycles` kernel, to compare the two), or a scene where no geometry is shared, the job exports flattened tables exactly as before.+- A job reduces the materials of an instanced scene exactly as it reduces those of a flattened one (`buildJobNativeInput` in `packages/render-native/job-input.mjs`): only the fields of the v1 material tables survive, so a part looks the same whether or not other geometry in the scene is shared. Calling `buildNativeInputV2` yourself on an instanced scene keeps the richer FORMAT-v2 material fields, as it does for a flattened scene.+- When the instanced packer refuses a scene (copies of an emissive mesh that emit different triangles, a singular matrix), the job exports it flattened as before and the report says `instancing: "flattened"` and `instancingReason`. A scene that fails to export no longer marks the native tracer unusable for the process; only a tracer or adapter failure does.- A part with `shadowOnly: true` becomes an instance that camera rays skip (visibility bits for every other ray kind stay set). An instance whose material differs from the first copy's emits light by its own material: a copy made emissive by its material is sampled as a light, and a copy made non-emissive is not. Triangles of a shared mesh that are emissive keep one `local_emissive_offset` for all copies, so a copy scaled to a size that drops an emissive triangle the other copies keep is refused with its index.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.diff --git a/packages/render-native/job-input.mjs b/packages/render-native/job-input.mjsnew file mode 100644index 00000000..851ade9d--- /dev/null+++ b/packages/render-native/job-input.mjs@@ -0,0 +1,31 @@+// The FORMAT-v2 input a native render job sends for an instanced scene. A job without shared geometry sends v1 tables, whose+// material tables keep fewer fields than FORMAT-v2 materials do. An instanced job reduces its materials the same way, so a+// part looks the same whether or not other geometry in the scene is shared.+import { packNativeMaterialTables } from './pack-input.mjs';+import { buildNativeInputV2, reduceV1MaterialTable } from './pack-input-v2.mjs';++const ALL_LIGHT_GROUPS = 0xffffffff;++/**+ * Packs an instanced trace scene (`buildTraceScene` with `{ instancing: true }`) for the `cycles` kernel with the materials,+ * light masks and textures of the v1 job tables. `pack` is `src/path-tracer-gpu-pack.js`; `options` are those of the job.+ */+export function buildJobNativeInput(scene, camera, options, pack) {+ if (!scene?.instances || !scene.traceMaterials) {+ throw new TypeError('buildJobNativeInput packs an instanced scene: build it with buildTraceScene(parts, environment, { instancing: true }) and share a geometry between two parts.');+ }+ const tables = packNativeMaterialTables(scene.traceMaterials, null, pack);+ const reducedMaterials = reduceV1MaterialTable({+ materials: tables.materials,+ atlas: tables.atlas,+ atlasWidth: tables.atlasWidth,+ subsurfaceVec4Offset: tables.subsurfaceVec4Offset,+ materialCount: scene.traceMaterials.length,+ });+ const instances = scene.instances.map(instance => {+ const lightMask = reducedMaterials.materialLightMasks[instance.materialIndex] ?? ALL_LIGHT_GROUPS;+ return { ...instance, lightMask, lightMaskHi: lightMask === ALL_LIGHT_GROUPS ? ALL_LIGHT_GROUPS : 0 };+ });+ const { fireflyClamp, ...packOptions } = options;+ return buildNativeInputV2(scene, camera, { ...packOptions, instances, reducedMaterials });+}diff --git a/packages/render-native/pack-input-v2.mjs b/packages/render-native/pack-input-v2.mjsindex 7694dcf9..6cf91fbc 100644--- a/packages/render-native/pack-input-v2.mjs+++ b/packages/render-native/pack-input-v2.mjs@@ -2097,8 +2097,10 @@ function shareEmissiveOffsets(meshSlot, emittedLocalIndices, instanceIndex) {}}-function packInstancedGeometry(instancesInput, rawMaterials, textureCollector) {- const materialRecords = rawMaterials.map(mat => packMaterialRecordV2(mat, textureCollector));+function packInstancedGeometry(instancesInput, rawMaterials, textureCollector, reducedMaterials) {+ const materialRecords = reducedMaterials+ ? reducedMaterials.materialRecords+ : rawMaterials.map(mat => packMaterialRecordV2(mat, textureCollector));const materialsBuffer = new Uint8Array(Math.max(1, materialRecords.length) * STRUCT_STRIDES_V2.material);materialRecords.forEach((rec, index) => materialsBuffer.set(rec.bytes, index * STRUCT_STRIDES_V2.material));@@ -2377,10 +2379,19 @@ export function buildNativeInputV2(scene, camera, options = {}) {}validatePackOptions(options, 'buildNativeInputV2');- const textureCollector = createTextureCollector();const explicitInstances = options.instances ?? scene.instances;+ const reducedMaterials = options.reducedMaterials;+ if (reducedMaterials !== undefined) {+ if (!explicitInstances) {+ throw new TypeError('buildNativeInputV2 option `reducedMaterials` belongs to an instanced scene: pass a scene with `instances` (buildTraceScene with { instancing: true }), or leave the option out.');+ }+ if (!Array.isArray(reducedMaterials.materialRecords) || !reducedMaterials.textureCollector) {+ throw new TypeError('buildNativeInputV2 option `reducedMaterials` must be the result of reduceV1MaterialTable (materialRecords and textureCollector).');+ }+ }+ const textureCollector = reducedMaterials?.textureCollector ?? createTextureCollector();const packedGeometry = explicitInstances- ? packInstancedGeometry(explicitInstances, options.materials ?? scene.materials ?? [{}], textureCollector)+ ? packInstancedGeometry(explicitInstances, options.materials ?? scene.materials ?? [{}], textureCollector, reducedMaterials): packFlattenedTraceScene(scene, options.parts ?? scene.parts, textureCollector);const packedTextures = textureCollector.finish();@@ -2448,46 +2459,14 @@ function extractAtlasSubtexture(atlasWords, atlasWidth, rectX, rectY, width, hei}/**- * Upgrades a legacy v1 `buildNativeInput` payload to `FORMAT-v2` (`schemaVersion: 2`) so existing callers passing v1- * inputs with `kernel: 'cycles'` or `JS67_NATIVE_KERNEL=cycles` run without changing call sites.+ * The material records of a v1 material table, the reduction every v1 native job goes through: only the fields the v1 tables+ * carry survive (base colour, metallic, roughness, emission, clearcoat, transmission, ior, normal scale, mask cutoff,+ * subsurface and the four atlas textures). `materials` holds the table with the subsurface table after it, `atlas` the atlas+ * words and `atlasWidth` their row width.*/-export function upgradeNativeInputV1ToV2(v1Input, options = {}) {- if (v1Input?.schemaVersion === FORMAT_V2_VERSION) {- return v1Input;- }- if (!v1Input || !(v1Input.parameters instanceof Uint8Array) || v1Input.parameters.byteLength !== 256) {- throw new TypeError('upgradeNativeInputV1ToV2 requires a v1 NativeTraceInput with a 256-byte parameters block, or a FORMAT-v2 input.');- }- validatePackOptions(options, 'upgradeNativeInputV1ToV2');-- const paramBuffer = v1Input.parameters.buffer;- const paramByteOffset = v1Input.parameters.byteOffset;- const paramF32 = new Float32Array(paramBuffer, paramByteOffset, 64);- const paramI32 = new Int32Array(paramBuffer, paramByteOffset, 64);- const paramU32 = new Uint32Array(paramBuffer, paramByteOffset, 64);-- const triangleCount = Number(v1Input.triangleCount ?? 0);- const triData = v1Input.triangles;- if (!(triangleCount >= 0) || !triData || triData.length < triangleCount * 36) {- throw new RangeError('v1 NativeTraceInput.triangles must hold at least triangleCount * 36 floats.');- }-- const subsurfaceVec4Offset = paramU32[60];- const materialVec4Limit = subsurfaceVec4Offset > 0 ? subsurfaceVec4Offset : Math.floor((v1Input.materials?.length ?? 0) / 4);- const maxPossibleMaterials = Math.max(1, Math.floor(materialVec4Limit / 10));- let highestMaterialIndex = 0;- for (let slot = 0; slot < triangleCount; slot++) {- const matIdx = Math.max(0, Math.round(triData[slot * 36 + 3]));- if (matIdx > highestMaterialIndex) {- highestMaterialIndex = matIdx;- }- }- const materialCount = Math.min(maxPossibleMaterials, highestMaterialIndex + 1);-+export function reduceV1MaterialTable({ materials: matSource, atlas: atlasWords, atlasWidth, subsurfaceVec4Offset, materialCount }) {const textureCollector = createTextureCollector();const atlasCache = new Map();- const atlasWidth = paramU32[45] || 1;- const atlasWords = v1Input.atlas;function registerAtlasRect(rectX, rectY, width, height, flagsValue) {if (!(width > 0 && height > 0) || !atlasWords) {@@ -2510,7 +2489,6 @@ export function upgradeNativeInputV1ToV2(v1Input, options = {}) {return added;}- const matSource = v1Input.materials;const materialRecords = [];const materialLightMasks = [];const materialShadowOnly = [];@@ -2576,6 +2554,53 @@ export function upgradeNativeInputV1ToV2(v1Input, options = {}) {packedMat.isEmissive = luminance(packedMat.meanEmissiveRadiance) > 0;materialRecords.push(packedMat);}+ return { materialRecords, materialLightMasks, materialShadowOnly, textureCollector };+}++/**+ * Upgrades a legacy v1 `buildNativeInput` payload to `FORMAT-v2` (`schemaVersion: 2`) so existing callers passing v1+ * inputs with `kernel: 'cycles'` or `JS67_NATIVE_KERNEL=cycles` run without changing call sites.+ */+export function upgradeNativeInputV1ToV2(v1Input, options = {}) {+ if (v1Input?.schemaVersion === FORMAT_V2_VERSION) {+ return v1Input;+ }+ if (!v1Input || !(v1Input.parameters instanceof Uint8Array) || v1Input.parameters.byteLength !== 256) {+ throw new TypeError('upgradeNativeInputV1ToV2 requires a v1 NativeTraceInput with a 256-byte parameters block, or a FORMAT-v2 input.');+ }+ validatePackOptions(options, 'upgradeNativeInputV1ToV2');++ const paramBuffer = v1Input.parameters.buffer;+ const paramByteOffset = v1Input.parameters.byteOffset;+ const paramF32 = new Float32Array(paramBuffer, paramByteOffset, 64);+ const paramI32 = new Int32Array(paramBuffer, paramByteOffset, 64);+ const paramU32 = new Uint32Array(paramBuffer, paramByteOffset, 64);++ const triangleCount = Number(v1Input.triangleCount ?? 0);+ const triData = v1Input.triangles;+ if (!(triangleCount >= 0) || !triData || triData.length < triangleCount * 36) {+ throw new RangeError('v1 NativeTraceInput.triangles must hold at least triangleCount * 36 floats.');+ }++ const subsurfaceVec4Offset = paramU32[60];+ const materialVec4Limit = subsurfaceVec4Offset > 0 ? subsurfaceVec4Offset : Math.floor((v1Input.materials?.length ?? 0) / 4);+ const maxPossibleMaterials = Math.max(1, Math.floor(materialVec4Limit / 10));+ let highestMaterialIndex = 0;+ for (let slot = 0; slot < triangleCount; slot++) {+ const matIdx = Math.max(0, Math.round(triData[slot * 36 + 3]));+ if (matIdx > highestMaterialIndex) {+ highestMaterialIndex = matIdx;+ }+ }+ const materialCount = Math.min(maxPossibleMaterials, highestMaterialIndex + 1);++ const { materialRecords, materialLightMasks, materialShadowOnly, textureCollector } = reduceV1MaterialTable({+ materials: v1Input.materials,+ atlas: v1Input.atlas,+ atlasWidth: paramU32[45] || 1,+ subsurfaceVec4Offset,+ materialCount,+ });const materialsBuffer = new Uint8Array(Math.max(1, materialRecords.length) * STRUCT_STRIDES_V2.material);materialRecords.forEach((rec, idx) => materialsBuffer.set(rec.bytes, idx * STRUCT_STRIDES_V2.material));diff --git a/packages/render-native/pack-input.mjs b/packages/render-native/pack-input.mjsindex 33b9c46e..99f14a23 100644--- a/packages/render-native/pack-input.mjs+++ b/packages/render-native/pack-input.mjs@@ -39,7 +39,7 @@ 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 materialTables = packNativeMaterialTables(scene.materials, scene.shadowOnlyParts, pack);const lights = pack.packLights(scene.lights);const environment = pack.packEnvironment(scene.environment);const environmentTables = new Float32Array(environment ? environment.height + environment.width * environment.height : 4);@@ -47,23 +47,35 @@ export function buildNativeInput(scene, camera, options, pack) {environmentTables.set(environment.rows.data.subarray(0, environment.height), 0);environmentTables.set(environment.pixels.data.subarray(0, environment.width * environment.height), environment.height);}- // The subsurface table (two vectors per material) follows the material table in the same buffer; its offset is 0 when no- // material scatters light under its surface, which keeps the walk out of the kernel.- const materialData = pack.packMaterials(scene.materials, atlas, scene.shadowOnlyParts).data;- const usesSubsurface = pack.sceneUsesSubsurface(scene.materials);- const subsurfaceData = usesSubsurface ? pack.packSubsurface(scene.materials).data : new Float32Array(0);- const materials = new Float32Array(materialData.length + subsurfaceData.length);- materials.set(materialData);- materials.set(subsurfaceData, materialData.length);return {triangles: pack.packTriangles(scene).data,triangleCount: scene.bvh.triangleOrder.length,- materials,+ materials: materialTables.materials,lights: lights.table.data,- atlas: new Uint32Array(atlas.data.buffer, atlas.data.byteOffset, Math.floor(atlas.data.byteLength / 4)),+ atlas: materialTables.atlas,environmentColors: environment?.colors ?? new Float32Array(4),environmentTables,- parameters: writeParameters(scene, camera, options, lights.count, atlas.width, usesSubsurface ? materialData.length / 4 : 0),+ parameters: writeParameters(scene, camera, options, lights.count, materialTables.atlasWidth, materialTables.subsurfaceVec4Offset),+ };+}++/**+ * The v1 material tables of resolved trace materials: the material table with the subsurface table after it (its offset is 0+ * when no material scatters light under its surface, which keeps the walk out of the kernel), the texture atlas and its width.+ */+export function packNativeMaterialTables(materials, shadowOnlyParts, pack) {+ const atlas = pack.packAtlas(materials);+ const materialData = pack.packMaterials(materials, atlas, shadowOnlyParts).data;+ const usesSubsurface = pack.sceneUsesSubsurface(materials);+ const subsurfaceData = usesSubsurface ? pack.packSubsurface(materials).data : new Float32Array(0);+ const combined = new Float32Array(materialData.length + subsurfaceData.length);+ combined.set(materialData);+ combined.set(subsurfaceData, materialData.length);+ return {+ materials: combined,+ atlas: new Uint32Array(atlas.data.buffer, atlas.data.byteOffset, Math.floor(atlas.data.byteLength / 4)),+ atlasWidth: atlas.width,+ subsurfaceVec4Offset: usesSubsurface ? materialData.length / 4 : 0,};}diff --git a/scripts/agent-native-trace.mjs b/scripts/agent-native-trace.mjsindex 5b963696..bbef0f1c 100644--- a/scripts/agent-native-trace.mjs+++ b/scripts/agent-native-trace.mjs@@ -204,7 +204,8 @@ 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, inputBytes: tableBytes(tables), ...(exported.instances === undefined ? {} : { instances: exported.instances }), tracedSeconds, ignored: exported.ignored };+ kernel, averageSamples: traced.averageSamples ?? samples, noiseThreshold, triangles: exported.triangles, inputBytes: tableBytes(tables), ...(exported.instances === undefined ? {} : { instances: exported.instances }),+ ...(exported.instancing === undefined ? {} : { instancing: exported.instancing, instancingReason: exported.instancingReason }), 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 dd938719..a92cd0a0 100644--- a/scripts/agent-preview-browser.js+++ b/scripts/agent-preview-browser.js@@ -1,4 +1,4 @@-import { encodeNativeInputV2, encodeNativeTables, nativeTexelTracerIfAvailable } from './native-bake-page.js';+import { exportNativeSceneTables, 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,15 +829,6 @@ 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');@@ -999,20 +990,16 @@ window.__agentPreview = {record.scene.sampleMotion(motionTime);}const { instancing, ...packOptions } = options;- const [{ createCamera, describeIgnoredFeatures }, { buildTraceScene, refuseLocalVolumes }, pack, { buildNativeInput }] = await Promise.all([+ const [{ createCamera, describeIgnoredFeatures }, { buildTraceScene, refuseLocalVolumes }, pack, { buildNativeInput }, { buildJobNativeInput }] = 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'),+ import('../packages/render-native/pack-input.mjs'), import('../packages/render-native/job-input.mjs'),]);const environment = { ...record.scene.environment, map: agentEnvironmentMap(record.scene.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 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 };+ const exported = exportNativeSceneTables({ parts: record.scene.parts, environment, camera, options: packOptions, instancing: instancing === true,+ modules: { buildTraceScene, refuseLocalVolumes, buildNativeInput, buildJobNativeInput, pack } });+ return { ...exported, ignored: describeIgnoredFeatures(record.scene.parts, environment) };},// The PNG of linear pixels (three floats each, base64) that a denoiser outside the page returned, or of the wavelet// filter over the kept features when none came back.diff --git a/scripts/agent-runtime.mjs b/scripts/agent-runtime.mjsindex e6d5dd25..010f69df 100644--- a/scripts/agent-runtime.mjs+++ b/scripts/agent-runtime.mjs@@ -564,16 +564,19 @@ export function createAgentRuntime({ kernelWorkers = true, backend = 'gpu', browlet traced;let backendNote = trace.note;if (trace.backend === 'native') {+ let exportedScene = false;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, instancing: chooseNativeInstancing() } });+ exportedScene = true;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 });} catch (error) {// Past maxSeconds the job fails as it does on every backend; falling back would only run it twice as long.if (isNativeTimeLimitError(error)) throw error;- nativeTracerLocator.markUnusable(error.message);- backendNote = (await nativeTracerLocator.find()).reason;+ // Only a tracer or adapter failure makes the tracer unusable; a scene that failed to export says so for this job alone.+ if (exportedScene) nativeTracerLocator.markUnusable(error.message);+ backendNote = exportedScene ? (await nativeTracerLocator.find()).reason : `renderer.backend "native" could not export the scene (${error.message}).`;traceOptions.backend = backend === 'cpu' ? 'cpu' : 'gpu';choice = await chooseDenoiser(settings.renderer.denoise);traceOptions.denoise = choice.denoise;diff --git a/scripts/native-bake-page.js b/scripts/native-bake-page.jsindex 1680297a..127967f2 100644--- a/scripts/native-bake-page.js+++ b/scripts/native-bake-page.js@@ -43,6 +43,33 @@ export function encodeNativeInputV2(input) {return { schemaVersion: input.schemaVersion, tables: encodeNativeTables(input), types, counts };}+/**+ * The scene of a native render job as the tables the job runner traces. With `instancing`, parts that share a geometry are+ * exported as FORMAT-v2 instances; a scene the instanced packer refuses (copies of an emissive mesh that emit different+ * triangles, say) is exported flattened, as a job without shared geometry is, and says why in `instancing` and+ * `instancingReason`. `modules` holds buildTraceScene, refuseLocalVolumes, buildNativeInput, buildJobNativeInput and `pack`+ * (src/path-tracer-gpu-pack.js), which the page loads on demand.+ */+export function exportNativeSceneTables({ parts, environment, camera, options, instancing, modules }) {+ const { buildTraceScene, refuseLocalVolumes, buildNativeInput, buildJobNativeInput, pack } = modules;+ let traceScene = buildTraceScene(parts, environment, { instancing: instancing === true });+ refuseLocalVolumes(traceScene, 'the native path tracer');+ let flattenedBecause;+ if (traceScene.instances) {+ try {+ const input = buildJobNativeInput(traceScene, camera, options, pack);+ return { ...encodeNativeInputV2(input), triangleCount: input.triangleCount, triangles: input.triangleCount, instances: input.instanceCount };+ } catch (error) {+ if (!(error instanceof RangeError)) throw error;+ flattenedBecause = error.message;+ traceScene = buildTraceScene(parts, environment);+ }+ }+ const input = buildNativeInput(traceScene, camera, options, pack);+ return { tables: encodeNativeTables(input), triangleCount: input.triangleCount, triangles: traceScene.indices.length / 3,+ ...(flattenedBecause === undefined ? {} : { instancing: 'flattened', instancingReason: flattenedBecause }) };+}+function floatsFromBase64(data) {const bytes = bytesFromBase64(data);return new Float32Array(bytes.buffer, bytes.byteOffset, bytes.byteLength / Float32Array.BYTES_PER_ELEMENT);diff --git a/src/path-tracer-scene.js b/src/path-tracer-scene.jsindex 1ba8fac8..3fa898d7 100644--- a/src/path-tracer-scene.js+++ b/src/path-tracer-scene.js@@ -453,17 +453,20 @@ function boundingBoxOf(positions) {/*** 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+ * the unique geometries, and `materials` indexed by part (`traceMaterials` are the same parts' resolved materials alone, the+ * list a flattened scene calls `materials`), 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 traceMaterials = parts.map(part => resolveMaterial(part.material ?? {}));+ const materials = parts.map((part, index) => ({ ...(part.material ?? {}), ...traceMaterials[index] }));const instances = parts.map((part, index) => instanceFor(part, geometries[index], index, materials[index]));const extent = instancedExtent(instances);return {instances,materials,+ traceMaterials,lights: resolveLights(environment),environment: resolveEnvironment(environment.map),volume: resolveTraceVolume(environment.volumeFog),diff --git a/tests/native-instancing-fallback.test.js b/tests/native-instancing-fallback.test.jsnew file mode 100644index 00000000..b5278b0d--- /dev/null+++ b/tests/native-instancing-fallback.test.js@@ -0,0 +1,96 @@+import assert from 'node:assert/strict';+import test from 'node:test';+import { buildNativeInput } from '../packages/render-native/pack-input.mjs';+import { buildJobNativeInput } from '../packages/render-native/job-input.mjs';+import { findNativeAddon, traceNative } from '../packages/render-native/index.mjs';+import { traceFrameNative } from '../scripts/agent-native-trace.mjs';+import { exportNativeSceneTables } from '../scripts/native-bake-page.js';+import { createCamera } from '../src/path-tracer.js';+import * as pack from '../src/path-tracer-gpu-pack.js';+import { buildTraceScene, refuseLocalVolumes } from '../src/path-tracer-scene.js';++const WIDTH = 16;+const HEIGHT = 16;+const camera = createCamera({ eye: [0, 0, 8], target: [0, 0, 0], fov: 50 }, WIDTH, HEIGHT);+const options = { width: WIDTH, height: HEIGHT, bounces: 3, seed: 1, fireflyClamp: 20, noiseThreshold: 0 };+const environment = { keyColor: [3, 3, 3], lightDirection: [0.4, 0.8, 0.5] };+const modules = { buildTraceScene, refuseLocalVolumes, buildNativeInput, buildJobNativeInput, pack };++// A large triangle and a small one, so a copy shrunk far enough keeps one and loses the other.+const mixedSizeMesh = {+ positions: Float32Array.from([0, 0, 0, 1, 0, 0, 0, 1, 0, 2, 0, 0, 2.05, 0, 0, 2, 0.04, 0, 0, 0, 1, 0, 0.5, 1]),+ normals: Float32Array.from([0, 0, 1, 0, 0, 1, 0, 0, 1, 0, 0, 1, 0, 0, 1, 0, 0, 1, 1, 0, 0, 1, 0, 0]),+ uvs: Float32Array.from([0, 0, 1, 0, 0, 1, 0, 0, 1, 0, 0, 1, 0, 0, 1, 0]),+ indices: Uint32Array.from([0, 1, 2, 3, 4, 5, 0, 6, 7]),+};+const glow = { color: [1, 0.7, 0.4], emission: 4, roughness: 0.7 };++function scaleAndMove(x, y, z, width) {+ return [x, 0, 0, 0, 0, y, 0, 0, 0, 0, z, 0, width, 0, 0, 1];+}++const scenes = {+ 'a copy scaled flat': { reason: /singular/, matrices: [scaleAndMove(1, 1, 1, -2), scaleAndMove(1, 0, 1, 1)] },+ 'a copy scaled very small': { reason: /scales some emissive triangles/, matrices: [scaleAndMove(1, 1, 1, -2), scaleAndMove(1e-5, 1e-5, 1e-5, 1)] },+};++function parts(matrices) {+ return matrices.map((matrix, index) => ({ name: `lamp-${index}`, geometry: mixedSizeMesh, matrix, material: glow }));+}++function jobExport(matrices) {+ const exported = exportNativeSceneTables({ parts: parts(matrices), environment, camera, options, instancing: true, modules });+ return JSON.parse(JSON.stringify({ ...exported, ignored: [] }));+}++function mainsExport(matrices) {+ const input = buildNativeInput(buildTraceScene(parts(matrices), environment), camera, options, pack);+ return input;+}++for (const [name, scene] of Object.entries(scenes)) {+ const { matrices, reason } = scene;+ test(`${name} makes the emissive copies export flattened with the reason, and the tables equal the flattened job`, () => {+ const exported = jobExport(matrices);+ assert.equal(exported.instancing, 'flattened');+ assert.match(exported.instancingReason, reason);+ assert.equal(exported.schemaVersion, undefined, 'v1 tables');+ const main = mainsExport(matrices);+ for (const [tableName, table] of Object.entries(main)) {+ if (!ArrayBuffer.isView(table)) continue;+ assert.equal(exported.tables[tableName], Buffer.from(table.buffer, table.byteOffset, table.byteLength).toString('base64'), tableName);+ }+ });+}++test('copies that all keep their triangles still export instanced', () => {+ const exported = jobExport([scaleAndMove(1, 1, 1, -2), scaleAndMove(0.5, 0.5, 0.5, 1)]);+ assert.equal(exported.instancing, undefined);+ assert.equal(exported.instances, 2);+});++const addonSkip = findNativeAddon() ? false : 'the native addon is not built';++for (const [name, scene] of Object.entries(scenes)) {+ const { matrices, reason } = scene;+ test(`${name} renders natively in a job frame, equal to the flattened trace`, { skip: addonSkip }, async t => {+ const real = await import('../packages/render-native/index.mjs');+ let viaJob;+ const capturingTracer = { ...real, traceNative(tables, traceOptions) {+ viaJob = real.traceNative(tables, traceOptions);+ return viaJob;+ } };+ let direct;+ try {+ direct = traceNative(mainsExport(matrices), { 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: jobExport(matrices), width: WIDTH, height: HEIGHT, samples: 8, denoise: 'none', kernel: 'cycles' });+ assert.equal(traced.report.backend, 'native');+ assert.equal(traced.report.instancing, 'flattened');+ assert.match(traced.report.instancingReason, reason);+ assert.deepEqual(Buffer.from(viaJob.rgba.buffer), Buffer.from(direct.rgba.buffer));+ });+}diff --git a/tests/native-instancing-materials.test.js b/tests/native-instancing-materials.test.jsnew file mode 100644index 00000000..e1bba53d--- /dev/null+++ b/tests/native-instancing-materials.test.js@@ -0,0 +1,60 @@+import assert from 'node:assert/strict';+import test from 'node:test';+import { buildNativeInput } from '../packages/render-native/pack-input.mjs';+import { STRUCT_STRIDES_V2, upgradeNativeInputV1ToV2 } from '../packages/render-native/index.mjs';+import { buildJobNativeInput } from '../packages/render-native/job-input.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 camera = createCamera({ eye: [0, 0, 8], target: [0, 0, 0], fov: 50 }, 16, 16);+const options = { width: 16, height: 16, samples: 1, bounces: 4, seed: 1, fireflyClamp: 20, noiseThreshold: 0 };+const environment = { keyColor: [3, 3, 3], lightDirection: [0.4, 0.8, 0.5] };++function quad(scale) {+ return {+ positions: Float32Array.from([-scale, -scale, 0, scale, -scale, 0, scale, scale, 0, -scale, scale, 0]),+ normals: Float32Array.from([0, 0, 1, 0, 0, 1, 0, 0, 1, 0, 0, 1]),+ uvs: Float32Array.from([0, 0, 1, 0, 1, 1, 0, 1]),+ indices: Uint32Array.from([0, 1, 2, 0, 2, 3]),+ };+}++const sharedQuad = quad(1);+const translate = x => [1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1, 0, x, 0, 0, 1];++// Two copies of one mesh, then parts that each have a geometry of their own and use a material field the v1 job tables drop.+function partsWithSharedMesh() {+ return [+ { name: 'copy-a', geometry: sharedQuad, matrix: translate(-2), material: { color: [0.8, 0.2, 0.2], roughness: 0.5 } },+ { name: 'copy-b', geometry: sharedQuad, matrix: translate(2), material: { color: [0.2, 0.2, 0.8], roughness: 0.5 } },+ { name: 'pane', geometry: quad(0.9), matrix: translate(0), material: { color: [0.6, 0.8, 1], opacity: 0.3, alphaMode: 'blend', roughness: 0.1 } },+ { name: 'velvet', geometry: quad(0.8), matrix: translate(0.1), material: { color: [0.4, 0.1, 0.5], sheenColor: [1, 1, 1], sheenRoughness: 0.4, roughness: 0.8 } },+ { name: 'glass', geometry: quad(0.7), matrix: translate(0.2), material: { color: [1, 1, 1], transmission: 0.9, ior: 1.45, roughness: 0.05, attenuationDistance: 2, attenuationColor: [0.5, 0.8, 0.6] } },+ { name: 'foil', geometry: quad(0.6), matrix: translate(0.3), material: { color: [0.9, 0.8, 0.5], metallic: 1, anisotropy: 0.6, iridescence: 0.5, specular: 0.8, roughness: 0.3 } },+ ];+}++function materialRecords(input) {+ const records = [];+ for (let index = 0; index < input.materialCount; index++) {+ records.push(Buffer.from(input.materials.buffer, input.materials.byteOffset + index * STRUCT_STRIDES_V2.material, STRUCT_STRIDES_V2.material).toString('hex'));+ }+ return records;+}++// What a native job without shared geometry sends: v1 tables, which the cycles kernel upgrades to FORMAT-v2.+function flattenedJobInput(parts) {+ const scene = buildTraceScene(parts, environment);+ return upgradeNativeInputV1ToV2(buildNativeInput(scene, camera, options, pack), options);+}++test('a part keeps the same material record whether or not other geometry in the job is shared', () => {+ const parts = partsWithSharedMesh();+ const flattened = materialRecords(flattenedJobInput(parts));+ const instancedScene = buildTraceScene(parts, environment, { instancing: true });+ assert.ok(instancedScene.instances, 'the two copies of one mesh make the job instanced');+ const instanced = materialRecords(buildJobNativeInput(instancedScene, camera, options, pack));+ assert.equal(instanced.length, parts.length);+ parts.forEach((part, index) => assert.equal(instanced[index], flattened[index], `material record of ${part.name}`));+});