3D engine that AI agents drive
Sample Cook with Sobol-Burley and pick lights through a light tree (#895)
Nguyen Xuan Ana8b7bb515e66
diff --git a/bench/cycles-parity/make-many-lights-scene.mjs b/bench/cycles-parity/make-many-lights-scene.mjsnew file mode 100644index 00000000..c0cda724--- /dev/null+++ b/bench/cycles-parity/make-many-lights-scene.mjs@@ -0,0 +1,41 @@+// Writes a copy of an exported scene with many small point lights spread through the room, for light tree measurements.+// The lights go in `environment.manyPointLights`, which trace-native.mjs adds after the scene is built: a trace scene itself+// takes at most 32 lights because each light owns a light-link bit.+// node bench/cycles-parity/make-many-lights-scene.mjs <sceneJsonPath> <outputJsonPath> [--count 500] [--seed 7]+import { readFile, writeFile } from 'node:fs/promises';+import { resolve } from 'node:path';++function readFlagValue(argumentList, flagName, fallbackValue) {+ const flagIndex = argumentList.indexOf(flagName);+ return flagIndex === -1 ? fallbackValue : argumentList[flagIndex + 1];+}++function createRandom(seed) {+ let state = seed >>> 0;+ return () => {+ state = (state + 0x6d2b79f5) >>> 0;+ let mixed = Math.imul(state ^ (state >>> 15), 1 | state);+ mixed = (mixed + Math.imul(mixed ^ (mixed >>> 7), 61 | mixed)) ^ mixed;+ return ((mixed ^ (mixed >>> 14)) >>> 0) / 4294967296;+ };+}++const argumentList = process.argv.slice(2);+if (argumentList.length < 2) {+ throw new RangeError('Usage: node bench/cycles-parity/make-many-lights-scene.mjs <sceneJsonPath> <outputJsonPath> [--count 500] [--seed 7]');+}+const lightCount = Number(readFlagValue(argumentList, '--count', 500));+const nextRandom = createRandom(Number(readFlagValue(argumentList, '--seed', 7)));+const description = JSON.parse(await readFile(resolve(argumentList[0]), 'utf8'));+const totalIntensity = 12;+description.id = `${description.id}-${lightCount}-lights`;+description.environment.pointLights = [];+description.environment.manyPointLights = Array.from({ length: lightCount }, () => ({+ position: [(nextRandom() - 0.5) * 7.4, 0.3 + nextRandom() * 2.7, (nextRandom() - 0.5) * 7.4],+ color: [0.6 + 0.4 * nextRandom(), 0.6 + 0.4 * nextRandom(), 0.6 + 0.4 * nextRandom()],+ intensity: (totalIntensity / lightCount) * (0.25 + 1.5 * nextRandom()),+ radius: 0.03,+ castShadow: true,+}));+await writeFile(resolve(argumentList[1]), JSON.stringify(description));+console.log(JSON.stringify({ outputPath: resolve(argumentList[1]), lightCount }));diff --git a/bench/cycles-parity/measure-sampler-noise.py b/bench/cycles-parity/measure-sampler-noise.pynew file mode 100644index 00000000..55e24c73--- /dev/null+++ b/bench/cycles-parity/measure-sampler-noise.py@@ -0,0 +1,111 @@+"""Measure relMSE of Cook's sampler or light selection at equal sample counts against a high-sample reference.++ uv run --no-project --with numpy python bench/cycles-parity/measure-sampler-noise.py <sceneJson> <outputDirectory> \+ [--compare sampler|light-tree] [--samples 16,64,256] [--seeds 1,2] [--reference-samples 2048] [--width 480] [--height 270]++--compare sampler (default) pits the PCG hash against Sobol-Burley. --compare light-tree pits the cumulative-weight light pick+against the light tree, both on Sobol-Burley, and also reports sampling seconds and the time each needs to reach the error+the other reaches (interpolated on a log-log line through the sample ladder).+Every render goes through gpu-lock. The reference uses the first variant with its own seed, so no candidate shares random+numbers with it. Prints one JSON object.+"""+import json+import math+import os+import subprocess+import sys++import numpy++sys.stdout.reconfigure(encoding="utf-8", errors="replace")++REPOSITORY_ROOT = os.path.abspath(os.path.join(os.path.dirname(__file__), "..", ".."))+GPU_LOCK = os.path.expanduser("~/.agents/tools/gpu-lock.sh")+REL_MSE_EPSILON = 1e-2+REFERENCE_SEED = 9001+VARIANT_FLAGS = {+ "sampler": {"pcg": ["--sampler", "pcg"], "sobol": ["--sampler", "sobol"]},+ "light-tree": {+ "off": ["--sampler", "sobol", "--light-tree", "off"],+ "on": ["--sampler", "sobol", "--light-tree", "on"],+ },+}+++def read_flag(argument_list, flag_name, fallback):+ if flag_name not in argument_list:+ return fallback+ return argument_list[argument_list.index(flag_name) + 1]+++def render(scene_json, output_prefix, variant_flags, samples, seed, width, height, weight):+ environment = dict(os.environ, GPU_LOCK_WEIGHT=weight)+ command = [+ "bash", GPU_LOCK, "node", os.path.join(REPOSITORY_ROOT, "bench", "cycles-parity", "trace-native.mjs"),+ scene_json, output_prefix, "--kernel", "cycles", "--samples", str(samples),+ "--seed", str(seed), "--width", str(width), "--height", str(height), *variant_flags,+ ]+ subprocess.run(command, check=True, env=environment, stdout=subprocess.DEVNULL)+ with open(output_prefix + ".json", encoding="utf-8") as handle:+ report = json.load(handle)+ return numpy.load(output_prefix + ".npy"), report+++def relative_mse(reference_rgb, candidate_rgb):+ denominator = reference_rgb ** 2 + REL_MSE_EPSILON+ return float((((candidate_rgb - reference_rgb) ** 2) / denominator).mean())+++def seconds_to_reach(error_target, points):+ """points: (samplingSeconds, relMse) per sample count, error falling as time rises. Log-log interpolation or extrapolation."""+ log_seconds = numpy.log([seconds for seconds, _ in points])+ log_errors = numpy.log([error for _, error in points])+ slope, intercept = numpy.polyfit(log_errors, log_seconds, 1)+ return float(math.exp(slope * math.log(error_target) + intercept))+++def main():+ argument_list = sys.argv[1:]+ scene_json, output_directory = os.path.abspath(argument_list[0]), os.path.abspath(argument_list[1])+ comparison = read_flag(argument_list, "--compare", "sampler")+ sample_counts = [int(value) for value in read_flag(argument_list, "--samples", "16,64,256").split(",")]+ seeds = [int(value) for value in read_flag(argument_list, "--seeds", "1,2").split(",")]+ reference_samples = int(read_flag(argument_list, "--reference-samples", "2048"))+ width = int(read_flag(argument_list, "--width", "480"))+ height = int(read_flag(argument_list, "--height", "270"))+ variants = VARIANT_FLAGS[comparison]+ baseline_name, candidate_name = list(variants)+ os.makedirs(output_directory, exist_ok=True)+ reference_rgb, _ = render(+ scene_json, os.path.join(output_directory, "reference"), variants[baseline_name], reference_samples, REFERENCE_SEED, width, height, "heavy",+ )+ results = {}+ ladders = {baseline_name: [], candidate_name: []}+ for samples in sample_counts:+ for name, flags in variants.items():+ errors, seconds = [], []+ for seed in seeds:+ prefix = os.path.join(output_directory, f"{name}-{samples}-{seed}")+ candidate_rgb, report = render(scene_json, prefix, flags, samples, seed, width, height, "light")+ errors.append(relative_mse(reference_rgb, candidate_rgb))+ seconds.append(report["samplingSeconds"])+ mean_error, mean_seconds = float(numpy.mean(errors)), float(numpy.mean(seconds))+ results[f"{name}@{samples}"] = {"relMse": mean_error, "samplingSeconds": mean_seconds, "perSeed": errors}+ ladders[name].append((mean_seconds, mean_error))+ baseline = results[f"{baseline_name}@{samples}"]["relMse"]+ candidate = results[f"{candidate_name}@{samples}"]["relMse"]+ results[f"{candidate_name}@{samples}"]["dropVersus" + baseline_name.capitalize()] = 1.0 - candidate / baseline+ if comparison == "light-tree":+ mean_ratio = float(numpy.mean([+ numpy.load(os.path.join(output_directory, f"{candidate_name}-{sample_counts[-1]}-{seeds[0]}.npy")).mean()+ / numpy.load(os.path.join(output_directory, f"{baseline_name}-{sample_counts[-1]}-{seeds[0]}.npy")).mean()+ ]))+ target_error = ladders[baseline_name][-1][1]+ results["meanImageRatioTreeOverUniform"] = mean_ratio+ results["targetRelMse"] = target_error+ results["secondsToTargetWithout"] = ladders[baseline_name][-1][0]+ results["secondsToTargetWith"] = seconds_to_reach(target_error, ladders[candidate_name])+ print(json.dumps(results, indent=2))+++main()diff --git a/bench/cycles-parity/trace-native.mjs b/bench/cycles-parity/trace-native.mjsindex ac56420f..f62cdcac 100644--- a/bench/cycles-parity/trace-native.mjs+++ b/bench/cycles-parity/trace-native.mjs@@ -41,6 +41,14 @@ function parseNumberOption(argumentList, flagName, fallbackValue, minimumValue)return parsed;}+function parseChoiceOption(argumentList, flagName, allowedValues, fallbackValue) {+ const value = String(readFlagValue(argumentList, flagName, fallbackValue));+ if (!allowedValues.includes(value)) {+ throw new RangeError(`Option ${flagName} must be one of ${allowedValues.join(', ')}, got "${value}".`);+ }+ return value;+}+function parseKernelOption(argumentList) {const kernel = String(readFlagValue(argumentList, '--kernel', 'legacy'));if (!SUPPORTED_KERNELS.has(kernel)) {@@ -59,7 +67,7 @@ function parseFilterTypeOption(argumentList) {function parseTraceArguments(argumentList) {if (argumentList.length < 2 || argumentList[0].startsWith('--') || argumentList[1].startsWith('--')) {- throw new RangeError('Usage: node bench/cycles-parity/trace-native.mjs <sceneJsonPath> <outputPrefix> [--kernel legacy|cycles] [--samples 256] [--bounces 8] [--seed 1] [--width 960] [--height 540] [--filter-type box|blackman-harris] [--filter-width 1.0] [--clamp-direct 0] [--clamp-indirect 0] [--firefly-clamp 1e9] [--noise-threshold 0]');+ throw new RangeError('Usage: node bench/cycles-parity/trace-native.mjs <sceneJsonPath> <outputPrefix> [--kernel legacy|cycles] [--samples 256] [--bounces 8] [--seed 1] [--width 960] [--height 540] [--sampler sobol|pcg] [--light-tree auto|on|off] [--filter-type box|blackman-harris] [--filter-width 1.0] [--clamp-direct 0] [--clamp-indirect 0] [--firefly-clamp 1e9] [--noise-threshold 0]');}return {sceneJsonPath: resolve(argumentList[0]),@@ -71,6 +79,8 @@ function parseTraceArguments(argumentList) {bounces: parseIntegerOption(argumentList, '--bounces', 8, 0),seed: parseIntegerOption(argumentList, '--seed', 1, 0),filterType: parseFilterTypeOption(argumentList),+ sampler: parseChoiceOption(argumentList, '--sampler', ['sobol', 'pcg'], 'sobol'),+ lightTree: parseChoiceOption(argumentList, '--light-tree', ['auto', 'on', 'off'], 'auto'),filterWidth: parseNumberOption(argumentList, '--filter-width', 1.0, 0.01),clampDirect: parseNumberOption(argumentList, '--clamp-direct', 0, 0),clampIndirect: parseNumberOption(argumentList, '--clamp-indirect', 0, 0),@@ -115,11 +125,15 @@ async function runCli() {const buildStarted = performance.now();const traceSource = await reconstructTraceSceneSource(description);const traceScene = buildTraceScene(traceSource.parts, traceSource.environment);+ for (const light of description.environment?.manyPointLights ?? []) {+ traceScene.lights.points.push({ bit: -1, range: 0, ...light });+ }const camera = createCamera(traceSource.camera, options.width, options.height);const samplesPerDispatch = options.samplesPerDispatch !== undefined? options.samplesPerDispatch: (options.noiseThreshold > 0 ? 8 : undefined);- const nativeInput = packSceneForKernel(traceScene, camera, { ...options, samplesPerDispatch, parts: traceSource.parts });+ const useLightTree = { auto: undefined, on: true, off: false }[options.lightTree];+ const nativeInput = packSceneForKernel(traceScene, camera, { ...options, useLightTree, samplesPerDispatch, parts: traceSource.parts });const sceneBuildSeconds = (performance.now() - buildStarted) / 1000;const traced = renderNative.traceNative(nativeInput, {width: options.width,@@ -156,6 +170,8 @@ async function runCli() {samplesPerDispatch: traced.samplesPerDispatch ?? null,bounces: options.bounces,seed: options.seed,+ sampler: options.sampler,+ lightTree: options.lightTree,filterType: options.filterType,filterWidth: options.filterWidth,clampDirect: options.clampDirect,diff --git a/changes/895-cook-sampling.md b/changes/895-cook-sampling.mdnew file mode 100644index 00000000..206f6e18--- /dev/null+++ b/changes/895-cook-sampling.md@@ -0,0 +1 @@+- Cook samples with an Owen-scrambled Sobol sequence (Burley's hash scrambling) instead of white-noise hashes, picks lights through a light tree over the analytic lights and the emissive triangles once a kind has more than 8 emitters, and takes `sampler: 'pcg'` and `useLightTree` options to switch either back (#895)diff --git a/docs/cycles-parity.md b/docs/cycles-parity.mdindex 6747b86b..9b1029b4 100644--- a/docs/cycles-parity.md+++ b/docs/cycles-parity.md@@ -391,3 +391,22 @@ uv run --no-project --with numpy python bench/cycles-parity/verify-lobes.py --se# Set GIT_BASH_BIN="C:\Program Files\Git\bin\bash.exe" and GPU_LOCK_SCRIPT="<path-to-gpu-lock.sh>" to wrap every GPU step automatically.uv run --no-project --with numpy --with psutil python bench/cycles-parity/run-m0-suite.py $OutDir --scene lit-interior --repeats 3 --bounces 8 --mode all```++## Sampling and light selection (#895)++Cook's `cycles` kernel draws its random numbers from an Owen-scrambled Sobol sequence (Burley 2020, hash-based scrambling, one scramble per pixel and per group of four dimensions) and picks lights through a light tree (Conty and Kulla 2018) once the analytic lights or the emissive triangles number more than 8. `sampler: 'pcg'` and `useLightTree: false` restore the earlier behaviour. The pixel filter is unchanged: `box` unless `filterType: 'blackman-harris'` is passed, which is what a Cycles reference at its default filter needs.++Measured on the RTX 3060 at `480 × 270`, 8 bounces, `box` filter, two seeds per point, against a high-sample reference of the other variant with its own seed (`bench/cycles-parity/measure-sampler-noise.py`):++| Scene | Comparison | Samples | `relMSE` before | `relMSE` after | Drop |+| :--- | :--- | ---: | ---: | ---: | ---: |+| `lit-interior` | PCG hash, then Sobol-Burley | 16 | 0.1024 | 0.0886 | 13.5% |+| `lit-interior` | PCG hash, then Sobol-Burley | 64 | 0.02629 | 0.02022 | 23.1% |+| `lit-interior` | PCG hash, then Sobol-Burley | 256 | 0.007130 | 0.004966 | 30.4% |+| `lit-interior` with 500 point lights | uniform pick, then light tree | 16 | 0.09166 | 0.02193 | 76.1% |+| `lit-interior` with 500 point lights | uniform pick, then light tree | 256 | 0.004423 | 0.001235 | 72.1% |+| `lit-interior` with 500 point lights | uniform pick, then light tree | 1024 | 0.000993 | 0.000431 | 56.6% |++On the 500-light scene (`make-many-lights-scene.mjs`) the tree costs about 4% more time per sample and reaches the 1024-sample error of the uniform pick in `9.6 s` of sampling instead of `25.3 s` (log-log interpolation over the 16 to 1024 ladder). The mean image of the tree over the uniform pick is `0.99996`, and the per-channel mean of Sobol-Burley at 256 samples is within `0.04%` of the reference, so neither change moves the image mean.++Not done: the blue-noise arrangement of the per-pixel scrambles across the image (each pixel hashes its own scramble, so the error is white across pixels, not blue), and a light tree that stays on in scenes with a sun or with instances that restrict their light group. The image-match runs against Blender Cycles (`run-m1-parity.py`) need Blender, which this machine did not have on the path.diff --git a/packages/render-native/FORMAT-v2.md b/packages/render-native/FORMAT-v2.mdindex 8bf09c59..63ba6efd 100644--- a/packages/render-native/FORMAT-v2.md+++ b/packages/render-native/FORMAT-v2.md@@ -37,7 +37,7 @@ Total size: **320 bytes** (`20 × 16 B`), alignment: **16 bytes**.| `20` | `4` | `4` | `u32` | `samples_per_dispatch` | Samples traced per pixel in one dispatch (`>= 1`) || `24` | `4` | `4` | `u32` | `total_samples` | Target total samples per pixel || `28` | `4` | `4` | `u32` | `seed` | Deterministic scramble seed |-| `32` | `4` | `4` | `u32` | `kernel_flags` | Bitmask: `1=USE_LIGHT_TREE`, `2=HAS_VOLUME`, `4=HAS_SUBSURFACE`, `8=ORTHOGRAPHIC_CAMERA`, `16=ADAPTIVE_SAMPLING`, `32=TRANSPARENT_BACKGROUND` |+| `32` | `4` | `4` | `u32` | `kernel_flags` | Bitmask: `1=USE_LIGHT_TREE`, `2=HAS_VOLUME`, `4=HAS_SUBSURFACE`, `8=ORTHOGRAPHIC_CAMERA`, `16=ADAPTIVE_SAMPLING`, `32=TRANSPARENT_BACKGROUND`, `64=PCG_SAMPLER` (unset: Owen-scrambled Sobol-Burley), `128=USE_EMISSIVE_LIGHT_TREE` || `36` | `4` | `4` | `f32` | `adaptive_threshold` | Adaptive stop threshold (`0.0` = disabled) || `40` | `4` | `4` | `f32` | `clamp_direct` | Effective direct radiance ceiling at bounce `0` (`0.0` or `>= 1e30` = unclamped; Cycles `sample_clamp_direct * 3.0`) || `44` | `4` | `4` | `f32` | `clamp_indirect` | Effective indirect radiance ceiling at bounce `> 0` (`0.0` or `>= 1e30` = unclamped; Cycles `sample_clamp_indirect * 3.0`) |@@ -290,6 +290,13 @@ Convention: `direction` is always the **unit emission direction pointing from thTotal stride: **64 bytes** (`4 × 16 B`), alignment: **16 bytes**.+`light-tree-v2.mjs` builds the buffer. It holds one tree over the analytic lights and one over the emissive triangles (a kind keeps the cumulative-weight pick when the lights hold a sun, any instance restricts its light group, or the kind has more than 16383 emitters; `useLightTree: false` builds neither, `true` builds every tree that can exist, and the default builds one for a kind with more than 8 emitters). Layout:++- Node `0` is a directory: `left_child` is the analytic root (flag `1=USE_LIGHT_TREE`), `right_or_first_emitter` the emissive root (flag `128=USE_EMISSIVE_LIGHT_TREE`, `0xFFFFFFFF` when absent) and `light_group_mask_or` the node index of the first emissive leaf.+- Leaves come first: the leaf of light `i` is node `1 + i`, the leaf of emissive triangle `i` is node `emissive_leaf_base + i`. Inner nodes follow each block.+- A leaf keeps `-1 - parent` in `left_child`; an inner node keeps its parent in the low 16 bits of `emitter_count_and_kind`. The kernel walks up from a leaf to learn the chance of having picked that emitter from the previous shading point, for MIS.+- `theta_o` and `theta_e` are angles in radians. The importance ignores the surface normal, so the chance is the same from the next-event sample and from the BSDF ray that later hits the emitter.+| Byte Offset | Size (B) | Alignment (B) | WGSL Type | Field | Description || ---: | ---: | ---: | :--- | :--- | :--- || `0` | `12` | `16` | `vec3<f32>` | `bounds_min` | World AABB minimum of emitters in subtree |diff --git a/packages/render-native/README.md b/packages/render-native/README.mdindex 62f8ce89..750cc742 100644--- a/packages/render-native/README.md+++ b/packages/render-native/README.md@@ -31,3 +31,5 @@ const { radiance, escaped } = traceNativeTexels(input, { count: texelCount, poin````radiance` is the mean light that reaches each texel (three floats per texel) and `escaped` the share of first rays that left the scene. The agent runtime uses it for recipe bakes (`bake.backend: "native"`).++Cook's sampler is an Owen-scrambled Sobol sequence (Burley 2020); `sampler: 'pcg'` selects the earlier white-noise hash. Lights are picked through a light tree (Conty and Kulla 2018) when a kind, analytic lights or emissive triangles, holds more than 8 emitters, no sun is among the lights and no instance restricts its light group; `useLightTree: true` forces it and `false` turns it off. Both change only the noise pattern of the image, not its mean. The pixel filter stays `box` unless `filterType: 'blackman-harris'` is passed ([FORMAT-v2.md](./FORMAT-v2.md)).diff --git a/packages/render-native/light-tree-v2.mjs b/packages/render-native/light-tree-v2.mjsnew file mode 100644index 00000000..ee7f94ab--- /dev/null+++ b/packages/render-native/light-tree-v2.mjs@@ -0,0 +1,312 @@+// Light tree for the Cycles-parity kernel (Conty and Kulla 2018, as in Cycles `kernel/light/tree.h`).+// Builds `LightTreeNode` records (FORMAT-v2.md section 7) over the packed analytic lights and the packed emissive triangles.+//+// Node layout in the buffer:+// node 0 directory: left_child = analytic root, right_or_first_emitter = emissive root+// (0xFFFFFFFF when a tree is absent), light_group_mask_or = first emissive leaf node+// 1 .. 1 + lightCount analytic leaves, in light order (leaf of light i is node 1 + i)+// then the analytic inner nodes+// emissive leaves, in triangle order (leaf of triangle i is node emissiveLeafBase + i), then the emissive inner nodes+// A leaf stores `-1 - parent` in left_child; an inner node stores its parent in the low 16 bits of emitter_count_and_kind.+// The kernel walks up from a leaf to the root to learn the chance of having picked that emitter from a given point.++export const LIGHT_TREE_AUTO_EMITTER_COUNT = 8;+export const NO_TREE_ROOT = 0xffffffff;+const LIGHT_TREE_NODE_BYTES = 64;+// Inner nodes keep their parent in 16 bits and the two trees share one buffer, so each tree stays under 2^14 emitters.+const MAX_EMITTERS_PER_TREE = 16383;+const LIGHT_TYPE_POINT = 0;+const LIGHT_TYPE_SPOT = 1;+const LIGHT_TYPE_SUN = 4;+const HALF_PI = Math.PI / 2;+const NODE_WORDS = 16;+const INSTANCE_WORDS = 40;+const INSTANCE_MASK_WORD = 30;+const KIND_EMISSIVE_BIT = 1 << 16;++function luminance(red, green, blue) {+ return 0.2126 * red + 0.7152 * green + 0.0722 * blue;+}++function angleBetween(first, second) {+ const cosine = first[0] * second[0] + first[1] * second[1] + first[2] * second[2];+ return Math.acos(Math.min(1, Math.max(-1, cosine)));+}++function anyPerpendicular(axis) {+ const smallest = axis.map(Math.abs).indexOf(Math.min(...axis.map(Math.abs)));+ const basis = [0, 0, 0];+ basis[smallest] = 1;+ const crossed = [+ axis[1] * basis[2] - axis[2] * basis[1],+ axis[2] * basis[0] - axis[0] * basis[2],+ axis[0] * basis[1] - axis[1] * basis[0],+ ];+ const length = Math.hypot(...crossed);+ return crossed.map(value => value / length);+}++// The smallest cone holding two cones (Conty and Kulla, section 3.2).+export function mergeCones(first, second) {+ const [wide, narrow] = second.thetaO > first.thetaO ? [second, first] : [first, second];+ const thetaE = Math.max(first.thetaE, second.thetaE);+ const between = angleBetween(wide.axis, narrow.axis);+ if (Math.min(between + narrow.thetaO, Math.PI) <= wide.thetaO) {+ return { axis: [...wide.axis], thetaO: wide.thetaO, thetaE };+ }+ const thetaO = (wide.thetaO + between + narrow.thetaO) / 2;+ if (thetaO >= Math.PI) {+ return { axis: [...wide.axis], thetaO: Math.PI, thetaE };+ }+ const turn = thetaO - wide.thetaO;+ if (Math.sin(between) < 1e-6) {+ return { axis: anyPerpendicular(wide.axis), thetaO, thetaE };+ }+ const wideWeight = Math.sin(between - turn) / Math.sin(between);+ const narrowWeight = Math.sin(turn) / Math.sin(between);+ const axis = wide.axis.map((value, index) => value * wideWeight + narrow.axis[index] * narrowWeight);+ const length = Math.hypot(...axis) || 1;+ return { axis: axis.map(value => value / length), thetaO, thetaE };+}++function mergeEntries(first, second) {+ return {+ minimum: first.minimum.map((value, axis) => Math.min(value, second.minimum[axis])),+ maximum: first.maximum.map((value, axis) => Math.max(value, second.maximum[axis])),+ energy: first.energy + second.energy,+ ...mergeCones(first, second),+ };+}++function describeAnalyticLight(floats, uints, wordBase) {+ const lightType = uints[wordBase + 3];+ const position = [floats[wordBase], floats[wordBase + 1], floats[wordBase + 2]];+ const radius = floats[wordBase + 11];+ const direction = [floats[wordBase + 8], floats[wordBase + 9], floats[wordBase + 10]];+ const sizeU = floats[wordBase + 15];+ const sizeV = floats[wordBase + 19];+ const weight = floats[wordBase + 28];+ const extent = Math.max(radius, 0.5 * Math.hypot(sizeU, sizeV));+ const minimum = position.map(value => value - extent);+ const maximum = position.map(value => value + extent);+ if (lightType === LIGHT_TYPE_POINT) {+ return { minimum, maximum, axis: [0, 1, 0], thetaO: Math.PI, thetaE: HALF_PI, energy: weight };+ }+ if (lightType === LIGHT_TYPE_SPOT) {+ const thetaE = Math.acos(Math.min(1, Math.max(-1, floats[wordBase + 20])));+ return { minimum, maximum, axis: direction, thetaO: 0, thetaE, energy: weight };+ }+ return { minimum, maximum, axis: direction, thetaO: 0, thetaE: HALF_PI, energy: weight };+}++function describeEmissiveTriangle(floats, wordBase) {+ const p0 = [floats[wordBase], floats[wordBase + 1], floats[wordBase + 2]];+ const edgeOne = [floats[wordBase + 4], floats[wordBase + 5], floats[wordBase + 6]];+ const edgeTwo = [floats[wordBase + 8], floats[wordBase + 9], floats[wordBase + 10]];+ const normal = [floats[wordBase + 12], floats[wordBase + 13], floats[wordBase + 14]];+ const weight = floats[wordBase + 20];+ const corners = [p0, p0.map((v, i) => v + edgeOne[i]), p0.map((v, i) => v + edgeTwo[i])];+ return {+ minimum: [0, 1, 2].map(axis => Math.min(corners[0][axis], corners[1][axis], corners[2][axis])),+ maximum: [0, 1, 2].map(axis => Math.max(corners[0][axis], corners[1][axis], corners[2][axis])),+ axis: normal,+ thetaO: 0,+ thetaE: HALF_PI,+ energy: weight,+ };+}++// Recursive median split on the axis where the leaf centres spread most. Depth stays near log2(count).+function buildSubtree(entries) {+ if (entries.length === 1) {+ return { leaf: entries[0] };+ }+ let splitAxis = 0;+ let widest = -1;+ for (let axis = 0; axis < 3; axis++) {+ const centres = entries.map(entry => entry.minimum[axis] + entry.maximum[axis]);+ const spread = Math.max(...centres) - Math.min(...centres);+ if (spread > widest) {+ widest = spread;+ splitAxis = axis;+ }+ }+ const sorted = [...entries].sort(+ (first, second) => (first.minimum[splitAxis] + first.maximum[splitAxis]) - (second.minimum[splitAxis] + second.maximum[splitAxis]),+ );+ const middle = sorted.length >> 1;+ const left = buildSubtree(sorted.slice(0, middle));+ const right = buildSubtree(sorted.slice(middle));+ return { left, right, ...mergeEntries(summaryOf(left), summaryOf(right)) };+}++function summaryOf(subtree) {+ return subtree.leaf ?? subtree;+}++// Lays one tree into `nodeWords`: leaf of emitter i at leafBase + i, inner nodes from `nextInnerIndex` on.+function writeSubtree(subtree, parentIndex, state) {+ const summary = summaryOf(subtree);+ let nodeIndex;+ if (subtree.leaf) {+ nodeIndex = state.leafBase + subtree.leaf.emitterIndex;+ } else {+ nodeIndex = state.nextInnerIndex;+ state.nextInnerIndex += 1;+ }+ const base = nodeIndex * NODE_WORDS;+ const { floats, ints, uints } = state;+ floats[base] = summary.minimum[0];+ floats[base + 1] = summary.minimum[1];+ floats[base + 2] = summary.minimum[2];+ floats[base + 3] = summary.energy;+ floats[base + 4] = summary.maximum[0];+ floats[base + 5] = summary.maximum[1];+ floats[base + 6] = summary.maximum[2];+ floats[base + 7] = summary.thetaO;+ floats[base + 8] = summary.axis[0];+ floats[base + 9] = summary.axis[1];+ floats[base + 10] = summary.axis[2];+ floats[base + 11] = summary.thetaE;+ uints[base + 15] = 0xffffffff;+ if (subtree.leaf) {+ ints[base + 12] = -1 - parentIndex;+ uints[base + 13] = subtree.leaf.emitterIndex;+ uints[base + 14] = (1 | state.kindBits) >>> 0;+ } else {+ ints[base + 12] = writeSubtree(subtree.left, nodeIndex, state);+ uints[base + 13] = writeSubtree(subtree.right, nodeIndex, state);+ uints[base + 14] = ((parentIndex & 0xffff) | state.kindBits) >>> 0;+ }+ return nodeIndex;+}++function collectAnalyticEntries(packedLights) {+ const floats = new Float32Array(packedLights.lights.buffer, packedLights.lights.byteOffset, packedLights.lightCount * 32);+ const uints = new Uint32Array(packedLights.lights.buffer, packedLights.lights.byteOffset, packedLights.lightCount * 32);+ const entries = [];+ for (let index = 0; index < packedLights.lightCount; index++) {+ const entry = describeAnalyticLight(floats, uints, index * 32);+ entries.push({ ...entry, emitterIndex: index });+ }+ return entries;+}++function collectEmissiveEntries(packedEmissives) {+ const floats = new Float32Array(+ packedEmissives.emissiveTriangles.buffer,+ packedEmissives.emissiveTriangles.byteOffset,+ packedEmissives.emissiveTriangleCount * 24,+ );+ const entries = [];+ for (let index = 0; index < packedEmissives.emissiveTriangleCount; index++) {+ entries.push({ ...describeEmissiveTriangle(floats, index * 24), emitterIndex: index });+ }+ return entries;+}++// A tree picks an emitter without asking whether the receiver is linked to it, so it needs every receiver to see every emitter:+// all instances keep the default (full) light group mask and no emitter has an empty mask.+function receiversSeeEveryEmitter(instances, instanceCount) {+ const words = new Uint32Array(instances.buffer, instances.byteOffset, instanceCount * INSTANCE_WORDS);+ for (let index = 0; index < instanceCount; index++) {+ const lo = words[index * INSTANCE_WORDS + INSTANCE_MASK_WORD];+ const hi = words[index * INSTANCE_WORDS + INSTANCE_MASK_WORD + 1];+ if (lo !== 0xffffffff || hi !== 0xffffffff) {+ return false;+ }+ }+ return true;+}++function everyMaskIsNonEmpty(buffer, count, strideWords, maskWordOffset) {+ const words = new Uint32Array(buffer.buffer, buffer.byteOffset, count * strideWords);+ for (let index = 0; index < count; index++) {+ if (words[index * strideWords + maskWordOffset] === 0 && words[index * strideWords + maskWordOffset + 1] === 0) {+ return false;+ }+ }+ return true;+}++function lightsCanUseTree(packedLights, wantTree) {+ if (packedLights.lightCount === 0 || packedLights.lightCount > MAX_EMITTERS_PER_TREE || packedLights.hasDistant) {+ return false;+ }+ if (!everyMaskIsNonEmpty(packedLights.lights, packedLights.lightCount, 32, 30)) {+ return false;+ }+ return wantTree ?? packedLights.lightCount > LIGHT_TREE_AUTO_EMITTER_COUNT;+}++function emissivesCanUseTree(packedEmissives, wantTree) {+ const count = packedEmissives.emissiveTriangleCount;+ if (count === 0 || count > MAX_EMITTERS_PER_TREE) {+ return false;+ }+ if (!everyMaskIsNonEmpty(packedEmissives.emissiveTriangles, count, 24, 22)) {+ return false;+ }+ return wantTree ?? count > LIGHT_TREE_AUTO_EMITTER_COUNT;+}++/**+ * Builds the node buffer. `options.useLightTree`: true builds a tree for every kind that can have one, false builds none,+ * undefined (the default) builds one for a kind with more than LIGHT_TREE_AUTO_EMITTER_COUNT emitters.+ * A kind falls back to the cumulative-weight pick when the lights hold a sun, any instance restricts its light group, or the kind has more than 16383 emitters.+ * Returns { lightTreeNodes, lightTreeNodeCount, analyticTree, emissiveTree } (the booleans say which kinds use a tree), or+ * lightTreeNodeCount 0 when neither does.+ */+export function buildLightTreeNodes(packedLights, packedEmissives, packedInstances, options = {}) {+ const wantTree = typeof options.useLightTree === 'boolean' ? options.useLightTree : undefined;+ const receiversOk = wantTree !== false && receiversSeeEveryEmitter(packedInstances.instances, packedInstances.instanceCount);+ const analyticTree = receiversOk && lightsCanUseTree(packedLights, wantTree);+ const emissiveTree = receiversOk && emissivesCanUseTree(packedEmissives, wantTree);+ if (!analyticTree && !emissiveTree) {+ return { lightTreeNodes: new Uint8Array(LIGHT_TREE_NODE_BYTES), lightTreeNodeCount: 0, analyticTree: false, emissiveTree: false };+ }+ const analyticCount = analyticTree ? packedLights.lightCount : 0;+ const emissiveCount = emissiveTree ? packedEmissives.emissiveTriangleCount : 0;+ const nodeCount = 1 + (analyticCount > 0 ? 2 * analyticCount - 1 : 0) + (emissiveCount > 0 ? 2 * emissiveCount - 1 : 0);+ const bytes = new Uint8Array(nodeCount * LIGHT_TREE_NODE_BYTES);+ const state = {+ floats: new Float32Array(bytes.buffer),+ ints: new Int32Array(bytes.buffer),+ uints: new Uint32Array(bytes.buffer),+ leafBase: 0,+ nextInnerIndex: 0,+ kindBits: 0,+ };+ let nextFreeNode = 1;+ let analyticRoot = NO_TREE_ROOT;+ let emissiveRoot = NO_TREE_ROOT;+ let emissiveLeafBase = NO_TREE_ROOT;+ let totalEnergy = 0;+ if (analyticCount > 0) {+ state.leafBase = nextFreeNode;+ state.nextInnerIndex = nextFreeNode + analyticCount;+ state.kindBits = 0;+ const subtree = buildSubtree(collectAnalyticEntries(packedLights));+ analyticRoot = writeSubtree(subtree, 0, state);+ totalEnergy += summaryOf(subtree).energy;+ nextFreeNode += 2 * analyticCount - 1;+ }+ if (emissiveCount > 0) {+ state.leafBase = nextFreeNode;+ state.nextInnerIndex = nextFreeNode + emissiveCount;+ state.kindBits = KIND_EMISSIVE_BIT;+ const subtree = buildSubtree(collectEmissiveEntries(packedEmissives));+ emissiveRoot = writeSubtree(subtree, 0, state);+ emissiveLeafBase = nextFreeNode;+ totalEnergy += summaryOf(subtree).energy;+ }+ state.floats[3] = totalEnergy;+ state.floats[7] = Math.PI;+ state.floats[9] = 1;+ state.floats[11] = Math.PI;+ state.ints[12] = analyticRoot === NO_TREE_ROOT ? -1 : analyticRoot;+ state.uints[13] = emissiveRoot;+ state.uints[14] = 0;+ state.uints[15] = emissiveLeafBase;+ return { lightTreeNodes: bytes, lightTreeNodeCount: nodeCount, analyticTree: analyticCount > 0, emissiveTree: emissiveCount > 0 };+}diff --git a/packages/render-native/pack-input-v2.mjs b/packages/render-native/pack-input-v2.mjsindex fa7e2dcf..fc49e3d3 100644--- a/packages/render-native/pack-input-v2.mjs+++ b/packages/render-native/pack-input-v2.mjs@@ -1,6 +1,8 @@// Packs a 67js trace scene (or upgrades a legacy v1 input) into the FORMAT-v2 binary tables read by the Cycles-parity// native kernel (`FORMAT-v2.md` and `src/cycles/abi.wgsl`). Pure typed arrays with zero Node-only imports.+import { buildLightTreeNodes } from './light-tree-v2.mjs';+export const FORMAT_V2_MAGIC = 0x36375054;export const FORMAT_V2_VERSION = 2;export const INVALID_INDEX_V2 = 0xffffffff;@@ -26,6 +28,8 @@ const KERNEL_FLAG_HAS_SUBSURFACE = 4;const KERNEL_FLAG_ORTHOGRAPHIC_CAMERA = 8;const KERNEL_FLAG_ADAPTIVE_SAMPLING = 16;const KERNEL_FLAG_TRANSPARENT_BACKGROUND = 32;+const KERNEL_FLAG_PCG_SAMPLER = 64;+const KERNEL_FLAG_USE_EMISSIVE_LIGHT_TREE = 128;const INSTANCE_DEFAULT_VISIBILITY = 1 | 2 | 4 | 8 | 16 | 32;const INSTANCE_FLAG_NEGATIVE_SCALE = 64;@@ -1288,57 +1292,6 @@ function packAnalyticLightsBuffer(entries) {};}-function packRootLightTreeNode(packedLights, packedEmissives) {- const totalEmitters = packedLights.lightCount + packedEmissives.emissiveTriangleCount;- const buffer = new Uint8Array(STRUCT_STRIDES_V2.lightTreeNode);- if (totalEmitters === 0) {- return { lightTreeNodes: buffer, lightTreeNodeCount: 0 };- }- const f32 = new Float32Array(buffer.buffer, 0, 16);- const u32 = new Uint32Array(buffer.buffer, 0, 16);- const i32 = new Int32Array(buffer.buffer, 0, 16);-- const boundsMin = [Infinity, Infinity, Infinity];- const boundsMax = [-Infinity, -Infinity, -Infinity];- for (const candidate of [packedLights, packedEmissives]) {- if (!candidate.boundsMin) continue;- for (let axis = 0; axis < 3; axis++) {- boundsMin[axis] = Math.min(boundsMin[axis], candidate.boundsMin[axis]);- boundsMax[axis] = Math.max(boundsMax[axis], candidate.boundsMax[axis]);- }- }- if (!(boundsMin[0] <= boundsMax[0])) {- boundsMin.fill(-1);- boundsMax.fill(1);- }-- const leafCount = Math.min(0xffff, totalEmitters);- const kindBit = packedLights.lightCount === 0 && packedEmissives.emissiveTriangleCount > 0 ? (1 << 16) : 0;- const distantBit = packedLights.hasDistant ? (1 << 17) : 0;-- f32[0] = boundsMin[0];- f32[1] = boundsMin[1];- f32[2] = boundsMin[2];- f32[3] = packedLights.analyticLightTotalWeight + packedEmissives.emissiveTotalWeight;-- f32[4] = boundsMax[0];- f32[5] = boundsMax[1];- f32[6] = boundsMax[2];- f32[7] = Math.PI;-- f32[8] = 0;- f32[9] = 1;- f32[10] = 0;- f32[11] = Math.PI;-- i32[12] = -1;- u32[13] = 0;- u32[14] = (leafCount | kindBit | distantBit) >>> 0;- u32[15] = (packedLights.maskOr | packedEmissives.maskOr) >>> 0;-- return { lightTreeNodes: buffer, lightTreeNodeCount: 1 };-}-function packEnvironmentTexelsV2(environment, options = {}) {if (!environment || !(environment.width > 0 && environment.height > 0)) {const bg = options.backgroundColor ?? [0, 0, 0];@@ -1525,6 +1478,12 @@ export function validatePackOptions(options, callerName, requireDimensionsAndSam// samplesPerDispatch is optional (undefined means "let the addon choose"); only validate when provided.requireFiniteIntegerInRangeIfPresent(samplesPerDispatch, 'samplesPerDispatch', 1, 65536, callerName);validateMaxSeconds(options.maxSeconds, callerName);+ if (options.sampler !== undefined && options.sampler !== 'sobol' && options.sampler !== 'pcg') {+ throw new RangeError(`${callerName}: \`sampler\` must be "sobol" or "pcg", got ${JSON.stringify(options.sampler)}.`);+ }+ if (options.useLightTree !== undefined && typeof options.useLightTree !== 'boolean') {+ throw new TypeError(`${callerName}: \`useLightTree\` must be true, false or left out for automatic, got ${JSON.stringify(options.useLightTree)}.`);+ }if (width !== undefined && height !== undefined) {validateImagePixelCount(width, height, callerName);if (samplesPerDispatch !== undefined) {@@ -1598,9 +1557,12 @@ function packKernelParamsV2({const volumeDensity = Math.max(0, Number(volume?.density ?? 0));let kernelFlags = 0;- if (options.useLightTree === true && counts.lightTreeNodeCount > 0) {+ if (counts.analyticLightTree === true) {kernelFlags |= KERNEL_FLAG_USE_LIGHT_TREE;}+ if (counts.emissiveLightTree === true) {+ kernelFlags |= KERNEL_FLAG_USE_EMISSIVE_LIGHT_TREE;+ }if (volumeDensity > 0) {kernelFlags |= KERNEL_FLAG_HAS_VOLUME;}@@ -1616,6 +1578,9 @@ function packKernelParamsV2({if (options.transparentBackground === true) {kernelFlags |= KERNEL_FLAG_TRANSPARENT_BACKGROUND;}+ if (options.sampler === 'pcg') {+ kernelFlags |= KERNEL_FLAG_PCG_SAMPLER;+ }const maxBounces = Math.max(0, Math.round(Number(options.bounces ?? options.maxBounces ?? 8)));const maxDiffuseBounces = Math.max(0, Math.round(Number(options.diffuseBounces ?? maxBounces)));@@ -2190,7 +2155,7 @@ export function buildNativeInputV2(scene, camera, options = {}) {const packedEmissives = packEmissiveTriangleBuffer(packedGeometry.emissiveList);const analyticEntries = buildAnalyticLightEntries(scene.lights);const packedLights = packAnalyticLightsBuffer(analyticEntries);- const packedLightTree = packRootLightTreeNode(packedLights, packedEmissives);+ const packedLightTree = buildLightTreeNodes(packedLights, packedEmissives, { instances: packedGeometry.instances, instanceCount: packedGeometry.instanceCount }, options);const packedEnvironment = packEnvironmentTexelsV2(scene.environment, options);const counts = {@@ -2200,6 +2165,8 @@ export function buildNativeInputV2(scene, camera, options = {}) {emissiveTriangleCount: packedEmissives.emissiveTriangleCount,lightCount: packedLights.lightCount,lightTreeNodeCount: packedLightTree.lightTreeNodeCount,+ analyticLightTree: packedLightTree.analyticTree,+ emissiveLightTree: packedLightTree.emissiveTree,textureCount: packedTextures.textureCount,};@@ -2601,7 +2568,7 @@ export function upgradeNativeInputV1ToV2(v1Input, options = {}) {const packedEmissives = packEmissiveTriangleBuffer(emissiveList);const analyticEntries = buildAnalyticLightEntries(reconstructedLights);const packedLights = packAnalyticLightsBuffer(analyticEntries);- const packedLightTree = packRootLightTreeNode(packedLights, packedEmissives);+ const packedLightTree = buildLightTreeNodes(packedLights, packedEmissives, { instances: instancesBuffer, instanceCount: instanceItems.length }, options);const packedEnvironment = packEnvironmentTexelsV2(reconstructedEnv, options);const mergedOptions = {@@ -2620,6 +2587,8 @@ export function upgradeNativeInputV1ToV2(v1Input, options = {}) {emissiveTriangleCount: packedEmissives.emissiveTriangleCount,lightCount: packedLights.lightCount,lightTreeNodeCount: packedLightTree.lightTreeNodeCount,+ analyticLightTree: packedLightTree.analyticTree,+ emissiveLightTree: packedLightTree.emissiveTree,textureCount: packedTextures.textureCount,};diff --git a/packages/render-native/package.json b/packages/render-native/package.jsonindex 6982806c..929e7ee7 100644--- a/packages/render-native/package.json+++ b/packages/render-native/package.json@@ -11,6 +11,7 @@"index.mjs","pack-input.mjs","pack-input-v2.mjs",+ "light-tree-v2.mjs","FORMAT-v2.md","build.mjs","build.rs",diff --git a/packages/render-native/src/cycles/abi.wgsl b/packages/render-native/src/cycles/abi.wgslindex 0daa8b3e..80628b9a 100644--- a/packages/render-native/src/cycles/abi.wgsl+++ b/packages/render-native/src/cycles/abi.wgsl@@ -38,6 +38,8 @@ const KERNEL_FLAG_HAS_SUBSURFACE: u32 = 4u;const KERNEL_FLAG_ORTHOGRAPHIC_CAMERA: u32 = 8u;const KERNEL_FLAG_ADAPTIVE_SAMPLING: u32 = 16u;const KERNEL_FLAG_TRANSPARENT_BACKGROUND: u32 = 32u;+const KERNEL_FLAG_PCG_SAMPLER: u32 = 64u;+const KERNEL_FLAG_USE_EMISSIVE_LIGHT_TREE: u32 = 128u;// `KernelParamsV2.filter_type` values.const FILTER_BOX: u32 = 0u;diff --git a/packages/render-native/src/cycles/integrator.wgsl b/packages/render-native/src/cycles/integrator.wgslindex 0809d19d..ac4de55d 100644--- a/packages/render-native/src/cycles/integrator.wgsl+++ b/packages/render-native/src/cycles/integrator.wgsl@@ -896,6 +896,7 @@ fn main(@builtin(global_invocation_id) global_id: vec3<u32>) {if (closure.emission.x > 0.0 || closure.emission.y > 0.0 || closure.emission.z > 0.0) {let emission_weight = lgt_emissive_surface_weight(point.emissive_index,+ ray_origin,surface_hit.t,ray_dir,is_camera_ray,diff --git a/packages/render-native/src/cycles/lights.wgsl b/packages/render-native/src/cycles/lights.wgslindex f47d1708..4509cd23 100644--- a/packages/render-native/src/cycles/lights.wgsl+++ b/packages/render-native/src/cycles/lights.wgsl@@ -259,6 +259,120 @@ fn lgt_sample_ellipse_point(center: vec3<f32>, axis_u: vec3<f32>, size_u: f32, areturn center + axis_u * (disk.x * 0.5 * size_u) + axis_v * (disk.y * 0.5 * size_v);}+// Light tree walk (Conty and Kulla 2018, Cycles kernel/light/tree.h). Node 0 is a directory: `left_child` is the analytic+// root and `right_or_first_emitter` the emissive root. The importance ignores the surface normal, so the chance of picking+// an emitter is the same from the next-event sample and from the ray that later hits that emitter (MIS).+const LGT_TREE_MINIMUM_SHARE: f32 = 0.1;++fn lgt_tree_node_importance(node_index: u32, position: vec3<f32>) -> vec2<f32> {+ let node = light_tree_nodes[node_index];+ let center = 0.5 * (node.bounds_min + node.bounds_max);+ let half_diagonal = 0.5 * length(node.bounds_max - node.bounds_min);+ let delta = center - position;+ let distance = length(delta);+ let nearest = max(max(distance, half_diagonal), 1.0e-4);+ let farthest = distance + half_diagonal;+ let minimum_measure = node.energy / max(farthest * farthest, 1.0e-8);+ if (distance <= half_diagonal) {+ return vec2<f32>(node.energy / (nearest * nearest), minimum_measure);+ }+ let toward = delta / distance;+ let ratio = half_diagonal / distance;+ let theta_u = acos(sqrt(max(0.0, 1.0 - ratio * ratio)));+ let theta = acos(clamp(-dot(node.cone_axis, toward), -1.0, 1.0));+ let theta_prime = max(theta - node.theta_o - theta_u, 0.0);+ if (theta_prime >= node.theta_e) {+ return vec2<f32>(0.0, minimum_measure);+ }+ return vec2<f32>(node.energy * cos(theta_prime) / (nearest * nearest), minimum_measure);+}++// Chance of taking the left child, or -1 when both children are worth nothing.+fn lgt_tree_left_probability(left: vec2<f32>, right: vec2<f32>) -> f32 {+ let total_maximum = left.x + right.x;+ let total_minimum = left.y + right.y;+ if (!(total_minimum > 0.0)) {+ return -1.0;+ }+ if (!(total_maximum > 0.0)) {+ return left.y / total_minimum;+ }+ return (1.0 - LGT_TREE_MINIMUM_SHARE) * (left.x / total_maximum) + LGT_TREE_MINIMUM_SHARE * (left.y / total_minimum);+}++// Walks from `root_index` to a leaf with one random number, rescaled at each step. Returns the emitter index and writes the+// chance of that whole path to `probability_out`, or returns INVALID_INDEX when nothing is worth sampling.+fn lgt_tree_pick(root_index: u32, position: vec3<f32>, pick_u: f32, probability_out: ptr<function, f32>) -> u32 {+ var node_index = root_index;+ var remaining_u = pick_u;+ var probability = 1.0;+ for (var step = 0u; step < 40u; step += 1u) {+ let node = light_tree_nodes[node_index];+ if (node.left_child < 0) {+ *probability_out = probability;+ return node.right_or_first_emitter;+ }+ let left_index = u32(node.left_child);+ let right_index = node.right_or_first_emitter;+ let left_probability = lgt_tree_left_probability(+ lgt_tree_node_importance(left_index, position),+ lgt_tree_node_importance(right_index, position),+ );+ if (left_probability < 0.0) {+ return INVALID_INDEX;+ }+ if (remaining_u < left_probability) {+ node_index = left_index;+ probability *= left_probability;+ remaining_u = min(remaining_u / left_probability, 0.99999994);+ } else {+ let right_probability = 1.0 - left_probability;+ if (right_probability <= 0.0) {+ return INVALID_INDEX;+ }+ node_index = right_index;+ probability *= right_probability;+ remaining_u = min((remaining_u - left_probability) / right_probability, 0.99999994);+ }+ }+ return INVALID_INDEX;+}++// The chance `lgt_tree_pick` has of ending at `leaf_index` from `position`, found by walking up to the root.+fn lgt_tree_selection_probability(leaf_index: u32, position: vec3<f32>) -> f32 {+ var node_index = leaf_index;+ var probability = 1.0;+ for (var step = 0u; step < 40u; step += 1u) {+ let node = light_tree_nodes[node_index];+ var parent_index = node.emitter_count_and_kind & 0xFFFFu;+ if (node.left_child < 0) {+ parent_index = u32(-1 - node.left_child);+ }+ if (parent_index == 0u) {+ break;+ }+ let parent = light_tree_nodes[parent_index];+ let left_index = u32(parent.left_child);+ let left_probability = lgt_tree_left_probability(+ lgt_tree_node_importance(left_index, position),+ lgt_tree_node_importance(parent.right_or_first_emitter, position),+ );+ if (left_probability < 0.0) {+ return 0.0;+ }+ probability *= select(1.0 - left_probability, left_probability, left_index == node_index);+ node_index = parent_index;+ }+ return probability;+}++fn lgt_analytic_selection_pdf(light_index: u32, ray_origin: vec3<f32>) -> f32 {+ if ((kernel_params.kernel_flags & KERNEL_FLAG_USE_LIGHT_TREE) != 0u) {+ return lgt_tree_selection_probability(1u + light_index, ray_origin);+ }+ return lights[light_index].selection_pdf;+}+fn lgt_binary_search_light_cdf(pick_u: f32, count: u32) -> u32 {var low = 0u;var high = count - 1u;@@ -524,8 +638,19 @@ fn lgt_sample_analytic_light(if (count == 0u) {return lgt_empty_sample();}- let light_index = lgt_binary_search_light_cdf(pick_u, count);- let light = lights[light_index];+ var light_index = INVALID_INDEX;+ var selection_probability = 0.0;+ if ((kernel_params.kernel_flags & KERNEL_FLAG_USE_LIGHT_TREE) != 0u) {+ light_index = lgt_tree_pick(u32(light_tree_nodes[0].left_child), shading_pos, pick_u, &selection_probability);+ } else {+ light_index = lgt_binary_search_light_cdf(pick_u, count);+ selection_probability = lights[light_index].selection_pdf;+ }+ if (light_index == INVALID_INDEX) {+ return lgt_empty_sample();+ }+ var light = lights[light_index];+ light.selection_pdf = selection_probability;if (light.selection_pdf <= 0.0) {return lgt_empty_sample();}@@ -550,8 +675,19 @@ fn lgt_sample_emissive_triangle(point: ptr<function, ShadingPoint>, pick_u: f32,if (count == 0u) {return out;}- let index = lgt_binary_search_emissive_cdf(pick_u, count);- let emitter = emissive_triangles[index];+ var index = INVALID_INDEX;+ var selection_probability = 0.0;+ if ((kernel_params.kernel_flags & KERNEL_FLAG_USE_EMISSIVE_LIGHT_TREE) != 0u) {+ index = lgt_tree_pick(light_tree_nodes[0].right_or_first_emitter, (*point).position, pick_u, &selection_probability);+ if (index == INVALID_INDEX) {+ return out;+ }+ } else {+ index = lgt_binary_search_emissive_cdf(pick_u, count);+ selection_probability = emissive_triangles[index].selection_pdf;+ }+ var emitter = emissive_triangles[index];+ emitter.selection_pdf = selection_probability;if (emitter.selection_pdf <= 0.0 || emitter.area <= 0.0) {return out;}@@ -789,7 +925,7 @@ fn lgt_eval_analytic_lights_along_segment(let one_minus_cos = min(one_minus_cos_sphere, one_minus_cos_spot);pdf_solid_angle = 1.0 / max(TWO_PI * one_minus_cos, 1.0e-30);}- let pdf_nee = light.selection_pdf * pdf_solid_angle;+ let pdf_nee = lgt_analytic_selection_pdf(index, ray_origin) * pdf_solid_angle;let mis_weight = select(lgt_power_heuristic(prev_bsdf_pdf, pdf_nee), 1.0, is_camera_ray || mis_skip);let medium_atten = select(vec3<f32>(1.0), exp(-medium_sigma * max(hit_t - t_min, 0.0)), in_medium);total += light.radiance * medium_atten * (spot_weight * falloff * mis_weight);@@ -850,7 +986,7 @@ fn lgt_eval_analytic_lights_along_segment(continue;}}- let pdf_nee = light.selection_pdf * pdf_solid_angle;+ let pdf_nee = lgt_analytic_selection_pdf(index, ray_origin) * pdf_solid_angle;let mis_weight = select(lgt_power_heuristic(prev_bsdf_pdf, pdf_nee), 1.0, is_camera_ray || mis_skip);let medium_atten = select(vec3<f32>(1.0), exp(-medium_sigma * max(hit_t - t_min, 0.0)), in_medium);total += light.radiance * medium_atten * (spread_weight * falloff * mis_weight);@@ -917,6 +1053,7 @@ fn lgt_eval_escaped_ray(fn lgt_emissive_surface_weight(emissive_index: u32,+ ray_origin: vec3<f32>,hit_distance: f32,ray_dir: vec3<f32>,is_camera_ray: bool,@@ -945,6 +1082,10 @@ fn lgt_emissive_surface_weight(if (cos_light <= 1.0e-8) {return 0.0;}- let pdf_nee = emitter.selection_pdf * (hit_distance * hit_distance) / max(emitter.area * cos_light, 1.0e-20);+ var selection_pdf = emitter.selection_pdf;+ if ((kernel_params.kernel_flags & KERNEL_FLAG_USE_EMISSIVE_LIGHT_TREE) != 0u) {+ selection_pdf = lgt_tree_selection_probability(light_tree_nodes[0].light_group_mask_or + emissive_index, ray_origin);+ }+ let pdf_nee = selection_pdf * (hit_distance * hit_distance) / max(emitter.area * cos_light, 1.0e-20);return lgt_power_heuristic(prev_bsdf_pdf, pdf_nee);}diff --git a/packages/render-native/src/cycles/sampler.wgsl b/packages/render-native/src/cycles/sampler.wgslindex 5e122b56..c1f6e0e6 100644--- a/packages/render-native/src/cycles/sampler.wgsl+++ b/packages/render-native/src/cycles/sampler.wgsl@@ -1,7 +1,9 @@// SPDX-FileCopyrightText: 2011-2022 Blender Foundation// SPDX-License-Identifier: Apache-2.0//-// Stateless uncorrelated 4D PCG hash sampler (`smp_*`) for the Cycles-parity native kernel.+// Stateless 4D sampler (`smp_*`) for the Cycles-parity native kernel. The default is an Owen-scrambled Sobol+// sequence with Burley's hash-based scrambling ("Practical Hash-based Owen Scrambling", JCGT 2020), the sampler+// Cycles uses. `KERNEL_FLAG_PCG_SAMPLER` selects the earlier uncorrelated 4D PCG hash instead.const SMP_UINT_TO_UNIT_FLOAT: f32 = 1.0 / 16777216.0;@@ -11,6 +13,97 @@ struct SmpState {sample_index: u32,dimension: u32,seed: u32,+ pixel_seed: u32,+ use_pcg: u32,+}++// First four dimensions of the Joe-Kuo Sobol sequence, one row per bit of the sample index.+const SMP_SOBOL_MATRIX = array<vec4<u32>, 32>(+ vec4<u32>(0x80000000u, 0x80000000u, 0x80000000u, 0x80000000u),+ vec4<u32>(0x40000000u, 0xC0000000u, 0xC0000000u, 0xC0000000u),+ vec4<u32>(0x20000000u, 0xA0000000u, 0x60000000u, 0x20000000u),+ vec4<u32>(0x10000000u, 0xF0000000u, 0x90000000u, 0x50000000u),+ vec4<u32>(0x08000000u, 0x88000000u, 0xE8000000u, 0xF8000000u),+ vec4<u32>(0x04000000u, 0xCC000000u, 0x5C000000u, 0x74000000u),+ vec4<u32>(0x02000000u, 0xAA000000u, 0x8E000000u, 0xA2000000u),+ vec4<u32>(0x01000000u, 0xFF000000u, 0xC5000000u, 0x93000000u),+ vec4<u32>(0x00800000u, 0x80800000u, 0x68800000u, 0xD8800000u),+ vec4<u32>(0x00400000u, 0xC0C00000u, 0x9CC00000u, 0x25400000u),+ vec4<u32>(0x00200000u, 0xA0A00000u, 0xEE600000u, 0x59E00000u),+ vec4<u32>(0x00100000u, 0xF0F00000u, 0x55900000u, 0xE6D00000u),+ vec4<u32>(0x00080000u, 0x88880000u, 0x80680000u, 0x78080000u),+ vec4<u32>(0x00040000u, 0xCCCC0000u, 0xC09C0000u, 0xB40C0000u),+ vec4<u32>(0x00020000u, 0xAAAA0000u, 0x60EE0000u, 0x82020000u),+ vec4<u32>(0x00010000u, 0xFFFF0000u, 0x90550000u, 0xC3050000u),+ vec4<u32>(0x00008000u, 0x80008000u, 0xE8808000u, 0x208F8000u),+ vec4<u32>(0x00004000u, 0xC000C000u, 0x5CC0C000u, 0x51474000u),+ vec4<u32>(0x00002000u, 0xA000A000u, 0x8E606000u, 0xFBEA2000u),+ vec4<u32>(0x00001000u, 0xF000F000u, 0xC5909000u, 0x75D93000u),+ vec4<u32>(0x00000800u, 0x88008800u, 0x6868E800u, 0xA0858800u),+ vec4<u32>(0x00000400u, 0xCC00CC00u, 0x9C9C5C00u, 0x914E5400u),+ vec4<u32>(0x00000200u, 0xAA00AA00u, 0xEEEE8E00u, 0xDBE79E00u),+ vec4<u32>(0x00000100u, 0xFF00FF00u, 0x5555C500u, 0x25DB6D00u),+ vec4<u32>(0x00000080u, 0x80808080u, 0x8000E880u, 0x58800080u),+ vec4<u32>(0x00000040u, 0xC0C0C0C0u, 0xC0005CC0u, 0xE54000C0u),+ vec4<u32>(0x00000020u, 0xA0A0A0A0u, 0x60008E60u, 0x79E00020u),+ vec4<u32>(0x00000010u, 0xF0F0F0F0u, 0x9000C590u, 0xB6D00050u),+ vec4<u32>(0x00000008u, 0x88888888u, 0xE8006868u, 0x800800F8u),+ vec4<u32>(0x00000004u, 0xCCCCCCCCu, 0x5C009C9Cu, 0xC00C0074u),+ vec4<u32>(0x00000002u, 0xAAAAAAAAu, 0x8E00EEEEu, 0x200200A2u),+ vec4<u32>(0x00000001u, 0xFFFFFFFFu, 0xC5005555u, 0x50050093u),+);+++fn smp_hash_u32(input_word: u32) -> u32 {+ var v = input_word;+ v ^= v >> 16u;+ v *= 0x7feb352du;+ v ^= v >> 15u;+ v *= 0x846ca68bu;+ v ^= v >> 16u;+ return v;+}++fn smp_laine_karras_permutation(index_word: u32, scramble_seed: u32) -> u32 {+ var x = index_word + scramble_seed;+ x ^= x * 0x6c50b47cu;+ x ^= x * 0xb82f1e52u;+ x ^= x * 0xc7afe638u;+ x ^= x * 0x8d22f6e6u;+ return x;+}++fn smp_nested_uniform_scramble(index_word: u32, scramble_seed: u32) -> u32 {+ return reverseBits(smp_laine_karras_permutation(reverseBits(index_word), scramble_seed));+}++fn smp_sobol_4d(index_word: u32) -> vec4<u32> {+ var result = vec4<u32>(0u);+ var remaining = index_word;+ for (var bit = 0u; bit < 32u; bit += 1u) {+ if (remaining == 0u) {+ break;+ }+ if ((remaining & 1u) != 0u) {+ result = result ^ SMP_SOBOL_MATRIX[bit];+ }+ remaining = remaining >> 1u;+ }+ return result;+}++fn smp_sobol_burley_words(state: ptr<function, SmpState>) -> vec4<u32> {+ let group = (*state).dimension >> 2u;+ (*state).dimension = (*state).dimension + 4u;+ let group_seed = smp_hash_u32((*state).pixel_seed ^ (group * 0x9E3779B9u + 0x7F4A7C15u));+ let shuffled_index = smp_nested_uniform_scramble((*state).sample_index, group_seed);+ let sobol_words = smp_sobol_4d(shuffled_index);+ return vec4<u32>(+ smp_nested_uniform_scramble(sobol_words.x, smp_hash_u32(group_seed ^ 0x68E31DA4u)),+ smp_nested_uniform_scramble(sobol_words.y, smp_hash_u32(group_seed ^ 0xB5297A4Du)),+ smp_nested_uniform_scramble(sobol_words.z, smp_hash_u32(group_seed ^ 0x1B56C4E9u)),+ smp_nested_uniform_scramble(sobol_words.w, smp_hash_u32(group_seed ^ 0x2545F491u)),+ );}fn smp_pcg4d(input_words: vec4<u32>) -> vec4<u32> {@@ -32,6 +125,9 @@ fn smp_word_to_unit_float(word: u32) -> f32 {}fn smp_draw_words(state: ptr<function, SmpState>) -> vec4<u32> {+ if ((*state).use_pcg == 0u) {+ return smp_sobol_burley_words(state);+ }let dim = (*state).dimension;(*state).dimension = dim + 1u;let seed = (*state).seed;@@ -51,6 +147,8 @@ fn smp_init(pixel_x: u32, pixel_y: u32, sample_index: u32, seed: u32) -> SmpStatstate.sample_index = sample_index;state.dimension = 0u;state.seed = seed;+ state.use_pcg = select(0u, 1u, (kernel_params.kernel_flags & KERNEL_FLAG_PCG_SAMPLER) != 0u);+ state.pixel_seed = smp_hash_u32(pixel_x ^ smp_hash_u32(pixel_y ^ smp_hash_u32(seed + 0x3C6EF372u)));return state;}diff --git a/tests/native-light-tree.test.js b/tests/native-light-tree.test.jsnew file mode 100644index 00000000..a53987f8--- /dev/null+++ b/tests/native-light-tree.test.js@@ -0,0 +1,136 @@+import assert from 'node:assert/strict';+import test from 'node:test';+import { STRUCT_STRIDES_V2, buildNativeInputV2 } from '../packages/render-native/index.mjs';+import { NO_TREE_ROOT } from '../packages/render-native/light-tree-v2.mjs';+import { createCamera } from '../src/path-tracer.js';+import { buildTraceScene } from '../src/path-tracer-scene.js';++const KERNEL_FLAGS_WORD = 8;+const FLAG_USE_LIGHT_TREE = 1;+const FLAG_PCG_SAMPLER = 64;+const FLAG_USE_EMISSIVE_LIGHT_TREE = 128;++function floorGeometry() {+ return {+ positions: new Float32Array([-4, 0, -4, 4, 0, -4, 4, 0, 4, -4, 0, 4]),+ normals: new Float32Array([0, 1, 0, 0, 1, 0, 0, 1, 0, 0, 1, 0]),+ uvs: new Float32Array([0, 0, 1, 0, 1, 1, 0, 1]),+ colors: new Float32Array(12).fill(1),+ indices: new Uint32Array([0, 1, 2, 0, 2, 3]),+ };+}++function pointLights(count) {+ return Array.from({ length: count }, (_, index) => ({+ position: [(index % 5) - 2, 1 + (index % 3) * 0.5, Math.floor(index / 5) - 2],+ color: [1, 0.9, 0.8],+ intensity: 1 + index,+ radius: 0.05,+ }));+}++function pack(environment, options = {}, parts = [{ name: 'floor', geometry: floorGeometry(), material: { color: [0.5, 0.5, 0.5] } }]) {+ const scene = buildTraceScene(parts, environment);+ const camera = createCamera({ eye: [0, 2, 6], target: [0, 0, 0], fov: 45 }, 32, 16);+ return buildNativeInputV2(scene, camera, { width: 32, height: 16, samples: 4, ...options });+}++function kernelFlags(input) {+ return new Uint32Array(input.kernelParams.buffer, input.kernelParams.byteOffset, STRUCT_STRIDES_V2.kernelParams / 4)[KERNEL_FLAGS_WORD];+}++function nodeViews(input) {+ const stride = STRUCT_STRIDES_V2.lightTreeNode;+ return Array.from({ length: input.lightTreeNodeCount }, (_, index) => {+ const offset = input.lightTreeNodes.byteOffset + index * stride;+ return {+ f32: new Float32Array(input.lightTreeNodes.buffer, offset, stride / 4),+ i32: new Int32Array(input.lightTreeNodes.buffer, offset, stride / 4),+ u32: new Uint32Array(input.lightTreeNodes.buffer, offset, stride / 4),+ };+ });+}++function parentOf(node) {+ return node.i32[12] < 0 ? -1 - node.i32[12] : node.u32[14] & 0xffff;+}++test('the Sobol-Burley sampler is the default and sampler "pcg" sets the opt-out flag', () => {+ assert.equal(kernelFlags(pack({})) & FLAG_PCG_SAMPLER, 0);+ assert.equal(kernelFlags(pack({}, { sampler: 'sobol' })) & FLAG_PCG_SAMPLER, 0);+ assert.equal(kernelFlags(pack({}, { sampler: 'pcg' })) & FLAG_PCG_SAMPLER, FLAG_PCG_SAMPLER);+ assert.throws(() => pack({}, { sampler: 'halton' }), /sampler.*sobol.*pcg/);+});++test('a scene with few lights keeps the cumulative pick, and useLightTree forces or forbids the tree', () => {+ const environment = { pointLights: pointLights(3) };+ assert.equal(pack(environment).lightTreeNodeCount, 0);+ assert.equal(kernelFlags(pack(environment)) & FLAG_USE_LIGHT_TREE, 0);+ assert.equal(pack(environment, { useLightTree: true }).lightTreeNodeCount, 1 + 5);+ assert.equal(pack({ pointLights: pointLights(20) }, { useLightTree: false }).lightTreeNodeCount, 0);+ assert.throws(() => pack(environment, { useLightTree: 'yes' }), /useLightTree/);+});++test('the analytic light tree links every light to the root through its parents and sums their energy', () => {+ const lightCount = 20;+ const input = pack({ pointLights: pointLights(lightCount) });+ assert.equal(kernelFlags(input) & FLAG_USE_LIGHT_TREE, FLAG_USE_LIGHT_TREE);+ assert.equal(kernelFlags(input) & FLAG_USE_EMISSIVE_LIGHT_TREE, 0);+ assert.equal(input.lightTreeNodeCount, 1 + (2 * lightCount - 1));++ const nodes = nodeViews(input);+ const analyticRoot = nodes[0].i32[12];+ assert.equal(nodes[0].u32[13], NO_TREE_ROOT, 'no emissive tree');+ assert.equal(parentOf(nodes[analyticRoot]), 0, 'the root hangs off the directory node');++ let leafEnergy = 0;+ for (let lightIndex = 0; lightIndex < lightCount; lightIndex++) {+ const leaf = nodes[1 + lightIndex];+ assert.ok(leaf.i32[12] < 0, 'leaf marker');+ assert.equal(leaf.u32[13], lightIndex, 'leaf stores its light index');+ leafEnergy += leaf.f32[3];+ let current = 1 + lightIndex;+ for (let depth = 0; current !== analyticRoot; depth++) {+ assert.ok(depth < 32, 'chain reaches the root');+ const parent = parentOf(nodes[current]);+ assert.ok(parent > 0, 'parent is a real node');+ const children = [nodes[parent].i32[12], nodes[parent].u32[13]];+ assert.ok(children.includes(current), 'the parent lists the child');+ current = parent;+ }+ }+ assert.ok(leafEnergy > 0);+ assert.ok(Math.abs(nodes[analyticRoot].f32[3] - leafEnergy) <= leafEnergy * 1e-5, 'root energy is the sum of the leaves');+});++test('a sun, or light-linking masks, keep the analytic lights on the cumulative pick', () => {+ const withSun = pack({ pointLights: pointLights(20), keyColor: [3, 3, 3], lightDirection: [0, 1, 0] });+ assert.equal(kernelFlags(withSun) & FLAG_USE_LIGHT_TREE, 0);+ assert.equal(withSun.lightTreeNodeCount, 0);+});++test('emissive triangles get their own tree, found through the directory node', () => {+ const emissivePanels = Array.from({ length: 12 }, (_, index) => {+ const geometry = floorGeometry();+ geometry.positions = geometry.positions.map((value, position) => (position % 3 === 1 ? 3 : value * 0.1 + (index - 6) * 0.6));+ return { name: `panel-${index}`, geometry, material: { color: [0.5, 0.5, 0.5], emission: 5 } };+ });+ const input = pack({}, {}, emissivePanels);+ assert.equal(kernelFlags(input) & FLAG_USE_EMISSIVE_LIGHT_TREE, FLAG_USE_EMISSIVE_LIGHT_TREE);+ assert.equal(kernelFlags(input) & FLAG_USE_LIGHT_TREE, 0);+ assert.equal(input.emissiveTriangleCount, 24);++ const nodes = nodeViews(input);+ const emissiveRoot = nodes[0].u32[13];+ const leafBase = nodes[0].u32[15];+ assert.notEqual(emissiveRoot, NO_TREE_ROOT);+ assert.equal(leafBase, 1);+ for (let triangle = 0; triangle < input.emissiveTriangleCount; triangle++) {+ let current = leafBase + triangle;+ assert.equal(nodes[current].u32[13], triangle);+ for (let depth = 0; current !== emissiveRoot; depth++) {+ assert.ok(depth < 32);+ current = parentOf(nodes[current]);+ }+ }+});