3D engine that AI agents drive
Add progressive film and scene updates to the native session (#896)
Nguyen Xuan Ane0ed883c6eda
diff --git a/bench/cycles-parity/session-progressive.mjs b/bench/cycles-parity/session-progressive.mjsnew file mode 100644index 00000000..2df33083--- /dev/null+++ b/bench/cycles-parity/session-progressive.mjs@@ -0,0 +1,205 @@+// Checks and times the progressive film and the scene update of a persistent native session (issue 896, slice S2) on an+// exported scene:+// 1. one image built over several calls against one render of the same samples, for both samplers and with path regeneration+// on and off (SHA-256 of every float plane);+// 2. an update of material values, and of material values plus instance transforms, against a fresh one-shot render of the+// final input, and its cost against a new session (create and first render).+// Prints one SESSION_PROGRESSIVE line of JSON.+// node bench/cycles-parity/session-progressive.mjs <sceneJsonPath> [--samples 32] [--width 480] [--height 270] [--seed 1]+// [--update-samples 4]+import { createHash } from 'node:crypto';+import { readFile } from 'node:fs/promises';+import { resolve } from 'node:path';+import { performance } from 'node:perf_hooks';+import { createCamera } from '../../src/path-tracer.js';+import * as packModule from '../../src/path-tracer-gpu-pack.js';+import * as renderNative from '../../packages/render-native/index.mjs';+import { buildTraceSceneWithManyLights } from './trace-scene-many-lights.mjs';+import { reconstructTraceSceneSource } from './scene-bridge.mjs';++const PLANES = ['rgba', 'depth', 'albedo', 'normal', 'variance'];+const MATERIAL_RECORD_BYTES = 256;+const INSTANCE_RECORD_BYTES = 160;+const BASE_COLOR_SCALE = 0.6;+const TRANSLATION = [0.05, 0, 0.03];++function readNumberFlag(argumentList, flagName, fallbackValue) {+ const flagIndex = argumentList.indexOf(flagName);+ return flagIndex === -1 ? fallbackValue : Number(argumentList[flagIndex + 1]);+}++function sha256Of(values) {+ return createHash('sha256').update(Buffer.from(values.buffer, values.byteOffset, values.byteLength)).digest('hex');+}++function planeHashes(result) {+ return Object.fromEntries(PLANES.map((plane) => [plane, sha256Of(result[plane])]));+}++function sameHashes(left, right) {+ return PLANES.every((plane) => left[plane] === right[plane]);+}++function roundSeconds(seconds) {+ return Number(seconds.toFixed(6));+}++// Scales the base colour (three floats at the start of each material record) so the table differs in values only.+function withDimmedMaterials(input) {+ const materials = new Uint8Array(input.materials);+ const view = new DataView(materials.buffer);+ for (let record = 0; record < input.materialCount; record += 1) {+ for (let channel = 0; channel < 3; channel += 1) {+ const byteOffset = record * MATERIAL_RECORD_BYTES + channel * 4;+ view.setFloat32(byteOffset, view.getFloat32(byteOffset, true) * BASE_COLOR_SCALE, true);+ }+ }+ return { ...input, materials };+}++// Translates every instance: the object-to-world translation grows by the offset and the world-to-object translation+// shrinks by the linear part applied to it.+function withShiftedInstances(input) {+ const instances = new Uint8Array(input.instances);+ const view = new DataView(instances.buffer);+ for (let record = 0; record < input.instanceCount; record += 1) {+ const base = record * INSTANCE_RECORD_BYTES;+ for (let row = 0; row < 3; row += 1) {+ const objectToWorldTranslation = base + row * 16 + 12;+ view.setFloat32(objectToWorldTranslation, view.getFloat32(objectToWorldTranslation, true) + TRANSLATION[row], true);+ const inverseRow = base + 48 + row * 16;+ let shift = 0;+ for (let column = 0; column < 3; column += 1) {+ shift += view.getFloat32(inverseRow + column * 4, true) * TRANSLATION[column];+ }+ view.setFloat32(inverseRow + 12, view.getFloat32(inverseRow + 12, true) - shift, true);+ }+ }+ return { ...input, instances };+}++function checkSplits(input, baseOptions, samples) {+ const splits = [[samples / 2, samples / 2], [Math.floor(samples / 4), Math.floor(samples / 2) - 1, samples - Math.floor(samples / 4) - Math.floor(samples / 2) + 1]];+ const rows = [];+ const session = renderNative.createNativeSession(input);+ try {+ for (const sampler of ['sobol-burley', 'white']) {+ for (const pathRegeneration of [true, false]) {+ const options = { ...baseOptions, samples, sampler, pathRegeneration };+ const oneShot = planeHashes(renderNative.traceNative(input, options));+ for (const parts of splits) {+ session.reset();+ let result;+ let drawn = 0;+ for (const partSamples of parts) {+ result = session.render({ ...options, samples: partSamples, accumulate: true, ...(drawn === 0 ? { targetSamples: samples } : {}) });+ drawn += partSamples;+ }+ const resolved = planeHashes(session.resolve());+ rows.push({+ sampler,+ pathRegeneration,+ split: parts.join('+'),+ identical: sameHashes(oneShot, planeHashes(result)),+ resolveIdentical: sameHashes(oneShot, resolved),+ filmSamples: result.filmSamples,+ });+ }+ }+ }+ } finally {+ session.close();+ }+ return rows;+}++function timeUpdate(session, finalInput, options) {+ const started = performance.now();+ const update = session.update(finalInput);+ const frame = session.render(options);+ const wallMilliseconds = performance.now() - started;+ const oneShot = planeHashes(renderNative.traceNative(finalInput, options));+ return {+ wallMilliseconds: Number(wallMilliseconds.toFixed(2)),+ identicalToOneShot: sameHashes(oneShot, planeHashes(frame)),+ uploadedTables: update.uploadedTables,+ accelerationRebuilt: update.accelerationRebuilt,+ changedInstances: update.changedInstances,+ kernelRespecialized: update.kernelRespecialized,+ updateSeconds: roundSeconds(update.updateSeconds),+ uploadSeconds: roundSeconds(update.uploadSeconds),+ accelerationRebuildSeconds: roundSeconds(update.accelerationRebuildSeconds),+ renderPipelineReused: frame.pipelineReused,+ renderAccelerationReused: frame.accelerationReused,+ renderCompileSeconds: roundSeconds(frame.compileSeconds),+ renderAccelerationBuildSeconds: roundSeconds(frame.accelerationBuildSeconds),+ renderTracedSeconds: roundSeconds(frame.tracedSeconds),+ };+}++function timeNewSession(input, options) {+ const started = performance.now();+ const session = renderNative.createNativeSession(input);+ try {+ const frame = session.render(options);+ return {+ wallMilliseconds: Number((performance.now() - started).toFixed(2)),+ setupSeconds: roundSeconds(frame.setupSeconds),+ uploadSeconds: roundSeconds(frame.uploadSeconds),+ accelerationBuildSeconds: roundSeconds(frame.accelerationBuildSeconds),+ compileSeconds: roundSeconds(frame.compileSeconds),+ tracedSeconds: roundSeconds(frame.tracedSeconds),+ };+ } finally {+ session.close();+ }+}++async function run() {+ const argumentList = process.argv.slice(2);+ const width = readNumberFlag(argumentList, '--width', 480);+ const height = readNumberFlag(argumentList, '--height', 270);+ const samples = readNumberFlag(argumentList, '--samples', 32);+ const updateSamples = readNumberFlag(argumentList, '--update-samples', 4);+ const seed = readNumberFlag(argumentList, '--seed', 1);+ const description = JSON.parse(await readFile(resolve(argumentList[0]), 'utf8'));+ const traceSource = await reconstructTraceSceneSource(description);+ const traceScene = buildTraceSceneWithManyLights(traceSource.parts, traceSource.environment);+ const renderOptions = { width, height, samples, bounces: 8, seed, kernel: 'cycles' };+ const packOptions = { ...renderOptions, parts: traceSource.parts };+ const inputA = renderNative.buildNativeInputV2(traceScene, createCamera(traceSource.camera, width, height), packOptions, packModule);+ const dimmed = withDimmedMaterials(inputA);+ const shifted = withShiftedInstances(dimmed);+ const updateOptions = { ...renderOptions, samples: updateSamples };++ const report = {+ scene: description.id,+ width,+ height,+ samples,+ updateSamples,+ instanceCount: inputA.instanceCount,+ triangleCount: inputA.triangleCount,+ };+ // A new session goes first: it pays the shader compile, which the process keeps afterwards for any session.+ report.newSessionCold = timeNewSession(shifted, updateOptions);+ report.newSessionCachedPipeline = timeNewSession(shifted, updateOptions);+ report.splits = checkSplits(inputA, renderOptions, samples);+ report.allSplitsIdentical = report.splits.every((row) => row.identical && row.resolveIdentical);++ const session = renderNative.createNativeSession(inputA);+ try {+ session.render(updateOptions);+ report.updateMaterials = timeUpdate(session, dimmed, updateOptions);+ report.updateMaterialsAndTransforms = timeUpdate(session, shifted, updateOptions);+ report.updateBackToStart = timeUpdate(session, inputA, updateOptions);+ } finally {+ session.close();+ }+ report.allUpdatesIdentical = [report.updateMaterials, report.updateMaterialsAndTransforms, report.updateBackToStart]+ .every((row) => row.identicalToOneShot);+ report.adapter = renderNative.traceNative(inputA, { ...updateOptions, samples: 1 }).adapter;+ console.log(`SESSION_PROGRESSIVE ${JSON.stringify(report)}`);+}++await run();diff --git a/changes/896-session-progressive.md b/changes/896-session-progressive.mdnew file mode 100644index 00000000..9396a2a8--- /dev/null+++ b/changes/896-session-progressive.md@@ -0,0 +1 @@+- A native session builds one image over several `render` calls (`accumulate`, `targetSamples`, `reset()`, `resolve()`) and applies new material values, lights and instance transforms with `update()` without a new pipeline or BLAS build (#896)diff --git a/docs/cycles-parity.md b/docs/cycles-parity.mdindex fc630736..c088ec13 100644--- a/docs/cycles-parity.md+++ b/docs/cycles-parity.md@@ -870,6 +870,23 @@ All image gates and the depth gate pass on both scenes. Every disagreeing pixelNot covered: the Classroom scene (instancing, 854 instances, depth of field, which the depth comparator does not model: a thin lens changes the ray-to-Z conversion), a scene with a background, and 4096 spp references.+## Progressive film and scene updates (#896, slice S2)++A native session builds one image over several `render` calls (`accumulate: true`, `targetSamples`, `reset()`, `resolve()`) and applies new material values, lights, selection weights and instance transforms with `update()`. The kernel adds one sample at a time to the film in sample order and the Sobol-Burley sequence is indexed by the whole image's target count, so call boundaries cannot change a sum. The TLAS is rebuilt over the kept BLAS on a transform change (wgpu 30.0.1 has no refit); a change of counts, triangles or mesh topology is refused with a message that says to create a new session.++Measured on one NVIDIA A10 (480 x 270, 32 samples, `bench/cycles-parity/session-progressive.mjs`):++| Check | `lit-interior` | `many-lights-500` |+| --- | --- | --- |+| Split calls (16+16, 8+15+9; both samplers; path regeneration on and off) equal one call, byte for byte | 8 of 8 | 8 of 8 |+| `update()` then `render` equals a fresh one-shot of the final input, byte for byte (materials; materials and transforms; back to start) | 3 of 3 | 3 of 3 |+| New session, cold pipeline | 6721 ms | 6899 ms |+| New session, pipeline already compiled in the process | 65 ms | 44 ms |+| Update plus render (4 samples), materials only | 17.5 ms | 43.1 ms |+| Update plus render, transforms (TLAS rebuilt) | 17.7 ms | 44.9 ms |++One-shot `traceNative` images (both kernels) and S1 session frames hash the same as origin/main built in the same container.+## Reproducible CommandsRun from the repository root in PowerShell. Set `$env:BLENDER_BIN` if Blender 5.3 is installed outside `C:\Program Files\Blender Foundation\Blender 5.3\blender.exe`, and pass an untracked `<out-dir>` (such as `artifacts/cycles-parity`) so binary `.exr` and `.npy` files stay out of Git:diff --git a/packages/render-native/README.md b/packages/render-native/README.mdindex 63710321..98deeefa 100644--- a/packages/render-native/README.md+++ b/packages/render-native/README.md@@ -64,10 +64,41 @@ session.close(); // frees the`createNativeSession(input, options)` takes a FORMAT-v2 input (it throws a `TypeError` for anything else and for `kernel: "legacy"`); `options` are defaults for every frame. `render(renderOptions)` takes what `traceNative` takes (`width`, `height`, `samples`, `samplesPerDispatch`, `maxSeconds`, `denoise`, the sampling and filter options) and returns what it returns plus four fields that tell what the frame reused: `pipelineReused` (the compiled kernel was held; the specialized kernel text did not change), `accelerationReused` (no acceleration structure build; true from the second frame on), `filmReused` (same image size, so the film and its bind group were kept; the film is cleared for each frame) and `frameIndex`. A frame that reuses something spends no time on it: the first frame reports the setup, upload and acceleration build seconds of the creation, later frames report `0` for the setup and the build.-`renderOptions.kernelParams` is the `kernelParams` of another `buildNativeInputV2` call on the same scene, which is how a frame gets another camera (or seed, bounces or filter). The seven record counts must match the session scene, or the frame throws and names the count. Changing the scene itself (geometry, materials, lights) needs a new session.+`renderOptions.kernelParams` is the `kernelParams` of another `buildNativeInputV2` call on the same scene, which is how a frame gets another camera (or seed, bounces or filter). The seven record counts must match the session scene, or the frame throws and names the count. Changing materials, lights or instance transforms is `session.update` (below); other changes to the scene need a new session.A frame may change these words of the 320 byte block: the camera, lens, aperture and sensor shift (bytes 112 to 191), `seed`, the bounce limits, clamps, filter, adaptive sampling, `film_exposure`, `filter_glossy`, the environment rotation and colour (204, 208), the fog fields (224 to 267) and `kernel_flags`. Fog and the kernel flags select kernel variants, so such a frame recompiles (`pipelineReused` is false). The other words describe data the session uploaded or compiled for, and a frame that changes one throws and names it: the seven record counts (84 to 108), `env_width`, `env_height`, `env_cdf_offset`, `env_total_weight` (192, 196, 200, 220), `emissive_total_weight`, `analytic_light_total_weight` (268, 272), `ies_table_offset` (284), `background_mis_weight` (292) and `sobol_table_offset` (296). A frame with another HDRI, or one where the session had none, needs a new session. A frame that fails leaves the creation costs for the next frame that succeeds, which then reports them.-A frame may change these words of the 320 byte block and no others of the scene: the camera, lens, aperture and sensor shift (bytes 112 to 191), , the bounce limits, clamps, filter, adaptive sampling, , , the environment rotation and colour (204, 208), the fog fields (224 to 267) and . Fog and the kernel flags select kernel variants, so such a frame recompiles ( is false). These words describe data the session uploaded or compiled for, and a frame that changes one throws and names it: the seven record counts (84 to 108), , , , (192, 196, 200, 220), , (268, 272), , (284, 296) and (292). A frame with another HDRI, or with one where the session had none, therefore needs a new session. A frame that fails leaves the creation costs for the next frame that succeeds, which then reports them.+A frame is byte-identical to the `traceNative` render of the same input and options: `traceNative` runs a session that renders once. `render` after `close()` throws, and so does a frame on a session whose device was lost; the error says to create a new session. A plain frame clears the film and starts at sample 0.-A frame is byte-identical to the `traceNative` render of the same input and options: `traceNative` runs a session that renders once. `render` after `close()` throws, and so does a frame on a session whose device was lost; the error says to create a new session. The film does not carry samples from one frame to the next, and nothing in the scene can be updated in place yet.+### Progressive film++`render({ samples: 16, accumulate: true, targetSamples: 64 })` adds its samples to the film instead of starting an image, so one image can grow over several calls and be read at any point:++```js+const first = session.render({ samples: 16, accumulate: true, targetSamples: 64 }); // samples 0 to 15 of a 64 sample image+const second = session.render({ samples: 48, accumulate: true }); // samples 16 to 63, onto the same film+const preview = session.resolve({ denoise: 'atrous' }); // the film as it stands, nothing traced+session.reset(); // clears the film; the next accumulate call starts a new image+```++`targetSamples` is the total the image will hold. It is the length of each pixel's section of the sample sequence, so the calls must agree on it: the first call of an image sets it, later calls leave it out (or repeat it) and are refused if they would pass it. With it, the film after any split of the samples into calls (2, 3 or uneven) is byte-identical to one `traceNative` render of `targetSamples` samples, for both samplers, with `pathRegeneration` on or off and with any `samplesPerDispatch`: the kernel adds one sample at a time in sample order into the pixel's running sums (see the section above), so where a call or a dispatch ends changes nothing. The result carries `firstSample` (where this call began), `filmSamples` (what the film holds after it) and `targetSamples` (`null` for a plain frame). `resolve({ denoise })` returns the same fields as a render (`rgba`, `depth`, `albedo`, `normal`, `variance`, `denoisedRgba` for `denoise: "atrous"`) for what the film holds; it compiles, builds and draws nothing, and it throws when the film holds no samples.++A call must keep the image size and every render setting of the call that began the image (camera, seed, sampler, bounces and the rest of `kernelParams`); one that does not is refused with the way out (`reset()`, or a plain frame), and so is one that asks for more samples than `targetSamples` leaves. A refused call leaves the film as it was. A call that fails while drawing (a `maxSeconds` limit, a lost device) ends the image, since the film then holds an unknown number of samples: `resolve()` throws, and the next accumulating call starts a new image and needs `targetSamples` again. `maxSeconds` counts the seconds of one call.++### Updating the scene++`session.update(newInput)` takes a FORMAT-v2 input packed from the same scene after a change of values and applies it to the card without compiling a pipeline or building a BLAS:++| Changed in `newInput` | Applied as |+| --- | --- |+| camera, seed and other render settings (`kernelParams`) | the new block becomes the session default |+| `materials` (colour, roughness, emission strength and the other values) | the table's buffer is replaced |+| `lights`, `emissiveTriangles`, `lightTreeNodes`, `lightTreeEmitters`, `lightToTree` | the table's buffers are replaced, with the selection weights of `kernelParams` (bytes 268, 272, 292) |+| instance transforms and ray visibility | the instance table is replaced and the TLAS is rebuilt over the kept BLAS |+| instance material overrides, colours, light linking | the instance table is replaced, no TLAS rebuild |++The pinned wgpu has no TLAS refit (`PreferUpdate` is accepted and rebuilds), so a rebuild is the cost of moving an instance; the BLAS, which hold the triangles, are never touched. `update` returns `uploadedTables`, `accelerationRebuilt`, `changedInstances`, `kernelRespecialized` (the new tables change which features the kernel text is specialized for, for example the first transmissive material, so the next render compiles) and the seconds. It clears the film, ends a progressive image, and the next frame equals the `traceNative` render of `newInput` byte for byte. The next frame reports `accelerationReused: true`, and `pipelineReused: false` only when `kernelRespecialized` was true.++An update that changes a record count (instances, triangles, materials, emissive triangles, lights, light tree nodes, textures), the geometry, the textures, the environment map or which mesh an instance places is refused before anything changes, with an error that names what differs and says to create a new session. Moving an emissive instance means the input carries new `emissiveTriangles` and light tree tables for it, which the update applies like any other table.++A frame may change these words of the 320 byte block: the camera, lens, aperture and sensor shift (bytes 112 to 191), `seed`, the bounce limits, clamps, filter, adaptive sampling, `film_exposure`, `filter_glossy`, the environment rotation and colour (204, 208), the fog fields (224 to 267) and `kernel_flags`. The scene-bound words stay with the session (above), until an update brings new selection weights.diff --git a/packages/render-native/index.mjs b/packages/render-native/index.mjsindex ee05eabc..5319a5ec 100644--- a/packages/render-native/index.mjs+++ b/packages/render-native/index.mjs@@ -27,6 +27,7 @@ import {validateImagePixelCount,validateMaxSeconds,validatePackOptions,+ validateDenoiseOption,} from './pack-input-v2.mjs';export { buildNativeInput, buildNativeTexelInput } from './pack-input.mjs';@@ -383,25 +384,149 @@ export function resolveSessionFrame(sessionInput, sessionOptions, renderOptions)baseKernelParams = renderOptions.kernelParams;}const kernelParams = patchedCyclesKernelParams(sessionInput, baseKernelParams, options, 'NativeSession.render');- const { width, height, samples, samplesPerDispatch, maxSeconds, bootstrapKernel, denoise } = options;- return { width, height, samples, samplesPerDispatch, maxSeconds, bootstrapKernel, denoise, kernelParams };+ const { width, height, samples, samplesPerDispatch, maxSeconds, bootstrapKernel, denoise, accumulate, targetSamples } = options;+ validateProgressiveOptions({ accumulate, targetSamples, samples });+ return { width, height, samples, samplesPerDispatch, maxSeconds, bootstrapKernel, denoise, kernelParams, accumulate, targetSamples };+}++const MAX_TARGET_SAMPLES = 16777216;++function validateProgressiveOptions({ accumulate, targetSamples, samples }) {+ if (accumulate !== undefined && typeof accumulate !== 'boolean') {+ throw new TypeError(`NativeSession.render: \`accumulate\` must be true, false or left out, got ${JSON.stringify(accumulate)}.`);+ }+ if (targetSamples === undefined) return;+ if (accumulate !== true) {+ throw new TypeError('NativeSession.render: `targetSamples` only applies with `accumulate: true`. Pass accumulate: true to build one image over several render calls.');+ }+ if (!Number.isInteger(targetSamples) || targetSamples < 1 || targetSamples > MAX_TARGET_SAMPLES) {+ throw new RangeError(`NativeSession.render: \`targetSamples\` must be an integer in [1, ${MAX_TARGET_SAMPLES}]; got ${JSON.stringify(targetSamples)}.`);+ }+ if (samples > targetSamples) {+ throw new RangeError(`NativeSession.render: \`samples\` (${samples}) is more than \`targetSamples\` (${targetSamples}). Pass targetSamples as the total for the whole image.`);+ }+}++// ---- Scene updates ----++const UPDATE_COUNT_NAMES = [+ 'instanceCount', 'triangleCount', 'materialCount', 'emissiveTriangleCount', 'lightCount', 'lightTreeNodeCount', 'lightTreeEmitterCount', 'textureCount',+];+// Tables a session update cannot change, with what each holds, for the error.+const UPDATE_FIXED_TABLES = [+ ['triangles', 'the geometry'],+ ['textureDescriptors', 'the textures'],+ ['textureTexels', 'the textures'],+ ['environmentTexels', 'the environment map'],+];+// Tables a session update can replace: same size, new values.+const UPDATE_VALUE_TABLES = ['instances', 'materials', 'emissiveTriangles', 'lights', 'lightTreeNodes', 'lightTreeEmitters', 'lightToTree'];+const INSTANCE_RECORD_BYTE_LENGTH = 160;+const INSTANCE_TOPOLOGY_FIELDS = [['blasIndex', 96], ['triangleOffset', 100], ['opaqueTriangleCount', 104], ['totalTriangleCount', 108]];++function bytesOfTable(table) {+ return table === undefined || table === null ? Buffer.alloc(0) : Buffer.from(table.buffer, table.byteOffset, table.byteLength);+}++function sameTableBytes(first, second) {+ return bytesOfTable(first).equals(bytesOfTable(second));+}++function refuseUpdate(detail) {+ return new Error(`NativeSession.update: ${detail} Create a new session with createNativeSession(input) for this input.`);+}++function checkUpdateKeepsRecordCounts(current, next) {+ for (const name of UPDATE_COUNT_NAMES) {+ const heldCount = current[name] ?? 0;+ const newCount = next[name] ?? 0;+ if (heldCount !== newCount) {+ throw refuseUpdate(`\`${name}\` changes from ${heldCount} to ${newCount}; a session keeps the tables at the size it was created with.`);+ }+ }+}++function checkUpdateKeepsFixedTables(current, next) {+ for (const [name, holds] of UPDATE_FIXED_TABLES) {+ if (!sameTableBytes(current[name], next[name])) {+ throw refuseUpdate(`\`${name}\` differs, and it holds ${holds}; a session update changes values of materials, lights and instance transforms only.`);+ }+ }+}++function checkUpdateKeepsInstanceMeshes(currentInstances, nextInstances) {+ const heldBytes = bytesOfTable(currentInstances);+ const newBytes = bytesOfTable(nextInstances);+ for (let offset = 0; offset < newBytes.length; offset += INSTANCE_RECORD_BYTE_LENGTH) {+ for (const [fieldName, fieldOffset] of INSTANCE_TOPOLOGY_FIELDS) {+ const heldWord = heldBytes.readUInt32LE(offset + fieldOffset);+ const newWord = newBytes.readUInt32LE(offset + fieldOffset);+ if (heldWord !== newWord) {+ throw refuseUpdate(`instance ${offset / INSTANCE_RECORD_BYTE_LENGTH} changes \`${fieldName}\` from ${heldWord} to ${newWord}; an update may move or restyle an instance but not change the mesh it places.`);+ }+ }+ }+}++/**+ * Compares a new FORMAT-v2 input with the one a session holds and returns the tables to send: those whose bytes changed.+ * Refuses, naming what changed, an input with other record counts, other geometry, textures or environment, or instances+ * that place other meshes. Exported for tests; not part of the public API.+ */+export function planNativeSessionUpdate(currentInput, nextInput) {+ checkUpdateKeepsRecordCounts(currentInput, nextInput);+ checkUpdateKeepsFixedTables(currentInput, nextInput);+ const changedTables = {};+ for (const name of UPDATE_VALUE_TABLES) {+ if (!sameTableBytes(currentInput[name], nextInput[name])) changedTables[name] = nextInput[name];+ }+ if (changedTables.instances !== undefined) {+ checkUpdateKeepsInstanceMeshes(currentInput.instances, nextInput.instances);+ }+ return changedTables;}// Exported for tests, which pass a stand-in for the addon's session class; not part of the public API.export function wrapNativeSession(nativeSession, sessionInput, sessionOptions) {let closed = false;+ let heldInput = sessionInput;+ function requireOpen(methodName) {+ if (closed) {+ throw new Error(`NativeSession.${methodName}: this session is closed. Create a new one with createNativeSession(input).`);+ }+ }return {get closed() {return closed;},render(renderOptions = {}) {- if (closed) {- throw new Error('NativeSession.render: this session is closed. Create a new one with createNativeSession(input).');- }- const frame = resolveSessionFrame(sessionInput, sessionOptions, renderOptions);+ requireOpen('render');+ const frame = resolveSessionFrame(heldInput, sessionOptions, renderOptions);const { trace, session } = nativeSession.render(frame);return { ...trace, ...session };},+ reset() {+ requireOpen('reset');+ nativeSession.reset();+ },+ resolve(resolveOptions = {}) {+ requireOpen('resolve');+ if (resolveOptions === null || typeof resolveOptions !== 'object') {+ throw new TypeError('NativeSession.resolve: `resolveOptions` must be an object.');+ }+ const denoise = resolveOptions.denoise ?? sessionOptions.denoise;+ validateDenoiseOption(denoise, 'NativeSession.resolve');+ const { trace, session } = nativeSession.resolve({ denoise });+ return { ...trace, ...session };+ },+ update(newInput) {+ requireOpen('update');+ const nextInput = resolveSessionCreation(newInput, sessionOptions);+ const changedTables = planNativeSessionUpdate(heldInput, nextInput);+ const report = nativeSession.update({ kernelParams: nextInput.kernelParams, ...changedTables });+ heldInput = nextInput;+ return report;+ },close() {if (closed) return;closed = true;@@ -418,6 +543,19 @@ export function wrapNativeSession(nativeSession, sessionInput, sessionOptions) {* frame at the same size also keeps the film. `renderOptions.kernelParams` brings another camera of the same scene: the* `kernelParams` of a second `buildNativeInputV2` call. `options` are defaults for every frame. `close()` frees the card.* A frame equals the `traceNative` render of the same input and options byte for byte.+ *+ * Progressive film: `render({ samples, accumulate: true, targetSamples })` adds `samples` to the image instead of starting a new+ * one, so an image can grow over several calls (the first call of an image sets `targetSamples`, the total it will hold; later+ * calls leave it out). The calls continue one sample sequence, so the film after all of them equals one render of `targetSamples`+ * samples byte for byte. The reports carry `firstSample`, `filmSamples` and `targetSamples`. `reset()` starts the image over.+ * `resolve({ denoise })` returns the film as it stands without tracing. A later call must keep the size and the render settings+ * (camera, seed, sampler) of the first; a plain frame (no `accumulate`) discards the progressive image.+ *+ * `update(newInput)` takes a FORMAT-v2 input packed from the same scene with other material values, lights, emission or instance+ * transforms and applies it without a new pipeline or BLAS build (the TLAS is rebuilt when a transform changed). It returns+ * `uploadedTables`, `accelerationRebuilt`, `changedInstances`, `kernelRespecialized` and the seconds. It clears the film, and a+ * following frame equals the `traceNative` render of `newInput`. A change of record counts, geometry, textures, the environment+ * map or of the mesh an instance places is refused with an error that says to create a new session.*/export function createNativeSession(input, options = {}) {const sessionInput = resolveSessionCreation(input, options);diff --git a/packages/render-native/src/cycles/mod.rs b/packages/render-native/src/cycles/mod.rsindex 02b0dd9d..55f80102 100644--- a/packages/render-native/src/cycles/mod.rs+++ b/packages/render-native/src/cycles/mod.rs@@ -208,6 +208,33 @@ pub(crate) fn check_frame_params_keep_scene_counts(session_kernel_params: &[u8],Ok(())}+/// The scene-bound words an update of the light or emission tables may change: the selection weights are sums over the+/// tables the update replaces. Every other scene-bound word (counts, environment, texel pool offsets) must stay.+const UPDATABLE_SCENE_WORD_OFFSETS: [usize; 3] = [268, 272, 292];++/// Checks that the kernel parameters of a session update describe a scene of the same shape as the session's: the same+/// counts, environment and texel pool offsets. The light and emission selection weights may differ.+pub(crate) fn check_update_params_keep_scene_shape(session_kernel_params: &[u8], update_kernel_params: &[u8]) -> Result<()> {+ for (name, byte_offset) in SCENE_BOUND_FIELDS {+ if UPDATABLE_SCENE_WORD_OFFSETS.contains(&byte_offset) {+ continue;+ }+ if session_kernel_params.len() < byte_offset + 4 || update_kernel_params.len() < byte_offset + 4 {+ return Err(failure(format!(+ "kernelParams must hold the 320 byte KernelParamsV2 block to read {name} at byte {byte_offset}."+ )));+ }+ let session_word = read_u32_le(session_kernel_params, byte_offset);+ let update_word = read_u32_le(update_kernel_params, byte_offset);+ if session_word != update_word {+ return Err(failure(format!(+ "The update changes {name} (byte {byte_offset}) from {session_word} to {update_word} (raw 32 bit words). A session update keeps the shape of the scene it holds (the record counts, the environment and the textures); create a new session for this input."+ )));+ }+ }+ Ok(())+}+/// The compute entry point to run for a kernel parameter block: `main`, or `light_tree_probe` when it carries/// `KERNEL_FLAG_LIGHT_TREE_PROBE` (tests).pub(crate) fn trace_entry_point_for_params(kernel_params: &[u8]) -> &'static str {@@ -753,6 +780,29 @@ mod specialization_tests {assert!(check_frame_params_keep_scene_counts(&with_environment, &no_environment).is_err());}+ #[test]+ fn an_update_may_change_the_selection_weights_but_not_the_shape_of_the_scene() {+ let session_params = make_kp(0, 0.0, 512, 256, 3.0);+ for byte_offset in UPDATABLE_SCENE_WORD_OFFSETS {+ let mut reweighted = session_params.clone();+ reweighted[byte_offset..byte_offset + 4].copy_from_slice(&0x4000_0000u32.to_le_bytes());+ assert!(check_update_params_keep_scene_shape(&session_params, &reweighted).is_ok(), "byte {byte_offset}");+ }+ for (name, byte_offset) in SCENE_BOUND_FIELDS {+ if UPDATABLE_SCENE_WORD_OFFSETS.contains(&byte_offset) {+ continue;+ }+ let mut reshaped = session_params.clone();+ reshaped[byte_offset..byte_offset + 4].copy_from_slice(&0x1234_5678u32.to_le_bytes());+ let message = check_update_params_keep_scene_shape(&session_params, &reshaped)+ .expect_err("a changed scene shape must be refused")+ .to_string();+ assert!(message.contains(name), "{name}: {message}");+ assert!(message.contains("create a new session"), "{name}: {message}");+ }+ assert!(check_update_params_keep_scene_shape(&session_params, &session_params[..64]).is_err());+ }+#[test]fn per_frame_settings_may_change_freely() {let session_params = make_kp(0, 0.0, 512, 256, 3.0);diff --git a/packages/render-native/src/host/accel.rs b/packages/render-native/src/host/accel.rsindex 34f05967..a244eb96 100644--- a/packages/render-native/src/host/accel.rs+++ b/packages/render-native/src/host/accel.rs@@ -22,7 +22,9 @@ pub(crate) struct UnpackedTriangles {pub(crate) struct CyclesAcceleration {pub(crate) tlas: wgpu::Tlas,- pub(crate) _blases: Vec<wgpu::Blas>,+ pub(crate) blases: Vec<wgpu::Blas>,+ /// For each instance, the index into `blases` of the mesh it places; a transform update rebuilds the TLAS from it.+ pub(crate) instance_blas_indices: Vec<usize>,pub(crate) _vertex_buffer: wgpu::Buffer,}@@ -243,6 +245,60 @@ fn create_blas_plan_for_slice(device: &wgpu::Device, spec: BlasSliceSpec) -> Bla}}+/// The object-to-world rows of the instance record that starts at byte `base`, as a hardware TLAS transform.+fn read_instance_transform(instance_bytes: &[u8], base: usize) -> [f32; 12] {+ let mut transform_row_major_3x4 = [0.0f32; 12];+ for float_index in 0..12 {+ transform_row_major_3x4[float_index] = read_f32_le(instance_bytes, base + float_index * 4);+ }+ transform_row_major_3x4+}++/// The ray-kind bits of `visibility_flags` the hardware culls on (the negative-scale bit is not one of them).+pub(crate) fn instance_cull_mask(visibility_flags: u32) -> u8 {+ (visibility_flags & INSTANCE_RAY_VISIBILITY_MASK) as u8+}++/// Rebuilds the TLAS of a session from a new instance table with the same instances in the same order: new transforms+/// and ray visibility, the same meshes. The BLAS are not touched. The pinned wgpu has no TLAS refit (`PreferUpdate` is+/// accepted and rebuilds), so a rebuild is the whole cost of moving an instance.+pub(crate) fn rebuild_cycles_tlas(+ device: &wgpu::Device,+ queue: &wgpu::Queue,+ acceleration: &mut CyclesAcceleration,+ instance_bytes: &[u8],+) -> Result<()> {+ let instance_count = acceleration.instance_blas_indices.len();+ if instance_count == 0 || instance_bytes.len() != instance_count * INSTANCE_RECORD_BYTES {+ return Err(failure(format!(+ "The instance table must hold the session's {instance_count} instances of {INSTANCE_RECORD_BYTES} bytes to rebuild the TLAS; got {} bytes.",+ instance_bytes.len()+ )));+ }+ for instance_index in 0..instance_count {+ let base = instance_index * INSTANCE_RECORD_BYTES;+ let visibility_flags = read_u32_le(instance_bytes, base + 116);+ let blas = &acceleration.blases[acceleration.instance_blas_indices[instance_index]];+ let placed = wgpu::TlasInstance::new(+ blas,+ read_instance_transform(instance_bytes, base),+ instance_index as u32,+ instance_cull_mask(visibility_flags),+ );+ acceleration.tlas[instance_index] = Some(placed);+ }+ let mut build_encoder = device.create_command_encoder(&wgpu::CommandEncoderDescriptor {+ label: Some("cycles tlas rebuild"),+ });+ build_encoder.build_acceleration_structures(+ std::iter::empty::<&wgpu::BlasBuildEntry>(),+ std::iter::once(&acceleration.tlas),+ );+ queue.submit(Some(build_encoder.finish()));+ let _ = device.poll(wgpu::PollType::wait_indefinitely());+ Ok(())+}+/// Builds an empty masked-out 1-triangle BLAS + TLAS when a scene has zero instances or runs a lobe-only probe.pub(crate) fn build_empty_cycles_acceleration(device: &wgpu::Device, queue: &wgpu::Queue) -> CyclesAcceleration {let vertex_buffer = create_vertex_buffer(device, &[0.0f32; 9]);@@ -290,7 +346,8 @@ pub(crate) fn build_empty_cycles_acceleration(device: &wgpu::Device, queue: &wgplet _ = device.poll(wgpu::PollType::wait_indefinitely());CyclesAcceleration {tlas,- _blases: vec![dummy_plan.blas],+ blases: vec![dummy_plan.blas],+ instance_blas_indices: Vec::new(),_vertex_buffer: vertex_buffer,}}@@ -361,17 +418,13 @@ pub(crate) fn build_cycles_acceleration_structure(next_index};- let mut transform_row_major_3x4 = [0.0f32; 12];- for float_index in 0..12 {- transform_row_major_3x4[float_index] = read_f32_le(instance_bytes, base + float_index * 4);- }- let cull_mask = (visibility_flags & INSTANCE_RAY_VISIBILITY_MASK) as u8;placements.push(ParsedInstancePlacement {- transform_row_major_3x4,+ transform_row_major_3x4: read_instance_transform(instance_bytes, base),blas_plan_index,- cull_mask,+ cull_mask: instance_cull_mask(visibility_flags),});}+ let instance_blas_indices: Vec<usize> = placements.iter().map(|placement| placement.blas_plan_index).collect();let vertices = unpack_v2_triangle_vertices(triangle_bytes, triangle_count);let vertex_buffer = create_vertex_buffer(device, &vertices);@@ -431,7 +484,8 @@ pub(crate) fn build_cycles_acceleration_structure(let blases = plans.into_iter().map(|plan| plan.blas).collect();Ok(CyclesAcceleration {tlas,- _blases: blases,+ blases,+ instance_blas_indices,_vertex_buffer: vertex_buffer,})}diff --git a/packages/render-native/src/host/cycles_session.rs b/packages/render-native/src/host/cycles_session.rsindex 00ee4da7..02998f3d 100644--- a/packages/render-native/src/host/cycles_session.rs+++ b/packages/render-native/src/host/cycles_session.rs@@ -6,15 +6,18 @@use std::sync::atomic::Ordering;use std::time::Instant;+use napi::bindgen_prelude::{Float32Array, Uint32Array, Uint8Array};use napi::Result;use crate::cycles::{assemble_cycles_kernel_entry, check_counts_match_kernel_params, check_frame_params_keep_scene_counts,- scan_scene_specialization, specialize_kernel_source, trace_entry_point_for_params, SceneSpecialization,+ check_update_params_keep_scene_shape, scan_scene_specialization, specialize_kernel_source,+ trace_entry_point_for_params, SceneSpecialization,};-use crate::host::accel::{build_cycles_acceleration_structure, CyclesAcceleration};-use crate::host::device::failure;-use crate::host::film::{image_accumulation_bytes, image_workgroups};+use crate::host::accel::{build_cycles_acceleration_structure, rebuild_cycles_tlas, CyclesAcceleration};+use crate::host::cycles_update::{choose_film_use, plan_instance_update, FilmRequest, ProgressiveFilm, UpdatableTable};+use crate::host::device::{failure, storage_buffer};+use crate::host::film::{image_accumulation_bytes, image_workgroups, read_accumulation};use crate::host::session::{create_cycles_bind_group, get_cycles_device_context, get_or_compile_cycles_pipeline_on, pipeline_key,trace_cycles_samples, validate_cycles_input, validate_kernel_params_v2, validate_light_tree_flag_has_tables,@@ -41,6 +44,32 @@ pub(crate) struct CyclesRenderRequest<'a> {/// A KernelParamsV2 block for this frame (another camera, seed or filter of the same scene); absent means the block/// the session was created with.pub(crate) kernel_params: Option<&'a [u8]>,+ /// Add this call's samples to the film instead of starting a new image (see `choose_film_use`).+ pub(crate) accumulate: bool,+ /// The sample count of the whole image; required by the first accumulating call, optional (and equal) after.+ pub(crate) target_samples: Option<u32>,+}++/// New values for the scene tables a session holds, with the kernel parameters that go with them. Only the tables that+/// changed are listed.+pub(crate) struct CyclesSceneUpdate<'a> {+ pub(crate) kernel_params: &'a [u8],+ pub(crate) tables: Vec<(UpdatableTable, &'a [u8])>,+}++/// What an update did, so a test or a caller can see it kept the pipeline and the BLAS instead of timing it.+pub(crate) struct CyclesUpdateReport {+ /// The tables whose buffers were replaced, by their input names.+ pub(crate) uploaded_tables: Vec<&'static str>,+ /// The TLAS was rebuilt over the kept BLAS (a transform or ray visibility changed).+ pub(crate) acceleration_rebuilt: bool,+ /// How many instance records differ from the old table.+ pub(crate) changed_instances: u32,+ /// The new tables change what the kernel text is specialized for, so the next render compiles it again.+ pub(crate) kernel_respecialized: bool,+ pub(crate) upload_seconds: f64,+ pub(crate) acceleration_rebuild_seconds: f64,+ pub(crate) update_seconds: f64,}/// The per-phase seconds of one frame and what it reused. A frame that reuses something spends no time on it: the@@ -58,6 +87,12 @@ pub(crate) struct CyclesRenderReport {pub(crate) film_reused: bool,/// How many frames this session finished before this one.pub(crate) frame_index: u32,+ /// The index of the first sample this call drew (0 unless it continued a progressive film).+ pub(crate) first_sample: u32,+ /// How many samples the film holds after this call.+ pub(crate) film_samples: u32,+ /// The sample count the progressive film was started for; absent for a plain frame.+ pub(crate) target_samples: Option<u32>,}pub(crate) struct CyclesRender {@@ -104,15 +139,108 @@ impl SessionGpuState {}}+/// The number of scene buffers `upload_cycles_scene_tables` makes.+const SCENE_BUFFER_COUNT: usize = 11;++/// Host copies of what the kernel specialization reads, so an update can scan the new tables without the whole input:+/// the record counts and the small tables the scan walks. The triangles, texels and emitters are not kept.+/// If `scan_scene_specialization` starts to read another table, keep it here too.+struct RetainedTables {+ instance_count: u32,+ material_count: u32,+ emissive_triangle_count: u32,+ light_count: u32,+ light_tree_node_count: u32,+ texture_count: u32,+ instances: Vec<u8>,+ materials: Vec<u8>,+ lights: Vec<u8>,+ texture_descriptors: Vec<u8>,+ /// The byte length of each scene buffer's source, by buffer index: an update must bring a table of the same size.+ table_lengths: [usize; SCENE_BUFFER_COUNT],+}++impl RetainedTables {+ fn of_input(input: &NativeTraceInputV2) -> RetainedTables {+ let mut table_lengths = [0usize; SCENE_BUFFER_COUNT];+ table_lengths[UpdatableTable::Instances.buffer_index()] = input.instances.len();+ table_lengths[UpdatableTable::Materials.buffer_index()] = input.materials.len();+ table_lengths[UpdatableTable::EmissiveTriangles.buffer_index()] = input.emissive_triangles.len();+ table_lengths[UpdatableTable::Lights.buffer_index()] = input.lights.len();+ table_lengths[UpdatableTable::LightTreeNodes.buffer_index()] = input.light_tree_nodes.len();+ table_lengths[UpdatableTable::LightTreeEmitters.buffer_index()] =+ input.light_tree_emitters.as_ref().map_or(0, |emitters| emitters.len());+ table_lengths[UpdatableTable::LightToTree.buffer_index()] =+ input.light_to_tree.as_ref().map_or(0, |words| words.len() * 4);+ RetainedTables {+ instance_count: input.instance_count,+ material_count: input.material_count,+ emissive_triangle_count: input.emissive_triangle_count,+ light_count: input.light_count,+ light_tree_node_count: input.light_tree_node_count,+ texture_count: input.texture_count,+ instances: input.instances.to_vec(),+ materials: input.materials.to_vec(),+ lights: input.lights.to_vec(),+ texture_descriptors: input.texture_descriptors.to_vec(),+ table_lengths,+ }+ }++ /// The specialization of these tables; equal to `scan_scene_specialization` of the whole input they came from.+ fn specialization(&self) -> SceneSpecialization {+ let scan_input = NativeTraceInputV2 {+ schema_version: 2,+ kernel_params: Uint8Array::new(Vec::new()),+ instances: Uint8Array::new(self.instances.clone()),+ instance_count: self.instance_count,+ triangles: Uint8Array::new(Vec::new()),+ triangle_count: 0,+ materials: Uint8Array::new(self.materials.clone()),+ material_count: self.material_count,+ emissive_triangles: Uint8Array::new(Vec::new()),+ emissive_triangle_count: self.emissive_triangle_count,+ lights: Uint8Array::new(self.lights.clone()),+ light_count: self.light_count,+ light_tree_nodes: Uint8Array::new(Vec::new()),+ light_tree_node_count: self.light_tree_node_count,+ light_tree_emitters: None,+ light_tree_emitter_count: None,+ light_to_tree: None,+ texture_descriptors: Uint8Array::new(self.texture_descriptors.clone()),+ texture_count: self.texture_count,+ texture_texels: Uint32Array::new(Vec::new()),+ environment_texels: Float32Array::new(Vec::new()),+ };+ scan_scene_specialization(&scan_input)+ }++ fn keep_table(&mut self, table: UpdatableTable, bytes: &[u8]) {+ match table {+ UpdatableTable::Instances => self.instances = bytes.to_vec(),+ UpdatableTable::Materials => self.materials = bytes.to_vec(),+ UpdatableTable::Lights => self.lights = bytes.to_vec(),+ _ => {}+ }+ }+}+pub(crate) struct CyclesSession {context: CyclesDeviceContext,- /// The kernel parameters the session was created with, the default for a frame that brings none.+ /// The kernel parameters the session was created with (or last updated to), the default for a frame that brings none.session_kernel_params: Vec<u8>,scene_specialization: SceneSpecialization,+ retained: RetainedTables,light_tree_node_count: u32,has_light_tree_tables: bool,creation_costs: Option<CreationCosts>,renders_completed: u32,+ /// The image being built over several calls; `None` after a plain frame, a reset, an update or a failed call.+ progressive: Option<ProgressiveFilm>,+ /// The film holds the samples of the last successful render, so `resolve` has something to read.+ film_holds_samples: bool,+ /// How many samples per pixel the film holds; meaningful while `film_holds_samples`.+ film_sample_count: u32,/// `None` once the session is closed.gpu: Option<SessionGpuState>,}@@ -180,10 +308,14 @@ impl CyclesSession {context,session_kernel_params: input.kernel_params.to_vec(),scene_specialization,+ retained: RetainedTables::of_input(input),light_tree_node_count: input.light_tree_node_count,has_light_tree_tables: input.light_tree_emitters.is_some(),creation_costs: Some(CreationCosts { setup_seconds, upload_seconds, acceleration_build_seconds }),renders_completed: 0,+ progressive: None,+ film_holds_samples: false,+ film_sample_count: 0,gpu: Some(SessionGpuState {scene_tables,acceleration,@@ -226,11 +358,23 @@ impl CyclesSession {}/// Renders one frame. The scene, the acceleration structures and (while the specialized kernel text and the image size- /// stay the same) the pipeline and the film are reused; the film is cleared, so a frame starts from zero as a one-shot does.+ /// stay the same) the pipeline and the film are reused. A plain frame clears the film and starts from sample 0, as a+ /// one-shot does. An accumulating call adds its samples to the film and continues the sample sequence (see `choose_film_use`).pub(crate) fn render(&mut self, request: &CyclesRenderRequest<'_>) -> Result<CyclesRender> {self.fail_if_unusable()?;validate_render_extent(request.width, request.height, request.samples)?;let frame_kernel_params = self.frame_kernel_params(request.kernel_params)?;+ let film_use = choose_film_use(+ self.progressive.as_ref(),+ &FilmRequest {+ width: request.width,+ height: request.height,+ samples: request.samples,+ accumulate: request.accumulate,+ target_samples: request.target_samples,+ frame_kernel_params: &frame_kernel_params,+ },+ )?;let frame_index = self.renders_completed;let creation_costs = self.creation_costs;@@ -251,13 +395,17 @@ impl CyclesSession {let upload_started = Instant::now();let film_reused = ensure_film(context, gpu, request.width, request.height)?;let render_parameters =- patch_render_parameters(&frame_kernel_params, request.width, request.height, request.samples);+ patch_render_parameters(&frame_kernel_params, request.width, request.height, film_use.total_samples);context.queue.write_buffer(&gpu.parameters, 0, &render_parameters);- if film_reused {+ if film_reused && film_use.starts_new_image {clear_film(context, gpu.film()?);}let upload_seconds = upload_started.elapsed().as_secs_f64();+ // From here the film changes: a call that fails leaves it unusable, so nothing may claim it holds an image.+ self.progressive = None;+ self.film_holds_samples = false;+let film = gpu.film()?;let target = CyclesDispatchTarget {device: &context.device,@@ -272,6 +420,7 @@ impl CyclesSession {let plan = choose_dispatch_plan(request.samples, request.samples_per_dispatch, request.max_seconds);let trace = trace_cycles_samples(&target,+ film_use.first_sample,request.samples,plan,image_workgroups(request.width, request.height),@@ -280,7 +429,9 @@ impl CyclesSession {)?;self.renders_completed = frame_index + 1;self.creation_costs = None;+ self.film_holds_samples = true;+ let film_after = film_use.film_after.as_ref();let report = CyclesRenderReport {setup_seconds: creation_costs.as_ref().map_or(0.0, |costs| costs.setup_seconds),compile_seconds,@@ -290,9 +441,133 @@ impl CyclesSession {acceleration_reused,film_reused,frame_index,+ first_sample: film_use.first_sample,+ film_samples: film_after.map_or(request.samples, |film| film.samples_drawn),+ target_samples: film_after.map(|film| film.target_samples),};+ self.film_sample_count = report.film_samples;+ self.progressive = film_use.film_after;Ok(CyclesRender { trace, report })}++ /// Starts the progressive image over: the film is cleared and the next accumulating call begins at sample 0, with a+ /// `targetSamples` of its choosing. The scene, the pipeline and the film's memory stay.+ pub(crate) fn reset(&mut self) -> Result<()> {+ self.fail_if_unusable()?;+ self.clear_progressive_film();+ Ok(())+ }++ fn clear_progressive_film(&mut self) {+ self.progressive = None;+ self.film_holds_samples = false;+ if let Some(film) = self.gpu.as_ref().and_then(|gpu| gpu.film.as_ref()) {+ clear_film(&self.context, film);+ }+ }++ /// The film as it stands, read back without tracing: the sums of every sample drawn since the image began.+ pub(crate) fn read_film(&mut self) -> Result<CyclesFilmRead> {+ self.fail_if_unusable()?;+ let held_film = self.gpu.as_ref().and_then(|gpu| gpu.film.as_ref());+ let film = match (held_film, self.film_holds_samples) {+ (Some(film), true) => film,+ _ => {+ return Err(failure(+ "The session film holds no samples to resolve: render first (with accumulate: true to build an image over several calls). reset() and update() clear the film.",+ ))+ }+ };+ let sums = read_accumulation(+ &self.context.device,+ &self.context.queue,+ &film.accumulation,+ image_accumulation_bytes(film.width, film.height),+ )?;+ Ok(CyclesFilmRead {+ sums,+ width: film.width,+ height: film.height,+ film_samples: self.film_sample_count,+ target_samples: self.progressive.as_ref().map(|held| held.target_samples),+ frame_index: self.renders_completed,+ })+ }++ /// Replaces the values of scene tables without rebuilding the pipeline or the BLAS. The tables keep their size and the+ /// instances their meshes (see `plan_instance_update`); the TLAS is rebuilt only when a transform or a ray visibility+ /// changed. The film is cleared, since the image it holds no longer shows the scene. Everything is checked before+ /// anything on the card changes, so a refused update leaves the session as it was.+ pub(crate) fn update(&mut self, update: &CyclesSceneUpdate<'_>) -> Result<CyclesUpdateReport> {+ self.fail_if_unusable()?;+ let update_started = Instant::now();+ validate_kernel_params_v2(update.kernel_params)?;+ check_update_params_keep_scene_shape(&self.session_kernel_params, update.kernel_params)?;+ validate_light_tree_flag_has_tables(update.kernel_params, self.light_tree_node_count, self.has_light_tree_tables)?;+ for (table, bytes) in &update.tables {+ let held_length = self.retained.table_lengths[table.buffer_index()];+ if bytes.len() != held_length {+ return Err(failure(format!(+ "The new {} table holds {} bytes but the session holds {held_length}. An update keeps the record counts; create a new session for this input.",+ table.input_name(),+ bytes.len()+ )));+ }+ }+ let new_instances =+ update.tables.iter().find(|(table, _)| *table == UpdatableTable::Instances).map(|(_, bytes)| *bytes);+ let instance_plan = match new_instances {+ Some(bytes) => Some(plan_instance_update(&self.retained.instances, bytes)?),+ None => None,+ };++ let upload_started = Instant::now();+ let context = &self.context;+ let gpu = self.gpu.as_mut().ok_or_else(session_closed_failure)?;+ for (table, bytes) in &update.tables {+ let label = format!("cycles {} (updated)", table.input_name());+ gpu.scene_tables[table.buffer_index()] = storage_buffer(&context.device, &label, bytes);+ self.retained.keep_table(*table, bytes);+ }+ let upload_seconds = upload_started.elapsed().as_secs_f64();++ let rebuild_started = Instant::now();+ let acceleration_rebuilt = instance_plan.as_ref().is_some_and(|plan| plan.tlas_dirty);+ if let (true, Some(bytes)) = (acceleration_rebuilt, new_instances) {+ rebuild_cycles_tlas(&context.device, &context.queue, &mut gpu.acceleration, bytes)?;+ }+ let acceleration_rebuild_seconds = rebuild_started.elapsed().as_secs_f64();++ if !update.tables.is_empty() {+ rebind_film(context, gpu)?;+ }+ self.session_kernel_params = update.kernel_params.to_vec();+ let respecialized = self.retained.specialization();+ let kernel_respecialized = respecialized != self.scene_specialization;+ self.scene_specialization = respecialized;+ self.clear_progressive_film();++ Ok(CyclesUpdateReport {+ uploaded_tables: update.tables.iter().map(|(table, _)| table.input_name()).collect(),+ acceleration_rebuilt,+ changed_instances: instance_plan.map_or(0, |plan| plan.changed_instances as u32),+ kernel_respecialized,+ upload_seconds,+ acceleration_rebuild_seconds,+ update_seconds: update_started.elapsed().as_secs_f64(),+ })+ }+}++/// The film of a session read back without tracing.+pub(crate) struct CyclesFilmRead {+ pub(crate) sums: Vec<f32>,+ pub(crate) width: u32,+ pub(crate) height: u32,+ /// The samples per pixel the film holds.+ pub(crate) film_samples: u32,+ pub(crate) target_samples: Option<u32>,+ pub(crate) frame_index: u32,}/// Makes `gpu.pipeline` the pipeline for this frame's specialized kernel text; true when it already was.@@ -336,6 +611,28 @@ fn ensure_film(context: &CyclesDeviceContext, gpu: &mut SessionGpuState, width:Ok(false)}+/// Builds a new bind group over the current scene buffers and the film that exists, after an update replaced buffers.+fn rebind_film(context: &CyclesDeviceContext, gpu: &mut SessionGpuState) -> Result<()> {+ let Some(film) = gpu.film.as_ref() else {+ return Ok(());+ };+ let bind_group = with_cycles_cache_on(Some(&context.device_lost), |device, _queue, layout, lut| {+ create_cycles_bind_group(+ device,+ layout,+ &gpu.parameters,+ &gpu.acceleration.tlas,+ &gpu.scene_tables,+ &film.accumulation,+ lut,+ )+ })?;+ if let Some(film) = gpu.film.as_mut() {+ film.bind_group = bind_group;+ }+ Ok(())+}+fn clear_film(context: &CyclesDeviceContext, film: &SessionFilm) {let mut encoder = context.device.create_command_encoder(&wgpu::CommandEncoderDescriptor {label: Some("cycles film clear"),@@ -380,6 +677,69 @@ mod tests {assert!(matches!(choose_dispatch_plan(0, None, None), DispatchPlan::TimeBudget { largest_batch: 1 }));}+ /// One opaque material record with no texture on any slot (a texture index of -1 means none) and the given transmission.+ fn plain_material(transmission_weight: f32) -> Vec<u8> {+ let mut material = vec![0u8; 256];+ material[52..56].copy_from_slice(&transmission_weight.to_le_bytes());+ for texture_slot_byte in [212usize, 216, 224, 228, 236, 240, 244, 248, 252] {+ material[texture_slot_byte..texture_slot_byte + 4].copy_from_slice(&(-1i32).to_le_bytes());+ }+ material+ }++ fn scan_test_input(transmission_weight: f32, light_group_mask_lo: u32) -> NativeTraceInputV2 {+ let materials = plain_material(transmission_weight);+ let mut lights = vec![0u8; 128];+ lights[12..16].copy_from_slice(&2u32.to_le_bytes());+ lights[120..124].copy_from_slice(&light_group_mask_lo.to_le_bytes());+ lights[124..128].copy_from_slice(&0xFFFF_FFFFu32.to_le_bytes());+ NativeTraceInputV2 {+ schema_version: 2,+ kernel_params: Uint8Array::new(vec![0u8; 320]),+ instances: Uint8Array::new(vec![0u8; 160]),+ instance_count: 1,+ triangles: Uint8Array::new(vec![0u8; 224]),+ triangle_count: 1,+ materials: Uint8Array::new(materials),+ material_count: 1,+ emissive_triangles: Uint8Array::new(vec![0u8; 96]),+ emissive_triangle_count: 0,+ lights: Uint8Array::new(lights),+ light_count: 1,+ light_tree_nodes: Uint8Array::new(vec![0u8; 64]),+ light_tree_node_count: 1,+ light_tree_emitters: None,+ light_tree_emitter_count: None,+ light_to_tree: None,+ texture_descriptors: Uint8Array::new(vec![0u8; 32]),+ texture_count: 1,+ texture_texels: Uint32Array::new(vec![0u32; 4]),+ environment_texels: Float32Array::new(vec![0f32; 4]),+ }+ }++ #[test]+ fn the_retained_tables_specialize_the_kernel_like_the_whole_input() {+ for (transmission_weight, light_group_mask_lo) in [(0.0, 0xFFFF_FFFF), (0.7, 0xFFFF_FFFF), (0.0, 0x0F)] {+ let input = scan_test_input(transmission_weight, light_group_mask_lo);+ let retained = RetainedTables::of_input(&input);+ assert_eq!(retained.specialization(), scan_scene_specialization(&input));+ }+ let glass = RetainedTables::of_input(&scan_test_input(0.7, 0xFFFF_FFFF));+ let clear = RetainedTables::of_input(&scan_test_input(0.0, 0xFFFF_FFFF));+ assert_ne!(glass.specialization(), clear.specialization(), "a transmissive material changes the specialization");+ }++ #[test]+ fn keeping_an_updated_table_changes_what_the_specialization_reads() {+ let mut retained = RetainedTables::of_input(&scan_test_input(0.0, 0xFFFF_FFFF));+ let before = retained.specialization();+ retained.keep_table(UpdatableTable::Materials, &plain_material(0.7));+ assert_ne!(retained.specialization(), before);+ assert_eq!(retained.table_lengths[UpdatableTable::Materials.buffer_index()], 256);+ assert_eq!(retained.table_lengths[UpdatableTable::Lights.buffer_index()], 128);+ }+#[test]fn a_closed_session_error_says_how_to_continue() {let message = session_closed_failure().to_string();diff --git a/packages/render-native/src/host/cycles_update.rs b/packages/render-native/src/host/cycles_update.rsnew file mode 100644index 00000000..619b4558--- /dev/null+++ b/packages/render-native/src/host/cycles_update.rs@@ -0,0 +1,393 @@+//! The pure rules of a session scene update and of a progressive film (issue 896): what an update may change, what it+//! asks of the acceleration structure, and which samples the next call of a progressive film draws. Nothing here touches+//! the card, so the rules are covered by plain unit tests.++use napi::Result;++use crate::host::accel::{instance_cull_mask, INSTANCE_RECORD_BYTES};+use crate::host::device::failure;++const INSTANCE_TRANSFORM_BYTES: usize = 48;+const INSTANCE_VISIBILITY_FLAGS_BYTE: usize = 116;+/// The fields of an instance record that say which mesh it places. An update keeps them: they decide the BLAS slices.+const INSTANCE_TOPOLOGY_FIELDS: [(&str, usize); 4] = [+ ("blasIndex", 96),+ ("triangleOffset", 100),+ ("opaqueTriangleCount", 104),+ ("totalTriangleCount", 108),+];++/// The scene tables an update can replace, with the position of each in the buffers `upload_cycles_scene_tables` makes.+#[derive(Clone, Copy, Debug, PartialEq, Eq)]+pub(crate) enum UpdatableTable {+ Instances,+ Materials,+ EmissiveTriangles,+ Lights,+ LightTreeNodes,+ LightTreeEmitters,+ LightToTree,+}++impl UpdatableTable {+ /// The index in the scene buffers; keep in step with the order of `upload_cycles_scene_tables`.+ pub(crate) fn buffer_index(self) -> usize {+ match self {+ UpdatableTable::Instances => 0,+ UpdatableTable::Materials => 2,+ UpdatableTable::EmissiveTriangles => 3,+ UpdatableTable::Lights => 4,+ UpdatableTable::LightTreeNodes => 5,+ UpdatableTable::LightTreeEmitters => 9,+ UpdatableTable::LightToTree => 10,+ }+ }++ /// The name the JavaScript input uses for the table.+ pub(crate) fn input_name(self) -> &'static str {+ match self {+ UpdatableTable::Instances => "instances",+ UpdatableTable::Materials => "materials",+ UpdatableTable::EmissiveTriangles => "emissiveTriangles",+ UpdatableTable::Lights => "lights",+ UpdatableTable::LightTreeNodes => "lightTreeNodes",+ UpdatableTable::LightTreeEmitters => "lightTreeEmitters",+ UpdatableTable::LightToTree => "lightToTree",+ }+ }+}++/// What a new instance table asks of the acceleration structure.+#[derive(Debug, PartialEq, Eq)]+pub(crate) struct InstanceUpdatePlan {+ /// A transform or a ray visibility changed, so the TLAS must be rebuilt (the BLAS are kept).+ pub(crate) tlas_dirty: bool,+ /// How many instances differ from the old table in any byte.+ pub(crate) changed_instances: usize,+}++fn read_word(bytes: &[u8], offset: usize) -> u32 {+ u32::from_le_bytes([bytes[offset], bytes[offset + 1], bytes[offset + 2], bytes[offset + 3]])+}++/// Compares a new instance table with the one the session holds. The same instances must stay in the same order with the+/// same meshes; transforms, materials, colours, visibility and light linking may change.+pub(crate) fn plan_instance_update(old_table: &[u8], new_table: &[u8]) -> Result<InstanceUpdatePlan> {+ if old_table.len() != new_table.len() || new_table.len() % INSTANCE_RECORD_BYTES != 0 {+ return Err(failure(format!(+ "The new instance table holds {} bytes but the session holds {}. An update keeps the instance count; create a new session to add or remove instances.",+ new_table.len(),+ old_table.len()+ )));+ }+ let mut tlas_dirty = false;+ let mut changed_instances = 0;+ for (instance_index, (old_record, new_record)) in old_table+ .chunks_exact(INSTANCE_RECORD_BYTES)+ .zip(new_table.chunks_exact(INSTANCE_RECORD_BYTES))+ .enumerate()+ {+ if old_record == new_record {+ continue;+ }+ changed_instances += 1;+ for (field_name, byte_offset) in INSTANCE_TOPOLOGY_FIELDS {+ let old_word = read_word(old_record, byte_offset);+ let new_word = read_word(new_record, byte_offset);+ if old_word != new_word {+ return Err(failure(format!(+ "Instance {instance_index} changes {field_name} from {old_word} to {new_word}. An update may move or restyle an instance but not change which mesh it places; create a new session for this input."+ )));+ }+ }+ let old_mask = instance_cull_mask(read_word(old_record, INSTANCE_VISIBILITY_FLAGS_BYTE));+ let new_mask = instance_cull_mask(read_word(new_record, INSTANCE_VISIBILITY_FLAGS_BYTE));+ if old_record[..INSTANCE_TRANSFORM_BYTES] != new_record[..INSTANCE_TRANSFORM_BYTES] || old_mask != new_mask {+ tlas_dirty = true;+ }+ }+ Ok(InstanceUpdatePlan { tlas_dirty, changed_instances })+}++/// The bytes of a kernel parameter block that a progressive film compares between calls: everything except the image size+/// and the three words the session writes for each render (sample offset, samples per dispatch, total samples).+const FILM_SIGNATURE_ZEROED_BYTES: std::ops::Range<usize> = 8..28;++pub(crate) fn film_signature(frame_kernel_params: &[u8]) -> Vec<u8> {+ let mut signature = frame_kernel_params.to_vec();+ let zeroed = FILM_SIGNATURE_ZEROED_BYTES.start..FILM_SIGNATURE_ZEROED_BYTES.end.min(signature.len());+ signature[zeroed].fill(0);+ signature+}++/// The film a progressive render is adding to: its size, the sample count it was started for and how many it holds.+#[derive(Clone, Debug, PartialEq, Eq)]+pub(crate) struct ProgressiveFilm {+ pub(crate) width: u32,+ pub(crate) height: u32,+ pub(crate) target_samples: u32,+ pub(crate) samples_drawn: u32,+ pub(crate) signature: Vec<u8>,+}++/// What one render call asks of the film.+pub(crate) struct FilmRequest<'a> {+ pub(crate) width: u32,+ pub(crate) height: u32,+ pub(crate) samples: u32,+ pub(crate) accumulate: bool,+ pub(crate) target_samples: Option<u32>,+ pub(crate) frame_kernel_params: &'a [u8],+}++/// Which samples a render call draws and into which film.+#[derive(Debug, PartialEq, Eq)]+pub(crate) struct FilmUse {+ /// The index of the first sample this call draws.+ pub(crate) first_sample: u32,+ /// The value of the kernel's `total_samples` word: the length of each pixel's section of the sample sequence.+ pub(crate) total_samples: u32,+ /// The call starts a new image, so the film is cleared first.+ pub(crate) starts_new_image: bool,+ /// The film this call leaves behind when it succeeds; `None` for a plain frame.+ pub(crate) film_after: Option<ProgressiveFilm>,+}++const REQUIRES_RESET: &str = "Call reset() to start a new image, or render without accumulate.";++/// Decides which samples a call draws. A plain frame draws samples 0..samples of a new image. An accumulating call draws+/// the samples that follow the ones the film holds, in the same sequence a single render of `targetSamples` would use, so+/// the film ends equal to that render. Pure: it changes nothing, so a refused call leaves the film as it was.+pub(crate) fn choose_film_use(film: Option<&ProgressiveFilm>, request: &FilmRequest<'_>) -> Result<FilmUse> {+ if !request.accumulate {+ if request.target_samples.is_some() {+ return Err(failure("targetSamples only applies with accumulate: true. Pass accumulate: true to build one image over several render calls."));+ }+ return Ok(FilmUse { first_sample: 0, total_samples: request.samples, starts_new_image: true, film_after: None });+ }+ let signature = film_signature(request.frame_kernel_params);+ let Some(film) = film else {+ let target_samples = request.target_samples.ok_or_else(|| {+ failure("The first accumulate render of an image needs targetSamples: the total number of samples the image will hold. It fixes the sample sequence, so the calls add up to the same image as one render of that many samples.")+ })?;+ if request.samples > target_samples {+ return Err(failure(format!(+ "samples ({}) is more than targetSamples ({target_samples}). Pass targetSamples as the total for the whole image.",+ request.samples+ )));+ }+ let film_after = ProgressiveFilm {+ width: request.width,+ height: request.height,+ target_samples,+ samples_drawn: request.samples,+ signature,+ };+ return Ok(FilmUse { first_sample: 0, total_samples: target_samples, starts_new_image: true, film_after: Some(film_after) });+ };+ if request.width != film.width || request.height != film.height {+ return Err(failure(format!(+ "The film holds a {}x{} image and this call asks for {}x{}. {REQUIRES_RESET}",+ film.width, film.height, request.width, request.height+ )));+ }+ if let Some(target_samples) = request.target_samples {+ if target_samples != film.target_samples {+ return Err(failure(format!(+ "targetSamples is {target_samples} but the film was started for {}. Leave it out to continue, or call reset() to start an image of another length.",+ film.target_samples+ )));+ }+ }+ if signature != film.signature {+ return Err(failure(format!(+ "The kernel parameters (camera, seed, sampler or other render settings) differ from the ones this film started with, so the new samples would not belong to the same image. {REQUIRES_RESET}"+ )));+ }+ let remaining_samples = film.target_samples - film.samples_drawn;+ if request.samples > remaining_samples {+ return Err(failure(format!(+ "The film holds {} of {} samples; {} more would pass targetSamples. Ask for {remaining_samples} or fewer, or call reset() and start an image with a larger targetSamples.",+ film.samples_drawn, film.target_samples, request.samples+ )));+ }+ let film_after = ProgressiveFilm { samples_drawn: film.samples_drawn + request.samples, ..film.clone() };+ Ok(FilmUse {+ first_sample: film.samples_drawn,+ total_samples: film.target_samples,+ starts_new_image: false,+ film_after: Some(film_after),+ })+}++#[cfg(test)]+mod tests {+ use super::*;++ fn instance_table(count: usize) -> Vec<u8> {+ let mut table = vec![0u8; count * INSTANCE_RECORD_BYTES];+ for (index, record) in table.chunks_exact_mut(INSTANCE_RECORD_BYTES).enumerate() {+ record[96..100].copy_from_slice(&(index as u32).to_le_bytes());+ record[100..104].copy_from_slice(&(index as u32 * 10).to_le_bytes());+ record[104..108].copy_from_slice(&2u32.to_le_bytes());+ record[108..112].copy_from_slice(&2u32.to_le_bytes());+ record[116..120].copy_from_slice(&0x3Fu32.to_le_bytes());+ }+ table+ }++ #[test]+ fn an_identical_instance_table_changes_nothing() {+ let table = instance_table(3);+ assert_eq!(plan_instance_update(&table, &table.clone()).unwrap(), InstanceUpdatePlan { tlas_dirty: false, changed_instances: 0 });+ }++ #[test]+ fn a_moved_instance_dirties_the_tlas_and_counts_only_itself() {+ let old_table = instance_table(3);+ let mut new_table = old_table.clone();+ new_table[INSTANCE_RECORD_BYTES + 12..INSTANCE_RECORD_BYTES + 16].copy_from_slice(&1.5f32.to_le_bytes());+ let plan = plan_instance_update(&old_table, &new_table).unwrap();+ assert_eq!(plan, InstanceUpdatePlan { tlas_dirty: true, changed_instances: 1 });+ }++ #[test]+ fn a_change_the_hardware_does_not_see_leaves_the_tlas_alone() {+ let old_table = instance_table(2);+ let mut restyled = old_table.clone();+ restyled[112..116].copy_from_slice(&5u32.to_le_bytes()); // material_override+ restyled[144..148].copy_from_slice(&0.5f32.to_le_bytes()); // object_color+ restyled[48..52].copy_from_slice(&2.0f32.to_le_bytes()); // world_to_object row 0 (the shader reads it, the TLAS does not)+ restyled[116..120].copy_from_slice(&(0x3Fu32 | 64).to_le_bytes()); // the negative scale bit is not a ray mask bit+ let plan = plan_instance_update(&old_table, &restyled).unwrap();+ assert_eq!(plan, InstanceUpdatePlan { tlas_dirty: false, changed_instances: 1 });+ }++ #[test]+ fn a_changed_ray_visibility_dirties_the_tlas() {+ let old_table = instance_table(1);+ let mut hidden = old_table.clone();+ hidden[116..120].copy_from_slice(&0x3Eu32.to_le_bytes());+ assert!(plan_instance_update(&old_table, &hidden).unwrap().tlas_dirty);+ }++ #[test]+ fn a_changed_mesh_is_refused_and_the_error_names_the_instance_and_the_field() {+ let old_table = instance_table(3);+ for (field_name, byte_offset) in INSTANCE_TOPOLOGY_FIELDS {+ let mut new_table = old_table.clone();+ let record = 2 * INSTANCE_RECORD_BYTES + byte_offset;+ new_table[record..record + 4].copy_from_slice(&99u32.to_le_bytes());+ let message = plan_instance_update(&old_table, &new_table).unwrap_err().to_string();+ assert!(message.contains("Instance 2"), "{field_name}: {message}");+ assert!(message.contains(field_name), "{field_name}: {message}");+ assert!(message.contains("create a new session"), "{field_name}: {message}");+ }+ }++ #[test]+ fn another_instance_count_is_refused() {+ let message = plan_instance_update(&instance_table(2), &instance_table(3)).unwrap_err().to_string();+ assert!(message.contains("instance count"), "{message}");+ assert!(message.contains("create a new session"), "{message}");+ assert!(plan_instance_update(&[0u8; 100], &[0u8; 100]).is_err());+ }++ #[test]+ fn every_updatable_table_has_its_own_buffer_and_input_name() {+ let tables = [+ UpdatableTable::Instances,+ UpdatableTable::Materials,+ UpdatableTable::EmissiveTriangles,+ UpdatableTable::Lights,+ UpdatableTable::LightTreeNodes,+ UpdatableTable::LightTreeEmitters,+ UpdatableTable::LightToTree,+ ];+ let mut indices: Vec<usize> = tables.iter().map(|table| table.buffer_index()).collect();+ indices.sort_unstable();+ indices.dedup();+ assert_eq!(indices.len(), tables.len());+ assert!(indices.iter().all(|index| *index < 11), "the session holds 11 scene buffers");+ let mut names: Vec<&str> = tables.iter().map(|table| table.input_name()).collect();+ names.sort_unstable();+ names.dedup();+ assert_eq!(names.len(), tables.len());+ }++ fn request<'a>(kernel_params: &'a [u8], samples: u32, accumulate: bool, target_samples: Option<u32>) -> FilmRequest<'a> {+ FilmRequest { width: 24, height: 16, samples, accumulate, target_samples, frame_kernel_params: kernel_params }+ }++ #[test]+ fn a_plain_frame_starts_at_sample_zero_with_its_own_length_and_leaves_no_film() {+ let params = vec![7u8; 320];+ let used = choose_film_use(None, &request(¶ms, 32, false, None)).unwrap();+ assert_eq!(used, FilmUse { first_sample: 0, total_samples: 32, starts_new_image: true, film_after: None });+ let message = choose_film_use(None, &request(¶ms, 32, false, Some(64))).unwrap_err().to_string();+ assert!(message.contains("accumulate: true"), "{message}");+ }++ #[test]+ fn split_calls_continue_the_sequence_of_one_render_of_the_target_length() {+ let params = vec![7u8; 320];+ let first = choose_film_use(None, &request(¶ms, 5, true, Some(16))).unwrap();+ assert_eq!((first.first_sample, first.total_samples, first.starts_new_image), (0, 16, true));+ let second = choose_film_use(first.film_after.as_ref(), &request(¶ms, 7, true, None)).unwrap();+ assert_eq!((second.first_sample, second.total_samples, second.starts_new_image), (5, 16, false));+ let third = choose_film_use(second.film_after.as_ref(), &request(¶ms, 4, true, Some(16))).unwrap();+ assert_eq!((third.first_sample, third.total_samples), (12, 16));+ assert_eq!(third.film_after.as_ref().unwrap().samples_drawn, 16);+ }++ #[test]+ fn the_first_accumulating_call_needs_a_target_that_covers_it() {+ let params = vec![7u8; 320];+ let missing = choose_film_use(None, &request(¶ms, 4, true, None)).unwrap_err().to_string();+ assert!(missing.contains("targetSamples"), "{missing}");+ let too_small = choose_film_use(None, &request(¶ms, 8, true, Some(4))).unwrap_err().to_string();+ assert!(too_small.contains("more than targetSamples"), "{too_small}");+ }++ #[test]+ fn a_call_that_does_not_belong_to_the_film_is_refused_with_the_way_out() {+ let params = vec![7u8; 320];+ let started = choose_film_use(None, &request(¶ms, 4, true, Some(8))).unwrap().film_after.unwrap();++ let past_the_end = choose_film_use(Some(&started), &request(¶ms, 5, true, None)).unwrap_err().to_string();+ assert!(past_the_end.contains("Ask for 4 or fewer"), "{past_the_end}");++ let other_target = choose_film_use(Some(&started), &request(¶ms, 2, true, Some(12))).unwrap_err().to_string();+ assert!(other_target.contains("reset()"), "{other_target}");++ let mut other_size = request(¶ms, 2, true, None);+ other_size.width = 25;+ let size_message = choose_film_use(Some(&started), &other_size).unwrap_err().to_string();+ assert!(size_message.contains("24x16") && size_message.contains("25x16"), "{size_message}");++ let mut moved_camera = params.clone();+ moved_camera[200] ^= 1;+ let camera_message = choose_film_use(Some(&started), &request(&moved_camera, 2, true, None)).unwrap_err().to_string();+ assert!(camera_message.contains("kernel parameters"), "{camera_message}");+ }++ #[test]+ fn the_film_signature_ignores_the_words_the_session_writes_for_each_render() {+ let params = vec![7u8; 320];+ let mut rewritten = params.clone();+ rewritten[8..28].copy_from_slice(&[9u8; 20]);+ assert_eq!(film_signature(¶ms), film_signature(&rewritten));+ let mut other_seed = params.clone();+ other_seed[28] ^= 1;+ assert_ne!(film_signature(¶ms), film_signature(&other_seed));+ }++ #[test]+ fn a_refused_call_leaves_the_film_as_it_was() {+ let params = vec![7u8; 320];+ let started = choose_film_use(None, &request(¶ms, 4, true, Some(8))).unwrap().film_after.unwrap();+ let before = started.clone();+ assert!(choose_film_use(Some(&started), &request(¶ms, 9, true, None)).is_err());+ assert_eq!(started, before);+ }+}diff --git a/packages/render-native/src/host/mod.rs b/packages/render-native/src/host/mod.rsindex 4972a58f..9856fc39 100644--- a/packages/render-native/src/host/mod.rs+++ b/packages/render-native/src/host/mod.rs@@ -6,3 +6,4 @@ pub(crate) mod film;pub(crate) mod cycles_session;pub(crate) mod session;pub(crate) mod textures;+pub(crate) mod cycles_update;diff --git a/packages/render-native/src/host/session.rs b/packages/render-native/src/host/session.rsindex 882e5721..d8414ed7 100644--- a/packages/render-native/src/host/session.rs+++ b/packages/render-native/src/host/session.rs@@ -621,7 +621,7 @@ pub(crate) fn validate_kernel_params_v2(parameter_bytes: &[u8]) -> Result<()> {Ok(())}-fn validate_record_buffer(label: &str, bytes: &[u8], count: u32, stride: usize) -> Result<()> {+pub(crate) fn validate_record_buffer(label: &str, bytes: &[u8], count: u32, stride: usize) -> Result<()> {let minimum_bytes = (count.max(1) as usize) * stride;if bytes.len() < minimum_bytes || bytes.len() % stride != 0 {return Err(failure(format!(@@ -773,8 +773,11 @@ fn fail_if_device_lost()))}+/// Draws `samples` samples numbered `first_sample` onwards, adding them to what the film already holds. A one-shot render+/// and the first call of a progressive film start at sample 0.pub(crate) fn trace_cycles_samples(target: &CyclesDispatchTarget<'_>,+ first_sample: u32,samples: u32,plan: DispatchPlan,groups: (u32, u32),@@ -788,13 +791,14 @@ pub(crate) fn trace_cycles_samples(DispatchPlan::TimeBudget { largest_batch } => Some(DispatchPlanner::new(DISPATCH_BUDGET_SECONDS, largest_batch)),DispatchPlan::Fixed(_) => None,};- let mut sample_offset = 0u32;+ let end_sample = first_sample + samples;+ let mut sample_offset = first_sample;let mut dispatch_count = 0u32;let mut largest_batch = 0u32;let mut longest_dispatch_seconds: Option<f64> = None;- while sample_offset < samples {- let remaining_samples = samples - sample_offset;+ while sample_offset < end_sample {+ let remaining_samples = end_sample - sample_offset;let batch_samples = match (&planner, plan) {(Some(planner), _) => planner.next_batch(remaining_samples),(None, DispatchPlan::Fixed(step)) => remaining_samples.min(step.max(1)),@@ -830,13 +834,13 @@ pub(crate) fn trace_cycles_samples(let should_poll = if planner.is_some() {true} else if max_seconds.is_some() {- dispatch_count % SAMPLES_PER_WAIT == 0 || sample_offset >= samples+ dispatch_count % SAMPLES_PER_WAIT == 0 || sample_offset >= end_sample} else {- sample_offset < samples && dispatch_count % SAMPLES_PER_WAIT == 0+ sample_offset < end_sample && dispatch_count % SAMPLES_PER_WAIT == 0};if should_poll {let _ = device.poll(wgpu::PollType::wait_indefinitely());- fail_if_device_lost(target, dispatch_offset, batch_samples, samples)?;+ fail_if_device_lost(target, dispatch_offset, batch_samples, end_sample)?;if let Some(planner) = planner.as_mut() {let dispatch_seconds = dispatch_started.elapsed().as_secs_f64();planner.record(batch_samples, dispatch_seconds);@@ -845,7 +849,7 @@ pub(crate) fn trace_cycles_samples(if let Some(limit) = max_seconds {if trace_started.elapsed().as_secs_f64() > limit {return Err(failure(format!(- "The native trace passed its time limit of {limit} s after {sample_offset} of {samples} samples."+ "The native trace passed its time limit of {limit} s after {sample_offset} of {end_sample} samples.")));}}@@ -853,7 +857,7 @@ pub(crate) fn trace_cycles_samples(}let sums = read_accumulation(device, queue, target.accumulation, accumulation_bytes);- fail_if_device_lost(target, samples.saturating_sub(largest_batch), largest_batch, samples)?;+ fail_if_device_lost(target, end_sample.saturating_sub(largest_batch), largest_batch, end_sample)?;Ok(CyclesTrace {sums: sums?,traced_seconds: trace_started.elapsed().as_secs_f64(),diff --git a/packages/render-native/src/lib.rs b/packages/render-native/src/lib.rsindex 5b74f1c3..76fb1b90 100644--- a/packages/render-native/src/lib.rs+++ b/packages/render-native/src/lib.rs@@ -14,8 +14,13 @@ use crate::host::film::{image_accumulation_bytes, image_workgroups, pad_texel_vectors, resolve_image, resolve_texels,texel_accumulation_bytes, texel_workgroups,};-use crate::host::cycles_session::{CyclesRenderRequest, CyclesSession};-use crate::host::session::{get_cached_device, prepare_scene, run_cycles_lobe_probe, trace_samples, JobShape};+use crate::host::cycles_session::{+ CyclesRender, CyclesRenderReport, CyclesRenderRequest, CyclesSceneUpdate, CyclesSession,+};+use crate::host::cycles_update::UpdatableTable;+use crate::host::session::{+ get_cached_device, prepare_scene, run_cycles_lobe_probe, trace_samples, CyclesTrace, JobShape,+};const KERNEL_SOURCE: &str = include_str!("kernel.wgsl");/// The texel entry point of the light bake, appended to the kernel for a bake only.@@ -88,6 +93,10 @@ pub struct NativeCyclesTraceOptions {/// A KernelParamsV2 block for this render (a session frame with another camera or render settings of the same scene);/// absent means the block of the input.pub kernel_params: Option<Uint8Array>,+ /// Session only: add this call's samples to the film instead of starting a new image.+ pub accumulate: Option<bool>,+ /// Session only: the sample count of the whole image a progressive film builds; the first accumulating call sets it.+ pub target_samples: Option<u32>,}#[napi(object)]@@ -273,6 +282,12 @@ pub struct NativeSessionReport {pub film_reused: bool,/// How many frames the session finished before this one.pub frame_index: u32,+ /// The index of the first sample this call drew: 0, or where the progressive film left off.+ pub first_sample: u32,+ /// How many samples per pixel the film holds after this call.+ pub film_samples: u32,+ /// The sample count the progressive film was started for; absent for a plain frame.+ pub target_samples: Option<u32>,}#[napi(object)]@@ -281,6 +296,40 @@ pub struct NativeSessionRenderResult {pub session: NativeSessionReport,}+#[napi(object)]+pub struct NativeSessionResolveOptions {+ /// `"none"` (default) or `"atrous"`, as for a render.+ pub denoise: Option<String>,+}++/// The tables of a session update that changed, and the kernel parameters of the new input.+#[napi(object)]+pub struct NativeSessionUpdateOptions {+ pub kernel_params: Uint8Array,+ pub instances: Option<Uint8Array>,+ pub materials: Option<Uint8Array>,+ pub emissive_triangles: Option<Uint8Array>,+ pub lights: Option<Uint8Array>,+ pub light_tree_nodes: Option<Uint8Array>,+ pub light_tree_emitters: Option<Uint8Array>,+ pub light_to_tree: Option<Uint32Array>,+}++#[napi(object)]+pub struct NativeSessionUpdateReport {+ /// The tables whose buffers were replaced, by their input names.+ pub uploaded_tables: Vec<String>,+ /// The TLAS was rebuilt over the kept BLAS because a transform or a ray visibility changed. The pinned wgpu has no refit.+ pub acceleration_rebuilt: bool,+ /// How many instance records differ from the old table.+ pub changed_instances: u32,+ /// The new tables change what the kernel text is specialized for, so the next render compiles a new pipeline.+ pub kernel_respecialized: bool,+ pub upload_seconds: f64,+ pub acceleration_rebuild_seconds: f64,+ pub update_seconds: f64,+}+/// Renders one frame on a session and resolves the film into the result object.fn render_session_frame(session: &mut CyclesSession,@@ -295,9 +344,22 @@ fn render_session_frame(max_seconds: options.max_seconds,bootstrap_kernel: options.bootstrap_kernel.unwrap_or(false),kernel_params: options.kernel_params.as_deref(),+ accumulate: options.accumulate.unwrap_or(false),+ target_samples: options.target_samples,};let render = session.render(&request)?;- let pixel_count = options.width as u64 * options.height as u64;+ session_render_result(session, options.width, options.height, use_atrous_filter, render)+}++/// Resolves the sums of a session render (or of the film as it stands) into the result object.+fn session_render_result(+ session: &CyclesSession,+ width: u32,+ height: u32,+ use_atrous_filter: bool,+ render: CyclesRender,+) -> Result<NativeSessionRenderResult> {+ let pixel_count = width as u64 * height as u64;let resolved = resolve_image(&render.trace.sums, pixel_count);let context = session.device_context();let filtered = if use_atrous_filter {@@ -305,8 +367,8 @@ fn render_session_frame(&context.device,&context.queue,&DenoiseInput {- width: options.width,- height: options.height,+ width,+ height,rgba: &resolved.rgba,albedo: &resolved.albedo,normal: &resolved.normal,@@ -331,7 +393,7 @@ fn render_session_frame(depth: Float32Array::new(resolved.depth),variance: Float32Array::new(resolved.variance),average_samples: resolved.average_samples,- samples_per_dispatch: Some(render.trace.largest_batch),+ samples_per_dispatch: (render.trace.largest_batch > 0).then_some(render.trace.largest_batch),longest_dispatch_seconds: render.trace.longest_dispatch_seconds,adapter: context.adapter_name.clone(),backend: context.backend_name.clone(),@@ -347,10 +409,58 @@ fn render_session_frame(acceleration_reused: render.report.acceleration_reused,film_reused: render.report.film_reused,frame_index: render.report.frame_index,+ first_sample: render.report.first_sample,+ film_samples: render.report.film_samples,+ target_samples: render.report.target_samples,};Ok(NativeSessionRenderResult { trace, session: session_report })}+/// The film of a session as it stands, resolved without tracing: the report says nothing was compiled, built or drawn.+fn resolve_session_film(session: &mut CyclesSession, options: &NativeSessionResolveOptions) -> Result<NativeSessionRenderResult> {+ let use_atrous_filter = parse_denoise_option(options.denoise.as_deref())?;+ let film = session.read_film()?;+ let film_samples = film.film_samples;+ let render = CyclesRender {+ trace: CyclesTrace { sums: film.sums, traced_seconds: 0.0, largest_batch: 0, longest_dispatch_seconds: None },+ report: CyclesRenderReport {+ setup_seconds: 0.0,+ compile_seconds: 0.0,+ upload_seconds: 0.0,+ acceleration_build_seconds: 0.0,+ pipeline_reused: true,+ acceleration_reused: true,+ film_reused: true,+ frame_index: film.frame_index,+ first_sample: film_samples,+ film_samples,+ target_samples: film.target_samples,+ },+ };+ session_render_result(session, film.width, film.height, use_atrous_filter, render)+}++fn update_tables<'a>(options: &'a NativeSessionUpdateOptions) -> Vec<(UpdatableTable, &'a [u8])> {+ let mut tables: Vec<(UpdatableTable, &'a [u8])> = Vec::new();+ let byte_tables = [+ (UpdatableTable::Instances, &options.instances),+ (UpdatableTable::Materials, &options.materials),+ (UpdatableTable::EmissiveTriangles, &options.emissive_triangles),+ (UpdatableTable::Lights, &options.lights),+ (UpdatableTable::LightTreeNodes, &options.light_tree_nodes),+ (UpdatableTable::LightTreeEmitters, &options.light_tree_emitters),+ ];+ for (table, bytes) in byte_tables {+ if let Some(bytes) = bytes {+ tables.push((table, &bytes[..]));+ }+ }+ if let Some(words) = &options.light_to_tree {+ tables.push((UpdatableTable::LightToTree, bytemuck::cast_slice::<u32, u8>(words)));+ }+ tables+}+/// Traces a packed `FORMAT-v2` scene on the GPU using the assembled Cycles-parity WGSL kernel: a session that renders once.#[napi]pub fn trace_scene_cycles(input: NativeTraceInputV2, options: NativeCyclesTraceOptions) -> Result<NativeTraceResult> {@@ -380,6 +490,35 @@ impl NativeCyclesSession {render_session_frame(&mut self.session, &options)}+ /// Starts the progressive image over: clears the film, keeps the scene and the pipeline.+ #[napi]+ pub fn reset(&mut self) -> Result<()> {+ self.session.reset()+ }++ /// The film as it stands (the average of every sample drawn so far), without tracing.+ #[napi]+ pub fn resolve(&mut self, options: NativeSessionResolveOptions) -> Result<NativeSessionRenderResult> {+ resolve_session_film(&mut self.session, &options)+ }++ /// Replaces the values of scene tables (materials, lights, emission, instance transforms) without rebuilding the+ /// pipeline or the BLAS. Clears the film.+ #[napi]+ pub fn update(&mut self, options: NativeSessionUpdateOptions) -> Result<NativeSessionUpdateReport> {+ let update = CyclesSceneUpdate { kernel_params: &options.kernel_params, tables: update_tables(&options) };+ let report = self.session.update(&update)?;+ Ok(NativeSessionUpdateReport {+ uploaded_tables: report.uploaded_tables.iter().map(|name| name.to_string()).collect(),+ acceleration_rebuilt: report.acceleration_rebuilt,+ changed_instances: report.changed_instances,+ kernel_respecialized: report.kernel_respecialized,+ upload_seconds: report.upload_seconds,+ acceleration_rebuild_seconds: report.acceleration_rebuild_seconds,+ update_seconds: report.update_seconds,+ })+ }+/// Frees the card; every later `render` fails.#[napi]pub fn close(&mut self) {diff --git a/tests/native-session.test.js b/tests/native-session.test.jsindex e123a2e7..55f01afd 100644--- a/tests/native-session.test.js+++ b/tests/native-session.test.js@@ -4,6 +4,7 @@ import {buildNativeInputV2,createNativeSession,findNativeAddon,+ planNativeSessionUpdate,resolveSessionCreation,resolveSessionFrame,traceNative,@@ -220,6 +221,164 @@ test('a closed session refuses to render and closing twice frees the card once',assert.deepEqual(calls, ['close']);});+// ---- Progressive film and scene updates: argument checks and the wrapper, without the addon ----++function roomInputWith(changeScene, eye = [0, 2.2, 6], options = IMAGE_OPTIONS) {+ const scene = buildRoomScene();+ changeScene(scene);+ const camera = createCamera({ eye, target: [0, 0.5, 0], fov: 45 }, options.width, options.height);+ return buildNativeInputV2(scene, camera, options);+}++const DEFAULT_FRAME = { width: 24, height: 16, samples: 8 };++test('a frame passes accumulate and targetSamples on and checks them', () => {+ const sessionInput = resolveSessionCreation(roomInput([0, 2.2, 6]), {});+ const frame = resolveSessionFrame(sessionInput, DEFAULT_FRAME, { accumulate: true, targetSamples: 32 });+ assert.equal(frame.accumulate, true);+ assert.equal(frame.targetSamples, 32);+ const plain = resolveSessionFrame(sessionInput, DEFAULT_FRAME, {});+ assert.equal(plain.accumulate, undefined);+ assert.equal(plain.targetSamples, undefined);+ const fromDefaults = resolveSessionFrame(sessionInput, { ...DEFAULT_FRAME, accumulate: true, targetSamples: 64 }, {});+ assert.equal(fromDefaults.targetSamples, 64);++ assert.throws(() => resolveSessionFrame(sessionInput, DEFAULT_FRAME, { accumulate: 'yes' }), { name: 'TypeError', message: /accumulate/ });+ assert.throws(() => resolveSessionFrame(sessionInput, DEFAULT_FRAME, { targetSamples: 32 }), { name: 'TypeError', message: /accumulate: true/ });+ assert.throws(() => resolveSessionFrame(sessionInput, DEFAULT_FRAME, { accumulate: true, targetSamples: 1.5 }), { name: 'RangeError', message: /targetSamples/ });+ assert.throws(() => resolveSessionFrame(sessionInput, DEFAULT_FRAME, { accumulate: true, targetSamples: 0 }), { name: 'RangeError', message: /targetSamples/ });+ assert.throws(() => resolveSessionFrame(sessionInput, DEFAULT_FRAME, { accumulate: true, targetSamples: 4 }), { name: 'RangeError', message: /more than .targetSamples/ });+});++test('planNativeSessionUpdate sends nothing for the same input and only the tables whose bytes changed', () => {+ const current = roomInput([0, 2.2, 6]);+ assert.deepEqual(planNativeSessionUpdate(current, roomInput([1.5, 2.2, 5])), {}, 'a camera is not a table');++ const recoloured = roomInputWith((scene) => {+ scene.materials[0].color = [0.2, 0.5, 0.8];+ });+ const colourPlan = planNativeSessionUpdate(current, recoloured);+ assert.deepEqual(Object.keys(colourPlan), ['materials']);+ assert.equal(colourPlan.materials, recoloured.materials);++ const moved = roomInputWith((scene) => {+ scene.instances[0].matrix = horizontalQuadMatrix(8, -0.25, true);+ });+ const movePlan = planNativeSessionUpdate(current, moved);+ assert.ok(Object.keys(movePlan).includes('instances'));+ assert.ok(!Object.keys(movePlan).includes('materials'));+});++test('planNativeSessionUpdate refuses a change of record counts and names it', () => {+ const current = roomInput([0, 2.2, 6]);+ const withExtraQuad = roomInputWith((scene) => {+ scene.instances.push({ geometry: UNIT_QUAD, matrix: horizontalQuadMatrix(1, 1, true), materialIndex: 0 });+ });+ assert.throws(() => planNativeSessionUpdate(current, withExtraQuad), { message: /`instanceCount` changes from 3 to 4.*createNativeSession/ });+ const withExtraMaterial = roomInputWith((scene) => {+ scene.materials.push({ color: [1, 0, 0] });+ });+ assert.throws(() => planNativeSessionUpdate(current, withExtraMaterial), { message: /`materialCount` changes from 2 to 3/ });+});++test('planNativeSessionUpdate refuses other geometry, other textures and an instance that places another mesh', () => {+ const current = roomInput([0, 2.2, 6]);+ const bent = { ...current, triangles: new Uint8Array(current.triangles) };+ new DataView(bent.triangles.buffer).setFloat32(8, 0.5, true);+ assert.throws(() => planNativeSessionUpdate(current, bent), { message: /`triangles` differs.*the geometry/ });+ const otherMesh = roomInputWith((scene) => {+ scene.instances[0].geometry = { ...UNIT_QUAD, positions: new Float32Array([-1, -1, 0, 1, -1, 0, 1, 1, 0.5, -1, 1, 0]) };+ });+ assert.throws(() => planNativeSessionUpdate(current, otherMesh), { message: /`triangleCount` changes from 2 to 4/ });++ const otherTexels = { ...current, textureTexels: new Uint32Array([1, 2, 3, 4]) };+ assert.throws(() => planNativeSessionUpdate({ ...current, textureTexels: new Uint32Array(4) }, otherTexels), { message: /`textureTexels` differs.*the textures/ });++ const swappedMesh = { ...current, instances: new Uint8Array(current.instances) };+ new DataView(swappedMesh.instances.buffer).setUint32(160 + 100, 77, true);+ assert.throws(() => planNativeSessionUpdate(current, swappedMesh), { message: /instance 1 changes `triangleOffset` from \d+ to 77.*not change the mesh/ });+});++test('a wrapped session resets, resolves and updates through the addon and keeps the new defaults', () => {+ const first = roomInput([0, 2.2, 6]);+ const second = roomInputWith((scene) => {+ scene.materials[0].color = [0.2, 0.5, 0.8];+ }, [1.5, 2.2, 5]);+ const calls = [];+ const nativeSession = {+ render(frame) {+ calls.push(['render', frame]);+ return { trace: { rgba: new Float32Array(4) }, session: { filmSamples: frame.samples } };+ },+ reset() {+ calls.push(['reset']);+ },+ resolve(options) {+ calls.push(['resolve', options]);+ return { trace: { rgba: new Float32Array(4), tracedSeconds: 0 }, session: { filmSamples: 8 } };+ },+ update(options) {+ calls.push(['update', options]);+ return { uploadedTables: Object.keys(options).filter((name) => name !== 'kernelParams'), accelerationRebuilt: false };+ },+ close() {+ calls.push(['close']);+ },+ };+ const sessionInput = resolveSessionCreation(first, {});+ const session = wrapNativeSession(nativeSession, sessionInput, { width: 24, height: 16, samples: 4 });++ session.reset();+ assert.equal(session.resolve().filmSamples, 8);+ assert.deepEqual(calls[1], ['resolve', { denoise: undefined }]);+ session.resolve({ denoise: 'atrous' });+ assert.deepEqual(calls[2], ['resolve', { denoise: 'atrous' }]);+ assert.throws(() => session.resolve({ denoise: 'bilateral' }), { message: /denoise/ });+ assert.throws(() => session.resolve(null), { name: 'TypeError', message: /resolveOptions/ });++ const report = session.update(second);+ assert.deepEqual(report.uploadedTables, ['materials']);+ const updateCall = calls.find(([name]) => name === 'update')[1];+ assert.deepEqual(Object.keys(updateCall).sort(), ['kernelParams', 'materials']);+ assert.deepEqual(updateCall.kernelParams, resolveSessionCreation(second, {}).kernelParams);++ session.render({});+ const frameAfterUpdate = calls.filter(([name]) => name === 'render').pop()[1];+ assert.deepEqual(frameAfterUpdate.kernelParams, updateCall.kernelParams, 'a frame after the update starts from the new kernel parameters');+});++test('a refused update changes nothing and a closed session refuses reset, resolve and update', () => {+ const current = roomInput([0, 2.2, 6]);+ const calls = [];+ const nativeSession = {+ update() {+ calls.push('update');+ return {};+ },+ reset() {+ calls.push('reset');+ },+ resolve() {+ calls.push('resolve');+ return { trace: {}, session: {} };+ },+ close() {},+ };+ const session = wrapNativeSession(nativeSession, resolveSessionCreation(current, {}), {});+ const withExtraQuad = roomInputWith((scene) => {+ scene.instances.push({ geometry: UNIT_QUAD, matrix: horizontalQuadMatrix(1, 1, true), materialIndex: 0 });+ });+ assert.throws(() => session.update(withExtraQuad), { message: /instanceCount/ });+ assert.throws(() => session.update(undefined), { name: 'TypeError', message: /FORMAT-v2/ });+ assert.deepEqual(calls, [], 'the addon is not called for a refused update');+ session.close();+ for (const method of ['reset', 'resolve']) {+ assert.throws(() => session[method](), { message: new RegExp(`NativeSession.${method}: this session is closed`) });+ }+ assert.throws(() => session.update(current), { message: /NativeSession.update: this session is closed/ });+ assert.deepEqual(calls, []);+});+// ---- Renders on the GPU ----test('a session render equals the one-shot render byte for byte and the second frame reuses the setup', { skip: skipWithoutAddon }, () => {@@ -364,3 +523,282 @@ test('a first frame that fails leaves the creation costs for the retry', { skip:session.close();}});++// ---- Progressive film on the GPU ----++const FILM_SAMPLES = 32;+const FILM_SPLITS = [[16, 16], [8, 8, 16], [5, 11, 7, 9], [1, 31]];++function renderInParts(session, options, parts, targetSamples = FILM_SAMPLES) {+ let drawn = 0;+ let last;+ for (const samples of parts) {+ last = session.render({ ...options, samples, accumulate: true, ...(drawn === 0 ? { targetSamples } : {}) });+ assert.equal(last.firstSample, drawn, 'the call continues where the film left off');+ drawn += samples;+ assert.equal(last.filmSamples, drawn);+ assert.equal(last.targetSamples, targetSamples);+ }+ return last;+}++test('one image over several calls equals one render of the same samples, for both samplers, with and without path regeneration', { skip: skipWithoutAddon }, () => {+ const input = roomInput([0, 2.2, 6]);+ const session = createNativeSession(input);+ try {+ for (const sampler of ['sobol-burley', 'white']) {+ for (const pathRegeneration of [true, false]) {+ for (const samplesPerDispatch of [undefined, 3]) {+ const options = { ...IMAGE_OPTIONS, samples: FILM_SAMPLES, kernel: 'cycles', sampler, pathRegeneration, samplesPerDispatch };+ const oneShot = traceNative(input, options);+ for (const parts of FILM_SPLITS) {+ session.reset();+ const label = `${sampler}, regeneration ${pathRegeneration}, samplesPerDispatch ${samplesPerDispatch}, split ${parts.join('+')}`;+ const split = renderInParts(session, options, parts);+ assertSameBytes(oneShot, split, label);+ assertSameBytes(oneShot, session.resolve(), `${label}, resolved without tracing`);+ }+ }+ }+ }+ } finally {+ session.close();+ }+});++test('resolve gives the a-trous image of the film and traces nothing', { skip: skipWithoutAddon }, () => {+ const input = roomInput([0, 2.2, 6]);+ const options = { ...IMAGE_OPTIONS, samples: FILM_SAMPLES, kernel: 'cycles', denoise: 'atrous' };+ const oneShot = traceNative(input, options);+ const session = createNativeSession(input);+ try {+ renderInParts(session, options, [10, 22]);+ const resolved = session.resolve({ denoise: 'atrous' });+ assertSameBytes(oneShot, resolved, 'the film');+ assert.ok(bytesOf(oneShot, 'denoisedRgba').equals(bytesOf(resolved, 'denoisedRgba')), 'the denoised image');+ assert.equal(resolved.tracedSeconds, 0);+ assert.equal(resolved.compileSeconds, 0);+ assert.equal(resolved.accelerationBuildSeconds, 0);+ assert.equal(resolved.pipelineReused, true);+ assert.equal(resolved.filmSamples, FILM_SAMPLES);+ assert.equal(resolved.denoisedRgba.length, 24 * 16 * 4);+ assert.ok([null, undefined].includes(session.resolve().denoisedRgba), 'no denoise unless asked');+ } finally {+ session.close();+ }+});++test('a call that does not belong to the film is refused and leaves the film as it was', { skip: skipWithoutAddon }, () => {+ const input = roomInput([0, 2.2, 6]);+ const movedCamera = roomInput([1.5, 2.2, 5]);+ const options = { ...IMAGE_OPTIONS, samples: 16, kernel: 'cycles' };+ const session = createNativeSession(input);+ try {+ assert.throws(() => session.render({ ...options, accumulate: true }), { message: /needs targetSamples/ });+ session.render({ ...options, accumulate: true, targetSamples: FILM_SAMPLES });+ assert.throws(() => session.render({ ...options, accumulate: true, kernelParams: movedCamera.kernelParams }), { message: /kernel parameters.*reset\(\)/ });+ assert.throws(() => session.render({ ...options, samples: 20, accumulate: true }), { message: /Ask for 16 or fewer/ });+ assert.throws(() => session.render({ ...options, width: 32, height: 20, accumulate: true }), { message: /24x16.*32x20/ });+ assert.throws(() => session.render({ ...options, accumulate: true, targetSamples: 64 }), { message: /started for 32/ });+ const finished = session.render({ ...options, accumulate: true });+ assert.equal(finished.firstSample, 16);+ assertSameBytes(traceNative(input, { ...options, samples: FILM_SAMPLES }), finished, 'after the refused calls');+ assert.throws(() => session.render({ ...options, samples: 1, accumulate: true }), { message: /more would pass targetSamples/ });+ } finally {+ session.close();+ }+});++test('reset starts over, a plain frame discards the image and resolve needs samples', { skip: skipWithoutAddon }, () => {+ const input = roomInput([0, 2.2, 6]);+ const options = { ...IMAGE_OPTIONS, samples: FILM_SAMPLES, kernel: 'cycles' };+ const oneShot = traceNative(input, options);+ const session = createNativeSession(input);+ try {+ assert.throws(() => session.resolve(), { message: /holds no samples/ });+ renderInParts(session, options, [10]);+ session.reset();+ assert.throws(() => session.resolve(), { message: /holds no samples/ });+ assertSameBytes(oneShot, renderInParts(session, options, [12, 20]), 'after a reset');++ const plain = session.render(options);+ assertSameBytes(oneShot, plain, 'a plain frame');+ assert.equal(plain.firstSample, 0);+ assert.equal(plain.filmSamples, FILM_SAMPLES);+ assert.ok(plain.targetSamples === null || plain.targetSamples === undefined, 'a plain frame has no target');+ assert.throws(() => session.render({ ...options, samples: 4, accumulate: true }), { message: /needs targetSamples/ });+ assertSameBytes(oneShot, session.resolve(), 'the plain frame as the film');+ } finally {+ session.close();+ }+});++// ---- Scene updates on the GPU ----++function recolourFloor(scene) {+ scene.materials[0].color = [0.2, 0.5, 0.8];+}++function moveFloorAndLamp(scene) {+ scene.instances[0].matrix = horizontalQuadMatrix(8, -0.25, true);+ scene.instances[2].matrix = horizontalQuadMatrix(1, 2.4, false);+}++test('an update of material values equals a fresh render of the final input and keeps the pipeline and the BLAS', { skip: skipWithoutAddon }, () => {+ const options = { ...IMAGE_OPTIONS, kernel: 'cycles' };+ const before = roomInput([0, 2.2, 6]);+ const after = roomInputWith(recolourFloor);+ const session = createNativeSession(before);+ try {+ const cold = session.render(options);+ const report = session.update(after);+ assert.deepEqual(report.uploadedTables, ['materials']);+ assert.equal(report.accelerationRebuilt, false);+ assert.equal(report.changedInstances, 0);+ assert.equal(report.kernelRespecialized, false);+ const warm = session.render(options);+ assertSameBytes(traceNative(after, options), warm, 'the update then render against a fresh one-shot render');+ assert.ok(!bytesOf(cold, 'rgba').equals(bytesOf(warm, 'rgba')), 'the new colour must show');+ assert.equal(warm.accelerationReused, true);+ assert.equal(warm.pipelineReused, true);+ assert.equal(warm.accelerationBuildSeconds, 0);+ } finally {+ session.close();+ }+});++test('moving instances rebuilds only the TLAS and the next render equals a fresh render of the moved scene', { skip: skipWithoutAddon }, () => {+ const options = { ...IMAGE_OPTIONS, kernel: 'cycles' };+ const before = roomInput([0, 2.2, 6]);+ const after = roomInputWith(moveFloorAndLamp);+ const session = createNativeSession(before);+ try {+ const cold = session.render(options);+ const report = session.update(after);+ assert.ok(report.uploadedTables.includes('instances'));+ assert.equal(report.accelerationRebuilt, true);+ assert.equal(report.changedInstances, 2);+ const moved = session.render(options);+ assertSameBytes(traceNative(after, options), moved, 'the moved scene');+ assert.ok(!bytesOf(cold, 'rgba').equals(bytesOf(moved, 'rgba')));+ assert.equal(moved.accelerationReused, true);+ assert.equal(moved.accelerationBuildSeconds, 0);+ assert.equal(moved.pipelineReused, true);++ const back = session.update(before);+ assert.equal(back.accelerationRebuilt, true);+ assertSameBytes(cold, session.render(options), 'moved back to the first placement');+ } finally {+ session.close();+ }+});++test('an update that changes what the kernel is specialized for compiles again and still equals a fresh render', { skip: skipWithoutAddon }, () => {+ const options = { ...IMAGE_OPTIONS, kernel: 'cycles' };+ const before = roomInput([0, 2.2, 6]);+ const glass = roomInputWith((scene) => {+ scene.materials[0].transmission = 0.8;+ });+ const session = createNativeSession(before);+ try {+ session.render(options);+ const report = session.update(glass);+ assert.equal(report.kernelRespecialized, true);+ const rendered = session.render(options);+ assert.equal(rendered.pipelineReused, false);+ assert.equal(rendered.accelerationReused, true);+ assertSameBytes(traceNative(glass, options), rendered, 'the transmissive floor');+ } finally {+ session.close();+ }+});++test('an update with a new camera only sends no table, and the same input again changes nothing', { skip: skipWithoutAddon }, () => {+ const options = { ...IMAGE_OPTIONS, kernel: 'cycles' };+ const first = roomInput([0, 2.2, 6]);+ const moved = roomInput([1.5, 2.2, 5]);+ const session = createNativeSession(first);+ try {+ session.render(options);+ const same = session.update(first);+ assert.deepEqual(same.uploadedTables, []);+ assert.equal(same.accelerationRebuilt, false);+ const cameraOnly = session.update(moved);+ assert.deepEqual(cameraOnly.uploadedTables, []);+ assertSameBytes(traceNative(moved, options), session.render(options), 'the new default camera');+ } finally {+ session.close();+ }+});++test('an update ends the progressive image and the next one equals a fresh render of the final input', { skip: skipWithoutAddon }, () => {+ const options = { ...IMAGE_OPTIONS, samples: FILM_SAMPLES, kernel: 'cycles' };+ const before = roomInput([0, 2.2, 6]);+ const after = roomInputWith(moveFloorAndLamp);+ const session = createNativeSession(before);+ try {+ renderInParts(session, options, [10]);+ session.update(after);+ assert.throws(() => session.resolve(), { message: /holds no samples/ });+ assert.throws(() => session.render({ ...options, samples: 4, accumulate: true }), { message: /needs targetSamples/ });+ assertSameBytes(traceNative(after, options), renderInParts(session, options, [7, 25]), 'the image after the update');+ } finally {+ session.close();+ }+});++test('an update that cannot be applied is refused before anything changes', { skip: skipWithoutAddon }, () => {+ const options = { ...IMAGE_OPTIONS, kernel: 'cycles' };+ const before = roomInput([0, 2.2, 6]);+ const session = createNativeSession(before);+ try {+ const oneShot = traceNative(before, options);+ assertSameBytes(oneShot, session.render(options), 'before the refused updates');+ const withExtraQuad = roomInputWith((scene) => {+ scene.instances.push({ geometry: UNIT_QUAD, matrix: horizontalQuadMatrix(1, 1, true), materialIndex: 0 });+ });+ assert.throws(() => session.update(withExtraQuad), { message: /instanceCount.*createNativeSession/ });+ const otherEnvironment = new Uint8Array(before.kernelParams);+ new DataView(otherEnvironment.buffer).setUint32(ENV_WIDTH_BYTE_OFFSET, 64, true);+ assert.throws(() => session.update({ ...before, kernelParams: otherEnvironment }), { message: /envWidth.*create a new session/ });+ assertSameBytes(oneShot, session.render(options), 'after the refused updates');+ } finally {+ session.close();+ }+ assert.throws(() => session.update(before), { message: /closed/ });+});++test('an updated session renders like a new session and the timings of both are printed', { skip: skipWithoutAddon }, () => {+ const options = { ...IMAGE_OPTIONS, samples: 4, kernel: 'cycles' };+ const before = roomInput([0, 2.2, 6]);+ const after = roomInputWith(moveFloorAndLamp);+ const session = createNativeSession(before);+ try {+ session.render(options);+ const updateStarted = performance.now();+ const report = session.update(after);+ const updated = session.render(options);+ const updateMilliseconds = performance.now() - updateStarted;+ const newSessionStarted = performance.now();+ const fresh = createNativeSession(after);+ let newSessionFrame;+ try {+ newSessionFrame = fresh.render(options);+ } finally {+ fresh.close();+ }+ const newSessionMilliseconds = performance.now() - newSessionStarted;+ assertSameBytes(newSessionFrame, updated, 'the updated session against a new session');+ console.log(`SESSION_UPDATE_TIMING ${JSON.stringify({+ updateAndRenderMilliseconds: Number(updateMilliseconds.toFixed(2)),+ newSessionAndRenderMilliseconds: Number(newSessionMilliseconds.toFixed(2)),+ updateSeconds: report.updateSeconds,+ accelerationRebuildSeconds: report.accelerationRebuildSeconds,+ newSessionCompileSeconds: newSessionFrame.compileSeconds,+ newSessionAccelerationBuildSeconds: newSessionFrame.accelerationBuildSeconds,+ })}`);+ assert.equal(updated.accelerationBuildSeconds, 0);+ } finally {+ session.close();+ }+});