Skip to content

armgit / 67.js

Public Imported from GitHub
0

3D engine that AI agents drive

Keep one OIDN device and filter alive in the render-native addon (#1025)

Nguyen Xuan Anc5edda6928c5
diff --git a/bench/cycles-parity/trace-native.mjs b/bench/cycles-parity/trace-native.mjs
index 4d10230a..4cea383e 100644
--- a/bench/cycles-parity/trace-native.mjs
+++ b/bench/cycles-parity/trace-native.mjs
@@ -11,7 +11,7 @@ import { writeFloat32Npy } from './npy.mjs';
import { reconstructTraceSceneSource } from './scene-bridge.mjs';
import { denoiseRadiance } from '../../src/path-tracer-denoise.js';
import { applyGreyDiffuseOverride } from './grey-diffuse-override.mjs';
-import { denoiseWithOidn } from '../../packages/denoise-oidn/index.mjs';
+import { createOidnDenoiser, denoiseWithOidn } from '../../packages/denoise-oidn/index.mjs';
const SUPPORTED_KERNELS = new Set(['legacy', 'cycles']);
const SUPPORTED_FILTERS = new Set(['box', 'gaussian', 'blackman-harris']);
@@ -89,8 +89,8 @@ function parseOidnDevicesOption(argumentList) {
const requested = String(readFlagValue(argumentList, '--oidn-devices', ''));
const devices = requested === '' ? [] : requested.split(',');
for (const device of devices) {
- if (!['cpu', 'cuda', 'default'].includes(device)) {
- throw new RangeError(`Option --oidn-devices takes a comma list of cpu, cuda or default, got "${device}".`);
+ if (!['cpu', 'cuda', 'default', 'cpu-cli', 'cuda-cli', 'default-cli'].includes(device)) {
+ throw new RangeError(`Option --oidn-devices takes a comma list of cpu, cuda or default, each optionally with a -cli suffix to force the oidnDenoise tool, got "${device}".`);
}
}
return devices;
@@ -206,33 +206,65 @@ function applyWavelet(traced, linearRgb, width, height) {
return { image: result, seconds, replacedPixels };
}
+function median(values) {
+ const sorted = [...values].sort((first, second) => first - second);
+ return sorted[Math.floor(sorted.length / 2)];
+}
+
+const WARM_OIDN_CALLS = 3;
+
/**
- * Comparison runs only: runs the OIDN addon (packages/denoise-oidn, the official oidnDenoise tool through PFM files) on the
- * traced colour with the kernel's first-hit albedo and normal guides, once per device, and writes each result to
- * <prefix>.oidn-<device>.npy. The seconds are a second, warm call as the addon is built (PFM write, tool start, weights
- * load, filter, PFM read); the first call is reported apart.
+ * Comparison runs only: runs OIDN on the traced colour with the kernel's first-hit albedo and normal guides, once per
+ * entry of --oidn-devices, and writes each result to <prefix>.oidn-<entry>.npy. A plain device name ("cuda") uses the
+ * persistent in-process device of the render-native addon when the OIDN library is installed, and the oidnDenoise tool
+ * otherwise; "cuda-cli" forces the tool (PFM files and a process per call). `seconds` is the median of three warm calls;
+ * `firstCallSeconds` is everything the first image costs, including device creation for the in-process device.
*/
async function runOidnComparison(traced, linearRgb, options, outputPrefix) {
const albedo = traced.albedo;
const normal = new Float32Array(traced.normal);
normalizeNormals(normal);
const results = {};
- for (const device of options.oidnDevices) {
- const callOidn = () => denoiseWithOidn({ width: options.width, height: options.height, color: linearRgb, albedo, normal, device });
+ for (const entry of options.oidnDevices) {
+ const forceCli = entry.endsWith('-cli');
+ const device = forceCli ? entry.slice(0, -'-cli'.length) : entry;
+ const frame = { width: options.width, height: options.height, color: linearRgb, albedo, normal };
+ let persistent = null;
try {
const firstStarted = performance.now();
+ let mode = 'cli';
+ if (!forceCli) {
+ try {
+ persistent = createOidnDenoiser({ createNative: renderNative.createNativeOidnDenoiser, device });
+ mode = 'in-process';
+ } catch (error) {
+ results[entry] = { fallbackReason: String(error.message).slice(0, 300) };
+ }
+ }
+ const callOidn = persistent ? () => persistent.denoise(frame) : () => denoiseWithOidn({ ...frame, device });
await callOidn();
const firstSeconds = (performance.now() - firstStarted) / 1000;
- const started = performance.now();
- const denoised = await callOidn();
- results[device] = {
- seconds: Number(((performance.now() - started) / 1000).toFixed(6)),
+ const warmSeconds = [];
+ let denoised;
+ for (let call = 0; call < WARM_OIDN_CALLS; call++) {
+ const started = performance.now();
+ denoised = await callOidn();
+ warmSeconds.push((performance.now() - started) / 1000);
+ }
+ results[entry] = {
+ ...results[entry],
+ mode,
+ seconds: Number(median(warmSeconds).toFixed(6)),
firstCallSeconds: Number(firstSeconds.toFixed(6)),
+ warmCallSeconds: warmSeconds.map(seconds => Number(seconds.toFixed(6))),
+ ...(persistent ? { deviceSeconds: Number(persistent.deviceSeconds.toFixed(6)), warmPhases: persistent.lastTimings } : {}),
};
- await writeFloat32Npy(`${outputPrefix}.oidn-${device}.npy`, denoised, [options.height, options.width, 3]);
+ await writeFloat32Npy(`${outputPrefix}.oidn-${entry}.npy`, denoised, [options.height, options.width, 3]);
} catch (error) {
// One failing device (for example CUDA missing in a container) must not lose the other variants of this trace.
- results[device] = { error: String(error.message).slice(0, 600) };
+ results[entry] = { error: String(error.message).slice(0, 600) };
+ } finally {
+ persistent?.close();
}
}
return results;
diff --git a/bench/native-tracer/metal-job.mjs b/bench/native-tracer/metal-job.mjs
index 45c64c9d..e6a7eabc 100644
--- a/bench/native-tracer/metal-job.mjs
+++ b/bench/native-tracer/metal-job.mjs
@@ -11,7 +11,7 @@ import { buildNativeInput } from '../../packages/render-native/pack-input.mjs';
import * as renderNative from '../../packages/render-native/index.mjs';
import { encodeNativeTables } from '../../scripts/native-bake-page.js';
import { chooseDenoiser } from '../../scripts/agent-path-trace-denoise.mjs';
-import { traceFrameNative } from '../../scripts/agent-native-trace.mjs';
+import { denoiseFrameWithOidn, traceFrameNative } from '../../scripts/agent-native-trace.mjs';
import { loadReferenceScene } from '../cycles-parity/scene-bridge.mjs';
import { writeFloat32Npy } from '../cycles-parity/npy.mjs';
@@ -39,7 +39,7 @@ const input = buildNativeInput(buildTraceScene(source.parts, source.environment)
const exported = { tables: encodeNativeTables(input), triangleCount: input.triangleCount, triangles: input.triangleCount, ignored: [] };
let captured;
-const tracer = { traceNative(tables, traceOptions) {
+const tracer = { createNativeOidnDenoiser: renderNative.createNativeOidnDenoiser, traceNative(tables, traceOptions) {
captured = renderNative.traceNative(tables, traceOptions);
return captured;
} };
@@ -55,7 +55,7 @@ for (let offset = 0; offset < features.normal.length; offset += 3) {
if (length > 1e-6) for (let axis = 0; axis < 3; axis++) features.normal[offset + axis] /= length;
}
let linear = features.color;
-if (measured.report.denoiser === 'oidn') linear = await choice.denoiser.denoiseWithOidn(features);
+if (measured.report.denoiser === 'oidn') linear = (await denoiseFrameWithOidn({ tracer, denoiser: choice.denoiser, ...features })).linear;
else if (measured.report.denoiser === 'wavelet') linear = (await import('../../src/path-tracer-denoise.js')).denoiseRadiance(features);
await mkdir(outputDirectory, { recursive: true });
await writeFile(`${outputDirectory}/job-${label}.png`, Buffer.from(measured.data, 'base64'));
diff --git a/bench/oidn-cost/measure-oidn-cost.mjs b/bench/oidn-cost/measure-oidn-cost.mjs
new file mode 100644
index 00000000..b06a488f
--- /dev/null
+++ b/bench/oidn-cost/measure-oidn-cost.mjs
@@ -0,0 +1,257 @@
+// Measures what one OIDN call costs, and what the persistent in-process device saves (issue #1025).
+//
+// node bench/oidn-cost/measure-oidn-cost.mjs --out <result.json> [--sizes 960x540,1920x1080] [--devices cpu,cuda] [--warm 7]
+//
+// Needs the oidnDenoise tool and its library (npm run fetch in packages/denoise-oidn, or OIDN_DENOISE_PATH) and the built
+// render-native addon. For each size and device it reports:
+// - the oidnDenoise tool call split into PFM encode, PFM file write, process start to exit, PFM read and decode,
+// with the bare process start (`--version`) beside it;
+// - the in-process device: creation, first call and warm calls split into commit, buffer writes, execute and read;
+// - output equality: tool against in-process (largest absolute difference and byte identity), first against warm call;
+// - the host copy cost of the three guide images, which is the floor left when the tracer and OIDN share no memory.
+// Inputs are synthetic and seeded (shaded blocks with noise), so the timings do not depend on a scene.
+import { spawn } from 'node:child_process';
+import { mkdtemp, readFile, rm, writeFile } from 'node:fs/promises';
+import { mkdirSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { dirname, join } from 'node:path';
+
+import { createOidnDenoiser, decodePfm, denoiseWithOidn, encodePfm, findOidnBinary } from '../../packages/denoise-oidn/index.mjs';
+import { createNativeOidnDenoiser, findNativeAddon } from '../../packages/render-native/index.mjs';
+
+function readOption(name, fallback) {
+ const index = process.argv.indexOf(name);
+ return index >= 0 ? process.argv[index + 1] : fallback;
+}
+
+function median(values) {
+ const sorted = [...values].sort((first, second) => first - second);
+ return sorted[Math.floor(sorted.length / 2)];
+}
+
+function seconds(started) {
+ return (performance.now() - started) / 1000;
+}
+
+function round(value) {
+ return Number(value.toFixed(6));
+}
+
+/** A small seeded generator, so every run and every machine denoises the same pixels. */
+function createRandom(seed) {
+ let state = seed >>> 0;
+ return () => {
+ state = (Math.imul(state, 1664525) + 1013904223) >>> 0;
+ return state / 4294967296;
+ };
+}
+
+function makeImages(width, height) {
+ const random = createRandom(1025);
+ const pixelCount = width * height;
+ const color = new Float32Array(pixelCount * 3);
+ const albedo = new Float32Array(pixelCount * 3);
+ const normal = new Float32Array(pixelCount * 3);
+ for (let y = 0; y < height; y++) {
+ for (let x = 0; x < width; x++) {
+ const offset = (y * width + x) * 3;
+ const block = (Math.floor(x / 64) + Math.floor(y / 64)) % 3;
+ const base = [0.8, 0.3, 0.5][block];
+ const tilt = block * 0.4;
+ const length = Math.hypot(tilt, 1);
+ const shade = 0.5 + 2 * (x / width);
+ for (let channel = 0; channel < 3; channel++) {
+ albedo[offset + channel] = base * (0.7 + 0.1 * channel);
+ color[offset + channel] = Math.max(0, albedo[offset + channel] * shade * (0.4 + 1.2 * random()));
+ }
+ normal[offset] = tilt / length;
+ normal[offset + 1] = 1 / length;
+ normal[offset + 2] = 0;
+ }
+ }
+ return { color, albedo, normal };
+}
+
+function maxAbsoluteDifference(first, second) {
+ let largest = 0;
+ for (let index = 0; index < first.length; index++) largest = Math.max(largest, Math.abs(first[index] - second[index]));
+ return largest;
+}
+
+function byteIdentical(first, second) {
+ return Buffer.compare(Buffer.from(first.buffer, first.byteOffset, first.byteLength), Buffer.from(second.buffer, second.byteOffset, second.byteLength)) === 0;
+}
+
+function runProcess(binary, toolArguments) {
+ return new Promise((resolve, reject) => {
+ const started = performance.now();
+ const child = spawn(binary, toolArguments, { stdio: ['ignore', 'pipe', 'pipe'], windowsHide: true });
+ let output = '';
+ child.stdout.on('data', chunk => { output += chunk; });
+ child.stderr.on('data', chunk => { output += chunk; });
+ child.on('error', reject);
+ child.on('close', code => resolve({ code, seconds: seconds(started), output }));
+ });
+}
+
+/** One tool call, timed phase by phase with the same steps denoiseWithOidn takes. */
+async function timeToolCall(binary, frame, device) {
+ const { width, height, color, albedo, normal } = frame;
+ const directory = await mkdtemp(join(tmpdir(), '67js-oidn-cost-'));
+ try {
+ let started = performance.now();
+ const encoded = [encodePfm(color, width, height), encodePfm(albedo, width, height), encodePfm(normal, width, height)];
+ const encodeSeconds = seconds(started);
+ started = performance.now();
+ await Promise.all([
+ writeFile(join(directory, 'color.pfm'), encoded[0]),
+ writeFile(join(directory, 'albedo.pfm'), encoded[1]),
+ writeFile(join(directory, 'normal.pfm'), encoded[2]),
+ ]);
+ const writeSeconds = seconds(started);
+ const toolArguments = ['--device', device, '--quality', 'high', '--hdr', join(directory, 'color.pfm'), '--alb', join(directory, 'albedo.pfm'),
+ '--nrm', join(directory, 'normal.pfm'), '--output', join(directory, 'out.pfm')];
+ const run = await runProcess(binary, toolArguments);
+ if (run.code !== 0) throw new Error(`oidnDenoise exited with ${run.code}: ${run.output.slice(0, 400)}`);
+ started = performance.now();
+ decodePfm(await readFile(join(directory, 'out.pfm')), width, height);
+ const readSeconds = seconds(started);
+ return { encodeSeconds, writeSeconds, processSeconds: run.seconds, readSeconds, totalSeconds: encodeSeconds + writeSeconds + run.seconds + readSeconds };
+ } finally {
+ await rm(directory, { recursive: true, force: true });
+ }
+}
+
+function medianOf(rows, key) {
+ return round(median(rows.map(row => row[key])));
+}
+
+async function measureTool(binary, frame, device, warmCount) {
+ const rows = [];
+ for (let call = 0; call < warmCount; call++) rows.push(await timeToolCall(binary, frame, device));
+ const bare = [];
+ for (let call = 0; call < warmCount; call++) bare.push((await runProcess(binary, ['--version'])).seconds);
+ // Verbose output shows where the tool spends its time on this machine; a flag the tool rejects is recorded, not fatal.
+ const directory = await mkdtemp(join(tmpdir(), '67js-oidn-cost-'));
+ let verbose;
+ try {
+ await Promise.all([
+ writeFile(join(directory, 'color.pfm'), encodePfm(frame.color, frame.width, frame.height)),
+ writeFile(join(directory, 'albedo.pfm'), encodePfm(frame.albedo, frame.width, frame.height)),
+ writeFile(join(directory, 'normal.pfm'), encodePfm(frame.normal, frame.width, frame.height)),
+ ]);
+ const run = await runProcess(binary, ['--device', device, '--quality', 'high', '--hdr', join(directory, 'color.pfm'), '--alb', join(directory, 'albedo.pfm'),
+ '--nrm', join(directory, 'normal.pfm'), '--output', join(directory, 'out.pfm'), '--verbose', '2']);
+ verbose = { exit: run.code, seconds: round(run.seconds), output: run.output.slice(0, 3000) };
+ } catch (error) {
+ verbose = { error: String(error.message).slice(0, 300) };
+ } finally {
+ await rm(directory, { recursive: true, force: true });
+ }
+ return {
+ warmCalls: warmCount,
+ encodeSeconds: medianOf(rows, 'encodeSeconds'),
+ fileWriteSeconds: medianOf(rows, 'writeSeconds'),
+ processStartToExitSeconds: medianOf(rows, 'processSeconds'),
+ bareProcessSeconds: round(median(bare)),
+ fileReadDecodeSeconds: medianOf(rows, 'readSeconds'),
+ totalSeconds: medianOf(rows, 'totalSeconds'),
+ verbose,
+ };
+}
+
+async function measureInProcess(frame, device, warmCount) {
+ const created = performance.now();
+ const denoiser = createOidnDenoiser({ createNative: createNativeOidnDenoiser, device });
+ const createSeconds = seconds(created);
+ try {
+ let started = performance.now();
+ const firstOutput = await denoiser.denoise(frame);
+ const firstCallSeconds = seconds(started);
+ const firstTimings = denoiser.lastTimings;
+ const warm = [];
+ let warmOutput;
+ for (let call = 0; call < warmCount; call++) {
+ started = performance.now();
+ warmOutput = await denoiser.denoise(frame);
+ warm.push({ wallSeconds: seconds(started), ...denoiser.lastTimings });
+ }
+ // A different size recommits the filter; the same size afterwards recommits once more and gives the same bytes.
+ const otherSize = await denoiser.denoise({ width: 64, height: 64, color: new Float32Array(64 * 64 * 3).fill(0.5), albedo: new Float32Array(64 * 64 * 3).fill(0.5), normal: new Float32Array(64 * 64 * 3) });
+ const afterResize = denoiser.lastTimings.recommitted;
+ const againOutput = await denoiser.denoise(frame);
+ return {
+ libraryPath: denoiser.libraryPath,
+ createSeconds: round(createSeconds),
+ deviceSeconds: round(denoiser.deviceSeconds),
+ firstCall: { wallSeconds: round(firstCallSeconds), ...Object.fromEntries(Object.entries(firstTimings).map(([key, value]) => [key, typeof value === 'number' ? round(value) : value])) },
+ warm: {
+ calls: warmCount,
+ wallSeconds: medianOf(warm, 'wallSeconds'),
+ commitSeconds: medianOf(warm, 'commitSeconds'),
+ writeSeconds: medianOf(warm, 'writeSeconds'),
+ executeSeconds: medianOf(warm, 'executeSeconds'),
+ readSeconds: medianOf(warm, 'readSeconds'),
+ anyRecommitted: warm.some(row => row.recommitted),
+ },
+ resize: { recommittedAfterSizeChange: afterResize, smallOutputLength: otherSize.length, recommittedBackAtFullSize: denoiser.lastTimings.recommitted },
+ outputs: { firstOutput, warmOutput, againOutput },
+ };
+ } finally {
+ denoiser.close();
+ }
+}
+
+function measureHostCopies(frame, repeats) {
+ const timings = [];
+ for (let repeat = 0; repeat < repeats; repeat++) {
+ const started = performance.now();
+ const copies = [frame.color.slice(), frame.albedo.slice(), frame.normal.slice()];
+ timings.push(seconds(started));
+ if (copies[0].length !== frame.color.length) throw new Error('copy failed');
+ }
+ return round(median(timings));
+}
+
+async function main() {
+ const outputPath = readOption('--out', '');
+ if (!outputPath) throw new RangeError('Usage: node bench/oidn-cost/measure-oidn-cost.mjs --out <result.json> [--sizes 960x540,1920x1080] [--devices cpu,cuda] [--warm 7]');
+ const sizes = readOption('--sizes', '960x540,1920x1080').split(',').map(text => text.split('x').map(Number));
+ const devices = readOption('--devices', 'cpu,cuda').split(',');
+ const warmCount = Number(readOption('--warm', '7'));
+ const binary = findOidnBinary();
+ if (!binary) throw new Error('The oidnDenoise tool is not installed: run `npm run fetch` in packages/denoise-oidn, or set OIDN_DENOISE_PATH.');
+ if (!findNativeAddon()) throw new Error('The render-native addon is not built: run `npm run build` in packages/render-native.');
+ const result = { oidnBinary: 'oidnDenoise', devices, sizes: [], rows: [] };
+ for (const [width, height] of sizes) {
+ const images = makeImages(width, height);
+ const frame = { width, height, ...images };
+ const hostCopySeconds = measureHostCopies(frame, warmCount);
+ for (const device of devices) {
+ const row = { width, height, device, hostCopyThreeImagesSeconds: hostCopySeconds };
+ try {
+ row.tool = await measureTool(binary, frame, device, warmCount);
+ const toolOutput = await denoiseWithOidn({ ...frame, device });
+ const inProcess = await measureInProcess(frame, device, warmCount);
+ const { firstOutput, warmOutput, againOutput } = inProcess.outputs;
+ delete inProcess.outputs;
+ row.inProcess = inProcess;
+ row.equality = {
+ toolVsWarm: { maxAbsoluteDifference: maxAbsoluteDifference(toolOutput, warmOutput), byteIdentical: byteIdentical(toolOutput, warmOutput) },
+ firstVsWarm: { maxAbsoluteDifference: maxAbsoluteDifference(firstOutput, warmOutput), byteIdentical: byteIdentical(firstOutput, warmOutput) },
+ warmVsAfterRecommit: { maxAbsoluteDifference: maxAbsoluteDifference(againOutput, warmOutput), byteIdentical: byteIdentical(againOutput, warmOutput) },
+ };
+ row.speedupWarmVersusTool = round(row.tool.totalSeconds / inProcess.warm.wallSeconds);
+ } catch (error) {
+ row.error = String(error.message).slice(0, 600);
+ }
+ result.rows.push(row);
+ console.log('ROW', JSON.stringify(row));
+ }
+ }
+ mkdirSync(dirname(outputPath), { recursive: true });
+ writeFileSync(outputPath, JSON.stringify(result, null, 1));
+ console.log('WROTE', outputPath);
+}
+
+await main();
diff --git a/packages/denoise-oidn/index.mjs b/packages/denoise-oidn/index.mjs
index 7bc51136..396465c4 100644
--- a/packages/denoise-oidn/index.mjs
+++ b/packages/denoise-oidn/index.mjs
@@ -91,3 +91,69 @@ export async function denoiseWithOidn({ width, height, color, albedo, normal, de
await rm(directory, { recursive: true, force: true });
}
}
+
+const LIBRARY_FILES = {
+ win32: { directories: ['bin'], names: ['OpenImageDenoise.dll'] },
+ darwin: { directories: ['lib'], names: ['libOpenImageDenoise.2.dylib', `libOpenImageDenoise.${OIDN_VERSION}.dylib`, 'libOpenImageDenoise.dylib'] },
+ linux: { directories: ['lib', 'lib64'], names: ['libOpenImageDenoise.so.2', `libOpenImageDenoise.so.${OIDN_VERSION}`, 'libOpenImageDenoise.so'] },
+};
+
+function findFirstExisting(directories, names) {
+ for (const directory of directories) {
+ for (const name of names) {
+ const candidate = join(directory, name);
+ if (existsSync(candidate)) return candidate;
+ }
+ }
+ return null;
+}
+
+/**
+ * The path of the OIDN shared library that the in-process denoiser loads, or null when none is installed. Looks at
+ * `OIDN_LIBRARY_PATH`, then next to the tool named by `OIDN_DENOISE_PATH` (its release folder), then in ./vendor.
+ */
+export function findOidnLibrary() {
+ const configured = process.env.OIDN_LIBRARY_PATH;
+ if (configured) return existsSync(configured) ? configured : null;
+ const layout = LIBRARY_FILES[process.platform];
+ if (!layout) return null;
+ const binary = findOidnBinary();
+ if (!binary) return null;
+ const releaseDirectory = dirname(dirname(binary));
+ return findFirstExisting(layout.directories.map(directory => join(releaseDirectory, directory)), layout.names);
+}
+
+const NATIVE_DEVICE_NAMES = /^(default|cpu|sycl|cuda|hip|metal|\d+)$/;
+
+/**
+ * An OIDN device and filter that stay loaded between calls, so only the first call pays for the device, the weights and the
+ * filter commit. `createNative` is `createNativeOidnDenoiser` of `@codepawlhq/67js-render-native`, whose addon links the
+ * OIDN library at run time; this package does not load the addon itself. Returns `{ denoise, close, deviceSeconds,
+ * lastTimings, libraryPath }`; `denoise` takes what `denoiseWithOidn` takes and resolves with a new Float32Array.
+ * Throws, with what to do, when the library or the addon is missing, so a caller can use `denoiseWithOidn` instead.
+ */
+export function createOidnDenoiser({ createNative, device = 'cpu', quality = 'high', cleanAux = false, threads = 0, libraryPath = findOidnLibrary() } = {}) {
+ if (typeof createNative !== 'function') {
+ throw new TypeError('createOidnDenoiser needs `createNative`: pass createNativeOidnDenoiser from the render-native package.');
+ }
+ if (!libraryPath) {
+ throw new Error('The OIDN shared library is not installed: run `npm run fetch` in the denoise package, or set OIDN_LIBRARY_PATH.');
+ }
+ if (typeof device !== 'string' || !NATIVE_DEVICE_NAMES.test(device)) {
+ throw new TypeError(`createOidnDenoiser: device ${JSON.stringify(device)} is unknown: pass "cpu", "cuda", "hip", "sycl", "metal", "default" or a device index.`);
+ }
+ const native = createNative({ libraryPath, device, quality, cleanAux, threads });
+ let lastTimings = null;
+ return {
+ libraryPath,
+ deviceSeconds: native.deviceSeconds,
+ get lastTimings() { return lastTimings; },
+ async denoise({ width, height, color, albedo, normal }) {
+ const result = native.denoise({ width, height, color, albedo, normal });
+ const { color: denoised, ...timings } = result;
+ lastTimings = timings;
+ return denoised;
+ },
+ close() { native.close(); },
+ };
+}
diff --git a/packages/render-native/Cargo.lock b/packages/render-native/Cargo.lock
index 92bfa1a1..8385538c 100644
--- a/packages/render-native/Cargo.lock
+++ b/packages/render-native/Cargo.lock
@@ -654,6 +654,7 @@ name = "render-native"
version = "0.1.0"
dependencies = [
"bytemuck",
+ "libloading 0.8.9",
"napi",
"napi-build",
"napi-derive",
diff --git a/packages/render-native/Cargo.toml b/packages/render-native/Cargo.toml
index 6caa593e..5afbd3f4 100644
--- a/packages/render-native/Cargo.toml
+++ b/packages/render-native/Cargo.toml
@@ -11,6 +11,7 @@ crate-type = ["cdylib"]
[dependencies]
bytemuck = "1"
+libloading = "0.8"
napi = { version = "3", default-features = false, features = ["napi6"] }
napi-derive = "3"
pollster = "0.4"
diff --git a/packages/render-native/index.mjs b/packages/render-native/index.mjs
index 8b212e9d..518b4a3c 100644
--- a/packages/render-native/index.mjs
+++ b/packages/render-native/index.mjs
@@ -140,6 +140,23 @@ export function denoiseAtrous({ width, height, rgba, albedo, normal, depth, vari
return loadAddon().denoiseAtrous({ width, height, rgba, albedo, normal, depth, variance });
}
+/**
+ * Opens a persistent OIDN device and filter inside the addon. The OIDN shared library is loaded at run time from
+ * `libraryPath` (`findOidnLibrary()` of the denoise package), so the addon works without it. Returns the native object
+ * with `denoise({ width, height, color, albedo, normal })`, `close()` and `deviceSeconds`. Use
+ * `createOidnDenoiser` of the denoise package for the wrapper that jobs call.
+ */
+export function createNativeOidnDenoiser({ libraryPath, device = 'cpu', quality = 'high', cleanAux = false, threads = 0 }) {
+ if (typeof libraryPath !== 'string' || libraryPath === '') {
+ throw new TypeError('createNativeOidnDenoiser: pass `libraryPath`, the OIDN shared library (findOidnLibrary() in the denoise package).');
+ }
+ const addon = loadAddon();
+ if (typeof addon.OidnDenoiser !== 'function') {
+ throw new Error('The built native tracer has no OIDN support: run `npm run build` in packages/render-native again.');
+ }
+ return new addon.OidnDenoiser({ libraryPath, device, quality, cleanAux, threads });
+}
+
function hasFilterOptions(options) {
return options.filterType !== undefined || options.pixelFilter !== undefined || options.filterWidth !== undefined;
}
diff --git a/packages/render-native/src/host/mod.rs b/packages/render-native/src/host/mod.rs
index 6e4bc72d..83f75ecc 100644
--- a/packages/render-native/src/host/mod.rs
+++ b/packages/render-native/src/host/mod.rs
@@ -3,5 +3,6 @@ pub(crate) mod denoise;
pub(crate) mod dispatch;
pub(crate) mod device;
pub(crate) mod film;
+pub(crate) mod oidn;
pub(crate) mod session;
pub(crate) mod textures;
diff --git a/packages/render-native/src/host/oidn.rs b/packages/render-native/src/host/oidn.rs
new file mode 100644
index 00000000..c3ee6fcc
--- /dev/null
+++ b/packages/render-native/src/host/oidn.rs
@@ -0,0 +1,467 @@
+//! A persistent Intel Open Image Denoise device and filter (issue #1025). The OIDN shared library is opened at run time, so
+//! the addon builds and loads without it. The device, the four image buffers and the committed "RT" filter stay alive
+//! between calls and are rebuilt only when the image size, the set of guides or the settings change, so a warm call costs
+//! the buffer writes, the filter and the read back.
+//!
+//! The C names and enum values come from `include/OpenImageDenoise/oidn.h` of OIDN 2.5.
+
+use std::ffi::{c_char, c_int, c_void, CStr, CString};
+use std::time::Instant;
+
+use libloading::Library;
+use napi::bindgen_prelude::Float32Array;
+use napi::Result;
+use napi_derive::napi;
+
+use crate::host::device::failure;
+
+type Handle = *mut c_void;
+
+const FORMAT_FLOAT3: c_int = 3;
+const BYTES_PER_PIXEL: usize = 12;
+const ERROR_NONE: c_int = 0;
+
+const DEVICE_NAMES: [(&str, c_int); 6] = [("default", 0), ("cpu", 1), ("sycl", 2), ("cuda", 3), ("hip", 4), ("metal", 5)];
+const QUALITY_NAMES: [(&str, c_int); 4] = [("default", 0), ("fast", 4), ("balanced", 5), ("high", 6)];
+
+/// How a device name becomes an OIDN device: a type, or a physical device index.
+#[derive(Debug, PartialEq, Eq, Clone, Copy)]
+enum DeviceChoice {
+ Type(c_int),
+ PhysicalIndex(c_int),
+}
+
+fn parse_device(name: &str) -> Result<DeviceChoice> {
+ let lowered = name.trim().to_ascii_lowercase();
+ if let Some((_, device_type)) = DEVICE_NAMES.iter().find(|(known, _)| *known == lowered) {
+ return Ok(DeviceChoice::Type(*device_type));
+ }
+ if let Ok(index) = lowered.parse::<c_int>() {
+ if index >= 0 {
+ return Ok(DeviceChoice::PhysicalIndex(index));
+ }
+ }
+ Err(failure(format!(
+ "OIDN device {name:?} is unknown: pass \"cpu\", \"cuda\", \"hip\", \"sycl\", \"metal\", \"default\" or a physical device index."
+ )))
+}
+
+fn parse_quality(name: &str) -> Result<c_int> {
+ QUALITY_NAMES
+ .iter()
+ .find(|(known, _)| *known == name)
+ .map(|(_, value)| *value)
+ .ok_or_else(|| failure(format!("OIDN quality {name:?} is unknown: pass \"default\", \"fast\", \"balanced\" or \"high\".")))
+}
+
+/// The OIDN entry points this module calls, copied out of the library as plain function pointers.
+struct OidnApi {
+ new_device: unsafe extern "C" fn(c_int) -> Handle,
+ new_device_by_id: unsafe extern "C" fn(c_int) -> Handle,
+ set_device_int: unsafe extern "C" fn(Handle, *const c_char, c_int),
+ commit_device: unsafe extern "C" fn(Handle),
+ sync_device: unsafe extern "C" fn(Handle),
+ release_device: unsafe extern "C" fn(Handle),
+ get_device_error: unsafe extern "C" fn(Handle, *mut *const c_char) -> c_int,
+ new_buffer: unsafe extern "C" fn(Handle, usize) -> Handle,
+ write_buffer: unsafe extern "C" fn(Handle, usize, usize, *const c_void),
+ read_buffer: unsafe extern "C" fn(Handle, usize, usize, *mut c_void),
+ release_buffer: unsafe extern "C" fn(Handle),
+ new_filter: unsafe extern "C" fn(Handle, *const c_char) -> Handle,
+ set_filter_image: unsafe extern "C" fn(Handle, *const c_char, Handle, c_int, usize, usize, usize, usize, usize),
+ set_filter_bool: unsafe extern "C" fn(Handle, *const c_char, bool),
+ set_filter_int: unsafe extern "C" fn(Handle, *const c_char, c_int),
+ commit_filter: unsafe extern "C" fn(Handle),
+ execute_filter: unsafe extern "C" fn(Handle),
+ release_filter: unsafe extern "C" fn(Handle),
+ // Declared last: the pointers above stay valid only while the library is loaded.
+ _library: Library,
+}
+
+/// Looks one entry point up by name.
+///
+/// # Safety
+/// `Function` must be the exact `extern "C"` signature of the named OIDN function.
+unsafe fn load_function<Function: Copy>(library: &Library, name: &str) -> Result<Function> {
+ let symbol = library
+ .get::<Function>(name.as_bytes())
+ .map_err(|error| failure(format!("The OIDN library has no function {name} ({error}): it is not OIDN 2.5 or newer.")))?;
+ Ok(*symbol)
+}
+
+impl OidnApi {
+ fn open(library_path: &str) -> Result<Self> {
+ // SAFETY: opening a shared library runs its initialisers; the caller names the official OIDN library.
+ let library = unsafe { Library::new(library_path) }.map_err(|error| {
+ failure(format!("Could not load the OIDN library at {library_path:?} ({error}): run `npm run fetch` in the denoise package, or pass libraryPath."))
+ })?;
+ // SAFETY: every signature below is the one declared in oidn.h of OIDN 2.5.
+ unsafe {
+ Ok(Self {
+ new_device: load_function(&library, "oidnNewDevice")?,
+ new_device_by_id: load_function(&library, "oidnNewDeviceByID")?,
+ set_device_int: load_function(&library, "oidnSetDeviceInt")?,
+ commit_device: load_function(&library, "oidnCommitDevice")?,
+ sync_device: load_function(&library, "oidnSyncDevice")?,
+ release_device: load_function(&library, "oidnReleaseDevice")?,
+ get_device_error: load_function(&library, "oidnGetDeviceError")?,
+ new_buffer: load_function(&library, "oidnNewBuffer")?,
+ write_buffer: load_function(&library, "oidnWriteBuffer")?,
+ read_buffer: load_function(&library, "oidnReadBuffer")?,
+ release_buffer: load_function(&library, "oidnReleaseBuffer")?,
+ new_filter: load_function(&library, "oidnNewFilter")?,
+ set_filter_image: load_function(&library, "oidnSetFilterImage")?,
+ set_filter_bool: load_function(&library, "oidnSetFilterBool")?,
+ set_filter_int: load_function(&library, "oidnSetFilterInt")?,
+ commit_filter: load_function(&library, "oidnCommitFilter")?,
+ execute_filter: load_function(&library, "oidnExecuteFilter")?,
+ release_filter: load_function(&library, "oidnReleaseFilter")?,
+ _library: library,
+ })
+ }
+ }
+
+ /// Turns the device's pending error, or the global one for a null device, into a message.
+ fn pending_error(&self, device: Handle) -> Option<String> {
+ let mut message: *const c_char = std::ptr::null();
+ // SAFETY: a null device asks for the global error; `message` is written by OIDN and valid until the next call.
+ let code = unsafe { (self.get_device_error)(device, &mut message) };
+ if code == ERROR_NONE {
+ return None;
+ }
+ let text = if message.is_null() {
+ "no message".to_string()
+ } else {
+ // SAFETY: OIDN returns a NUL terminated string.
+ unsafe { CStr::from_ptr(message) }.to_string_lossy().into_owned()
+ };
+ Some(format!("{text} (OIDN error {code})"))
+ }
+}
+
+/// What a committed filter was built for. A call with another key rebuilds the buffers and the filter.
+#[derive(PartialEq, Eq, Clone, Copy)]
+struct FilterKey {
+ width: usize,
+ height: usize,
+ has_albedo: bool,
+ has_normal: bool,
+}
+
+#[napi(object)]
+pub struct OidnDenoiserOptions {
+ pub library_path: String,
+ /// `"cpu"` (default), `"cuda"`, `"hip"`, `"sycl"`, `"metal"`, `"default"` or a physical device index.
+ pub device: Option<String>,
+ /// `"default"`, `"fast"`, `"balanced"` or `"high"` (default).
+ pub quality: Option<String>,
+ pub clean_aux: Option<bool>,
+ /// CPU thread count; absent or 0 lets OIDN choose.
+ pub threads: Option<u32>,
+}
+
+#[napi(object)]
+pub struct OidnDenoiseCall {
+ pub width: u32,
+ pub height: u32,
+ /// Linear HDR radiance, three floats per pixel, rows top to bottom.
+ pub color: Float32Array,
+ pub albedo: Option<Float32Array>,
+ /// Needs `albedo`.
+ pub normal: Option<Float32Array>,
+}
+
+#[napi(object)]
+pub struct OidnDenoiseResult {
+ pub color: Float32Array,
+ /// True when this call rebuilt the buffers and committed the filter (the first call, or a changed size or guide set).
+ pub recommitted: bool,
+ /// Buffer allocation, filter creation and commit; 0 when the committed filter was reused.
+ pub commit_seconds: f64,
+ pub write_seconds: f64,
+ pub execute_seconds: f64,
+ pub read_seconds: f64,
+}
+
+/// A device and filter kept alive between calls.
+#[napi]
+pub struct OidnDenoiser {
+ api: OidnApi,
+ device: Handle,
+ quality: c_int,
+ clean_aux: bool,
+ device_seconds: f64,
+ key: Option<FilterKey>,
+ filter: Handle,
+ color_buffer: Handle,
+ albedo_buffer: Handle,
+ normal_buffer: Handle,
+ output_buffer: Handle,
+}
+
+// SAFETY: the handles are used only through `&mut self`, one call at a time.
+unsafe impl Send for OidnDenoiser {}
+
+fn name_to_c(name: &str) -> CString {
+ CString::new(name).expect("names in this module have no NUL byte")
+}
+
+#[napi]
+impl OidnDenoiser {
+ #[napi(constructor)]
+ pub fn new(options: OidnDenoiserOptions) -> Result<Self> {
+ let device_name = options.device.as_deref().unwrap_or("cpu");
+ let choice = parse_device(device_name)?;
+ let quality = parse_quality(options.quality.as_deref().unwrap_or("high"))?;
+ let api = OidnApi::open(&options.library_path)?;
+ let started = Instant::now();
+ // SAFETY: plain OIDN calls with valid arguments; a null device means creation failed.
+ let device = unsafe {
+ match choice {
+ DeviceChoice::Type(device_type) => (api.new_device)(device_type),
+ DeviceChoice::PhysicalIndex(index) => (api.new_device_by_id)(index),
+ }
+ };
+ if device.is_null() {
+ let reason = api.pending_error(std::ptr::null_mut()).unwrap_or_else(|| "no message".to_string());
+ return Err(failure(format!("OIDN could not create the {device_name:?} device: {reason}. Pass device \"cpu\" or check the GPU driver.")));
+ }
+ let mut denoiser = Self {
+ api,
+ device,
+ quality,
+ clean_aux: options.clean_aux.unwrap_or(false),
+ device_seconds: 0.0,
+ key: None,
+ filter: std::ptr::null_mut(),
+ color_buffer: std::ptr::null_mut(),
+ albedo_buffer: std::ptr::null_mut(),
+ normal_buffer: std::ptr::null_mut(),
+ output_buffer: std::ptr::null_mut(),
+ };
+ // From here a failure drops `denoiser`, which releases the device.
+ if let Some(threads) = options.threads.filter(|count| *count > 0) {
+ let setting = name_to_c("numThreads");
+ // SAFETY: the device is valid and the name is NUL terminated.
+ unsafe { (denoiser.api.set_device_int)(device, setting.as_ptr(), threads as c_int) };
+ }
+ // SAFETY: the device is valid.
+ unsafe { (denoiser.api.commit_device)(device) };
+ denoiser.check_device("commit the device")?;
+ denoiser.device_seconds = started.elapsed().as_secs_f64();
+ Ok(denoiser)
+ }
+
+ /// Seconds the constructor spent creating and committing the device (CUDA initialisation is most of it).
+ #[napi(getter)]
+ pub fn device_seconds(&self) -> f64 {
+ self.device_seconds
+ }
+
+ #[napi]
+ pub fn denoise(&mut self, call: OidnDenoiseCall) -> Result<OidnDenoiseResult> {
+ if self.device.is_null() {
+ return Err(failure("This OIDN denoiser is closed: create a new one with createOidnDenoiser."));
+ }
+ let width = call.width as usize;
+ let height = call.height as usize;
+ let floats = width * height * 3;
+ if width == 0 || height == 0 {
+ return Err(failure("OIDN denoise needs a width and height of at least 1."));
+ }
+ if call.normal.is_some() && call.albedo.is_none() {
+ return Err(failure("OIDN takes a normal guide only together with an albedo guide: pass albedo too, or drop normal."));
+ }
+ check_length("color", call.color.len(), floats)?;
+ if let Some(albedo) = &call.albedo {
+ check_length("albedo", albedo.len(), floats)?;
+ }
+ if let Some(normal) = &call.normal {
+ check_length("normal", normal.len(), floats)?;
+ }
+ let key = FilterKey { width, height, has_albedo: call.albedo.is_some(), has_normal: call.normal.is_some() };
+ let byte_count = floats * 4;
+
+ let commit_started = Instant::now();
+ let recommitted = self.key != Some(key);
+ if recommitted {
+ self.release_session();
+ self.build_session(key)?;
+ }
+ let commit_seconds = if recommitted { commit_started.elapsed().as_secs_f64() } else { 0.0 };
+
+ let write_started = Instant::now();
+ // SAFETY: each buffer holds `byte_count` bytes and each source slice was checked to hold as many.
+ unsafe {
+ (self.api.write_buffer)(self.color_buffer, 0, byte_count, call.color.as_ptr().cast());
+ if let Some(albedo) = &call.albedo {
+ (self.api.write_buffer)(self.albedo_buffer, 0, byte_count, albedo.as_ptr().cast());
+ }
+ if let Some(normal) = &call.normal {
+ (self.api.write_buffer)(self.normal_buffer, 0, byte_count, normal.as_ptr().cast());
+ }
+ }
+ let write_seconds = write_started.elapsed().as_secs_f64();
+
+ let execute_started = Instant::now();
+ // SAFETY: the filter is committed for this key. The sync makes GPU time count here, not in the read.
+ unsafe {
+ (self.api.execute_filter)(self.filter);
+ (self.api.sync_device)(self.device);
+ }
+ self.check_device("run the filter")?;
+ let execute_seconds = execute_started.elapsed().as_secs_f64();
+
+ let read_started = Instant::now();
+ let mut denoised = vec![0.0f32; floats];
+ // SAFETY: `denoised` holds `byte_count` bytes.
+ unsafe { (self.api.read_buffer)(self.output_buffer, 0, byte_count, denoised.as_mut_ptr().cast()) };
+ self.check_device("read the result")?;
+ let read_seconds = read_started.elapsed().as_secs_f64();
+
+ Ok(OidnDenoiseResult { color: Float32Array::new(denoised), recommitted, commit_seconds, write_seconds, execute_seconds, read_seconds })
+ }
+
+ /// Releases the filter, the buffers and the device now instead of when the object is collected.
+ #[napi]
+ pub fn close(&mut self) {
+ self.release_session();
+ if !self.device.is_null() {
+ // SAFETY: the device is valid and released once.
+ unsafe { (self.api.release_device)(self.device) };
+ self.device = std::ptr::null_mut();
+ }
+ }
+}
+
+fn check_length(name: &str, actual: usize, expected: usize) -> Result<()> {
+ if actual == expected {
+ return Ok(());
+ }
+ Err(failure(format!("OIDN denoise: `{name}` has {actual} floats but the image needs {expected} (3 per pixel): pass a Float32Array of width * height * 3.")))
+}
+
+impl OidnDenoiser {
+ fn check_device(&self, action: &str) -> Result<()> {
+ match self.api.pending_error(self.device) {
+ None => Ok(()),
+ Some(message) => Err(failure(format!("OIDN could not {action}: {message}."))),
+ }
+ }
+
+ fn new_buffer(&self, byte_count: usize) -> Result<Handle> {
+ // SAFETY: the device is valid.
+ let buffer = unsafe { (self.api.new_buffer)(self.device, byte_count) };
+ self.check_device("allocate an image buffer")?;
+ if buffer.is_null() {
+ return Err(failure("OIDN returned no buffer: the device is out of memory for this image size."));
+ }
+ Ok(buffer)
+ }
+
+ fn set_image(&self, name: &str, buffer: Handle, key: FilterKey) {
+ let image_name = name_to_c(name);
+ // SAFETY: strides of 0 let OIDN compute tightly packed float3 pixels.
+ unsafe { (self.api.set_filter_image)(self.filter, image_name.as_ptr(), buffer, FORMAT_FLOAT3, key.width, key.height, 0, 0, 0) };
+ }
+
+ /// Allocates the buffers, creates the "RT" filter and commits it. On failure the partly built session is released by
+ /// the next `release_session`, which `Drop` and `denoise` both run.
+ fn build_session(&mut self, key: FilterKey) -> Result<()> {
+ let byte_count = key.width * key.height * BYTES_PER_PIXEL;
+ self.color_buffer = self.new_buffer(byte_count)?;
+ if key.has_albedo {
+ self.albedo_buffer = self.new_buffer(byte_count)?;
+ }
+ if key.has_normal {
+ self.normal_buffer = self.new_buffer(byte_count)?;
+ }
+ self.output_buffer = self.new_buffer(byte_count)?;
+ let filter_type = name_to_c("RT");
+ // SAFETY: the device is valid.
+ self.filter = unsafe { (self.api.new_filter)(self.device, filter_type.as_ptr()) };
+ self.check_device("create the RT filter")?;
+ self.set_image("color", self.color_buffer, key);
+ if key.has_albedo {
+ self.set_image("albedo", self.albedo_buffer, key);
+ }
+ if key.has_normal {
+ self.set_image("normal", self.normal_buffer, key);
+ }
+ self.set_image("output", self.output_buffer, key);
+ let hdr = name_to_c("hdr");
+ let clean_aux = name_to_c("cleanAux");
+ let quality = name_to_c("quality");
+ // SAFETY: the filter is valid and the names are NUL terminated.
+ unsafe {
+ (self.api.set_filter_bool)(self.filter, hdr.as_ptr(), true);
+ (self.api.set_filter_bool)(self.filter, clean_aux.as_ptr(), self.clean_aux);
+ (self.api.set_filter_int)(self.filter, quality.as_ptr(), self.quality);
+ (self.api.commit_filter)(self.filter);
+ }
+ self.check_device("commit the RT filter")?;
+ self.key = Some(key);
+ Ok(())
+ }
+
+ fn release_session(&mut self) {
+ // SAFETY: each non-null handle came from the matching `new` call and is released once, then nulled.
+ unsafe {
+ if !self.filter.is_null() {
+ (self.api.release_filter)(self.filter);
+ }
+ for buffer in [self.color_buffer, self.albedo_buffer, self.normal_buffer, self.output_buffer] {
+ if !buffer.is_null() {
+ (self.api.release_buffer)(buffer);
+ }
+ }
+ }
+ self.filter = std::ptr::null_mut();
+ self.color_buffer = std::ptr::null_mut();
+ self.albedo_buffer = std::ptr::null_mut();
+ self.normal_buffer = std::ptr::null_mut();
+ self.output_buffer = std::ptr::null_mut();
+ self.key = None;
+ }
+}
+
+impl Drop for OidnDenoiser {
+ fn drop(&mut self) {
+ self.close();
+ }
+}
+
+#[cfg(test)]
+mod tests {
+ use super::*;
+
+ #[test]
+ fn device_names_map_to_types_and_numbers_to_indices() {
+ assert_eq!(parse_device("cpu").unwrap(), DeviceChoice::Type(1));
+ assert_eq!(parse_device(" CUDA ").unwrap(), DeviceChoice::Type(3));
+ assert_eq!(parse_device("2").unwrap(), DeviceChoice::PhysicalIndex(2));
+ assert!(parse_device("tpu").is_err());
+ assert!(parse_device("-1").is_err());
+ }
+
+ #[test]
+ fn quality_names_map_to_oidn_values() {
+ assert_eq!(parse_quality("high").unwrap(), 6);
+ assert_eq!(parse_quality("fast").unwrap(), 4);
+ assert!(parse_quality("ultra").is_err());
+ }
+
+ #[test]
+ fn a_missing_library_names_the_path_and_the_fix() {
+ let error = OidnApi::open("definitely-not-an-oidn-library.so").err().expect("opening a missing library fails");
+ let message = error.reason.to_string();
+ assert!(message.contains("definitely-not-an-oidn-library"));
+ assert!(message.contains("npm run fetch"));
+ }
+
+ #[test]
+ fn image_lengths_are_checked() {
+ assert!(check_length("color", 12, 12).is_ok());
+ assert!(check_length("color", 11, 12).is_err());
+ }
+}
diff --git a/scripts/agent-native-trace.mjs b/scripts/agent-native-trace.mjs
index 0c058313..4e4b3adc 100644
--- a/scripts/agent-native-trace.mjs
+++ b/scripts/agent-native-trace.mjs
@@ -122,6 +122,40 @@ function atrousColor({ tracer, traced, width, height }) {
return withoutAlpha(filtered, width * height);
}
+// One in-process OIDN device per loaded denoiser package, kept for the life of the process so the second and later frames
+// skip device creation and the filter commit. `instance` is null when the package, the OIDN library or the addon cannot do it.
+const persistentOidnByPackage = new WeakMap();
+
+function persistentOidnFor({ tracer, denoiser }) {
+ if (typeof denoiser.createOidnDenoiser !== 'function' || typeof tracer.createNativeOidnDenoiser !== 'function') return { instance: null };
+ if (!persistentOidnByPackage.has(denoiser)) {
+ try {
+ persistentOidnByPackage.set(denoiser, { instance: denoiser.createOidnDenoiser({ createNative: tracer.createNativeOidnDenoiser }) });
+ } catch (error) {
+ persistentOidnByPackage.set(denoiser, { instance: null, note: error.message });
+ }
+ }
+ return persistentOidnByPackage.get(denoiser);
+}
+
+/**
+ * Runs OIDN on one frame: in the persistent in-process device when it is available, otherwise (or when that call fails)
+ * through the `oidnDenoise` tool. Resolves with the filtered colour and `{ mode, note }`; `mode` is "in-process" or "cli".
+ */
+export async function denoiseFrameWithOidn({ tracer, denoiser, width, height, color, albedo, normal }) {
+ const persistent = persistentOidnFor({ tracer, denoiser });
+ let note = persistent.note;
+ if (persistent.instance) {
+ try {
+ return { linear: await persistent.instance.denoise({ width, height, color, albedo, normal }), mode: 'in-process' };
+ } catch (error) {
+ note = error.message;
+ }
+ }
+ const linear = await denoiser.denoiseWithOidn({ width, height, color, albedo, normal });
+ return { linear, mode: 'cli', ...(note ? { note: `The in-process OIDN device was not used (${note}): the oidnDenoise tool ran instead.` } : {}) };
+}
+
/**
* Traces one frame the page exported and returns the PNG (base64) with the job report. `denoise` is "none", "wavelet",
* "atrous" (the tracer's GPU filter, which is also where a missing or failing OIDN lands) or "oidn"; `denoiser` is the
@@ -144,8 +178,9 @@ export async function traceFrameNative({ tracer, exported, width, height, sample
const denoiseStarted = performance.now();
if (denoise === 'oidn') {
try {
- linear = await denoiser.denoiseWithOidn({ width, height, color: features.color, albedo: features.albedo, normal: features.normal });
- Object.assign(report, { denoised: true, denoiser: 'oidn', oidnVersion: denoiser.OIDN_VERSION });
+ const filtered = await denoiseFrameWithOidn({ tracer, denoiser, width, height, color: features.color, albedo: features.albedo, normal: features.normal });
+ linear = filtered.linear;
+ Object.assign(report, { denoised: true, denoiser: 'oidn', oidnVersion: denoiser.OIDN_VERSION, oidnMode: filtered.mode, ...(filtered.note ? { denoiserNote: filtered.note } : {}) });
} catch (error) {
report.denoiserNote = `OIDN failed (${error.message}): the GPU a-trous filter ran instead.`;
denoise = 'atrous';
diff --git a/tests/denoise-oidn-persistent.test.js b/tests/denoise-oidn-persistent.test.js
new file mode 100644
index 00000000..0ac832cc
--- /dev/null
+++ b/tests/denoise-oidn-persistent.test.js
@@ -0,0 +1,163 @@
+import assert from 'node:assert/strict';
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import test from 'node:test';
+
+import { createOidnDenoiser, denoiseWithOidn, findOidnBinary, findOidnLibrary } from '../packages/denoise-oidn/index.mjs';
+import { createNativeOidnDenoiser, findNativeAddon } from '../packages/render-native/index.mjs';
+import { denoiseFrameWithOidn } from '../scripts/agent-native-trace.mjs';
+
+const LIBRARY_LAYOUTS = {
+ win32: { directory: 'bin', name: 'OpenImageDenoise.dll', tool: 'oidnDenoise.exe' },
+ darwin: { directory: 'lib', name: 'libOpenImageDenoise.2.dylib', tool: 'oidnDenoise' },
+ linux: { directory: 'lib', name: 'libOpenImageDenoise.so.2', tool: 'oidnDenoise' },
+};
+
+function withEnvironment(context, values) {
+ const saved = {};
+ for (const [name, value] of Object.entries(values)) {
+ saved[name] = process.env[name];
+ if (value === undefined) delete process.env[name];
+ else process.env[name] = value;
+ }
+ context.after(() => {
+ for (const [name, value] of Object.entries(saved)) {
+ if (value === undefined) delete process.env[name];
+ else process.env[name] = value;
+ }
+ });
+}
+
+function fakeNative(calls) {
+ return options => {
+ calls.push({ type: 'create', options });
+ return {
+ deviceSeconds: 0.25,
+ denoise(frame) {
+ calls.push({ type: 'denoise', width: frame.width, hasAlbedo: Boolean(frame.albedo) });
+ return { color: new Float32Array(frame.color).map(value => value * 2), recommitted: calls.length < 3, commitSeconds: 0.1, writeSeconds: 0.01, executeSeconds: 0.02, readSeconds: 0.01 };
+ },
+ close() { calls.push({ type: 'close' }); },
+ };
+ };
+}
+
+const FRAME = { width: 1, height: 2, color: new Float32Array([1, 2, 3, 4, 5, 6]), albedo: new Float32Array(6), normal: new Float32Array(6) };
+
+test('findOidnLibrary reads OIDN_LIBRARY_PATH and the release folder of the tool', context => {
+ const layout = LIBRARY_LAYOUTS[process.platform];
+ if (!layout) return context.skip('no official OIDN build for this platform');
+ const release = mkdtempSync(join(tmpdir(), '67js-oidn-layout-'));
+ context.after(() => rmSync(release, { recursive: true, force: true }));
+ mkdirSync(join(release, 'bin'), { recursive: true });
+ mkdirSync(join(release, layout.directory), { recursive: true });
+ writeFileSync(join(release, 'bin', layout.tool), '');
+ withEnvironment(context, { OIDN_LIBRARY_PATH: undefined, OIDN_DENOISE_PATH: join(release, 'bin', layout.tool) });
+ assert.equal(findOidnLibrary(), null);
+ writeFileSync(join(release, layout.directory, layout.name), '');
+ assert.equal(findOidnLibrary(), join(release, layout.directory, layout.name));
+ process.env.OIDN_LIBRARY_PATH = join(release, 'missing.so');
+ assert.equal(findOidnLibrary(), null);
+ process.env.OIDN_LIBRARY_PATH = join(release, layout.directory, layout.name);
+ assert.equal(findOidnLibrary(), join(release, layout.directory, layout.name));
+});
+
+test('createOidnDenoiser says what to pass or install, and passes the options to the native object', () => {
+ assert.throws(() => createOidnDenoiser({}), /createNative/);
+ assert.throws(() => createOidnDenoiser({ createNative: fakeNative([]), libraryPath: '' }), /npm run fetch/);
+ assert.throws(() => createOidnDenoiser({ createNative: fakeNative([]), libraryPath: 'oidn.so', device: 'tpu' }), /device "tpu" is unknown/);
+ const calls = [];
+ const denoiser = createOidnDenoiser({ createNative: fakeNative(calls), libraryPath: 'oidn.so', device: 'cuda', quality: 'balanced', cleanAux: true, threads: 4 });
+ assert.deepEqual(calls[0].options, { libraryPath: 'oidn.so', device: 'cuda', quality: 'balanced', cleanAux: true, threads: 4 });
+ assert.equal(denoiser.deviceSeconds, 0.25);
+ assert.equal(denoiser.lastTimings, null);
+ denoiser.close();
+ assert.equal(calls.at(-1).type, 'close');
+});
+
+test('a persistent denoiser resolves with the filtered pixels and keeps the timings apart', async () => {
+ const calls = [];
+ const denoiser = createOidnDenoiser({ createNative: fakeNative(calls), libraryPath: 'oidn.so' });
+ const filtered = await denoiser.denoise(FRAME);
+ assert.deepEqual([...filtered], [2, 4, 6, 8, 10, 12]);
+ assert.deepEqual(Object.keys(denoiser.lastTimings).sort(), ['commitSeconds', 'executeSeconds', 'readSeconds', 'recommitted', 'writeSeconds']);
+});
+
+test('createNativeOidnDenoiser asks for the library path before it loads anything', () => {
+ assert.throws(() => createNativeOidnDenoiser({}), /libraryPath/);
+ assert.throws(() => createNativeOidnDenoiser({ libraryPath: '' }), /libraryPath/);
+});
+
+test('a job frame uses one persistent device per package and the tool when it cannot', async () => {
+ const created = [];
+ const persistentPackage = {
+ createOidnDenoiser: options => {
+ created.push(options);
+ return { denoise: async frame => new Float32Array(frame.color) };
+ },
+ denoiseWithOidn: async () => { throw new Error('the tool must not run'); },
+ };
+ const tracer = { createNativeOidnDenoiser: () => ({}) };
+ const first = await denoiseFrameWithOidn({ tracer, denoiser: persistentPackage, ...FRAME });
+ const second = await denoiseFrameWithOidn({ tracer, denoiser: persistentPackage, ...FRAME });
+ assert.equal(first.mode, 'in-process');
+ assert.equal(second.mode, 'in-process');
+ assert.equal(created.length, 1);
+ assert.equal(created[0].createNative, tracer.createNativeOidnDenoiser);
+
+ const toolOnly = { denoiseWithOidn: async frame => frame.color };
+ const withoutPersistence = await denoiseFrameWithOidn({ tracer, denoiser: toolOnly, ...FRAME });
+ assert.deepEqual({ mode: withoutPersistence.mode, note: withoutPersistence.note }, { mode: 'cli', note: undefined });
+
+ const missingLibrary = { createOidnDenoiser: () => { throw new Error('The OIDN shared library is not installed'); }, denoiseWithOidn: async frame => frame.color };
+ const afterMissing = await denoiseFrameWithOidn({ tracer, denoiser: missingLibrary, ...FRAME });
+ assert.equal(afterMissing.mode, 'cli');
+ assert.match(afterMissing.note, /not installed.*oidnDenoise tool ran instead/);
+
+ const crashing = { createOidnDenoiser: () => ({ denoise: async () => { throw new Error('CUDA out of memory'); } }), denoiseWithOidn: async frame => frame.color };
+ const afterCrash = await denoiseFrameWithOidn({ tracer, denoiser: crashing, ...FRAME });
+ assert.equal(afterCrash.mode, 'cli');
+ assert.match(afterCrash.note, /CUDA out of memory/);
+
+ const tracerWithoutSupport = await denoiseFrameWithOidn({ tracer: {}, denoiser: { ...persistentPackage, denoiseWithOidn: async frame => frame.color }, ...FRAME });
+ assert.equal(tracerWithoutSupport.mode, 'cli');
+});
+
+const skipWithoutLibrary = !findOidnLibrary() || !findOidnBinary() || !findNativeAddon() ? 'needs the OIDN release (npm run fetch) and the built render-native addon' : false;
+
+function noisyFrame(width, height) {
+ const pixels = width * height * 3;
+ const color = new Float32Array(pixels);
+ const albedo = new Float32Array(pixels).fill(0.5);
+ const normal = new Float32Array(pixels);
+ let state = 7;
+ for (let index = 0; index < pixels; index++) {
+ state = (Math.imul(state, 1664525) + 1013904223) >>> 0;
+ color[index] = 0.5 + state / 4294967296;
+ if (index % 3 === 1) normal[index] = 1;
+ }
+ return { width, height, color, albedo, normal };
+}
+
+test('the in-process device matches the tool and repeats exactly on the CPU', { skip: skipWithoutLibrary }, async () => {
+ const frame = noisyFrame(48, 32);
+ const denoiser = createOidnDenoiser({ createNative: createNativeOidnDenoiser, device: 'cpu' });
+ try {
+ const first = await denoiser.denoise(frame);
+ assert.equal(denoiser.lastTimings.recommitted, true);
+ const warm = await denoiser.denoise(frame);
+ assert.equal(denoiser.lastTimings.recommitted, false);
+ assert.deepEqual(warm, first);
+ const viaTool = await denoiseWithOidn({ ...frame, device: 'cpu' });
+ let largest = 0;
+ for (let index = 0; index < warm.length; index++) largest = Math.max(largest, Math.abs(warm[index] - viaTool[index]));
+ assert.ok(largest < 1e-4, `in-process and tool differ by ${largest}`);
+ await denoiser.denoise(noisyFrame(16, 16));
+ assert.equal(denoiser.lastTimings.recommitted, true);
+ await assert.rejects(denoiser.denoise({ ...frame, color: new Float32Array(3) }), /color/);
+ } finally {
+ denoiser.close();
+ }
+ await assert.rejects(denoiser.denoise(frame), /closed/);
+});