3D engine that AI agents drive
//! A persistent Cycles render session (issue 896). It owns what a render needs that does not change from one frame to
//! the next: the device handle, the scene tables on the card, the acceleration structures, the compiled pipeline and the
//! film with its bind group. A frame then only writes the kernel parameters (camera, image size, sample count), clears the
//! film and dispatches. The one-shot `traceSceneCycles` is a session that renders once.
use std::sync::atomic::Ordering;
use std::time::Instant;
use napi::bindgen_prelude::{Float32Array, Uint32Array, Uint8Array};
use napi::Result;
use crate::cycles::{
assemble_cycles_kernel_entry, check_counts_match_kernel_params, check_frame_params_keep_scene_counts,
check_update_params_keep_scene_shape, scan_scene_specialization, specialize_kernel_source,
trace_entry_point_for_params, SceneSpecialization,
};
use crate::host::accel::{build_cycles_acceleration_structure, rebuild_cycles_tlas, CyclesAcceleration, INSTANCE_RECORD_BYTES};
use crate::host::cycles_update::{choose_film_use, plan_instance_update, FilmRequest, ProgressiveFilm, UpdatableTable};
use crate::host::device::{failure, storage_buffer};
use crate::host::film::{image_accumulation_bytes, image_workgroups, read_accumulation};
use crate::host::session::{
create_cycles_bind_group, get_cycles_device_context, get_or_compile_cycles_pipeline_on, pipeline_key,
trace_cycles_samples, validate_cycles_input, validate_kernel_params_v2, validate_light_tree_flag_has_tables,
validate_render_extent, with_cycles_cache_on, CyclesDeviceContext, CyclesDispatchTarget, CyclesTrace, DispatchPlan,
PipelineKey,
};
use crate::host::textures::{check_texture_pool_budget, create_cycles_film, create_cycles_parameters, upload_cycles_scene_tables};
use crate::NativeTraceInputV2;
const KERNEL_PARAMS_WIDTH_BYTE: usize = 8;
const KERNEL_PARAMS_HEIGHT_BYTE: usize = 12;
const KERNEL_PARAMS_TOTAL_SAMPLES_BYTE: usize = 24;
/// A wall clock limit under this many seconds keeps one sample per dispatch so the limit is checked often.
const TIGHT_TIME_LIMIT_SECONDS: f64 = 2.0;
/// What one frame asks of a session.
pub(crate) struct CyclesRenderRequest<'a> {
pub(crate) width: u32,
pub(crate) height: u32,
pub(crate) samples: u32,
pub(crate) samples_per_dispatch: Option<u32>,
pub(crate) max_seconds: Option<f64>,
pub(crate) bootstrap_kernel: bool,
/// A KernelParamsV2 block for this frame (another camera, seed or filter of the same scene); absent means the block
/// the session was created with.
pub(crate) kernel_params: Option<&'a [u8]>,
/// Add this call's samples to the film instead of starting a new image (see `choose_film_use`).
pub(crate) accumulate: bool,
/// The sample count of the whole image; required by the first accumulating call, optional (and equal) after.
pub(crate) target_samples: Option<u32>,
}
/// New values for the scene tables a session holds, with the kernel parameters that go with them. Only the tables that
/// changed are listed.
pub(crate) struct CyclesSceneUpdate<'a> {
pub(crate) kernel_params: &'a [u8],
pub(crate) tables: Vec<(UpdatableTable, &'a [u8])>,
}
/// What an update did, so a test or a caller can see it kept the pipeline and the BLAS instead of timing it.
pub(crate) struct CyclesUpdateReport {
/// The tables whose buffers were replaced, by their input names.
pub(crate) uploaded_tables: Vec<&'static str>,
/// The TLAS was rebuilt over the kept BLAS (a transform or ray visibility changed).
pub(crate) acceleration_rebuilt: bool,
/// How many instance records differ from the old table.
pub(crate) changed_instances: u32,
/// The new tables change what the kernel text is specialized for, so the next render compiles it again.
pub(crate) kernel_respecialized: bool,
pub(crate) upload_seconds: f64,
pub(crate) acceleration_rebuild_seconds: f64,
pub(crate) update_seconds: f64,
}
/// The per-phase seconds of one frame and what it reused. A frame that reuses something spends no time on it: the
/// first frame of a session carries the setup, upload and acceleration build seconds of the creation.
pub(crate) struct CyclesRenderReport {
pub(crate) setup_seconds: f64,
pub(crate) compile_seconds: f64,
pub(crate) upload_seconds: f64,
pub(crate) acceleration_build_seconds: f64,
/// The session already held the compiled pipeline this frame needed.
pub(crate) pipeline_reused: bool,
/// The acceleration structures were built by an earlier call, not for this frame.
pub(crate) acceleration_reused: bool,
/// The film and its bind group were kept from the previous frame (same image size).
pub(crate) film_reused: bool,
/// How many frames this session finished before this one.
pub(crate) frame_index: u32,
/// The index of the first sample this call drew (0 unless it continued a progressive film).
pub(crate) first_sample: u32,
/// How many samples the film holds after this call.
pub(crate) film_samples: u32,
/// The sample count the progressive film was started for; absent for a plain frame.
pub(crate) target_samples: Option<u32>,
}
pub(crate) struct CyclesRender {
pub(crate) trace: CyclesTrace,
pub(crate) report: CyclesRenderReport,
}
/// What creating the session cost; the first frame reports it.
#[derive(Clone, Copy)]
struct CreationCosts {
setup_seconds: f64,
upload_seconds: f64,
acceleration_build_seconds: f64,
}
struct HeldPipeline {
key: PipelineKey,
pipeline: wgpu::ComputePipeline,
}
struct SessionFilm {
width: u32,
height: u32,
accumulation: wgpu::Buffer,
bind_group: wgpu::BindGroup,
}
/// Everything on the card. Dropping it frees the card, which is what `close` does.
struct SessionGpuState {
scene_tables: Vec<wgpu::Buffer>,
acceleration: CyclesAcceleration,
parameters: wgpu::Buffer,
pipeline: Option<HeldPipeline>,
film: Option<SessionFilm>,
}
impl SessionGpuState {
fn film(&self) -> Result<&SessionFilm> {
self.film.as_ref().ok_or_else(|| failure("The session film is missing; this is a bug in the session."))
}
fn pipeline(&self) -> Result<&HeldPipeline> {
self.pipeline.as_ref().ok_or_else(|| failure("The session pipeline is missing; this is a bug in the session."))
}
}
/// The number of scene buffers `upload_cycles_scene_tables` makes.
const SCENE_BUFFER_COUNT: usize = 11;
/// Host copies of what the kernel specialization reads, so an update can scan the new tables without the whole input:
/// the record counts and the small tables the scan walks. The triangles, texels and emitters are not kept.
/// If `scan_scene_specialization` starts to read another table, keep it here too.
struct RetainedTables {
instance_count: u32,
material_count: u32,
emissive_triangle_count: u32,
light_count: u32,
light_tree_node_count: u32,
texture_count: u32,
instances: Vec<u8>,
materials: Vec<u8>,
lights: Vec<u8>,
texture_descriptors: Vec<u8>,
/// The byte length of each scene buffer's source, by buffer index: an update must bring a table of the same size.
table_lengths: [usize; SCENE_BUFFER_COUNT],
}
impl RetainedTables {
fn of_input(input: &NativeTraceInputV2) -> RetainedTables {
let mut table_lengths = [0usize; SCENE_BUFFER_COUNT];
table_lengths[UpdatableTable::Instances.buffer_index()] = input.instances.len();
table_lengths[UpdatableTable::Materials.buffer_index()] = input.materials.len();
table_lengths[UpdatableTable::EmissiveTriangles.buffer_index()] = input.emissive_triangles.len();
table_lengths[UpdatableTable::Lights.buffer_index()] = input.lights.len();
table_lengths[UpdatableTable::LightTreeNodes.buffer_index()] = input.light_tree_nodes.len();
table_lengths[UpdatableTable::LightTreeEmitters.buffer_index()] =
input.light_tree_emitters.as_ref().map_or(0, |emitters| emitters.len());
table_lengths[UpdatableTable::LightToTree.buffer_index()] =
input.light_to_tree.as_ref().map_or(0, |words| words.len() * 4);
RetainedTables {
instance_count: input.instance_count,
material_count: input.material_count,
emissive_triangle_count: input.emissive_triangle_count,
light_count: input.light_count,
light_tree_node_count: input.light_tree_node_count,
texture_count: input.texture_count,
instances: input.instances.to_vec(),
materials: input.materials.to_vec(),
lights: input.lights.to_vec(),
texture_descriptors: input.texture_descriptors.to_vec(),
table_lengths,
}
}
/// The specialization of these tables; equal to `scan_scene_specialization` of the whole input they came from.
fn specialization(&self) -> SceneSpecialization {
let scan_input = NativeTraceInputV2 {
schema_version: 2,
kernel_params: Uint8Array::new(Vec::new()),
instances: Uint8Array::new(self.instances.clone()),
instance_count: self.instance_count,
triangles: Uint8Array::new(Vec::new()),
triangle_count: 0,
materials: Uint8Array::new(self.materials.clone()),
material_count: self.material_count,
emissive_triangles: Uint8Array::new(Vec::new()),
emissive_triangle_count: self.emissive_triangle_count,
lights: Uint8Array::new(self.lights.clone()),
light_count: self.light_count,
light_tree_nodes: Uint8Array::new(Vec::new()),
light_tree_node_count: self.light_tree_node_count,
light_tree_emitters: None,
light_tree_emitter_count: None,
light_to_tree: None,
texture_descriptors: Uint8Array::new(self.texture_descriptors.clone()),
texture_count: self.texture_count,
texture_texels: Uint32Array::new(Vec::new()),
environment_texels: Float32Array::new(Vec::new()),
};
scan_scene_specialization(&scan_input)
}
fn keep_table(&mut self, table: UpdatableTable, bytes: &[u8]) {
match table {
UpdatableTable::Instances => self.instances = bytes.to_vec(),
UpdatableTable::Materials => self.materials = bytes.to_vec(),
UpdatableTable::Lights => self.lights = bytes.to_vec(),
_ => {}
}
}
}
pub(crate) struct CyclesSession {
context: CyclesDeviceContext,
/// The kernel parameters the session was created with (or last updated to), the default for a frame that brings none.
session_kernel_params: Vec<u8>,
scene_specialization: SceneSpecialization,
retained: RetainedTables,
light_tree_node_count: u32,
has_light_tree_tables: bool,
creation_costs: Option<CreationCosts>,
renders_completed: u32,
/// The image being built over several calls; `None` after a plain frame, a reset, an update or a failed call.
progressive: Option<ProgressiveFilm>,
/// The film holds the samples of the last successful render, so `resolve` has something to read.
film_holds_samples: bool,
/// How many samples per pixel the film holds; meaningful while `film_holds_samples`.
film_sample_count: u32,
/// `None` once the session is closed.
gpu: Option<SessionGpuState>,
}
/// The kernel parameters of one render: the frame's block with the image size and the total sample count written in.
pub(crate) fn patch_render_parameters(kernel_params: &[u8], width: u32, height: u32, total_samples: u32) -> Vec<u8> {
let mut patched = kernel_params.to_vec();
patched[KERNEL_PARAMS_WIDTH_BYTE..KERNEL_PARAMS_WIDTH_BYTE + 4].copy_from_slice(&width.to_le_bytes());
patched[KERNEL_PARAMS_HEIGHT_BYTE..KERNEL_PARAMS_HEIGHT_BYTE + 4].copy_from_slice(&height.to_le_bytes());
patched[KERNEL_PARAMS_TOTAL_SAMPLES_BYTE..KERNEL_PARAMS_TOTAL_SAMPLES_BYTE + 4]
.copy_from_slice(&total_samples.to_le_bytes());
patched
}
/// Unless the caller fixes the batch, each dispatch is sized from the time of the last so none runs long enough for the
/// driver to reset the device. A wall-clock limit under 2 s keeps one sample per dispatch for tight responsiveness.
pub(crate) fn choose_dispatch_plan(samples: u32, samples_per_dispatch: Option<u32>, max_seconds: Option<f64>) -> DispatchPlan {
match samples_per_dispatch {
Some(samples_per_dispatch) => DispatchPlan::Fixed(samples_per_dispatch.max(1)),
None => match max_seconds {
Some(limit) if limit < TIGHT_TIME_LIMIT_SECONDS => DispatchPlan::Fixed(1),
_ => DispatchPlan::TimeBudget { largest_batch: samples.max(1) },
},
}
}
fn session_closed_failure() -> napi::Error {
failure("This native session is closed. Create a new one with createNativeSession(input) before rendering again.")
}
fn session_device_lost_failure(detail: &str) -> napi::Error {
let reported = if detail.is_empty() { "no detail from the driver" } else { detail };
failure(format!(
"The GPU device this session was created on was lost ({reported}). The session cannot render any more: call close() and create a new one with createNativeSession(input)."
))
}
impl CyclesSession {
/// Validates the input, opens (or reuses) the device, uploads the scene tables and builds the acceleration structures.
pub(crate) fn create(input: &NativeTraceInputV2) -> Result<CyclesSession> {
let setup_started = Instant::now();
validate_cycles_input(input)?;
check_counts_match_kernel_params(input)?;
let context = get_cycles_device_context()?;
let pool_limit_bytes = u64::from(context.device.limits().max_storage_buffer_binding_size);
check_texture_pool_budget(input.texture_texels.len() as u64 * 4, pool_limit_bytes)?;
let scene_specialization = scan_scene_specialization(input);
let setup_seconds = setup_started.elapsed().as_secs_f64();
let upload_started = Instant::now();
let scene_tables = upload_cycles_scene_tables(&context.device, input);
let parameters = create_cycles_parameters(&context.device, &input.kernel_params);
let upload_seconds = upload_started.elapsed().as_secs_f64();
let build_started = Instant::now();
let acceleration = build_cycles_acceleration_structure(
&context.device,
&context.queue,
&input.instances,
input.instance_count as usize,
&input.triangles,
input.triangle_count as usize,
)?;
let acceleration_build_seconds = build_started.elapsed().as_secs_f64();
Ok(CyclesSession {
context,
session_kernel_params: input.kernel_params.to_vec(),
scene_specialization,
retained: RetainedTables::of_input(input),
light_tree_node_count: input.light_tree_node_count,
has_light_tree_tables: input.light_tree_emitters.is_some(),
creation_costs: Some(CreationCosts { setup_seconds, upload_seconds, acceleration_build_seconds }),
renders_completed: 0,
progressive: None,
film_holds_samples: false,
film_sample_count: 0,
gpu: Some(SessionGpuState {
scene_tables,
acceleration,
parameters,
pipeline: None,
film: None,
}),
})
}
pub(crate) fn device_context(&self) -> &CyclesDeviceContext {
&self.context
}
/// Frees the scene, the acceleration structures, the pipeline and the film. A closed session refuses to render.
pub(crate) fn close(&mut self) {
self.gpu = None;
}
fn fail_if_unusable(&self) -> Result<()> {
if self.gpu.is_none() {
return Err(session_closed_failure());
}
if self.context.device_lost.load(Ordering::SeqCst) {
let detail = self.context.device_error.lock().map(|stored| stored.clone()).unwrap_or_default();
return Err(session_device_lost_failure(&detail));
}
Ok(())
}
/// The kernel parameters of a frame: the ones it brings after checking they describe this scene, else the session's own.
fn frame_kernel_params(&self, requested: Option<&[u8]>) -> Result<Vec<u8>> {
let Some(requested_bytes) = requested else {
return Ok(self.session_kernel_params.clone());
};
validate_kernel_params_v2(requested_bytes)?;
check_frame_params_keep_scene_counts(&self.session_kernel_params, requested_bytes)?;
validate_light_tree_flag_has_tables(requested_bytes, self.light_tree_node_count, self.has_light_tree_tables)?;
Ok(requested_bytes.to_vec())
}
/// Renders one frame. The scene, the acceleration structures and (while the specialized kernel text and the image size
/// stay the same) the pipeline and the film are reused. A plain frame clears the film and starts from sample 0, as a
/// one-shot does. An accumulating call adds its samples to the film and continues the sample sequence (see `choose_film_use`).
pub(crate) fn render(&mut self, request: &CyclesRenderRequest<'_>) -> Result<CyclesRender> {
self.fail_if_unusable()?;
validate_render_extent(request.width, request.height, request.samples)?;
let frame_kernel_params = self.frame_kernel_params(request.kernel_params)?;
let film_use = choose_film_use(
self.progressive.as_ref(),
&FilmRequest {
width: request.width,
height: request.height,
samples: request.samples,
accumulate: request.accumulate,
target_samples: request.target_samples,
frame_kernel_params: &frame_kernel_params,
bootstrap_kernel: request.bootstrap_kernel,
},
)?;
let frame_index = self.renders_completed;
let creation_costs = self.creation_costs;
let acceleration_reused = creation_costs.is_none();
let context = &self.context;
let gpu = self.gpu.as_mut().ok_or_else(session_closed_failure)?;
let compile_started = Instant::now();
let pipeline_reused = ensure_pipeline(
context,
gpu,
&self.scene_specialization,
&frame_kernel_params,
request.bootstrap_kernel,
)?;
let compile_seconds = compile_started.elapsed().as_secs_f64();
let upload_started = Instant::now();
let film_reused = ensure_film(context, gpu, request.width, request.height)?;
let render_parameters =
patch_render_parameters(&frame_kernel_params, request.width, request.height, film_use.total_samples);
context.queue.write_buffer(&gpu.parameters, 0, &render_parameters);
if film_reused && film_use.starts_new_image {
clear_film(context, gpu.film()?);
}
let upload_seconds = upload_started.elapsed().as_secs_f64();
// From here the film changes: a call that fails leaves it unusable, so nothing may claim it holds an image.
self.progressive = None;
self.film_holds_samples = false;
let film = gpu.film()?;
let target = CyclesDispatchTarget {
device: &context.device,
queue: &context.queue,
pipeline: &gpu.pipeline()?.pipeline,
bind_group: &film.bind_group,
parameters: &gpu.parameters,
accumulation: &film.accumulation,
device_lost: &context.device_lost,
device_error: &context.device_error,
};
let plan = choose_dispatch_plan(request.samples, request.samples_per_dispatch, request.max_seconds);
let trace = trace_cycles_samples(
&target,
film_use.first_sample,
request.samples,
plan,
image_workgroups(request.width, request.height),
image_accumulation_bytes(request.width, request.height),
request.max_seconds,
)?;
self.renders_completed = frame_index + 1;
self.creation_costs = None;
self.film_holds_samples = true;
let film_after = film_use.film_after.as_ref();
let report = CyclesRenderReport {
setup_seconds: creation_costs.as_ref().map_or(0.0, |costs| costs.setup_seconds),
compile_seconds,
upload_seconds: upload_seconds + creation_costs.as_ref().map_or(0.0, |costs| costs.upload_seconds),
acceleration_build_seconds: creation_costs.as_ref().map_or(0.0, |costs| costs.acceleration_build_seconds),
pipeline_reused,
acceleration_reused,
film_reused,
frame_index,
first_sample: film_use.first_sample,
film_samples: film_after.map_or(request.samples, |film| film.samples_drawn),
target_samples: film_after.map(|film| film.target_samples),
};
self.film_sample_count = report.film_samples;
self.progressive = film_use.film_after;
Ok(CyclesRender { trace, report })
}
/// Starts the progressive image over: the film is cleared and the next accumulating call begins at sample 0, with a
/// `targetSamples` of its choosing. The scene, the pipeline and the film's memory stay.
pub(crate) fn reset(&mut self) -> Result<()> {
self.fail_if_unusable()?;
self.clear_progressive_film();
Ok(())
}
fn clear_progressive_film(&mut self) {
self.progressive = None;
self.film_holds_samples = false;
if let Some(film) = self.gpu.as_ref().and_then(|gpu| gpu.film.as_ref()) {
clear_film(&self.context, film);
}
}
/// The film as it stands, read back without tracing: the sums of every sample drawn since the image began.
pub(crate) fn read_film(&mut self) -> Result<CyclesFilmRead> {
self.fail_if_unusable()?;
let held_film = self.gpu.as_ref().and_then(|gpu| gpu.film.as_ref());
let film = match (held_film, self.film_holds_samples) {
(Some(film), true) => film,
_ => {
return Err(failure(
"The session film holds no samples to resolve: render first (with accumulate: true to build an image over several calls). reset() and update() clear the film.",
))
}
};
let sums = read_accumulation(
&self.context.device,
&self.context.queue,
&film.accumulation,
image_accumulation_bytes(film.width, film.height),
)?;
Ok(CyclesFilmRead {
sums,
width: film.width,
height: film.height,
film_samples: self.film_sample_count,
target_samples: self.progressive.as_ref().map(|held| held.target_samples),
frame_index: self.renders_completed,
})
}
/// Replaces the values of scene tables without rebuilding the pipeline or the BLAS. The tables keep their size and the
/// instances their meshes (see `plan_instance_update`); the TLAS is rebuilt only when a transform or a ray visibility
/// changed. The film is cleared, since the image it holds no longer shows the scene. Everything is checked before
/// anything on the card changes, so a refused update leaves the session as it was.
pub(crate) fn update(&mut self, update: &CyclesSceneUpdate<'_>) -> Result<CyclesUpdateReport> {
self.fail_if_unusable()?;
let update_started = Instant::now();
validate_kernel_params_v2(update.kernel_params)?;
check_update_params_keep_scene_shape(&self.session_kernel_params, update.kernel_params)?;
validate_light_tree_flag_has_tables(update.kernel_params, self.light_tree_node_count, self.has_light_tree_tables)?;
for (table, bytes) in &update.tables {
let held_length = self.retained.table_lengths[table.buffer_index()];
if bytes.len() != held_length {
return Err(failure(format!(
"The new {} table holds {} bytes but the session holds {held_length}. An update keeps the record counts; create a new session for this input.",
table.input_name(),
bytes.len()
)));
}
}
let new_instances =
update.tables.iter().find(|(table, _)| *table == UpdatableTable::Instances).map(|(_, bytes)| *bytes);
let instance_plan = match new_instances {
Some(bytes) => Some(plan_instance_update(&self.retained.instances, bytes)?),
None => None,
};
// An empty acceleration (no triangles) holds a dummy TLAS that no ray reaches, so there is nothing to rebuild.
let held_instance_count = self.gpu.as_ref().ok_or_else(session_closed_failure)?.acceleration.instance_blas_indices.len();
let acceleration_rebuilt = held_instance_count > 0 && instance_plan.as_ref().is_some_and(|plan| plan.tlas_dirty);
if let (true, Some(bytes)) = (acceleration_rebuilt, new_instances) {
if bytes.len() != held_instance_count * INSTANCE_RECORD_BYTES {
return Err(failure(format!(
"The new instances table holds {} bytes but the acceleration structure holds {held_instance_count} instances ({} bytes). Create a new session for this input.",
bytes.len(),
held_instance_count * INSTANCE_RECORD_BYTES
)));
}
}
// Past this point the session changes. A step that still fails (a driver or device error) cannot be undone, so the
// film is cleared and the session closed rather than left half updated.
let applied = self.apply_tables(update, new_instances, acceleration_rebuilt);
let (upload_seconds, acceleration_rebuild_seconds) = match applied {
Ok(seconds) => seconds,
Err(error) => {
self.clear_progressive_film();
self.gpu = None;
return Err(failure(format!(
"The update failed part way ({error}) and the session was closed so it cannot render a half updated scene. Create a new session with createNativeSession(input)."
)));
}
};
self.session_kernel_params = update.kernel_params.to_vec();
let respecialized = self.retained.specialization();
let kernel_respecialized = respecialized != self.scene_specialization;
self.scene_specialization = respecialized;
self.clear_progressive_film();
Ok(CyclesUpdateReport {
uploaded_tables: update.tables.iter().map(|(table, _)| table.input_name()).collect(),
acceleration_rebuilt,
changed_instances: instance_plan.map_or(0, |plan| plan.changed_instances as u32),
kernel_respecialized,
upload_seconds,
acceleration_rebuild_seconds,
update_seconds: update_started.elapsed().as_secs_f64(),
})
}
}
impl CyclesSession {
/// Uploads the new tables, rebuilds the TLAS when asked and rebinds the film; returns the seconds spent uploading and rebuilding.
fn apply_tables(
&mut self,
update: &CyclesSceneUpdate<'_>,
new_instances: Option<&[u8]>,
acceleration_rebuilt: bool,
) -> Result<(f64, f64)> {
let upload_started = Instant::now();
let context = &self.context;
let gpu = self.gpu.as_mut().ok_or_else(session_closed_failure)?;
for (table, bytes) in &update.tables {
let label = format!("cycles {} (updated)", table.input_name());
gpu.scene_tables[table.buffer_index()] = storage_buffer(&context.device, &label, bytes);
self.retained.keep_table(*table, bytes);
}
let upload_seconds = upload_started.elapsed().as_secs_f64();
let rebuild_started = Instant::now();
if let (true, Some(bytes)) = (acceleration_rebuilt, new_instances) {
rebuild_cycles_tlas(&context.device, &context.queue, &mut gpu.acceleration, bytes)?;
}
let acceleration_rebuild_seconds = rebuild_started.elapsed().as_secs_f64();
if !update.tables.is_empty() {
rebind_film(context, gpu)?;
}
Ok((upload_seconds, acceleration_rebuild_seconds))
}
}
/// The film of a session read back without tracing.
pub(crate) struct CyclesFilmRead {
pub(crate) sums: Vec<f32>,
pub(crate) width: u32,
pub(crate) height: u32,
/// The samples per pixel the film holds.
pub(crate) film_samples: u32,
pub(crate) target_samples: Option<u32>,
pub(crate) frame_index: u32,
}
/// Makes `gpu.pipeline` the pipeline for this frame's specialized kernel text; true when it already was.
fn ensure_pipeline(
context: &CyclesDeviceContext,
gpu: &mut SessionGpuState,
scene: &SceneSpecialization,
frame_kernel_params: &[u8],
bootstrap_kernel: bool,
) -> Result<bool> {
let assembled_source = assemble_cycles_kernel_entry("main", bootstrap_kernel)?;
let entry_point = trace_entry_point_for_params(frame_kernel_params);
let specialized_source = specialize_kernel_source(&assembled_source, scene, frame_kernel_params);
let key = pipeline_key(entry_point, &specialized_source);
if gpu.pipeline.as_ref().is_some_and(|held| held.key == key) {
return Ok(true);
}
let pipeline = get_or_compile_cycles_pipeline_on(Some(&context.device_lost), entry_point, specialized_source)?;
gpu.pipeline = Some(HeldPipeline { key, pipeline });
Ok(false)
}
/// Makes `gpu.film` a film of this size with a bind group over it; true when the previous frame's film was kept.
fn ensure_film(context: &CyclesDeviceContext, gpu: &mut SessionGpuState, width: u32, height: u32) -> Result<bool> {
if gpu.film.as_ref().is_some_and(|film| film.width == width && film.height == height) {
return Ok(true);
}
let accumulation = create_cycles_film(&context.device, image_accumulation_bytes(width, height));
let bind_group = with_cycles_cache_on(Some(&context.device_lost), |device, _queue, layout, lut| {
create_cycles_bind_group(
device,
layout,
&gpu.parameters,
&gpu.acceleration.tlas,
&gpu.scene_tables,
&accumulation,
lut,
)
})?;
gpu.film = Some(SessionFilm { width, height, accumulation, bind_group });
Ok(false)
}
/// Builds a new bind group over the current scene buffers and the film that exists, after an update replaced buffers.
fn rebind_film(context: &CyclesDeviceContext, gpu: &mut SessionGpuState) -> Result<()> {
let Some(film) = gpu.film.as_ref() else {
return Ok(());
};
let bind_group = with_cycles_cache_on(Some(&context.device_lost), |device, _queue, layout, lut| {
create_cycles_bind_group(
device,
layout,
&gpu.parameters,
&gpu.acceleration.tlas,
&gpu.scene_tables,
&film.accumulation,
lut,
)
})?;
if let Some(film) = gpu.film.as_mut() {
film.bind_group = bind_group;
}
Ok(())
}
fn clear_film(context: &CyclesDeviceContext, film: &SessionFilm) {
let mut encoder = context.device.create_command_encoder(&wgpu::CommandEncoderDescriptor {
label: Some("cycles film clear"),
});
encoder.clear_buffer(&film.accumulation, 0, None);
context.queue.submit(Some(encoder.finish()));
}
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn render_parameters_carry_the_image_size_and_the_sample_count_and_nothing_else() {
let mut frame = vec![0xABu8; 320];
frame[0..4].copy_from_slice(&0x36375054u32.to_le_bytes());
let patched = patch_render_parameters(&frame, 1920, 1080, 64);
assert_eq!(patched.len(), 320);
assert_eq!(&patched[8..12], &1920u32.to_le_bytes());
assert_eq!(&patched[12..16], &1080u32.to_le_bytes());
assert_eq!(&patched[24..28], &64u32.to_le_bytes());
let untouched = |index: &usize| !(8..16).contains(index) && !(24..28).contains(index);
assert!((0..320).filter(untouched).all(|index| patched[index] == frame[index]));
}
#[test]
fn a_fixed_batch_is_kept_and_never_zero() {
assert!(matches!(choose_dispatch_plan(64, Some(8), None), DispatchPlan::Fixed(8)));
assert!(matches!(choose_dispatch_plan(64, Some(0), None), DispatchPlan::Fixed(1)));
assert!(matches!(choose_dispatch_plan(64, Some(16), Some(0.5)), DispatchPlan::Fixed(16)));
}
#[test]
fn a_tight_time_limit_draws_one_sample_per_dispatch() {
assert!(matches!(choose_dispatch_plan(64, None, Some(1.5)), DispatchPlan::Fixed(1)));
assert!(matches!(choose_dispatch_plan(64, None, Some(2.0)), DispatchPlan::TimeBudget { largest_batch: 64 }));
}
#[test]
fn without_a_batch_or_limit_the_dispatches_are_sized_by_time() {
assert!(matches!(choose_dispatch_plan(256, None, None), DispatchPlan::TimeBudget { largest_batch: 256 }));
assert!(matches!(choose_dispatch_plan(0, None, None), DispatchPlan::TimeBudget { largest_batch: 1 }));
}
/// One opaque material record with no texture on any slot (a texture index of -1 means none) and the given transmission.
fn plain_material(transmission_weight: f32) -> Vec<u8> {
let mut material = vec![0u8; 256];
material[52..56].copy_from_slice(&transmission_weight.to_le_bytes());
for texture_slot_byte in [212usize, 216, 224, 228, 236, 240, 244, 248, 252] {
material[texture_slot_byte..texture_slot_byte + 4].copy_from_slice(&(-1i32).to_le_bytes());
}
material
}
fn scan_test_input(transmission_weight: f32, light_group_mask_lo: u32) -> NativeTraceInputV2 {
let materials = plain_material(transmission_weight);
let mut lights = vec![0u8; 128];
lights[12..16].copy_from_slice(&2u32.to_le_bytes());
lights[120..124].copy_from_slice(&light_group_mask_lo.to_le_bytes());
lights[124..128].copy_from_slice(&0xFFFF_FFFFu32.to_le_bytes());
NativeTraceInputV2 {
schema_version: 2,
kernel_params: Uint8Array::new(vec![0u8; 320]),
instances: Uint8Array::new(vec![0u8; 160]),
instance_count: 1,
triangles: Uint8Array::new(vec![0u8; 224]),
triangle_count: 1,
materials: Uint8Array::new(materials),
material_count: 1,
emissive_triangles: Uint8Array::new(vec![0u8; 96]),
emissive_triangle_count: 0,
lights: Uint8Array::new(lights),
light_count: 1,
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 the_retained_tables_specialize_the_kernel_like_the_whole_input() {
for (transmission_weight, light_group_mask_lo) in [(0.0, 0xFFFF_FFFF), (0.7, 0xFFFF_FFFF), (0.0, 0x0F)] {
let input = scan_test_input(transmission_weight, light_group_mask_lo);
let retained = RetainedTables::of_input(&input);
assert_eq!(retained.specialization(), scan_scene_specialization(&input));
}
let glass = RetainedTables::of_input(&scan_test_input(0.7, 0xFFFF_FFFF));
let clear = RetainedTables::of_input(&scan_test_input(0.0, 0xFFFF_FFFF));
assert_ne!(glass.specialization(), clear.specialization(), "a transmissive material changes the specialization");
}
#[test]
fn keeping_an_updated_table_changes_what_the_specialization_reads() {
let mut retained = RetainedTables::of_input(&scan_test_input(0.0, 0xFFFF_FFFF));
let before = retained.specialization();
retained.keep_table(UpdatableTable::Materials, &plain_material(0.7));
assert_ne!(retained.specialization(), before);
assert_eq!(retained.table_lengths[UpdatableTable::Materials.buffer_index()], 256);
assert_eq!(retained.table_lengths[UpdatableTable::Lights.buffer_index()], 128);
}
#[test]
fn a_closed_session_error_says_how_to_continue() {
let message = session_closed_failure().to_string();
assert!(message.contains("closed"), "{message}");
assert!(message.contains("createNativeSession"), "{message}");
}
#[test]
fn a_lost_device_error_names_the_driver_report_and_the_way_out() {
let with_detail = session_device_lost_failure("Unknown: TDR").to_string();
assert!(with_detail.contains("TDR"), "{with_detail}");
assert!(with_detail.contains("createNativeSession"), "{with_detail}");
let without_detail = session_device_lost_failure("").to_string();
assert!(without_detail.contains("no detail from the driver"), "{without_detail}");
}
}