3D engine that AI agents drive
mod filter_table;
mod luts;
pub(crate) use filter_table::unit_filter_table_words;
pub(crate) use luts::CYCLES_LUT_WORDS;
use napi::Result;
use crate::host::device::failure;
use crate::NativeTraceInputV2;
const KERNEL_MANIFEST_SOURCE: &str = include_str!("kernel-manifest.txt");
const BOOTSTRAP_MAIN_SOURCE: &str = include_str!("bootstrap_main.wgsl");
include!(concat!(env!("OUT_DIR"), "/cycles_manifest_files.rs"));
// ---- KernelParamsV2 byte offsets (verified against pack-input-v2.mjs and abi.wgsl) ----
const KERNEL_FLAG_LIGHT_TREE_PROBE: u32 = 128;
const KP_KERNEL_FLAGS_BYTE: usize = 32; // u32[8]
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]
const MAT_ANISOTROPY_BYTE: usize = 44; // f32[11]
const MAT_TRANSMISSION_WEIGHT_BYTE: usize = 52; // f32[13]
const MAT_COAT_WEIGHT_BYTE: usize = 76; // f32[19]
const MAT_THIN_FILM_THICKNESS_BYTE: usize = 88; // f32[22]
const MAT_SHEEN_WEIGHT_BYTE: usize = 108; // f32[27]
const MAT_FLAGS_BYTE: usize = 192; // u32[48]
const MAT_ALPHA_MODE_BYTE: usize = 196; // u32[49]
const MAT_METALLIC_ROUGHNESS_TEX_BYTE: usize = 212; // i32[53]
const MAT_NORMAL_TEX_BYTE: usize = 216; // i32[54]
const MAT_TRANSMISSION_TEX_BYTE: usize = 224; // i32[56]
const MAT_COAT_ROUGHNESS_TEX_BYTE: usize = 228; // i32[57]
const MAT_COAT_NORMAL_TEX_BYTE: usize = 236; // i32[59]
const MAT_SHEEN_TEX_BYTE: usize = 240; // i32[60]
const MAT_ANISOTROPY_TEX_BYTE: usize = 244; // i32[61]
const MAT_ALPHA_TEX_BYTE: usize = 248; // i32[62]
const MAT_BUMP_TEX_BYTE: usize = 252; // i32[63]
const MATERIAL_RECORD_STRIDE: usize = 256;
// MaterialRecord.flags bits
const MATERIAL_FLAG_THIN_WALLED: u32 = 2;
const MATERIAL_FLAG_TRANSPARENT_SHADOW: u32 = 4;
const MATERIAL_FLAG_F82_METALLIC: u32 = 32;
// ---- LightRecord byte offsets (128-byte stride, verified against pack-input-v2.mjs) ----
const LIGHT_TYPE_BYTE: usize = 12; // u32[3]
const LIGHT_RADIUS_BYTE: usize = 44; // f32[11]
const LIGHT_GROUP_MASK_LO_BYTE: usize = 120; // u32[30]
const LIGHT_GROUP_MASK_HI_BYTE: usize = 124; // u32[31]
const LIGHT_RECORD_STRIDE: usize = 128;
// ---- InstanceRecord byte offsets (160-byte stride) ----
const INSTANCE_LIGHT_GROUP_MASK_LO_BYTE: usize = 120; // u32[30]
const INSTANCE_LIGHT_GROUP_MASK_HI_BYTE: usize = 124; // u32[31]
const INSTANCE_RECORD_STRIDE: usize = 160;
// ---- Alpha modes ----
const ALPHA_MODE_MASK: u32 = 1;
const ALPHA_MODE_BLEND: u32 = 2;
// ---- Light types ----
const LIGHT_TYPE_AREA_RECT: u32 = 2;
const LIGHT_TYPE_AREA_DISK: u32 = 3;
fn read_u32_le(bytes: &[u8], byte_offset: usize) -> u32 {
u32::from_le_bytes(bytes[byte_offset..byte_offset + 4].try_into().unwrap())
}
fn read_i32_le(bytes: &[u8], byte_offset: usize) -> i32 {
i32::from_le_bytes(bytes[byte_offset..byte_offset + 4].try_into().unwrap())
}
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(())
}
/// 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<()> {
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_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 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."
)));
}
}
Ok(())
}
/// The scene-bound words an update of the light or emission tables may change: the selection weights are sums over the
/// tables the update replaces. Every other scene-bound word (counts, environment, texel pool offsets) must stay.
const UPDATABLE_SCENE_WORD_OFFSETS: [usize; 3] = [268, 272, 292];
/// Checks that the kernel parameters of a session update describe a scene of the same shape as the session's: the same
/// counts, environment and texel pool offsets. The light and emission selection weights may differ.
pub(crate) fn check_update_params_keep_scene_shape(session_kernel_params: &[u8], update_kernel_params: &[u8]) -> Result<()> {
for (name, byte_offset) in SCENE_BOUND_FIELDS {
if UPDATABLE_SCENE_WORD_OFFSETS.contains(&byte_offset) {
continue;
}
if session_kernel_params.len() < byte_offset + 4 || update_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_word = read_u32_le(session_kernel_params, byte_offset);
let update_word = read_u32_le(update_kernel_params, byte_offset);
if session_word != update_word {
return Err(failure(format!(
"The update changes {name} (byte {byte_offset}) from {session_word} to {update_word} (raw 32 bit words). A session update keeps the shape of the scene it holds (the record counts, the environment and the textures); create a new session for this input."
)));
}
}
Ok(())
}
/// The compute entry point to run for a kernel parameter block: `main`, or `light_tree_probe` when it carries
/// `KERNEL_FLAG_LIGHT_TREE_PROBE` (tests).
pub(crate) fn trace_entry_point_for_params(kernel_params: &[u8]) -> &'static str {
let kernel_flags = read_u32_le(kernel_params, KP_KERNEL_FLAGS_BYTE);
if (kernel_flags & KERNEL_FLAG_LIGHT_TREE_PROBE) != 0 {
"light_tree_probe"
} else {
"main"
}
}
/// 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
/// correctly even without specialization; specialization disables dead branches for performance.
///
/// NOTE: Only replaces in `trace_scene_cycles` / `CyclesSession`. In `probe_cycles_lobe`
/// all flags stay `true` (which is the unspecialized default).
#[cfg(test)]
pub(crate) fn specialize_cycles_kernel(source: &str, input: &NativeTraceInputV2) -> String {
specialize_kernel_source(source, &scan_scene_specialization(input), &input.kernel_params)
}
/// What the scene tables decide about the kernel's `SCENE_HAS_*` constants and lobe bounds. A session scans its scene once
/// and combines the result with each frame's kernel parameters, so a frame does not walk the tables again.
#[derive(Clone, Copy, Debug, PartialEq)]
pub(crate) struct SceneSpecialization {
has_alpha_mask: bool,
has_transparent: bool,
has_glass: bool,
has_coat: bool,
has_sheen: bool,
has_anisotropy: bool,
has_thin_film: bool,
has_f82: bool,
has_normal_map: bool,
max_closure_lobes: u32,
max_closure_candidates: u32,
has_finite_lights: bool,
has_light_linking: bool,
has_emissive_triangles: bool,
has_analytic_lights: bool,
light_tree_node_count: u32,
}
/// Walks the materials, lights and instances of an input once.
pub(crate) fn scan_scene_specialization(input: &NativeTraceInputV2) -> SceneSpecialization {
let mats = &input.materials;
let lights = &input.lights;
let instances = &input.instances;
let has_emissive_triangles = input.emissive_triangle_count > 0;
let has_analytic_lights = input.light_count > 0;
// --- Per-material flags ---
let mat_count = input.material_count as usize;
let mut has_alpha_mask = false;
let mut has_transparent = false;
let mut has_glass = false;
let mut has_coat = false;
let mut has_sheen = false;
let mut has_anisotropy = false;
let mut has_thin_film = false;
let mut has_f82 = false;
let mut has_normal_map = false;
let mut max_closure_lobes: u32 = if mat_count > 0 { 1 } else { 4 };
let mut max_closure_candidates: u32 = if mat_count > 0 { 1 } else { 7 };
for m in 0..mat_count {
let base = m * MATERIAL_RECORD_STRIDE;
if base + MATERIAL_RECORD_STRIDE > mats.len() {
break;
}
let mat = &mats[base..base + MATERIAL_RECORD_STRIDE];
let metallic = read_f32_le(mat, MAT_METALLIC_BYTE);
let metallic_roughness_tex = read_i32_le(mat, MAT_METALLIC_ROUGHNESS_TEX_BYTE);
let flags = read_u32_le(mat, MAT_FLAGS_BYTE);
let alpha_mode = read_u32_le(mat, MAT_ALPHA_MODE_BYTE);
let alpha_tex = read_i32_le(mat, MAT_ALPHA_TEX_BYTE);
let anisotropy = read_f32_le(mat, MAT_ANISOTROPY_BYTE);
let anisotropy_tex = read_i32_le(mat, MAT_ANISOTROPY_TEX_BYTE);
let transmission_weight = read_f32_le(mat, MAT_TRANSMISSION_WEIGHT_BYTE);
let transmission_tex = read_i32_le(mat, MAT_TRANSMISSION_TEX_BYTE);
let coat_weight = read_f32_le(mat, MAT_COAT_WEIGHT_BYTE);
let coat_roughness_tex = read_i32_le(mat, MAT_COAT_ROUGHNESS_TEX_BYTE);
let thin_film_thickness = read_f32_le(mat, MAT_THIN_FILM_THICKNESS_BYTE);
let sheen_weight = read_f32_le(mat, MAT_SHEEN_WEIGHT_BYTE);
let sheen_tex = read_i32_le(mat, MAT_SHEEN_TEX_BYTE);
let normal_tex = read_i32_le(mat, MAT_NORMAL_TEX_BYTE);
let coat_normal_tex = read_i32_le(mat, MAT_COAT_NORMAL_TEX_BYTE);
let bump_tex = read_i32_le(mat, MAT_BUMP_TEX_BYTE);
if alpha_mode == ALPHA_MODE_MASK || alpha_tex >= 0 {
has_alpha_mask = true;
}
if alpha_mode == ALPHA_MODE_BLEND || (flags & MATERIAL_FLAG_TRANSPARENT_SHADOW) != 0 {
has_transparent = true;
}
if transmission_weight > 0.0 || transmission_tex >= 0 {
has_glass = true;
}
if coat_weight > 0.0 || coat_roughness_tex >= 0 {
has_coat = true;
}
if sheen_weight > 0.0 || sheen_tex >= 0 {
has_sheen = true;
}
if anisotropy > 0.0 || anisotropy_tex >= 0 {
has_anisotropy = true;
}
if thin_film_thickness > 0.0 {
has_thin_film = true;
}
if (flags & MATERIAL_FLAG_F82_METALLIC) != 0 {
has_f82 = true;
}
if normal_tex >= 0 || coat_normal_tex >= 0 || bump_tex >= 0 {
has_normal_map = true;
}
let trans_lobe = u32::from(
alpha_mode == ALPHA_MODE_BLEND
|| alpha_mode == ALPHA_MODE_MASK
|| alpha_tex >= 0
|| (flags & MATERIAL_FLAG_TRANSPARENT_SHADOW) != 0,
);
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));
}
// --- Per-light flags ---
let light_count = input.light_count as usize;
let mut has_finite_lights = false;
for l in 0..light_count {
let base = l * LIGHT_RECORD_STRIDE;
if base + LIGHT_RECORD_STRIDE > lights.len() {
break;
}
let light = &lights[base..base + LIGHT_RECORD_STRIDE];
let light_type = read_u32_le(light, LIGHT_TYPE_BYTE);
let radius = read_f32_le(light, LIGHT_RADIUS_BYTE);
let finite = light_type == LIGHT_TYPE_AREA_RECT
|| light_type == LIGHT_TYPE_AREA_DISK
|| ((light_type == 0 || light_type == 1) && radius > 0.0);
if finite {
has_finite_lights = true;
}
}
// --- Per-instance and per-light light-linking flags ---
let instance_count = input.instance_count as usize;
let mut has_light_linking = false;
for i in 0..instance_count {
let base = i * INSTANCE_RECORD_STRIDE;
if base + INSTANCE_RECORD_STRIDE > instances.len() {
break;
}
let inst = &instances[base..base + INSTANCE_RECORD_STRIDE];
let lo = read_u32_le(inst, INSTANCE_LIGHT_GROUP_MASK_LO_BYTE);
let hi = read_u32_le(inst, INSTANCE_LIGHT_GROUP_MASK_HI_BYTE);
if lo != 0xFFFFFFFF || hi != 0xFFFFFFFF {
has_light_linking = true;
break;
}
}
if !has_light_linking {
for l in 0..light_count {
let base = l * LIGHT_RECORD_STRIDE;
if base + LIGHT_RECORD_STRIDE > lights.len() {
break;
}
let light = &lights[base..base + LIGHT_RECORD_STRIDE];
let lo = read_u32_le(light, LIGHT_GROUP_MASK_LO_BYTE);
let hi = read_u32_le(light, LIGHT_GROUP_MASK_HI_BYTE);
if lo != 0xFFFFFFFF || hi != 0xFFFFFFFF {
has_light_linking = true;
break;
}
}
}
SceneSpecialization {
has_alpha_mask,
has_transparent,
has_glass,
has_coat,
has_sheen,
has_anisotropy,
has_thin_film,
has_f82,
has_normal_map,
max_closure_lobes,
max_closure_candidates,
has_finite_lights,
has_light_linking,
has_emissive_triangles,
has_analytic_lights,
light_tree_node_count: input.light_tree_node_count,
}
}
/// Replaces the `SCENE_HAS_*` sentinels of `source` with the scene scan and the frame's kernel parameters
/// (kernel flags, fog density and environment table size).
pub(crate) fn specialize_kernel_source(source: &str, scene: &SceneSpecialization, kp: &[u8]) -> String {
let kernel_flags = read_u32_le(kp, KP_KERNEL_FLAGS_BYTE);
let volume_density = read_f32_le(kp, KP_VOLUME_DENSITY_BYTE);
let env_width = read_u32_le(kp, KP_ENV_WIDTH_BYTE);
let env_height = read_u32_le(kp, KP_ENV_HEIGHT_BYTE);
let env_total_weight = read_f32_le(kp, KP_ENV_TOTAL_WEIGHT_BYTE);
let has_volume = (kernel_flags & 2) != 0 && volume_density > 0.0;
let has_env_importance = env_width > 0 && env_height > 0 && env_total_weight > 0.0;
let has_light_tree = (kernel_flags & 1) != 0 && scene.light_tree_node_count > 0;
let SceneSpecialization {
has_alpha_mask,
has_transparent,
has_glass,
has_coat,
has_sheen,
has_anisotropy,
has_thin_film,
has_f82,
has_normal_map,
max_closure_lobes,
max_closure_candidates,
has_finite_lights,
has_light_linking,
has_emissive_triangles,
has_analytic_lights,
..
} = *scene;
// --- Apply replacements ---
// The sentinel pattern `const SCENE_HAS_*: bool = true;` is replaced with the computed value.
// If the pattern is absent (kernel not yet updated), the source is returned unchanged.
let mut result = source.to_string();
macro_rules! specialize {
($flag:ident, $value:expr) => {
let marker = concat!("const SCENE_HAS_", stringify!($flag), ": bool = true;");
if $value {
// already `true` — no replacement needed
} else {
result = result.replace(marker, concat!("const SCENE_HAS_", stringify!($flag), ": bool = false;"));
}
};
}
specialize!(VOLUME, has_volume);
specialize!(ALPHA_MASK, has_alpha_mask);
specialize!(TRANSPARENT, has_transparent);
specialize!(GLASS, has_glass);
specialize!(COAT, has_coat);
specialize!(SHEEN, has_sheen);
specialize!(ANISOTROPY, has_anisotropy);
specialize!(THIN_FILM, has_thin_film);
specialize!(F82, has_f82);
specialize!(NORMAL_MAP, has_normal_map);
specialize!(EMISSIVE_TRIANGLES, has_emissive_triangles);
specialize!(ANALYTIC_LIGHTS, has_analytic_lights);
specialize!(FINITE_LIGHTS, has_finite_lights);
specialize!(ENV_IMPORTANCE, has_env_importance);
specialize!(LIGHT_LINKING, has_light_linking);
specialize!(LIGHT_TREE, has_light_tree);
if max_closure_lobes < 4 {
result = result.replace(
"const MAX_CLOSURE_LOBES: u32 = 4u; // SPECIALIZE_LOBES",
&format!("const MAX_CLOSURE_LOBES: u32 = {max_closure_lobes}u; // SPECIALIZE_LOBES"),
);
}
if max_closure_candidates < 7 {
result = result.replace(
"const MAX_CLOSURE_CANDIDATES: u32 = 7u; // SPECIALIZE_CANDIDATES",
&format!("const MAX_CLOSURE_CANDIDATES: u32 = {max_closure_candidates}u; // SPECIALIZE_CANDIDATES"),
);
}
result
}
#[cfg(test)]
mod specialization_tests {
use super::*;
fn dummy_input(kp: &[u8], mats: &[u8], lights: &[u8], instances: &[u8]) -> NativeTraceInputV2 {
use napi::bindgen_prelude::{Float32Array, Uint32Array, Uint8Array};
NativeTraceInputV2 {
schema_version: 2,
kernel_params: Uint8Array::new(kp.to_vec()),
instances: Uint8Array::new(instances.to_vec()),
instance_count: (instances.len() / INSTANCE_RECORD_STRIDE) as u32,
triangles: Uint8Array::new(vec![0u8; 224]),
triangle_count: 1,
materials: Uint8Array::new(mats.to_vec()),
material_count: (mats.len() / MATERIAL_RECORD_STRIDE) as u32,
emissive_triangles: Uint8Array::new(vec![0u8; 96]),
emissive_triangle_count: 0,
lights: Uint8Array::new(lights.to_vec()),
light_count: (lights.len() / LIGHT_RECORD_STRIDE) as u32,
light_tree_nodes: Uint8Array::new(vec![0u8; 64]),
light_tree_node_count: 1,
light_tree_emitters: None,
light_tree_emitter_count: None,
light_to_tree: None,
texture_descriptors: Uint8Array::new(vec![0u8; 32]),
texture_count: 1,
texture_texels: Uint32Array::new(vec![0u32; 4]),
environment_texels: Float32Array::new(vec![0f32; 4]),
}
}
#[test]
fn light_tree_flag_without_emitter_tables_is_rejected() {
let flagged = dummy_input(&make_kp(1, 0.0, 0, 0, 0.0), &[], &[], &[]);
let message = crate::host::session::validate_light_tree_tables(&flagged)
.expect_err("a flagged input without emitter tables must fail")
.to_string();
assert!(message.contains("buildNativeInputV2"), "{message}");
let unflagged = dummy_input(&make_kp(0, 0.0, 0, 0, 0.0), &[], &[], &[]);
assert!(crate::host::session::validate_light_tree_tables(&unflagged).is_ok());
}
fn make_kp(kernel_flags: u32, volume_density: f32, env_width: u32, env_height: u32, env_total_weight: f32) -> Vec<u8> {
let mut kp = vec![0u8; 320];
// magic & version at bytes 0-7
kp[0..4].copy_from_slice(&0x36375054u32.to_le_bytes());
kp[4..8].copy_from_slice(&2u32.to_le_bytes());
kp[KP_KERNEL_FLAGS_BYTE..KP_KERNEL_FLAGS_BYTE + 4].copy_from_slice(&kernel_flags.to_le_bytes());
kp[KP_VOLUME_DENSITY_BYTE..KP_VOLUME_DENSITY_BYTE + 4].copy_from_slice(&volume_density.to_bits().to_le_bytes());
kp[KP_ENV_WIDTH_BYTE..KP_ENV_WIDTH_BYTE + 4].copy_from_slice(&env_width.to_le_bytes());
kp[KP_ENV_HEIGHT_BYTE..KP_ENV_HEIGHT_BYTE + 4].copy_from_slice(&env_height.to_le_bytes());
kp[KP_ENV_TOTAL_WEIGHT_BYTE..KP_ENV_TOTAL_WEIGHT_BYTE + 4].copy_from_slice(&env_total_weight.to_bits().to_le_bytes());
kp
}
fn make_mat(transmission_weight: f32, coat_weight: f32, sheen_weight: f32,
anisotropy: f32, thin_film_thickness: f32, flags: u32,
alpha_mode: u32, normal_tex: i32, alpha_tex: i32) -> Vec<u8> {
let mut mat = vec![0u8; MATERIAL_RECORD_STRIDE];
mat[MAT_TRANSMISSION_WEIGHT_BYTE..MAT_TRANSMISSION_WEIGHT_BYTE + 4].copy_from_slice(&transmission_weight.to_bits().to_le_bytes());
mat[MAT_COAT_WEIGHT_BYTE..MAT_COAT_WEIGHT_BYTE + 4].copy_from_slice(&coat_weight.to_bits().to_le_bytes());
mat[MAT_SHEEN_WEIGHT_BYTE..MAT_SHEEN_WEIGHT_BYTE + 4].copy_from_slice(&sheen_weight.to_bits().to_le_bytes());
mat[MAT_ANISOTROPY_BYTE..MAT_ANISOTROPY_BYTE + 4].copy_from_slice(&anisotropy.to_bits().to_le_bytes());
mat[MAT_THIN_FILM_THICKNESS_BYTE..MAT_THIN_FILM_THICKNESS_BYTE + 4].copy_from_slice(&thin_film_thickness.to_bits().to_le_bytes());
mat[MAT_FLAGS_BYTE..MAT_FLAGS_BYTE + 4].copy_from_slice(&flags.to_le_bytes());
mat[MAT_ALPHA_MODE_BYTE..MAT_ALPHA_MODE_BYTE + 4].copy_from_slice(&alpha_mode.to_le_bytes());
mat[MAT_NORMAL_TEX_BYTE..MAT_NORMAL_TEX_BYTE + 4].copy_from_slice(&normal_tex.to_le_bytes());
mat[MAT_ALPHA_TEX_BYTE..MAT_ALPHA_TEX_BYTE + 4].copy_from_slice(&alpha_tex.to_le_bytes());
// All tex indices default to -1 (INVALID = 0xFFFFFFFF)
for &offset in &[MAT_METALLIC_ROUGHNESS_TEX_BYTE, MAT_TRANSMISSION_TEX_BYTE,
MAT_COAT_ROUGHNESS_TEX_BYTE, MAT_COAT_NORMAL_TEX_BYTE,
MAT_SHEEN_TEX_BYTE, MAT_ANISOTROPY_TEX_BYTE, MAT_BUMP_TEX_BYTE] {
if mat[offset..offset + 4] == [0u8; 4] {
mat[offset..offset + 4].copy_from_slice(&(-1i32).to_le_bytes());
}
}
mat
}
fn make_default_inst() -> Vec<u8> {
let mut inst = vec![0u8; INSTANCE_RECORD_STRIDE];
// Default all-ones light group mask (no linking)
inst[INSTANCE_LIGHT_GROUP_MASK_LO_BYTE..INSTANCE_LIGHT_GROUP_MASK_LO_BYTE + 4].copy_from_slice(&0xFFFFFFFFu32.to_le_bytes());
inst[INSTANCE_LIGHT_GROUP_MASK_HI_BYTE..INSTANCE_LIGHT_GROUP_MASK_HI_BYTE + 4].copy_from_slice(&0xFFFFFFFFu32.to_le_bytes());
inst
}
fn make_default_light() -> Vec<u8> {
let mut light = vec![0u8; LIGHT_RECORD_STRIDE];
light[LIGHT_GROUP_MASK_LO_BYTE..LIGHT_GROUP_MASK_LO_BYTE + 4].copy_from_slice(&0xFFFFFFFFu32.to_le_bytes());
light[LIGHT_GROUP_MASK_HI_BYTE..LIGHT_GROUP_MASK_HI_BYTE + 4].copy_from_slice(&0xFFFFFFFFu32.to_le_bytes());
light
}
#[test]
fn specialize_all_false_on_empty_opaque_scene() {
let kp = 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 input = dummy_input(&kp, &mat, &lights, &inst);
// Build a source with every sentinel
let source = "const SCENE_HAS_VOLUME: bool = true;\n\
const SCENE_HAS_GLASS: bool = true;\n\
const SCENE_HAS_COAT: bool = true;\n\
const SCENE_HAS_SHEEN: bool = true;\n\
const SCENE_HAS_ANISOTROPY: bool = true;\n\
const SCENE_HAS_THIN_FILM: bool = true;\n\
const SCENE_HAS_F82: bool = true;\n\
const SCENE_HAS_NORMAL_MAP: bool = true;\n\
const SCENE_HAS_ALPHA_MASK: bool = true;\n\
const SCENE_HAS_TRANSPARENT: bool = true;\n\
const SCENE_HAS_EMISSIVE_TRIANGLES: bool = true;\n\
const SCENE_HAS_ANALYTIC_LIGHTS: bool = true;\n\
const SCENE_HAS_FINITE_LIGHTS: bool = true;\n\
const SCENE_HAS_ENV_IMPORTANCE: bool = true;\n\
const SCENE_HAS_LIGHT_LINKING: bool = true;\n\
const SCENE_HAS_LIGHT_TREE: bool = true;\n\
const MAX_CLOSURE_LOBES: u32 = 4u; // SPECIALIZE_LOBES
const MAX_CLOSURE_CANDIDATES: u32 = 7u; // SPECIALIZE_CANDIDATES";
let result = specialize_cycles_kernel(source, &input);
assert!(result.contains("const SCENE_HAS_VOLUME: bool = false;"), "VOLUME should be false");
assert!(result.contains("const SCENE_HAS_GLASS: bool = false;"), "GLASS should be false");
assert!(result.contains("const SCENE_HAS_COAT: bool = false;"), "COAT should be false");
assert!(result.contains("const SCENE_HAS_SHEEN: bool = false;"), "SHEEN should be false");
assert!(result.contains("const SCENE_HAS_ANISOTROPY: bool = false;"), "ANISOTROPY should be false");
assert!(result.contains("const SCENE_HAS_THIN_FILM: bool = false;"), "THIN_FILM should be false");
assert!(result.contains("const SCENE_HAS_F82: bool = false;"), "F82 should be false");
assert!(result.contains("const SCENE_HAS_NORMAL_MAP: bool = false;"), "NORMAL_MAP should be false");
assert!(result.contains("const SCENE_HAS_ALPHA_MASK: bool = false;"), "ALPHA_MASK should be false");
assert!(result.contains("const SCENE_HAS_TRANSPARENT: bool = false;"), "TRANSPARENT should be false");
assert!(result.contains("const SCENE_HAS_EMISSIVE_TRIANGLES: bool = false;"), "EMISSIVE_TRIANGLES should be false");
// light_count is 1 (lights has 128 bytes) so ANALYTIC_LIGHTS=true; but no finite lights
assert!(result.contains("const SCENE_HAS_FINITE_LIGHTS: bool = false;"), "FINITE_LIGHTS should be false");
assert!(result.contains("const SCENE_HAS_ENV_IMPORTANCE: bool = false;"), "ENV_IMPORTANCE should be false");
assert!(result.contains("const SCENE_HAS_LIGHT_LINKING: bool = false;"), "LIGHT_LINKING should be false");
assert!(result.contains("const SCENE_HAS_LIGHT_TREE: bool = false;"), "LIGHT_TREE should be false");
assert!(result.contains("const MAX_CLOSURE_LOBES: u32 = 2u; // SPECIALIZE_LOBES"), "MAX_CLOSURE_LOBES should be 2u");
assert!(
result.contains("const MAX_CLOSURE_CANDIDATES: u32 = 2u; // SPECIALIZE_CANDIDATES"),
"MAX_CLOSURE_CANDIDATES should be 2u"
);
}
#[test]
fn specialize_glass_and_volume_on_matching_scene() {
let kp = make_kp(2, 1.0, 1920, 1080, 42.0); // KERNEL_FLAG_HAS_VOLUME=2, volume>0, env
let mat = make_mat(0.5, 0.0, 0.0, 0.0, 0.0, 0, 0, -1, -1); // transmission_weight > 0
let inst = make_default_inst();
let lights = vec![0u8; LIGHT_RECORD_STRIDE];
let input = dummy_input(&kp, &mat, &lights, &inst);
let source = "const SCENE_HAS_VOLUME: bool = true;\nconst SCENE_HAS_GLASS: bool = true;\nconst SCENE_HAS_ENV_IMPORTANCE: bool = true;";
let result = specialize_cycles_kernel(source, &input);
// These should stay true (not replaced)
assert!(result.contains("const SCENE_HAS_VOLUME: bool = true;"), "VOLUME should stay true");
assert!(result.contains("const SCENE_HAS_GLASS: bool = true;"), "GLASS should stay true");
assert!(result.contains("const SCENE_HAS_ENV_IMPORTANCE: bool = true;"), "ENV_IMPORTANCE should stay true");
}
#[test]
fn specialize_no_change_when_no_markers() {
let kp = 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 = vec![0u8; LIGHT_RECORD_STRIDE];
let input = dummy_input(&kp, &mat, &lights, &inst);
let source = "fn main() { let x = 1; }";
let result = specialize_cycles_kernel(source, &input);
assert_eq!(result, source, "Source without markers should be unchanged");
}
const SESSION_TEST_SOURCE: &str = "const SCENE_HAS_VOLUME: bool = true;\nconst SCENE_HAS_GLASS: bool = true;\nconst SCENE_HAS_ENV_IMPORTANCE: bool = true;";
#[test]
fn a_scene_scan_combined_with_the_parameters_equals_the_one_step_specialization() {
let kp = make_kp(2, 1.0, 0, 0, 0.0);
let mat = make_mat(0.0, 0.0, 0.0, 0.0, 0.0, 0, 0, -1, -1);
let input = dummy_input(&kp, &mat, &make_default_light(), &make_default_inst());
let scene = scan_scene_specialization(&input);
assert_eq!(
specialize_kernel_source(SESSION_TEST_SOURCE, &scene, &kp),
specialize_cycles_kernel(SESSION_TEST_SOURCE, &input)
);
}
#[test]
fn a_frame_that_changes_only_the_camera_keeps_the_specialized_source() {
let kp = make_kp(2, 1.0, 0, 0, 0.0);
let mat = make_mat(0.0, 0.0, 0.0, 0.0, 0.0, 0, 0, -1, -1);
let input = dummy_input(&kp, &mat, &make_default_light(), &make_default_inst());
let scene = scan_scene_specialization(&input);
let mut moved_camera = kp.clone();
moved_camera[120..124].copy_from_slice(&3.5f32.to_bits().to_le_bytes());
assert_eq!(
specialize_kernel_source(SESSION_TEST_SOURCE, &scene, &kp),
specialize_kernel_source(SESSION_TEST_SOURCE, &scene, &moved_camera)
);
}
#[test]
fn a_frame_that_removes_the_fog_changes_the_specialized_source() {
let kp = make_kp(2, 1.0, 0, 0, 0.0);
let mat = make_mat(0.0, 0.0, 0.0, 0.0, 0.0, 0, 0, -1, -1);
let input = dummy_input(&kp, &mat, &make_default_light(), &make_default_inst());
let scene = scan_scene_specialization(&input);
let without_fog = make_kp(0, 0.0, 0, 0, 0.0);
let fogged = specialize_kernel_source(SESSION_TEST_SOURCE, &scene, &kp);
let clear = specialize_kernel_source(SESSION_TEST_SOURCE, &scene, &without_fog);
assert!(fogged.contains("const SCENE_HAS_VOLUME: bool = true;"));
assert!(clear.contains("const SCENE_HAS_VOLUME: bool = false;"));
}
#[test]
fn a_frame_must_keep_the_scene_record_counts_of_the_session() {
let session_params = make_kp(0, 0.0, 0, 0, 0.0);
let mut moved_camera = session_params.clone();
moved_camera[120..124].copy_from_slice(&1.0f32.to_bits().to_le_bytes());
assert!(check_frame_params_keep_scene_counts(&session_params, &moved_camera).is_ok());
let mut other_scene = session_params.clone();
other_scene[KP_MATERIAL_COUNT_BYTE..KP_MATERIAL_COUNT_BYTE + 4].copy_from_slice(&9u32.to_le_bytes());
let message = check_frame_params_keep_scene_counts(&session_params, &other_scene)
.expect_err("a different material count must be refused")
.to_string();
assert!(message.contains("materialCount"), "{message}");
assert!(message.contains("create a new session"), "{message}");
let truncated = &session_params[..64];
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 an_update_may_change_the_selection_weights_but_not_the_shape_of_the_scene() {
let session_params = make_kp(0, 0.0, 512, 256, 3.0);
for byte_offset in UPDATABLE_SCENE_WORD_OFFSETS {
let mut reweighted = session_params.clone();
reweighted[byte_offset..byte_offset + 4].copy_from_slice(&0x4000_0000u32.to_le_bytes());
assert!(check_update_params_keep_scene_shape(&session_params, &reweighted).is_ok(), "byte {byte_offset}");
}
for (name, byte_offset) in SCENE_BOUND_FIELDS {
if UPDATABLE_SCENE_WORD_OFFSETS.contains(&byte_offset) {
continue;
}
let mut reshaped = session_params.clone();
reshaped[byte_offset..byte_offset + 4].copy_from_slice(&0x1234_5678u32.to_le_bytes());
let message = check_update_params_keep_scene_shape(&session_params, &reshaped)
.expect_err("a changed scene shape must be refused")
.to_string();
assert!(message.contains(name), "{name}: {message}");
assert!(message.contains("create a new session"), "{name}: {message}");
}
assert!(check_update_params_keep_scene_shape(&session_params, &session_params[..64]).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,
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.
pub(crate) fn parse_kernel_manifest(manifest_text: &str) -> Vec<&str> {
let mut entries = Vec::new();
let without_file_bom = manifest_text.trim_start_matches('\u{feff}');
for raw_line in without_file_bom.lines() {
let without_line_bom = raw_line.trim_start_matches('\u{feff}');
let without_comment = without_line_bom.split('#').next().unwrap_or("");
let trimmed = without_comment.trim();
if !trimmed.is_empty() {
entries.push(trimmed);
}
}
entries
}
fn strip_wgsl_comments(source: &str) -> String {
let mut cleaned = String::with_capacity(source.len());
let bytes = source.as_bytes();
let mut index = 0;
let mut block_depth = 0usize;
while index < bytes.len() {
if block_depth > 0 {
if index + 1 < bytes.len() && bytes[index] == b'/' && bytes[index + 1] == b'*' {
block_depth += 1;
index += 2;
continue;
}
if index + 1 < bytes.len() && bytes[index] == b'*' && bytes[index + 1] == b'/' {
block_depth -= 1;
index += 2;
cleaned.push(' ');
continue;
}
if bytes[index] == b'\n' {
cleaned.push('\n');
}
index += 1;
continue;
}
if index + 1 < bytes.len() && bytes[index] == b'/' && bytes[index + 1] == b'/' {
index += 2;
while index < bytes.len() && bytes[index] != b'\n' {
index += 1;
}
continue;
}
if index + 1 < bytes.len() && bytes[index] == b'/' && bytes[index + 1] == b'*' {
block_depth = 1;
index += 2;
continue;
}
cleaned.push(bytes[index] as char);
index += 1;
}
cleaned
}
fn is_identifier_byte(byte: u8) -> bool {
byte.is_ascii_alphanumeric() || byte == b'_'
}
pub(crate) fn has_compute_entry_point(shader_source: &str, target_entry_point: &str) -> bool {
let uncommented = strip_wgsl_comments(shader_source);
let bytes = uncommented.as_bytes();
let mut index = 0usize;
let mut pending_compute = false;
let mut awaiting_function_name = false;
while index < bytes.len() {
if bytes[index] == b'@' {
let start = index + 1;
let mut end = start;
while end < bytes.len() && is_identifier_byte(bytes[end]) {
end += 1;
}
if &uncommented[start..end] == "compute" {
pending_compute = true;
}
index = end;
continue;
}
if is_identifier_byte(bytes[index]) {
let start = index;
let mut end = start + 1;
while end < bytes.len() && is_identifier_byte(bytes[end]) {
end += 1;
}
let token = &uncommented[start..end];
if awaiting_function_name {
if pending_compute && token == target_entry_point {
return true;
}
awaiting_function_name = false;
pending_compute = false;
} else if token == "fn" {
awaiting_function_name = true;
}
index = end;
continue;
}
index += 1;
}
false
}
/// Concatenates the WGSL modules listed in `src/cycles/kernel-manifest.txt` in order and verifies a runnable `@compute`
/// `target_entry_point` exists (appending `bootstrap_main.wgsl` only when `allow_bootstrap` is true and the manifest lacks it).
pub(crate) fn assemble_cycles_kernel_entry(target_entry_point: &str, allow_bootstrap: bool) -> Result<String> {
let entries = parse_kernel_manifest(KERNEL_MANIFEST_SOURCE);
if entries.is_empty() {
return Err(failure(
"The Cycles native kernel cannot run: src/cycles/kernel-manifest.txt lists no WGSL files.",
));
}
let mut assembled = String::new();
for entry in &entries {
let (_, raw_bytes) = CYCLES_MANIFEST_FILES
.iter()
.find(|(name, _)| name == entry)
.ok_or_else(|| failure(format!("Cycles kernel manifest entry is not embedded: {entry}")))?;
let module_source = std::str::from_utf8(raw_bytes)
.map_err(|error| failure(format!("Cycles kernel module {entry} is not valid UTF-8: {error}")))?
.trim_start_matches('\u{feff}');
if !assembled.is_empty() && !assembled.ends_with('\n') {
assembled.push('\n');
}
assembled.push_str(module_source);
}
if !has_compute_entry_point(&assembled, target_entry_point) {
if allow_bootstrap {
if !assembled.ends_with('\n') {
assembled.push('\n');
}
assembled.push_str(BOOTSTRAP_MAIN_SOURCE.trim_start_matches('\u{feff}'));
}
if !has_compute_entry_point(&assembled, target_entry_point) {
return Err(failure(format!(
"The Cycles native kernel cannot run yet: src/cycles/kernel-manifest.txt defines no @compute {target_entry_point} entry point (assembled modules: {}).",
entries.join(", ")
)));
}
}
Ok(assembled)
}
pub(crate) fn assemble_cycles_kernel() -> Result<String> {
assemble_cycles_kernel_entry("main", false)
}
#[cfg(test)]
mod tests {
use super::{assemble_cycles_kernel, has_compute_entry_point, parse_kernel_manifest};
#[test]
fn parses_manifest_with_utf8_bom_and_comments() {
let text = "\u{feff}# header\r\n\u{feff}abi.wgsl # inline comment\r\n closure.wgsl \n\n";
assert_eq!(parse_kernel_manifest(text), vec!["abi.wgsl", "closure.wgsl"]);
}
#[test]
fn detects_named_compute_entry_points_independently() {
let source = r#"
// @compute fn main() {}
fn helper() {}
@compute @workgroup_size(64, 1, 1)
fn test_lobe_samples() {}
fn not_compute_main() {}
"#;
assert!(has_compute_entry_point(source, "test_lobe_samples"));
assert!(!has_compute_entry_point(source, "main"));
assert!(!has_compute_entry_point(source, "helper"));
}
/// The texel pool is read in one function. A second reader would sample with its own wrap and filter, and a cutout
/// would then be seen through different texels than it is shaded with.
#[test]
fn the_kernel_reads_the_texel_pool_in_one_shared_sampler_only() {
let kernel = assemble_cycles_kernel().expect("the kernel assembles");
let fetch_start = kernel.find("fn texture_fetch_texel(").expect("the shared texel fetch exists");
let fetch_end = fetch_start + kernel[fetch_start..].find("\n}").expect("the fetch function ends");
let reads_inside_fetch = kernel[fetch_start..fetch_end].matches("texture_texels[").count();
assert_eq!(kernel.matches("texture_texels[").count(), reads_inside_fetch);
assert!(reads_inside_fetch > 0);
assert!(!kernel.contains("fn int_sample_texture_channel"));
assert!(!kernel.contains("fn int_wrap_coord"));
assert!(kernel.contains("texture_sample(material.base_color_tex, uv0, uv1).a"));
assert!(kernel.contains("texture_sample(material.alpha_tex, uv0, uv1).r"));
}
/// Blender Cycles filters the stored values of an 8-bit sRGB image and decodes the blend. Decoding each texel before the
/// blend reads 2 to 5 percent too bright on a checker map (#1030).
#[test]
fn an_srgb_map_is_decoded_after_the_filter_and_not_per_texel() {
let kernel = assemble_cycles_kernel().expect("the kernel assembles");
let fetch_start = kernel.find("fn texture_fetch_texel(").expect("the shared texel fetch exists");
let fetch_end = fetch_start + kernel[fetch_start..].find("\n}").expect("the fetch function ends");
assert!(!kernel[fetch_start..fetch_end].contains("closure_srgb_to_linear"));
assert!(kernel.contains("texture_decode_filtered(mix(mix(c00, c10, tx), mix(c01, c11, tx), ty), format)"));
assert!(kernel.contains("texture_decode_filtered(texture_fetch_texel(desc, ix, iy, format), format)"));
}
/// Mip levels are opt in. The shared sampler without a footprint, which the alpha tests and the bump taps use, must read
/// level 0 only, and a hit hands a footprint to the sampler only when the kernel flag is set.
#[test]
fn mip_levels_are_read_only_for_a_footprint_and_only_with_the_kernel_flag() {
let kernel = assemble_cycles_kernel().expect("the kernel assembles");
assert!(kernel.contains("const KERNEL_FLAG_TEXTURE_MIPS: u32 = 2048u;"));
assert!(kernel.contains("return texture_sample_footprint(tex_index, raw_uv0, raw_uv1, 0.0);"));
assert!(kernel.contains("texture_sample_footprint(tex_index, (*point).uv0, (*point).uv1, (*point).uv_footprint)"));
assert!(kernel.contains("if (uv_footprint > 0.0 && mip_count > 1u && !is_nearest)"));
let build_start = kernel.find("fn int_build_shading_point(").expect("the shading point builder exists");
let build_body = &kernel[build_start..];
let flag_test = build_body.find("(kernel_params.kernel_flags & KERNEL_FLAG_TEXTURE_MIPS) != 0u").expect("the footprint is gated by the flag");
let footprint_call = build_body.find("point.uv_footprint = int_uv_footprint(").expect("the footprint is computed");
assert!(flag_test < footprint_call);
assert!(build_body.contains("point.uv_footprint = 0.0;"));
}
/// The mip levels sit after level 0 in one run of words (`texture_fetch_texel` stays the only reader of the pool).
#[test]
fn a_mip_level_is_found_by_walking_the_halving_chain_from_level_0() {
let kernel = assemble_cycles_kernel().expect("the kernel assembles");
let walk_start = kernel.find("fn texture_level_descriptor(").expect("the level descriptor walk exists");
let walk_end = walk_start + kernel[walk_start..].find("\n}").expect("the walk ends");
let walk = &kernel[walk_start..walk_end];
assert!(walk.contains("select(1u, 4u, format == 2u)"));
assert!(walk.contains("level_desc.width * level_desc.height * words_per_texel"));
assert!(walk.contains("max(level_desc.width >> 1u, 1u)"));
assert!(walk.contains("max(level_desc.height >> 1u, 1u)"));
assert!(kernel.contains("return mix(lower, upper, blend);"), "two decoded levels blend in linear light");
let level_start = kernel.find("fn texture_filter_level(").expect("the level filter exists");
let level_end = level_start + kernel[level_start..].find("\n}").expect("the level filter ends");
let level_filter = &kernel[level_start..level_end];
let level_zero_branch = level_filter.find("if (level == 0u) {").expect("level 0 has its own branch");
let first_decode = level_filter.find("let decoded_c00").expect("later levels decode their taps");
let level_zero_return = "return texture_decode_filtered(mix(mix(level_c00, level_c10, level_tx), mix(level_c01, level_c11, level_tx), level_ty), format);";
let return_position = level_filter.find(level_zero_return).expect("level 0 stays filter then decode (#1030)");
assert!(level_zero_branch < return_position && return_position < first_decode);
for tap in ["c00", "c10", "c01", "c11"] {
assert!(
level_filter.contains(&format!("let decoded_{tap} = texture_decode_filtered(level_{tap}, format);")),
"a level after 0 decodes tap {tap} before the blend"
);
}
}
/// A point or spot light with a radius is a sphere (Blender's `use_soft_falloff` off, #1040): outside it Cook samples the cone
/// of the sphere and a path that hits it uses the same cone pdf, inside it samples the surface, and the packed radiance is
/// intensity over pi r^2 so the power does not change with the radius. The Cycles reference script switches
/// `use_soft_falloff` off to render the same light; with it on Cycles uses an oriented disk this kernel does not model.
#[test]
fn a_light_with_a_radius_is_a_sphere_with_one_pdf_for_sampling_and_hits() {
let kernel = assemble_cycles_kernel().expect("the kernel assembles");
let sampler_start = kernel.find("fn lgt_sample_point_or_spot_light(").expect("the point and spot sampler exists");
let sampler_end = sampler_start + kernel[sampler_start..].find("\nfn lgt_sample_area_light(").expect("the sampler ends");
let sampler = &kernel[sampler_start..sampler_end];
assert!(sampler.contains("lgt_sample_uniform_cone(center_dir, one_minus_cos_sphere, rand_uv, &cos_theta)"));
assert!(sampler.contains("pdf_solid_angle = 1.0 / max(TWO_PI * one_minus_cos_sphere, 1.0e-30)"));
assert!(sampler.contains("lgt_sample_uniform_sphere(rand_uv)"));
assert!(kernel.contains("lgt_sphere_solid_angle_pdf(dist_sq, light.radius, hit_t, ray_origin, ray_dir, light.position)"));
assert!(kernel.contains("if (hit_t <= t_min || hit_t >= t_max) {"));
assert!(!kernel.contains("disk_light_sample"));
}
#[test]
fn the_bootstrap_entry_samples_alpha_through_the_shared_sampler() {
let bootstrap = include_str!("bootstrap_main.wgsl");
assert!(!bootstrap.contains("texture_texels["));
assert!(bootstrap.contains("texture_sample("));
}
}