3D engine that AI agents drive
Add opt-in path regeneration to the Cook cycles kernel (#895)
Nguyen Xuan An17dd4d088ba6
diff --git a/bench/cycles-parity/trace-native.mjs b/bench/cycles-parity/trace-native.mjsindex 265c0095..97bf55c2 100644--- a/bench/cycles-parity/trace-native.mjs+++ b/bench/cycles-parity/trace-native.mjs@@ -96,7 +96,7 @@ function parseLightSamplingOption(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] [--sampler white|sobol-burley] [--light-sampling auto|tree|uniform] [--filter-type box|gaussian|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 white|sobol-burley] [--light-sampling auto|tree|uniform] [--path-regeneration] [--filter-type box|gaussian|blackman-harris] [--filter-width 1.0] [--clamp-direct 0] [--clamp-indirect 0] [--firefly-clamp 1e9] [--noise-threshold 0]');}return {sceneJsonPath: resolve(argumentList[0]),@@ -112,6 +112,7 @@ function parseTraceArguments(argumentList) {lightSampling: parseLightSamplingOption(argumentList),directLighting: String(readFlagValue(argumentList, '--direct-lighting', 'both')),lightTreeProbe: argumentList.includes('--light-tree-probe'),+ pathRegeneration: argumentList.includes('--path-regeneration'),filterWidth: parseNumberOption(argumentList, '--filter-width', 1.0, 0.01),clampDirect: parseNumberOption(argumentList, '--clamp-direct', 0, 0),clampIndirect: parseNumberOption(argumentList, '--clamp-indirect', 0, 0),@@ -174,6 +175,7 @@ async function runCli() {filterType: options.filterType,sampler: options.sampler,lightSampling: options.lightSampling,+ pathRegeneration: options.pathRegeneration,filterWidth: options.filterWidth,clampDirect: options.clampDirect,clampIndirect: options.clampIndirect,diff --git a/changes/895-path-regeneration.md b/changes/895-path-regeneration.mdnew file mode 100644index 00000000..890b9b92--- /dev/null+++ b/changes/895-path-regeneration.md@@ -0,0 +1 @@+- The Cook `cycles` kernel starts a pixel's next sample as soon as a path ends when you pass `pathRegeneration: true` (`--path-regeneration` in `trace-native.mjs`), which cut sampling time by 9% to 37% on four scenes with the same image (#895)diff --git a/docs/cycles-parity.md b/docs/cycles-parity.mdindex 97d99111..f2d77698 100644--- a/docs/cycles-parity.md+++ b/docs/cycles-parity.md@@ -344,6 +344,25 @@ These are per-sample times on one scene. An equal-error comparison between the `---+### Path regeneration (`pathRegeneration`, opt-in)++By default a thread of the `cycles` kernel traces one whole path, then starts the next sample of its pixel, so a group of lanes waits for its longest path before any lane starts again. With `pathRegeneration: true` (`--path-regeneration` in `trace-native.mjs`) the kernel runs one bounce per loop iteration, and a lane whose path ended starts the next sample of the same pixel at once. The sample index, the random numbers and the sums are the same, so the image is the same: the relMSE against the Cycles reference matched to the last digit in all 8 cells below, and so did the mean ratio. Only the time per sample changes.++Sampling time, `960 x 540`, `8` bounces, seed `3`, NVIDIA A10 on Modal, baseline and trial interleaved in one container, three rounds, median and range `[measured]`:++| Scene | spp | Default | `pathRegeneration` | Ratio |+| --- | --- | --- | --- | --- |+| `lit-interior` | 256 | `3.296 s` [3.285-3.358] | `2.112 s` [2.100-2.164] | `0.64` |+| `lit-interior` | 1024 | `12.620 s` [12.340-12.633] | `7.966 s` [7.918-7.992] | `0.63` |+| `glass` | 256 | `2.100 s` [2.097-2.138] | `1.501 s` [1.464-1.614] | `0.71` |+| `glass` | 1024 | `7.639 s` [7.604-7.656] | `5.552 s` [5.492-5.577] | `0.73` |+| `many-lights-500` | 256 | `12.557 s` [12.551-12.645] | `8.567 s` [8.488-8.636] | `0.68` |+| `many-lights-500` | 1024 | `50.041 s` [49.938-50.305] | `33.873 s` [33.737-33.943] | `0.68` |+| `metal` | 256 | `1.277 s` [1.250-1.400] | `1.237 s` [1.163-1.243] | `0.97` |+| `metal` | 1024 | `4.658 s` [4.651-4.679] | `4.224 s` [4.179-4.240] | `0.91` |++The image does not change, so equal error is reached in the ratio's share of the time. The gain is largest where path lengths differ most between neighbouring pixels (the interior, glass and the many-lights scene) and smallest on `metal`, where most paths end at the same depth. One GPU and one batch size (`32` samples per dispatch) were measured in full; `64` and `128` gave `0.66` to `0.71` on `lit-interior` at 256 spp. The option is off by default; the seven-scene 4096 spp parity run passed every gate with the option off and with it on, with identical channel means and relMSE in both runs, and the cargo tests (25), node tests, lobe checks and furnace scenes passed.+### Pixel filter: box versus Blackman-HarrisThe six-scene references use the box filter of width 1, so the box filter stays the default of the `cycles` kernel. Cycles' own default is Blackman-Harris with width 1.5. To show which choice matches Cycles, `render-cycles.py --filter-type blackman-harris --filter-width 1.5` rendered a second Cycles 5.3 reference (4096 spp, seed 1, OptiX) and the `cycles` kernel ran at 1024 spp, seed 1, 8 bounces, 960 x 540 with each filter `[measured]`:diff --git a/packages/render-native/index.mjs b/packages/render-native/index.mjsindex 0c013d34..ad7ad6f3 100644--- a/packages/render-native/index.mjs+++ b/packages/render-native/index.mjs@@ -11,6 +11,8 @@ import {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,@@ -71,6 +73,7 @@ export function resolveNativeKernel(kernel) {export function traceNative(input, options = {}) {validatePackOptions(options, 'traceNative', true);const { sampler, lightSampling } = resolveSamplingOptions(options, 'traceNative');+ validatePathRegenerationOption(options.pathRegeneration, 'traceNative');const { width, height, samples, maxSeconds, kernel, samplesPerDispatch, bootstrapKernel } = options;const selectedKernel = resolveNativeKernel(kernel);const addon = loadAddon();@@ -99,6 +102,9 @@ export function traceNative(input, options = {}) {if (input?.schemaVersion === FORMAT_V2_VERSION && sampler !== undefined) {v2Input = { ...v2Input, kernelParams: withSamplerFlag(v2Input.kernelParams, sampler) };}+ if (input?.schemaVersion === FORMAT_V2_VERSION && options.pathRegeneration !== undefined) {+ v2Input = { ...v2Input, kernelParams: withPathRegenerationFlag(v2Input.kernelParams, options.pathRegeneration) };+ }if (input?.schemaVersion === FORMAT_V2_VERSION && lightSampling !== undefined) {v2Input = { ...v2Input, kernelParams: withLightSamplingFlag(v2Input, lightSampling) };}@@ -172,6 +178,18 @@ function withSamplerFlag(kernelParams, sampler) {return patchedParams;}+// 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);diff --git a/packages/render-native/pack-input-v2.mjs b/packages/render-native/pack-input-v2.mjsindex 978efc9b..90aa0ad2 100644--- a/packages/render-native/pack-input-v2.mjs+++ b/packages/render-native/pack-input-v2.mjs@@ -44,6 +44,7 @@ const KERNEL_FLAG_ORTHOGRAPHIC_CAMERA = 8;const KERNEL_FLAG_ADAPTIVE_SAMPLING = 16;const KERNEL_FLAG_TRANSPARENT_BACKGROUND = 32;export const KERNEL_FLAG_WHITE_NOISE_SAMPLER = 64;+export const KERNEL_FLAG_PATH_REGENERATION = 1024;const INSTANCE_DEFAULT_VISIBILITY = 1 | 2 | 4 | 8 | 16 | 32;const INSTANCE_FLAG_NEGATIVE_SCALE = 64;@@ -1549,6 +1550,15 @@ export function resolveSamplingOptions(options, callerName) {return { sampler, lightSampling };}+/** Throws unless `pathRegeneration` is undefined, true or false. */+export function validatePathRegenerationOption(pathRegeneration, callerName) {+ if (pathRegeneration !== undefined && typeof pathRegeneration !== 'boolean') {+ throw new TypeError(+ `${callerName}: \`pathRegeneration\` must be true, false (default) or left out, got ${JSON.stringify(pathRegeneration)}.`+ );+ }+}+/** True when the kernel should pick lights through the light tree for this scene and mode. */export function resolveUseLightTree(lightSampling, emitterCount, lightTreeNodeCount) {if (lightTreeNodeCount <= 0 || lightSampling === 'uniform') {diff --git a/packages/render-native/src/cycles/abi.wgsl b/packages/render-native/src/cycles/abi.wgslindex 00358229..d2db86db 100644--- a/packages/render-native/src/cycles/abi.wgsl+++ b/packages/render-native/src/cycles/abi.wgsl@@ -46,6 +46,9 @@ const KERNEL_FLAG_LIGHT_TREE_PROBE: u32 = 128u;// reverse: no direct light samples and emissive hits count fully (BSDF only). Both clear is the normal MIS combination.const KERNEL_FLAG_TEST_NEE_ONLY: u32 = 256u;const KERNEL_FLAG_TEST_BSDF_ONLY: u32 = 512u;+// Set: a path that ends is replaced at once by the pixel's next sample (one bounce per loop iteration). Clear (default): each path+// runs to its end before the next one starts. The image is the same either way; only the time per sample differs.+const KERNEL_FLAG_PATH_REGENERATION: u32 = 1024u;// `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 4ec6fe39..c962da45 100644--- a/packages/render-native/src/cycles/integrator.wgsl+++ b/packages/render-native/src/cycles/integrator.wgsl@@ -713,53 +713,111 @@ fn main(@builtin(global_invocation_id) global_id: vec3<u32>) {var batch_normal = vec3<f32>(0.0);var taken_in_batch = 0u;- for (var s = 0u; s < sample_count; s += 1u) {- if (s > 0u && int_pixel_has_converged(stats)) {- stats.z = 1.0;- break;+ // Per-path state lives outside the loops so that, with KERNEL_FLAG_PATH_REGENERATION, a path that ends is replaced by the+ // pixel's next sample at once instead of idling until the longest path of the dispatch ends. Without the flag a whole path+ // runs inside one iteration of the outer loop, which is the order of work before regeneration existed.+ let steps_per_iteration = select(INT_MAX_PATH_STEPS, 1u, (kernel_params.kernel_flags & KERNEL_FLAG_PATH_REGENERATION) != 0u);+ var rng = smp_init(pixel_x, pixel_y, kernel_params.sample_offset, kernel_params.seed);+ var next_sample = 0u;+ var path_active = false;+ var path_step = 0u;++ var ray_origin = vec3<f32>(0.0);+ var ray_dir = vec3<f32>(0.0);+ var ray_t_min = 0.0;+ var ray_t_max = 0.0;+ var ray_visibility = INSTANCE_VISIBILITY_CAMERA;+ var self_instance = INVALID_INDEX;+ var self_triangle = INVALID_INDEX;++ var throughput = vec3<f32>(1.0);+ var medium_sigma = vec3<f32>(0.0);+ var in_medium = false;+ var is_camera_ray = true;+ var is_transparent_bg_ray = false;+ var mis_skip = true;+ var prev_bsdf_pdf = 0.0;+ var min_ray_pdf = 1.0e30;+ var prev_recv_lo = 0xFFFFFFFFu;+ var prev_recv_hi = 0xFFFFFFFFu;+ var terminate_on_hit = false;+ var terminate_on_next_surface = false;++ var bounce = 0u;+ var diffuse_bounces = 0u;+ var glossy_bounces = 0u;+ var transmission_bounces = 0u;+ var volume_bounces = 0u;+ var transparent_bounces = 0u;++ var sample_radiance = vec3<f32>(0.0);+ var first_depth = 0.0;+ var first_albedo = vec3<f32>(0.0);+ var first_normal = vec3<f32>(0.0);+ var recorded_features = false;++ loop {+ if (!path_active) {+ if (next_sample >= sample_count) {+ break;+ }+ if (next_sample > 0u && int_pixel_has_converged(stats)) {+ stats.z = 1.0;+ break;+ }++ let sample_index = kernel_params.sample_offset + next_sample;+ next_sample += 1u;+ rng = smp_init(pixel_x, pixel_y, sample_index, kernel_params.seed);+ let filter_offset = flt_sample_offset(smp_next_2d(&rng));+ let lens_uv = smp_next_2d(&rng);+ let cam_ray = cam_generate_ray(pixel_x, pixel_y, filter_offset, lens_uv);++ ray_origin = cam_ray.origin;+ ray_dir = cam_ray.direction;+ ray_t_min = cam_ray.t_min;+ ray_t_max = cam_ray.t_max;+ ray_visibility = INSTANCE_VISIBILITY_CAMERA;+ self_instance = INVALID_INDEX;+ self_triangle = INVALID_INDEX;++ throughput = vec3<f32>(1.0);+ medium_sigma = vec3<f32>(0.0);+ in_medium = false;+ is_camera_ray = true;+ is_transparent_bg_ray = (kernel_params.kernel_flags & KERNEL_FLAG_TRANSPARENT_BACKGROUND) != 0u;+ mis_skip = true;+ prev_bsdf_pdf = 0.0;+ min_ray_pdf = 1.0e30;+ prev_recv_lo = 0xFFFFFFFFu;+ prev_recv_hi = 0xFFFFFFFFu;+ terminate_on_hit = false;+ terminate_on_next_surface = false;++ bounce = 0u;+ diffuse_bounces = 0u;+ glossy_bounces = 0u;+ transmission_bounces = 0u;+ volume_bounces = 0u;+ transparent_bounces = 0u;++ sample_radiance = vec3<f32>(0.0);+ first_depth = 0.0;+ first_albedo = vec3<f32>(0.0);+ first_normal = vec3<f32>(0.0);+ recorded_features = false;+ path_step = 0u;+ path_active = true;}- let sample_index = kernel_params.sample_offset + s;- var rng = smp_init(pixel_x, pixel_y, sample_index, kernel_params.seed);- let filter_offset = flt_sample_offset(smp_next_2d(&rng));- let lens_uv = smp_next_2d(&rng);- let cam_ray = cam_generate_ray(pixel_x, pixel_y, filter_offset, lens_uv);-- var ray_origin = cam_ray.origin;- var ray_dir = cam_ray.direction;- var ray_t_min = cam_ray.t_min;- var ray_t_max = cam_ray.t_max;- var ray_visibility = INSTANCE_VISIBILITY_CAMERA;- var self_instance = INVALID_INDEX;- var self_triangle = INVALID_INDEX;-- var throughput = vec3<f32>(1.0);- var medium_sigma = vec3<f32>(0.0);- var in_medium = false;- var is_camera_ray = true;- var is_transparent_bg_ray = (kernel_params.kernel_flags & KERNEL_FLAG_TRANSPARENT_BACKGROUND) != 0u;- var mis_skip = true;- var prev_bsdf_pdf = 0.0;- var min_ray_pdf = 1.0e30;- var prev_recv_lo = 0xFFFFFFFFu;- var prev_recv_hi = 0xFFFFFFFFu;- var terminate_on_hit = false;- var terminate_on_next_surface = false;-- var bounce = 0u;- var diffuse_bounces = 0u;- var glossy_bounces = 0u;- var transmission_bounces = 0u;- var volume_bounces = 0u;- var transparent_bounces = 0u;-- var sample_radiance = vec3<f32>(0.0);- var first_depth = 0.0;- var first_albedo = vec3<f32>(0.0);- var first_normal = vec3<f32>(0.0);- var recorded_features = false;-- for (var step = 0u; step < INT_MAX_PATH_STEPS; step += 1u) {+ for (var iteration_step = 0u; iteration_step < steps_per_iteration; iteration_step += 1u) {+ // A `break` below ends the path. Only the places that go on to the next step set `path_active` again.+ path_active = false;+ if (path_step >= INT_MAX_PATH_STEPS) {+ break;+ }+ let step = path_step;+ path_step += 1u;let surface_hit = int_trace_closest_surface(ray_origin,ray_dir,@@ -865,6 +923,7 @@ fn main(@builtin(global_invocation_id) global_id: vec3<u32>) {prev_recv_lo = 0xFFFFFFFFu;prev_recv_hi = 0xFFFFFFFFu;lgt_remember_mis_origin(scatter_pos, ray_dir, false, false);+ path_active = true;continue;}@@ -943,6 +1002,7 @@ fn main(@builtin(global_invocation_id) global_id: vec3<u32>) {ray_t_min = surface_hit.t + max(kernel_params.ray_epsilon, 1.0e-6);self_instance = point.instance_index;self_triangle = point.triangle_index;+ path_active = true;continue;}}@@ -1013,6 +1073,7 @@ fn main(@builtin(global_invocation_id) global_id: vec3<u32>) {ray_t_min = surface_hit.t + max(kernel_params.ray_epsilon, 1.0e-6);self_instance = point.instance_index;self_triangle = point.triangle_index;+ path_active = true;continue;}@@ -1082,18 +1143,21 @@ fn main(@builtin(global_invocation_id) global_id: vec3<u32>) {prev_recv_lo = point.light_group_mask_lo;prev_recv_hi = point.light_group_mask_hi;lgt_remember_mis_origin(point.position, point.shading_normal, closure_has_transmission, picks_through_tree);+ path_active = true;}- let exposed = int_sanitize_radiance(sample_radiance * exposure);- let lum = int_luminance(exposed);- batch_radiance += exposed;- batch_depth += select(0.0, first_depth, first_depth >= 0.0 && first_depth < 1.0e29);- batch_albedo += int_sanitize_radiance(first_albedo);- batch_normal += first_normal;- stats.x += lum;- stats.y += lum * lum;- stats.w += 1.0;- taken_in_batch += 1u;+ if (!path_active) {+ let exposed = int_sanitize_radiance(sample_radiance * exposure);+ let lum = int_luminance(exposed);+ batch_radiance += exposed;+ batch_depth += select(0.0, first_depth, first_depth >= 0.0 && first_depth < 1.0e29);+ batch_albedo += int_sanitize_radiance(first_albedo);+ batch_normal += first_normal;+ stats.x += lum;+ stats.y += lum * lum;+ stats.w += 1.0;+ taken_in_batch += 1u;+ }}if (taken_in_batch > 0u) {diff --git a/tests/native-path-regeneration.test.js b/tests/native-path-regeneration.test.jsnew file mode 100644index 00000000..59e195a6--- /dev/null+++ b/tests/native-path-regeneration.test.js@@ -0,0 +1,40 @@+import assert from 'node:assert/strict';+import test from 'node:test';+import { withPathRegenerationFlag } from '../packages/render-native/index.mjs';+import {+ KERNEL_FLAG_PATH_REGENERATION,+ KERNEL_PARAMS_V2_KERNEL_FLAGS_BYTE_OFFSET,+ STRUCT_STRIDES_V2,+ validatePathRegenerationOption,+} from '../packages/render-native/pack-input-v2.mjs';++function readKernelFlags(kernelParams) {+ const view = new DataView(kernelParams.buffer, kernelParams.byteOffset, kernelParams.byteLength);+ return view.getUint32(KERNEL_PARAMS_V2_KERNEL_FLAGS_BYTE_OFFSET, true);+}++function makeKernelParams(flags) {+ const kernelParams = new Uint8Array(STRUCT_STRIDES_V2.kernelParams);+ new DataView(kernelParams.buffer).setUint32(KERNEL_PARAMS_V2_KERNEL_FLAGS_BYTE_OFFSET, flags, true);+ return kernelParams;+}++test('the path regeneration flag is bit 10 and does not collide with the other kernel flags', () => {+ assert.equal(KERNEL_FLAG_PATH_REGENERATION, 1024);+});++test('withPathRegenerationFlag sets and clears only its own bit and leaves the input untouched', () => {+ const original = makeKernelParams(1 | 64);+ const enabled = withPathRegenerationFlag(original, true);+ assert.equal(readKernelFlags(enabled), 1 | 64 | 1024);+ assert.equal(readKernelFlags(original), 1 | 64);+ assert.equal(readKernelFlags(withPathRegenerationFlag(enabled, false)), 1 | 64);+});++test('pathRegeneration accepts true, false and undefined, and rejects anything else', () => {+ validatePathRegenerationOption(undefined, 'caller');+ validatePathRegenerationOption(true, 'caller');+ validatePathRegenerationOption(false, 'caller');+ assert.throws(() => validatePathRegenerationOption('on', 'caller'), /`pathRegeneration` must be true, false/);+ assert.throws(() => validatePathRegenerationOption(1, 'caller'), TypeError);+});