From 2918919194e0d2cae3a6fde99910cfbdcc407b7f Mon Sep 17 00:00:00 2001 From: Sam <13449963+SamG-Coder@users.noreply.github.com> Date: Fri, 13 Nov 2026 21:04:43 +1100 Subject: [PATCH] Reduce dense vegetation raster costs and avoid unnecessary cull queue work --- Cargo.lock | 2 + crates/solstice-render/Cargo.toml | 2 + .../examples/vegetation_stress.rs | 377 ++++++++++++++++++ crates/solstice-render/shaders/sky/luts.wgsl | 2 +- crates/solstice-render/shaders/vg/cull.wgsl | 18 +- .../shaders/vg/raster_sw_body.wgsl | 11 +- crates/solstice-render/src/particles/mod.rs | 82 ++-- crates/solstice-render/src/particles/tests.rs | 60 ++- crates/solstice-render/src/sky.rs | 100 +++++ .../solstice-render/src/vg/culling_stress.rs | 69 +++- crates/solstice-render/src/vg/mod.rs | 2 + .../solstice-render/src/vg/raster_stress.rs | 131 ++++++ .../vegetation-aggregate.csv | 7 + .../vegetation-image-checks.json | 74 ++++ .../vegetation-orbit-checks.json | 38 ++ .../vegetation-overflow-before.csv | 2 + docs/performance-results/vegetation-runs.csv | 18 + docs/vegetation-performance.md | 116 ++++++ scripts/vegetation_stress.py | 79 ++++ 19 files changed, 1147 insertions(+), 43 deletions(-) create mode 100644 crates/solstice-render/examples/vegetation_stress.rs create mode 100644 crates/solstice-render/src/vg/raster_stress.rs create mode 100644 docs/performance-results/vegetation-aggregate.csv create mode 100644 docs/performance-results/vegetation-image-checks.json create mode 100644 docs/performance-results/vegetation-orbit-checks.json create mode 100644 docs/performance-results/vegetation-overflow-before.csv create mode 100644 docs/performance-results/vegetation-runs.csv create mode 100644 docs/vegetation-performance.md create mode 100644 scripts/vegetation_stress.py diff --git a/Cargo.lock b/Cargo.lock index a7c4bc4..1d9e770 100644 --- a/Cargo.lock +++ b/Cargo.lock @@ -3294,9 +3294,11 @@ dependencies = [ "glam 0.33.12", "log", "naga", + "png 0.17.16", "pollster", "solstice-asset", "solstice-builder", + "solstice-procgen", "wgpu", ] diff --git a/crates/solstice-render/Cargo.toml b/crates/solstice-render/Cargo.toml index 541f875..823a140 100644 --- a/crates/solstice-render/Cargo.toml +++ b/crates/solstice-render/Cargo.toml @@ -17,3 +17,5 @@ wgpu.workspace = true naga.workspace = true pollster.workspace = true solstice-builder.workspace = true +solstice-procgen.workspace = true +png = "0.17" diff --git a/crates/solstice-render/examples/vegetation_stress.rs b/crates/solstice-render/examples/vegetation_stress.rs new file mode 100644 index 0000000..8f715bf --- /dev/null +++ b/crates/solstice-render/examples/vegetation_stress.rs @@ -0,0 +1,377 @@ +//! Deterministic, fixed-quality vegetation benchmark with per-pass GPU timings. +//! Arguments: grass grid side, tree count, measured frames, camera mode, output directory. +//! Example: cargo run --release -p solstice-render --example vegetation_stress -- 128 1024 120 overview target/vegetation/128 +use glam::{Mat4, Quat, Vec2, Vec3}; +use solstice_asset::{Instance, Material, SceneAsset}; +use solstice_builder::{build_virtual_mesh, paginate, BuildOptions, Mesh, Vertex}; +use solstice_procgen::foliage::{grass::Meadow, tree::Species, Rng}; +use solstice_render::{profiler::SECTIONS, Camera, Environment, Gpu, Renderer, RendererSettings}; +use std::fs::{self, File}; +use std::io::{BufWriter, Write}; +use std::path::Path; +use std::time::Instant; + +const WIDTH: u32 = 1920; +const HEIGHT: u32 = 1080; +const WARMUP: u32 = 48; + +fn mesh(scene: &mut SceneAsset, source: &Mesh) -> u32 { + let index = scene.meshes.len() as u32; + scene + .meshes + .push(build_virtual_mesh(source, &BuildOptions::default())); + index +} + +fn scene(side: u32, trees: u32) -> SceneAsset { + let mut scene = SceneAsset { + texture_size: 512, + ..Default::default() + }; + let grass = Meadow::default(); + let grass_mesh = mesh(&mut scene, &grass.mesh()); + scene.textures.push(grass.atlas(0).bake(512)); + scene.materials.push(Material { + base_color: [1.0; 4], + texture_layer: 0, + roughness: 1.0, + normal_strength: 1.0, + flags: Material::TWO_SIDED | Material::FOLIAGE | Material::SWAYS, + ..Default::default() + }); + let extent = side as f32 * grass.size; + let mut rng = Rng::new(917, 11); + for z in 0..side { + for x in 0..side { + scene.instances.push(Instance { + mesh: grass_mesh, + material: 0, + transform: Mat4::from_rotation_translation( + Quat::from_rotation_y(rng.index(4) as f32 * std::f32::consts::FRAC_PI_2), + Vec3::new( + (x as f32 + 0.5) * grass.size - extent * 0.5, + 0.0, + (z as f32 + 0.5) * grass.size - extent * 0.5, + ), + ), + }); + } + } + let mut plants = Vec::new(); + for (seed, species) in [Species::oak(), Species::birch(), Species::fir()] + .iter() + .enumerate() + { + let plant = species.grow(seed as u32); + let wood = mesh(&mut scene, &plant.wood); + let leaves = mesh(&mut scene, &plant.leaves); + let bark_layer = scene.textures.len() as i32; + scene + .textures + .push(species.bark.surface(seed as u32).bake(512)); + scene + .textures + .push(species.leaves.kind.atlas(seed as u32).bake(512)); + let bark = scene.materials.len() as u32; + scene.materials.push(Material { + base_color: [1.0; 4], + texture_layer: bark_layer, + uv_scale: 1.0 / solstice_procgen::foliage::bark::BARK_TILE_METRES, + roughness: 1.0, + normal_strength: 1.0, + flags: Material::SWAYS | Material::TREE, + ..Default::default() + }); + scene.materials.push(Material { + base_color: [1.0; 4], + texture_layer: bark_layer + 1, + roughness: 1.0, + normal_strength: 1.0, + flags: Material::TWO_SIDED | Material::FOLIAGE | Material::SWAYS | Material::TREE, + ..Default::default() + }); + plants.push((wood, leaves, bark)); + } + for _ in 0..trees { + let (wood, leaves, bark) = plants[rng.index(plants.len())]; + let position = Vec3::new( + rng.signed() * extent * 0.48, + 0.0, + rng.signed() * extent * 0.48, + ); + let transform = Mat4::from_scale_rotation_translation( + Vec3::splat(rng.range(0.8, 1.2)), + Quat::from_rotation_y(rng.range(0.0, std::f32::consts::TAU)), + position, + ); + for (mesh, material) in [(wood, bark), (leaves, bark + 1)] { + scene.instances.push(Instance { + mesh, + material, + transform, + }); + } + } + let ground = Mesh { + vertices: [(-1.0, -1.0), (-1.0, 1.0), (1.0, 1.0), (1.0, -1.0)] + .map(|(x, z)| Vertex { + position: Vec3::new(x * extent, -0.04, z * extent), + normal: Vec3::Y, + uv: Vec2::new(x, z), + }) + .to_vec(), + indices: vec![0, 1, 2, 0, 2, 3], + }; + let ground_mesh = mesh(&mut scene, &ground); + let material = scene.materials.len() as u32; + scene.materials.push(Material { + base_color: [0.035, 0.055, 0.018, 1.0], + roughness: 1.0, + ..Default::default() + }); + scene.instances.push(Instance { + mesh: ground_mesh, + material, + transform: Mat4::IDENTITY, + }); + scene +} + +#[cfg(windows)] +fn process_bytes() -> (usize, usize) { + #[repr(C)] + #[derive(Default)] + struct Counters { + cb: u32, + faults: u32, + peak_working: usize, + working: usize, + peak_paged: usize, + paged: usize, + peak_nonpaged: usize, + nonpaged: usize, + pagefile: usize, + peak_pagefile: usize, + private: usize, + } + #[link(name = "psapi")] + unsafe extern "system" { + fn GetProcessMemoryInfo(process: isize, counters: *mut Counters, size: u32) -> i32; + } + let mut c = Counters { + cb: std::mem::size_of::() as u32, + ..Default::default() + }; + // SAFETY: -1 is the current-process pseudo handle; c points to a valid structure of cb bytes. + let ok = unsafe { GetProcessMemoryInfo(-1, &mut c, std::mem::size_of::() as u32) }; + if ok == 0 { + (0, 0) + } else { + (c.working, c.private) + } +} +#[cfg(not(windows))] +fn process_bytes() -> (usize, usize) { + (0, 0) +} + +fn screenshot(gpu: &Gpu, target: &wgpu::Texture, path: &Path) { + let row = (WIDTH * 4).next_multiple_of(256); + let staging = gpu.device.create_buffer(&wgpu::BufferDescriptor { + label: Some("screenshot"), + size: u64::from(row * HEIGHT), + usage: wgpu::BufferUsages::MAP_READ | wgpu::BufferUsages::COPY_DST, + mapped_at_creation: false, + }); + let mut encoder = gpu.device.create_command_encoder(&Default::default()); + encoder.copy_texture_to_buffer( + target.as_image_copy(), + wgpu::TexelCopyBufferInfo { + buffer: &staging, + layout: wgpu::TexelCopyBufferLayout { + offset: 0, + bytes_per_row: Some(row), + rows_per_image: Some(HEIGHT), + }, + }, + target.size(), + ); + gpu.queue.submit([encoder.finish()]); + staging + .slice(..) + .map_async(wgpu::MapMode::Read, |r| r.unwrap()); + gpu.device + .poll(wgpu::PollType::wait_indefinitely()) + .unwrap(); + let data = staging.slice(..).get_mapped_range().unwrap(); + let pixels: Vec = data + .chunks_exact(row as usize) + .flat_map(|r| r[..(WIDTH * 4) as usize].iter().copied()) + .collect(); + let mut png = png::Encoder::new(BufWriter::new(File::create(path).unwrap()), WIDTH, HEIGHT); + png.set_color(png::ColorType::Rgba); + png.set_depth(png::BitDepth::Eight); + png.write_header() + .unwrap() + .write_image_data(&pixels) + .unwrap(); +} + +fn percentile(values: &[f64], fraction: f64) -> f64 { + let mut sorted = values.to_vec(); + sorted.sort_by(f64::total_cmp); + sorted[((sorted.len() - 1) as f64 * fraction).round() as usize] +} + +fn main() { + let args: Vec = std::env::args().collect(); + let number = |i: usize, fallback| { + args.get(i) + .map(|s| s.parse::().unwrap()) + .unwrap_or(fallback) + }; + let side = number(1, 64); + let trees = number(2, 256); + let frames = number(3, 120).max(1); + let mode = args.get(4).map_or("overview", String::as_str); + let output = Path::new(args.get(5).map_or("target/vegetation", String::as_str)); + fs::create_dir_all(output).unwrap(); + let start = Instant::now(); + let scene = scene(side, trees); + let loaded = paginate(&scene); + eprintln!("baked in {:.2}s: {} grass patches, {} trees, {} instances, {} unique triangles, {} instanced source triangles, {} pages", + start.elapsed().as_secs_f64(), side * side, trees, scene.instances.len(), scene.unique_source_triangles(), scene.total_source_triangles(), loaded.scene.pages.len()); + drop(scene); + let instance = wgpu::Instance::new(wgpu::InstanceDescriptor { + backends: wgpu::Backends::PRIMARY, + ..wgpu::InstanceDescriptor::new_without_display_handle() + }); + let gpu = pollster::block_on(Gpu::request( + &instance, + None, + wgpu::PowerPreference::HighPerformance, + )) + .unwrap(); + eprintln!("adapter: {:?}", gpu.adapter_info); + let settings = RendererSettings::default(); + eprintln!("fixed settings: {settings:?}"); + let mut renderer = Renderer::new(&gpu, &loaded, wgpu::TextureFormat::Rgba8Unorm, settings); + drop(loaded); + let target = gpu.device.create_texture(&wgpu::TextureDescriptor { + label: Some("vegetation output"), + size: wgpu::Extent3d { + width: WIDTH, + height: HEIGHT, + depth_or_array_layers: 1, + }, + mip_level_count: 1, + sample_count: 1, + dimension: wgpu::TextureDimension::D2, + format: wgpu::TextureFormat::Rgba8Unorm, + usage: wgpu::TextureUsages::RENDER_ATTACHMENT | wgpu::TextureUsages::COPY_SRC, + view_formats: &[], + }); + let view = target.create_view(&Default::default()); + let extent = side as f32 * Meadow::default().size; + let mut camera = if matches!(mode, "ground" | "walk" | "orbit") { + Camera { + position: Vec3::new(0.0, 1.7, extent * 0.3), + pitch: -0.08, + fov_y: 65.0f32.to_radians(), + ..Default::default() + } + } else { + Camera { + position: Vec3::new(0.0, extent * 0.55, extent * 0.7), + pitch: -(0.55f32 / 0.7).atan(), + fov_y: 65.0f32.to_radians(), + ..Default::default() + } + }; + let environment = Environment::default(); + let mut csv = BufWriter::new(File::create(output.join("frames.csv")).unwrap()); + writeln!(csv,"frame,cpu_ms,wall_ms,clusters,triangles,dropped,shadow_dropped,working_bytes,private_bytes,{}",SECTIONS.join(",")).unwrap(); + let mut cpu = Vec::new(); + let mut wall = Vec::new(); + let mut gpu_times = Vec::new(); + let mut sections = vec![Vec::new(); SECTIONS.len()]; + let mut dropped = 0; + let mut shadow_dropped = 0; + let mut max_private = 0; + let mut max_working = 0; + for frame in 0..WARMUP + frames { + if mode == "walk" { + camera.position.x = (frame as f32 * 0.005).sin() * 8.0; + camera.yaw = (frame as f32 * 0.004).sin() * 0.25; + } else if mode == "orbit" { + camera.yaw = frame.saturating_sub(WARMUP) as f32 * std::f32::consts::TAU / 600.0; + } + let started = Instant::now(); + renderer.render( + &gpu, + &camera, + &environment, + &view, + (WIDTH, HEIGHT), + 1.0 / 60.0, + ); + let cpu_ms = started.elapsed().as_secs_f64() * 1000.0; + gpu.device + .poll(wgpu::PollType::wait_indefinitely()) + .unwrap(); + let wall_ms = started.elapsed().as_secs_f64() * 1000.0; + // Startup is not timed, but missing geometry there is still a quality failure. + let stats = renderer.stats(); + dropped = dropped.max(stats.dropped); + shadow_dropped = shadow_dropped.max(stats.shadow_dropped); + if frame >= WARMUP { + let times = renderer + .section_times() + .expect("this benchmark needs native GPU timestamps"); + let (working, private) = process_bytes(); + max_private = max_private.max(private); + max_working = max_working.max(working); + cpu.push(cpu_ms); + wall.push(wall_ms); + gpu_times.push(times.iter().map(|&x| f64::from(x)).sum()); + write!( + csv, + "{frame},{cpu_ms:.6},{wall_ms:.6},{},{},{},{},{working},{private}", + stats.clusters, stats.triangles, stats.dropped, stats.shadow_dropped + ) + .unwrap(); + for (i, time) in times.iter().enumerate() { + sections[i].push(f64::from(*time)); + write!(csv, ",{time:.6}").unwrap(); + } + writeln!(csv).unwrap(); + if mode == "orbit" && (frame + 1 - WARMUP).is_multiple_of(600) { + screenshot( + &gpu, + &target, + &output.join(format!("orbit-{:04}.png", frame + 1 - WARMUP)), + ); + } + } + } + csv.flush().unwrap(); + screenshot(&gpu, &target, &output.join("final.png")); + let memory = renderer.scene_bytes(); + let stats = renderer.stats(); + println!("side,trees,mode,instances,source_triangles,clusters,triangles,cpu_median_ms,cpu_p95_ms,gpu_median_ms,gpu_p95_ms,wall_median_ms,scene_gpu_bytes,peak_working_bytes,peak_private_bytes,dropped,shadow_dropped"); + println!("{side},{trees},{mode},{},{},{},{},{:.6},{:.6},{:.6},{:.6},{:.6},{},{max_working},{max_private},{dropped},{shadow_dropped}", + stats.instances,stats.source_triangles,stats.clusters,stats.triangles, percentile(&cpu,0.5),percentile(&cpu,0.95), + percentile(&gpu_times,0.5),percentile(&gpu_times,0.95),percentile(&wall,0.5),memory.total()); + for (i, name) in SECTIONS.iter().enumerate() { + eprintln!( + "{name}: median {:.3}ms, p95 {:.3}ms", + percentile(§ions[i], 0.5), + percentile(§ions[i], 0.95) + ); + } + assert_eq!( + (dropped, shadow_dropped), + (0, 0), + "capacity overflow means this run did not preserve image quality" + ); +} diff --git a/crates/solstice-render/shaders/sky/luts.wgsl b/crates/solstice-render/shaders/sky/luts.wgsl index beb84dc..0d6ca57 100644 --- a/crates/solstice-render/shaders/sky/luts.wgsl +++ b/crates/solstice-render/shaders/sky/luts.wgsl @@ -1,6 +1,6 @@ // Generates the three atmosphere lookup tables. Transmittance and multiple scattering // depend only on the atmosphere, so they are built once. The sky view depends on the -// sun and is cheap enough to rebuild every frame. Radiance is per unit of sun illuminance. +// sun and viewer radius, and is rebuilt when either changes. Radiance is per unit of sun illuminance. #include "common/math.wgsl" #include "common/atmosphere.wgsl" diff --git a/crates/solstice-render/shaders/vg/cull.wgsl b/crates/solstice-render/shaders/vg/cull.wgsl index dadc255..f4c8fca 100644 --- a/crates/solstice-render/shaders/vg/cull.wgsl +++ b/crates/solstice-render/shaders/vg/cull.wgsl @@ -178,6 +178,20 @@ fn projected_error(center: vec3f, radius: f32, error: f32) -> f32 { return error * view.lod_scale / distance; } +// A child below the LOD cut would return immediately on the next dispatch. Reject it +// before reserving queue space: distant instances can have many such children even +// though only a few of their coarsest clusters contribute to the image. +fn push_child(instance_index: u32, node_index: u32, instance: Instance) { + let node = nodes[node_index]; + let center = transform_point(instance, node.lod_center); + let radius = (node.lod_radius + instance.lod_margin) * instance.max_scale; + let error = node.max_parent_error * instance.max_scale; + if projected_error(center, radius, error) <= view.lod_threshold { + return; + } + push_queue(QueueEntry(instance_index, node_index)); +} + fn in_frustum(center: vec3f, radius: f32) -> bool { for (var i = 0u; i < 6u; i++) { let p = view.planes[i]; @@ -440,7 +454,7 @@ fn process(@builtin(global_invocation_id) id: vec3u, @builtin(num_workgroups) gr && distance(center, view.camera_position) - radius < view.prefetch_radius { if node.is_leaf == 0u { for (var i = 0u; i < node.count; i++) { - push_queue(QueueEntry(entry.instance, node.first + i)); + push_child(entry.instance, node.first + i, instance); } } else { atomicMax(&page_requests[page], REQUEST_LOWEST_LOAD); @@ -460,7 +474,7 @@ fn process(@builtin(global_invocation_id) id: vec3u, @builtin(num_workgroups) gr if node.is_leaf == 0u { for (var i = 0u; i < node.count; i++) { - push_queue(QueueEntry(entry.instance, node.first + i)); + push_child(entry.instance, node.first + i, instance); } return; } diff --git a/crates/solstice-render/shaders/vg/raster_sw_body.wgsl b/crates/solstice-render/shaders/vg/raster_sw_body.wgsl index 39b4daa..a3509de 100644 --- a/crates/solstice-render/shaders/vg/raster_sw_body.wgsl +++ b/crates/solstice-render/shaders/vg/raster_sw_body.wgsl @@ -141,8 +141,15 @@ fn rasterize_triangle( let z2 = b_in.z; let inv_area = 1.0 / f32(-area); - let first = max(vec2i(bounds_min), vec2i(0)); - let last = min(vec2i(bounds_max), vec2i(view.viewport) - 1); + // Only visit pixel centres inside the rounded triangle's bounds. Using whole pixel + // edges visits an extra row/column on both sides of tiny grass and leaf triangles, + // often even when no sample can be covered. Work from the same fixed-point vertices + // as the edge tests so rounding cannot discard a sample on a top/left edge. + // The numerators stay nonnegative, including for triangles outside the viewport. + let low = min(min(a, b), c); + let high = max(max(a, b), c); + let first = max(vec2i(origin) + (low + vec2i(127)) / SUBPIXEL_I, vec2i(0)); + let last = min(vec2i(origin) + (high + vec2i(128)) / SUBPIXEL_I - vec2i(1), vec2i(view.viewport) - 1); if first.x > last.x || first.y > last.y { return; } diff --git a/crates/solstice-render/src/particles/mod.rs b/crates/solstice-render/src/particles/mod.rs index f4c08b2..2058578 100644 --- a/crates/solstice-render/src/particles/mod.rs +++ b/crates/solstice-render/src/particles/mod.rs @@ -167,6 +167,7 @@ impl ParticleTargets { /// The buffers of a pool of one size, and their bind groups. struct Pool { capacity: u32, + buffer_bytes: u64, // Held by the bind groups too; tests read them back. #[cfg_attr(not(test), allow(dead_code))] particles: wgpu::Buffer, @@ -202,7 +203,10 @@ struct PoolLayouts { /// Every effect running, the pool their particles live in, and the passes that move and draw /// them. pub struct Particles { - pool: Pool, + // Logical capacity is reserved immediately; GPU buffers are needed only once an + // effect reaches prepare. Keep a used pool for later effects to avoid allocation churn. + pool: Option, + capacity: u32, layouts: PoolLayouts, inputs: LightInputs, light: wgpu::ComputePipeline, @@ -253,8 +257,9 @@ pub struct Particles { } impl Particles { - /// Creates the passes and a pool of `capacity` particles, or as many as the device can - /// bind. `frame` is the renderer's frame uniform, which the draw reads; the light pass reads + /// Creates the passes and reserves a pool of `capacity` particles, or as many as the + /// device can bind. The GPU buffers are allocated when an effect is first prepared. + /// `frame` is the renderer's frame uniform, which the draw reads; the light pass reads /// the environment group, made with `environment`, and `inputs`. pub fn new( gpu: &Gpu, @@ -535,9 +540,9 @@ impl Particles { light: light_layout, draw: pool_draw_layout, }; - let pool = Pool::new(gpu, capacity, &layouts, &inputs); Self { - pool, + pool: None, + capacity, layouts, inputs, light, @@ -598,17 +603,30 @@ impl Particles { /// Particles the pool holds. pub fn capacity(&self) -> u32 { - self.pool.capacity + self.capacity + } + + /// Bytes in the allocated simulation buffers, excluding pipelines and render targets. + /// Zero until an effect is first prepared; the configured capacity is unchanged. + pub fn buffer_bytes(&self) -> u64 { + self.pool.as_ref().map_or(0, |pool| pool.buffer_bytes) + } + + fn pool(&self) -> &Pool { + self.pool.as_ref().expect("active particles have a pool") } /// Makes the pool hold `capacity` particles. Running effects start again in the new pool, /// with budgets that fit it. pub fn resize(&mut self, gpu: &Gpu, capacity: u32) { let capacity = fitted_capacity(gpu, capacity); - if capacity == self.pool.capacity { + if capacity == self.capacity { return; } - self.pool = Pool::new(gpu, capacity, &self.layouts, &self.inputs); + self.capacity = capacity; + if self.pool.is_some() { + self.pool = Some(Pool::new(gpu, capacity, &self.layouts, &self.inputs)); + } self.ranges = vec![(0, capacity)]; self.slots = [false; MAX_EMITTERS]; self.pending.clear(); @@ -788,7 +806,7 @@ impl Particles { /// The pool's use, from a recent frame. pub fn stats(&self) -> ParticleStats { let mut stats = self.stats.latest(); - stats.capacity = self.pool.capacity; + stats.capacity = self.capacity; stats.reserved = self .effects .iter() @@ -841,7 +859,10 @@ impl Particles { return; } - let capacity = self.pool.capacity; + let pool = self + .pool + .get_or_insert_with(|| Pool::new(gpu, self.capacity, &self.layouts, &self.inputs)); + let capacity = pool.capacity; let mut records = [EmitterRecord::default(); MAX_EMITTERS]; let mut draws = vec![0u8; MAX_EMITTERS * DRAW_STRIDE as usize]; let written = 1 - self.parity; @@ -935,31 +956,31 @@ impl Particles { ..Default::default() }; queue.write_buffer( - &self.pool.state, + &pool.state, (slot * std::mem::size_of::()) as u64, bytemuck::bytes_of(&state), ); let free: Vec = (emitter.base..emitter.base + emitter.budget).collect(); queue.write_buffer( - &self.pool.free, + &pool.free, u64::from(emitter.base) * 4, bytemuck::cast_slice(&free), ); queue.write_buffer( - &self.pool.curves, + &pool.curves, (slot * CURVE_STRIDE * 16) as u64, bytemuck::cast_slice(&baked_curves(desc)), ); // Light left by the slice's last owner must not pass for a new particle's: the // new emitter counts its particles from zero again, into the same slots. queue.write_buffer( - &self.pool.light, + &pool.light, u64::from(emitter.base) * LIGHT_BYTES, &vec![0u8; (u64::from(emitter.budget) * LIGHT_BYTES) as usize], ); } - queue.write_buffer(&self.pool.emitters, 0, bytemuck::cast_slice(&records)); - queue.write_buffer(&self.pool.draws, 0, &draws); + queue.write_buffer(&pool.emitters, 0, bytemuck::cast_slice(&records)); + queue.write_buffer(&pool.draws, 0, &draws); let sim = SimUniform { seconds, parity: self.parity, @@ -971,7 +992,7 @@ impl Particles { camera_position: eye.extend(self.wind_floor).into(), camera_forward: camera.forward().extend(0.0).into(), }; - queue.write_buffer(&self.pool.sim, 0, bytemuck::bytes_of(&sim)); + queue.write_buffer(&pool.sim, 0, bytemuck::bytes_of(&sim)); self.stats.live = self.slots; self.stats.parity = written; self.parity = written; @@ -982,7 +1003,7 @@ impl Particles { if !self.active { return; } - let pool = &self.pool; + let pool = self.pool(); let mut pass = encoder.begin_compute_pass(&wgpu::ComputePassDescriptor { label: Some("particles"), timestamp_writes: None, @@ -1018,11 +1039,11 @@ impl Particles { timestamp_writes: None, }); pass.set_pipeline(&self.collide); - pass.set_bind_group(0, &self.pool.collide_group, &[]); + pass.set_bind_group(0, &self.pool().collide_group, &[]); pass.set_bind_group(1, environment, &[]); pass.set_bind_group(2, &targets.opaque_group, &[]); pass.set_bind_group(3, waterline, &[]); - pass.dispatch_workgroups_indirect(&self.pool.indirect, LIGHT_ARGS); + pass.dispatch_workgroups_indirect(&self.pool().indirect, LIGHT_ARGS); } /// Records the light each live particle receives this frame, after the simulation, with @@ -1037,9 +1058,9 @@ impl Particles { timestamp_writes: None, }); pass.set_pipeline(&self.light); - pass.set_bind_group(0, &self.pool.light_group, &[]); + pass.set_bind_group(0, &self.pool().light_group, &[]); pass.set_bind_group(1, environment, &[]); - pass.dispatch_workgroups_indirect(&self.pool.indirect, LIGHT_ARGS); + pass.dispatch_workgroups_indirect(&self.pool().indirect, LIGHT_ARGS); } /// The targets for drawing at one size, over a scene whose depth and motion are @@ -1125,7 +1146,7 @@ impl Particles { timestamp_writes: None, }); pass.set_pipeline(&self.sort); - pass.set_bind_group(0, &self.pool.simulate_group, &[]); + pass.set_bind_group(0, &self.pool().simulate_group, &[]); pass.dispatch_workgroups(MAX_EMITTERS as u32, 1, 1); } @@ -1196,10 +1217,10 @@ impl Particles { let draw_slot = |pass: &mut wgpu::RenderPass<'_>, slot: usize| { pass.set_bind_group( 1, - &self.pool.draw_group, + &self.pool().draw_group, &[(slot as u64 * DRAW_STRIDE) as u32], ); - pass.draw_indirect(&self.pool.indirect, DRAWS_OFFSET + slot as u64 * 16); + pass.draw_indirect(&self.pool().indirect, DRAWS_OFFSET + slot as u64 * 16); }; // The scene's depth, for the hardware to test against. @@ -1280,7 +1301,8 @@ impl Particles { /// Copies this frame's counters for the statistics, when the last copy has been read. pub fn capture_stats(&mut self, encoder: &mut wgpu::CommandEncoder) { if self.active { - self.stats.capture(encoder, &self.pool.state); + self.stats + .capture(encoder, &self.pool.as_ref().unwrap().state); } else { self.stats.idle(); } @@ -1428,8 +1450,16 @@ impl Pool { whole(&light), ], ); + let buffer_bytes = [ + &particles, &free, &alive, &state, &emitters, &curves, &indirect, &light, &events, + &sim, &draws, + ] + .iter() + .map(|buffer| buffer.size()) + .sum(); Self { capacity, + buffer_bytes, particles, free, alive, diff --git a/crates/solstice-render/src/particles/tests.rs b/crates/solstice-render/src/particles/tests.rs index c4ff7c0..a0de4ae 100644 --- a/crates/solstice-render/src/particles/tests.rs +++ b/crates/solstice-render/src/particles/tests.rs @@ -147,12 +147,16 @@ impl Rig { /// Each live emitter's slot, slice, state, free list and alive particles, as the next frame /// will read them. fn emitters(&self) -> Vec { - let states: Vec = self.read(&self.particles.pool.state); - let records: Vec = self.read(&self.particles.pool.emitters); - let free: Vec = self.read(&self.particles.pool.free); - let alive: Vec = self.read(&self.particles.pool.alive); - let pool: Vec = self.read(&self.particles.pool.particles); - let capacity = self.particles.pool.capacity; + if self.particles.pool.is_none() { + assert!(!self.particles.slots.iter().any(|&live| live)); + return Vec::new(); + } + let states: Vec = self.read(&self.particles.pool().state); + let records: Vec = self.read(&self.particles.pool().emitters); + let free: Vec = self.read(&self.particles.pool().free); + let alive: Vec = self.read(&self.particles.pool().alive); + let pool: Vec = self.read(&self.particles.pool().particles); + let capacity = self.particles.pool().capacity; let parity = self.particles.parity; (0..MAX_EMITTERS) .filter(|&slot| self.particles.slots[slot]) @@ -192,6 +196,40 @@ struct Snapshot { particles: Vec, } +#[test] +fn unused_pool_is_lazy_and_late_effects_keep_their_full_budget() { + let Some(mut rig) = Rig::new(262_144) else { + return; + }; + assert_eq!(rig.particles.capacity(), 262_144); + assert_eq!(rig.particles.buffer_bytes(), 0); + for _ in 0..8 { + rig.frame(1.0 / 60.0); + } + rig.particles.resize(&rig.gpu, 8192); + assert_eq!(rig.particles.stats().capacity, 8192); + assert_eq!(rig.particles.buffer_bytes(), 0); + let effect = + Effect::parse("emitter late\n budget 8192\n spawn burst=8192\n lifetime 10").unwrap(); + // An effect cancelled before prepare never needs GPU storage. + let cancelled = rig.particles.spawn(&effect, Mat4::IDENTITY).unwrap(); + rig.particles.kill(cancelled); + rig.frame(1.0 / 60.0); + assert_eq!(rig.particles.buffer_bytes(), 0); + let live = rig.particles.spawn(&effect, Mat4::IDENTITY).unwrap(); + rig.frame(1.0 / 60.0); + let allocated = rig.particles.buffer_bytes(); + assert!(allocated > 8192 * std::mem::size_of::() as u64); + assert_eq!(rig.emitters()[0].alive.len(), 8192); + rig.particles.kill(live); + rig.frame(1.0 / 60.0); + // Keep used storage to avoid a hitch when another effect starts. + assert_eq!(rig.particles.buffer_bytes(), allocated); + rig.particles.spawn(&effect, Mat4::IDENTITY).unwrap(); + rig.frame(1.0 / 60.0); + assert_eq!(rig.emitters()[0].alive.len(), 8192); +} + const BALLISTIC: &str = " emitter shot budget 2000 @@ -1470,13 +1508,13 @@ impl Ground { fn emitters(&mut self) -> Vec<(EmitterState, Vec)> { let particles = self.renderer.particles(); let (state, alive, pool, emitters) = ( - particles.pool.state.clone(), - particles.pool.alive.clone(), - particles.pool.particles.clone(), - particles.pool.emitters.clone(), + particles.pool().state.clone(), + particles.pool().alive.clone(), + particles.pool().particles.clone(), + particles.pool().emitters.clone(), ); let (capacity, parity, slots) = - (particles.pool.capacity, particles.parity, particles.slots); + (particles.pool().capacity, particles.parity, particles.slots); let records: Vec = self.read(&emitters); let states: Vec = self.read(&state); let lists: Vec = self.read(&alive); diff --git a/crates/solstice-render/src/sky.rs b/crates/solstice-render/src/sky.rs index c2e1972..fe94d26 100644 --- a/crates/solstice-render/src/sky.rs +++ b/crates/solstice-render/src/sky.rs @@ -29,6 +29,7 @@ pub struct Sky { build_multi_scatter: (wgpu::ComputePipeline, wgpu::BindGroup), build_sky_view: (wgpu::ComputePipeline, wgpu::BindGroup), static_tables_built: bool, + last_params: Option, } impl Sky { @@ -92,6 +93,7 @@ impl Sky { sky_view, params, static_tables_built: false, + last_params: None, } } @@ -107,6 +109,15 @@ impl Sky { sun_direction, viewer_radius: GROUND_RADIUS_KM + viewer_height_m.max(1.0) * 0.001, }; + // No time or camera orientation enters the LUT. Compare the exact shader inputs + // after height conversion; no tolerance or stale lighting is introduced. + if self + .last_params + .is_some_and(|last| bytemuck::bytes_of(&last) == bytemuck::bytes_of(¶ms)) + { + return; + } + self.last_params = Some(params); gpu.queue .write_buffer(&self.params, 0, bytemuck::bytes_of(¶ms)); @@ -128,3 +139,92 @@ impl Sky { run(&self.build_sky_view, SKY_VIEW_SIZE); } } + +#[cfg(test)] +mod tests { + use super::*; + + #[test] + fn cached_sky_matches_rebuilding_after_sun_and_height_changes() { + let Some(gpu) = crate::gpu::test_gpu() else { + return; + }; + let mut sky = Sky::new(&gpu); + let layout = LayoutBuilder::new() + .texture_unfilterable() + .storage_write() + .build(&gpu, "sky readback"); + let module = gpu + .device + .create_shader_module(wgpu::ShaderModuleDescriptor { + label: None, + source: wgpu::ShaderSource::Wgsl( + r#" +@group(0) @binding(0) var sky: texture_2d; +@group(0) @binding(1) var pixels: array; +@compute @workgroup_size(8, 8) +fn main(@builtin(global_invocation_id) id: vec3u) { + let size = textureDimensions(sky); + if all(id.xy < size) { pixels[id.y * size.x + id.x] = textureLoad(sky, id.xy, 0); } +} +"# + .into(), + ), + }); + let pipeline = gpu.compute_pipeline("sky readback", &module, "main", &[&layout]); + let size = u64::from(SKY_VIEW_SIZE.0 * SKY_VIEW_SIZE.1) * 16; + let output = gpu.storage_buffer("sky pixels", size, wgpu::BufferUsages::COPY_SRC); + let group = gpu.bind_group( + "sky readback", + &layout, + &[ + wgpu::BindingResource::TextureView(&sky.sky_view.view), + output.as_entire_binding(), + ], + ); + let staging = gpu.device.create_buffer(&wgpu::BufferDescriptor { + label: None, + size, + usage: wgpu::BufferUsages::COPY_DST | wgpu::BufferUsages::MAP_READ, + mapped_at_creation: false, + }); + let read = |sky: &mut Sky, sun, height| { + let mut encoder = gpu.device.create_command_encoder(&Default::default()); + sky.record(&gpu, &mut encoder, sun, height); + { + let mut pass = encoder.begin_compute_pass(&Default::default()); + pass.set_pipeline(&pipeline); + pass.set_bind_group(0, &group, &[]); + pass.dispatch_workgroups(SKY_VIEW_SIZE.0 / 8, SKY_VIEW_SIZE.1 / 8, 1); + } + encoder.copy_buffer_to_buffer(&output, 0, &staging, 0, size); + gpu.queue.submit([encoder.finish()]); + staging + .slice(..) + .map_async(wgpu::MapMode::Read, |r| r.unwrap()); + gpu.device + .poll(wgpu::PollType::wait_indefinitely()) + .unwrap(); + let data = staging.slice(..).get_mapped_range().unwrap().to_vec(); + staging.unmap(); + data + }; + let mut previous = Vec::new(); + for (sun, height) in [ + (Vec3::Y, 1.0), + (Vec3::Y, 1000.0), + (Vec3::new(1.0, 0.1, 0.0).normalize(), 1000.0), + ] { + let changed = read(&mut sky, sun, height); + assert_ne!(changed, previous, "changed input must refresh the LUT"); + assert_eq!(changed, read(&mut sky, sun, height)); + sky.last_params = None; + assert_eq!( + changed, + read(&mut sky, sun, height), + "cached and rebuilt pixels differ" + ); + previous = changed; + } + } +} diff --git a/crates/solstice-render/src/vg/culling_stress.rs b/crates/solstice-render/src/vg/culling_stress.rs index 6bb5b2c..044a09b 100644 --- a/crates/solstice-render/src/vg/culling_stress.rs +++ b/crates/solstice-render/src/vg/culling_stress.rs @@ -115,7 +115,7 @@ fn traversal_visits_every_entry_beyond_one_dispatch_dimension() { let queue = gpu.storage_buffer( "stress queue", ((1 << 22) * 2 + 64) * 8, - wgpu::BufferUsages::empty(), + wgpu::BufferUsages::COPY_SRC | wgpu::BufferUsages::COPY_DST, ); let scratch = gpu.storage_buffer("stress scratch", 16, wgpu::BufferUsages::empty()); // Separate buffers avoid writable binding aliasing. @@ -169,4 +169,71 @@ fn traversal_visits_every_entry_beyond_one_dispatch_dimension() { assert_eq!(result[9], 0, "no entry should be dropped"); } } + + // Distant child subtrees must be rejected before they consume queue capacity. + // Values exactly at the threshold match process's existing <= comparison. + let errors = [ + 0.0, + 0.5, + 1.0, + 1.0001, + 2.0, + solstice_asset::gpu::ROOT_PARENT_ERROR, + ]; + let mut children = vec![PackedNode { + radius: 1.0, + max_parent_error: solstice_asset::gpu::ROOT_PARENT_ERROR, + first: 1, + count: 120, + ..Default::default() + }]; + children.extend((0..120).map(|index| PackedNode { + radius: 1.0, + max_parent_error: errors[index % errors.len()], + ..Default::default() + })); + let child_nodes = gpu.storage_buffer_init("child LOD nodes", &children); + let child_scene = gpu.bind_group( + "child LOD scene", + &pipelines.scene_layout, + &[ + slots.binding(), + instances.as_entire_binding(), + child_nodes.as_entire_binding(), + clusters.as_entire_binding(), + wgpu::BindingResource::TextureView(&float_view), + wgpu::BindingResource::TextureView(&float_view), + wgpu::BindingResource::TextureView(&uint_view), + ], + ); + let mut words = [0u32; STATE_SIZE as usize / 4]; + words[2] = 1; + gpu.queue + .write_buffer(&state, 0, bytemuck::cast_slice(&words)); + gpu.queue.write_buffer(&queue, 0, &[0u8; 8]); + let mut encoder = gpu.device.create_command_encoder(&Default::default()); + { + let mut pass = encoder.begin_compute_pass(&Default::default()); + pass.set_pipeline(&pipelines.advance); + pass.set_bind_group(0, &control, &[]); + pass.dispatch_workgroups(1, 1, 1); + pass.set_pipeline(&pipelines.process); + pass.set_bind_group(0, &child_scene, &[0]); + pass.set_bind_group(1, &work, &[]); + pass.dispatch_workgroups_indirect(&args, 0); + } + gpu.queue.submit([encoder.finish()]); + let result = read_words(&gpu, &state, STATE_SIZE); + let expected: Vec = (0..120) + .filter(|&i| errors[i % errors.len()] > 1.0) + .map(|i| i as u32 + 1) + .collect(); + assert_eq!(result[2], expected.len() as u32 + 1); + assert_eq!(result[9], 0); + let entries = read_words(&gpu, &queue, u64::from(result[2]) * 8); + let actual: Vec = entries[2..].chunks_exact(2).map(|entry| entry[1]).collect(); + assert_eq!( + actual, expected, + "only children that process would visit may be queued" + ); } diff --git a/crates/solstice-render/src/vg/mod.rs b/crates/solstice-render/src/vg/mod.rs index 793f3da..f7ea71d 100644 --- a/crates/solstice-render/src/vg/mod.rs +++ b/crates/solstice-render/src/vg/mod.rs @@ -14,6 +14,8 @@ mod culling; mod hzb; mod raster; +#[cfg(test)] +mod raster_stress; mod resolve; pub use culling::{ diff --git a/crates/solstice-render/src/vg/raster_stress.rs b/crates/solstice-render/src/vg/raster_stress.rs new file mode 100644 index 0000000..46ebfec --- /dev/null +++ b/crates/solstice-render/src/vg/raster_stress.rs @@ -0,0 +1,131 @@ +//! Compare production sample bounds with an exhaustive viewport scan on the GPU. +use crate::gpu::{test_gpu, LayoutBuilder}; + +#[test] +fn tiny_triangles_keep_every_covered_sample() { + let Some(gpu) = test_gpu() else { return }; + let source = include_str!("../../shaders/vg/raster_sw_body.wgsl"); + let source = &source[source.find("fn edge_f(").unwrap()..]; + let first = source.find(" let first =").unwrap(); + let end = first + source[first..].find(" if first.x").unwrap(); + // The reference visits all 256 samples, even those outside the triangle's bounding + // box. Only the unchanged edge/fill/depth rules decide which ones it writes. + let reference = format!( + "{} let first = vec2i(0);\n let last = vec2i(15);\n{}", + &source[..first], + &source[end..] + ); + let header = r#" +const SUBPIXEL: f32 = 256.0; +const SUBPIXEL_I: i32 = 256; +const MAX_EXTENT_PX: f32 = 512.0; +struct View { viewport: vec2f } +const view = View(vec2f(16.0)); +struct Triangle { a: vec4f, b: vec4f, c: vec4f } +@group(0) @binding(0) var triangles: array; +@group(0) @binding(1) var pixels: array; +fn depth_bias(a: vec3f, b: vec3f, c: vec3f) -> f32 { return 0.0; } +fn cover_triangle(x: u32, y: u32, z: u32, a: vec3f, b: vec3f, c: vec3f, instance: u32) {} +fn covered(a: f32, b: f32, c: f32) -> bool { return true; } +fn write_visibility(pixel: u32, depth: f32, id: u32) { + pixels[id * 256u + pixel] = bitcast(depth); +} +@compute @workgroup_size(64) +fn main(@builtin(global_invocation_id) id: vec3u) { + if id.x >= arrayLength(&triangles) { return; } + let t = triangles[id.x]; + rasterize_triangle(t.a.xyz, t.b.xyz, t.c.xyz, id.x, t.a.w > 0.0, vec3u(0u, 1u, 2u), 0u); +} +"#; + let mut seed = 917u32; + let mut random = || { + seed ^= seed << 13; + seed ^= seed >> 17; + seed ^= seed << 5; + seed as f32 / u32::MAX as f32 + }; + let mut cases: Vec<[[f32; 4]; 3]> = Vec::new(); + for n in 0..8192 { + let x = random() * 20.0 - 2.0; + let y = random() * 20.0 - 2.0; + let extent = if n % 3 == 0 { 0.01 } else { 5.0 }; + cases.push([ + [x, y, 0.1, (n % 2) as f32], + [x + random() * extent, y + random() * extent, 0.9, 0.0], + [x + random() * extent, y - random() * extent, 0.5, 0.0], + ]); + } + // Quantization ties, exact pixel centres, top/left shared edges and clipped edges. + for step in -260..=260 { + let x = 7.5 + step as f32 / 512.0; + for y in [-0.5, 0.5, 7.5, 15.5, 16.5] { + cases.push([ + [x, y, 0.2, 1.0], + [x + 0.01, y + 2.0, 0.7, 0.0], + [x + 2.0, y, 0.9, 0.0], + ]); + cases.push([ + [x, y, 0.2, 0.0], + [x + 2.0, y, 0.7, 0.0], + [x, y + 0.01, 0.9, 0.0], + ]); + } + } + let input = gpu.storage_buffer_init("sample bounds cases", &cases); + let size = cases.len() as u64 * 256 * 4; + let layout = LayoutBuilder::new() + .storage_read() + .storage_write() + .build(&gpu, "sample bounds"); + let run = |body: &str| { + let module = gpu + .device + .create_shader_module(wgpu::ShaderModuleDescriptor { + label: Some("sample bounds"), + source: wgpu::ShaderSource::Wgsl(format!("{header}\n{body}").into()), + }); + let pipeline = gpu.compute_pipeline("sample bounds", &module, "main", &[&layout]); + let output = gpu.storage_buffer("samples", size, wgpu::BufferUsages::COPY_SRC); + let group = gpu.bind_group( + "sample bounds", + &layout, + &[input.as_entire_binding(), output.as_entire_binding()], + ); + let staging = gpu.device.create_buffer(&wgpu::BufferDescriptor { + label: None, + size, + usage: wgpu::BufferUsages::COPY_DST | wgpu::BufferUsages::MAP_READ, + mapped_at_creation: false, + }); + let mut encoder = gpu.device.create_command_encoder(&Default::default()); + { + let mut pass = encoder.begin_compute_pass(&Default::default()); + pass.set_pipeline(&pipeline); + pass.set_bind_group(0, &group, &[]); + pass.dispatch_workgroups((cases.len() as u32).div_ceil(64), 1, 1); + } + encoder.copy_buffer_to_buffer(&output, 0, &staging, 0, size); + gpu.queue.submit([encoder.finish()]); + staging + .slice(..) + .map_async(wgpu::MapMode::Read, |r| r.unwrap()); + gpu.device + .poll(wgpu::PollType::wait_indefinitely()) + .unwrap(); + let mapping = staging.slice(..).get_mapped_range().unwrap(); + bytemuck::cast_slice::(&mapping).to_vec() + }; + let expected = run(&reference); + let actual = run(source); + assert!(expected.iter().filter(|&&v| v != 0).count() > 10_000); + for (pixel, (actual, expected)) in actual.iter().zip(expected).enumerate() { + assert_eq!( + *actual, + expected, + "triangle {}, sample ({}, {})", + pixel / 256, + pixel % 16, + pixel / 16 % 16 + ); + } +} diff --git a/docs/performance-results/vegetation-aggregate.csv b/docs/performance-results/vegetation-aggregate.csv new file mode 100644 index 0000000..86c75b6 --- /dev/null +++ b/docs/performance-results/vegetation-aggregate.csv @@ -0,0 +1,7 @@ +case,version,frames,cpu_ms_median,cpu_ms_p95,wall_ms_median,wall_ms_p95,sky_median,sky_p95,clouds_median,clouds_p95,ocean_median,ocean_p95,wind_median,wind_p95,shadows_median,shadows_p95,wet line_median,wet line_p95,rain_median,rain_p95,gi cull_median,gi cull_p95,gi voxelize_median,gi voxelize_p95,gi flood_median,gi flood_p95,gi write_median,gi write_p95,light shadows_median,light shadows_p95,gi light_median,gi light_p95,cull 1_median,cull 1_p95,raster 1_median,raster 1_p95,cull 2_median,cull 2_p95,raster 2_median,raster 2_p95,resolve_median,resolve_p95,clouds on screen_median,clouds on screen_p95,screen gi_median,screen gi_p95,lighting_median,lighting_p95,water_median,water_p95,particles_median,particles_p95,particle draw_median,particle draw_p95,rain draw_median,rain draw_p95,post_median,post_p95,gpu_ms_median,gpu_ms_p95 +128-ground,baseline,480,0.3781,0.6534,6.50605,6.9294,0.012928,0.013408,0.099104,0.101184,0.00032,0.000768,0.008896,0.008992,0.00032,0.000768,0.000608,0.000704,0.00032,0.00032,0.00032,0.00032,0.00032,0.00032,0.00032,0.00032,0.00032,0.00032,0.00032,0.00032,0.14,0.146304,0.41032,0.419424,3.0935040000000003,3.317824,0.100304,0.111488,0.13916800000000001,0.161792,0.306176,0.48944,0.16672,0.181312,0.942112,1.158048,0.293664,0.469024,0.000352,0.000768,0.000576,0.000704,0.00032,0.000352,0.00032,0.000352,0.195808,0.199296,5.938319999999999,6.333408 +128-ground,candidate,480,0.3723,0.7163,5.909800000000001,6.3677,0.00032,0.00032,0.0984,0.100512,0.00032,0.000768,0.008896,0.008992,0.00032,0.000768,0.000608,0.000704,0.00032,0.00032,0.00032,0.00032,0.00032,0.00032,0.00032,0.00032,0.00032,0.00032,0.00032,0.00032,0.13808,0.144256,0.394208,0.403392,2.432496,2.775584,0.106464,0.116896,0.122848,0.13536,0.30424,0.481696,0.164864,0.328896,0.939696,1.155776,0.291648,0.465888,0.00032,0.000768,0.000608,0.000672,0.00032,0.000352,0.00032,0.000352,0.19472,0.19792,5.35656,5.6976320000000005 +128-walk,baseline,480,0.39765,0.7234,6.57855,7.9281,0.012912,0.013408,0.099136,0.101216,0.00032,0.000768,0.008896,0.008992,0.00032,0.000896,0.000608,0.000736,0.00032,0.00032,0.00032,0.00032,0.00032,0.00032,0.00032,0.09248,0.00032,0.000352,0.00032,0.000352,0.14016,0.150432,0.408704,0.582368,3.0733759999999997,3.388,0.0964,0.111296,0.12584,0.164864,0.312288,0.498752,0.1792,0.199648,0.958464,1.194912,0.293824,0.298752,0.000352,0.0008,0.000576,0.000704,0.00032,0.000352,0.00032,0.000352,0.196,0.204288,5.975488,7.202784 +128-walk,candidate,480,0.3779,0.6851,5.9907,7.2238,0.00032,0.00032,0.098672,0.100608,0.00032,0.000768,0.008864,0.00896,0.00032,0.000864,0.000608,0.000768,0.00032,0.00032,0.00032,0.00032,0.00032,0.000352,0.00032,0.092384,0.00032,0.000768,0.00032,0.000352,0.14011200000000001,0.150304,0.391408,0.40496,2.56488,2.809728,0.102432,0.118784,0.112832,0.140256,0.312288,0.318624,0.1792,0.203712,0.960448,1.22784,0.293728,0.473504,0.000352,0.0008,0.000608,0.000704,0.00032,0.000352,0.00032,0.000352,0.19584,0.199104,5.426256,6.56336 +512-overview,baseline,480,0.3779,0.5211,4.76155,5.1493,0.012928,0.01344,0.10512,0.105504,0.00032,0.000768,0.008896,0.008992,0.00032,0.000768,0.000608,0.000736,0.00032,0.00032,0.00032,0.00032,0.00032,0.00032,0.00032,0.00032,0.00032,0.00032,0.00032,0.00032,0.029472,0.029696,0.622272,0.63248,2.211776,2.562944,0.046048,0.050176,0.064544,0.073728,0.195584,0.355232,0.015328,0.016096,0.442368,0.627168,0.152416,0.329472,0.000736,0.0008,0.000352,0.000672,0.00032,0.000352,0.00032,0.000352,0.190848,0.36128,4.271424,4.5544 +512-overview,candidate,480,0.37115,0.6074,4.0336,4.3537,0.00032,0.00032,0.10272,0.104928,0.00032,0.000768,0.008896,0.008992,0.00032,0.000768,0.000608,0.000704,0.00032,0.00032,0.00032,0.00032,0.00032,0.00032,0.00032,0.00032,0.00032,0.00032,0.00032,0.00032,0.029472,0.029664,0.38976,0.547968,1.743888,2.06848,0.051328,0.057568,0.067584,0.071584,0.195584,0.19824,0.015328,0.015648,0.440352,0.62352,0.152384,0.15456,0.00032,0.000768,0.000608,0.000672,0.00032,0.000352,0.00032,0.000352,0.190432,0.192896,3.547056,3.819424 diff --git a/docs/performance-results/vegetation-image-checks.json b/docs/performance-results/vegetation-image-checks.json new file mode 100644 index 0000000..773db23 --- /dev/null +++ b/docs/performance-results/vegetation-image-checks.json @@ -0,0 +1,74 @@ +{ + "128-ground-r1": { + "frames": 240, + "different_cluster_count_frames": 0, + "different_triangle_count_frames": 0, + "mean_abs_rgb_0_255": 0.30354407793209875, + "changed_fraction": 0.3151027199074074, + "over_4_fraction": 0.016120273919753087, + "over_16_fraction": 0.0017708333333333332 + }, + "128-ground-r2": { + "frames": 240, + "different_cluster_count_frames": 0, + "different_triangle_count_frames": 0, + "mean_abs_rgb_0_255": 0.3193187371399177, + "changed_fraction": 0.34630642361111114, + "over_4_fraction": 0.01640335648148148, + "over_16_fraction": 0.0017959104938271605 + }, + "128-ground-baseline-repeat": { + "mean_abs_rgb_0_255": 0.16526234567901235, + "changed_fraction": 0.265844425154321, + "over_4_fraction": 0.00433449074074074, + "over_16_fraction": 0.000394483024691358 + }, + "128-walk-r1": { + "frames": 240, + "different_cluster_count_frames": 0, + "different_triangle_count_frames": 0, + "mean_abs_rgb_0_255": 0.2880097415123457, + "changed_fraction": 0.30665895061728393, + "over_4_fraction": 0.014103973765432098, + "over_16_fraction": 0.0013855131172839507 + }, + "128-walk-r2": { + "frames": 240, + "different_cluster_count_frames": 0, + "different_triangle_count_frames": 0, + "mean_abs_rgb_0_255": 0.2970949074074074, + "changed_fraction": 0.32957947530864196, + "over_4_fraction": 0.013974247685185185, + "over_16_fraction": 0.0013478973765432098 + }, + "128-walk-baseline-repeat": { + "mean_abs_rgb_0_255": 0.14866319444444445, + "changed_fraction": 0.2369357638888889, + "over_4_fraction": 0.004045621141975308, + "over_16_fraction": 0.00038532021604938273 + }, + "512-overview-r1": { + "frames": 240, + "different_cluster_count_frames": 0, + "different_triangle_count_frames": 0, + "mean_abs_rgb_0_255": 0.11462673611111111, + "changed_fraction": 0.17119020061728396, + "over_4_fraction": 0.0027464313271604937, + "over_16_fraction": 1.109182098765432e-05 + }, + "512-overview-r2": { + "frames": 240, + "different_cluster_count_frames": 0, + "different_triangle_count_frames": 0, + "mean_abs_rgb_0_255": 0.11458027906378601, + "changed_fraction": 0.17118296682098766, + "over_4_fraction": 0.0027483603395061728, + "over_16_fraction": 1.2056327160493826e-05 + }, + "512-overview-baseline-repeat": { + "mean_abs_rgb_0_255": 0.020959362139917698, + "changed_fraction": 0.04390432098765432, + "over_4_fraction": 0.0001769868827160494, + "over_16_fraction": 0.0 + } +} diff --git a/docs/performance-results/vegetation-orbit-checks.json b/docs/performance-results/vegetation-orbit-checks.json new file mode 100644 index 0000000..fbe33bf --- /dev/null +++ b/docs/performance-results/vegetation-orbit-checks.json @@ -0,0 +1,38 @@ +[ + { + "frame": 600, + "near_black_fraction": 0.0015311535493827161, + "mean_rgb": [ + 145.05685329861112, + 153.3682846257716, + 133.3710190007716 + ] + }, + { + "frame": 1200, + "near_black_fraction": 0.0018581211419753086, + "mean_rgb": [ + 145.74134886188273, + 153.7153732638889, + 133.4650318287037 + ] + }, + { + "frame": 1800, + "near_black_fraction": 0.002386670524691358, + "mean_rgb": [ + 145.47381172839505, + 153.37196228780863, + 133.02684027777778 + ] + }, + { + "frame": 2400, + "near_black_fraction": 0.0022550154320987656, + "mean_rgb": [ + 145.62278645833334, + 153.50937789351852, + 133.12791087962964 + ] + } +] diff --git a/docs/performance-results/vegetation-overflow-before.csv b/docs/performance-results/vegetation-overflow-before.csv new file mode 100644 index 0000000..1661e21 --- /dev/null +++ b/docs/performance-results/vegetation-overflow-before.csv @@ -0,0 +1,2 @@ +side,trees,mode,instances,source_triangles,clusters,triangles,cpu_median_ms,cpu_p95_ms,gpu_median_ms,gpu_p95_ms,wall_median_ms,scene_gpu_bytes,peak_working_bytes,peak_private_bytes,dropped,shadow_dropped +1024,65536,overview,1179649,83377378134,258592,19652992,0.375000,0.712000,2.551808,2.932224,3.201700,352956536,636760064,2034561024,10179858,0 diff --git a/docs/performance-results/vegetation-runs.csv b/docs/performance-results/vegetation-runs.csv new file mode 100644 index 0000000..9de3e0f --- /dev/null +++ b/docs/performance-results/vegetation-runs.csv @@ -0,0 +1,18 @@ +run,side,trees,mode,instances,source_triangles,clusters,triangles,cpu_median_ms,cpu_p95_ms,gpu_median_ms,gpu_p95_ms,wall_median_ms,scene_gpu_bytes,peak_working_bytes,peak_private_bytes,dropped,shadow_dropped +final-baseline-128-ground-r1,128,1024,ground,18433,1302163010,487730,54774608,0.376100,0.573500,5.904224,6.222656,6.432200,111423608,363913216,1481236480,0,0 +final-baseline-128-ground-r2,128,1024,ground,18433,1302163010,487730,54774608,0.380000,0.691700,5.967360,6.396800,6.541300,111423608,367038464,1482547200,0,0 +final-baseline-128-walk-r1,128,1024,walk,18433,1302163010,488315,54836600,0.384000,0.723200,5.923168,7.118528,6.498600,111423608,363589632,1479233536,0,0 +final-baseline-128-walk-r2,128,1024,walk,18433,1302163010,488315,54836600,0.406400,0.727600,6.049888,7.247008,6.666800,111423608,366710784,1481469952,0,0 +final-baseline-512-overview-r1,512,16384,overview,294913,20843387906,582253,51474910,0.377100,0.574200,4.259168,4.547200,4.754200,168931448,427356160,1548587008,0,0 +final-baseline-512-overview-r2,512,16384,overview,294913,20843387906,582253,51474910,0.378600,0.474400,4.281888,4.562656,4.766400,168931448,428978176,1547784192,0,0 +final-candidate-128-ground-r1,128,1024,ground,18433,1302163010,487730,54774608,0.372200,0.713700,5.337920,5.676768,5.907400,111423608,370003968,1482706944,0,0 +final-candidate-128-ground-r2,128,1024,ground,18433,1302163010,487730,54774608,0.372400,0.717100,5.379040,5.713824,5.913500,111423608,366379008,1481371648,0,0 +final-candidate-128-walk-r1,128,1024,walk,18433,1302163010,488315,54836600,0.377800,0.676400,5.399424,6.480224,5.974700,111423608,365076480,1481543680,0,0 +final-candidate-128-walk-r2,128,1024,walk,18433,1302163010,488315,54836600,0.378000,0.715100,5.454816,6.563360,6.022900,111423608,365043712,1481310208,0,0 +final-candidate-512-overview-r1,512,16384,overview,294913,20843387906,582253,51474910,0.371700,0.609000,3.538720,3.807168,4.024600,168931448,429019136,1548136448,0,0 +final-candidate-512-overview-r2,512,16384,overview,294913,20843387906,582253,51474910,0.370800,0.551600,3.556672,3.832416,4.043200,168931448,427933696,1550475264,0,0 +final-candidate-1024-ground-stress,1024,65536,ground,1179649,83377378134,608457,66527832,0.393100,0.675400,6.620000,7.248704,7.179500,352956536,639803392,2037440512,0,0 +final-candidate-1024-overview-stress,1024,65536,overview,1179649,83377378134,1306277,103911475,0.392300,0.586700,6.043168,6.504832,6.622400,352956536,644784128,2041184256,0,0 +final-candidate-128-dense-stress,128,16384,ground,49153,8200087606,124453,12942710,0.559100,0.579200,4.158400,6.853888,4.851400,117813368,369954816,1488896000,0,0 +final-candidate-128-orbit-stress,128,1024,orbit,18433,1302163010,492182,55258314,0.617500,0.937700,5.291648,8.567520,6.069900,111423608,405987328,1533460480,0,0 +final-candidate-512-grass-stress,512,0,ground,262145,13480493058,854881,89517544,0.562000,0.688500,5.764096,6.089632,6.478600,162115704,426393600,1549246464,0,0 diff --git a/docs/vegetation-performance.md b/docs/vegetation-performance.md new file mode 100644 index 0000000..3ec38b5 --- /dev/null +++ b/docs/vegetation-performance.md @@ -0,0 +1,116 @@ +# Vegetation performance audit + +This follows the correctness, page packing and streaming work in [PR #85](https://github.com/SamG-Coder/solstice/pull/85). The baseline is `a07a4b48487cf8c1f907e7e6935a7b634793a8df`, including those fixes. + +## Workload and measurement + +The new `solstice-render` example `vegetation_stress` builds actual procedural meadow geometry and oak, birch and fir trees. Each tree has wood and leaf instances. Grass patches are two metres across; transforms and species selection use a fixed seed. The ground, textures, materials, geometry, lighting and camera paths are identical between versions. + +All runs use 1920 × 1080, release builds and the default high-quality settings: render scale 1, LOD error 1, temporal accumulation, clouds, eight probe rays, animated vegetation and no speck approximation. The renderer warms up for 48 frames and advances time by exactly 1/60 second per frame. Comparisons measure the next 240 frames. Baseline/candidate order reverses in the second repetition. + +Hardware: NVIDIA RTX 5080, Ryzen 7 9800X3D, Windows, native Vulkan through wgpu. These are native measurements of the shared renderer; they are not browser FPS measurements. + +* GPU time is the sum of the renderer's per-pass timestamp measurements. +* CPU time covers `Renderer::render`, including command encoding and submission, but excludes the explicit GPU wait. Wall time includes that wait. Neither number includes procedural generation or shader/pipeline startup. +* `scene_gpu_bytes` counts the existing scene memory categories, not all GPU allocations. Process working set and private commit are sampled during measured frames; they are not VRAM measurements or whole-process lifetime peaks. +* Geometry is fully resident. These runs test instance count, culling, rasterization and steady-state memory. They do not model network latency or a forest of unique assets. Three tree variants and one meadow mesh share geometry across all instances. +* Source triangle counts include every instance before LOD/visibility selection. Selected triangle counts describe what reaches rasterization, not necessarily how many triangles cover a pixel. +* Each run writes per-frame CSV data and a final PNG. Any nonzero main-view or shadow dropped-cluster count fails the run, so overflow cannot silently count as a performance gain. + +## Results + +Medians across 480 measured frames per version (two 240-frame runs). Lower times are better. + +| Scene and view | GPU before | GPU after | Reduction | CPU before | CPU after | +| --- | ---: | ---: | ---: | ---: | ---: | +| 16,384 grass patches + 1,024 trees, ground | 5.938 ms | 5.357 ms | 9.8% | 0.378 ms | 0.372 ms | +| Same forest, walking/turning | 5.976 ms | 5.426 ms | 9.2% | 0.398 ms | 0.378 ms | +| 262,144 grass patches + 16,384 trees, overview | 4.271 ms | 3.547 ms | 17.0% | 0.378 ms | 0.371 ms | + +The first raster pass fell from 3.094 to 2.432 ms in the ground view, and from 2.212 to 1.744 ms in the large overview. The overview's first cull fell from 0.622 to 0.390 ms. CPU medians improved slightly in this pair of repetitions, but exploratory runs varied more than that difference; a reliable CPU speedup has not been established. Process working set/private commit also did not demonstrate a consistent decrease. The measured allocation reduction is the unused GPU particle buffers described below, not a claim of lower whole-process RAM. + +Additional runs of the final implementation: + +| Grass patches | Trees | View | Render instances | Selected triangles at final frame | GPU median | Dropped work | +| ---: | ---: | --- | ---: | ---: | ---: | ---: | +| 1,048,576 | 65,536 | Overview | 1,179,649 | 103,911,475 | 6.043 ms | 0 | +| 1,048,576 | 65,536 | Ground | 1,179,649 | 66,527,832 | 6.620 ms | 0 | +| 262,144 | 0 | Ground | 262,145 | 89,517,544 | 5.764 ms | 0 | +| 16,384 | 16,384 | Dense forest, ground | 49,153 | 12,942,710 | 4.158 ms | 0 | +| 16,384 | 1,024 | Four full rotations, 2,400 frames | 18,433 | 55,258,314 | 5.292 ms | 0 | + +Both main-view and shadow dropped counters remained zero throughout the measured frames of these final runs. The million-patch overview before early rejection failed with a maximum of 10,179,858 dropped entries in a measured frame; its 2.55 ms result is invalid for a quality-preserving comparison. Denser trees can occlude more geometry, so increasing tree count need not increase selected triangles or GPU time monotonically. + +All 1,440 paired frame positions had identical selected-cluster and triangle counts between versions. Isolated raster coverage/depth and sky-cache tests are bit-exact. Full shaded PNGs are not bit-identical: mean absolute RGB differences were 0.115–0.319 on a 0–255 scale, compared with 0.021–0.165 between baseline repetitions. These differences are recorded rather than treated as exact image equivalence. Inspection of the ground views and rotation checkpoints found no large spreading black region. At the four rotation checkpoints, near-black pixels (all channels below 4) occupied 0.15–0.24% of the image. This is a 40-second simulated-time soak, not a claim of indefinite stability or validation of the user's separate street application. + +Data: [individual runs](performance-results/vegetation-runs.csv), [aggregate pass timings](performance-results/vegetation-aggregate.csv), [image differences](performance-results/vegetation-image-checks.json), [rotation checkpoints](performance-results/vegetation-orbit-checks.json), and [the failed pre-rejection million-patch run](performance-results/vegetation-overflow-before.csv). The overflow reference uses the raster/sky/particle changes but the original queueing behavior, isolating the capacity issue. + +## Changes + +### Reject unnecessary hierarchy work before queueing it + +The existing traversal checked a child's parent-error bound only after adding the child to the queue. At very high instance counts, many nodes below the required LOD cut could exhaust the 4,194,304-entry queue before being immediately rejected on the next dispatch. + +The child now goes through that same existing bound and comparison before claiming a queue entry. It still goes through the normal traversal checks when processed. This uses the bounds already stored by the baker, with the same transforms, pose margin and camera threshold. No new visibility approximation or lower detail setting is introduced. + +In the 1,048,576-patch / 65,536-tree overview, the earlier build dropped more than ten million queue entries in a measured frame. The early rejection build completed with zero drops and selected about 104 million triangles. The failed build's shorter frame time is not a valid speed baseline. + +A GPU regression checks values below, exactly at and above the threshold, alongside the existing multi-million-entry traversal/dispatch tests. This does not remove every capacity limit: a genuinely wider live frontier or visible list can still overflow and must still be reported. + +### Scan only potentially covered pixel centres + +The software rasterizer previously scanned from the floor of each triangle's minimum coordinate to the ceiling of its maximum coordinate, inclusive. Tiny grass and leaf triangles consequently visited extra rows and columns, often even when they could not cover a pixel centre. + +The new bounds come from the same rounded 8-bit subpixel coordinates used by the edge tests. They include every potentially covered centre. Triangle selection, positions, fill rules, depth interpolation, alpha coverage and LOD remain unchanged. Both opaque and masked software rasterizers, including their depth-only variants, use this shared implementation. + +A GPU regression compares the production code with an exhaustive scan of a 16 × 16 viewport for 13,402 triangles: random tiny triangles, quantization ties, exact centres, shared-edge orientations and viewport clipping. All 3,430,912 sample positions must match bit-for-bit in coverage and depth. + +### Allocate particle storage when an effect needs it + +A forest with no particle effects previously allocated the complete default 262,144-particle pool. The configured capacity and reservation semantics are preserved, while GPU storage is created on the first active `prepare`. Once allocated, storage is retained so stopping and restarting effects does not repeatedly allocate it. Resizing an unused pool remains allocation-free. + +This avoids 28,916,848 bytes (27.58 MiB) of simulation buffers at the default capacity: particle records, free/alive lists, lighting, events, emitter records, curves and indirect/uniform data. Pipelines, statistics readback and screen-sized particle targets still exist. Starting the first effect pays the allocation cost at that point. + +`Particles::buffer_bytes()` reports these allocated buffers separately from configured capacity. The new lifecycle regression checks idle frames, resizing, cancellation before preparation, a late full-budget burst and restart with retained storage. Existing particle simulation, collision, sorting, lighting and rendering tests remain relevant. + +### Reuse an unchanged atmosphere table + +The sky-view table is reused when the exact bytes of its shader parameters match the last build. Its only variable inputs are sun direction and viewer radius after the existing height conversion. Camera rotation and movement at the same height do not require rebuilding it. Changing sun or effective height rebuilds immediately, without thresholds or update-rate reduction. + +A GPU regression compares cached pixels with a forced rebuild and verifies that changing sun or height changes the output. This saves a small compute dispatch and uniform upload on unchanged frames; it is not the main vegetation speedup. + +## Remaining constraints + +The renderer stores a 208-byte GPU record per instance and a CPU copy for updates. The million-patch test therefore needs 245,366,992 bytes for the instance GPU buffer alone. A browser/device exposing a smaller single-storage-buffer binding limit cannot run that case unchanged. Splitting static and moving instance data, or paging instance records, is a separate opportunity; it is not implemented here. + +The default atmosphere is kept in all runs. The very large `overview` cameras rise into cloud/haze, so their screenshots are not useful for judging close-up leaf detail even though the selected geometry is still rasterized. Ground-level tests exercise visible nearby grass and leaves. No claim is made that every one of the scene's source triangles is simultaneously visible. + +The new early LOD rejection avoids proven unnecessary work. Back-face cones for one-sided static surfaces could eliminate other work, but two-sided leaves cannot use that rejection indiscriminately. Off-screen geometry may also remain necessary for shadows, indirect lighting and reflections. No angle-based page blacklist is introduced. + +## Reproduction + +Build the benchmark at the baseline and at the candidate, copying each executable to a distinct path. The baseline needs the benchmark source and its two dev dependencies from this change; its production renderer must remain unchanged. Do not compile or run another GPU workload during timing. + +```sh +cargo build --release -p solstice-render --example vegetation_stress +# Single run: grid side, trees, measured frames, camera, output directory +path/to/vegetation_stress 128 1024 240 ground target/vegetation/run + +# Matched runs with reversed ordering on alternate repetitions +python scripts/vegetation_stress.py --baseline path/to/before --candidate path/to/after \ + --output target/vegetation-comparison --repeats 2 --frames 240 --stress + +cargo test --release -p solstice-render --lib +cargo test --release -p solstice-render --test gpu -- --test-threads=1 +``` + +The comparison runner preserves failed-run logs and refuses to overwrite an existing run directory. `overview` scales camera height with the forest extent; `ground` and `walk` put the camera among the vegetation. The moving camera includes translation and turning. + +For a temporal-history soak, `orbit` turns through 360 degrees every 600 measured frames and writes an additional PNG after each turn. For example, `vegetation_stress 128 1024 2400 orbit target/vegetation/orbit` renders four full rotations with wind, clouds and temporal lighting enabled. + +## Validation status + +* 289 renderer unit tests passed, with one existing ignored test. The expanded early-LOD traversal regression also passed after that change. +* All 11 shader tests and 13 region tests passed, including validation of rewritten shaders. +* Native workspace/all-target Clippy with warnings denied passed. Minimal, default and editor WASM viewer builds and Clippy passed. +* The final GPU integration sweep and separate startup-overflow checks are running; their completed results will be recorded before the pull request is marked ready. diff --git a/scripts/vegetation_stress.py b/scripts/vegetation_stress.py new file mode 100644 index 0000000..34b815d --- /dev/null +++ b/scripts/vegetation_stress.py @@ -0,0 +1,79 @@ +#!/usr/bin/env python3 +"""Run two prebuilt vegetation_stress binaries sequentially at identical quality. + +Example: + python scripts/vegetation_stress.py --baseline /tmp/before --candidate /tmp/after \ + --output target/vegetation-comparison --stress + +Build/copy each binary before starting; compiling or running another GPU workload +during measurements contaminates CPU and GPU timings. No third-party packages. +""" + +import argparse +import csv +import subprocess +from pathlib import Path + + +CASES = ( + ("128-ground", 128, 1024, "ground"), + ("128-walk", 128, 1024, "walk"), + ("512-overview", 512, 16384, "overview"), +) +STRESS = ( + ("1024-overview", 1024, 65536, "overview"), + ("128-dense", 128, 16384, "ground"), + ("512-grass", 512, 0, "ground"), +) + + +def main(): + parser = argparse.ArgumentParser(description=__doc__) + parser.add_argument("--baseline", type=Path, required=True) + parser.add_argument("--candidate", type=Path, required=True) + parser.add_argument("--output", type=Path, required=True) + parser.add_argument("--frames", type=int, default=240) + parser.add_argument("--repeats", type=int, default=2) + parser.add_argument("--stress", action="store_true") + args = parser.parse_args() + if args.frames < 1 or args.repeats < 1: + parser.error("frames and repeats must be positive") + binaries = {"baseline": args.baseline.resolve(), "candidate": args.candidate.resolve()} + for binary in binaries.values(): + if not binary.is_file(): + parser.error(f"binary does not exist: {binary}") + args.output.mkdir(parents=True, exist_ok=True) + results = [] + failures = [] + cases = CASES + (STRESS if args.stress else ()) + for repeat in range(1, args.repeats + 1): + for name, side, trees, mode in cases: + # Balance startup/thermal ordering across repetitions. + versions = ("baseline", "candidate") if repeat % 2 else ("candidate", "baseline") + for version in versions: + run = f"{version}-{name}-r{repeat}" + output = (args.output / run).resolve() + # Never silently replace a previous measurement. + output.mkdir() + with (output / "summary.csv").open("w") as summary, (output / "stderr.log").open("w") as log: + result = subprocess.run( + [str(binaries[version]), str(side), str(trees), str(args.frames), mode, str(output)], + stdout=summary, stderr=log, check=False, + ) + print(f"{run}: exit {result.returncode}", flush=True) + if result.returncode: + failures.append(run) + with (output / "summary.csv").open(newline="") as summary: + for row in csv.DictReader(summary): + results.append({"run": run, "exit_code": result.returncode, **row}) + if results: + with (args.output / "comparison.csv").open("w", newline="") as output: + writer = csv.DictWriter(output, fieldnames=list(results[0])) + writer.writeheader() + writer.writerows(results) + if failures: + raise SystemExit("Failed or overflowed runs (inspect stderr.log): " + ", ".join(failures)) + + +if __name__ == "__main__": + main()