Skip to content

armgit / 67.js

Public Imported from GitHub
0

3D engine that AI agents drive

Refuse session frames that change scene-bound kernel words, keep creation costs after a failed first frame, share the kernel parameter patches (#896)

Nguyen Xuan An43752d298984
diff --git a/packages/render-native/README.md b/packages/render-native/README.md
index 9e20e2d9..091062cd 100644
--- a/packages/render-native/README.md
+++ b/packages/render-native/README.md
@@ -66,4 +66,8 @@ session.close(); // frees the
`renderOptions.kernelParams` is the `kernelParams` of another `buildNativeInputV2` call on the same scene, which is how a frame gets another camera (or seed, bounces or filter). The seven record counts must match the session scene, or the frame throws and names the count. Changing the scene itself (geometry, materials, lights) needs a new session.
+A frame may change these words of the 320 byte block: the camera, lens, aperture and sensor shift (bytes 112 to 191), `seed`, the bounce limits, clamps, filter, adaptive sampling, `film_exposure`, `filter_glossy`, the environment rotation and colour (204, 208), the fog fields (224 to 267) and `kernel_flags`. Fog and the kernel flags select kernel variants, so such a frame recompiles (`pipelineReused` is false). The other words describe data the session uploaded or compiled for, and a frame that changes one throws and names it: the seven record counts (84 to 108), `env_width`, `env_height`, `env_cdf_offset`, `env_total_weight` (192, 196, 200, 220), `emissive_total_weight`, `analytic_light_total_weight` (268, 272), `ies_table_offset` (284), `background_mis_weight` (292) and `sobol_table_offset` (296). A frame with another HDRI, or one where the session had none, needs a new session. A frame that fails leaves the creation costs for the next frame that succeeds, which then reports them.
+
+A frame may change these words of the 320 byte block and no others of the scene: the camera, lens, aperture and sensor shift (bytes 112 to 191), , the bounce limits, clamps, filter, adaptive sampling, , , the environment rotation and colour (204, 208), the fog fields (224 to 267) and . Fog and the kernel flags select kernel variants, so such a frame recompiles ( is false). These words describe data the session uploaded or compiled for, and a frame that changes one throws and names it: the seven record counts (84 to 108), , , , (192, 196, 200, 220), , (268, 272), , (284, 296) and (292). A frame with another HDRI, or with one where the session had none, therefore needs a new session. A frame that fails leaves the creation costs for the next frame that succeeds, which then reports them.
+
A frame is byte-identical to the `traceNative` render of the same input and options: `traceNative` runs a session that renders once. `render` after `close()` throws, and so does a frame on a session whose device was lost; the error says to create a new session. The film does not carry samples from one frame to the next, and nothing in the scene can be updated in place yet.
diff --git a/packages/render-native/index.mjs b/packages/render-native/index.mjs
index 64061011..4ce37456 100644
--- a/packages/render-native/index.mjs
+++ b/packages/render-native/index.mjs
@@ -91,25 +91,8 @@ export function traceNative(input, options = {}) {
let v2Input = input?.schemaVersion === FORMAT_V2_VERSION
? input
: upgradeNativeInputV1ToV2(input, options);
- const explicitFilterGlossy = options.filterGlossy ?? options.blurGlossy;
- if (input?.schemaVersion === FORMAT_V2_VERSION && explicitFilterGlossy !== undefined) {
- const rawFilterGlossy = Number(explicitFilterGlossy);
- const resolvedFilterGlossy = Number.isFinite(rawFilterGlossy) && rawFilterGlossy > 0 ? rawFilterGlossy : 0.0;
- const patchedParams = new Uint8Array(v2Input.kernelParams);
- new DataView(patchedParams.buffer, patchedParams.byteOffset, patchedParams.byteLength).setFloat32(KERNEL_PARAMS_V2_FILTER_GLOSSY_BYTE_OFFSET, resolvedFilterGlossy, true);
- v2Input = { ...v2Input, kernelParams: patchedParams };
- }
- if (input?.schemaVersion === FORMAT_V2_VERSION && hasFilterOptions(options)) {
- v2Input = { ...v2Input, kernelParams: withFilterOptions(v2Input.kernelParams, 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) };
+ if (input?.schemaVersion === FORMAT_V2_VERSION) {
+ v2Input = { ...v2Input, kernelParams: patchedCyclesKernelParams(v2Input, v2Input.kernelParams, options, 'traceNative') };
}
return addon.traceSceneCycles(v2Input, {
width,
@@ -336,9 +319,9 @@ function mergeDefinedOptions(sessionOptions, renderOptions) {
return merged;
}
-// The kernel parameters of a FORMAT-v2 input after the sampling, filter and light options of `options`: the same patches, in the
-// same order, that `traceNative` applies to a v2 input.
-function patchedSessionKernelParams(v2Input, kernelParams, options, callerName) {
+// 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);
@@ -371,7 +354,7 @@ export function resolveSessionCreation(input, options) {
}
requireCyclesKernelOption(options.kernel, 'createNativeSession');
validatePackOptions(options, 'createNativeSession');
- return { ...input, kernelParams: patchedSessionKernelParams(input, input.kernelParams, options, 'createNativeSession') };
+ return { ...input, kernelParams: patchedCyclesKernelParams(input, input.kernelParams, options, 'createNativeSession') };
}
// Exported for tests; not part of the public API.
@@ -387,7 +370,7 @@ export function resolveSessionFrame(sessionInput, sessionOptions, renderOptions)
requireSessionKernelParams(renderOptions.kernelParams, 'NativeSession.render');
baseKernelParams = renderOptions.kernelParams;
}
- const kernelParams = patchedSessionKernelParams(sessionInput, baseKernelParams, options, 'NativeSession.render');
+ const kernelParams = patchedCyclesKernelParams(sessionInput, baseKernelParams, options, 'NativeSession.render');
const { width, height, samples, samplesPerDispatch, maxSeconds, bootstrapKernel, denoise } = options;
return { width, height, samples, samplesPerDispatch, maxSeconds, bootstrapKernel, denoise, kernelParams };
}
diff --git a/packages/render-native/src/cycles/mod.rs b/packages/render-native/src/cycles/mod.rs
index 0911d905..02b0dd9d 100644
--- a/packages/render-native/src/cycles/mod.rs
+++ b/packages/render-native/src/cycles/mod.rs
@@ -164,29 +164,44 @@ pub(crate) fn check_counts_match_kernel_params(input: &NativeTraceInputV2) -> Re
Ok(())
}
-/// Checks that a frame's kernel parameters describe the scene the session holds: the seven record counts must equal the
-/// counts of the parameters the session was created with. Everything else (camera, bounces, seed, filter, flags) may change.
+/// The words of `KernelParamsV2` that describe scene data a session uploaded or compiled for once: the record counts that
+/// size the buffers, the environment table (size, offset and total weight), the offsets into the texel pool and the light
+/// selection weights. A frame may not change them; every other word (camera, lens, seed, bounces, clamps, filter, adaptive
+/// sampling, exposure, fog, kernel flags) is a per-frame setting. Fog and the kernel flags select pipeline variants, which a
+/// session recompiles on its own when they change.
+const SCENE_BOUND_FIELDS: [(&str, usize); 16] = [
+ ("instanceCount", KP_INSTANCE_COUNT_BYTE),
+ ("triangleCount", KP_TRIANGLE_COUNT_BYTE),
+ ("materialCount", KP_MATERIAL_COUNT_BYTE),
+ ("emissiveTriangleCount", KP_EMISSIVE_TRIANGLE_COUNT_BYTE),
+ ("lightCount", KP_LIGHT_COUNT_BYTE),
+ ("lightTreeNodeCount", KP_LIGHT_TREE_NODE_COUNT_BYTE),
+ ("textureCount", KP_TEXTURE_COUNT_BYTE),
+ ("envWidth", KP_ENV_WIDTH_BYTE),
+ ("envHeight", KP_ENV_HEIGHT_BYTE),
+ ("envCdfOffset", 200),
+ ("envTotalWeight", KP_ENV_TOTAL_WEIGHT_BYTE),
+ ("emissiveTotalWeight", 268),
+ ("analyticLightTotalWeight", 272),
+ ("iesTableOffset", 284),
+ ("backgroundMisWeight", 292),
+ ("sobolTableOffset", 296),
+];
+
+/// Checks that a frame's kernel parameters describe the scene the session holds: every scene-bound word (see
+/// `SCENE_BOUND_FIELDS`) must equal the one the session was created with.
pub(crate) fn check_frame_params_keep_scene_counts(session_kernel_params: &[u8], frame_kernel_params: &[u8]) -> Result<()> {
- let counts = [
- ("instanceCount", KP_INSTANCE_COUNT_BYTE),
- ("triangleCount", KP_TRIANGLE_COUNT_BYTE),
- ("materialCount", KP_MATERIAL_COUNT_BYTE),
- ("emissiveTriangleCount", KP_EMISSIVE_TRIANGLE_COUNT_BYTE),
- ("lightCount", KP_LIGHT_COUNT_BYTE),
- ("lightTreeNodeCount", KP_LIGHT_TREE_NODE_COUNT_BYTE),
- ("textureCount", KP_TEXTURE_COUNT_BYTE),
- ];
- for (name, byte_offset) in counts {
+ for (name, byte_offset) in SCENE_BOUND_FIELDS {
if session_kernel_params.len() < byte_offset + 4 || frame_kernel_params.len() < byte_offset + 4 {
return Err(failure(format!(
"kernelParams must hold the 320 byte KernelParamsV2 block to read {name} at byte {byte_offset}."
)));
}
- let session_count = read_u32_le(session_kernel_params, byte_offset);
- let frame_count = read_u32_le(frame_kernel_params, byte_offset);
- if session_count != frame_count {
+ let session_word = read_u32_le(session_kernel_params, byte_offset);
+ let frame_word = read_u32_le(frame_kernel_params, byte_offset);
+ if session_word != frame_word {
return Err(failure(format!(
- "The kernelParams of this frame say {name} is {frame_count}, but the session scene has {session_count}. A session renders one scene; pack the frame from the same scene (only the camera and the render settings may differ) or create a new session."
+ "The kernelParams of this frame change {name} (byte {byte_offset}) from {session_word} to {frame_word} (raw 32 bit words), but the session scene was uploaded with the first value. A session renders one scene; pack the frame from the same scene (only the camera and the render settings may differ) or create a new session."
)));
}
}
@@ -713,6 +728,47 @@ mod specialization_tests {
assert!(check_frame_params_keep_scene_counts(&session_params, truncated).is_err());
}
+ #[test]
+ fn a_frame_may_not_change_any_scene_bound_word_and_the_error_names_it() {
+ let session_params = make_kp(0, 0.0, 512, 256, 3.0);
+ for (name, byte_offset) in SCENE_BOUND_FIELDS {
+ let mut changed = session_params.clone();
+ changed[byte_offset..byte_offset + 4].copy_from_slice(&0x1234_5678u32.to_le_bytes());
+ let message = check_frame_params_keep_scene_counts(&session_params, &changed)
+ .expect_err("a changed scene-bound word must be refused")
+ .to_string();
+ assert!(message.contains(name), "{name}: {message}");
+ assert!(message.contains("create a new session"), "{name}: {message}");
+ }
+ }
+
+ #[test]
+ fn a_frame_with_another_hdri_or_an_environment_the_session_lacks_is_refused() {
+ let with_environment = make_kp(0, 0.0, 512, 256, 3.0);
+ let other_size = make_kp(0, 0.0, 1024, 512, 3.0);
+ let no_environment = make_kp(0, 0.0, 0, 0, 0.0);
+ let message = check_frame_params_keep_scene_counts(&with_environment, &other_size).unwrap_err().to_string();
+ assert!(message.contains("envWidth"), "{message}");
+ assert!(check_frame_params_keep_scene_counts(&no_environment, &with_environment).is_err());
+ assert!(check_frame_params_keep_scene_counts(&with_environment, &no_environment).is_err());
+ }
+
+ #[test]
+ fn per_frame_settings_may_change_freely() {
+ let session_params = make_kp(0, 0.0, 512, 256, 3.0);
+ let scene_bound: Vec<usize> = SCENE_BOUND_FIELDS.iter().map(|(_, offset)| *offset).collect();
+ // Every 4 byte word after the header except the scene-bound ones (camera, lens, seed, bounces, clamps, filter,
+ // fog, exposure, flags, adaptive sampling) is a setting of the frame.
+ for byte_offset in (8..304).step_by(4).filter(|offset| !scene_bound.contains(offset)) {
+ let mut changed = session_params.clone();
+ changed[byte_offset..byte_offset + 4].copy_from_slice(&0x3f80_0000u32.to_le_bytes());
+ assert!(
+ check_frame_params_keep_scene_counts(&session_params, &changed).is_ok(),
+ "byte {byte_offset} is a per-frame setting"
+ );
+ }
+ }
+
fn opaque_inputs(metallic: f32, transmission_weight: f32) -> BaseLayerInputs {
BaseLayerInputs {
metallic,
diff --git a/packages/render-native/src/host/cycles_session.rs b/packages/render-native/src/host/cycles_session.rs
index 4372421c..00ee4da7 100644
--- a/packages/render-native/src/host/cycles_session.rs
+++ b/packages/render-native/src/host/cycles_session.rs
@@ -66,6 +66,7 @@ pub(crate) struct CyclesRender {
}
/// What creating the session cost; the first frame reports it.
+#[derive(Clone, Copy)]
struct CreationCosts {
setup_seconds: f64,
upload_seconds: f64,
@@ -232,7 +233,7 @@ impl CyclesSession {
let frame_kernel_params = self.frame_kernel_params(request.kernel_params)?;
let frame_index = self.renders_completed;
- let creation_costs = self.creation_costs.take();
+ let creation_costs = self.creation_costs;
let acceleration_reused = creation_costs.is_none();
let context = &self.context;
let gpu = self.gpu.as_mut().ok_or_else(session_closed_failure)?;
@@ -278,6 +279,7 @@ impl CyclesSession {
request.max_seconds,
)?;
self.renders_completed = frame_index + 1;
+ self.creation_costs = None;
let report = CyclesRenderReport {
setup_seconds: creation_costs.as_ref().map_or(0.0, |costs| costs.setup_seconds),
diff --git a/tests/native-session.test.js b/tests/native-session.test.js
index 6d564358..e38c2bf8 100644
--- a/tests/native-session.test.js
+++ b/tests/native-session.test.js
@@ -326,3 +326,38 @@ test('rendering after close throws and the card is free for a new session', { sk
fresh.close();
}
});
+
+const ENV_WIDTH_BYTE_OFFSET = 192;
+const SOBOL_TABLE_OFFSET_BYTE_OFFSET = 296;
+
+test('a frame that changes the environment table shape or a texel pool offset is refused', { skip: skipWithoutAddon }, () => {
+ const input = roomInput([0, 2.2, 6]);
+ const session = createNativeSession(input);
+ try {
+ for (const [byteOffset, fieldName] of [[ENV_WIDTH_BYTE_OFFSET, /envWidth/], [SOBOL_TABLE_OFFSET_BYTE_OFFSET, /sobolTableOffset/]]) {
+ const changed = new Uint8Array(input.kernelParams);
+ const view = new DataView(changed.buffer);
+ view.setUint32(byteOffset, view.getUint32(byteOffset, true) + 64, true);
+ assert.throws(() => session.render({ ...IMAGE_OPTIONS, kernelParams: changed }), { message: fieldName });
+ }
+ } finally {
+ session.close();
+ }
+});
+
+test('a first frame that fails leaves the creation costs for the retry', { skip: skipWithoutAddon }, () => {
+ const input = roomInput([0, 2.2, 6]);
+ const options = { ...IMAGE_OPTIONS, kernel: 'cycles' };
+ const session = createNativeSession(input);
+ try {
+ assert.throws(() => session.render({ ...options, samples: 4096, maxSeconds: 1e-6 }), { message: /time limit/ });
+ const retry = session.render(options);
+ assert.equal(retry.frameIndex, 0);
+ assert.equal(retry.accelerationReused, false);
+ assert.ok(retry.setupSeconds > 0, 'the creation setup seconds are reported by the first frame that succeeds');
+ assertSameBytes(traceNative(input, options), retry, 'the retry against the one-shot render');
+ assert.equal(session.render(options).accelerationReused, true);
+ } finally {
+ session.close();
+ }
+});