Skip to content

armgit / vork

Public Imported from GitHub
0

Headless 3D and VFX engine for agents. Research preview.

69.7 KB
Raw Blame
//! Hardware ray queries over the installed geometry. Install builds one BLAS per
//! unique static geometry set straight from the shared vertex/index pages;
//! each frame slot owns its TLAS and the BLAS of its deformed streams. The
//! change tracker's object and skin uploads decide when they rebuild. Visibility
//! queries share opaque static hierarchies; identity consumers retain primitives.
//! This path uses full TLAS/BLAS builds; true update/refit remains separate.
use crate::*;

const BUILD_FLAGS: wgpu::AccelerationStructureFlags =
    wgpu::AccelerationStructureFlags::PREFER_FAST_TRACE;

/// The scene TLAS at `first` and the alpha table at `first + 1`.
pub(crate) fn layout_entries(first: u32, stages: wgpu::ShaderStages) -> [wgpu::BindGroupLayoutEntry; 2] {
    [
        wgpu::BindGroupLayoutEntry {
            binding: first,
            visibility: stages,
            ty: wgpu::BindingType::AccelerationStructure { vertex_return: false },
            count: None,
        },
        pipelines::buffer_entry(
            first + 1,
            stages,
            wgpu::BufferBindingType::Storage { read_only: true },
        ),
    ]
}

/// AO/GI query outputs: visibility/radiance and the selected world position.
fn storage_entry(binding: u32, format: wgpu::TextureFormat) -> wgpu::BindGroupLayoutEntry {
    wgpu::BindGroupLayoutEntry { binding, visibility: wgpu::ShaderStages::COMPUTE,
        ty: wgpu::BindingType::StorageTexture { access: wgpu::StorageTextureAccess::WriteOnly,
            format, view_dimension: wgpu::TextureViewDimension::D2 }, count: None }
}
/// Ray GI group 0: the shared scene globals (frame.slang), then depth, normals,
/// the AO/visibility output, camera colour, incident output, TLAS and hit table.
/// Group 1 is the scene material table, group 2 the hit buffer array.
pub(crate) fn gi_entries() -> Vec<wgpu::BindGroupLayoutEntry> {
    let compute = wgpu::ShaderStages::COMPUTE;
    let texture = |binding| wgpu::BindGroupLayoutEntry {
        visibility: compute,
        ..pipelines::texture_entry(binding, wgpu::TextureSampleType::Float { filterable: false }, false)
    };
    let mut entries = pipelines::global_entries();
    entries.extend([texture(10), texture(11), storage_entry(12,wgpu::TextureFormat::Rgba16Float), storage_entry(13,wgpu::TextureFormat::Rgba16Float)]);
    entries.extend(layout_entries(14, compute));
    entries.push(storage_entry(16,wgpu::TextureFormat::Rgba32Float));
    entries.push(pipelines::buffer_entry(17,compute,wgpu::BufferBindingType::Uniform));
    entries.push(pipelines::buffer_entry(18,compute,wgpu::BufferBindingType::Storage {read_only:true}));
    entries.push(texture(19));
    entries.push(pipelines::buffer_entry(20,compute,wgpu::BufferBindingType::Storage {read_only:true}));
    for e in &mut entries {
        e.visibility = compute;
    }
    entries
}

/// With probes, group 2 reads the irradiance volume at hits (probes.rs).
pub(crate) fn gi_layout(
    d: &wgpu::Device,
    materials: &wgpu::BindGroupLayout,
    probes: bool,
) -> wgpu::PipelineLayout {
    let entries = gi_entries();
    let group = d.create_bind_group_layout(&wgpu::BindGroupLayoutDescriptor {
        label: Some("local GI"),
        entries: &entries,
    });
    d.create_pipeline_layout(&wgpu::PipelineLayoutDescriptor {
        label: Some("ray GI layout"),
        bind_group_layouts: &[Some(&group), Some(materials), probes.then(|| crate::probes::read_layout(d)).as_ref(), Some(&gi_read_layout(d))],
        immediate_size: 0,
    })
}
pub(crate) fn gi_read_entries()->Vec<wgpu::BindGroupLayoutEntry> {
    let mut entries=vec![hit_buffers_entry(0,wgpu::ShaderStages::COMPUTE)];
    entries.push(pipelines::buffer_entry(1,wgpu::ShaderStages::COMPUTE,wgpu::BufferBindingType::Storage {read_only:false}));
    entries
}
pub(crate) fn gi_read_layout(d:&wgpu::Device)->wgpu::BindGroupLayout {
    d.create_bind_group_layout(&wgpu::BindGroupLayoutDescriptor {label:Some("GI hit and accumulation buffers"),entries:&gi_read_entries()})
}
/// Group 3 of hit-shading compute kernels: only the hit buffer array (wgpu
/// keeps binding arrays out of groups with uniform buffers; group 2 is the
/// shadow modules' own).
pub(crate) fn hits_layout(d: &wgpu::Device) -> wgpu::BindGroupLayout {
    d.create_bind_group_layout(&wgpu::BindGroupLayoutDescriptor {
        label: Some("hit buffers"),
        entries: &[hit_buffers_entry(0, wgpu::ShaderStages::COMPUTE)],
    })
}

/// Ray reflections that shade unseen hits: the scene globals (frame.slang), then
/// colour, depth, normals, ambient, the output, TLAS and hit table. Group 1 is
/// the scene material table, group 3 the hit geometry and reflection field arrays.
pub(crate) fn reflections_hits_entries() -> Vec<wgpu::BindGroupLayoutEntry> {
    let compute = wgpu::ShaderStages::COMPUTE;
    let texture = |binding| wgpu::BindGroupLayoutEntry {
        visibility: compute,
        ..pipelines::texture_entry(binding, wgpu::TextureSampleType::Float { filterable: false }, false)
    };
    let mut entries = pipelines::global_entries();
    entries.extend([texture(10), texture(11), texture(12), texture(13)]);
    entries.push(wgpu::BindGroupLayoutEntry {
        binding: 14,
        visibility: compute,
        ty: wgpu::BindingType::StorageTexture {
            access: wgpu::StorageTextureAccess::WriteOnly,
            format: wgpu::TextureFormat::Rgba16Float,
            view_dimension: wgpu::TextureViewDimension::D2Array,
        },
        count: None,
    });
    entries.extend(layout_entries(15, compute));
    entries.push(pipelines::buffer_entry(17, compute, wgpu::BufferBindingType::Storage {read_only:true}));
    entries.push(pipelines::buffer_entry(18, compute, wgpu::BufferBindingType::Storage {read_only:true}));
    entries.push(pipelines::buffer_entry(19, compute, wgpu::BufferBindingType::Storage {read_only:true}));
    entries.push(pipelines::buffer_entry(20,compute,wgpu::BufferBindingType::Uniform));
    entries.push(pipelines::buffer_entry(21,compute,wgpu::BufferBindingType::Storage {read_only:false}));
    entries.push(pipelines::buffer_entry(22,compute,wgpu::BufferBindingType::Storage {read_only:true}));
    for e in &mut entries {
        e.visibility = compute;
    }
    entries
}
pub(crate) fn reflections_hits_layout(d: &wgpu::Device, materials: &wgpu::BindGroupLayout, probes: bool, medium_pages: u32) -> wgpu::PipelineLayout {
    let group = d.create_bind_group_layout(&wgpu::BindGroupLayoutDescriptor {
        label: Some("ray reflection hits"),
        entries: &reflections_hits_entries(),
    });
    d.create_pipeline_layout(&wgpu::PipelineLayoutDescriptor {
        label: Some("ray reflection hits layout"),
        bind_group_layouts: &[Some(&group), Some(materials), probes.then(|| crate::probes::read_layout(d)).as_ref(), Some(&reflection_read_layout(d,medium_pages))],
        immediate_size: 0,
    })
}

/// Optional current-view visibility pages share the hit-table group. With no
/// scattering lights only geometry and reflection fields are bound.
pub(crate) fn reflection_read_entries(medium_pages:u32)->Vec<wgpu::BindGroupLayoutEntry> {
    let mut entries=vec![hit_buffers_entry(0,wgpu::ShaderStages::COMPUTE),crate::passes::reflections::record_fields_entry(1,true)];
    if let Some(count)=std::num::NonZeroU32::new(medium_pages) {
        let mut pages=pipelines::buffer_entry(2,wgpu::ShaderStages::COMPUTE,wgpu::BufferBindingType::Storage {read_only:true});
        pages.count=Some(count);entries.push(pages);
    }
    entries
}
pub(crate) fn reflection_read_layout(d:&wgpu::Device,medium_pages:u32)->wgpu::BindGroupLayout {
    d.create_bind_group_layout(&wgpu::BindGroupLayoutDescriptor {label:Some("reflection hit and medium buffers"),entries:&reflection_read_entries(medium_pages)})
}

/// Raster geometry buffers double as BLAS inputs only in scenes that trace rays.
pub(crate) fn geometry_usage(rays: bool) -> wgpu::BufferUsages {
    if rays {
        wgpu::BufferUsages::BLAS_INPUT
    } else {
        wgpu::BufferUsages::empty()
    }
}

fn intern_buffer(buffers: &mut Vec<HitBuffer>, buffer: HitBuffer) -> u32 {
    buffers.iter().position(|b| *b == buffer).unwrap_or_else(|| {
        buffers.push(buffer);
        buffers.len() - 1
    }) as u32
}

/// Where one draw's ray-hit corners live in the raster buffers (hit.slang):
/// positions, indices and the packed attribute stream of its VertexLayout,
/// addressed through the hit buffer array. No second copy of geometry.
fn hit_record(
    draw: &install::Draw,
    buffers: &mut Vec<HitBuffer>,
    leader: Option<usize>,
    displaced: Option<(usize, u64)>,
) -> [u32; constants::RAY_HIT_RECORD_WORDS] {
    let mut slot = |buffer| intern_buffer(buffers, buffer);
    let layout = draw.layout;
    let deformed = layout.deform;
    let (positions, base, stride) = if let Some((page, offset)) = displaced {
        (slot(HitBuffer::DisplacedPage(page)), (offset / 4) as u32, 10)
    } else {
        match leader {
        Some(leader) => (slot(HitBuffer::Deformed(leader)), 0, (std::mem::size_of::<DeformedVertex>() / 4) as u32),
        None => (slot(HitBuffer::Static(draw.vertices.clone())), (draw.vertex_offset / 4) as u32, (layout.vertex_stride()/4) as u32),
        }
    };
    let indices = slot(HitBuffer::Static(draw.indices.clone()));
    let attributes = slot(if draw.computed { HitBuffer::Attributes(leader.expect("computed leader")) } else { HitBuffer::Static(draw.attributes.clone()) });
    const NONE: u32 = 0xff;
    // Float offsets within a vertex: deformed normals/tangents follow the pose.
    let (normal, tangent, rest, surface) = if deformed {
        (3, 6, 0, 3)
    } else {
        (0, if layout.tangent { 3 } else { NONE }, NONE, 3 + if layout.tangent { 4 } else { 0 })
    };
    let uv = |set: usize| {
        let packed = layout.uv[set];
        if packed == constants::VERTEX_DEFAULT_UV { NONE } else { surface + 2 * u32::from(packed) }
    };
    let uv_count = layout.uv.iter().filter(|&&p| p != constants::VERTEX_DEFAULT_UV).map(|&p| u32::from(p) + 1).max().unwrap_or(0);
    let color = surface + 2 * uv_count;
    let custom = color + if layout.color { 4 } else { 0 };
    [
        positions,
        base,
        stride,
        indices,
        (draw.index_offset / 4) as u32,
        attributes,
        (draw.attribute_offset() / 4) as u32,
        (layout.attribute_stride() / 4) as u32,
        normal | tangent << 8 | rest << 16 | u32::from(deformed) << 24,
        uv(0) | uv(1) << 8 | (if layout.color { color } else { NONE }) << 16 | (if layout.custom > 0 { custom } else { NONE }) << 24,
    ]
}
/// One element of the hit buffer array: an installed raster buffer, or a
/// deformation leader's range of the frame slot's deform pool.
#[derive(Clone, PartialEq)]
pub(crate) enum HitBuffer {
    Static(wgpu::Buffer),
    Deformed(usize),
    DisplacedPage(usize),
    Attributes(usize),
}
/// Installed buffers are bound whole by both camera and ray-hit readers.
/// Evaluated ranges have already been admitted by the geometry page planner.
fn admit_static_hit_buffers(limits: &wgpu::Limits, buffers: &[HitBuffer]) -> Result<()> {
    for (index, buffer) in buffers.iter().enumerate() {
        if let HitBuffer::Static(buffer) = buffer {
            crate::gpu_memory::storage_binding(limits, &format!("hit geometry buffer {index}"), buffer.size())?;
        }
    }
    Ok(())
}
/// Resolve installed hit records to the frame slot's evaluated geometry ranges.
pub(crate) fn resolve_hit_buffers(buffers: &[HitBuffer], deforms: &[Option<EvaluatedGeometry>]) -> Vec<(wgpu::Buffer, u64, u64)> {
    buffers.iter().map(|b| match b {
        HitBuffer::Attributes(i) => { let b=deforms[*i].as_ref().unwrap().attributes.as_ref().unwrap(); (b.clone(),0,b.size()) },
        HitBuffer::Static(buffer) => (buffer.clone(), 0, buffer.size()),
        HitBuffer::DisplacedPage(leader) => {
            let output = &deforms[*leader].as_ref().expect("evaluated page").output;
            (output.buffer.clone(), 0, output.buffer.size())
        }
        HitBuffer::Deformed(leader) => {
            let output = &deforms[*leader].as_ref().expect("deformation leader output").output;
            (output.buffer.clone(), output.offset, output.size)
        }
    }).collect()
}
/// The hit buffer array binding; unused slots stay unbound (partially bound).
pub(crate) fn hit_bindings(buffers: &[(wgpu::Buffer, u64, u64)]) -> Vec<wgpu::BufferBinding<'_>> {
    buffers.iter().map(|(buffer, offset, size)| wgpu::BufferBinding {
        buffer, offset: *offset, size: std::num::NonZeroU64::new(*size),
    }).collect()
}
/// The hit-buffer group shared by compute surface kernels.
pub(crate) fn hits_bind(d: &wgpu::Device, buffers: &[(wgpu::Buffer, u64, u64)]) -> wgpu::BindGroup {
    let bindings = hit_bindings(buffers);
    d.create_bind_group(&wgpu::BindGroupDescriptor {
        label: Some("hit buffers"),
        layout: &hits_layout(d),
        entries: &[entry(0, wgpu::BindingResource::BufferArray(&bindings))],
    })
}
/// Device features the hit buffer array needs (rt::require).
pub(crate) const HIT_BUFFER_FEATURES: wgpu::Features = wgpu::Features::BUFFER_BINDING_ARRAY
    .union(wgpu::Features::STORAGE_RESOURCE_BINDING_ARRAY)
    .union(wgpu::Features::SAMPLED_TEXTURE_AND_STORAGE_BUFFER_ARRAY_NON_UNIFORM_INDEXING)
    .union(wgpu::Features::PARTIALLY_BOUND_BINDING_ARRAY);
/// Path, ray GI, ray refraction and probes shade hit surfaces (hit.slang).
pub(crate) fn traces_hit_surfaces(scene: &Scene) -> bool {
    ray_refraction(scene) || other_hit_surfaces(scene)
}
/// Hit shading still needed after installed materials prove there is no solid glass.
pub(crate) fn other_hit_surfaces(scene: &Scene) -> bool {
    ray_indirect(scene) || scene.render.settings.integrator.reflections() == Some(vork_scene::Reflections::Ray) || scene.render.settings.integrator.is_path()
        || scene.render.settings.integrator.probe_volume().is_some()
}
/// The hit buffer array layout entry (`count` elements, partially bound).
pub(crate) fn hit_buffers_entry(binding: u32, stages: wgpu::ShaderStages) -> wgpu::BindGroupLayoutEntry {
    wgpu::BindGroupLayoutEntry {
        count: std::num::NonZeroU32::new(constants::RAY_HIT_BUFFERS),
        ..pipelines::buffer_entry(binding, stages, wgpu::BufferBindingType::Storage { read_only: true })
    }
}

/// Installed triangle-shadow permission, including automatic local lights.
pub(crate) fn traces_shadows(kind: &NodeKind) -> bool {
    kind.casts_shadows()
        && !matches!(kind, NodeKind::Light { shape: vork_scene::LightShape::Environment, .. })
}

// Reserve unknown environment exports and imported lights before compilation.
// Installed consumers refine this reservation against actual evaluated lights.
fn automatic_light_shadows(scene: &Scene) -> bool {
    fn possible(nodes: &[Node]) -> bool {
        nodes.iter().any(|node| (matches!(node.kind,
            NodeKind::Light { .. }) && node.kind.casts_shadows())
            || matches!(node.kind, NodeKind::Light { shape: vork_scene::LightShape::Environment, .. } | NodeKind::Asset { .. })
            || possible(&node.children))
    }
    scene.render.settings.integrator.shadow_method() == vork_scene::ShadowMethod::Auto
        && surface_transport_required(scene) && possible(&scene.nodes)
}
pub(crate) fn installed_shadow_rays(scene: &Scene, nodes: &[EvalNode]) -> bool {
    if scene.render.settings.integrator.shadow_method()!=vork_scene::ShadowMethod::Auto {return ray_shadows(scene);}
    scene.render.settings.integrator.subsurface_method().is_some()
        || (surface_transport_required(scene)
            && nodes.iter().any(|node| traces_shadows(&node.node.kind)))
}

/// Scene options that trace rays, as their scene paths.
fn options(scene: &Scene) -> Vec<String> {
    ray_options(scene, ray_refraction(scene))
}
pub(crate) fn ray_options(scene: &Scene, refraction: bool) -> Vec<String> {
    let mut out = Vec::new();
    if crate::catcher::has_mattes(scene) {out.push("node matte transport (is_holdout/is_shadow_catcher)".into());}
    if !scene.render.settings.integrator.is_path()
        && scene.render.settings.integrator.shadow_method() == vork_scene::ShadowMethod::Ray {
        out.push("ray-traced shadows".into());
    } else if automatic_light_shadows(scene) {
        out.push("automatic light shadows".into());
    }
    if scene.render.settings.integrator.is_path() {
        out.push("path transport".into());
    }
    if scene.render.settings.integrator.subsurface_method().is_some() {
        out.push("spatial subsurface scattering".into());
    }
    if scene.render.settings.integrator.reflections() == Some(vork_scene::Reflections::Ray) {
        out.push("glossy reflections".into());
    }
    if refraction {out.push("glass refraction".into());}
    if ray_indirect(scene) {
        out.push("diffuse indirect lighting".into());
    }
    if scene.render.settings.integrator.probe_volume().is_some() && surface_transport_required(scene) {
        out.push("retained indirect lighting".into());
    }
    out
}
/// Ray-traced diffuse indirect: install keeps hit attributes in the ray table.
pub(crate) fn ray_indirect(scene: &Scene) -> bool {
    scene.render.settings.integrator.indirect().is_some_and(|gi| gi.method == vork_scene::FastGiMethod::Ray)
}

// Groups, cameras and lights cannot receive surface transport. Imported and
// procedural geometry remain required/unknown; never infer absence from views
// or visibility, since captures and secondary rays can see other receivers.
fn surface_transport_required(scene:&Scene)->bool {
    fn any(nodes:&[vork_scene::v2::Node])->bool {
        nodes.iter().any(|node| !matches!(&node.kind,NodeKind::Node{} | NodeKind::Camera{..} | NodeKind::Light{..}) || any(&node.children))
    }
    any(&scene.nodes)
}

/// Automatic diffuse transport is independent of reflection and refraction.
/// Receiver queries integrate diffuse lighting, with retained irradiance supplying
/// further bounces when installed. Screen GI cannot supply offscreen transport.
pub(crate) fn resolve_indirect(scene:&mut Scene,features:wgpu::Features)->Result<()> {
    let required=surface_transport_required(scene);
    // Retained probe support is planned from CPU geometry. Arbitrary computed
    // streams can leave that support; the complete provider evaluates each
    // requested snapshot instead of reusing rest-space masks.
    fn computed_mesh(scene: &Scene, nodes: &[vork_scene::v2::Node]) -> bool {
        nodes.iter().any(|node| matches!(&node.kind, vork_scene::v2::NodeKind::Mesh { geometry, .. }
            if scene.geometry.get(geometry).is_some_and(|g| !matches!(g.topology,vork_scene::v2::Topology::Implicit) && crate::computed_geometry::dynamic(scene, g)))
            || computed_mesh(scene, &node.children))
    }
    if automatic_indirect_requested(scene) && scene.render.settings.integrator.probe_volume().is_some()
        && computed_mesh(scene, &scene.nodes) {
        promote_indirect_to_path(scene);
        return Ok(());
    }
    // An aggregate field cannot separate World receiver classes. Preserve the
    // scene's links with the complete per-receiver query provider instead.
    fn linked_world(nodes:&[vork_scene::v2::Node])->bool {
        nodes.iter().any(|n| matches!(&n.kind,NodeKind::Light {shape:vork_scene::LightShape::Environment,illuminates:Some(_),..}) || linked_world(&n.children))
    }
    let linked_world=linked_world(&scene.nodes) || scene.geometry.values().any(|g|matches!(g.topology,vork_scene::v2::Topology::Implicit));
    let Some(raster)=scene.render.settings.integrator.raster_mut() else {return Ok(())};
    let Some(gi)=raster.fast_gi.as_mut() else {return Ok(())};
    if gi.method!=vork_scene::FastGiMethod::Auto {return Ok(())}
    if !required {raster.fast_gi=None;raster.probes=None;return Ok(())}
    let queries=features.contains(wgpu::Features::EXPERIMENTAL_RAY_QUERY | HIT_BUFFER_FEATURES);
        ensure!(queries,"effect unavailable: diffuse indirect lighting needs complete scene queries; use a ray-query capable adapter, simplify the scene");
        if linked_world { raster.probes=None; }
        // Integrate the receiver hemisphere before displaying retained lighting.
        // Exact receiver-to-probe connections remain cache leak guards, not
        // point-light silhouettes projected directly onto the primary surface.
        gi.method=vork_scene::FastGiMethod::Ray;
    Ok(())
}

/// Keep the call's sample budget and denoise intent when retained transport
/// cannot represent the scene. Never substitute an unoccluded World fill.
pub(crate) fn promote_indirect_to_path(scene:&mut Scene) {
    let denoiser=scene.render.settings.integrator.raster().and_then(|r|r.denoiser.clone());
    // Primary-surface reconstruction cannot describe transported detail. Preserve
    // the call's OIDN opt-out when promoting glass or other path-only effects.
    scene.render.settings.reconstruct=false;
    scene.render.settings.integrator=vork_scene::Integrator::Path(vork_scene::PathIntegrator {denoiser,..Default::default()});
}

pub(crate) fn automatic_indirect_requested(scene:&Scene)->bool {
    scene.render.settings.integrator.raster().is_some_and(|r|r.fast_gi.as_ref().is_some_and(|gi|gi.method==vork_scene::FastGiMethod::Auto))
        && surface_transport_required(scene)
}

/// Conservative preflight before assets/programs are installed. Imported materials
/// and program outputs are unknown here; native OpenPBR uses the normal compiler's
/// transmission capability, including animated and textured weights.
pub(crate) fn may_refract(scene: &Scene) -> bool {
    fn assets(nodes: &[Node]) -> bool {
        nodes.iter().any(|n| matches!(n.kind, NodeKind::Asset { .. }) || assets(&n.children))
    }
    if assets(&scene.nodes) {return true;}
    let Ok(animated) = materials::animated_inputs(scene) else {return true;};
    scene.materials.iter().any(|(name, material)| {
        if material.program != "std/openpbr" {return true;}
        let inputs = animated.get(name).cloned().unwrap_or_default();
        materials::openpbr_values(scene, Some(name), &inputs, |_| Ok(0))
            .map_or(true, |m|m.transmissive)
    })
}

/// Device creation precedes compiled program capabilities. Reserve queries for
/// possible solid SSS or RGB connections; installation refines unknown programs.
pub(crate) fn possible_transport_queries(scene: &Scene) -> bool {
    let Ok(animated)=materials::animated_inputs(scene) else {return true;};
    for (name,material) in &scene.materials {
        if material.program!="std/openpbr" {return true;}
        let inputs=animated.get(name).cloned().unwrap_or_default();
        let Ok(record)=materials::openpbr_values(scene,Some(name),&inputs,|_|Ok(0)) else {return true;};
        if record.spatial_subsurface() {return true;}
    }
    may_refract(scene)
}

/// Thin and solid camera interfaces both need scene boundary transport.
pub(crate) fn automatic_refraction(scene: &Scene) -> bool {
    scene.render.settings.integrator.raster().is_some_and(|r|r.refraction == vork_scene::Refraction::Auto) && may_refract(scene)
}
pub(crate) fn automatic_refraction_supported(_device_type: wgpu::DeviceType, features: wgpu::Features) -> bool {
    // Complete interface transport depends on capabilities, including software
    // queries; a CPU classification cannot strand it after public overrides retire.
    features.contains(wgpu::Features::EXPERIMENTAL_RAY_QUERY | HIT_BUFFER_FEATURES)
}

/// Resolve the automatic technique before requirements, prewarm and installation.
/// Explicit ray remains an error on unsupported devices; screen is always retained.
pub(crate) fn resolve_refraction(scene: &mut Scene, device_type: wgpu::DeviceType, features: wgpu::Features) {
    if !scene.render.settings.integrator.raster().is_some_and(|r| r.refraction == vork_scene::Refraction::Auto) {return;}
    let transmission = may_refract(scene);
    let ray = automatic_refraction(scene) && automatic_refraction_supported(device_type, features);
    if let Some(raster) = scene.render.settings.integrator.raster_mut() {
        if raster.refraction == vork_scene::Refraction::Auto {
            raster.refraction = if !transmission {vork_scene::Refraction::Environment}
                else if ray {vork_scene::Refraction::Ray} else {vork_scene::Refraction::Screen};
        }
    }
}

pub(crate) fn ray_refraction(scene: &Scene) -> bool {
    scene.render.settings.integrator.raster().is_some_and(|r|r.refraction == vork_scene::Refraction::Ray)
}

/// Resolve the authored automatic reflection technique once, before planning.
/// Adapter admission already guarantees ray queries; scene absence disables work.
pub(crate) fn resolve_reflections(scene: &mut Scene) {
    let required=surface_transport_required(scene);
    if let Some(raster) = scene.render.settings.integrator.raster_mut()
        && raster.reflections == vork_scene::Reflections::Auto
    {
        if !required {
            raster.reflections=vork_scene::Reflections::Environment;
            return;
        }
        // Neither World nor the directional capture currently certifies the
        // filtered lobe's local visibility/radiance residual. Unknown error
        // cannot qualify an approximation at any roughness, including one.
        // Keep sampling instead of turning roughness into a correctness limit.
        raster.reflections = vork_scene::Reflections::Ray;
    }
}

/// Automatic transport requests the optional query capability during startup;
/// only the resolved scene determines whether installation needs an AS.
pub(crate) fn automatic_reflections_requested(scene: &Scene) -> bool {
    scene.render.settings.integrator.reflections() == Some(vork_scene::Reflections::Auto)
        && surface_transport_required(scene)
}

/// Any ray technique: the install builds acceleration structures.
pub(crate) fn uses_rays(scene: &Scene) -> bool {
    installed_rays(scene, ray_refraction(scene))
}
/// Refine conservative preflight after imported/program material capabilities exist.
pub(crate) fn installed_rays(scene: &Scene, refraction: bool) -> bool {
    !ray_options(scene, refraction).is_empty()
}
/// Ray AO is required when authored or keyed strength can activate it.

/// Ray-traced light shadows: the forward shader variant reads the TLAS.
pub(crate) fn ray_shadows(scene: &Scene) -> bool {
    automatic_light_shadows(scene)
        || scene.render.settings.integrator.shadow_method() == vork_scene::ShadowMethod::Ray
        || scene.render.settings.integrator.subsurface_method().is_some()
}

/// Validate opacity inputs against the transport actually installed, including
/// capability-selected shadows on imported lights.
pub(crate) fn normalize_materials(scene: &mut Scene) {
    if !uses_rays(scene) { return; }
    let mut discarded=std::collections::BTreeSet::new();
    for (name, material) in &mut scene.materials {
        for input in ["geometry_opacity", "alpha_cutoff"] {
            if (input!="alpha_cutoff" || material.program=="std/openpbr") && matches!(material.inputs.get(input), Some(vork_scene::v2::Input::Attribute(_))) {
                if material.program=="std/openpbr" {
                    crate::warnings::dropped("ray_opacity_attribute", serde_json::json!({"material":name,"input":input,"binding":material.inputs.get(input)}), format!("warning: material {name}: ignored named {input} attribute for ray visibility; using the program default"));
                    material.inputs.remove(input);
                } else {
                    crate::warnings::dropped("ray_surface_attribute", serde_json::json!({"material":name,"surface":material,"input":input,"tracks":scene.animation.iter().flat_map(|layer|layer.tracks.iter().flatten()).filter(|track|matches!(track.path.as_slice(),[root,target,..] if root=="materials" && target==name)).collect::<Vec<_>>()}), format!("warning: material {name}: ignored custom surface and its material animation with named {input} attribute for ray visibility; using default OpenPBR surface"));
                    *material=serde_json::from_value(serde_json::json!({})).expect("default material");
                    discarded.insert(name.clone());
                    break;
                }
            }
        }
    }
    for layer in &mut scene.animation {
        if let Some(tracks)=&mut layer.tracks {tracks.retain(|t|!matches!(t.path.as_slice(),[root,name,..] if root=="materials" && discarded.contains(name)));}
    }
}

/// Production requires a ray-capable GPU. Test builds may exercise the same
/// complete ray pipeline on software Vulkan; they never substitute screen transport.
pub(crate) fn require_adapter(info: &wgpu::AdapterInfo, features: wgpu::Features) -> Result<()> {
    let software_test = cfg!(any(test, feature = "test-support"));
    ensure!(features.contains(wgpu::Features::EXPERIMENTAL_RAY_QUERY | HIT_BUFFER_FEATURES)
        && (software_test || info.device_type != wgpu::DeviceType::Cpu),
        "unsupported GPU: {} ({:?}); vork requires a modern GPU with hardware ray tracing and storage buffer arrays (Apple Silicon Metal or recent NVIDIA Vulkan); software adapters are supported only by test builds with complete ray-query support",
        info.name, info.backend);
    Ok(())
}

/// Ray techniques are explicit scene choices; a device without ray queries is an
/// error naming the option, never a silent fallback to another technique.
pub(crate) fn require(r: &Renderer, scene: &Scene) -> Result<()> {
    let supported = r
        .device
        .features()
        .contains(wgpu::Features::EXPERIMENTAL_RAY_QUERY);
    let adapter = format!("{} ({:?})", r.adapter_info.name, r.adapter_info.backend);
    if let Some(message) = missing(scene, supported, &adapter) {
        bail!(message);
    }
    ensure!(
        !traces_hit_surfaces(scene) || r.device.features().contains(HIT_BUFFER_FEATURES),
        "{} reads hit geometry through storage buffer arrays ({HIT_BUFFER_FEATURES:?}); adapter {adapter} lacks them",
        options(scene).join(", ")
    );
    Ok(())
}
fn missing(scene: &Scene, supported: bool, adapter: &str) -> Option<String> {
    let chosen = options(scene);
    (!supported && !chosen.is_empty()).then(|| {
        let effect=if ray_indirect(scene) {"diffuse indirect lighting; "} else {""};
        format!(
            "effect unavailable: {effect}{} needs hardware ray queries (wgpu EXPERIMENTAL_RAY_QUERY); adapter {adapter} has none; use a ray-query capable adapter",
            chosen.join(", ")
        )
    })
}

fn triangles(
    alpha_tested: bool,
    vertex_count: u32,
    index_count: u32,
) -> wgpu::BlasTriangleGeometrySizeDescriptor {
    wgpu::BlasTriangleGeometrySizeDescriptor {
        vertex_format: wgpu::VertexFormat::Float32x3,
        vertex_count,
        index_format: Some(wgpu::IndexFormat::Uint32),
        index_count: Some(index_count),
        // Alpha-tested draws yield candidates the shaders test against the
        // material cutoff; every other caster is opaque.
        flags: if alpha_tested {
            wgpu::AccelerationStructureGeometryFlags::NO_DUPLICATE_ANY_HIT_INVOCATION
        } else {
            wgpu::AccelerationStructureGeometryFlags::OPAQUE
        },
    }
}
fn blas(
    d: &wgpu::Device,
    label: &str,
    size: &wgpu::BlasTriangleGeometrySizeDescriptor,
) -> wgpu::Blas {
    blas_geometries(d, label, std::slice::from_ref(size))
}
fn blas_geometries(d: &wgpu::Device, label: &str, sizes: &[wgpu::BlasTriangleGeometrySizeDescriptor]) -> wgpu::Blas {
    d.create_blas(
        &wgpu::CreateBlasDescriptor {
            label: Some(label),
            flags: BUILD_FLAGS,
            update_mode: wgpu::AccelerationStructureUpdateMode::Build,
        },
        wgpu::BlasGeometrySizeDescriptors::Triangles {
            descriptors: sizes.to_vec(),
        },
    )
}
fn geometry<'a>(
    size: &'a wgpu::BlasTriangleGeometrySizeDescriptor,
    vertices: &'a wgpu::Buffer,
    first_vertex: u32,
    stride: u64,
    indices: &'a wgpu::Buffer,
    first_index: u32,
) -> wgpu::BlasGeometries<'a> {
    wgpu::BlasGeometries::TriangleGeometries(vec![wgpu::BlasTriangleGeometry {
        size,
        vertex_buffer: vertices,
        first_vertex,
        vertex_stride: stride,
        index_buffer: Some(indices),
        first_index: Some(first_index),
        transform_buffer: None,
        transform_buffer_offset: None,
    }])
}

/// Install-owned static BLAS, shared by every frame slot, and the ray table:
/// RAY_SLOT_WORDS per TLAS instance (first corner word, or NO_ALPHA when opaque;
/// the material record; first hit-triangle word, or NO_ALPHA; the first slot
/// points to the optional shadow-containment table), then TEXCOORD_0,
/// TEXCOORD_1 and vertex-colour alpha of each index of the alpha-tested draws
/// (five words per corner), then the hit triangles of `indirect.method: ray` scenes.
pub(crate) struct Rays {
    /// All installed BLAS geometry accepts opaque intersections directly.
    pub(crate) opaque: bool,
    /// Offset of the path emitter topology in the shared ray table.
    pub(crate) emitters: u32,
    pub(crate) probe_emitters: bool,
    pub(crate) emitter_weights: Option<crate::emitter_weights::Plan>,
    /// Offset of per-instance solid-boundary capability descriptors.
    pub(crate) boundaries: u32,
    /// Per-object solid identity for raster camera interfaces.
    pub(crate) object_boundaries: u32,
    /// Offset of per-instance authored mesh identities for spatial BSSRDFs.
    pub(crate) subsurface: u32,
    /// Offset of per-solid records (constants::PATH_SOLID_WORDS each).
    pub(crate) occupancy_solids: u32,
    /// Offset of the path camera film inverse CDF in the shared ray table.
    pub(crate) film_filter: u32,
    /// Per draw; None for deformed draws, whose BLAS are frame-private.
    blas: Vec<Option<wgpu::Blas>>,
    visibility_groups: Vec<VisibilityGroup>,
    /// Dense TLAS slots represented by shared opaque visibility hierarchies.
    #[cfg(test)]
    grouped_instances: Vec<bool>,
    /// Ray topology; opacity headers use this same CandidateInstanceIndex order.
    instances: Vec<(usize,u32)>,
    /// Every frame slot uses the installed topology and descriptor ABI.
    placement_pipeline: std::sync::OnceLock<wgpu::ComputePipeline>,
    /// Per draw: candidates are alpha-tested (non-opaque BLAS geometry).
    alpha_tested: Vec<bool>,
    shadow_solids: Vec<bool>,
    shadow_bounds: Option<crate::shadow_containment::Plan>,
    pub(crate) alpha: wgpu::Buffer,
    /// The hit buffer array's elements (hit records index them).
    pub(crate) hit_buffers: Vec<HitBuffer>,
    pub(crate) implicit: [u32;4],
}
/// Visibility-only opaque geometry needs neither primitive material IDs nor hit
/// attributes. Static instances with identical transforms, masks, groups and material sidedness can
/// share one triangle hierarchy without changing the rays' intersection space.
struct VisibilityGroup { slot: usize, blas: wgpu::Blas }

/// Material bindings are final only after geometry reuse and primitive groups.
/// Retain UV/alpha corners here so an opaque first binding cannot make later
/// transparent bindings opaque to ray queries. Geometry buffers remain shared.
pub(crate) fn prepare_coverage(draws: &mut [install::Draw], materials: &[Material]) -> Result<()> {
    let mut shared = std::collections::HashMap::new();
    for draw in draws {
        let material = &materials[draw.material];
        if !material.surface_coverage && !material.transmissive {
            draw.ray_corners = None;
            continue;
        }
        let geometry = draw.exit_geometry.as_ref().context("ray opacity needs retained geometry")?;
        let key = (std::sync::Arc::as_ptr(geometry), draw.primitive_start, draw.count);
        draw.ray_corners = Some(shared.entry(key).or_insert_with(|| {
            let start = draw.primitive_start as usize * 3;
            std::sync::Arc::new(geometry.indices[start..start + draw.count as usize].iter().map(|&i| {
                let v = &geometry.vertices[i as usize];
                [v.TEXCOORD_0[0], v.TEXCOORD_0[1], v.TEXCOORD_1[0], v.TEXCOORD_1[1], v.COLOR_0[3]]
            }).collect::<Vec<_>>())
        }).clone());
    }
    Ok(())
}
const NO_ALPHA: u32 = u32::MAX;
/// The decoupled camera's draw table (decoupled.slang CameraGeometry): per draw,
/// RAY_SLOT_WORDS words whose third addresses its hit record, then the records.
/// Camera slots read their triangles through the records ray hits use, with
/// the draw index in place of a TLAS instance.
pub(crate) fn draw_table(r: &Renderer, draws: &[install::Draw]) -> Result<(wgpu::Buffer, Vec<HitBuffer>)> {
    let (displaced, _) = crate::displacement::page_layout(draws, &r.device.limits())?;
    let slot_words = constants::RAY_SLOT_WORDS;
    // Exit-tree buffer index, reserved, hit record; one slot even without draws.
    let mut words = vec![NO_ALPHA; draws.len().max(1) * slot_words];
    let mut buffers = Vec::new();
    for (i, draw) in draws.iter().enumerate() {
        words[slot_words * i + 2] = words.len() as u32;
        words.extend(hit_record(draw, &mut buffers, draw.evaluation_leader().or_else(||draw.computed.then_some(i)), displaced[i]));
        if let Some(field) = &draw.implicit {
            words[slot_words * i + 1] = words.len() as u32;
            words.extend(field.dims);
            words.push(field.spans.len() as u32);
            for (buffer, span) in &field.spans {
                let slot = intern_buffer(&mut buffers, HitBuffer::Static(buffer.clone()));
                words.extend([slot, span.offset, span.first, span.count]);
            }
            words.push(intern_buffer(&mut buffers,HitBuffer::Static(field.acceleration.buffer.clone())));
        }
        if let Some(tree) = &draw.exit_bvh {
            words[slot_words * i] = intern_buffer(&mut buffers, HitBuffer::Static(tree.clone()));
        }
    }
    ensure!(
        buffers.len() <= constants::RAY_HIT_BUFFERS as usize,
        "camera hits address {} geometry buffers; the hit buffer array holds {}",
        buffers.len(),
        constants::RAY_HIT_BUFFERS
    );
    admit_static_hit_buffers(&r.device.limits(), &buffers)?;
    crate::gpu_memory::storage_binding(&r.device.limits(), "camera draw table", words.len() as u64 * 4)?;
    let table = init(&r.device, "decoupled draw table", bytemuck::cast_slice(&words), wgpu::BufferUsages::STORAGE);
    // A binding array needs one element even without draws.
    if buffers.is_empty() {
        buffers.push(HitBuffer::Static(table.clone()));
    }
    Ok((table, buffers))
}
fn alpha_table(
    r: &Renderer,
    draws: &[install::Draw],
    instances: &[(usize, u32)],
    hits: bool,
    path: bool,
    buffers: &mut Vec<HitBuffer>,
    emitters: &[u32],
    implicit_sources: &[u32],
    boundary_ids: &[u32],
    subsurface_ids: &[u32],
    solids: &[crate::passes::path::PathSolid],
    shadow_solids: &[bool],
    solid_owners: &[u32],
    shadow_bounds: Option<&mut crate::shadow_containment::Plan>,
) -> Result<(wgpu::Buffer, u32, u32, u32, u32, u32, u32, [u32;4])> {
    let (displaced, _) = crate::displacement::page_layout(draws, &r.device.limits())?;
    let slot_words = constants::RAY_SLOT_WORDS;
    let mut words: Vec<u32> = instances
        .iter()
        .flat_map(|&(draw, _)| [NO_ALPHA, draws[draw].material as u32, NO_ALPHA, NO_ALPHA])
        .collect();
    words.resize(words.len().max(slot_words), NO_ALPHA);
    let mut first = std::collections::HashMap::new();
    for (slot, &(draw, _)) in instances.iter().enumerate() {
        let Some(corners) = &draws[draw].ray_corners else {
            continue;
        };
        let start = *first
            .entry(std::sync::Arc::as_ptr(corners))
            .or_insert_with(|| words.len() as u32);
        if start == words.len() as u32 {
            words.extend(corners.iter().flatten().map(|v| v.to_bits()));
        }
        words[slot_words * slot] = start;
    }
    // Hit records, one per draw: aliases of a deformation share its leader's pose.
    let mut records = std::collections::HashMap::new();
    for (slot, &(draw, _)) in instances.iter().enumerate().filter(|_| hits) {
        let start = *records.entry(draw).or_insert_with(|| {
            let start = words.len() as u32;
            let leader = draws[draw].evaluation_leader().or_else(||draws[draw].computed.then_some(draw));
            words.extend(hit_record(&draws[draw], buffers, leader, displaced[draw]));
            start
        });
        words[slot_words * slot + 2] = start;
    }
    ensure!(
        buffers.len() <= constants::RAY_HIT_BUFFERS as usize,
        "ray hits address {} geometry buffers; the hit buffer array holds {}",
        buffers.len(),
        constants::RAY_HIT_BUFFERS
    );
    let implicit_offset=words.len() as u32;
    let fields:Vec<_>=instances.iter().enumerate().filter(|(_, (d,_))|draws[*d].implicit.is_some()).collect();
    words.resize(words.len()+fields.len()*3,0);
    for (row,&(instance,&(draw,object))) in fields.iter().enumerate() {
        let field=draws[draw].implicit.as_ref().unwrap();
        let descriptor=words.len() as u32;
        words[implicit_offset as usize+row*3..implicit_offset as usize+row*3+3].copy_from_slice(&[instance as u32,object,descriptor]);
        words.extend(field.dims);
        words.push(field.spans.len() as u32);
        for (buffer,span) in &field.spans {
            let slot=intern_buffer(buffers,HitBuffer::Static(buffer.clone()));
            words.extend([slot,span.offset,span.first,span.count]);
        }
        words.push(intern_buffer(buffers,HitBuffer::Static(field.acceleration.buffer.clone())));
    }
    admit_static_hit_buffers(&r.device.limits(), buffers)?;
    ensure!(buffers.len()<=constants::RAY_HIT_BUFFERS as usize,"implicit grids exceed hit-buffer capacity");
    let implicit=[implicit_offset,fields.len() as u32,words.len() as u32,implicit_sources.len() as u32];
    words.extend_from_slice(implicit_sources);
    let emitter_offset = words.len() as u32;
    words.extend_from_slice(emitters);
    let boundary_offset = words.len() as u32;
    if !boundary_ids.is_empty() {
        words.extend(instances.iter().map(|&(_, object)| boundary_ids[object as usize]));
    }
    let object_boundary_offset=words.len() as u32;
    words.extend_from_slice(boundary_ids);
    let subsurface_offset=words.len() as u32;
    if !subsurface_ids.is_empty() {
        words.extend(instances.iter().map(|&(_,object)|subsurface_ids[object as usize]));
    }
    let bounds_offset = words.len() as u32;
    words.extend(solids.iter().flat_map(|s| -> [u32; constants::PATH_SOLID_WORDS] {
        [s.lo.x.to_bits(), s.lo.y.to_bits(), s.lo.z.to_bits(), s.hi.x.to_bits(), s.hi.y.to_bits(), s.hi.z.to_bits(), s.row]
    }));
    // The first slot publishes only potentially absorbing solid identities.
    // Clear/depth-zero interfaces need no occupancy query beyond an emitter.
    let eligible=instances.iter().zip(shadow_solids).filter_map(|(&(_,object),&absorbing)| {
        let solid=solid_owners.get(object as usize).copied().unwrap_or(NO_ALPHA);
        (absorbing && solid!=NO_ALPHA).then_some(solid)
    }).collect::<std::collections::BTreeSet<_>>();
    if !eligible.is_empty() {
        let identities=words.len() as u32;
        words.extend(instances.iter().map(|&(_,object)|solid_owners.get(object as usize).copied().unwrap_or(NO_ALPHA)));
        let unbounded:Vec<_>=eligible.into_iter().filter(|&id|solids[id as usize].shadow_bounds.is_none()).collect();
        let (buffer,count)=if let Some(plan)=shadow_bounds {
            plan.slot=intern_buffer(buffers,HitBuffer::Static(plan.template.clone()));
            (plan.slot,plan.count)
        } else {(NO_ALPHA,0)};
        ensure!(buffers.len()<=constants::RAY_HIT_BUFFERS as usize,"shadow bounds exceed ray hit-buffer capacity");
        let table=words.len() as u32;
        words.extend([unbounded.len() as u32,bounds_offset,identities,buffer,count]);
        words.extend(unbounded);
        words[constants::RAY_SHADOW_TABLE_WORD]=table;
    }
    let film_filter = words.len() as u32;
    if path { words.extend(crate::sampling::path_filter_table().iter().map(|v| v.to_bits())); }
    let bytes = words.len() as u64 * 4;
    let limits = r.device.limits();
    ensure!(
        bytes <= u64::from(limits.max_storage_buffer_binding_size)
            && bytes <= limits.max_buffer_size,
        "ray table needs {bytes} bytes; device storage binding limit is {}",
        limits.max_storage_buffer_binding_size
    );
    let table = init(&r.device, "ray table", bytemuck::cast_slice(&words), wgpu::BufferUsages::STORAGE);
    if buffers.is_empty() {
        buffers.push(HitBuffer::Static(table.clone()));
    }
    Ok((table, emitter_offset, boundary_offset, subsurface_offset, bounds_offset, film_filter, object_boundary_offset, implicit))
}
// Intern geometry sets independently of their instance transforms. Repeated
// opaque assemblies retain shared BLAS instead of duplicating geometry per instance.
fn geometry_key(draw: &install::Draw) -> (wgpu::Buffer,wgpu::Buffer,u64,u64,u32,u32,u64,bool) {
    (draw.vertices.clone(),draw.indices.clone(),draw.vertex_offset,draw.index_offset,
        draw.count,draw.vertex_count,draw.layout.vertex_stride(),draw.ray_corners.is_some())
}
/// A shared position stream still needs separate BLAS for distinct topology or
/// coverage flags. Static geometry retains its installed ownership separately.
fn evaluated_owners(draws: &[install::Draw]) -> Vec<usize> {
    let mut geometries = std::collections::HashMap::new();
    draws.iter().enumerate().map(|(i, draw)| {
        if !draw.evaluated() { return i; }
        *geometries.entry((draw.evaluation_leader().unwrap_or(i), geometry_key(draw))).or_insert(i)
    }).collect()
}
fn triangles_size(draw: &install::Draw) -> wgpu::BlasTriangleGeometrySizeDescriptor {
    triangles(draw.ray_corners.is_some(),draw.vertex_count,draw.count)
}
impl Rays {
    pub(crate) fn new(
        r: &Renderer,
        draws: &[install::Draw],
        instances: &[(usize, u32)],
        objects: &[Object],
        static_casters: &[(usize, u32)],
        hits: bool,
        materials: &[Material],
        integrator: &vork_scene::Integrator,
        boundary_ids: &[u32],
        solid_owners: &[u32],
        subsurface_ids: &[u32],
        solids: &[crate::passes::path::PathSolid],
        medium_sources: bool,
    ) -> Result<Self> {
        let path=integrator.is_path();
        ensure!(
            objects.len() as u64 <= u64::from(constants::RAY_MAX_INSTANCE_INDEX) + 1,
            "{} object instances exceed the 24-bit ray instance index", objects.len()
        );
        let d = &r.device;
        let mut pending: Vec<(Vec<(usize,wgpu::BlasTriangleGeometrySizeDescriptor)>,wgpu::Blas)> = Vec::new();
        let mut unique = std::collections::HashMap::new();
        let mut visibility_groups = Vec::new();
        let mut grouped_instances = vec![false;instances.len()];
        if !hits && integrator.subsurface_method().is_none() {
            let eligible: std::collections::HashSet<_> = static_casters.iter().copied().collect();
            let mut groups = std::collections::BTreeMap::new();
            for (slot,&(draw,object)) in instances.iter().enumerate() {
                let source=&draws[draw];
                if !eligible.contains(&(draw,object)) || source.evaluated() || source.ray_corners.is_some() {continue;}
                let value=&objects[object as usize];
                let mask=if collapsed(value.model) {0} else {value.metadata[1]};
                let key=(value.model.to_cols_array().map(f32::to_bits),value.metadata[0],mask,!materials[source.material].transparent,materials[source.material].double_sided);
                groups.entry(key).or_insert_with(Vec::new).push((slot,draw,object));
            }
            let limits=d.limits();
            let primitive_limit=u64::from(limits.max_blas_primitive_count).min(constants::RAY_BLAS_BATCH_TRIANGLES);
            for members in groups.values() {
                let mut start=0;
                while start<members.len() {
                    let mut end=start;let mut triangles=0u64;
                    while end<members.len() {
                        let count=u64::from(draws[members[end].1].count/3);
                        if end>start && ((end-start) as u32==limits.max_blas_geometry_count || triangles+count>primitive_limit) {break;}
                        triangles+=count;end+=1;
                    }
                    let records:Vec<_>=members[start..end].iter().map(|&(slot,draw,_)| {
                        grouped_instances[slot]=true;
                        (draw,triangles_size(&draws[draw]))
                    }).collect();
                    let key:Vec<_>=records.iter().map(|(draw,_)|geometry_key(&draws[*draw])).collect();
                    let built=unique.entry(key).or_insert_with(|| {
                        let sizes:Vec<_>=records.iter().map(|(_,size)|size.clone()).collect();
                        let built=blas_geometries(d,"static opaque visibility BLAS",&sizes);
                        pending.push((records,built.clone()));built
                    }).clone();
                    visibility_groups.push(VisibilityGroup {slot:members[start].0,blas:built});
                    start=end;
                }
            }
        }
        let mut primitive_needed=vec![false;draws.len()];
        for (slot,&(draw,_)) in instances.iter().enumerate() {primitive_needed[draw]|=!grouped_instances[slot];}
        let blas = draws.iter().enumerate().map(|(index,draw)| {
            if draw.evaluated() || !primitive_needed[index] {return None;}
            let key=vec![geometry_key(draw)];
            Some(unique.entry(key).or_insert_with(|| {
                let size=triangles_size(draw);
                let built=blas(d,"static primitive BLAS",&size);
                pending.push((vec![(index,size)],built.clone()));built
            }).clone())
        }).collect();
        // Bounded submissions keep build scratch small (the M5 forest spike OOM):
        // each batch's scratch is released before the next batch allocates its own.
        let mut start = 0;
        let mut previous = None;
        while start < pending.len() {
            if let Some(submission) = previous.take() {
                r.wait(Some(submission))?;
            }
            let mut end = start;
            let mut batch = 0u64;
            while end < pending.len()
                && (end == start || batch < constants::RAY_BLAS_BATCH_TRIANGLES)
            {
                batch += pending[end].0.iter().map(|(_,size)|u64::from(size.index_count.unwrap_or(0)/3)).sum::<u64>();
                end += 1;
            }
            let entries: Vec<_> = pending[start..end]
                .iter()
                .map(|(records,blas)| wgpu::BlasBuildEntry {
                    blas,
                    geometry: wgpu::BlasGeometries::TriangleGeometries(records.iter().map(|(index,size)| {
                        let draw=&draws[*index];let stride=draw.layout.vertex_stride();
                        wgpu::BlasTriangleGeometry {
                            size,vertex_buffer:&draw.vertices,first_vertex:(draw.vertex_offset/stride) as u32,vertex_stride:stride,
                            index_buffer:Some(&draw.indices),first_index:Some((draw.index_offset/4) as u32),
                            transform_buffer:None,transform_buffer_offset:None,
                        }
                    }).collect()),
                })
                .collect();
            let mut encoder = d.create_command_encoder(&wgpu::CommandEncoderDescriptor {
                label: Some("static BLAS build"),
            });
            encoder.build_acceleration_structures(entries.iter(), std::iter::empty());
            previous = Some(crate::command_finish::Segments::submit(&r.queue, encoder));
            start = end;
        }
        // CandidateInstanceIndex addresses this dense TLAS order, not the
        // original raster instance list. Keep alpha headers in the same order.
        let mut leaders:std::collections::BTreeMap<_,_>=visibility_groups.iter().enumerate().map(|(i,g)|(g.slot,i)).collect();
        let mut ray_instances=Vec::new();let mut ray_grouped=Vec::new();
        for (slot,&instance) in instances.iter().enumerate() {
            if let Some(group)=leaders.remove(&slot) {
                visibility_groups[group].slot=ray_instances.len();
            } else if grouped_instances[slot] {continue;}
            ray_instances.push(instance);ray_grouped.push(grouped_instances[slot]);
        }
        let mut hit_buffers = Vec::new();
        let probe_emitters = integrator.probe_volume().is_some()
            && crate::emitters::has_sources(draws,instances,materials,true);
        let gi_emitters=integrator.raster().is_some_and(|r|r.fast_gi.as_ref().is_some_and(|g|g.method==vork_scene::FastGiMethod::Ray))
            && crate::emitters::has_sources(draws,instances,materials,true);
        let topology = if path || probe_emitters || gi_emitters || medium_sources || integrator.reflections()==Some(vork_scene::Reflections::Ray) {
            crate::emitters::emitter_topology(draws, &ray_instances, materials, !path)?
        } else { vec![0, 0, 0] };
        let absorbing=ray_instances.iter().filter_map(|&(draw,object)| {
            let solid=solid_owners.get(object as usize).copied().unwrap_or(NO_ALPHA);
            (draws[draw].implicit.is_none() && materials[draws[draw].material].solid_absorption && solid!=NO_ALPHA).then_some(solid)
        }).collect::<std::collections::BTreeSet<_>>();
        // All faces of a potentially absorbing solid participate in nearest-boundary
        // discovery, including clear and opaque material groups of that solid.
        let shadow_solids=ray_instances.iter().map(|&(_,object)|absorbing.contains(&solid_owners.get(object as usize).copied().unwrap_or(NO_ALPHA))).collect::<Vec<_>>();
        let mut shadow_bounds=crate::shadow_containment::Plan::new(r,solids,&absorbing,objects,draws,solid_owners)?;
        let (alpha, emitters, boundaries, subsurface, occupancy_solids, film_filter, object_boundaries, implicit) = alpha_table(r, draws, &ray_instances, hits, path, &mut hit_buffers, &topology, &crate::emitters::implicit_sources(draws,&ray_instances,materials), boundary_ids, subsurface_ids, solids, &shadow_solids, solid_owners, shadow_bounds.as_mut())?;
        Ok(Self {
            shadow_solids,
            shadow_bounds,
            opaque: draws.iter().all(|draw| draw.ray_corners.is_none()),
            emitters,
            probe_emitters,
            emitter_weights:if path || probe_emitters || gi_emitters || medium_sources {crate::emitter_weights::Plan::new(r,emitters,topology[1])?} else {None},
            boundaries,
            object_boundaries,
            subsurface,
            occupancy_solids,
            film_filter,
            blas,
            visibility_groups,
            #[cfg(test)]
            grouped_instances:ray_grouped,
            instances:ray_instances,
            placement_pipeline: Default::default(),
            alpha_tested: draws.iter().map(|d| d.ray_corners.is_some()).collect(),
            alpha,
            hit_buffers,
            implicit,
        })
    }
}

/// Frame-slot TLAS over every draw instance, plus BLAS of deformed streams.
pub(crate) struct FrameRays {
    shadow_bounds:Option<crate::shadow_containment::Slot>,
    pub(crate) emitter_weights:Option<crate::emitter_weights::Slot>,
    pub(crate) tlas: wgpu::Tlas,
    placement: Option<crate::gpu_tlas::Placement>,
    placement_revision: u64,
    #[cfg(test)]
    pub(crate) builds: u32,
    /// This slot's hit buffer array (Rays::hit_buffers with deformed ranges
    /// resolved to its deform pool), as (buffer, offset, size).
    pub(crate) hit_buffers: Vec<(wgpu::Buffer, u64, u64)>,
    /// Per draw: the size and BLAS built from this slot's deformed output.
    deformed: Vec<Option<(wgpu::BlasTriangleGeometrySizeDescriptor, wgpu::Blas)>>,
}
impl Rays {
    pub(crate) fn dynamic_shadow_bounds(&self)->bool {self.shadow_bounds.as_ref().is_some_and(|p|p.dynamic())}
}
impl FrameRays {
    pub(crate) fn prepare_shadow_bounds(&self,s:&InstalledScene,local:&[(Vec3,Vec3)],changes:&mut values::ChangeTracker) {
        if let (Some(plan),Some(slot))=(&s.rays.as_ref().unwrap().shadow_bounds,&self.shadow_bounds) {plan.upload(slot,local,changes);}
    }
    /// Resolve the hit buffer array against this slot's deformation outputs.
    pub(crate) fn resolve_hit_buffers(&mut self, s: &InstalledScene, deforms: &[Option<EvaluatedGeometry>]) {
        let Some(installed) = s.rays.as_ref() else { return };
        self.hit_buffers = resolve_hit_buffers(&installed.hit_buffers, deforms);
        if let (Some(plan),Some(slot))=(&installed.shadow_bounds,&self.shadow_bounds) {
            self.hit_buffers[plan.slot as usize]=(slot.buffer.clone(),0,slot.buffer.size());
        }
    }
    /// The hit-buffer group of compute kernels (rt::hits_layout).
    pub(crate) fn hits_bind(&self, d: &wgpu::Device) -> wgpu::BindGroup {
        hits_bind(d, &self.hit_buffers)
    }
    /// The hit buffer array binding; unused slots stay unbound (partially bound).
    pub(crate) fn hit_bindings(&self) -> Vec<wgpu::BufferBinding<'_>> {
        hit_bindings(&self.hit_buffers)
    }

    pub(crate) fn new(s: &InstalledScene, r: &Renderer, objects: &wgpu::Buffer) -> Result<Option<Self>> {
        let d=&r.device;
        let Some(installed) = s.rays.as_ref() else {return Ok(None);};
        // Evaluated positions can be shared by draws with different index ranges.
        // Own BLAS by the complete geometry identity, not just the pose leader.
        let owners = evaluated_owners(&s.draws);
        let deformed: Vec<Option<(wgpu::BlasTriangleGeometrySizeDescriptor, wgpu::Blas)>> = s
            .draws
            .iter()
            .zip(&installed.alpha_tested)
            .enumerate()
            .map(|(i, (draw, &alpha_tested))| {
                if !draw.evaluated() || owners[i] != i {return None;}
                let size = triangles(alpha_tested, draw.vertex_count, draw.count);
                let built = blas(d, "deformed primitive BLAS", &size);
                Some((size, built))
            })
            .collect();
        let tlas = d.create_tlas(&wgpu::CreateTlasDescriptor {
            label: Some("scene TLAS"),
            max_instances: installed.instances.len().max(1) as u32,
            flags: BUILD_FLAGS,
            update_mode: wgpu::AccelerationStructureUpdateMode::Build,
        });
        let placement=(!installed.instances.is_empty()).then(|| {
                let visibility_blas:std::collections::HashMap<_,_>=installed.visibility_groups.iter().map(|group|(group.slot,&group.blas)).collect();
                let instances:Vec<_>=installed.instances.iter().enumerate().map(|(slot,&(draw,object))| {
                    let blas=visibility_blas.get(&slot).copied()
                        .or(installed.blas[draw].as_ref())
                        .or_else(||deformed[owners[draw]].as_ref().map(|(_,b)|b)).expect("ray instance BLAS");
                    (object,!s.materials[s.draws[draw].material].transparent,s.draws[draw].implicit.is_none(),installed.shadow_solids[slot],blas.clone())
                }).collect();
                crate::gpu_tlas::Placement::new(r,objects,&instances,&installed.placement_pipeline)
            }).transpose()?;
        let shadow_bounds=installed.shadow_bounds.as_ref().map(|plan|crate::shadow_containment::Slot::new(r,plan,objects)).transpose()?;
        Ok(Some(Self { shadow_bounds, tlas, placement, placement_revision:0, #[cfg(test)] builds:0, hit_buffers: Vec::new(), deformed, emitter_weights:installed.emitter_weights.as_ref().map(|p|crate::emitter_weights::Slot::new(p,d)) }))
    }
}

/// Rebuild what this sample's uploads changed: deformed BLAS when skin or morph
/// values moved, and the TLAS when any object value (transform or ray mask) moved.
pub(crate) fn encode(encoder: &mut wgpu::CommandEncoder, s: &InstalledScene, f: &mut FrameSlot) {
    let (Some(rays), Some(installed)) = (f.rays.as_mut(), s.rays.as_ref()) else {
        return;
    };
    // The slot's first sample builds everything; later ones follow the uploads.
    let first = f.changes.changed(values::ChangeKey::RayStructures, &[1]);
    let uploaded = |buffer: &wgpu::Buffer| f.changes.buffer_dirty(buffer);
    // CPU subdivision uploads its evaluated poses with fixed skin parameters.
    // Those vertex changes invalidate the same deformed BLAS as GPU skin/morphs.
    let dirty_geometry: Vec<bool> = s.draws.iter().enumerate().map(|(i, draw)| {
        // Static draws and aliases own no evaluated BLAS to invalidate.
        if rays.deformed[i].is_none() {return false;}
        let i = draw.displacement_leader.unwrap_or(i);
        first || f.changes.dirty(values::ChangeKey::ComputedPositions(i))
            || f.skin[i].as_ref().is_some_and(|d| uploaded(&d.params) || uploaded(&d.previous_params))
            || f.subdivision_morphs[i].as_ref().is_some_and(uploaded)
            || f.displacements.get(i).and_then(|frame| frame.as_ref()).is_some_and(|frame| frame.dirty(&f.changes))
    }).collect();
    let deform_changed = rays.deformed.iter().zip(&dirty_geometry).any(|(blas, dirty)| blas.is_some() && *dirty);
    let placement_changed = if rays.placement.is_some() {
        let changed=rays.placement_revision != f.changes.placement_revision;
        rays.placement_revision=f.changes.placement_revision;
        changed
            || f.compute.as_ref().is_some_and(|compute|uploaded(&compute.parents))
    } else {false};
    let objects_changed = first || uploaded(&f.objects) || placement_changed;
    if let Some(bounds)=&rays.shadow_bounds {
        if objects_changed || uploaded(&bounds.buffer) {bounds.encode(encoder);}
    }
    // Emission tracks update proposal mass without rebuilding acceleration
    // structures. Use the existing per-slot upload tracker for both inputs.
    let materials=f.materials.as_ref().map_or_else(||s.material_table.records(),|m|&m.records);
    if deform_changed || objects_changed || uploaded(materials) {
        if let (Some(slot),Some(plan))=(&rays.emitter_weights,&installed.emitter_weights) {slot.encode(plan,encoder);}
    }
    if !deform_changed && !objects_changed {
        return;
    }
    let entries: Vec<_> = rays
        .deformed
        .iter()
        .enumerate()
        .filter(|(index, _)| dirty_geometry[*index])
        .filter_map(|(index, deformed)| {
            let (size, blas) = deformed.as_ref()?;
            let draw = &s.draws[index];
            Some(wgpu::BlasBuildEntry {
                blas,
                geometry: geometry(
                    size,
                    &f.deforms[index].as_ref()?.output.buffer,
                    f.deforms[index].as_ref()?.output.first_vertex(),
                    std::mem::size_of::<DeformedVertex>() as u64,
                    &draw.indices,
                    (draw.index_offset / 4) as u32,
                ),
            })
        })
        .collect();
    #[cfg(test)] {rays.builds+=1;}
    if let Some(placement)=&rays.placement {
        encoder.build_acceleration_structures(entries.iter(), std::iter::empty());
        placement.encode(encoder,&rays.tlas);
    } else {
        encoder.build_acceleration_structures(entries.iter(), std::iter::once(&rays.tlas));
    }
}

#[cfg(all(test, vork_private_tests))]
include!("rt_tests_private.rs");
#[cfg(test)]
mod default_shadow_tests {
    use super::*;
    #[test]
    fn ray_profile_reserves_queries_for_imported_and_extracted_lights() {
        let scene: Scene = vork_scene::v2::from_test_value(serde_json::json!({
            "version":2, "nodes":[{"type":"light","shape":"environment"}],
            "render":{"settings":{"integrator":"raster","shadow_method":"ray"}}
        })).unwrap();
        assert!(ray_shadows(&scene));
        assert!(ray_options(&scene, false).iter().any(|option| option.contains("ray-traced shadows")));
    }

    #[test]
    fn automatic_lights_admit_the_extracted_provider_after_install() {
        let mut scene: Scene = vork_scene::v2::from_test_value(serde_json::json!({
            "version":2, "nodes":[{"type":"mesh","geometry":"shape_box"},
                {"type":"light","shape":"environment"}]
        })).unwrap();
        assert!(ray_shadows(&scene));
        assert!(!installed_shadow_rays(&scene,&[]));
        let node:Node=vork_scene::v2::from_test_value(serde_json::json!({"type":"light","shape":"sun"})).unwrap();
        let nodes=vec![EvalNode { camera: None,node:node.clone(),parent:None,world:Mat4::IDENTITY,dynamic:false,embedded:None}];
        assert!(installed_shadow_rays(&scene,&nodes));
        scene.nodes.push(node);
        assert!(ray_shadows(&scene));
        assert!(super::missing(&scene, false, "test (Vulkan)").unwrap().contains("automatic light shadows"));
    }

    #[test]
    fn automatic_lights_skip_empty_surface_trees() {
        let scene:Scene=vork_scene::v2::from_test_value(serde_json::json!({"version":2,
            "nodes":[{"type":"camera"},{"type":"light","shape":"sun"},
                {"type":"light","shape":"environment"}]})).unwrap();
        assert!(!ray_shadows(&scene));
        assert!(!uses_rays(&scene));
    }

    #[test]
    fn environment_lights_cast_no_ray_shadows() {
        for shape in ["environment","sun","point","spot","rectangle","ellipse"] {
            let node:Node=vork_scene::v2::from_test_value(serde_json::json!({"name":"light","type":"light","shape":shape})).unwrap();
            assert_eq!(traces_shadows(&node.kind),shape!="environment");
        }
    }

    #[test]
    fn sampled_alpha_scene_ignores_environment_shadow_defaults() -> Result<()> {
        let Some(r)=crate::test_renderer()? else {return Ok(());};
        let mut scene:serde_json::Value=vork_scene::v2::with_test_settings(include_str!("../tests/fixtures/analytic.json"), include_str!("../tests/presets/analytic-7fefd52a.json"))?;
        scene["render"]["settings"]["shadow_method"]="ray".into();
        scene["render"]["settings"]["samples"]=2.into();
        scene["render"]["settings"]["reflections"]="environment".into();
        scene["materials"]=serde_json::json!({"alpha":{"opacity":"transmittance","inputs":{"geometry_opacity":0.5}}});
        for n in scene["nodes"].as_array_mut().unwrap() {
            if n["type"]=="mesh" {n["materials"]=serde_json::json!(["alpha"]);}
        }
        scene["nodes"].as_array_mut().unwrap().push(serde_json::json!({"type":"light","name":"world","shape":"environment","color":[0.1,0.1,0.1]}));
        let base=Path::new(env!("CARGO_MANIFEST_DIR")).join("tests/fixtures");
        let mut installed=r.install(vork_scene::v2::from_test_value(scene)?,&base)?;
        let mut frame=FrameSlot::new(&installed,&r,crate::frame::ReadbackPrecision::Packed)?;
        assert!(!installed.render_frame(&r,&mut frame,0.)?.rgba.is_empty());
        Ok(())
    }

}

// Keep default materials and imported material slots conservative. Visibility
// cannot prove absence: captures and secondary rays may consume any surface.
fn surface_stages_required(nodes:&[Node], stages:&std::collections::BTreeMap<String,crate::programs::Stages>)->bool {
    nodes.iter().any(|node| {
        let surface=match &node.kind {
            NodeKind::Mesh {materials,..}=>materials.is_empty() || materials.iter().any(|name|stages.get(name).is_none_or(|s|s.surface)),
            NodeKind::Asset {..}=>true,
            _=>false,
        };
        surface || surface_stages_required(&node.children,stages)
    })
}

/// Resolve unsupported combinations from scene facts before resources or passes
/// are chosen. Quality never controls admission; preserve the call budget.
pub(crate) fn resolve_scene_providers(r:&Renderer, scene:&mut Scene, base:&Path)->Result<()> {
    fn nodes<'a>(roots:&'a [Node], out:&mut Vec<&'a Node>) {
        for node in roots {out.push(node); nodes(&node.children,out);}
    }
    let mut all=Vec::new(); nodes(&scene.nodes,&mut all);
    let world=all.iter().find_map(|n|if let NodeKind::Light {shape:vork_scene::LightShape::Environment,medium,..}=&n.kind {medium.as_deref()} else {None});
    let (varying_world,raster_world)=world.map(|name|crate::medium::compile(r,scene,name,base).map(|(program,_)|(!program.homogeneous,!program.homogeneous && program.exponential.is_none()))).transpose()?.unwrap_or((false,false));
    let ies=all.iter().any(|n|matches!(&n.kind,NodeKind::Light {shape,image:Some(_),..} if !matches!(shape,vork_scene::LightShape::Environment)));
    let stages=crate::programs::mesh_stages(r,scene,base)?;
    // Mesh stage reflection is authoritative here, before automatic providers
    // and effect pipelines are selected. A medium boundary is not a receiver.
    if !surface_stages_required(&scene.nodes, &stages) {
        if let Some(raster)=scene.render.settings.integrator.raster_mut() {
            raster.fast_gi=None;
            raster.probes=None;
            if raster.reflections==vork_scene::Reflections::Auto {raster.reflections=vork_scene::Reflections::Environment;}
            if raster.refraction==vork_scene::Refraction::Auto {raster.refraction=vork_scene::Refraction::Environment;}
        }
    }
    let hair=stages.keys().any(|name|scene.materials[name].program=="std/hair");
    // The direct-only look uses ray camera visibility for authored table alpha.
    // This retains transparent emission without the indirect receiver stages.
    let mut previs_coverage=false;
    if scene.render.settings.previs {
        let animated=materials::animated_inputs(scene)?;
        for name in stages.keys().filter(|name|scene.materials[*name].program=="std/openpbr") {
            let inputs=animated.get(name).cloned().unwrap_or_default();
            previs_coverage |= materials::openpbr_values(scene,Some(name),&inputs,|_|Ok(0))?.has_opacity;
        }
    }
    let requires_path=ies || hair || previs_coverage || crate::catcher::has_mattes(scene);
    ensure!(!(raster_world && requires_path),"effect unavailable: heterogeneous world media combined with IES lights, physical hair or compositing mattes need a finite medium domain; bind the medium to a closed mesh");
    if (raster_world || !r.device.features().contains(wgpu::Features::EXPERIMENTAL_RAY_QUERY | HIT_BUFFER_FEATURES)) && !requires_path && scene.render.settings.integrator.is_path() {
        let denoise=scene.render.settings.integrator.denoiser().is_some();
        let mut fallback=vork_scene::Settings::for_level(1,vork_scene::RenderSettings {seed:scene.render.settings.seed,denoise,..Default::default()});
        fallback.samples=scene.render.settings.samples;
        scene.render.settings=fallback;
    } else if requires_path && !scene.render.settings.integrator.is_path() {promote_indirect_to_path(scene);}
    if varying_world && let Some(raster)=scene.render.settings.integrator.raster_mut() {
        // Heterogeneous world transport uses per-receiver queries. Computed
        // placements retain adaptive probe support over the camera clip region.
        raster.probes=None;
    }
    Ok(())
}