3D engine that AI agents drive
// Hardware ray traced stills for 67js: loads the native addon built by `npm run build` and traces a packed scene on the
// GPU with Vulkan ray queries. The addon is not in this package; without it `findNativeAddon()` returns null.
import { existsSync } from 'node:fs';
import { createRequire } from 'node:module';
import { dirname, join } from 'node:path';
import { fileURLToPath } from 'node:url';
import {
FORMAT_V2_MAGIC,
FORMAT_V2_VERSION,
STRUCT_STRIDES_V2,
KERNEL_FLAG_USE_LIGHT_TREE,
KERNEL_FLAG_WHITE_NOISE_SAMPLER,
KERNEL_FLAG_PATH_REGENERATION,
validatePathRegenerationOption,
resolveSamplingOptions,
resolveUseLightTree,
KERNEL_PARAMS_V2_FILTER_GLOSSY_BYTE_OFFSET,
KERNEL_PARAMS_V2_FILTER_TYPE_BYTE_OFFSET,
KERNEL_PARAMS_V2_FILTER_WIDTH_BYTE_OFFSET,
KERNEL_PARAMS_V2_KERNEL_FLAGS_BYTE_OFFSET,
filterTypeCode,
resolveFilterParameters,
buildNativeInputV2,
packMaterialRecordV2,
upgradeNativeInputV1ToV2,
validateImagePixelCount,
validateMaxSeconds,
validatePackOptions,
validateDenoiseOption,
} from './pack-input-v2.mjs';
export { buildNativeInput, buildNativeTexelInput } from './pack-input.mjs';
export {
FORMAT_V2_MAGIC,
FORMAT_V2_VERSION,
STRUCT_STRIDES_V2,
KERNEL_PARAMS_V2_FILTER_GLOSSY_BYTE_OFFSET,
buildNativeInputV2,
packMaterialRecordV2,
upgradeNativeInputV1ToV2,
};
const PACKAGE_DIRECTORY = dirname(fileURLToPath(import.meta.url));
const ADDON_PATH = join(PACKAGE_DIRECTORY, 'build', 'render-native.node');
const VALID_KERNELS = new Set(['legacy', 'cycles']);
/** The path of the built addon, or null when `npm run build` has not run. */
export function findNativeAddon() {
return existsSync(ADDON_PATH) ? ADDON_PATH : null;
}
/**
* Resolves and validates the native kernel name from `kernel`, falling back to `JS67_NATIVE_KERNEL` and `'legacy'`.
*/
export function resolveNativeKernel(kernel) {
const envKernel = process.env.JS67_NATIVE_KERNEL;
const selectedKernel = kernel !== undefined
? kernel
: (envKernel !== undefined && envKernel !== '' ? envKernel : 'legacy');
if (typeof selectedKernel !== 'string' || !VALID_KERNELS.has(selectedKernel)) {
throw new Error(
`Invalid native kernel ${JSON.stringify(selectedKernel)}: pass "legacy" or "cycles" in options.kernel or JS67_NATIVE_KERNEL.`
);
}
return selectedKernel;
}
// The `cycles` kernel starts a pixel's next sample as soon as a path ends unless the caller passes `pathRegeneration: false`.
const DEFAULT_PATH_REGENERATION = true;
/**
* Traces the input on the GPU and resolves linear RGBA float data (`rgba`, width * height * 4, rows from the top, the
* average of `samples` paths) with the adapter name and timings in seconds. `maxSeconds` makes the trace fail once it has
* run that long. `kernel` selects `"legacy"` (default) or `"cycles"` (falling back to `JS67_NATIVE_KERNEL` when omitted).
*/
export function traceNative(input, options = {}) {
validatePackOptions(options, 'traceNative', true);
resolveSamplingOptions(options, 'traceNative');
validatePathRegenerationOption(options.pathRegeneration, 'traceNative');
const { width, height, samples, maxSeconds, kernel, samplesPerDispatch, bootstrapKernel, denoise } = options;
const selectedKernel = resolveNativeKernel(kernel);
const addon = loadAddon();
if (selectedKernel === 'legacy') {
if (denoise === 'atrous') {
throw new TypeError('traceNative: `denoise: "atrous"` filters the Cycles kernel result; pass kernel "cycles", or call denoiseAtrous with the traced guide buffers.');
}
if (input?.schemaVersion === FORMAT_V2_VERSION) {
throw new TypeError(
'Cannot pass a FORMAT-v2 scene input to kernel "legacy": pass kernel "cycles" or build a v1 input with buildNativeInput (an instanced scene needs kernel "cycles"; build it without { instancing: true } for kernel "legacy").'
);
}
return addon.traceScene(input, { width, height, samples, maxSeconds, kernel: selectedKernel });
}
const v2Input = prepareCyclesInput(input, options);
return addon.traceSceneCycles(v2Input, {
width,
height,
samples,
samplesPerDispatch,
maxSeconds,
bootstrapKernel,
denoise,
});
}
/**
* Filters a traced image with the edge-avoiding a-trous wavelet filter on the GPU (Dammertz 2010 with SVGF's variance
* guidance, spatial only). `rgba` holds four floats per pixel; `albedo`, `normal` (any length, zero where nothing was
* hit), `depth` and `variance` are the guide buffers `traceNative` returns. The result is smoothed and biased: it is not
* a converged image. Returns `{ rgba, compileSeconds, uploadSeconds, gpuSeconds, readbackSeconds }`.
*/
export function denoiseAtrous({ width, height, rgba, albedo, normal, depth, variance }) {
const pixelCount = width * height;
validateImagePixelCount(width, height, 'denoiseAtrous');
const planes = { rgba: [rgba, 4], albedo: [albedo, 3], normal: [normal, 3], depth: [depth, 1], variance: [variance, 1] };
for (const [name, [plane, floatsPerPixel]] of Object.entries(planes)) {
if (!(plane instanceof Float32Array) || plane.length !== pixelCount * floatsPerPixel) {
throw new TypeError(`denoiseAtrous: \`${name}\` must be a Float32Array of ${pixelCount * floatsPerPixel} floats for a ${width}x${height} image.`);
}
}
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;
}
// A packed input already carries its filter; explicit options replace it. A new type without a width gets that type's
// default width, as the packer does; a width alone keeps the packed type.
// Exported for tests; not part of the public API.
export function withFilterOptions(kernelParams, options) {
const patchedParams = new Uint8Array(kernelParams);
const view = new DataView(patchedParams.buffer, patchedParams.byteOffset, patchedParams.byteLength);
const requestedType = options.filterType ?? options.pixelFilter;
const filterType = requestedType !== undefined
? filterTypeCode(requestedType)
: view.getUint32(KERNEL_PARAMS_V2_FILTER_TYPE_BYTE_OFFSET, true);
const filterWidth = options.filterWidth !== undefined || requestedType !== undefined
? resolveFilterParameters({ filterType, filterWidth: options.filterWidth }).filterWidth
: view.getFloat32(KERNEL_PARAMS_V2_FILTER_WIDTH_BYTE_OFFSET, true);
view.setUint32(KERNEL_PARAMS_V2_FILTER_TYPE_BYTE_OFFSET, filterType, true);
view.setFloat32(KERNEL_PARAMS_V2_FILTER_WIDTH_BYTE_OFFSET, filterWidth, true);
return patchedParams;
}
function hasLightTreeEmitterTables(v2Input) {
return Boolean(v2Input.lightTreeEmitters && v2Input.lightToTree && v2Input.lightTreeEmitterCount !== undefined);
}
// Exported for tests; not part of the public API.
export function withLightSamplingFlag(v2Input, lightSampling) {
const patchedParams = new Uint8Array(v2Input.kernelParams);
const view = new DataView(patchedParams.buffer, patchedParams.byteOffset, patchedParams.byteLength);
const flags = view.getUint32(KERNEL_PARAMS_V2_KERNEL_FLAGS_BYTE_OFFSET, true);
const emitterCount = (v2Input.lightCount ?? 0) + (v2Input.emissiveTriangleCount ?? 0);
let lightTreeNodeCount = v2Input.lightTreeNodeCount ?? 0;
if (lightTreeNodeCount > 0 && !hasLightTreeEmitterTables(v2Input)) {
if (lightSampling === 'tree') {
throw new TypeError(
'traceNative: lightSampling "tree" needs the emitter tables (lightTreeEmitters, lightTreeEmitterCount, lightToTree), which this packed FORMAT-v2 input lacks. Repack the scene with buildNativeInputV2.'
);
}
lightTreeNodeCount = 0;
}
const useTree = resolveUseLightTree(lightSampling, emitterCount, lightTreeNodeCount);
const patchedFlags = useTree
? (flags | KERNEL_FLAG_USE_LIGHT_TREE) >>> 0
: (flags & ~KERNEL_FLAG_USE_LIGHT_TREE) >>> 0;
view.setUint32(KERNEL_PARAMS_V2_KERNEL_FLAGS_BYTE_OFFSET, patchedFlags, true);
return patchedParams;
}
function withSamplerFlag(kernelParams, sampler) {
const patchedParams = new Uint8Array(kernelParams);
const view = new DataView(patchedParams.buffer, patchedParams.byteOffset, patchedParams.byteLength);
const flags = view.getUint32(KERNEL_PARAMS_V2_KERNEL_FLAGS_BYTE_OFFSET, true);
const patchedFlags = sampler === 'white'
? (flags | KERNEL_FLAG_WHITE_NOISE_SAMPLER) >>> 0
: (flags & ~KERNEL_FLAG_WHITE_NOISE_SAMPLER) >>> 0;
view.setUint32(KERNEL_PARAMS_V2_KERNEL_FLAGS_BYTE_OFFSET, patchedFlags, true);
return patchedParams;
}
/**
* Builds the FORMAT-v2 input of the `cycles` kernel from a v1 or v2 input and the trace options, patching the kernel flags
* the options set. Exported for tests; not part of the public API.
*/
export function prepareCyclesInput(input, options = {}) {
if (input?.schemaVersion === FORMAT_V2_VERSION) {
return { ...input, kernelParams: patchedCyclesKernelParams(input, input.kernelParams, options, 'traceNative') };
}
resolveSamplingOptions(options, 'traceNative');
const upgradedInput = upgradeNativeInputV1ToV2(input, options);
const pathRegeneration = options.pathRegeneration ?? DEFAULT_PATH_REGENERATION;
return { ...upgradedInput, kernelParams: withPathRegenerationFlag(upgradedInput.kernelParams, pathRegeneration) };
}
// Exported for tests; not part of the public API.
export function withPathRegenerationFlag(kernelParams, pathRegeneration) {
const patchedParams = new Uint8Array(kernelParams);
const view = new DataView(patchedParams.buffer, patchedParams.byteOffset, patchedParams.byteLength);
const flags = view.getUint32(KERNEL_PARAMS_V2_KERNEL_FLAGS_BYTE_OFFSET, true);
const patchedFlags = pathRegeneration
? (flags | KERNEL_FLAG_PATH_REGENERATION) >>> 0
: (flags & ~KERNEL_FLAG_PATH_REGENERATION) >>> 0;
view.setUint32(KERNEL_PARAMS_V2_KERNEL_FLAGS_BYTE_OFFSET, patchedFlags, true);
return patchedParams;
}
function buildProbeKernelParams({ width, height, mode, seed, sampleOffset, wo, frontFace, materialCount, textureCount }) {
const buffer = new ArrayBuffer(STRUCT_STRIDES_V2.kernelParams);
const f32 = new Float32Array(buffer);
const u32 = new Uint32Array(buffer);
const length = Math.hypot(wo[0], wo[1], wo[2]);
if (!(length > 1e-12) || !wo.every(Number.isFinite)) {
throw new RangeError('probeCyclesLobe option `wo` must be a non-zero finite 3D vector.');
}
u32[0] = FORMAT_V2_MAGIC;
u32[1] = FORMAT_V2_VERSION;
u32[2] = width >>> 0;
u32[3] = height >>> 0;
u32[4] = (sampleOffset ?? 0) >>> 0;
u32[5] = 1;
u32[6] = 1;
u32[7] = (seed ?? 1) >>> 0;
u32[8] = (mode ?? 0) >>> 0;
u32[23] = materialCount >>> 0;
u32[27] = textureCount >>> 0;
f32[31] = frontFace === false ? -1.0 : 1.0;
f32[32] = wo[0] / length;
f32[33] = wo[1] / length;
f32[34] = wo[2] / length;
f32[35] = 1e30;
f32[72] = 1.0;
return new Uint8Array(buffer);
}
/**
* Dispatches entry point `"test_lobe_samples"` on the assembled Cycles shader and returns the raw un-divided
* `Float32Array` of all 4 `film_accumulation` planes (`4 * width * height * 4` floats).
*/
export function probeCyclesLobe(options = {}) {
const width = options.width ?? 512;
const height = options.height ?? 512;
if (!Number.isInteger(width) || width < 1 || width > 16384 || !Number.isInteger(height) || height < 1 || height > 16384) {
throw new RangeError(`probeCyclesLobe requires integer \`width\` and \`height\` in [1, 16384]; got width=${width}, height=${height}.`);
}
validateImagePixelCount(width, height, 'probeCyclesLobe');
validateMaxSeconds(options.maxSeconds, 'probeCyclesLobe');
const wo = options.wo ?? [0, 0, 1];
if (!Array.isArray(wo) && !ArrayBuffer.isView(wo) || wo.length !== 3) {
throw new TypeError('probeCyclesLobe option `wo` must hold 3 numbers.');
}
let materials;
if (options.materialBytes !== undefined) {
if (!(options.materialBytes instanceof Uint8Array) || options.materialBytes.byteLength < STRUCT_STRIDES_V2.material || options.materialBytes.byteLength % STRUCT_STRIDES_V2.material !== 0) {
throw new TypeError(`probeCyclesLobe option \`materialBytes\` must be a Uint8Array of a positive multiple of ${STRUCT_STRIDES_V2.material} bytes.`);
}
materials = options.materialBytes;
} else {
materials = packMaterialRecordV2(options.material ?? {}, null).bytes;
}
const materialCount = materials.byteLength / STRUCT_STRIDES_V2.material;
const textureDescriptors = options.textureDescriptors;
const textureCount = textureDescriptors ? Math.floor(textureDescriptors.byteLength / STRUCT_STRIDES_V2.textureDescriptor) : 0;
const kernelParams = options.kernelParams instanceof Uint8Array
? options.kernelParams
: buildProbeKernelParams({
width,
height,
mode: options.mode ?? 0,
seed: options.seed ?? 1,
sampleOffset: options.sampleOffset,
wo,
frontFace: options.frontFace ?? true,
materialCount,
textureCount,
});
return loadAddon().probeCyclesLobe({
width,
height,
kernelParams,
materials,
textureDescriptors,
textureTexels: options.textureTexels,
maxSeconds: options.maxSeconds,
bootstrapKernel: options.bootstrapKernel,
});
}
/**
* The light bake: traces `samples` cosine weighted paths from every texel of `texels` (`count`, `points`, `normals`) and
* returns the mean `radiance` (three floats per texel) and the share of first rays that `escaped`. The input comes from
* `buildNativeTexelInput`.
*/
export function traceNativeTexels(input, texels, { samples, maxSeconds }) {
validateMaxSeconds(maxSeconds, 'traceNativeTexels');
return loadAddon().traceTexels(input, texels, { samples, maxSeconds });
}
function loadAddon() {
const addonPath = findNativeAddon();
if (!addonPath) throw new Error('The native tracer is not built. Run `npm run build` in packages/render-native.');
return createRequire(import.meta.url)(addonPath);
}
// ---- Persistent session (issue 896) ----
function requireSessionKernelParams(kernelParams, callerName) {
if (!(kernelParams instanceof Uint8Array) || kernelParams.byteLength !== STRUCT_STRIDES_V2.kernelParams) {
throw new TypeError(
`${callerName}: \`kernelParams\` must be a Uint8Array of ${STRUCT_STRIDES_V2.kernelParams} bytes (the KernelParamsV2 block of buildNativeInputV2).`
);
}
}
function requireCyclesKernelOption(kernel, callerName) {
if (kernel !== undefined && resolveNativeKernel(kernel) !== 'cycles') {
throw new TypeError(`${callerName}: a native session runs the "cycles" kernel only; got kernel "${kernel}". Use traceNative for the legacy kernel.`);
}
}
function mergeDefinedOptions(sessionOptions, renderOptions) {
const merged = { ...sessionOptions };
for (const [name, value] of Object.entries(renderOptions)) {
if (value !== undefined) merged[name] = value;
}
return merged;
}
// The kernel parameters of a FORMAT-v2 input after the sampling, filter and light options of `options`, the one place the patches live (traceNative and sessions share it), in a fixed
// order.
function patchedCyclesKernelParams(v2Input, kernelParams, options, callerName) {
const { sampler, lightSampling } = resolveSamplingOptions(options, callerName);
validatePathRegenerationOption(options.pathRegeneration, callerName);
let patchedParams = new Uint8Array(kernelParams);
const explicitFilterGlossy = options.filterGlossy ?? options.blurGlossy;
if (explicitFilterGlossy !== undefined) {
const rawFilterGlossy = Number(explicitFilterGlossy);
const resolvedFilterGlossy = Number.isFinite(rawFilterGlossy) && rawFilterGlossy > 0 ? rawFilterGlossy : 0.0;
new DataView(patchedParams.buffer, patchedParams.byteOffset, patchedParams.byteLength).setFloat32(KERNEL_PARAMS_V2_FILTER_GLOSSY_BYTE_OFFSET, resolvedFilterGlossy, true);
}
if (hasFilterOptions(options)) patchedParams = withFilterOptions(patchedParams, options);
if (sampler !== undefined) patchedParams = withSamplerFlag(patchedParams, sampler);
patchedParams = withPathRegenerationFlag(patchedParams, options.pathRegeneration ?? DEFAULT_PATH_REGENERATION);
if (lightSampling !== undefined) patchedParams = withLightSamplingFlag({ ...v2Input, kernelParams: patchedParams }, lightSampling);
return patchedParams;
}
// Exported for tests; not part of the public API.
export function resolveSessionCreation(input, options, callerName = 'createNativeSession') {
if (input === null || typeof input !== 'object') {
throw new TypeError(`${callerName}: \`input\` must be a FORMAT-v2 input object from buildNativeInputV2.`);
}
if (input.schemaVersion !== FORMAT_V2_VERSION) {
throw new TypeError(
`${callerName}: \`input.schemaVersion\` must be ${FORMAT_V2_VERSION} (a FORMAT-v2 input from buildNativeInputV2); got ${JSON.stringify(input.schemaVersion)}. Convert a v1 input with upgradeNativeInputV1ToV2.`
);
}
requireSessionKernelParams(input.kernelParams, callerName);
if (options === null || typeof options !== 'object') {
throw new TypeError(`${callerName}: \`options\` must be an object.`);
}
requireCyclesKernelOption(options.kernel, callerName);
validatePackOptions(options, callerName);
return { ...input, kernelParams: patchedCyclesKernelParams(input, input.kernelParams, options, callerName) };
}
// Exported for tests; not part of the public API.
export function resolveSessionFrame(sessionInput, sessionOptions, renderOptions) {
if (renderOptions === null || typeof renderOptions !== 'object') {
throw new TypeError('NativeSession.render: `renderOptions` must be an object.');
}
const options = mergeDefinedOptions(sessionOptions, renderOptions);
requireCyclesKernelOption(options.kernel, 'NativeSession.render');
validatePackOptions(options, 'NativeSession.render', true);
let baseKernelParams = sessionInput.kernelParams;
if (renderOptions.kernelParams !== undefined) {
requireSessionKernelParams(renderOptions.kernelParams, 'NativeSession.render');
baseKernelParams = renderOptions.kernelParams;
}
const kernelParams = patchedCyclesKernelParams(sessionInput, baseKernelParams, options, 'NativeSession.render');
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 = {}) {
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, 'NativeSession.update');
const changedTables = planNativeSessionUpdate(heldInput, nextInput);
const report = nativeSession.update({ kernelParams: nextInput.kernelParams, ...changedTables });
heldInput = nextInput;
return report;
},
close() {
if (closed) return;
closed = true;
nativeSession.close();
},
};
}
/**
* Keeps a FORMAT-v2 scene on the GPU between frames (the `cycles` kernel only). `render(renderOptions)` takes what
* `traceNative` takes (`width`, `height`, `samples`, `samplesPerDispatch`, `maxSeconds`, `denoise`, the sampling and filter
* options) and returns what it returns plus `pipelineReused`, `accelerationReused`, `filmReused` and `frameIndex`. A later frame
* with the same scene compiles no shader (while the specialized kernel text is unchanged) and builds no acceleration structure; a
* 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);
const addon = loadAddon();
if (typeof addon.NativeCyclesSession !== 'function') {
throw new Error('The built native addon has no session support. Run `npm run build` in packages/render-native.');
}
return wrapNativeSession(new addon.NativeCyclesSession(sessionInput), sessionInput, options);
}