Skip to content

armgit / 67.js

Public Imported from GitHub
0

3D engine that AI agents drive

Derive the Cycles lobe bounds from the kernel's own cutoff and check the napi counts against kernel_params (#894)

Nguyen Xuan An6f2728d1da5a
diff --git a/packages/render-native/src/cycles/mod.rs b/packages/render-native/src/cycles/mod.rs
index 1f2e736b..f8c39cc3 100644
--- a/packages/render-native/src/cycles/mod.rs
+++ b/packages/render-native/src/cycles/mod.rs
@@ -18,6 +18,13 @@ const KP_ENV_WIDTH_BYTE: usize = 192; // u32[48]
const KP_ENV_HEIGHT_BYTE: usize = 196; // u32[49]
const KP_ENV_TOTAL_WEIGHT_BYTE: usize = 220; // f32[55]
const KP_VOLUME_DENSITY_BYTE: usize = 236; // f32[59]
+const KP_INSTANCE_COUNT_BYTE: usize = 84; // u32[21]
+const KP_TRIANGLE_COUNT_BYTE: usize = 88; // u32[22]
+const KP_MATERIAL_COUNT_BYTE: usize = 92; // u32[23]
+const KP_EMISSIVE_TRIANGLE_COUNT_BYTE: usize = 96; // u32[24]
+const KP_LIGHT_COUNT_BYTE: usize = 100; // u32[25]
+const KP_LIGHT_TREE_NODE_COUNT_BYTE: usize = 104; // u32[26]
+const KP_TEXTURE_COUNT_BYTE: usize = 108; // u32[27]
// ---- MaterialRecord byte offsets (256-byte stride, verified against pack-input-v2.mjs) ----
const MAT_METALLIC_BYTE: usize = 12; // f32[3]
@@ -76,6 +83,84 @@ fn read_f32_le(bytes: &[u8], byte_offset: usize) -> f32 {
f32::from_le_bytes(bytes[byte_offset..byte_offset + 4].try_into().unwrap())
}
+/// The weight below which `closure.wgsl` drops a layer (`CLOSURE_WEIGHT_CUTOFF`). The host bounds below use the
+/// same value and the same f32 arithmetic, so a lobe the kernel can add is never left out of the bound.
+const CLOSURE_WEIGHT_CUTOFF: f32 = 1.0e-5;
+
+/// The material fields that decide how many metal, glass, specular and diffuse lobes the kernel can build.
+struct BaseLayerInputs {
+ metallic: f32,
+ /// A metallic roughness texture multiplies metallic by a value in [0, 1], so metallic can be anything up to its record value.
+ metallic_from_texture: bool,
+ transmission_weight: f32,
+ transmission_from_texture: bool,
+ thin_walled: bool,
+}
+
+/// Upper bound on the lobes `closure_build` adds for the metal, glass, specular and diffuse layers of one material.
+/// It follows the kernel: each layer is added only while its weight exceeds the cutoff and the weight left for the
+/// layers below (never more than 1, shrinking by `1 - metallic` and `1 - transmission`) still exceeds it.
+/// A texture can only lower a weight, so it keeps a layer possible and stops the host assuming the weight is spent.
+fn base_layer_lobe_bound(inputs: &BaseLayerInputs) -> u32 {
+ let metallic = inputs.metallic.clamp(0.0, 1.0);
+ let transmission = inputs.transmission_weight.clamp(0.0, 1.0);
+ let mut remaining_weight: f32 = 1.0;
+ let mut lobes: u32 = 0;
+
+ let metal_possible = inputs.metallic_from_texture || metallic > CLOSURE_WEIGHT_CUTOFF;
+ if metal_possible {
+ lobes += 1;
+ if !inputs.metallic_from_texture {
+ remaining_weight *= 1.0 - metallic;
+ }
+ }
+
+ let glass_possible = (inputs.transmission_from_texture || transmission > CLOSURE_WEIGHT_CUTOFF)
+ && remaining_weight > CLOSURE_WEIGHT_CUTOFF;
+ if glass_possible {
+ lobes += if inputs.thin_walled { 2 } else { 1 };
+ if !inputs.transmission_from_texture {
+ remaining_weight *= 1.0 - transmission;
+ }
+ }
+
+ if remaining_weight > CLOSURE_WEIGHT_CUTOFF {
+ // One dielectric specular lobe and one diffuse lobe.
+ lobes += 2;
+ }
+ lobes
+}
+
+/// Checks that the counts the specializer reads from the napi input equal the counts the kernel reads from
+/// `kernel_params`, so the specialized flags and lobe bounds describe the data the shader really walks.
+pub(crate) fn check_counts_match_kernel_params(input: &NativeTraceInputV2) -> Result<()> {
+ let kernel_params = &input.kernel_params;
+ let counts = [
+ ("instanceCount", input.instance_count, KP_INSTANCE_COUNT_BYTE),
+ ("triangleCount", input.triangle_count, KP_TRIANGLE_COUNT_BYTE),
+ ("materialCount", input.material_count, KP_MATERIAL_COUNT_BYTE),
+ ("emissiveTriangleCount", input.emissive_triangle_count, KP_EMISSIVE_TRIANGLE_COUNT_BYTE),
+ ("lightCount", input.light_count, KP_LIGHT_COUNT_BYTE),
+ ("lightTreeNodeCount", input.light_tree_node_count, KP_LIGHT_TREE_NODE_COUNT_BYTE),
+ ("textureCount", input.texture_count, KP_TEXTURE_COUNT_BYTE),
+ ];
+ for (name, input_count, byte_offset) in counts {
+ if kernel_params.len() < byte_offset + 4 {
+ return Err(failure(format!(
+ "kernelParams holds {} bytes, too few to read {name} at byte {byte_offset}. Pass the 320 byte KernelParamsV2 block.",
+ kernel_params.len()
+ )));
+ }
+ let kernel_count = read_u32_le(kernel_params, byte_offset);
+ if kernel_count != input_count {
+ return Err(failure(format!(
+ "{name} is {input_count} in the input but {kernel_count} in kernelParams (byte {byte_offset}). The two must match; pack both from the same scene."
+ )));
+ }
+ }
+ Ok(())
+}
+
/// Specializes the assembled Cycles kernel source for the given scene input, replacing
/// `const SCENE_HAS_*: bool = true;` sentinel declarations with the actual scene-derived values.
/// The sentinel pattern is `true` (conservative default) so the kernel compiles and renders
@@ -173,22 +258,15 @@ pub(crate) fn specialize_cycles_kernel(source: &str, input: &NativeTraceInputV2)
|| alpha_tex >= 0
|| (flags & MATERIAL_FLAG_TRANSPARENT_SHADOW) != 0,
);
- let sheen_lobe = u32::from(sheen_weight > 1.0e-5 || sheen_tex >= 0);
- let coat_lobe = u32::from(coat_weight > 1.0e-5 || coat_roughness_tex >= 0);
- let glass_lobes = if transmission_weight > 1.0e-5 || transmission_tex >= 0 {
- if (flags & MATERIAL_FLAG_THIN_WALLED) != 0 { 2 } else { 1 }
- } else {
- 0
- };
- let pure_metal = metallic >= 1.0 - 1.0e-5 && metallic_roughness_tex < 0;
- let pure_glass = !pure_metal && transmission_weight >= 1.0 - 1.0e-5 && transmission_tex < 0 && metallic <= 1.0e-5 && metallic_roughness_tex < 0;
- let base_lobes = if pure_metal {
- 1
- } else if pure_glass {
- glass_lobes.max(1)
- } else {
- u32::from(metallic > 1.0e-5 || metallic_roughness_tex >= 0) + glass_lobes + 2
- };
+ let sheen_lobe = u32::from(sheen_weight > CLOSURE_WEIGHT_CUTOFF || sheen_tex >= 0);
+ let coat_lobe = u32::from(coat_weight > CLOSURE_WEIGHT_CUTOFF || coat_roughness_tex >= 0);
+ let base_lobes = base_layer_lobe_bound(&BaseLayerInputs {
+ metallic,
+ metallic_from_texture: metallic_roughness_tex >= 0,
+ transmission_weight,
+ transmission_from_texture: transmission_tex >= 0,
+ thin_walled: (flags & MATERIAL_FLAG_THIN_WALLED) != 0,
+ });
let candidate_lobes = trans_lobe + sheen_lobe + coat_lobe + base_lobes;
max_closure_candidates = max_closure_candidates.max(candidate_lobes.clamp(1, 7));
max_closure_lobes = max_closure_lobes.max(candidate_lobes.clamp(1, 4));
@@ -446,6 +524,130 @@ mod specialization_tests {
let result = specialize_cycles_kernel(source, &input);
assert_eq!(result, source, "Source without markers should be unchanged");
}
+
+ fn opaque_inputs(metallic: f32, transmission_weight: f32) -> BaseLayerInputs {
+ BaseLayerInputs {
+ metallic,
+ metallic_from_texture: false,
+ transmission_weight,
+ transmission_from_texture: false,
+ thin_walled: false,
+ }
+ }
+
+ /// The lobes `closure_build` adds for the base layers of a white, opaque material, written from closure.wgsl.
+ fn kernel_base_lobes(metallic: f32, transmission_weight: f32, thin_walled: bool) -> u32 {
+ let metallic = metallic.clamp(0.0, 1.0);
+ let transmission = transmission_weight.clamp(0.0, 1.0);
+ let mut layer_weight: f32 = 1.0;
+ let mut lobes = 0;
+ if metallic > CLOSURE_WEIGHT_CUTOFF {
+ lobes += 1;
+ layer_weight *= 1.0 - metallic;
+ }
+ if transmission > CLOSURE_WEIGHT_CUTOFF && layer_weight > CLOSURE_WEIGHT_CUTOFF {
+ lobes += if thin_walled { 2 } else { 1 };
+ layer_weight *= 1.0 - transmission;
+ }
+ if layer_weight > CLOSURE_WEIGHT_CUTOFF {
+ lobes += 2;
+ }
+ lobes
+ }
+
+ #[test]
+ fn metallic_near_one_keeps_the_specular_and_diffuse_lobes_the_kernel_builds() {
+ assert_eq!(base_layer_lobe_bound(&opaque_inputs(1.0, 0.0)), 1);
+ assert_eq!(base_layer_lobe_bound(&opaque_inputs(0.999999, 0.0)), 1);
+ assert_eq!(base_layer_lobe_bound(&opaque_inputs(0.99999, 0.0)), 3);
+ }
+
+ #[test]
+ fn transmission_near_one_keeps_the_specular_and_diffuse_lobes_the_kernel_builds() {
+ assert_eq!(base_layer_lobe_bound(&opaque_inputs(0.0, 1.0)), 1);
+ assert_eq!(base_layer_lobe_bound(&opaque_inputs(0.0, 0.999999)), 1);
+ assert_eq!(base_layer_lobe_bound(&opaque_inputs(0.0, 0.99999)), 3);
+ let thin_walled = BaseLayerInputs { thin_walled: true, ..opaque_inputs(0.0, 1.0) };
+ assert_eq!(base_layer_lobe_bound(&thin_walled), 2);
+ }
+
+ #[test]
+ fn a_texture_keeps_every_layer_possible() {
+ let metallic_texture = BaseLayerInputs { metallic_from_texture: true, ..opaque_inputs(1.0, 0.0) };
+ assert_eq!(base_layer_lobe_bound(&metallic_texture), 3);
+ let transmission_texture = BaseLayerInputs { transmission_from_texture: true, ..opaque_inputs(0.0, 1.0) };
+ assert_eq!(base_layer_lobe_bound(&transmission_texture), 3);
+ let both_textures = BaseLayerInputs {
+ metallic_from_texture: true,
+ transmission_from_texture: true,
+ ..opaque_inputs(1.0, 1.0)
+ };
+ assert_eq!(base_layer_lobe_bound(&both_textures), 4);
+ }
+
+ #[test]
+ fn fully_metal_material_ignores_glass_the_kernel_never_reaches() {
+ assert_eq!(base_layer_lobe_bound(&opaque_inputs(1.0, 1.0)), 1);
+ }
+
+ #[test]
+ fn lobe_bound_never_falls_below_what_the_kernel_builds() {
+ let near_one = [
+ 0.0, 1.0e-6, 1.0e-5, 1.1e-5, 0.5, 0.99, 0.9999, 0.99998, 0.999985, 0.99999, 0.9999905, 0.999995, 0.999999, 1.0, 1.5,
+ ];
+ for &metallic in &near_one {
+ for &transmission in &near_one {
+ for thin_walled in [false, true] {
+ let inputs = BaseLayerInputs { thin_walled, ..opaque_inputs(metallic, transmission) };
+ let bound = base_layer_lobe_bound(&inputs);
+ let built = kernel_base_lobes(metallic, transmission, thin_walled);
+ assert!(
+ bound >= built,
+ "metallic {metallic} transmission {transmission} thin {thin_walled}: bound {bound} below kernel {built}"
+ );
+ }
+ }
+ }
+ }
+
+ #[test]
+ fn counts_check_accepts_matching_counts_and_names_a_mismatch() {
+ let mut kernel_params = make_kp(0, 0.0, 0, 0, 0.0);
+ let mat = make_mat(0.0, 0.0, 0.0, 0.0, 0.0, 0, 0, -1, -1);
+ let inst = make_default_inst();
+ let lights = make_default_light();
+ let mut input = dummy_input(&kernel_params, &mat, &lights, &inst);
+ let counts = [
+ (KP_INSTANCE_COUNT_BYTE, input.instance_count),
+ (KP_TRIANGLE_COUNT_BYTE, input.triangle_count),
+ (KP_MATERIAL_COUNT_BYTE, input.material_count),
+ (KP_EMISSIVE_TRIANGLE_COUNT_BYTE, input.emissive_triangle_count),
+ (KP_LIGHT_COUNT_BYTE, input.light_count),
+ (KP_LIGHT_TREE_NODE_COUNT_BYTE, input.light_tree_node_count),
+ (KP_TEXTURE_COUNT_BYTE, input.texture_count),
+ ];
+ for (byte_offset, count) in counts {
+ kernel_params[byte_offset..byte_offset + 4].copy_from_slice(&count.to_le_bytes());
+ }
+ input = dummy_input(&kernel_params, &mat, &lights, &inst);
+ assert!(check_counts_match_kernel_params(&input).is_ok());
+
+ kernel_params[KP_MATERIAL_COUNT_BYTE..KP_MATERIAL_COUNT_BYTE + 4].copy_from_slice(&9u32.to_le_bytes());
+ let mismatched = dummy_input(&kernel_params, &mat, &lights, &inst);
+ let message = check_counts_match_kernel_params(&mismatched).unwrap_err().reason;
+ assert!(message.contains("materialCount"), "{message}");
+ assert!(message.contains('9'), "{message}");
+ }
+
+ #[test]
+ fn counts_check_rejects_a_short_kernel_params_block() {
+ let mat = make_mat(0.0, 0.0, 0.0, 0.0, 0.0, 0, 0, -1, -1);
+ let inst = make_default_inst();
+ let lights = make_default_light();
+ let input = dummy_input(&[0u8; 16], &mat, &lights, &inst);
+ let message = check_counts_match_kernel_params(&input).unwrap_err().reason;
+ assert!(message.contains("320"), "{message}");
+ }
}
/// Parses `kernel-manifest.txt`, stripping any UTF-8 BOM and ignoring blank lines and `#` comments, and returns relative WGSL paths in order.
diff --git a/packages/render-native/src/host/session.rs b/packages/render-native/src/host/session.rs
index ee6f5db6..033c2a03 100644
--- a/packages/render-native/src/host/session.rs
+++ b/packages/render-native/src/host/session.rs
@@ -8,7 +8,7 @@ use std::time::Instant;
use napi::Result;
use wgpu::util::DeviceExt;
-use crate::cycles::{specialize_cycles_kernel, CYCLES_LUT_WORDS};
+use crate::cycles::{check_counts_match_kernel_params, specialize_cycles_kernel, CYCLES_LUT_WORDS};
use crate::host::accel::{
build_acceleration_structure, build_cycles_acceleration_structure, build_empty_cycles_acceleration,
create_vertex_buffer, unpack_triangles, CyclesAcceleration, INSTANCE_RECORD_BYTES, TRIANGLE_FLOATS,
@@ -602,6 +602,7 @@ pub(crate) fn prepare_cycles_scene(
let compile_started = Instant::now();
// Specialise the kernel source for this scene (replaces SCENE_HAS_* sentinels).
+ check_counts_match_kernel_params(input)?;
let specialized_source = specialize_cycles_kernel(&shader_source, input);
let pipeline = get_or_compile_cycles_pipeline("main", specialized_source)?;
let compile_seconds = compile_started.elapsed().as_secs_f64();