concinnity-device 0.19.23

// src/vulkan/raymarch.rs
//
// Raymarched SDF volume pass for the Vulkan backend. Runs at `PassId::Raymarch`
// between `AutoExposure` and `Decals` on the hdr_resolve RMW chain. Each
// `SdfVolume` rasterises the back faces of its world-space bounding box and runs
// a user-authored GLSL fragment shader that sphere-traces the SDF inside the
// box. GLSL/Vulkan port of `src/directx/raymarch.rs`: same shader interface,
// same depth-compositing rules.
//
// MSAA depth write-back. MSAA is on by default, so the pass renders the proxy
// into the multisampled HDR colour + the writable scene depth (the shader
// writes hit depth via `gl_FragDepth` redeclared `depth_less`), then the render
// pass resolves the combined colour into `hdr_resolve` so the single-sample
// post stack picks up the raymarched pixels and the raymarched-surface depth.
// This reuses the two-pass-occlusion main render passes (`load = false` STOREs
// the MSAA colour at the main pass so this pass can `load = true` it back), and
// the existing main framebuffers, which are render-pass-compatible. The main
// pass selects the STORE-colour variant whenever raymarch is active (see
// `vulkan/main.rs`). When single-sampled the main pass already leaves the scene
// in `hdr_resolve`, so the pass loads it directly and re-stores it (no resolve).
//
// Backend filter. The asset's `fragment_shader` path picks the backend: Vulkan
// consumes `.glsl` payloads; `.metal` / `.hlsl` SDFs are skipped at init with a
// logged warning and the rest of the world renders unchanged.

use concinnity_core::gfx::transform::mat4_inverse;
use std::ffi::CString;

use ash::vk;

use crate::vulkan::owned::{
    OwnedDescriptorPool, OwnedPipeline, OwnedPipelineLayout, OwnedRenderPass, OwnedSetLayout,
    VkDevice,
};

use super::allocator::{DeviceAllocator, PooledBuffer};
use crate::components::SdfVolume;
use crate::gfx::mesh_payload::Vertex;
use crate::gfx::render_types::{LightUniforms, ShadowUniforms};

use concinnity_core::components::sdf_programs::SdfPrograms;
use concinnity_core::platform::Platform;
use concinnity_core::render::slang_programs::raymarch::{self, Family};
use concinnity_slang::SlangTarget;

use super::context::{HDR_FORMAT, VkContext};
use super::pipeline::spv_module;
use super::render_pass::create_main_render_pass_two_pass;
use super::texture::{
    GpuImage, ImageSpec, LayoutTransition, SubresourceRange, create_image, create_image_view,
    one_shot_submit, transition_image_layout_range,
};

// 36 indices for the unit-cube proxy: front faces are culled so each pixel
// inside the bounding box gets exactly one back-face fragment.
const CUBE_INDEX_COUNT: u32 = 36;

// One declaration for all three backends, in `core::render::uniforms`.
// Re-exported so `crate::vulkan::raymarch::{RaymarchView, RaymarchVolumeUniforms}`
// stay the paths the encode and `volume_uniforms_from` sites use.
pub(in crate::vulkan) use concinnity_core::render::uniforms::{
    RaymarchView, RaymarchVolumeUniforms,
};

// Which cascade a shadow-caster draw targets, pushed to both stages. The whole
// 16-byte block is declared, not just the live `u32`: the shared source spells
// it out to the padding the other two hosts allocate, and a range narrower than
// what the shader declares is a validation finding.
use concinnity_core::render::uniforms::RaymarchShadowCascade;

pub(in crate::vulkan) fn volume_uniforms_from(v: &SdfVolume) -> RaymarchVolumeUniforms {
    RaymarchVolumeUniforms {
        centre: v.centre,
        _pad0: 0.0,
        extent: v.extent,
        _pad1: 0.0,
        cone_ratio: v.cone_ratio(),
        max_distance: v.max_distance,
        max_steps: v.max_steps as i32,
        receive_shadows: if v.receive_shadows { 1 } else { 0 },
        params: v.params,
    }
}

// Copy the resolved scene into the refraction snapshot, opening both images for
// the transfer and leaving the source in TRANSFER_SRC for the caller's step-2
// barrier to close. Only a frame drawing a volume that taps the scene runs it.
fn copy_scene_snapshot(
    device: &ash::Device,
    cmd: vk::CommandBuffer,
    hdr_resolve: vk::Image,
    snapshot: vk::Image,
    extent: vk::Extent2D,
) {
    let color_aspect = vk::ImageSubresourceRange {
        aspect_mask: vk::ImageAspectFlags::COLOR,
        base_mip_level: 0,
        level_count: 1,
        base_array_layer: 0,
        layer_count: 1,
    };
    let open = |image: vk::Image, new: vk::ImageLayout, dst: vk::AccessFlags| {
        vk::ImageMemoryBarrier::default()
            .src_access_mask(vk::AccessFlags::SHADER_READ)
            .dst_access_mask(dst)
            .old_layout(vk::ImageLayout::SHADER_READ_ONLY_OPTIMAL)
            .new_layout(new)
            .src_queue_family_index(vk::QUEUE_FAMILY_IGNORED)
            .dst_queue_family_index(vk::QUEUE_FAMILY_IGNORED)
            .image(image)
            .subresource_range(color_aspect)
    };
    let layers = vk::ImageSubresourceLayers {
        aspect_mask: vk::ImageAspectFlags::COLOR,
        mip_level: 0,
        base_array_layer: 0,
        layer_count: 1,
    };
    let region = vk::ImageCopy::default()
        .src_subresource(layers)
        .dst_subresource(layers)
        .extent(vk::Extent3D {
            width: extent.width,
            height: extent.height,
            depth: 1,
        });
    // SAFETY: `cmd` is a command buffer in the recording state, and every handle and slice these
    // commands name is live for the call.
    unsafe {
        device.cmd_pipeline_barrier(
            cmd,
            vk::PipelineStageFlags::COMPUTE_SHADER | vk::PipelineStageFlags::FRAGMENT_SHADER,
            vk::PipelineStageFlags::TRANSFER,
            vk::DependencyFlags::empty(),
            &[],
            &[],
            &[
                open(
                    hdr_resolve,
                    vk::ImageLayout::TRANSFER_SRC_OPTIMAL,
                    vk::AccessFlags::TRANSFER_READ,
                ),
                open(
                    snapshot,
                    vk::ImageLayout::TRANSFER_DST_OPTIMAL,
                    vk::AccessFlags::TRANSFER_WRITE,
                ),
            ],
        );
        device.cmd_copy_image(
            cmd,
            hdr_resolve,
            vk::ImageLayout::TRANSFER_SRC_OPTIMAL,
            snapshot,
            vk::ImageLayout::TRANSFER_DST_OPTIMAL,
            std::slice::from_ref(&region),
        );
    }
}

// Per-`SdfVolume` GPU state: the compiled render pipeline, the static per-volume
// UBO (uploaded once at init), its descriptor set, and the visibility flag the
// encoder + `any_visible` read.
struct RaymarchVolumeRecord {
    // Owned, not a raw handle: the record outlives the local the pipeline was
    // built into, so storing the bare `vk::Pipeline` destroyed it at the end of
    // the loop iteration and left every draw binding a dangling one.
    pipeline: OwnedPipeline,
    // Depth-only shadow-caster pipeline. `Some` when the asset's `cast_shadows`
    // is set; the shadow encoder iterates only the volumes where this is `Some`
    // and `visible`. Targets `shadow_render_pass`.
    shadow_pipeline: Option<OwnedPipeline>,
    // Held for the volume's lifetime; `volume_set` aliases it.
    _volume_ubo: PooledBuffer,
    volume_set: vk::DescriptorSet,
    visible: bool,
    // Whether the authored field samples the scene behind the surface. The
    // pass copies hdr_resolve into `snapshot` only when some visible volume
    // does; the descriptor at set 0 binding 6 stands either way, so this
    // selects no pipeline variant.
    refractive: bool,
}

// Engine-side raymarch resources. Built only when at least one `.glsl`
// `SdfVolume` landed at init; `VkContext::raymarch` stays `None` otherwise and
// the pass is omitted from the frame graph.
pub(in crate::vulkan) struct RaymarchResources {
    // The raymarch render pass. MSAA: the two-pass `load = true` main pass
    // (loads the stored MSAA colour + scene depth, draws, resolves into
    // hdr_resolve). Single-sample: a dedicated load+store pass on hdr_resolve.
    render_pass: OwnedRenderPass,
    // STORE-colour main render pass the main pass switches to while raymarch is
    // active (MSAA only) so the MSAA samples survive for `render_pass` to load.
    // `None` when single-sampled (the main pass already keeps the resolve).
    pub(in crate::vulkan) main_store_color_pass: Option<OwnedRenderPass>,
    pipeline_layout: OwnedPipelineLayout,
    _view_set_layout: OwnedSetLayout,
    _volume_set_layout: OwnedSetLayout,
    _descriptor_pool: OwnedDescriptorPool,

    // Per-frame `RaymarchView` UBO ring. Persistently mapped; the encoder
    // memcpys this frame's view into `view_ubo_buffers[frame_idx].mapped_ptr()` before binding.
    view_ubos: Vec<PooledBuffer>,
    view_sets: Vec<vk::DescriptorSet>,

    // Shared unit-cube proxy geometry (positions at +/-1; the vertex shader
    // scales by `vol_extent` + offsets by `vol_centre`).
    cube_vb: PooledBuffer,
    cube_ib: PooledBuffer,

    // Pre-raymarch HDR scene snapshot for the refraction tap (`scene_color`).
    // The encoder copies hdr_resolve into this at the head of the pass; sized to
    // render dims, recreated by `rebuild` on resize.
    snapshot: GpuImage,
    // Sampler bound alongside the snapshot at set 0 binding 6. Borrowed from
    // `VkContext::linear_sampler`; not owned, never destroyed here.
    scene_sampler: vk::Sampler,

    // Shadow-caster resources. Built only when at least one volume opts into
    // `cast_shadows`; null / empty otherwise. The shadow view set is a minimal
    // 3-UBO set (RaymarchView for `view_time`, lights, shadow VPs) with its own
    // per-frame `RaymarchView` ring written by the shadow pass, so the shared
    // main view ring (written by `encode_raymarch`) is never touched from the
    // concurrently-recorded Shadow pass. The pipeline layout carries a
    // `cascade_idx` push constant.
    shadow_pipeline_layout: OwnedPipelineLayout,
    _shadow_view_set_layout: OwnedSetLayout,
    shadow_view_ubos: Vec<PooledBuffer>,
    shadow_view_sets: Vec<vk::DescriptorSet>,

    msaa: bool,
    volumes: Vec<RaymarchVolumeRecord>,
}

// The SPIR-V for one family of a volume's field, as (vertex, fragment).
//
// The cook compiled these; each entry is its own module here, which is what a
// Vulkan pipeline binds and what a DXIL container is on the other host. A
// template edit makes the stored artifacts miss and both entries compile.
fn family_spirv(
    programs: &SdfPrograms,
    family: Family,
    hot_reload: bool,
    label: &str,
) -> Result<(Vec<u8>, Vec<u8>), String> {
    let mut stages = raymarch::ALL.iter().filter(|p| p.family == family);
    let spirv = |entry: &str| -> Result<Vec<u8>, String> {
        crate::raymarch_source::artifact(
            programs,
            &crate::raymarch_source::Request {
                family,
                platform: Platform::Glsl,
                entries: &[entry],
                target: SlangTarget::Spirv,
                hot_reload,
                label,
            },
        )
        .map(|bytes| bytes.into_owned())
    };
    let vert = spirv(
        stages
            .next()
            .expect("a family declares a vertex entry")
            .entry,
    )?;
    let frag = spirv(
        stages
            .next()
            .expect("a family declares a fragment entry")
            .entry,
    )?;
    Ok((vert, frag))
}

// One corner of the proxy cube. Only the position is fetched (location 0); the
// rest of the 56-byte engine `Vertex` is zeroed.
fn cube_vertex(pos: [f32; 3]) -> Vertex {
    Vertex {
        pos,
        normal: [0.0; 3],
        tangent: [0.0; 3],
        color: [0.0; 3],
        uv: [0.0; 2],
    }
}

// Build the shared unit-cube proxy VB + IB. 8 corners at +/-1; 36 indices (the
// pipeline culls front faces so only back faces fire). Host-visible buffers,
// written once. Mirrors `directx::raymarch::build_cube_buffers`.
type CubeBuffers = (PooledBuffer, PooledBuffer);
fn build_cube_buffers(alloc: &DeviceAllocator) -> Result<CubeBuffers, String> {
    #[rustfmt::skip]
    let corners: [Vertex; 8] = [
        cube_vertex([-1.0, -1.0, -1.0]),
        cube_vertex([ 1.0, -1.0, -1.0]),
        cube_vertex([ 1.0,  1.0, -1.0]),
        cube_vertex([-1.0,  1.0, -1.0]),
        cube_vertex([-1.0, -1.0,  1.0]),
        cube_vertex([ 1.0, -1.0,  1.0]),
        cube_vertex([ 1.0,  1.0,  1.0]),
        cube_vertex([-1.0,  1.0,  1.0]),
    ];
    #[rustfmt::skip]
    let indices: [u16; 36] = [
        0, 2, 1,  0, 3, 2, // -Z
        4, 5, 6,  4, 6, 7, // +Z
        0, 4, 7,  0, 7, 3, // -X
        1, 2, 6,  1, 6, 5, // +X
        0, 1, 5,  0, 5, 4, // -Y
        3, 7, 6,  3, 6, 2, // +Y
    ];

    let vb_bytes = std::mem::size_of_val(&corners) as u64;
    let ib_bytes = std::mem::size_of_val(&indices) as u64;
    let host = vk::MemoryPropertyFlags::HOST_VISIBLE | vk::MemoryPropertyFlags::HOST_COHERENT;

    let vb = alloc.create_buffer(vb_bytes, vk::BufferUsageFlags::VERTEX_BUFFER, host)?;
    let ib = alloc.create_buffer(ib_bytes, vk::BufferUsageFlags::INDEX_BUFFER, host)?;
    vb.write_slice(0, &corners);
    ib.write_slice(0, &indices);
    Ok((vb, ib))
}

// The single-sample raymarch render pass: load + store hdr_resolve directly
// (the main pass already left the scene there in SHADER_READ_ONLY) and the
// scene depth, with no resolve. The MSAA path reuses the two-pass main passes
// instead.
fn create_raymarch_render_pass_single(
    device: &VkDevice,
    format: vk::Format,
) -> Result<OwnedRenderPass, String> {
    let attachments = [
        vk::AttachmentDescription::default()
            .format(format)
            .samples(vk::SampleCountFlags::TYPE_1)
            .load_op(vk::AttachmentLoadOp::LOAD)
            .store_op(vk::AttachmentStoreOp::STORE)
            .stencil_load_op(vk::AttachmentLoadOp::DONT_CARE)
            .stencil_store_op(vk::AttachmentStoreOp::DONT_CARE)
            .initial_layout(vk::ImageLayout::SHADER_READ_ONLY_OPTIMAL)
            .final_layout(vk::ImageLayout::SHADER_READ_ONLY_OPTIMAL),
        vk::AttachmentDescription::default()
            .format(vk::Format::D32_SFLOAT)
            .samples(vk::SampleCountFlags::TYPE_1)
            .load_op(vk::AttachmentLoadOp::LOAD)
            .store_op(vk::AttachmentStoreOp::STORE)
            .stencil_load_op(vk::AttachmentLoadOp::DONT_CARE)
            .stencil_store_op(vk::AttachmentStoreOp::DONT_CARE)
            .initial_layout(vk::ImageLayout::DEPTH_STENCIL_ATTACHMENT_OPTIMAL)
            .final_layout(vk::ImageLayout::DEPTH_STENCIL_ATTACHMENT_OPTIMAL),
    ];
    let color_ref = vk::AttachmentReference::default()
        .attachment(0)
        .layout(vk::ImageLayout::COLOR_ATTACHMENT_OPTIMAL);
    let depth_ref = vk::AttachmentReference::default()
        .attachment(1)
        .layout(vk::ImageLayout::DEPTH_STENCIL_ATTACHMENT_OPTIMAL);
    let subpass = vk::SubpassDescription::default()
        .pipeline_bind_point(vk::PipelineBindPoint::GRAPHICS)
        .color_attachments(std::slice::from_ref(&color_ref))
        .depth_stencil_attachment(&depth_ref);
    let dependency = vk::SubpassDependency::default()
        .src_subpass(vk::SUBPASS_EXTERNAL)
        .dst_subpass(0)
        .src_stage_mask(
            vk::PipelineStageFlags::COLOR_ATTACHMENT_OUTPUT
                | vk::PipelineStageFlags::EARLY_FRAGMENT_TESTS,
        )
        .src_access_mask(vk::AccessFlags::empty())
        .dst_stage_mask(
            vk::PipelineStageFlags::COLOR_ATTACHMENT_OUTPUT
                | vk::PipelineStageFlags::EARLY_FRAGMENT_TESTS,
        )
        .dst_access_mask(
            vk::AccessFlags::COLOR_ATTACHMENT_WRITE
                | vk::AccessFlags::DEPTH_STENCIL_ATTACHMENT_WRITE,
        );
    let info = vk::RenderPassCreateInfo::default()
        .attachments(&attachments)
        .subpasses(std::slice::from_ref(&subpass))
        .dependencies(std::slice::from_ref(&dependency));
    device
        .create_render_pass(&info)
        .map_err(|e| format!("raymarch render pass: {e}"))
}

fn create_view_set_layout(device: &VkDevice) -> Result<OwnedSetLayout, String> {
    let vert_frag = vk::ShaderStageFlags::VERTEX | vk::ShaderStageFlags::FRAGMENT;
    let frag = vk::ShaderStageFlags::FRAGMENT;
    let ubo = |b: u32, stages: vk::ShaderStageFlags| {
        vk::DescriptorSetLayoutBinding::default()
            .binding(b)
            .descriptor_type(vk::DescriptorType::UNIFORM_BUFFER)
            .descriptor_count(1)
            .stage_flags(stages)
    };
    let tex = |b: u32| {
        vk::DescriptorSetLayoutBinding::default()
            .binding(b)
            .descriptor_type(vk::DescriptorType::COMBINED_IMAGE_SAMPLER)
            .descriptor_count(1)
            .stage_flags(frag)
    };
    let bindings = [
        ubo(0, vert_frag), // RaymarchView
        ubo(1, frag),      // RaymarchLights
        ubo(2, frag),      // RaymarchShadow
        tex(3),            // shadow_map (sampler2DArrayShadow)
        tex(4),            // irradiance cube
        tex(5),            // prefilter cube
        tex(6),            // scene_color snapshot
    ];
    let info = vk::DescriptorSetLayoutCreateInfo::default().bindings(&bindings);
    device
        .create_descriptor_set_layout(&info)
        .map_err(|e| format!("raymarch view set layout: {e}"))
}

fn create_volume_set_layout(device: &VkDevice) -> Result<OwnedSetLayout, String> {
    let binding = vk::DescriptorSetLayoutBinding::default()
        .binding(0)
        .descriptor_type(vk::DescriptorType::UNIFORM_BUFFER)
        .descriptor_count(1)
        .stage_flags(vk::ShaderStageFlags::VERTEX | vk::ShaderStageFlags::FRAGMENT);
    let info =
        vk::DescriptorSetLayoutCreateInfo::default().bindings(std::slice::from_ref(&binding));
    device
        .create_descriptor_set_layout(&info)
        .map_err(|e| format!("raymarch volume set layout: {e}"))
}

fn create_descriptor_pool(
    device: &VkDevice,
    frames: usize,
    volumes: usize,
    has_shadow: bool,
) -> Result<OwnedDescriptorPool, String> {
    let f = frames as u32;
    let v = volumes as u32;
    // Shadow view sets (when any volume casts shadows): 3 UBOs each per frame.
    let shadow_sets = if has_shadow { f } else { 0 };
    let sizes = [
        // view: RaymarchView + Lights + Shadow (3) per frame; volume: 1 each;
        // shadow view: 3 per frame.
        vk::DescriptorPoolSize {
            ty: vk::DescriptorType::UNIFORM_BUFFER,
            descriptor_count: 3 * f + v + 3 * shadow_sets,
        },
        // view: shadow_map + irradiance + prefilter + scene_color (4) per frame.
        vk::DescriptorPoolSize {
            ty: vk::DescriptorType::COMBINED_IMAGE_SAMPLER,
            descriptor_count: 4 * f,
        },
    ];
    let info = vk::DescriptorPoolCreateInfo::default()
        .max_sets(f + v + shadow_sets)
        .pool_sizes(&sizes);
    device
        .create_descriptor_pool(&info)
        .map_err(|e| format!("raymarch descriptor pool: {e}"))
}

// Minimal 3-UBO descriptor set layout for the shadow-caster pass: RaymarchView
// (view_time), lights (sun direction), and the cascade light VPs. No texture
// bindings (the shadow march never samples), so the shadow map being written
// this pass is never also bound as a descriptor.
fn create_shadow_view_set_layout(device: &VkDevice) -> Result<OwnedSetLayout, String> {
    let frag = vk::ShaderStageFlags::FRAGMENT;
    let vert_frag = vk::ShaderStageFlags::VERTEX | vk::ShaderStageFlags::FRAGMENT;
    let ubo = |b: u32, stages: vk::ShaderStageFlags| {
        vk::DescriptorSetLayoutBinding::default()
            .binding(b)
            .descriptor_type(vk::DescriptorType::UNIFORM_BUFFER)
            .descriptor_count(1)
            .stage_flags(stages)
    };
    let bindings = [
        ubo(0, frag),      // RaymarchView (view_time)
        ubo(1, frag),      // RaymarchLights (sun direction)
        ubo(2, vert_frag), // RaymarchShadow (light VPs)
    ];
    let info = vk::DescriptorSetLayoutCreateInfo::default().bindings(&bindings);
    device
        .create_descriptor_set_layout(&info)
        .map_err(|e| format!("raymarch shadow view set layout: {e}"))
}

fn write_shadow_view_set(
    device: &VkDevice,
    set: vk::DescriptorSet,
    view_ubo: vk::Buffer,
    light_ubo: vk::Buffer,
    shadow_ubo: vk::Buffer,
) {
    let view_info = vk::DescriptorBufferInfo::default()
        .buffer(view_ubo)
        .offset(0)
        .range(std::mem::size_of::<RaymarchView>() as u64);
    let light_info = vk::DescriptorBufferInfo::default()
        .buffer(light_ubo)
        .offset(0)
        .range(std::mem::size_of::<LightUniforms>() as u64);
    let shadow_info = vk::DescriptorBufferInfo::default()
        .buffer(shadow_ubo)
        .offset(0)
        .range(std::mem::size_of::<ShadowUniforms>() as u64);
    let ubo = |b: u32| {
        vk::WriteDescriptorSet::default()
            .dst_set(set)
            .dst_binding(b)
            .descriptor_type(vk::DescriptorType::UNIFORM_BUFFER)
    };
    let writes = [
        ubo(0).buffer_info(std::slice::from_ref(&view_info)),
        ubo(1).buffer_info(std::slice::from_ref(&light_info)),
        ubo(2).buffer_info(std::slice::from_ref(&shadow_info)),
    ];
    // SAFETY: `writes` and the buffer/image infos it borrows are live for the call, and every set
    // and resource it names belongs to this device.
    unsafe { device.update_descriptor_sets(&writes, &[]) };
}

fn alloc_sets(
    device: &VkDevice,
    pool: vk::DescriptorPool,
    layouts: &[vk::DescriptorSetLayout],
) -> Result<Vec<vk::DescriptorSet>, String> {
    let info = vk::DescriptorSetAllocateInfo::default()
        .descriptor_pool(pool)
        .set_layouts(layouts);
    // SAFETY: the create-info and every slice it borrows are live for the call, and each handle it
    // names belongs to this device.
    unsafe { device.allocate_descriptor_sets(&info) }
        .map_err(|e| format!("raymarch descriptor sets: {e}"))
}

// The three UBOs bound into one per-frame view set: the per-frame RaymarchView,
// the shared lights, and the shared shadow VPs.
#[derive(Clone, Copy)]
struct RaymarchViewSetBuffers {
    view_ubo: vk::Buffer,
    light_ubo: vk::Buffer,
    shadow_ubo: vk::Buffer,
}

// The image/sampler pairs bound into one per-frame view set: the CSM shadow
// map, the IBL irradiance + prefilter cubes (sharing the cube sampler), and the
// per-frame-independent scene snapshot tap.
#[derive(Clone, Copy)]
struct RaymarchViewSetTextures {
    shadow_map_view: vk::ImageView,
    shadow_sampler: vk::Sampler,
    irradiance_view: vk::ImageView,
    prefilter_view: vk::ImageView,
    cube_sampler: vk::Sampler,
    snapshot_view: vk::ImageView,
    scene_sampler: vk::Sampler,
}

// Write every binding of one per-frame view set. The shadow / IBL / light /
// shadow-UBO bindings are shared engine resources; the snapshot is the
// per-frame-independent scene tap (its contents are refreshed by the encoder).
fn write_view_set(
    device: &VkDevice,
    set: vk::DescriptorSet,
    buffers: RaymarchViewSetBuffers,
    textures: RaymarchViewSetTextures,
) {
    let RaymarchViewSetBuffers {
        view_ubo,
        light_ubo,
        shadow_ubo,
    } = buffers;
    let RaymarchViewSetTextures {
        shadow_map_view,
        shadow_sampler,
        irradiance_view,
        prefilter_view,
        cube_sampler,
        snapshot_view,
        scene_sampler,
    } = textures;
    let view_info = vk::DescriptorBufferInfo::default()
        .buffer(view_ubo)
        .offset(0)
        .range(std::mem::size_of::<RaymarchView>() as u64);
    let light_info = vk::DescriptorBufferInfo::default()
        .buffer(light_ubo)
        .offset(0)
        .range(std::mem::size_of::<LightUniforms>() as u64);
    let shadow_info = vk::DescriptorBufferInfo::default()
        .buffer(shadow_ubo)
        .offset(0)
        .range(std::mem::size_of::<ShadowUniforms>() as u64);
    let img = |view: vk::ImageView, sampler: vk::Sampler| {
        vk::DescriptorImageInfo::default()
            .image_layout(vk::ImageLayout::SHADER_READ_ONLY_OPTIMAL)
            .image_view(view)
            .sampler(sampler)
    };
    let shadow_map_info = img(shadow_map_view, shadow_sampler);
    let irradiance_info = img(irradiance_view, cube_sampler);
    let prefilter_info = img(prefilter_view, cube_sampler);
    let snapshot_info = img(snapshot_view, scene_sampler);

    let ubo = |b: u32| {
        vk::WriteDescriptorSet::default()
            .dst_set(set)
            .dst_binding(b)
            .descriptor_type(vk::DescriptorType::UNIFORM_BUFFER)
    };
    let tex = |b: u32| {
        vk::WriteDescriptorSet::default()
            .dst_set(set)
            .dst_binding(b)
            .descriptor_type(vk::DescriptorType::COMBINED_IMAGE_SAMPLER)
    };
    let writes = [
        ubo(0).buffer_info(std::slice::from_ref(&view_info)),
        ubo(1).buffer_info(std::slice::from_ref(&light_info)),
        ubo(2).buffer_info(std::slice::from_ref(&shadow_info)),
        tex(3).image_info(std::slice::from_ref(&shadow_map_info)),
        tex(4).image_info(std::slice::from_ref(&irradiance_info)),
        tex(5).image_info(std::slice::from_ref(&prefilter_info)),
        tex(6).image_info(std::slice::from_ref(&snapshot_info)),
    ];
    // SAFETY: `writes` and the buffer/image infos it borrows are live for the call, and every set
    // and resource it names belongs to this device.
    unsafe { device.update_descriptor_sets(&writes, &[]) };
}

fn write_volume_set(device: &VkDevice, set: vk::DescriptorSet, volume_ubo: vk::Buffer) {
    let info = vk::DescriptorBufferInfo::default()
        .buffer(volume_ubo)
        .offset(0)
        .range(std::mem::size_of::<RaymarchVolumeUniforms>() as u64);
    let write = vk::WriteDescriptorSet::default()
        .dst_set(set)
        .dst_binding(0)
        .descriptor_type(vk::DescriptorType::UNIFORM_BUFFER)
        .buffer_info(std::slice::from_ref(&info));
    // SAFETY: `writes` and the buffer/image infos it borrows are live for the call, and every set
    // and resource it names belongs to this device.
    unsafe { device.update_descriptor_sets(std::slice::from_ref(&write), &[]) };
}

// Build a per-volume raymarch graphics pipeline. Front-face culled (back faces
// of the proxy cube rasterise regardless of camera position), depth-tested
// LESS_OR_EQUAL with depth write (the fragment writes `gl_FragDepth`), opaque
// (no blend). Negative-height viewport is applied dynamically at encode time.
fn create_pipeline(
    device: &VkDevice,
    render_pass: vk::RenderPass,
    layout: vk::PipelineLayout,
    msaa_samples: vk::SampleCountFlags,
    vert_spv: &[u8],
    frag_spv: &[u8],
) -> Result<OwnedPipeline, String> {
    let vert = spv_module(device, vert_spv)?;
    let frag = spv_module(device, frag_spv)?;
    let entry = CString::new("main").unwrap();
    let stages = [
        vk::PipelineShaderStageCreateInfo::default()
            .stage(vk::ShaderStageFlags::VERTEX)
            .module(vert.handle())
            .name(&entry),
        vk::PipelineShaderStageCreateInfo::default()
            .stage(vk::ShaderStageFlags::FRAGMENT)
            .module(frag.handle())
            .name(&entry),
    ];

    // Cube proxy VB: the 56-byte engine `Vertex`, position (location 0) only.
    let binding = vk::VertexInputBindingDescription::default()
        .binding(0)
        .stride(std::mem::size_of::<Vertex>() as u32)
        .input_rate(vk::VertexInputRate::VERTEX);
    let attribute = vk::VertexInputAttributeDescription::default()
        .location(0)
        .binding(0)
        .format(vk::Format::R32G32B32_SFLOAT)
        .offset(0);
    let vertex_input = vk::PipelineVertexInputStateCreateInfo::default()
        .vertex_binding_descriptions(std::slice::from_ref(&binding))
        .vertex_attribute_descriptions(std::slice::from_ref(&attribute));

    let input_assembly = vk::PipelineInputAssemblyStateCreateInfo::default()
        .topology(vk::PrimitiveTopology::TRIANGLE_LIST);
    let viewport_state = vk::PipelineViewportStateCreateInfo::default()
        .viewport_count(1)
        .scissor_count(1);
    // Front-face cull. The main pass renders with a negative-height (Y-flipped)
    // viewport; under that flip the proxy's near faces wind CCW, so culling them
    // as the front face leaves the back faces to rasterise (matches the DirectX
    // CULL_FRONT path).
    let raster = vk::PipelineRasterizationStateCreateInfo::default()
        .polygon_mode(vk::PolygonMode::FILL)
        .cull_mode(vk::CullModeFlags::FRONT)
        .front_face(vk::FrontFace::COUNTER_CLOCKWISE)
        .line_width(1.0);
    let multisample =
        vk::PipelineMultisampleStateCreateInfo::default().rasterization_samples(msaa_samples);
    // Depth test against the existing scene depth; write hit depth (the fragment
    // overrides `gl_FragDepth`) so downstream passes see the raymarched surface.
    let depth_stencil = vk::PipelineDepthStencilStateCreateInfo::default()
        .depth_test_enable(true)
        .depth_write_enable(true)
        .depth_compare_op(vk::CompareOp::LESS_OR_EQUAL);
    let blend_attachment = vk::PipelineColorBlendAttachmentState::default()
        .blend_enable(false)
        .color_write_mask(vk::ColorComponentFlags::RGBA);
    let blend_attachments = [blend_attachment];
    let blend_state = vk::PipelineColorBlendStateCreateInfo::default()
        .logic_op_enable(false)
        .attachments(&blend_attachments);
    let dynamic_states = [vk::DynamicState::VIEWPORT, vk::DynamicState::SCISSOR];
    let dynamic = vk::PipelineDynamicStateCreateInfo::default().dynamic_states(&dynamic_states);

    let info = vk::GraphicsPipelineCreateInfo::default()
        .stages(&stages)
        .vertex_input_state(&vertex_input)
        .input_assembly_state(&input_assembly)
        .viewport_state(&viewport_state)
        .rasterization_state(&raster)
        .multisample_state(&multisample)
        .depth_stencil_state(&depth_stencil)
        .color_blend_state(&blend_state)
        .dynamic_state(&dynamic)
        .layout(layout)
        .render_pass(render_pass);
    let pipeline = crate::vulkan::pipeline_cache::create_graphics_pipeline(device, &info)
        .map_err(|e| format!("create raymarch pipeline: {e}"))?;
    Ok(pipeline)
}

// Build the volumetric variant of the per-volume pipeline. Same cube proxy +
// front cull as the opaque pass, but the colour output alpha-blends over the
// existing scene (SRC_ALPHA / ONE_MINUS_SRC_ALPHA) and the depth state keeps the
// LESS_OR_EQUAL early-z test without writing: the medium is translucent and
// never updates the depth buffer downstream passes read. Mirrors the DirectX
// `create_raymarch_volumetric_pso`.
fn create_volumetric_pipeline(
    device: &VkDevice,
    render_pass: vk::RenderPass,
    layout: vk::PipelineLayout,
    msaa_samples: vk::SampleCountFlags,
    vert_spv: &[u8],
    frag_spv: &[u8],
) -> Result<OwnedPipeline, String> {
    let vert = spv_module(device, vert_spv)?;
    let frag = spv_module(device, frag_spv)?;
    let entry = CString::new("main").unwrap();
    let stages = [
        vk::PipelineShaderStageCreateInfo::default()
            .stage(vk::ShaderStageFlags::VERTEX)
            .module(vert.handle())
            .name(&entry),
        vk::PipelineShaderStageCreateInfo::default()
            .stage(vk::ShaderStageFlags::FRAGMENT)
            .module(frag.handle())
            .name(&entry),
    ];

    let binding = vk::VertexInputBindingDescription::default()
        .binding(0)
        .stride(std::mem::size_of::<Vertex>() as u32)
        .input_rate(vk::VertexInputRate::VERTEX);
    let attribute = vk::VertexInputAttributeDescription::default()
        .location(0)
        .binding(0)
        .format(vk::Format::R32G32B32_SFLOAT)
        .offset(0);
    let vertex_input = vk::PipelineVertexInputStateCreateInfo::default()
        .vertex_binding_descriptions(std::slice::from_ref(&binding))
        .vertex_attribute_descriptions(std::slice::from_ref(&attribute));

    let input_assembly = vk::PipelineInputAssemblyStateCreateInfo::default()
        .topology(vk::PrimitiveTopology::TRIANGLE_LIST);
    let viewport_state = vk::PipelineViewportStateCreateInfo::default()
        .viewport_count(1)
        .scissor_count(1);
    let raster = vk::PipelineRasterizationStateCreateInfo::default()
        .polygon_mode(vk::PolygonMode::FILL)
        .cull_mode(vk::CullModeFlags::FRONT)
        .front_face(vk::FrontFace::COUNTER_CLOCKWISE)
        .line_width(1.0);
    let multisample =
        vk::PipelineMultisampleStateCreateInfo::default().rasterization_samples(msaa_samples);
    // Early-z against the existing scene depth, but no depth write: the medium
    // doesn't occlude itself or update SSR / decal depth.
    let depth_stencil = vk::PipelineDepthStencilStateCreateInfo::default()
        .depth_test_enable(true)
        .depth_write_enable(false)
        .depth_compare_op(vk::CompareOp::LESS_OR_EQUAL);
    // Alpha-blend the in-scattered luminance over the rasterised scene.
    let blend_attachment = vk::PipelineColorBlendAttachmentState::default()
        .blend_enable(true)
        .src_color_blend_factor(vk::BlendFactor::SRC_ALPHA)
        .dst_color_blend_factor(vk::BlendFactor::ONE_MINUS_SRC_ALPHA)
        .color_blend_op(vk::BlendOp::ADD)
        .src_alpha_blend_factor(vk::BlendFactor::ONE)
        .dst_alpha_blend_factor(vk::BlendFactor::ONE_MINUS_SRC_ALPHA)
        .alpha_blend_op(vk::BlendOp::ADD)
        .color_write_mask(vk::ColorComponentFlags::RGBA);
    let blend_attachments = [blend_attachment];
    let blend_state = vk::PipelineColorBlendStateCreateInfo::default()
        .logic_op_enable(false)
        .attachments(&blend_attachments);
    let dynamic_states = [vk::DynamicState::VIEWPORT, vk::DynamicState::SCISSOR];
    let dynamic = vk::PipelineDynamicStateCreateInfo::default().dynamic_states(&dynamic_states);

    let info = vk::GraphicsPipelineCreateInfo::default()
        .stages(&stages)
        .vertex_input_state(&vertex_input)
        .input_assembly_state(&input_assembly)
        .viewport_state(&viewport_state)
        .rasterization_state(&raster)
        .multisample_state(&multisample)
        .depth_stencil_state(&depth_stencil)
        .color_blend_state(&blend_state)
        .dynamic_state(&dynamic)
        .layout(layout)
        .render_pass(render_pass);
    let pipeline = crate::vulkan::pipeline_cache::create_graphics_pipeline(device, &info)
        .map_err(|e| format!("create raymarch volumetric pipeline: {e}"))?;
    Ok(pipeline)
}

// Build a per-volume depth-only shadow-caster pipeline. Same cube proxy + front
// cull as the main pass, but no colour attachment (single-sample shadow map),
// depth-test LESS (matching the rasterised CSM casters) with depth write, and
// the fragment writes hit depth via `gl_FragDepth`. Targets `shadow_render_pass`.
fn create_shadow_pipeline(
    device: &VkDevice,
    shadow_render_pass: vk::RenderPass,
    layout: vk::PipelineLayout,
    vert_spv: &[u8],
    frag_spv: &[u8],
) -> Result<OwnedPipeline, String> {
    let vert = spv_module(device, vert_spv)?;
    let frag = spv_module(device, frag_spv)?;
    let entry = CString::new("main").unwrap();
    let stages = [
        vk::PipelineShaderStageCreateInfo::default()
            .stage(vk::ShaderStageFlags::VERTEX)
            .module(vert.handle())
            .name(&entry),
        vk::PipelineShaderStageCreateInfo::default()
            .stage(vk::ShaderStageFlags::FRAGMENT)
            .module(frag.handle())
            .name(&entry),
    ];

    let binding = vk::VertexInputBindingDescription::default()
        .binding(0)
        .stride(std::mem::size_of::<Vertex>() as u32)
        .input_rate(vk::VertexInputRate::VERTEX);
    let attribute = vk::VertexInputAttributeDescription::default()
        .location(0)
        .binding(0)
        .format(vk::Format::R32G32B32_SFLOAT)
        .offset(0);
    let vertex_input = vk::PipelineVertexInputStateCreateInfo::default()
        .vertex_binding_descriptions(std::slice::from_ref(&binding))
        .vertex_attribute_descriptions(std::slice::from_ref(&attribute));

    let input_assembly = vk::PipelineInputAssemblyStateCreateInfo::default()
        .topology(vk::PrimitiveTopology::TRIANGLE_LIST);
    let viewport_state = vk::PipelineViewportStateCreateInfo::default()
        .viewport_count(1)
        .scissor_count(1);
    // Same front-face cull as the main pass: under the shadow pass's
    // negative-height viewport the proxy's near faces wind CCW, so culling them
    // leaves the back faces to seed the from-light ray.
    let raster = vk::PipelineRasterizationStateCreateInfo::default()
        .polygon_mode(vk::PolygonMode::FILL)
        .cull_mode(vk::CullModeFlags::FRONT)
        .front_face(vk::FrontFace::COUNTER_CLOCKWISE)
        .line_width(1.0);
    let multisample = vk::PipelineMultisampleStateCreateInfo::default()
        .rasterization_samples(vk::SampleCountFlags::TYPE_1);
    let depth_stencil = vk::PipelineDepthStencilStateCreateInfo::default()
        .depth_test_enable(true)
        .depth_write_enable(true)
        .depth_compare_op(vk::CompareOp::LESS);
    // No colour attachment in the shadow render pass.
    let blend_state = vk::PipelineColorBlendStateCreateInfo::default().logic_op_enable(false);
    let dynamic_states = [vk::DynamicState::VIEWPORT, vk::DynamicState::SCISSOR];
    let dynamic = vk::PipelineDynamicStateCreateInfo::default().dynamic_states(&dynamic_states);

    let info = vk::GraphicsPipelineCreateInfo::default()
        .stages(&stages)
        .vertex_input_state(&vertex_input)
        .input_assembly_state(&input_assembly)
        .viewport_state(&viewport_state)
        .rasterization_state(&raster)
        .multisample_state(&multisample)
        .depth_stencil_state(&depth_stencil)
        .color_blend_state(&blend_state)
        .dynamic_state(&dynamic)
        .layout(layout)
        .render_pass(shadow_render_pass);
    let pipeline = crate::vulkan::pipeline_cache::create_graphics_pipeline(device, &info)
        .map_err(|e| format!("create raymarch shadow pipeline: {e}"))?;
    Ok(pipeline)
}

// Create the pre-raymarch HDR scene snapshot (SAMPLED | TRANSFER_DST, GPU-local)
// and rest it in SHADER_READ_ONLY so the first frame's snapshot barrier
// (SHADER_READ_ONLY -> TRANSFER_DST) matches.
fn create_snapshot(
    alloc: &DeviceAllocator,
    device: &VkDevice,
    command_pool: vk::CommandPool,
    queue: vk::Queue,
    width: u32,
    height: u32,
) -> Result<GpuImage, String> {
    let pooled = create_image(
        alloc,
        &ImageSpec {
            width: width.max(1),
            height: height.max(1),
            format: HDR_FORMAT,
            tiling: vk::ImageTiling::OPTIMAL,
            usage: vk::ImageUsageFlags::SAMPLED | vk::ImageUsageFlags::TRANSFER_DST,
            mem_props: vk::MemoryPropertyFlags::DEVICE_LOCAL,
            samples: vk::SampleCountFlags::TYPE_1,
        },
    )?;
    let image = pooled.image();
    one_shot_submit(device, command_pool, queue, |cmd| {
        transition_image_layout_range(
            device,
            cmd,
            image,
            LayoutTransition {
                old_layout: vk::ImageLayout::UNDEFINED,
                new_layout: vk::ImageLayout::SHADER_READ_ONLY_OPTIMAL,
                aspect: vk::ImageAspectFlags::COLOR,
            },
            SubresourceRange {
                base_layer: 0,
                layer_count: 1,
                base_mip: 0,
                mip_count: 1,
            },
        );
    })?;
    let view = create_image_view(device, image, HDR_FORMAT, vk::ImageAspectFlags::COLOR)?;
    Ok(GpuImage::from_pooled(pooled, view))
}

// Vulkan device/instance handles used to create + rebuild raymarch GPU
// resources. Shared by `try_new` and `rebuild`.
#[derive(Clone, Copy)]
pub(in crate::vulkan) struct RaymarchDeviceContext<'a> {
    pub(in crate::vulkan) alloc: &'a DeviceAllocator,
    pub(in crate::vulkan) device: &'a VkDevice,
    pub(in crate::vulkan) command_pool: vk::CommandPool,
    pub(in crate::vulkan) queue: vk::Queue,
}

// Render-target configuration for the raymarch pass: the per-frame ring depth,
// the MSAA sample count, and the render dims the snapshot is sized to.
#[derive(Clone, Copy)]
pub(in crate::vulkan) struct RaymarchTargetConfig {
    pub(in crate::vulkan) frames: usize,
    pub(in crate::vulkan) msaa_samples: vk::SampleCountFlags,
    pub(in crate::vulkan) width: u32,
    pub(in crate::vulkan) height: u32,
}

// Shared engine resources bound into the view sets (and the shadow view sets):
// the CSM shadow map, the IBL cubes + samplers, the scene-snapshot sampler, the
// light + shadow UBO rings, and the depth-only shadow render pass the
// shadow-caster pipelines target.
#[derive(Clone, Copy)]
pub(in crate::vulkan) struct RaymarchSharedBindings<'a> {
    pub(in crate::vulkan) shadow_map_view: vk::ImageView,
    pub(in crate::vulkan) shadow_sampler: vk::Sampler,
    pub(in crate::vulkan) irradiance_view: vk::ImageView,
    pub(in crate::vulkan) prefilter_view: vk::ImageView,
    pub(in crate::vulkan) cube_sampler: vk::Sampler,
    pub(in crate::vulkan) linear_sampler: vk::Sampler,
    // Per-frame-in-flight LightUniforms ring, indexed by frame slot.
    pub(in crate::vulkan) light_ubos: &'a [PooledBuffer],
    // Per-frame-in-flight ShadowUniforms ring, indexed by frame slot.
    pub(in crate::vulkan) shadow_ubos: &'a [PooledBuffer],
    pub(in crate::vulkan) shadow_render_pass: vk::RenderPass,
}

impl RaymarchResources {
    // Build every raymarch resource + the per-volume records. `sdf_volumes` is
    // the drained-and-payload-paired list from `graphics_system::init`; each
    // volume's `fragment_shader` path is checked here: `.glsl` payloads compile,
    // anything else (Metal-first `.metal` / DirectX `.hlsl`) is skipped with a
    // logged warning. Returns `Ok(None)` when no volume survived the filter so
    // the engine omits the pass.
    pub(in crate::vulkan) fn try_new(
        ctx: RaymarchDeviceContext,
        target: RaymarchTargetConfig,
        bindings: RaymarchSharedBindings,
        sdf_volumes: &[(SdfVolume, Vec<u8>, String)],
        hot_reload: bool,
    ) -> Result<Option<Self>, String> {
        let RaymarchDeviceContext {
            alloc,
            device,
            command_pool,
            queue,
        } = ctx;
        let RaymarchTargetConfig {
            frames,
            msaa_samples,
            width,
            height,
        } = target;
        let RaymarchSharedBindings {
            shadow_map_view,
            shadow_sampler,
            irradiance_view,
            prefilter_view,
            cube_sampler,
            linear_sampler,
            light_ubos,
            shadow_ubos,
            shadow_render_pass,
        } = bindings;
        // Every volume is this backend's: one distance field serves all three,
        // so there is no per-backend source to select between and nothing to
        // filter out. This used to drop anything not named `.glsl`.
        let active: Vec<&(SdfVolume, Vec<u8>, String)> = sdf_volumes.iter().collect();
        if active.is_empty() {
            return Ok(None);
        }

        let msaa = msaa_samples != vk::SampleCountFlags::TYPE_1;
        let (render_pass, main_store_color_pass) = if msaa {
            (
                create_main_render_pass_two_pass(device, HDR_FORMAT, msaa_samples, true)?,
                Some(create_main_render_pass_two_pass(
                    device,
                    HDR_FORMAT,
                    msaa_samples,
                    false,
                )?),
            )
        } else {
            (
                create_raymarch_render_pass_single(device, HDR_FORMAT)?,
                None,
            )
        };

        let view_set_layout = create_view_set_layout(device)?;
        let volume_set_layout = create_volume_set_layout(device)?;
        let set_layouts = [view_set_layout.handle(), volume_set_layout.handle()];
        let pipeline_layout = {
            let info = vk::PipelineLayoutCreateInfo::default().set_layouts(&set_layouts);
            device
                .create_pipeline_layout(&info)
                .map_err(|e| format!("raymarch pipeline layout: {e}"))?
        };

        let (cube_vb, cube_ib) = build_cube_buffers(alloc)?;

        let snapshot = create_snapshot(alloc, device, command_pool, queue, width, height)?;

        // Per-frame view UBO ring (HOST_VISIBLE | HOST_COHERENT, mapped).
        let view_size = std::mem::size_of::<RaymarchView>() as u64;
        let mut view_ubos = Vec::with_capacity(frames);
        for _ in 0..frames {
            view_ubos.push(alloc.create_buffer(
                view_size,
                vk::BufferUsageFlags::UNIFORM_BUFFER,
                vk::MemoryPropertyFlags::HOST_VISIBLE | vk::MemoryPropertyFlags::HOST_COHERENT,
            )?);
        }

        let has_shadow = active.iter().any(|(v, _, _)| v.cast_shadows);
        let descriptor_pool = create_descriptor_pool(device, frames, active.len(), has_shadow)?;
        let view_layouts: Vec<_> = (0..frames).map(|_| view_set_layout.handle()).collect();
        let view_sets = alloc_sets(device, descriptor_pool.handle(), &view_layouts)?;
        for (i, &set) in view_sets.iter().enumerate() {
            write_view_set(
                device,
                set,
                RaymarchViewSetBuffers {
                    view_ubo: view_ubos[i].buffer(),
                    light_ubo: light_ubos[i].buffer(),
                    shadow_ubo: shadow_ubos[i].buffer(),
                },
                RaymarchViewSetTextures {
                    shadow_map_view,
                    shadow_sampler,
                    irradiance_view,
                    prefilter_view,
                    cube_sampler,
                    snapshot_view: snapshot.view,
                    scene_sampler: linear_sampler,
                },
            );
        }

        // Shadow-caster infrastructure: a minimal 3-UBO view set with its own
        // per-frame `RaymarchView` ring (written by the Shadow pass, never the
        // concurrently-recorded Raymarch pass) + a pipeline layout carrying the
        // `cascade_idx` push constant. Built only when a volume casts shadows.
        let mut shadow_pipeline_layout = OwnedPipelineLayout::null();
        let mut shadow_view_set_layout = OwnedSetLayout::null();
        let mut shadow_view_ubos: Vec<PooledBuffer> = Vec::new();
        let mut shadow_view_sets: Vec<vk::DescriptorSet> = Vec::new();
        if has_shadow {
            shadow_view_set_layout = create_shadow_view_set_layout(device)?;
            let set_layouts = [shadow_view_set_layout.handle(), volume_set_layout.handle()];
            let push = vk::PushConstantRange::default()
                .stage_flags(vk::ShaderStageFlags::VERTEX | vk::ShaderStageFlags::FRAGMENT)
                .offset(0)
                .size(std::mem::size_of::<RaymarchShadowCascade>() as u32);
            let info = vk::PipelineLayoutCreateInfo::default()
                .set_layouts(&set_layouts)
                .push_constant_ranges(std::slice::from_ref(&push));
            shadow_pipeline_layout = device
                .create_pipeline_layout(&info)
                .map_err(|e| format!("raymarch shadow pipeline layout: {e}"))?;

            for _ in 0..frames {
                shadow_view_ubos.push(alloc.create_buffer(
                    view_size,
                    vk::BufferUsageFlags::UNIFORM_BUFFER,
                    vk::MemoryPropertyFlags::HOST_VISIBLE | vk::MemoryPropertyFlags::HOST_COHERENT,
                )?);
            }
            let shadow_layouts: Vec<_> = (0..frames)
                .map(|_| shadow_view_set_layout.handle())
                .collect();
            shadow_view_sets = alloc_sets(device, descriptor_pool.handle(), &shadow_layouts)?;
            for (i, &set) in shadow_view_sets.iter().enumerate() {
                write_shadow_view_set(
                    device,
                    set,
                    shadow_view_ubos[i].buffer(),
                    light_ubos[i].buffer(),
                    shadow_ubos[i].buffer(),
                );
            }
        }

        // Build per-volume records. A compile error in an active volume is a
        // developer-time bug, so it aborts init (unlike the .glsl filter above).
        let mut volumes: Vec<RaymarchVolumeRecord> = Vec::with_capacity(active.len());
        for (vol, payload, label) in &active {
            let programs = crate::raymarch_source::decode(payload, label)?;
            // A medium authors `sampleVolume` and renders alpha-blended without a
            // depth write; a surface volume authors `map` and `shade` and
            // sphere-traces an opaque surface. The asset's flag selects which.
            let pipeline = if vol.volumetric {
                let (vert_spv, frag_spv) =
                    family_spirv(&programs, Family::Volumetric, hot_reload, label)?;
                create_volumetric_pipeline(
                    device,
                    render_pass.handle(),
                    pipeline_layout.handle(),
                    msaa_samples,
                    &vert_spv,
                    &frag_spv,
                )?
            } else {
                let (vert_spv, frag_spv) =
                    family_spirv(&programs, Family::Surface, hot_reload, label)?;
                create_pipeline(
                    device,
                    render_pass.handle(),
                    pipeline_layout.handle(),
                    msaa_samples,
                    &vert_spv,
                    &frag_spv,
                )?
            };

            // Depth-only shadow caster when the asset opts in.
            let shadow_pipeline = if vol.cast_shadows {
                let (sh_vert, sh_frag) =
                    family_spirv(&programs, Family::Shadow, hot_reload, label)?;
                Some(create_shadow_pipeline(
                    device,
                    shadow_render_pass,
                    shadow_pipeline_layout.handle(),
                    &sh_vert,
                    &sh_frag,
                )?)
            } else {
                None
            };

            let uniforms = volume_uniforms_from(vol);
            let volume_ubo = alloc.create_buffer(
                std::mem::size_of::<RaymarchVolumeUniforms>() as u64,
                vk::BufferUsageFlags::UNIFORM_BUFFER,
                vk::MemoryPropertyFlags::HOST_VISIBLE | vk::MemoryPropertyFlags::HOST_COHERENT,
            )?;
            volume_ubo.write_val(0, &uniforms);
            let volume_set = alloc_sets(
                device,
                descriptor_pool.handle(),
                &[volume_set_layout.handle()],
            )?[0];
            write_volume_set(device, volume_set, volume_ubo.buffer());

            volumes.push(RaymarchVolumeRecord {
                pipeline,
                shadow_pipeline,
                _volume_ubo: volume_ubo,
                volume_set,
                visible: vol.visible,
                refractive: crate::raymarch_source::taps_scene(&programs),
            });
        }

        Ok(Some(Self {
            render_pass,
            main_store_color_pass,
            pipeline_layout,
            _view_set_layout: view_set_layout,
            _volume_set_layout: volume_set_layout,
            _descriptor_pool: descriptor_pool,
            view_ubos,
            view_sets,
            cube_vb,
            cube_ib,
            snapshot,
            scene_sampler: linear_sampler,
            shadow_pipeline_layout,
            _shadow_view_set_layout: shadow_view_set_layout,
            shadow_view_ubos,
            shadow_view_sets,
            msaa,
            volumes,
        }))
    }

    // True when any volume in the world is currently visible. Drives
    // `FrameGraphInputs::raymarch_enabled` and the encoder early-out.
    pub(in crate::vulkan) fn any_visible(&self) -> bool {
        self.volumes.iter().any(|v| v.visible)
    }

    // True when a visible volume reads the scene behind its surface, which is
    // the only thing the per-frame snapshot copy feeds. A world of opaque
    // volumes skips the copy and the layout transitions that bracket it.
    fn any_refractive_visible(&self) -> bool {
        self.volumes.iter().any(|v| v.visible && v.refractive)
    }

    // True when at least one visible volume opted into shadow casting (so its
    // `shadow_pipeline` was built). Gates the shadow-pass injection.
    fn any_shadow_casters(&self) -> bool {
        self.volumes
            .iter()
            .any(|v| v.visible && v.shadow_pipeline.is_some())
    }

    // Recreate the scene snapshot at new render dims + re-point the `scene_color`
    // binding of every view set. Called from the swapchain-resize handler; the
    // pipelines, layouts, UBOs, cube buffers, and render passes all survive.
    pub(in crate::vulkan) fn rebuild(
        &mut self,
        ctx: RaymarchDeviceContext,
        width: u32,
        height: u32,
    ) -> Result<(), String> {
        let RaymarchDeviceContext {
            alloc,
            device,
            command_pool,
            queue,
        } = ctx;
        let old = std::mem::replace(
            &mut self.snapshot,
            create_snapshot(alloc, device, command_pool, queue, width, height)?,
        );
        drop(old);
        for &set in &self.view_sets {
            let info = vk::DescriptorImageInfo::default()
                .image_layout(vk::ImageLayout::SHADER_READ_ONLY_OPTIMAL)
                .image_view(self.snapshot.view)
                .sampler(self.scene_sampler);
            let write = vk::WriteDescriptorSet::default()
                .dst_set(set)
                .dst_binding(6)
                .descriptor_type(vk::DescriptorType::COMBINED_IMAGE_SAMPLER)
                .image_info(std::slice::from_ref(&info));
            // SAFETY: `writes` and the buffer/image infos it borrows are live for the call, and
            // every set and resource it names belongs to this device.
            unsafe { device.update_descriptor_sets(std::slice::from_ref(&write), &[]) };
        }
        Ok(())
    }

    // Re-point the irradiance + prefilter cube bindings (set 0 bindings 4 + 5)
    // of every view set after an EnvironmentMap hot-reload swapped the IBL
    // cubes for fresh image views. The light / shadow / snapshot bindings and
    // the cube-less shadow-caster view sets are left untouched. Reached only
    // through the bin's `cn debug` env-map hot-reload path (dead in the FFI
    // lib, live in the bin).
    pub(in crate::vulkan) fn rewire_ibl_cubes(
        &self,
        device: &VkDevice,
        irradiance_view: vk::ImageView,
        prefilter_view: vk::ImageView,
        cube_sampler: vk::Sampler,
    ) {
        let irr_info = vk::DescriptorImageInfo::default()
            .image_layout(vk::ImageLayout::SHADER_READ_ONLY_OPTIMAL)
            .image_view(irradiance_view)
            .sampler(cube_sampler);
        let pre_info = vk::DescriptorImageInfo::default()
            .image_layout(vk::ImageLayout::SHADER_READ_ONLY_OPTIMAL)
            .image_view(prefilter_view)
            .sampler(cube_sampler);
        for &set in &self.view_sets {
            let writes = [
                vk::WriteDescriptorSet::default()
                    .dst_set(set)
                    .dst_binding(4)
                    .descriptor_type(vk::DescriptorType::COMBINED_IMAGE_SAMPLER)
                    .image_info(std::slice::from_ref(&irr_info)),
                vk::WriteDescriptorSet::default()
                    .dst_set(set)
                    .dst_binding(5)
                    .descriptor_type(vk::DescriptorType::COMBINED_IMAGE_SAMPLER)
                    .image_info(std::slice::from_ref(&pre_info)),
            ];
            // SAFETY: `writes` and the buffer/image infos it borrows are live for the call, and
            // every set and resource it names belongs to this device.
            unsafe { device.update_descriptor_sets(&writes, &[]) };
        }
    }

    // Destroy every owned GPU resource. The `scene_sampler` is borrowed from
    // `VkContext` and is not destroyed here.
    pub(in crate::vulkan) fn destroy(&mut self, _device: &VkDevice) {
        self.volumes.clear();
        self.view_ubos.clear();
        self.shadow_view_ubos.clear();
        self.snapshot = GpuImage::null();
        self.cube_vb = PooledBuffer::null();
        self.cube_ib = PooledBuffer::null();
    }
}

impl VkContext {
    // Assemble the per-frame raymarch view from the frame's jittered VP (the
    // matrix the main pass rasterised the depth buffer with) + camera position.
    pub(in crate::vulkan) fn build_raymarch_view(
        &self,
        vp: [[f32; 4]; 4],
        cam_pos: [f32; 3],
        time: f32,
    ) -> RaymarchView {
        RaymarchView {
            vp,
            inv_vp: mat4_inverse(vp),
            cam_pos: [cam_pos[0], cam_pos[1], cam_pos[2], 0.0],
            viewport: [
                self.render_extent.width as f32,
                self.render_extent.height as f32,
            ],
            time,
            prefilter_mip_count: self.prefilter_mip_count as f32,
            sky_rot: self.view.sky_rot,
        }
    }

    // Upload this frame's `view_time` into the shadow-caster view ring so the
    // from-light SDF march samples the same animation time as the live pass. A
    // no-op when no volume casts shadows. Called once per frame from the Shadow
    // pass, before the cascade loop; the dedicated ring (not the main view ring)
    // keeps this write off the concurrently-recorded Raymarch pass's buffer.
    pub(in crate::vulkan) fn upload_raymarch_shadow_view(&self, frame_idx: usize, elapsed: f32) {
        let Some(rm) = self.raymarch.as_ref() else {
            return;
        };
        if !rm.any_shadow_casters() {
            return;
        }
        let Some(ubo) = rm.shadow_view_ubos.get(frame_idx) else {
            return;
        };
        // Only `time` is read by the shadow shaders; the rest is inert padding.
        let view = RaymarchView {
            vp: [[0.0; 4]; 4],
            inv_vp: [[0.0; 4]; 4],
            cam_pos: [0.0; 4],
            viewport: [0.0, 0.0],
            time: elapsed,
            prefilter_mip_count: 0.0,
            sky_rot: concinnity_core::sky::SkyOrientation::IDENTITY_ROWS,
        };
        ubo.write_val(0, &view);
    }

    // Draw the visible SDF shadow casters into one CSM cascade. Called from the
    // Shadow pass inside each cascade's depth-only render pass, after the
    // rasterised casters: the cascade's LESS depth test keeps the nearer of the
    // rasterised vs raymarched occluder per texel. The viewport / scissor set by
    // the shadow pass persist (dynamic state), so this only rebinds the cube
    // geometry, the shadow pipeline, the shadow view + per-volume sets, and the
    // cascade push constant. A no-op when no volume casts shadows.
    pub(in crate::vulkan) fn encode_sdf_shadow_cascade(
        &self,
        cmd: vk::CommandBuffer,
        frame_idx: usize,
        cascade_idx: usize,
    ) {
        let Some(rm) = self.raymarch.as_ref() else {
            return;
        };
        if !rm.any_shadow_casters() || rm.shadow_view_sets.is_empty() {
            return;
        }
        let device = &self.device;
        let push = RaymarchShadowCascade {
            cascade_idx: cascade_idx as u32,
            _pad: [0; 3],
        };
        // SAFETY: `cmd` is a command buffer in the recording state, and every handle and slice
        // these commands name is live for the call.
        unsafe {
            device.cmd_bind_vertex_buffers(cmd, 0, &[rm.cube_vb.buffer()], &[0]);
            device.cmd_bind_index_buffer(cmd, rm.cube_ib.buffer(), 0, vk::IndexType::UINT16);
            device.cmd_bind_descriptor_sets(
                cmd,
                vk::PipelineBindPoint::GRAPHICS,
                rm.shadow_pipeline_layout.handle(),
                0,
                std::slice::from_ref(&rm.shadow_view_sets[frame_idx]),
                &[],
            );
            device.cmd_push_constants(
                cmd,
                rm.shadow_pipeline_layout.handle(),
                vk::ShaderStageFlags::VERTEX | vk::ShaderStageFlags::FRAGMENT,
                0,
                std::slice::from_raw_parts(
                    &push as *const RaymarchShadowCascade as *const u8,
                    std::mem::size_of::<RaymarchShadowCascade>(),
                ),
            );
            for vol in &rm.volumes {
                let Some(shadow_pipeline) = vol.shadow_pipeline.as_ref() else {
                    continue;
                };
                if !vol.visible {
                    continue;
                }
                device.cmd_bind_pipeline(
                    cmd,
                    vk::PipelineBindPoint::GRAPHICS,
                    shadow_pipeline.handle(),
                );
                device.cmd_bind_descriptor_sets(
                    cmd,
                    vk::PipelineBindPoint::GRAPHICS,
                    rm.shadow_pipeline_layout.handle(),
                    1,
                    std::slice::from_ref(&vol.volume_set),
                    &[],
                );
                device.cmd_draw_indexed(cmd, CUBE_INDEX_COUNT, 1, 0, 0, 0);
                self.inc_draw_calls(1);
            }
        }
    }

    // Encode the raymarched SDF volume pass. Runs after `AutoExposure` (which
    // sampled the pre-raymarch hdr_resolve) and before `Decals`. Snapshots the
    // resolved scene into `snapshot` for refractive taps, draws each visible
    // volume's proxy back faces into the MSAA colour + scene depth, and the
    // render pass resolves the combined colour into hdr_resolve (single-sample:
    // renders into hdr_resolve directly). Leaves hdr_resolve SHADER_READ_ONLY
    // and depth DEPTH_STENCIL_ATTACHMENT_OPTIMAL for the downstream stack.
    pub(in crate::vulkan) fn encode_raymarch(
        &self,
        cmd: vk::CommandBuffer,
        frame_idx: usize,
        view: &RaymarchView,
    ) -> Result<(), String> {
        let Some(rm) = self.raymarch.as_ref() else {
            return Ok(());
        };
        if !rm.any_visible() {
            return Ok(());
        }
        let device = &self.device;
        let extent = self.render_extent;
        let hdr_resolve = self
            .hdr_resolve_images
            .get(frame_idx)
            .ok_or("raymarch: hdr_resolve index OOB")?
            .image;
        let snapshot = rm.snapshot.image;
        // The snapshot feeds the scene tap and nothing else. Skipping it leaves
        // `snapshot` resting in SHADER_READ_ONLY, which is where its descriptor
        // already expects it, and leaves hdr_resolve untouched.
        let refract = rm.any_refractive_visible();

        // Upload this frame's view.
        rm.view_ubos
            .get(frame_idx)
            .ok_or("raymarch: view_ubos index OOB")?
            .write_val(0, view);

        let color_aspect = vk::ImageSubresourceRange {
            aspect_mask: vk::ImageAspectFlags::COLOR,
            base_mip_level: 0,
            level_count: 1,
            base_array_layer: 0,
            layer_count: 1,
        };
        let barrier = |image: vk::Image,
                       old: vk::ImageLayout,
                       new: vk::ImageLayout,
                       src: vk::AccessFlags,
                       dst: vk::AccessFlags| {
            vk::ImageMemoryBarrier::default()
                .src_access_mask(src)
                .dst_access_mask(dst)
                .old_layout(old)
                .new_layout(new)
                .src_queue_family_index(vk::QUEUE_FAMILY_IGNORED)
                .dst_queue_family_index(vk::QUEUE_FAMILY_IGNORED)
                .image(image)
                .subresource_range(color_aspect)
        };

        // 1) Snapshot the resolved scene for the refraction tap. The src scopes
        // order AutoExposure's compute read + the previous frame's fragment
        // read ahead of the transfer.
        if refract {
            copy_scene_snapshot(device, cmd, hdr_resolve, snapshot, extent);
        }

        // 2) Close the snapshot for the fragment read, order the main pass's
        // colour + depth writes (and the copy read of hdr_resolve) ahead of the
        // render pass's attachment load + resolve, and (single-sample only)
        // restore hdr_resolve to SHADER_READ_ONLY so the render pass's colour
        // load matches its declared initial layout.
        let snapshot_to_read = barrier(
            snapshot,
            vk::ImageLayout::TRANSFER_DST_OPTIMAL,
            vk::ImageLayout::SHADER_READ_ONLY_OPTIMAL,
            vk::AccessFlags::TRANSFER_WRITE,
            vk::AccessFlags::SHADER_READ,
        );
        let load_barrier = vk::MemoryBarrier::default()
            .src_access_mask(
                vk::AccessFlags::COLOR_ATTACHMENT_WRITE
                    | vk::AccessFlags::DEPTH_STENCIL_ATTACHMENT_WRITE
                    | vk::AccessFlags::TRANSFER_READ,
            )
            .dst_access_mask(
                vk::AccessFlags::COLOR_ATTACHMENT_READ
                    | vk::AccessFlags::COLOR_ATTACHMENT_WRITE
                    | vk::AccessFlags::DEPTH_STENCIL_ATTACHMENT_READ
                    | vk::AccessFlags::DEPTH_STENCIL_ATTACHMENT_WRITE,
            );
        // Single-sample also restores hdr_resolve to SHADER_READ_ONLY for the
        // render pass's colour load; MSAA leaves it as the resolve target, so
        // only the snapshot barrier applies, and a skipped copy needs neither.
        // Build both on the stack and slice, avoiding a per-frame allocation.
        let hdr_to_read = barrier(
            hdr_resolve,
            vk::ImageLayout::TRANSFER_SRC_OPTIMAL,
            vk::ImageLayout::SHADER_READ_ONLY_OPTIMAL,
            vk::AccessFlags::TRANSFER_READ,
            vk::AccessFlags::COLOR_ATTACHMENT_READ,
        );
        let image_barriers = [snapshot_to_read, hdr_to_read];
        let image_barriers = match (refract, rm.msaa) {
            // No copy ran, so neither image left the layout it rests in.
            (false, _) => &image_barriers[..0],
            (true, true) => &image_barriers[..1],
            (true, false) => &image_barriers[..],
        };
        // SAFETY: `cmd` is a command buffer in the recording state, and every handle and slice
        // these commands name is live for the call.
        unsafe {
            device.cmd_pipeline_barrier(
                cmd,
                vk::PipelineStageFlags::TRANSFER
                    | vk::PipelineStageFlags::COLOR_ATTACHMENT_OUTPUT
                    | vk::PipelineStageFlags::LATE_FRAGMENT_TESTS,
                vk::PipelineStageFlags::FRAGMENT_SHADER
                    | vk::PipelineStageFlags::COLOR_ATTACHMENT_OUTPUT
                    | vk::PipelineStageFlags::EARLY_FRAGMENT_TESTS,
                vk::DependencyFlags::empty(),
                std::slice::from_ref(&load_barrier),
                &[],
                image_barriers,
            );
        }

        // 3) The render pass: LOAD the scene colour + depth, draw each visible
        // volume, then resolve (MSAA) / store (single-sample) into hdr_resolve.
        let rp_begin = vk::RenderPassBeginInfo::default()
            .render_pass(rm.render_pass.handle())
            .framebuffer(self.framebuffers[frame_idx].handle())
            .render_area(vk::Rect2D::default().extent(extent));
        // Negative-height viewport: matches the main pass so the proxy rasterises
        // into identical pixels and the reprojected hit depth shares its space.
        let vp = vk::Viewport {
            x: 0.0,
            y: extent.height as f32,
            width: extent.width as f32,
            height: -(extent.height as f32),
            min_depth: 0.0,
            max_depth: 1.0,
        };
        let scissor = vk::Rect2D::default().extent(extent);
        // SAFETY: `cmd` is a command buffer in the recording state, and every handle and slice
        // these commands name is live for the call.
        unsafe {
            device.cmd_begin_render_pass(cmd, &rp_begin, vk::SubpassContents::INLINE);
            device.cmd_set_viewport(cmd, 0, std::slice::from_ref(&vp));
            device.cmd_set_scissor(cmd, 0, std::slice::from_ref(&scissor));
            device.cmd_bind_vertex_buffers(cmd, 0, &[rm.cube_vb.buffer()], &[0]);
            device.cmd_bind_index_buffer(cmd, rm.cube_ib.buffer(), 0, vk::IndexType::UINT16);
            device.cmd_bind_descriptor_sets(
                cmd,
                vk::PipelineBindPoint::GRAPHICS,
                rm.pipeline_layout.handle(),
                0,
                std::slice::from_ref(&rm.view_sets[frame_idx]),
                &[],
            );
            for vol in &rm.volumes {
                if !vol.visible {
                    continue;
                }
                device.cmd_bind_pipeline(
                    cmd,
                    vk::PipelineBindPoint::GRAPHICS,
                    vol.pipeline.handle(),
                );
                device.cmd_bind_descriptor_sets(
                    cmd,
                    vk::PipelineBindPoint::GRAPHICS,
                    rm.pipeline_layout.handle(),
                    1,
                    std::slice::from_ref(&vol.volume_set),
                    &[],
                );
                device.cmd_draw_indexed(cmd, CUBE_INDEX_COUNT, 1, 0, 0, 0);
                self.inc_draw_calls(1);
            }
            device.cmd_end_render_pass(cmd);
        }
        Ok(())
    }
}