Skip to content

SolidCraft: an open-source parametric 3D CAD application built in pure Rust. Desktop, web, and automation through MCP.

72.8 KB
Raw Blame
//! Native progressive product rendering. Software BVH traversal needs no ray-query
//! features. Small measured quanta adapt to the device, then check cancellation.
use solidcore_record::Vec3;
use solidcraft_geom::Vec3Geom;
#[cfg(test)]
use solidcraft_render::job::ToneMap;
use solidcraft_render::{
    Availability, ExecutorDescriptor, ExecutorId, ProductScene, RenderFeature, RenderFormat, RenderMode, RenderOperation, RenderProfile,
    ScratchLayout,
    job::{
        Admission, CancelToken, ErrorCode, GPU_PATH_LIMITS, ImageExecutor, ImageHost, ImageRequest, ImageWork, JobError, JobOptions,
        MAX_GPU_PATH_BODIES, MAX_GPU_PATH_TRIANGLES, Phase, PngTask, Progress, Result, TaskPoll, admit_geometry_with_limits,
    },
};
use std::{
    sync::{
        Arc,
        atomic::{AtomicBool, Ordering},
    },
    time::{Duration, Instant},
};
use wgpu::util::DeviceExt;

mod adaptive;
mod denoise;
mod dispatch;
mod media_hierarchy;
mod photons;
mod scene;
#[cfg(test)]
mod tests;
mod textures;
// Opaque producers specialize away dielectric traversal and use a single
// unused medium slot. Optical producers share the sixteen-medium shader.
macro_rules! path_shader {
    ($capacity:literal) => {
        concat!(
            "const MEDIUM_CAPACITY: u32 = ",
            $capacity,
            "u;\n",
            include_str!("path.wgsl"),
            "\n",
            include_str!("shadows.wgsl"),
            "\n",
            include_str!("textures.wgsl"),
            "\n",
            include_str!("volume.wgsl"),
            "\n",
            include_str!("aging.wgsl"),
            "\n",
            include_str!("punctual.wgsl"),
            "\n",
            include_str!("glass.wgsl"),
            "\n",
            include_str!("glass_lighting.wgsl"),
            "\n",
            include_str!("photons_disabled.wgsl")
        )
    };
}
const SHADER: &str = path_shader!(16);
const SINGLE_MEDIUM_SHADER: &str = path_shader!(1);
const MAX_TRIANGLES: u64 = MAX_GPU_PATH_TRIANGLES;
const PATH_WORKGROUP_SIZE: u32 = 32;
const SCENE_PIPELINE_CACHE_SLOTS: usize = 5;
const PARAMETER_BYTES: usize = 2080;
// Five vec4s per source; exact device+upload growth is additional to v2's budget.
const PUNCTUAL_PARAMETER_BYTES: u64 = 8 * 80;
// Eight inline 32-byte hard directions: device uniform plus host upload bytes.
const DIRECTIONAL_PARAMETER_BYTES: u64 = 8 * 32;
// Eight u32 words: count low, pixel, bounce, sample, code, count high, first-writer flag, spare.
const FAILURE_BYTES: u64 = 56;
// Original medium words0..7 remain unchanged; three low/high punctual counters
// occupy words8..13. Both device storage and complete-pass readback are prepaid.
const PUNCTUAL_COUNTER_BYTES: u64 = 24;
// A path that cannot classify its glass medium ends there. Isolated paths at the
// limits of f32 geometry are tolerated and logged; more than this fraction of all
// paths (any systematic error such as an ambiguous boundary origin) fails the job.
const FAILURE_FRACTION: f64 = 1e-6;
const TIMEOUT: Duration = Duration::from_secs(30);
// Software Vulkan drivers can compile a pipeline at its first dispatch, which on a cold
// shader cache exceeds the per-dispatch hang timeout. Setup dispatches once with no work
// and allows this longer wait, so jobs keep the short one.
const SETUP_TIMEOUT: Duration = Duration::from_secs(600);

fn gpu(e: impl std::fmt::Display) -> JobError {
    JobError::new(ErrorCode::HostUnavailable, e.to_string())
}

fn scopes(device: &wgpu::Device) -> [wgpu::ErrorScopeGuard; 3] {
    [wgpu::ErrorFilter::Validation, wgpu::ErrorFilter::OutOfMemory, wgpu::ErrorFilter::Internal].map(|f| device.push_error_scope(f))
}
fn checked(scopes: [wgpu::ErrorScopeGuard; 3]) -> Result<()> {
    let mut error = None;
    for scope in scopes.into_iter().rev() {
        if let Some(e) = pollster::block_on(scope.pop()) {
            error = Some(e);
        }
    }
    error.map_or(Ok(()), |e| Err(gpu(e)))
}

/// Drain every scope, in reverse order, even when resource creation returns an error.
/// The ordinary cancellation/error path must not drop an array of guards forwards.
fn checked_creation<T>(device: &wgpu::Device, create: impl FnOnce() -> Result<T>) -> Result<T> {
    let error_scopes = scopes(device);
    let result = create();
    checked(error_scopes)?;
    result
}

/// Open and validate a native device before advertising the executor. Failure leaves the
/// caller's CPU host usable. Respects SOLIDCRAFT_GPU, including the software adapter policy.
pub fn host() -> Result<ImageHost> {
    let (adapter, device, queue) = open_headless()?;
    log::info!("gpu-path adapter: {} ({:?})", adapter.get_info().name, adapter.get_info().device_type);
    ImageHost::with_executor(Arc::new(Executor::new(device, queue)?))
}

/// Open an independent job device on the viewport's selected adapter. In particular,
/// software fallback and safe mode must not rediscover a failing hardware driver.
/// An explicit incompatible SOLIDCRAFT_GPU policy leaves this executor unavailable.
/// The path tracer runs on Vulkan, or Metal on macOS. On Windows it must keep the viewport's
/// backend: opening Vulkan drivers that startup avoided can crash inside native driver code.
/// Elsewhere a viewport on another backend is reopened on the same GPU through one of them.
/// Without a usable adapter the executor is unavailable; CPU image methods remain usable.
pub fn host_on_adapter(adapter: &wgpu::Adapter) -> Result<ImageHost> {
    let policy = crate::select::Policy::from_env().map_err(gpu)?;
    let info = adapter.get_info();
    if !viewport_path_backends(info.backend, cfg!(target_os = "windows")).intersects(crate::select::path_backends()) {
        return Err(gpu(format!("{VULKAN_ONLY}; the viewport uses {:?}", info.backend)));
    }
    if !policy.admits(crate::select::tier_of(info.device_type)) {
        return Err(gpu(format!("viewport adapter does not satisfy SOLIDCRAFT_GPU={}", policy.name())));
    }
    if !matches!(info.backend, wgpu::Backend::Vulkan | wgpu::Backend::Metal) {
        let (picked, _) = crate::select::pick_path(policy, |i| i.vendor == info.vendor && i.device == info.device)
            .ok_or_else(|| gpu(format!("{VULKAN_ONLY}; the viewport uses {:?}", info.backend)))?;
        let (device, queue) = open_device(&picked)?;
        log::info!("gpu-path viewport GPU: {} through Vulkan or Metal", info.name);
        return ImageHost::with_executor(Arc::new(Executor::new(device, queue)?));
    }
    let (device, queue) = open_device(adapter)?;
    log::info!("gpu-path viewport adapter: {} ({:?})", info.name, info.device_type);
    ImageHost::with_executor(Arc::new(Executor::new(device, queue)?))
}

// D3D12 shader compilation is avoided; the user can select a CPU image method instead.
const VULKAN_ONLY: &str = "the GPU path tracer requires a Vulkan driver (Metal on macOS); select a CPU image method when none is available";

/// Backends a viewport's path device may open, before any driver is loaded.
fn viewport_path_backends(backend: wgpu::Backend, windows: bool) -> wgpu::Backends {
    if windows { wgpu::Backends::from(backend) } else { crate::select::path_backends() }
}

// Path resources need six storage buffers (geometry, BVH, accumulation, HDRI,
// textures, medium-failure counts). Request that limit only on this independent path device: raster and
// tessellation keep their existing four-buffer downlevel requirement.
const PATH_STORAGE_BUFFERS: u32 = 6;
fn device_limits(supported: wgpu::Limits) -> Result<wgpu::Limits> {
    if supported.max_storage_buffers_per_shader_stage < PATH_STORAGE_BUFFERS {
        return Err(gpu("gpu-path requires six storage buffers per shader stage"));
    }
    // Query first: never request unsupported storage or buffer sizes. The old
    // downlevel defaults unnecessarily capped large CAD geometry at 128 MiB.
    let storage = supported.max_storage_buffer_binding_size.min(1024 * 1024 * 1024);
    let buffer = supported.max_buffer_size.min(1024 * 1024 * 1024);
    let optional_photon_buffers = supported.max_storage_buffers_per_shader_stage.min(7);
    let mut limits = wgpu::Limits::downlevel_defaults().using_resolution(supported);
    limits.max_storage_buffer_binding_size = storage.min(buffer);
    limits.max_buffer_size = buffer;
    limits.max_storage_buffers_per_shader_stage = optional_photon_buffers;
    Ok(limits)
}
fn open_device(adapter: &wgpu::Adapter) -> Result<(wgpu::Device, wgpu::Queue)> {
    let required_limits = device_limits(adapter.limits())?;
    pollster::block_on(adapter.request_device(&wgpu::DeviceDescriptor {
        label: Some("solidcraft progressive path"),
        required_features: crate::depth_features(adapter),
        required_limits,
        ..Default::default()
    }))
    .map_err(gpu)
}
fn open_headless() -> Result<(wgpu::Adapter, wgpu::Device, wgpu::Queue)> {
    let policy = crate::select::Policy::from_env().map_err(gpu)?;
    let (adapter, _) = crate::select::pick_path(policy, |_| true)
        .ok_or_else(|| gpu(format!("{VULKAN_ONLY}; no Vulkan or Metal adapter satisfies SOLIDCRAFT_GPU={}", policy.name())))?;
    let (device, queue) = open_device(&adapter)?;
    Ok((adapter, device, queue))
}

struct Context {
    healthy: Arc<AtomicBool>,
    device: wgpu::Device,
    queue: wgpu::Queue,
    pipeline: wgpu::ComputePipeline,
    // Plain opaque and non-nested glass are ready before the host is published.
    // The four map/nested variants are prepared lazily in the remaining slots.
    scene_pipelines: [std::sync::OnceLock<wgpu::ComputePipeline>; SCENE_PIPELINE_CACHE_SLOTS],
    // Built and warmed by the first denoised job, then shared by later ones.
    denoise: std::sync::OnceLock<denoise::Pipelines>,
    // Only authored caustics compile/retain the seven-storage-buffer variant.
    photons: std::sync::OnceLock<photons::Pipelines>,
    // Optical hard-light connections are specialized away in the legacy program.
    glass: std::sync::OnceLock<GlassPipelines>,
    photon_glass: std::sync::OnceLock<GlassPipelines>,
    layout: wgpu::BindGroupLayout,
}
impl Context {
    fn ensure_available(&self) -> Result<()> {
        if self.healthy.load(Ordering::Acquire) {
            Ok(())
        } else {
            Err(JobError::new(
                ErrorCode::HostUnavailable,
                "GPU path device was lost or failed to complete work; restart the renderer before retrying",
            ))
        }
    }
    fn wait(&self, submission: wgpu::SubmissionIndex, timeout: Duration) -> Result<()> {
        wait_device(&self.device, &self.healthy, submission, timeout)
    }
    #[cfg(test)]
    fn prepared_scene_pipeline(&self, opaque: bool, maps: bool, nested: bool) -> Result<&wgpu::ComputePipeline> {
        let Some(index) = scene_pipeline_variant(opaque, maps, nested) else { return Ok(&self.pipeline) };
        self.scene_pipelines.get(index).and_then(std::sync::OnceLock::get).ok_or_else(|| gpu("captured scene has no prepared pipeline"))
    }
    fn prepare_scene_pipeline(&self, opaque: bool, maps: bool, nested: bool) -> Result<&wgpu::ComputePipeline> {
        self.ensure_available()?;
        let Some(index) = scene_pipeline_variant(opaque, maps, nested) else { return Ok(&self.pipeline) };
        let slot = self.scene_pipelines.get(index).ok_or_else(|| gpu("scene pipeline variant exceeds its finite cache"))?;
        if let Some(pipeline) = slot.get() {
            return Ok(pipeline);
        }
        let _compiling = one_compile_at_a_time();
        if let Some(pipeline) = slot.get() {
            return Ok(pipeline);
        }
        let scopes = scopes(&self.device);
        let shader = self.device.create_shader_module(wgpu::ShaderModuleDescriptor {
            label: Some("gpu-path captured scene"),
            source: wgpu::ShaderSource::Wgsl(scene_shader(opaque).into()),
        });
        let layout = self.device.create_pipeline_layout(&wgpu::PipelineLayoutDescriptor {
            label: Some("gpu-path captured scene"),
            bind_group_layouts: &[Some(&self.layout)],
            immediate_size: 0,
        });
        let pipeline = self.device.create_compute_pipeline(&wgpu::ComputePipelineDescriptor {
            label: Some("gpu-path captured scene"),
            layout: Some(&layout),
            module: &shader,
            entry_point: Some("main"),
            compilation_options: wgpu::PipelineCompilationOptions {
                constants: &[("OPAQUE_SCENE", f64::from(u8::from(opaque))), ("HAS_TEXTURES", f64::from(u8::from(maps)))],
                ..Default::default()
            },
            cache: None,
        });
        checked(scopes)?;
        warm_up(&self.device, &self.queue, &pipeline, &placeholder_bind(&self.device, &self.layout, 7)?, &self.healthy)?;
        let _ = slot.set(pipeline);
        slot.get().ok_or_else(|| gpu("scene pipeline publication failed"))
    }
}

fn wait_device(device: &wgpu::Device, healthy: &AtomicBool, submission: wgpu::SubmissionIndex, timeout: Duration) -> Result<()> {
    if !healthy.load(Ordering::Acquire) {
        return Err(JobError::new(ErrorCode::HostUnavailable, "GPU path device is unavailable"));
    }
    if let Err(error) = device.poll(wgpu::PollType::Wait { submission_index: Some(submission), timeout: Some(timeout) }) {
        healthy.store(false, Ordering::Release);
        return Err(JobError::new(ErrorCode::HostUnavailable, format!("GPU path completion failed; executor retired: {error}")));
    }
    if !healthy.load(Ordering::Acquire) {
        return Err(JobError::new(ErrorCode::HostUnavailable, "GPU path device was lost while completing work"));
    }
    Ok(())
}

struct Executor {
    context: Arc<Context>,
}
impl Executor {
    fn new(device: wgpu::Device, queue: wgpu::Queue) -> Result<Self> {
        device_limits(device.limits())?;
        let healthy = Arc::new(AtomicBool::new(true));
        let uncaptured = healthy.clone();
        device.on_uncaptured_error(Arc::new(move |e: wgpu::Error| {
            uncaptured.store(false, Ordering::Release);
            log::error!("gpu-path executor retired after uncaptured error: {e}");
        }));
        let lost = healthy.clone();
        device.set_device_lost_callback(move |reason, message| {
            lost.store(false, Ordering::Release);
            log::warn!("gpu-path device lost ({reason:?}); executor unavailable: {message}");
        });
        let compiling = one_compile_at_a_time();
        let scopes = scopes(&device);
        let shader = device.create_shader_module(wgpu::ShaderModuleDescriptor {
            label: Some("gpu-path"),
            source: wgpu::ShaderSource::Wgsl(scene_shader(true).into()),
        });
        let entries: Vec<_> = (0..7)
            .map(|binding| wgpu::BindGroupLayoutEntry {
                binding,
                visibility: wgpu::ShaderStages::COMPUTE,
                ty: wgpu::BindingType::Buffer {
                    ty: if binding == 0 {
                        wgpu::BufferBindingType::Uniform
                    } else {
                        wgpu::BufferBindingType::Storage { read_only: binding != 3 && binding != 6 }
                    },
                    has_dynamic_offset: false,
                    min_binding_size: None,
                },
                count: None,
            })
            .collect();
        let layout = device.create_bind_group_layout(&wgpu::BindGroupLayoutDescriptor { label: Some("gpu-path"), entries: &entries });
        let pipeline_layout = device.create_pipeline_layout(&wgpu::PipelineLayoutDescriptor {
            label: Some("gpu-path"),
            bind_group_layouts: &[Some(&layout)],
            immediate_size: 0,
        });
        let pipeline = device.create_compute_pipeline(&wgpu::ComputePipelineDescriptor {
            label: Some("gpu-path"),
            layout: Some(&pipeline_layout),
            module: &shader,
            entry_point: Some("main"),
            compilation_options: wgpu::PipelineCompilationOptions { constants: &[("OPAQUE_SCENE", 1.0)], ..Default::default() },
            cache: None,
        });
        checked(scopes)?;
        drop(compiling);
        warm_up(&device, &queue, &pipeline, &placeholder_bind(&device, &layout, 7)?, &healthy)?;
        let context = Arc::new(Context {
            healthy,
            device,
            queue,
            pipeline,
            layout,
            denoise: std::sync::OnceLock::new(),
            photons: std::sync::OnceLock::new(),
            glass: std::sync::OnceLock::new(),
            photon_glass: std::sync::OnceLock::new(),
            scene_pipelines: std::array::from_fn(|_| std::sync::OnceLock::new()),
        });
        // The original host prepared glass before advertising readiness. Keep the
        // common no-map/non-nested program out of the first image job's work.
        context.prepare_scene_pipeline(false, false, false)?;
        Ok(Self { context })
    }
}

fn needs_glass_lighting(scene: &ProductScene) -> bool {
    let active = |transmission: Option<solidcraft_render::transmission::Transmission>| {
        transmission.is_some_and(|material| {
            material.model().is_some_and(|model| model.roughness > 0.0) || material.subsurface().is_some_and(|medium| medium.active())
        })
    };
    scene.meshes.iter().any(|body| active(body.transmission) || body.faces.iter().any(|face| active(face.transmission)))
}

#[derive(Clone)]
struct GlassPipelines {
    camera: wgpu::ComputePipeline,
    resolve: wgpu::ComputePipeline,
}

// One request and camera value per path in the largest admitted tile, reusing
// the accumulation binding. No extra image plane or storage binding is needed.
fn glass_tile_bytes(scene: &ProductScene, request: &ImageRequest) -> u64 {
    if needs_glass_lighting(scene) { (u64::from(request.width) * u64::from(request.height)).min(u64::from(dispatch::MAX_PATHS)) * 128 } else { 0 }
}

fn glass_pipeline(context: &Context, layout: &wgpu::BindGroupLayout, caustics: bool, cancel: &CancelToken) -> Result<GlassPipelines> {
    cancel.check()?;
    let slot = if caustics { &context.photon_glass } else { &context.glass };
    if let Some(pipeline) = slot.get() {
        return Ok(pipeline.clone());
    }
    let source = if caustics { std::borrow::Cow::Owned(photons::shader_source()?) } else { std::borrow::Cow::Borrowed(SHADER) };
    let compiling = one_compile_at_a_time();
    cancel.check()?;
    let device = &context.device;
    let scopes = scopes(device);
    let module = device
        .create_shader_module(wgpu::ShaderModuleDescriptor { label: Some("gpu-path optical hard lights"), source: wgpu::ShaderSource::Wgsl(source) });
    let pipeline_layout = device.create_pipeline_layout(&wgpu::PipelineLayoutDescriptor {
        label: Some("gpu-path optical hard lights"),
        bind_group_layouts: &[Some(layout)],
        immediate_size: 0,
    });
    let constants = [("GLASS_DELTA_LIGHTS", 1.0), ("OPAQUE_SCENE", 0.0), ("HAS_TEXTURES", 1.0)];
    let pipeline = |entry| {
        device.create_compute_pipeline(&wgpu::ComputePipelineDescriptor {
            label: Some("gpu-path optical hard lights"),
            layout: Some(&pipeline_layout),
            module: &module,
            entry_point: Some(entry),
            compilation_options: wgpu::PipelineCompilationOptions { constants: &constants, ..Default::default() },
            cache: None,
        })
    };
    let camera = pipeline("main");
    checked(scopes)?;
    cancel.check()?;
    let resolve = checked_creation(device, || Ok(pipeline("optical_resolve")))?;
    let pipelines = GlassPipelines { camera, resolve };
    cancel.check()?;
    drop(compiling);
    let placeholder = placeholder_bind(device, layout, if caustics { 8 } else { 7 })?;
    warm_up(device, &context.queue, &pipelines.camera, &placeholder, &context.healthy)?;
    cancel.check()?;
    warm_up(device, &context.queue, &pipelines.resolve, &placeholder, &context.healthy)?;
    cancel.check()?;
    Ok(slot.get_or_init(|| pipelines).clone())
}

/// Native drivers compile the path pipeline for minutes and gigabytes on a cold shader cache.
/// Executors opened side by side (parallel tests, each on its own device) compiled it together
/// until memory ran out (#6706). One compile at a time per process: the first fills the driver's
/// cache, and the waiting ones then get it from there.
fn one_compile_at_a_time() -> std::sync::MutexGuard<'static, ()> {
    static COMPILE: std::sync::Mutex<()> = std::sync::Mutex::new(());
    COMPILE.lock().unwrap_or_else(std::sync::PoisonError::into_inner)
}

// Small zeroed bindings: binding 0 is a uniform whose zero work count makes every
// invocation return at once; the others are storage buffers.
fn placeholder_bind(device: &wgpu::Device, layout: &wgpu::BindGroupLayout, count: u32) -> Result<wgpu::BindGroup> {
    let scopes = scopes(device);
    let buffers: Vec<_> = (0..count)
        .map(|binding| {
            device.create_buffer(&wgpu::BufferDescriptor {
                label: Some("gpu-path warm-up"),
                size: if binding == 0 { PARAMETER_BYTES as u64 } else { 256 },
                usage: if binding == 0 { wgpu::BufferUsages::UNIFORM } else { wgpu::BufferUsages::STORAGE },
                mapped_at_creation: false,
            })
        })
        .collect();
    let entries: Vec<_> = buffers
        .iter()
        .enumerate()
        .map(|(binding, buffer)| wgpu::BindGroupEntry { binding: binding as u32, resource: buffer.as_entire_binding() })
        .collect();
    let bind = device.create_bind_group(&wgpu::BindGroupDescriptor { label: Some("gpu-path warm-up"), layout, entries: &entries });
    checked(scopes)?;
    Ok(bind)
}

fn warm_up(device: &wgpu::Device, queue: &wgpu::Queue, pipeline: &wgpu::ComputePipeline, bind: &wgpu::BindGroup, healthy: &AtomicBool) -> Result<()> {
    let scopes = scopes(device);
    let mut encoder = device.create_command_encoder(&wgpu::CommandEncoderDescriptor { label: Some("gpu-path warm-up") });
    {
        let mut pass = encoder.begin_compute_pass(&wgpu::ComputePassDescriptor { label: Some("gpu-path warm-up"), timestamp_writes: None });
        pass.set_pipeline(pipeline);
        pass.set_bind_group(0, bind, &[]);
        pass.dispatch_workgroups(1, 1, 1);
    }
    let submission = queue.submit([encoder.finish()]);
    checked(scopes)?;
    wait_device(device, healthy, submission, SETUP_TIMEOUT)?;
    Ok(())
}

fn medium_failures_tolerated(failed: u64, paths: u64) -> bool {
    failed as f64 <= paths as f64 * FAILURE_FRACTION
}

fn descriptor() -> Result<ExecutorDescriptor> {
    Ok(ExecutorDescriptor {
        id: ExecutorId::new("gpu-path").map_err(gpu)?,
        availability: Availability::Available,
        profiles: vec![RenderProfile {
            mode: RenderMode::Preview,
            operation: RenderOperation::Image,
            formats: vec![RenderFormat::Png],
            features: vec![RenderFeature::Pbr, RenderFeature::Progressive, RenderFeature::Refraction, RenderFeature::Hdri],
        }],
        limits: GPU_PATH_LIMITS,
        scratch: ScratchLayout { sample_scale: 1, sample_bytes_per_pixel: 16, output_bytes_per_pixel: 16, encoding_bytes_per_pixel: 16 },
    })
}

// RADV failed to cover mapped thin-glass pixels with the combined one-medium
// producer. Keep the qualified full stack for optical transport. The nested
// media option still controls admission and the actual boundary transitions.
fn scene_shader(opaque: bool) -> &'static str {
    if opaque { SINGLE_MEDIUM_SHADER } else { SHADER }
}

fn scene_pipeline_variant(opaque: bool, maps: bool, nested: bool) -> Option<usize> {
    if opaque { maps.then_some(0) } else { Some(1 + 2 * usize::from(maps) + usize::from(nested)) }
}

fn use_opaque_pipeline(scene: &ProductScene, options: JobOptions) -> bool {
    !scene.has_transmission()
        && !options.volume.is_some_and(|volume| volume.active())
        && scene.meshes.iter().all(|body| body.opacity == 1.0 && body.faces.iter().all(|face| face.opacity == 1.0))
}

fn admission(scene: &ProductScene, request: &ImageRequest, options: JobOptions) -> Result<Admission> {
    if request.integrator != solidcraft_render::job::Integrator::Raster || request.raytrace.is_some() {
        return Err(JobError::new(ErrorCode::InvalidRequest, "GPU path rendering does not accept CPU raytrace options"));
    }
    options.validate()?;
    photons::validate_scene(scene, options)?;
    if request.studio_weights.is_some_and(|weights| weights.iter().any(|value| !value.is_finite() || !(0.0..=1.0).contains(value))) {
        return Err(JobError::new(ErrorCode::InvalidRequest, "invalid studio visibility weights"));
    }
    if request.studio_weights.is_some() && (options.lighting.is_some() || request.environment.is_some()) {
        return Err(JobError::new(ErrorCode::InvalidRequest, "studio weights require implicit studio lighting"));
    }
    options.aging.validate_scene(scene)?;
    if options.finishing.photographic.active() && request.transparent_background {
        return Err(JobError::new(ErrorCode::InvalidRequest, "photographic effects require opaque output; choose it explicitly"));
    }
    if let Some(volume) = options.volume.filter(|v| v.active()) {
        volume.relative_bounds([request.camera.target.x, request.camera.target.y, request.camera.target.z])?;
        if options.lighting.is_none() && request.environment.is_none() {
            return Err(JobError::new(ErrorCode::InvalidRequest, "volume transport requires explicit studio lighting or an HDR/sky environment"));
        }
        if scene.meshes.iter().any(|body| body.transmission.is_some() || body.faces.iter().any(|face| face.transmission.is_some())) {
            return Err(JobError::new(
                ErrorCode::InvalidScene,
                "this homogeneous volume cannot combine with glass boundaries; disable either explicitly",
            ));
        }
    }
    if request.transparent_background && options.finishing.bloom.is_some_and(|b| b.active()) {
        return Err(JobError::new(ErrorCode::InvalidRequest, "display bloom requires opaque output; no implicit alpha expansion is supported"));
    }
    if options.backdrop.is_some() && request.transparent_background {
        return Err(JobError::new(ErrorCode::InvalidRequest, "choose a camera backdrop or transparent PNG, not both"));
    }
    if let Some(environment) = &request.environment {
        environment.validate()?;
    }
    let scattering = |t: Option<solidcraft_render::transmission::Transmission>| t.and_then(|v| v.subsurface()).is_some_and(|s| s.active());
    if scene.meshes.iter().any(|b| scattering(b.transmission) || b.faces.iter().any(|f| scattering(f.transmission)))
        && (options.denoise || options.transmission_samples != 1 || options.volume.is_some_and(|v| v.active()))
    {
        return Err(JobError::new(
            ErrorCode::InvalidRequest,
            "subsurface random walks require disabled surface denoising, one Fresnel stratum and no external volume",
        ));
    }
    let camera = request.camera;
    validate_punctual_origin(options, camera.target)?;
    if options.lens.is_some_and(|lens| lens.aperture_radius_mm > 0.0)
        && (camera.distance < 1e-6 || !(1e-6..=1e6).contains(&(camera.half_height() / camera.distance)) || camera.fov == 0.0)
    {
        return Err(JobError::new(
            ErrorCode::InvalidRequest,
            "thin-lens depth of field requires a bounded perspective camera (distance >= 0.000001 mm and tan(fov/2) in 0.000001..1000000)",
        ));
    }
    if !camera.fov.is_finite()
        || !(0.0..std::f64::consts::PI).contains(&camera.fov)
        || !camera.half_height().is_finite()
        || camera.half_height() > 1e12
        || camera.distance > 1e9
    {
        return Err(JobError::new(ErrorCode::InvalidRequest, "gpu-path requires a bounded finite camera"));
    }
    let mut admission = admit_geometry_with_limits(scene, request, MAX_TRIANGLES, MAX_GPU_PATH_BODIES, 2 * 1024 * 1024 * 1024, GPU_PATH_LIMITS)?;
    if scene
        .meshes
        .iter()
        .any(|m| (m.opacity != 1.0 && m.transmission.is_none()) || m.faces.iter().any(|f| f.opacity != 1.0 && f.transmission.is_none()))
    {
        return Err(JobError::new(ErrorCode::InvalidScene, "gpu-path requires explicit transmission for nonopaque preview appearances"));
    }
    // Peak preparation: f64 triangles + nodes + serialized upload. After preparation:
    // serialized + device geometry + accumulation/readback/RGBA/PNG. These phases don't overlap.
    let pixels = u64::from(request.width) * u64::from(request.height);
    let denoise_bytes = pixels * if options.denoise { denoise::BYTES_PER_PIXEL + if options.adaptive.is_some() { 16 } else { 0 } } else { 0 };
    let optical_tile_bytes = glass_tile_bytes(scene, request);
    admission.pixel_scratch_bytes = pixels * 64 + denoise_bytes;
    let vertex_bytes = scene.meshes.iter().map(|m| m.mesh.positions.len() as u64 * 32).sum::<u64>();
    let model_bytes = admission.triangles * scene::model_bytes_per_triangle(scene);
    admission.geometry_bytes += model_bytes;
    let triangle_preparation =
        (admission.triangles * 400_u64.max(scene::planar_preparation_bytes_per_triangle() as u64)).max(scene::medium_preparation_bytes(scene));
    admission.preparation_bytes = (triangle_preparation + vertex_bytes * 2 + admission.face_appearances * 8)
        .max(admission.triangles * 264 + vertex_bytes * 2 + pixels * 32 + denoise_bytes)
        .max(admission.triangles * 132 + vertex_bytes + admission.pixel_scratch_bytes)
        + 1_048_576
        + 2 * DIRECTIONAL_PARAMETER_BYTES
        + 2 * PUNCTUAL_PARAMETER_BYTES
        + 2 * PUNCTUAL_COUNTER_BYTES;
    // Optional material lane is retained in serialized/device geometry while
    // preparation also owns its serialization scratch. Legacy scenes add zero.
    admission.preparation_bytes += model_bytes * 2;
    admission.preparation_bytes += request.environment.as_ref().map_or(0, |source| source.admitted_bytes());
    if let Some(textures) = &request.textures {
        textures.validate_scene(scene)?;
        admission.preparation_bytes += textures.working_bytes();
    }
    if options.linear_exr {
        admission.preparation_bytes = admission
            .preparation_bytes
            .checked_add(solidcraft_render::job::linear_exr::encoded_limit(request.width, request.height)?)
            .ok_or_else(|| JobError::new(ErrorCode::LimitExceeded, "linear master admission overflow"))?;
    }
    let bloom_bytes = options.finishing.bloom.map_or(Ok(0), |b| b.scratch_bytes(request.width, request.height))?;
    admission.pixel_scratch_bytes = admission
        .pixel_scratch_bytes
        .checked_add(bloom_bytes)
        .ok_or_else(|| JobError::new(ErrorCode::LimitExceeded, "bloom pixel estimate overflow"))?;
    admission.preparation_bytes = admission
        .preparation_bytes
        .checked_add(bloom_bytes)
        .ok_or_else(|| JobError::new(ErrorCode::LimitExceeded, "bloom preparation estimate overflow"))?;
    let photo_bytes = options.finishing.photographic.scratch_bytes(request.width, request.height)?;
    admission.pixel_scratch_bytes += photo_bytes;
    admission.preparation_bytes += photo_bytes;
    // Two pilot/budget planes plus a second readback plane. Adaptive denoising's
    // independent normalized preview input is included in denoise_bytes above.
    let adaptive_bytes = pixels * if options.adaptive.is_some() { 48 } else { 0 };
    admission.pixel_scratch_bytes += adaptive_bytes + optical_tile_bytes;
    admission.preparation_bytes += adaptive_bytes + optical_tile_bytes;
    admission.preparation_bytes = admission
        .preparation_bytes
        .checked_add(photons::admission_bytes(options.caustics)?)
        .ok_or_else(|| JobError::new(ErrorCode::LimitExceeded, "caustic photon admission overflow"))?;
    admission.estimated_total_bytes = admission.geometry_bytes + admission.preparation_bytes;
    if admission.estimated_total_bytes > GPU_PATH_LIMITS.max_scratch_bytes {
        return Err(JobError::new(ErrorCode::LimitExceeded, "gpu-path job exceeds its bounded 8 GiB admission estimate"));
    }
    Ok(admission)
}

impl ImageExecutor for Executor {
    fn supports_glass_models(&self) -> bool {
        true
    }
    fn supports_caustics(&self) -> bool {
        true
    }
    fn preview_samples(&self, options: JobOptions) -> Option<u32> {
        options.preview_target().ok()
    }
    fn supports_aging(&self) -> bool {
        true
    }
    fn supports_photographic(&self) -> bool {
        true
    }
    fn supports_subsurface(&self) -> bool {
        true
    }
    fn supports_nested_media(&self) -> bool {
        true
    }
    fn supports_volume(&self) -> bool {
        true
    }
    fn supports_adaptive_sampling(&self) -> bool {
        true
    }
    fn supports_transmission_sampling(&self) -> bool {
        true
    }
    fn supports_bloom(&self) -> bool {
        true
    }
    fn supports_finishing(&self) -> bool {
        true
    }
    fn supports_linear_exr(&self) -> bool {
        true
    }
    fn memory_limit_bytes(&self) -> u64 {
        GPU_PATH_LIMITS.max_scratch_bytes
    }
    fn descriptor(&self) -> Result<ExecutorDescriptor> {
        let mut value = descriptor()?;
        if !self.context.healthy.load(Ordering::Acquire) {
            value.availability = Availability::Unavailable { reason: "GPU path device was lost or failed to complete work; restart renderer".into() };
        }
        Ok(value)
    }
    fn admit(&self, scene: &ProductScene, request: &ImageRequest, options: JobOptions) -> Result<Admission> {
        self.context.ensure_available()?;
        let a = admission(scene, request, options)?;
        let device_limits = self.context.device.limits();
        if let Some(caustics) = options.caustics {
            if device_limits.max_storage_buffers_per_shader_stage < 7 {
                return Err(JobError::new(
                    ErrorCode::HostUnavailable,
                    "caustics require seven GPU storage buffers; ordinary GPU images remain available",
                ));
            }
            let photon_bytes = photons::buffer_bytes(caustics)?;
            if photon_bytes > device_limits.max_storage_buffer_binding_size || photon_bytes > device_limits.max_buffer_size {
                return Err(JobError::new(ErrorCode::LimitExceeded, "caustic photon storage exceeds the selected GPU buffer limit"));
            }
        }
        if PARAMETER_BYTES as u64 > device_limits.max_uniform_buffer_binding_size
            || PARAMETER_BYTES as u64 > device_limits.max_buffer_size
            || FAILURE_BYTES > device_limits.max_storage_buffer_binding_size
        {
            return Err(JobError::new(ErrorCode::LimitExceeded, "GPU light parameters or diagnostic storage exceed device buffer limits"));
        }
        let limit = device_limits.max_storage_buffer_binding_size;
        let geometry_bytes = 16
            + a.triangles.max(1) * (100 + scene::model_bytes_per_triangle(scene))
            + scene.meshes.iter().map(|m| m.mesh.positions.len() as u64 * 32).sum::<u64>();
        let texture_bytes = request.textures.as_ref().map_or(16, |t| textures::packed_bytes(t, scene.meshes.len()));
        let environment_bytes =
            request.environment.as_ref().map_or(48, |source| 16 + u64::from(source.info().width) * u64::from(source.info().height) * 32);
        let node_bytes = a.triangles.max(1) * 64;
        let accumulation_bytes = u64::from(request.width) * u64::from(request.height) * if options.adaptive.is_some() { 48 } else { 16 }
            + glass_tile_bytes(scene, request);
        if node_bytes > limit
            || texture_bytes > limit
            || environment_bytes > limit
            || geometry_bytes > limit
            || accumulation_bytes > limit
            || (options.denoise && u64::from(request.width) * u64::from(request.height) * 48 > limit)
        {
            return Err(JobError::new(ErrorCode::LimitExceeded, "gpu-path storage buffer exceeds this device's limit"));
        }
        Ok(a)
    }
    fn begin(&self, scene: ProductScene, request: ImageRequest, options: JobOptions, cancel: CancelToken) -> Result<Box<dyn ImageWork>> {
        self.admit(&scene, &request, options)?;
        let mut task = Task::new(self.context.clone(), scene, request, options, cancel)?;
        task.preview_enabled = true;
        Ok(Box::new(task))
    }
}

/// Build all fallible CPU environment data before opening GPU error scopes.
fn prepare_environment(request: &ImageRequest, cancel: &CancelToken) -> Result<Vec<u8>> {
    cancel.check()?;
    let mut environment_bytes = Vec::new();
    if let Some(source) = &request.environment {
        let prepared = source.prepare(cancel)?;
        environment_bytes = scene::reserved(16 + prepared.texels().len() * 32)?;
        let [width, height] = prepared.dimensions();
        for x in [width, height, width * height, 0] {
            environment_bytes.extend_from_slice(&x.to_le_bytes());
        }
        for (index, texel) in prepared.texels().iter().enumerate() {
            if index % 1024 == 0 {
                cancel.check()?;
            }
            for x in texel.rgb.into_iter().chain([texel.pdf, texel.threshold]) {
                environment_bytes.extend_from_slice(&x.to_le_bytes());
            }
            environment_bytes.extend_from_slice(&texel.alias.to_le_bytes());
            environment_bytes.extend_from_slice(&[0; 8]);
        }
    } else {
        environment_bytes.resize(48, 0);
    }
    Ok(environment_bytes)
}

fn punctual_parameters(light: &solidcraft_render::job::PunctualLightOptions, origin: Vec3) -> [[f32; 4]; 5] {
    let p = Vec3::new(light.position_mm[0], light.position_mm[1], light.position_mm[2]) - origin;
    let hi = [p.x as f32, p.y as f32, p.z as f32];
    let lo = [(p.x - f64::from(hi[0])) as f32, (p.y - f64::from(hi[1])) as f32, (p.z - f64::from(hi[2])) as f32];
    let (axis, inner, outer, enabled) = if let Some(cone) = light.cone {
        let [x, y, z] = cone.emitted_axis;
        let scale = x.abs().max(y.abs()).max(z.abs());
        let v = Vec3::new(x / scale, y / scale, z / scale);
        let v = v / v.len();
        ([v.x as f32, v.y as f32, v.z as f32], cone.inner_half_angle_radians.cos() as f32, cone.outer_half_angle_radians.cos() as f32, 1.0)
    } else {
        ([0.0; 3], 0.0, 0.0, 0.0)
    };
    [
        [hi[0], hi[1], hi[2], light.reference_distance_mm as f32],
        [lo[0], lo[1], lo[2], light.minimum_distance_mm as f32],
        [light.color[0] as f32, light.color[1] as f32, light.color[2] as f32, light.intensity as f32],
        [axis[0], axis[1], axis[2], inner],
        [outer, enabled, 0.0, 0.0],
    ]
}
fn validate_punctual_origin(options: JobOptions, origin: Vec3) -> Result<()> {
    if let Some(lighting) = options.lighting {
        for light in lighting.punctual_lights.iter() {
            light.validate_gpu()?;
            if punctual_parameters(light, origin).iter().flatten().any(|v| !v.is_finite()) {
                return Err(JobError::new(ErrorCode::InvalidRequest, "point or spot position is outside the GPU camera-relative range"));
            }
        }
    }
    Ok(())
}

struct Task {
    dispatch_budget: dispatch::Budget,
    context: Arc<Context>,
    request: ImageRequest,
    options: JobOptions,
    #[cfg(test)]
    opaque_scene: bool,
    #[cfg(test)]
    has_textures: bool,
    cancel: CancelToken,
    uniform: wgpu::Buffer,
    accumulation: wgpu::Buffer,
    failures: wgpu::Buffer,
    readback: wgpu::Buffer,
    bind: wgpu::BindGroup,
    render_pipeline: wgpu::ComputePipeline,
    optical_resolve: Option<wgpu::ComputePipeline>,
    photons: Option<photons::Resources>,
    denoiser: Option<denoise::Resources>,
    sample: u32,
    lane: u32,
    sampling_report: Option<solidcraft_render::job::adaptive::SamplingReport>,
    punctual_diagnostics: std::cell::Cell<solidcraft_render::job::PunctualDiagnostics>,
    volume: [[f32; 4]; 3],
    aging: [[f32; 20]; 8],
    photographic: Option<solidcraft_render::job::photographic::PhotographicTask>,
    offset: u32,
    epsilon: f32,
    png: Option<PngTask>,
    encoding_preview: bool,
    preview_enabled: bool,
    preview: Option<solidcraft_render::job::ImageWorkPreview>,
    exr_work: Option<solidcraft_render::job::linear_exr::ExrTask>,
    bloom_work: Option<solidcraft_render::job::bloom::BloomTask>,
    exr: Option<Vec<u8>>,
    started: Instant,
    // Uniform environment is used only by the numerical furnace test, never advertised as HDRI.
    environment: f32,
    environment_bottom_only: bool,
    studio: f32,
    #[cfg(test)]
    metrics: (f64, u64, f64),
}
impl Task {
    fn new(context: Arc<Context>, scene: ProductScene, mut request: ImageRequest, options: JobOptions, cancel: CancelToken) -> Result<Self> {
        cancel.check()?;
        options.validate()?;
        validate_punctual_origin(options, request.camera.target)?;
        let opaque_scene = use_opaque_pipeline(&scene, options);
        let has_textures = request.textures.is_some();
        let start = Instant::now();
        let aging = options.aging.gpu_layers([request.camera.target.x, request.camera.target.y, request.camera.target.z])?;
        let mut volume = if let Some(v) = options.volume.filter(|v| v.active()) {
            let bounds = v.relative_bounds([request.camera.target.x, request.camera.target.y, request.camera.target.z])?;
            [
                [bounds[0][0], bounds[0][1], bounds[0][2], v.extinction_per_mm as f32],
                [bounds[1][0], bounds[1][1], bounds[1][2], v.anisotropy as f32],
                [v.scattering_albedo[0] as f32, v.scattering_albedo[1] as f32, v.scattering_albedo[2] as f32, 0.0],
            ]
        } else {
            [[0.0; 4]; 3]
        };
        if let Some(resources) = &request.textures {
            resources.validate_scene(&scene)?;
        }
        let texture_upload = textures::flatten(request.textures.as_deref(), scene.meshes.len(), request.camera.target, &cancel)?;
        request.textures = None; // GPU upload owns decoded pixels; release captured source bytes.
        let upload = scene::flatten_with_media(&scene, request.camera.target, &cancel, options.nested_media)?;
        // This uniform lane was spare. Keep the material offset mask that the
        // mapped opaque shader has qualified on RADV.
        volume[2][3] = if upload.active_glass_model { 1.0 } else { 0.0 };
        photons::validate_punctual_origins(&scene, request.camera.target, options, upload.epsilon, &cancel)?;
        let bvh_ms = start.elapsed().as_secs_f64() * 1000.0;
        let source_count = options.lighting.map_or_else(
            || if request.environment.is_none() { 3 } else { 0 },
            |lighting| lighting.directional_lights.iter().count() as u32 + lighting.punctual_lights.iter().count() as u32,
        );
        let photons = options.caustics.map(|options| photons::Resources::new(&context, options, &upload.nodes, source_count)).transpose()?;
        cancel.check()?;
        let glass_lighting = needs_glass_lighting(&scene);
        let optical_tile_bytes = glass_tile_bytes(&scene, &request);
        let optical_pipelines = if glass_lighting {
            Some(glass_pipeline(&context, photons.as_ref().map_or(&context.layout, |resources| &resources.layout), photons.is_some(), &cancel)?)
        } else {
            None
        };
        let render_pipeline = if let Some(pipelines) = &optical_pipelines {
            pipelines.camera.clone()
        } else if let Some(resources) = &photons {
            resources.render.clone()
        } else {
            context.prepare_scene_pipeline(opaque_scene, has_textures, options.nested_media)?.clone()
        };
        let optical_resolve = optical_pipelines.map(|pipelines| pipelines.resolve);
        cancel.check()?;
        let mut upload_bytes = (upload.geometry.len() + upload.nodes.len() + texture_upload.len()) as u64;
        let environment_bytes = prepare_environment(&request, &cancel)?;
        cancel.check()?;
        let uploading = Instant::now();
        drop(scene);
        let device = &context.device;
        let (uniform, accumulation, failures, readback, bind, denoiser) = checked_creation(device, || {
            let make = |label, bytes: &[u8], usage| {
                device.create_buffer_init(&wgpu::util::BufferInitDescriptor { label: Some(label), contents: bytes, usage })
            };
            upload_bytes += environment_bytes.len() as u64;
            let environment = make("path environment", &environment_bytes, wgpu::BufferUsages::STORAGE);
            drop(environment_bytes);
            let triangles = make("path triangles", &upload.geometry, wgpu::BufferUsages::STORAGE);
            let nodes = make("path BVH", &upload.nodes, wgpu::BufferUsages::STORAGE);
            let texture_buffer = make("path opaque textures", &texture_upload, wgpu::BufferUsages::STORAGE);
            let uniform = make("path parameters", &[0; PARAMETER_BYTES], wgpu::BufferUsages::UNIFORM | wgpu::BufferUsages::COPY_DST);
            let size = u64::from(request.width) * u64::from(request.height) * 16;
            let accumulation = device.create_buffer(&wgpu::BufferDescriptor {
                label: Some("path accumulation"),
                size: size * if options.adaptive.is_some() { 3 } else { 1 } + optical_tile_bytes,
                usage: wgpu::BufferUsages::STORAGE | wgpu::BufferUsages::COPY_SRC,
                mapped_at_creation: false,
            });
            // Inconsistent-medium path count and the first such path's location (see read_linear).
            let failures = make(
                "path medium failures",
                &[0; FAILURE_BYTES as usize],
                wgpu::BufferUsages::STORAGE | wgpu::BufferUsages::COPY_SRC | wgpu::BufferUsages::COPY_DST,
            );
            let readback = device.create_buffer(&wgpu::BufferDescriptor {
                label: Some("path readback"),
                size: size * if options.adaptive.is_some() { 2 } else { 1 } + FAILURE_BYTES,
                usage: wgpu::BufferUsages::MAP_READ | wgpu::BufferUsages::COPY_DST,
                mapped_at_creation: false,
            });
            let mut entries: Vec<_> = [&uniform, &triangles, &nodes, &accumulation, &environment]
                .iter()
                .enumerate()
                .map(|(binding, buffer)| wgpu::BindGroupEntry { binding: binding as u32, resource: buffer.as_entire_binding() })
                .collect();
            entries.push(wgpu::BindGroupEntry { binding: 5, resource: texture_buffer.as_entire_binding() });
            entries.push(wgpu::BindGroupEntry { binding: 6, resource: failures.as_entire_binding() });
            if let Some(resources) = &photons {
                entries.push(wgpu::BindGroupEntry { binding: 7, resource: resources.buffer.as_entire_binding() });
            }
            let bind = device.create_bind_group(&wgpu::BindGroupDescriptor {
                label: Some("gpu-path"),
                layout: photons.as_ref().map_or(&context.layout, |resources| &resources.layout),
                entries: &entries,
            });
            let denoiser = if options.denoise {
                Some(denoise::Resources::new(
                    &context,
                    &uniform,
                    [&triangles, &nodes, &environment, &texture_buffer, &failures],
                    &accumulation,
                    size,
                    options.adaptive.is_some(),
                )?)
            } else {
                None
            };
            Ok((uniform, accumulation, failures, readback, bind, denoiser))
        })?;
        let submission = context.queue.submit([]);
        context.wait(submission, TIMEOUT)?;
        let upload_ms = uploading.elapsed().as_secs_f64() * 1000.0;
        log::info!("gpu-path BVH {bvh_ms:.3} ms, upload {upload_bytes} bytes in {upload_ms:.3} ms");
        cancel.check()?;
        if let Some(resources) = &photons {
            resources.warm_up_actual(&context, &uniform, &bind, &cancel)?;
        }
        if glass_lighting {
            cancel.check()?;
            context.ensure_available()?;
            checked_creation(&context.device, || {
                context.queue.write_buffer(&uniform, 0, &[0; PARAMETER_BYTES]);
                Ok(())
            })?;
            warm_up(&context.device, &context.queue, &render_pipeline, &bind, &context.healthy)?;
            cancel.check()?;
            if let Some(resolve) = &optical_resolve {
                warm_up(&context.device, &context.queue, resolve, &bind, &context.healthy)?;
            };
            cancel.check()?;
        }
        Ok(Self {
            dispatch_budget: Default::default(),
            #[cfg(test)]
            opaque_scene,
            #[cfg(test)]
            has_textures,
            context,
            request,
            options,
            cancel,
            uniform,
            accumulation,
            failures,
            readback,
            bind,
            render_pipeline,
            optical_resolve,
            photons,
            denoiser,
            sample: 0,
            lane: 0,
            sampling_report: None,
            punctual_diagnostics: Default::default(),
            volume,
            aging,
            photographic: None,
            offset: 0,
            epsilon: upload.epsilon,
            png: None,
            encoding_preview: false,
            preview_enabled: false,
            preview: None,
            exr_work: None,
            bloom_work: None,
            exr: None,
            started: Instant::now(),
            environment: 0.0,
            environment_bottom_only: false,
            studio: 1.0,
            #[cfg(test)]
            metrics: (bvh_ms, upload_bytes, upload_ms),
        })
    }
    fn parameters(&self, count: u32) -> Result<Vec<u8>> {
        let mut bytes = scene::reserved(PARAMETER_BYTES)?;
        if bytes.capacity() != PARAMETER_BYTES {
            return Err(JobError::new(ErrorCode::LimitExceeded, "GPU parameter upload exceeds its prepaid capacity"));
        }
        for x in [
            self.request.width,
            self.request.height,
            self.sample,
            self.offset,
            self.options.seed,
            self.options.max_depth,
            count,
            u32::from(self.environment_bottom_only),
        ] {
            bytes.extend_from_slice(&x.to_le_bytes());
        }
        let camera = self.request.camera;
        let (right, up, back) = camera.basis();
        let perspective = camera.fov > 0.0;
        let eye = back * (camera.distance * if perspective { 1.0 } else { 4.0 });
        scene::vector(&mut bytes, eye, if perspective { 1.0 } else { 0.0 });
        scene::vector(
            &mut bytes,
            right * camera.half_height() * (f64::from(self.request.width) / f64::from(self.request.height)),
            self.options.lens.map_or(0.0, |l| l.aperture_radius_mm as f32),
        );
        scene::vector(&mut bytes, up * camera.half_height(), self.options.lens.map_or(0.0, |l| l.focus_distance_mm as f32));
        scene::vector(&mut bytes, back, camera.distance as f32);
        scene::vector(
            &mut bytes,
            Vec3::new(f64::from(self.epsilon), f64::from(self.environment), f64::from(self.studio)),
            f32::from(u8::from(self.options.nested_media)),
        );
        let lighting = self.options.lighting.unwrap_or_default();
        scene::vector(
            &mut bytes,
            Vec3::new(lighting.environment[0], lighting.environment[1], lighting.environment[2]),
            if self.options.lighting.is_some() || self.request.environment.is_some() { 1.0 } else { 0.0 },
        );
        scene::vector(
            &mut bytes,
            Vec3::new(lighting.directional_lights.iter().count() as f64, lighting.punctual_lights.iter().count() as f64, 0.0),
            lighting.area_lights.iter().count() as f32,
        );
        for light in lighting.area_lights.iter() {
            let vector = |[x, y, z]: [f64; 3]| Vec3::new(x, y, z);
            scene::vector(&mut bytes, vector(light.center) - camera.target, light.area() as f32);
            scene::vector(&mut bytes, vector(light.u), 0.0);
            scene::vector(&mut bytes, vector(light.v), 0.0);
            scene::vector(&mut bytes, vector(light.radiance), 0.0);
        }
        bytes.resize(400, 0);
        if let Some(source) = &self.request.environment {
            let info = source.info();
            scene::vector(&mut bytes, Vec3::new(info.rotation_rad.cos(), info.rotation_rad.sin(), info.intensity), 1.0);
        } else {
            scene::vector(&mut bytes, Vec3::ZERO, 0.0);
        }
        if let Some(sun) = lighting.sun {
            scene::vector(&mut bytes, sun.direction(), sun.angular_radius_rad.cos() as f32);
            let [r, g, b] = sun.radiance;
            scene::vector(&mut bytes, Vec3::new(r, g, b), (1.0 / sun.solid_angle()) as f32);
        } else {
            bytes.resize(448, 0);
        }

        let adaptive = self.options.adaptive;
        for value in
            [adaptive.map_or(0, |a| a.pilot_samples), adaptive.map_or(0, |a| a.min_samples), self.options.transmission_samples, self.options.samples]
        {
            bytes.extend_from_slice(&value.to_le_bytes());
        }
        for value in [
            adaptive.map_or(0.0, |a| a.relative_error as f32),
            adaptive.map_or(0.0, |a| a.absolute_error as f32),
            adaptive.map_or(0.0, |a| a.coverage_error as f32),
            self.lane as f32,
        ] {
            bytes.extend_from_slice(&value.to_le_bytes());
        }
        for vector in self.volume {
            for value in vector {
                bytes.extend_from_slice(&value.to_le_bytes());
            }
        }
        for layer in self.aging {
            for value in layer {
                bytes.extend_from_slice(&value.to_le_bytes());
            }
        }
        for light in lighting.directional_lights.iter() {
            // Validation rejects zero/nonfinite input; scaled normalization preserves
            // every bounded CPU directional intent, including tiny finite vectors.
            let [x, y, z] = light.direction;
            let scale = x.abs().max(y.abs()).max(z.abs());
            let direction = Vec3::new(x / scale, y / scale, z / scale);
            scene::vector(&mut bytes, direction / direction.len(), light.intensity as f32);
            let [r, g, b] = light.color;
            scene::vector(&mut bytes, Vec3::new(r, g, b), 0.0);
        }
        bytes.resize(PARAMETER_BYTES - PUNCTUAL_PARAMETER_BYTES as usize - 16, 0);
        for light in lighting.punctual_lights.iter() {
            for vector in punctual_parameters(light, camera.target) {
                for value in vector {
                    bytes.extend_from_slice(&value.to_le_bytes());
                }
            }
        }
        bytes.resize(PARAMETER_BYTES - 16, 0);
        let weights = self.request.studio_weights.unwrap_or([1.0; 3]);
        for value in [weights[0] as f32, weights[1] as f32, weights[2] as f32, 0.0] {
            bytes.extend_from_slice(&value.to_le_bytes());
        }
        Ok(bytes)
    }
    fn normalization_samples(&self) -> u32 {
        if self.options.adaptive.is_some() { 1 } else { self.sample }
    }
    fn target_samples(&self) -> u32 {
        self.options.samples + self.options.adaptive.map_or(0, |a| a.pilot_samples)
    }
    fn dispatch(&mut self) -> Result<()> {
        self.cancel.check()?;
        self.context.ensure_available()?;
        if let Some(resources) = self.photons.as_ref().filter(|resources| !resources.ready()) {
            let parameters = self.parameters(resources.count())?;
            if let Some(resources) = &mut self.photons {
                resources.step(&self.context, &self.uniform, &self.bind, &parameters, &self.cancel)?;
            }
            return Ok(());
        }
        let dispatch_started = Instant::now();
        let pixels = self.request.width * self.request.height;
        let count = self.dispatch_budget.count(pixels - self.offset);
        let context = &self.context;
        let scopes = scopes(&context.device);
        context.queue.write_buffer(&self.uniform, 0, &self.parameters(count)?);
        let mut encoder = context.device.create_command_encoder(&wgpu::CommandEncoderDescriptor { label: Some("path tile") });
        {
            let mut pass = encoder.begin_compute_pass(&wgpu::ComputePassDescriptor { label: Some("path tile"), timestamp_writes: None });
            pass.set_pipeline(&self.render_pipeline);
            pass.set_bind_group(0, &self.bind, &[]);
            pass.dispatch_workgroups(count.div_ceil(PATH_WORKGROUP_SIZE), 1, 1);
        }
        if let Some(resolve) = &self.optical_resolve {
            let mut pass = encoder.begin_compute_pass(&wgpu::ComputePassDescriptor { label: Some("path optical resolve"), timestamp_writes: None });
            pass.set_pipeline(resolve);
            pass.set_bind_group(0, &self.bind, &[]);
            pass.dispatch_workgroups(count.div_ceil(PATH_WORKGROUP_SIZE), 1, 1);
        }
        let submission = context.queue.submit([encoder.finish()]);
        checked(scopes)?;
        context.wait(submission, TIMEOUT)?;
        self.dispatch_budget.observe(count, dispatch_started.elapsed());
        self.cancel.check()?;
        self.offset += count;
        if self.offset == pixels {
            self.offset = 0;
            let strata = if self.options.adaptive.is_some_and(|a| self.sample < a.pilot_samples) { 1 } else { self.options.transmission_samples };
            self.lane += 1;
            if self.lane == strata {
                self.sample += 1;
                self.lane = 0;
            }
        }
        Ok(())
    }
    #[cfg(test)]
    fn complete_sample(&mut self) -> Result<()> {
        let wanted = self.sample.checked_add(1).ok_or_else(|| gpu("sample counter overflow"))?;
        let maximum = (self.request.width * self.request.height)
            .div_ceil(dispatch::MIN_PATHS)
            .checked_mul(self.options.transmission_samples)
            .and_then(|count| count.checked_add(self.photons.as_ref().map_or(0, photons::Resources::maximum_quanta)))
            .ok_or_else(|| gpu("test sample wave count overflow"))?;
        for _ in 0..maximum {
            self.dispatch()?;
            if self.sample == wanted {
                return Ok(());
            }
        }
        Err(gpu("bounded full-sample test helper did not advance"))
    }
    fn read_linear(&self) -> Result<Vec<[f32; 4]>> {
        self.read_linear_buffer(&self.accumulation)
    }
    fn read_linear_buffer(&self, source: &wgpu::Buffer) -> Result<Vec<[f32; 4]>> {
        self.read_pixels(source, false)
    }
    fn read_checkpoint(&self) -> Result<Vec<[f32; 4]>> {
        self.read_pixels(&self.accumulation, self.options.adaptive.is_some())
    }
    fn read_pixels(&self, source: &wgpu::Buffer, adaptive_preview: bool) -> Result<Vec<[f32; 4]>> {
        self.cancel.check()?;
        let context = &self.context;
        let scopes = scopes(&context.device);
        let mut encoder = context.device.create_command_encoder(&wgpu::CommandEncoderDescriptor { label: Some("path readback") });
        let pixel_bytes = u64::from(self.request.width) * u64::from(self.request.height) * 16;
        let pilot = adaptive_preview && self.options.adaptive.is_some_and(|options| self.sample <= options.pilot_samples);
        encoder.copy_buffer_to_buffer(source, if pilot { pixel_bytes } else { 0 }, &self.readback, 0, pixel_bytes);
        if adaptive_preview && !pilot {
            encoder.copy_buffer_to_buffer(&self.accumulation, pixel_bytes * 2, &self.readback, pixel_bytes, pixel_bytes);
        }
        let failure_offset = pixel_bytes * if self.options.adaptive.is_some() { 2 } else { 1 };
        encoder.copy_buffer_to_buffer(&self.failures, 0, &self.readback, failure_offset, FAILURE_BYTES);
        let submission = context.queue.submit([encoder.finish()]);
        checked(scopes)?;
        let slice = self.readback.slice(..);
        let (tx, rx) = std::sync::mpsc::channel();
        slice.map_async(wgpu::MapMode::Read, move |result| {
            let _ = tx.send(result);
        });
        context.wait(submission, TIMEOUT)?;
        rx.try_recv().map_err(gpu)?.map_err(gpu)?;
        let data = slice.get_mapped_range().map_err(gpu)?;
        let result = (|| {
            let pixels = data.get(..pixel_bytes as usize).ok_or_else(|| gpu("missing image readback"))?;
            let failures = data.get(failure_offset as usize..).ok_or_else(|| gpu("missing failure readback"))?;
            let budgets = if adaptive_preview && !pilot {
                Some(data.get(pixel_bytes as usize..(pixel_bytes * 2) as usize).ok_or_else(|| gpu("missing adaptive preview budgets"))?)
            } else {
                None
            };
            let word = |i: usize| failures.as_chunks::<4>().0.get(i).map_or(0, |w| u32::from_le_bytes(*w));
            if word(7) & 16 != 0 {
                return Err(JobError::new(ErrorCode::InvalidScene, "rough optical response exceeds GPU arithmetic precision"));
            }
            if word(7) & 8 != 0 {
                return Err(JobError::new(ErrorCode::InvalidScene, "optical light-event count exceeds the admitted camera depth"));
            }
            if word(7) & 4 != 0 {
                return Err(JobError::new(ErrorCode::InvalidScene, "caustic photon medium origin or transition is ambiguous"));
            }
            if word(7) & 2 != 0 {
                return Err(JobError::new(ErrorCode::InvalidScene, "positive-thickness index-matched sheet has no finite grazing optical path"));
            }
            if word(7) != 0 {
                return Err(JobError::new(ErrorCode::Internal, "nonfinite or negative pilot/production path radiance"));
            }
            self.punctual_diagnostics.set(solidcraft_render::job::PunctualDiagnostics {
                near_source: u64::from(word(8)) | (u64::from(word(9)) << 32),
                radiance_limit: u64::from(word(10)) | (u64::from(word(11)) << 32),
                shadow_offset_crossed: u64::from(word(12)) | (u64::from(word(13)) << 32),
            });
            let failed = u64::from(word(0)) | (u64::from(word(5)) << 32);
            if failed > 0 {
                let pixels = u64::from(self.request.width) * u64::from(self.request.height);
                let paths = if adaptive_preview {
                    adaptive::preview_paths(self, budgets)?
                } else {
                    self.sampling_report.as_ref().map_or(
                        pixels * u64::from(self.sample.max(1)) * u64::from(self.options.transmission_samples),
                        |report| {
                            report.production_samples * u64::from(report.transmission_strata) + pixels * u64::from(report.pilot_samples_per_pixel)
                        },
                    )
                };
                let detail =
                    format!("{failed} of {paths} paths, first at pixel {}, bounce {}, sample {}, code {}", word(1), word(2), word(3), word(4));
                if !medium_failures_tolerated(failed, paths) {
                    return Err(JobError::new(
                        ErrorCode::InvalidScene,
                        format!(
                            "inconsistent glass medium paths ({detail}): ambiguous boundary origin or invalid containment; overlapping solids or more than 16 nested media are unsupported"
                        ),
                    ));
                }
                log::warn!("gpu-path ended {detail} at an unclassifiable glass medium");
            }
            let mut values = scene::reserved((self.request.width * self.request.height) as usize)?;
            for (index, pixel) in pixels.as_chunks::<16>().0.iter().enumerate() {
                if index % 4096 == 0 {
                    self.cancel.check()?;
                }
                let divisor = if adaptive_preview {
                    adaptive::preview_divisor(&self.options, self.sample, budgets.and_then(|values| values.get(index * 16..index * 16 + 4)))?
                } else {
                    self.normalization_samples() as f32
                };
                let mut value = [0.0; 4];
                for (v, bytes) in value.iter_mut().zip(pixel.as_chunks::<4>().0) {
                    *v = f32::from_le_bytes(*bytes) / divisor;
                    if !v.is_finite() || *v < 0.0 {
                        return Err(JobError::new(ErrorCode::Internal, "nonfinite or negative path radiance"));
                    }
                }
                values.push(value);
            }
            Ok(values)
        })();
        drop(data);
        self.readback.unmap();
        self.cancel.check()?;
        result
    }
}
use solidcraft_render::job::presentation::Display;

impl ImageWork for Task {
    fn punctual_diagnostics(&self) -> Option<solidcraft_render::job::PunctualDiagnostics> {
        self.options.lighting.filter(|l| !l.punctual_lights.is_empty()).map(|_| self.punctual_diagnostics.get())
    }

    fn take_preview(&mut self) -> Option<solidcraft_render::job::ImageWorkPreview> {
        self.preview.take()
    }
    fn sampling_report(&self) -> Option<solidcraft_render::job::adaptive::SamplingReport> {
        self.sampling_report.clone()
    }
    fn take_linear_exr(&mut self) -> Option<Vec<u8>> {
        self.exr.take()
    }
    fn step(&mut self, units: usize) -> Result<TaskPoll> {
        self.cancel.check()?;
        self.context.ensure_available()?;
        // Direct executor consumers may ignore previews; dropping their old slot
        // here never changes accumulated samples or final output. The image host
        // takes every publication immediately after this quantum.
        self.preview = None;
        if let Some(png) = &mut self.png {
            let poll = png.step(units)?;
            if self.encoding_preview
                && let TaskPoll::Complete(png) = poll
            {
                self.png = None;
                self.encoding_preview = false;
                self.preview = Some(solidcraft_render::job::ImageWorkPreview { png, samples_per_pixel: self.sample });
                return Ok(TaskPoll::Pending(Progress {
                    phase: Phase::Running,
                    done: u64::from(self.sample),
                    total: u64::from(self.target_samples()),
                }));
            }
            return Ok(poll);
        }
        if let Some(mut task) = self.photographic.take() {
            if !task.step(units)? {
                let (done, total) = task.progress();
                self.photographic = Some(task);
                return Ok(TaskPoll::Pending(Progress { phase: Phase::Encoding, done, total }));
            }
            self.png = Some(PngTask::new(&self.request, task.finish()?, self.cancel.clone())?);
            return Ok(TaskPoll::Pending(Progress { phase: Phase::Encoding, done: 0, total: u64::from(self.request.height) }));
        }
        if let Some(mut bloom) = self.bloom_work.take() {
            if !bloom.step(8)? {
                let done = bloom.completed_lines();
                let total = bloom.total_lines();
                self.bloom_work = Some(bloom);
                return Ok(TaskPoll::Pending(Progress { phase: Phase::Encoding, done, total }));
            }
            let (pixels, glow) = bloom.finish()?;
            return self.encode_output(pixels, Some(glow));
        }
        if self.sample < self.target_samples() {
            let before = self.sample;
            self.dispatch()?;
            if let Some(resources) = self.photons.as_ref().filter(|resources| !resources.ready()) {
                return Ok(TaskPoll::Pending(resources.progress()));
            }
            if self.preview_enabled && self.sample > before && self.sample < self.target_samples() {
                // sample advances only after every tile and Fresnel stratum of
                // the pass. Readback cannot observe a partially updated film.
                self.encoding_preview = true;
                let linear = self.read_checkpoint()?;
                return self.finish_output(linear);
            }
            return Ok(TaskPoll::Pending(Progress { phase: Phase::Running, done: u64::from(self.sample), total: u64::from(self.target_samples()) }));
        }
        if self.sampling_report.is_none() && (self.options.adaptive.is_some() || self.options.transmission_samples != 1) {
            self.sampling_report = Some(adaptive::report(self)?);
        }
        if self.exr_work.is_none() {
            log::info!("gpu-path {} spp, {:.3} ms/spp", self.sample, self.started.elapsed().as_secs_f64() * 1000.0 / f64::from(self.sample));
        }
        let linear = if let Some(mut work) = self.exr_work.take() {
            if !work.step(4)? {
                let done = work.completed_rows();
                self.exr_work = Some(work);
                return Ok(TaskPoll::Pending(Progress { phase: Phase::Encoding, done, total: u64::from(self.request.height) }));
            }
            let (bytes, pixels) = work.finish()?;
            self.exr = Some(bytes);
            pixels
        } else {
            let pixels = self.read_linear()?;
            if self.options.linear_exr {
                self.exr_work =
                    Some(solidcraft_render::job::linear_exr::ExrTask::new(self.request.width, self.request.height, pixels, self.cancel.clone())?);
                return Ok(TaskPoll::Pending(Progress { phase: Phase::Encoding, done: 0, total: u64::from(self.request.height) }));
            }
            pixels
        };
        self.finish_output(linear)
    }
}
impl Task {
    fn finish_output(&mut self, mut linear: Vec<[f32; 4]>) -> Result<TaskPoll> {
        if let Some(denoiser) = &self.denoiser {
            // Diagnose the raw path buffer before filtering: never hide invalid media
            // or nonfinite radiance by replacing a pixel with neighbouring values.
            drop(linear);
            if self.encoding_preview && self.options.adaptive.is_some() {
                denoiser.run_adaptive_preview(self)?;
            } else {
                denoiser.run(self)?;
            }
            linear = self.read_linear_buffer(denoiser.output())?;
        }
        if let Some(options) = self.options.finishing.bloom.filter(|options| options.active()) {
            self.bloom_work =
                Some(solidcraft_render::job::bloom::BloomTask::new(self.request.width, self.request.height, linear, options, self.cancel.clone())?);
            return Ok(TaskPoll::Pending(Progress {
                phase: Phase::Encoding,
                done: 0,
                total: u64::from(self.request.height) * 4 + u64::from(self.request.width) * 3,
            }));
        }
        self.encode_output(linear, None)
    }
    fn encode_output(&mut self, linear: Vec<[f32; 4]>, bloom: Option<Vec<[f32; 3]>>) -> Result<TaskPoll> {
        let encoded_len = linear.len().checked_mul(4).ok_or_else(|| gpu("display byte length overflow"))?;
        if bloom.as_ref().is_some_and(|pixels| pixels.len() != linear.len()) {
            return Err(gpu("bloom and display pixel counts differ"));
        }
        let mut rgba = scene::reserved(encoded_len)?;
        rgba.resize(encoded_len, 0);
        let display = Display {
            finishing: self.options.finishing,
            backdrop: self.options.backdrop,
            width: self.request.width,
            height: self.request.height,
            exposure: 2.0f64.powf(self.options.exposure_ev),
            tone_map: self.options.tone_map,
            background: self.request.background.map(solidcraft_render::surface::srgb8_to_linear),
            transparent: self.request.transparent_background,
        };
        // Pixels are independent: encode contiguous chunks on every core.
        let workers = std::thread::available_parallelism().map_or(1, |n| n.get()).clamp(1, 16);
        let chunk = linear.len().div_ceil(workers).max(1);
        let output_chunk = chunk.checked_mul(4).ok_or_else(|| gpu("display chunk byte length overflow"))?;
        let bloom = bloom.as_deref();
        let cancel = &self.cancel;
        std::thread::scope(|scope| {
            let jobs: Vec<_> = linear
                .chunks(chunk)
                .zip(rgba.chunks_mut(output_chunk))
                .enumerate()
                .map(|(i, (input, output))| {
                    scope.spawn(move || {
                        let offset = i.checked_mul(chunk).ok_or_else(|| gpu("display chunk offset overflow"))?;
                        let glow = bloom_chunk(bloom, offset, input.len())?;
                        display.encode_bloom_at(input, output, cancel, offset, glow)
                    })
                })
                .collect();
            jobs.into_iter()
                .try_for_each(|job| job.join().unwrap_or_else(|_| Err(JobError::new(ErrorCode::Internal, "display encoding worker failed"))))
        })?;
        if self.options.finishing.photographic.active() {
            self.photographic = Some(solidcraft_render::job::photographic::PhotographicTask::new(
                self.request.width,
                self.request.height,
                rgba,
                linear,
                self.options.finishing.photographic,
                self.cancel.clone(),
            )?);
        } else {
            self.png = Some(PngTask::new(&self.request, rgba, self.cancel.clone())?);
        }
        Ok(TaskPoll::Pending(Progress { phase: Phase::Encoding, done: 0, total: u64::from(self.request.height) }))
    }
}

/// A malformed intermediate image is a job error, never an indexing panic in a
/// display worker. Also bound addition before constructing the range.
fn bloom_chunk(pixels: Option<&[[f32; 3]]>, offset: usize, count: usize) -> Result<Option<&[[f32; 3]]>> {
    let Some(pixels) = pixels else { return Ok(None) };
    let end = offset.checked_add(count).ok_or_else(|| gpu("bloom chunk range overflow"))?;
    pixels.get(offset..end).map(Some).ok_or_else(|| gpu("bloom chunk is outside the retained image"))
}