use super::{VIEWER_FOV_DEG, resolve_facet_finishes, trace_into};
use glam::Vec3;
use indicatrix::{
optics::raytracer::Camera,
renderer::gpu_backend::{GpuAccumulate, GpuBackend, GpuSceneRef},
};
use indicatrix_net::SceneState;
use std::{
sync::atomic::{AtomicBool, Ordering},
thread,
time::Instant,
};
pub const HYBRID_MIN_SPP: u32 = 8;
fn cpu_threads_beside_gpu(threads: usize) -> usize {
super::effective_thread_count(threads)
.saturating_sub(1)
.max(1)
}
const HYBRID_MAX_GPU_SHARE: f64 = 0.7;
fn cpu_is_worth_splitting_with(gpu_share_frac: f64) -> bool {
gpu_share_frac < HYBRID_MAX_GPU_SHARE
}
#[derive(Debug, Clone, Copy, PartialEq)]
pub enum CalibrationOutcome {
Split(f64, u32),
GpuDeclined,
GpuDominates { gpu_share_frac: f64 },
Cancelled { consumed: u32 },
}
fn scene_pieces(scene: &SceneState) -> (Camera, Vec<indicatrix::optics::raytracer::FacetFinish>) {
let camera = Camera::new(scene.yaw, scene.pitch, scene.distance, VIEWER_FOV_DEG);
(camera, resolve_facet_finishes(scene))
}
#[must_use]
pub fn calibrate(
gpu: &GpuBackend,
scene: &SceneState,
first_sample: u32,
samples: u32,
threads: usize,
out: &mut [Vec3],
cancel: &AtomicBool,
) -> CalibrationOutcome {
if samples < 3 {
return CalibrationOutcome::GpuDeclined;
}
if cancel.load(Ordering::Relaxed) {
return CalibrationOutcome::Cancelled { consumed: 0 };
}
let (camera, facet_finishes) = scene_pieces(scene);
let environment =
scene
.lighting_preset
.studio(scene.exposure, scene.light_yaw, scene.light_pitch);
let gpu_scene = GpuSceneRef {
camera: &camera,
width: scene.width,
height: scene.height,
planes: &scene.planes,
facet_finishes: &facet_finishes,
material: &scene.material,
max_bounces: scene.max_bounces,
environment,
};
match gpu.try_accumulate_cancellable(&gpu_scene, first_sample, 1, out, cancel) {
GpuAccumulate::Done => {}
GpuAccumulate::Declined => return CalibrationOutcome::GpuDeclined,
GpuAccumulate::Cancelled => return CalibrationOutcome::Cancelled { consumed: 0 },
}
if cancel.load(Ordering::Relaxed) {
return CalibrationOutcome::Cancelled { consumed: 1 };
}
let start = Instant::now();
match gpu.try_accumulate_cancellable(&gpu_scene, first_sample + 1, 1, out, cancel) {
GpuAccumulate::Done => {}
GpuAccumulate::Declined => return CalibrationOutcome::GpuDeclined,
GpuAccumulate::Cancelled => return CalibrationOutcome::Cancelled { consumed: 1 },
}
let gpu_time = start.elapsed().as_secs_f64().max(1e-9);
if cancel.load(Ordering::Relaxed) {
return CalibrationOutcome::Cancelled { consumed: 2 };
}
let start = Instant::now();
trace_into(
scene,
first_sample + 2,
1,
threads,
&camera,
environment,
out,
);
let cpu_time = start.elapsed().as_secs_f64().max(1e-9);
let frac = (cpu_time / (gpu_time + cpu_time)).clamp(0.0, 1.0);
if !cpu_is_worth_splitting_with(frac) {
return CalibrationOutcome::GpuDominates {
gpu_share_frac: frac,
};
}
CalibrationOutcome::Split(frac, 3)
}
pub fn hybrid_trace(
gpu: &GpuBackend,
scene: &SceneState,
first_sample: u32,
samples: u32,
threads: usize,
gpu_frac: &mut Option<f64>,
cancel: &AtomicBool,
) -> Option<Vec<Vec3>> {
let width = scene.width;
let height = scene.height;
let mut buffer = vec![Vec3::ZERO; width as usize * height as usize];
if samples == 0 || width == 0 || height == 0 {
return Some(buffer);
}
let frac = gpu_frac.unwrap_or(0.0);
let gpu_share = ((f64::from(samples) * frac).round() as u32).min(samples);
let cpu_share = samples - gpu_share;
let (camera, facet_finishes) = scene_pieces(scene);
let environment =
scene
.lighting_preset
.studio(scene.exposure, scene.light_yaw, scene.light_pitch);
if gpu_share == 0 {
trace_into(
scene,
first_sample,
samples,
threads,
&camera,
environment,
&mut buffer,
);
return Some(buffer);
}
let gpu_scene = GpuSceneRef {
camera: &camera,
width,
height,
planes: &scene.planes,
facet_finishes: &facet_finishes,
material: &scene.material,
max_bounces: scene.max_bounces,
environment,
};
let mut gpu_buf = vec![Vec3::ZERO; width as usize * height as usize];
let (gpu_outcome, gpu_elapsed, cpu_elapsed) = if cpu_share == 0 {
let start = Instant::now();
let outcome = gpu.try_accumulate_cancellable(
&gpu_scene,
first_sample,
gpu_share,
&mut gpu_buf,
cancel,
);
(outcome, start.elapsed(), std::time::Duration::ZERO)
} else {
let cpu = CpuShare {
scene,
first_sample: first_sample + gpu_share,
samples: cpu_share,
threads: cpu_threads_beside_gpu(threads),
buffer: &mut buffer,
};
dispatch_concurrently(
gpu,
&gpu_scene,
first_sample,
gpu_share,
&mut gpu_buf,
cancel,
cpu,
)
};
match gpu_outcome {
GpuAccumulate::Cancelled => return None,
GpuAccumulate::Declined => {
trace_into(
scene,
first_sample,
gpu_share,
threads,
&camera,
environment,
&mut buffer,
);
*gpu_frac = None;
return Some(buffer);
}
GpuAccumulate::Done => {}
}
for (b, g) in buffer.iter_mut().zip(&gpu_buf) {
*b += *g;
}
if cpu_share > 0 {
*gpu_frac = Some(blend_gpu_frac(
frac,
gpu_share,
cpu_share,
gpu_elapsed,
cpu_elapsed,
));
}
Some(buffer)
}
struct CpuShare<'a> {
scene: &'a SceneState,
first_sample: u32,
samples: u32,
threads: usize,
buffer: &'a mut [Vec3],
}
#[expect(
clippy::needless_pass_by_value,
reason = "CpuShare::buffer is an exclusive &mut [Vec3] that must be MOVED into \
trace_into below; taking `&CpuShare` instead would make that reborrow \
impossible from behind a shared reference, so by-value is the only option"
)]
fn dispatch_concurrently(
gpu: &GpuBackend,
gpu_scene: &GpuSceneRef<'_>,
first_sample: u32,
gpu_share: u32,
gpu_buf: &mut [Vec3],
cancel: &AtomicBool,
cpu: CpuShare<'_>,
) -> (GpuAccumulate, std::time::Duration, std::time::Duration) {
thread::scope(|scope| {
let gpu_handle = scope.spawn(move || {
let start = Instant::now();
let outcome =
gpu.try_accumulate_cancellable(gpu_scene, first_sample, gpu_share, gpu_buf, cancel);
(outcome, start.elapsed())
});
let cpu_start = Instant::now();
trace_into(
cpu.scene,
cpu.first_sample,
cpu.samples,
cpu.threads,
gpu_scene.camera,
gpu_scene.environment,
cpu.buffer,
);
let cpu_elapsed = cpu_start.elapsed();
let (outcome, gpu_elapsed) = gpu_handle
.join()
.unwrap_or_else(|payload| std::panic::resume_unwind(payload));
(outcome, gpu_elapsed, cpu_elapsed)
})
}
fn blend_gpu_frac(
frac: f64,
gpu_share: u32,
cpu_share: u32,
gpu_elapsed: std::time::Duration,
cpu_elapsed: std::time::Duration,
) -> f64 {
let gpu_rate = f64::from(gpu_share) / gpu_elapsed.as_secs_f64().max(1e-9);
let cpu_rate = f64::from(cpu_share) / cpu_elapsed.as_secs_f64().max(1e-9);
let measured_frac = gpu_rate / (gpu_rate + cpu_rate);
let updated = frac.mul_add(0.7, measured_frac * 0.3).clamp(0.0, 1.0);
if cpu_is_worth_splitting_with(updated) {
updated
} else {
1.0
}
}
#[cfg(test)]
mod tests {
use super::*;
use indicatrix::{
geometry::cuts::StandardGemCuts,
optics::{materials::GemMaterial, raytracer::LightingPreset},
};
fn tiny_scene() -> SceneState {
SceneState {
width: 8,
height: 8,
yaw: 0.4,
pitch: 0.3,
distance: 3.0,
light_yaw: 0.85,
light_pitch: 0.95,
exposure: 1.0,
max_bounces: 4,
lighting_preset: LightingPreset::Daylight,
material: GemMaterial::diamond(),
planes: StandardGemCuts::standard_round_brilliant(),
girdle_frosted: false,
}
}
fn never_cancel() -> AtomicBool {
AtomicBool::new(false)
}
#[test]
fn calibrate_declines_when_the_gpu_declines() {
let scene = tiny_scene();
let gpu = GpuBackend::disabled();
let mut out = vec![Vec3::ZERO; 64];
assert_eq!(
calibrate(&gpu, &scene, 0, 8, 1, &mut out, &never_cancel()),
CalibrationOutcome::GpuDeclined
);
assert!(out.iter().all(|v| *v == Vec3::ZERO));
}
#[test]
fn calibrate_declines_when_there_are_too_few_samples_to_probe_with() {
let scene = tiny_scene();
let gpu = GpuBackend::disabled();
let mut out = vec![Vec3::ZERO; 64];
assert_eq!(
calibrate(&gpu, &scene, 0, 2, 1, &mut out, &never_cancel()),
CalibrationOutcome::GpuDeclined
);
}
#[test]
fn calibrate_honors_a_cancel_already_set_before_the_first_probe_sample() {
let scene = tiny_scene();
let gpu = GpuBackend::disabled();
let mut out = vec![Vec3::ZERO; 64];
let cancel = AtomicBool::new(true);
assert_eq!(
calibrate(&gpu, &scene, 0, 8, 1, &mut out, &cancel),
CalibrationOutcome::Cancelled { consumed: 0 }
);
assert!(out.iter().all(|v| *v == Vec3::ZERO));
}
#[test]
fn hybrid_trace_falls_back_to_cpu_only_when_gpu_frac_is_none() {
let scene = tiny_scene();
let gpu = GpuBackend::disabled();
let mut gpu_frac = None;
let hybrid = hybrid_trace(&gpu, &scene, 0, 4, 1, &mut gpu_frac, &never_cancel())
.expect("gpu_share == 0 here, so this can never observe a cancellation");
let cpu_only = render_core_trace_samples(&scene, 0, 4, 1);
assert_eq!(hybrid, cpu_only);
assert_eq!(gpu_frac, None);
}
#[test]
fn hybrid_trace_sums_to_the_same_result_as_tracing_the_whole_range_on_cpu() {
let scene = tiny_scene();
let gpu = GpuBackend::disabled();
let mut gpu_frac = Some(0.8);
let hybrid = hybrid_trace(&gpu, &scene, 10, 6, 2, &mut gpu_frac, &never_cancel())
.expect("gpu_share == 0 here, so this can never observe a cancellation");
let direct = render_core_trace_samples(&scene, 10, 6, 2);
assert_eq!(hybrid, direct);
}
fn render_core_trace_samples(
scene: &SceneState,
first: u32,
samples: u32,
threads: usize,
) -> Vec<Vec3> {
super::super::trace_samples(scene, first, samples, threads)
}
fn adaptive_next_batch_size(prev: u32, elapsed: std::time::Duration) -> u32 {
const TARGET: std::time::Duration = std::time::Duration::from_millis(100);
const MAX_SUBBATCH: u32 = 2048;
if elapsed.is_zero() {
return prev.saturating_mul(4).clamp(1, MAX_SUBBATCH);
}
let ratio = TARGET.as_secs_f64() / elapsed.as_secs_f64();
let scaled = f64::from(prev) * ratio;
let max_growth = f64::from(prev.saturating_mul(4).clamp(1, MAX_SUBBATCH));
scaled.clamp(1.0, max_growth).round() as u32
}
fn time_adaptive_loop(total: u32, mut trace: impl FnMut(u32, u32)) -> std::time::Duration {
let overall = Instant::now();
let mut produced = 0u32;
let mut batch_size = 1u32;
while produced < total {
let this_batch = batch_size.min(total - produced);
let start = Instant::now();
trace(produced, this_batch);
let elapsed = start.elapsed();
produced += this_batch;
batch_size = adaptive_next_batch_size(batch_size, elapsed);
}
overall.elapsed()
}
fn warm_up_gpu(gpu: &GpuBackend, scene: &SceneState) {
let mut warm = vec![Vec3::ZERO; scene.width as usize * scene.height as usize];
let _ = gpu.try_accumulate(
&GpuSceneRef {
camera: &Camera::new(
scene.yaw,
scene.pitch,
scene.distance,
super::VIEWER_FOV_DEG,
),
width: scene.width,
height: scene.height,
planes: &scene.planes,
facet_finishes: &[],
material: &scene.material,
max_bounces: scene.max_bounces,
environment: scene.lighting_preset.studio(
scene.exposure,
scene.light_yaw,
scene.light_pitch,
),
},
0,
1,
&mut warm,
);
}
#[test]
#[ignore = "manual measurement: prints GPU-only vs. hybrid throughput on this machine's real adapter"]
fn measure_hybrid_speedup_against_gpu_only() {
let gpu = GpuBackend::acquire();
assert!(
gpu.adapter_label().is_some(),
"this measurement requires a real adapter -- run probe_gpu_adapter first"
);
let scene = SceneState {
width: 800,
height: 600,
max_bounces: 6,
..tiny_scene()
};
let total_samples: u32 = 2000;
let threads = 0;
warm_up_gpu(&gpu, &scene);
let gpu_only_elapsed = time_adaptive_loop(total_samples, |first, n| {
let _ = super::super::trace_samples_with_gpu(&gpu, &scene, first, n, threads);
});
let hybrid_start = Instant::now();
{
let mut calib_buf = vec![Vec3::ZERO; scene.width as usize * scene.height as usize];
let (frac, consumed) = match calibrate(
&gpu,
&scene,
0,
total_samples,
threads,
&mut calib_buf,
&never_cancel(),
) {
CalibrationOutcome::Split(frac, consumed) => (frac, consumed),
other => panic!("gpu available, expected a Split outcome, got {other:?}"),
};
let mut gpu_frac = Some(frac);
let mut produced = consumed;
let mut batch_size = 1u32;
while produced < total_samples {
let this_batch = batch_size.min(total_samples - produced);
let start = Instant::now();
let _ = hybrid_trace(
&gpu,
&scene,
produced,
this_batch,
threads,
&mut gpu_frac,
&never_cancel(),
);
let elapsed = start.elapsed();
produced += this_batch;
batch_size = adaptive_next_batch_size(batch_size, elapsed);
}
eprintln!("final gpu_frac={gpu_frac:?}");
}
let hybrid_elapsed = hybrid_start.elapsed();
let cpu_only_samples: u32 = 200; let cpu_only_elapsed = time_adaptive_loop(cpu_only_samples, |first, n| {
let _ = super::super::trace_samples(&scene, first, n, threads);
});
let cpu_only_rate = f64::from(cpu_only_samples) / cpu_only_elapsed.as_secs_f64();
let gpu_only_rate = f64::from(total_samples) / gpu_only_elapsed.as_secs_f64();
let hybrid_rate = f64::from(total_samples) / hybrid_elapsed.as_secs_f64();
eprintln!(
"GPU-only: {total_samples} samples in {gpu_only_elapsed:?} ({gpu_only_rate:.1} samples/s)"
);
eprintln!(
"Hybrid: {total_samples} samples in {hybrid_elapsed:?} ({hybrid_rate:.1} samples/s)"
);
eprintln!(
"CPU-only: {cpu_only_samples} samples in {cpu_only_elapsed:?} ({cpu_only_rate:.1} samples/s)"
);
eprintln!(
"Speedup (hybrid vs GPU-only): {:.2}x",
hybrid_rate / gpu_only_rate
);
eprintln!(
"GPU is {:.1}x faster than CPU per-sample on this scene",
gpu_only_rate / cpu_only_rate
);
}
#[test]
fn cpu_threads_beside_gpu_never_returns_zero() {
assert_eq!(cpu_threads_beside_gpu(1), 1, "one core still traces");
assert_eq!(cpu_threads_beside_gpu(2), 1, "two cores: one reserved");
assert!(
cpu_threads_beside_gpu(0) >= 1,
"0 means `all available`, which must still resolve to at least one thread"
);
}
#[test]
fn cpu_threads_beside_gpu_reserves_exactly_one_core() {
for n in 3..=16usize {
assert_eq!(
cpu_threads_beside_gpu(n),
n - 1,
"with {n} cores the tracer should get {} of them",
n - 1
);
}
}
}