concinnity-device 0.19.119

//! Per-frame encoder for the raymarched SDF volume pass on D3D12. Runs at
//! `PassId::Raymarch`, between `AutoExposure` and `Decals` on the
//! hdr_resolve RMW chain. Each `SdfVolume` rasterizes one face set of
//! its world-space bounding box and runs a user-authored HLSL fragment
//! shader that sphere-traces the SDF inside the box. HLSL port of
//! `src/metal/raymarch.rs`: same shader interface, same
//! depth-compositing rules.
//!
//! DX architecture:
//!   * One `ID3D12PipelineState` per `SdfVolume` (built at init from the
//!     engine-shipped helpers + the user's HLSL bytes + the engine-shipped
//!     template). The wrap order is helpers → user → template so the
//!     template's `raymarch_fragment` can call the user's `map` / `shade`
//!     through the forward declarations in the helpers.
//!   * One shared unit-cube VB + IB for the proxy geometry; 8 corners /
//!     36 indices, allocated once at init. A surface volume has a PSO per
//!     face set and draws its front faces when the camera is clear of the
//!     box, its back faces otherwise; either way one fragment per pixel.
//!   * Per-volume `SdfVolumeUniforms` cbuffer (static: `center`, `extent`,
//!     `params`, ... don't change frame-to-frame) allocated once at init.
//!   * Per-frame `RaymarchView` cbuffer ring (triple-buffered).
//!   * Color attachment = `hdr_resolve` (LOAD, opaque write). Depth
//!     attachment = the main depth buffer in `DEPTH_WRITE`: the fragment
//!     writes hit depth as conservative depth so downstream passes
//!     (decals, fog, SSR, TAA, ...) see the raymarched surface.
//!
//! Every `SdfVolume` builds here from its one distance-field payload, the same
//! payload the other backends consume. `try_new` returns `Ok(None)` only when the
//! world declares no volumes; a payload decode or pipeline compile failure aborts
//! init.
//!
//! Currently unimplemented on DirectX:
//!   * No `depth_copy` snapshot, so no in-shader rasterized-depth early-
//!     out (hardware depth test still composites correctly: see the
//!     template's caveat). Volumes whose bbox sits fully behind
//!     rasterized geometry pay the full march cost.

use concinnity_core::components::sdf_programs::SdfPrograms;
use concinnity_core::components::sdf_volume::SdfVolume;
use concinnity_core::gfx::mesh_payload::Vertex;
use concinnity_core::gfx::render_types;
use concinnity_core::gfx::render_types::LightUniforms;
use concinnity_core::platform::Platform;
use concinnity_core::render::backend_init::SdfVolumeSource;
use concinnity_core::render::error::{RenderError, RenderResult};
use concinnity_core::render::shader_programs::raymarch::{Family, ProxyFaces, VolumeFlags};
use std::ffi::c_void;
use windows::Win32::Graphics::Direct3D::D3D_PRIMITIVE_TOPOLOGY_TRIANGLELIST;
use windows::Win32::Graphics::Direct3D12::*;
use windows::Win32::Graphics::Dxgi::Common::*;
// One declaration for all three backends, in `core::render::uniforms`.
// Re-exported so `crate::directx::raymarch::{RaymarchView, RaymarchVolumeUniforms}`
// stay the paths the encode and `volume_uniforms_from` sites use.
pub(in crate::directx) use concinnity_core::render::uniforms::{
    RaymarchView, RaymarchVolumeUniforms,
};

use concinnity_core::render::uniforms::{GBufferView, PassCamera};
use concinnity_core::transform::mat4_inverse;

use super::allocator::{DeviceAllocator, PooledBuffer, PooledTexture};
use super::post::gbuffer::GbufferPrepassView;
use crate::directx::com;
use crate::directx::context::{DxContext, FRAMES, align256, dump_on_err};
use crate::directx::depth::shadow_sample_compare;
use crate::directx::descriptor_slot::DescriptorTables;
use crate::directx::descriptor_slot::{SamplerSlot, SrvSlot};
use crate::directx::error::{map_hresult, map_pso_hresult};
use crate::directx::pipeline::main_input_layout;
use crate::directx::pso::{Blend, Cull, Depth, GraphicsPso, Raster};
use crate::directx::root_constants::RootConstants;
use crate::directx::root_sig::{RootSig, Visibility};
use crate::directx::texture::{
    HDR_FORMAT, create_fallback_white_resource, create_hdr_resolve_target, transition_barrier,
};
use crate::shader::raymarch_source::{face_artifacts, family_artifacts};

mod swap;

fn volume_uniforms_from(v: &SdfVolume) -> RaymarchVolumeUniforms {
    RaymarchVolumeUniforms {
        center: v.center,
        _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,
    }
}

// Per-`SdfVolume` GPU state: the compiled render pipeline, the static
// per-volume cbuffer (uploaded once at init) and the optional
// shadow-cast PSO.
pub(in crate::directx) struct RaymarchVolumeRecord {
    // The volume's asset name, for pipeline errors.
    pub(in crate::directx) label: String,
    // A surface's is the back-face variant; `front_pso` is the other.
    pub(in crate::directx) pso: ID3D12PipelineState,
    // The surface's front-face PSO; `None` for a medium.
    pub(in crate::directx) front_pso: Option<ID3D12PipelineState>,
    // Depth-only shadow PSO. `Some` when the asset's `cast_shadows`
    // is true at init; the shadow encoder iterates only the records
    // where this is `Some` AND `visible` AND `cast_shadows` (the
    // runtime flag, currently can't toggle, but the field is
    // preserved for future runtime mutation).
    pub(in crate::directx) shadow_pso: Option<ID3D12PipelineState>,
    // The surface's G-buffer pre-pass PSOs; `None` for a medium.
    pub(in crate::directx) prepass_psos: Option<FacePsos>,
    // Per-volume cbuffer (CPU-visible upload heap, written once at build
    // time and never modified: the asset's center / extent / params are
    // static). Held because `volume_cbuffer_gva` below is only valid while
    // this buffer is alive.
    #[expect(
        dead_code,
        reason = "held to keep the GPU memory alive; the encoder binds through volume_cbuffer_gva"
    )]
    volume_cbuffer: PooledBuffer,
    pub(in crate::directx) volume_cbuffer_gva: u64,
    pub(in crate::directx) visible: bool,
    pub(in crate::directx) volumetric: bool,
    pub(in crate::directx) cast_shadows: bool,
    // Whether the authored field samples the scene behind the surface. The
    // pass copies the scene spine into `hdr_resolve_copy` only when some
    // visible volume does; the `scene_color` SRV stands either way, so this
    // selects no PSO variant.
    pub(in crate::directx) refractive: bool,
    // The world-space bounding box, which decides the faces the proxy draws.
    pub(in crate::directx) center: [f32; 3],
    pub(in crate::directx) extent: [f32; 3],
}

// A surface family's PSO per set of proxy faces.
pub(in crate::directx) struct FacePsos {
    pub(in crate::directx) front: ID3D12PipelineState,
    pub(in crate::directx) back: ID3D12PipelineState,
}

impl FacePsos {
    fn get(&self, faces: ProxyFaces) -> &ID3D12PipelineState {
        match faces {
            ProxyFaces::Front => &self.front,
            ProxyFaces::Back => &self.back,
        }
    }
}

impl RaymarchVolumeRecord {
    // The faces this volume's proxy draws with from `view`: a medium always
    // takes the back faces.
    fn faces(&self, view: &RaymarchView) -> ProxyFaces {
        if self.volumetric {
            ProxyFaces::Back
        } else {
            ProxyFaces::for_box(view, self.center, self.extent)
        }
    }

    // The PSO the volume's own draw takes from `view`.
    fn draw_pso(&self, view: &RaymarchView) -> &ID3D12PipelineState {
        match (self.faces(view), &self.front_pso) {
            (ProxyFaces::Front, Some(front)) => front,
            _ => &self.pso,
        }
    }
}

// Engine-side raymarch resources: shared cube buffers, per-frame view
// cbuffer ring, scene-color fallback texture, root signature, per-
// volume records. Built only when at least one `SdfVolume` landed at
// init; the encoder is a no-op otherwise.
pub(in crate::directx) struct RaymarchResources {
    pub(in crate::directx) root_sig: ID3D12RootSignature,
    // Depth-only root signature for raymarched shadow casters. Only
    // binds the cbuffers the shadow template needs (no SRV / sampler
    // tables) plus a 1-DWORD cascade index root constant.
    pub(in crate::directx) shadow_root_sig: ID3D12RootSignature,
    // Shared unit-cube proxy geometry (vertices in ±1; the vertex
    // shader scales by `vol_extent`). Held only to keep the resources
    // resident; the encoder binds them through the `_view` siblings.
    #[expect(
        dead_code,
        reason = "held to keep the cube geometry resident; the encoder binds cube_vbv"
    )]
    cube_vb: PooledBuffer,
    #[expect(
        dead_code,
        reason = "held to keep the cube geometry resident; the encoder binds cube_ibv"
    )]
    cube_ib: PooledBuffer,
    cube_vbv: D3D12_VERTEX_BUFFER_VIEW,
    cube_ibv: D3D12_INDEX_BUFFER_VIEW,
    // Per-frame `RaymarchView` cbuffer ring. Persistently mapped; the
    // encoder memcpys this frame's view into `view_ptrs[frame_idx]`
    // before binding `view_cbuffers[frame_idx]` at b0.
    view_cbuffers: Vec<PooledBuffer>,
    view_ptrs: Vec<*mut u8>,
    // The G-buffer pre-pass's own view ring: its block rasterizes through the
    // pre-pass's VP and carries the motion matrices, and the pre-pass records
    // concurrently with the main raymarch pass.
    prepass_view_cbuffers: Vec<PooledBuffer>,
    prepass_view_ptrs: Vec<*mut u8>,
    // 1×1 white fallback for the `scene_color` SRV slot, kept around
    // only to hold a resource open while init runs; the live SRV at
    // `scene_color_srv_cpu` is rewritten to point at `hdr_resolve_copy`
    // (below) before the first frame.
    #[expect(
        dead_code,
        reason = "holds the scene_color slot open during init; the live SRV is re-pointed before the first frame"
    )]
    scene_color_fallback: PooledTexture,
    // Pre-raymarch HDR scene snapshot. At the top of `encode_raymarch`
    // we `CopyResource` from `hdr_resolve` (or `hdr_color` when MSAA
    // is off) into this resource, so refractive user shaders that
    // sample `scene_color` through `sampleSceneRefracted` see the
    // scene as it stood after Main + AutoExposure but before raymarch
    // itself writes / decals / fog / particles. Sized to render dims;
    // recreated by `resize_to` on window resize. Mirrors the Metal
    // `hdr_resolve_copy` snapshot.
    hdr_resolve_copy: ID3D12Resource,
    // CPU descriptor handle of the `scene_color` SRV slot, captured
    // at init so `resize_to` can rewrite the descriptor in place after
    // recreating `hdr_resolve_copy` (the GPU handle stays valid since
    // the heap slot itself doesn't move).
    scene_color_srv_cpu: D3D12_CPU_DESCRIPTOR_HANDLE,
    // GPU descriptor handle for the start of the 5-SRV descriptor
    // table the pixel shader binds at t0..t4 (main_depth, shadow_map,
    // irradiance, prefilter, scene_color). Written at init by
    // `write_raymarch_srvs`; live for the renderer's lifetime.
    pub(in crate::directx) srv_table_gpu: SrvSlot,
    // GPU descriptor handle for the start of the 3-sampler descriptor
    // table at s0..s2 (shadow_samp, cube_samp, scene_samp).
    pub(in crate::directx) sampler_table_gpu: SamplerSlot,
    // Per-volume records. Drained from the world's `SdfVolume`s at init.
    pub(in crate::directx) volumes: Vec<RaymarchVolumeRecord>,
}

// Root signature shared by every per-volume raymarch PSO.
//
//   [0] CBV b0 (RaymarchView)            : root descriptor
//   [1] CBV b1 (SdfVolumeUniforms)       : root descriptor
//   [2] CBV b2 (RaymarchLights)          : root descriptor
//   [3] CBV b3 (RaymarchShadowUniforms)  : root descriptor
//   [4] Descriptor table SRV  t0..t3     : shadow / IBL / scene fallback
//   [5] Descriptor table Sampler s0..s2  : shadow_samp / cube_samp / scene_samp
fn create_raymarch_root_signature(device: &ID3D12Device) -> RenderResult<ID3D12RootSignature> {
    use Visibility::{All, Pixel};
    RootSig::new()
        .cbv(0, All)
        .cbv(1, All)
        .cbv(2, Pixel)
        .cbv(3, Pixel)
        .srv_table(0, 4, Pixel) // t0..t3 (shadow_map, irradiance, prefilter, scene_color)
        .sampler_table(0, 3, Pixel) // s0..s2
        .input_layout()
        .build(device, "raymarch root sig")
}

// Build the per-volume PSO drawing the proxy's `faces`. Depth attachment is
// the main scene depth (D32_FLOAT); the shader writes hit depth as
// conservative depth so downstream passes see raymarched-surface depth.
fn create_raymarch_pso(
    device: &ID3D12Device,
    root_sig: &ID3D12RootSignature,
    (vs, ps): (&[u8], &[u8]),
    faces: ProxyFaces,
    msaa_samples: u32,
) -> RenderResult<ID3D12PipelineState> {
    let input_layout = main_input_layout();
    // Hardware z-test against the existing MSAA main depth, and write
    // hit depth back as conservative depth so downstream
    // depth-sampling passes (decals, fog, SSR) see the raymarched
    // surface. Renders into the MSAA `hdr_color` target so the depth
    // sample-count matches; the encoder re-resolves `hdr_color →
    // hdr_resolve` after the pass.
    GraphicsPso::new(root_sig, vs, ps)
        .input_layout(&input_layout)
        .target(HDR_FORMAT, Blend::Opaque)
        .depth(DXGI_FORMAT_D32_FLOAT, Depth::write_inclusive())
        .samples(msaa_samples.max(1))
        .raster(proxy_raster(msaa_samples > 1, faces))
        .build(device, "raymarch")
}

// The proxy cube's rasterizer, culling the face set `faces` does not draw. The
// cube winds its outward faces counterclockwise, as every engine mesh does.
fn proxy_raster(multisample: bool, faces: ProxyFaces) -> Raster {
    Raster {
        cull: match faces {
            ProxyFaces::Front => Cull::Back,
            ProxyFaces::Back => Cull::Front,
        },
        multisample,
        ..Raster::default()
    }
}

// Compile a surface volume's PSO drawing the proxy's `faces`.
fn compile_volume_pso(
    t: &VolumePsoTargets<'_>,
    programs: &SdfPrograms,
    asset_label: &str,
    faces: ProxyFaces,
) -> RenderResult<ID3D12PipelineState> {
    let (vs, ps) = face_artifacts(
        programs,
        Family::Surface,
        faces,
        Platform::DirectX,
        t.hot_reload,
        asset_label,
    )?;
    create_raymarch_pso(t.device, t.root_sig, (&vs, &ps), faces, t.msaa_samples)
}

// Volumetric variant of the raymarch PSO: same root signature + same
// vertex layout (cube proxy back faces), but the color output
// alpha-blends over the existing scene and the depth stencil keeps
// early-z through the read-only camera test: volumetrics are
// translucent and never update the depth buffer.
fn create_raymarch_volumetric_pso(
    device: &ID3D12Device,
    root_sig: &ID3D12RootSignature,
    vs: &[u8],
    ps: &[u8],
    msaa_samples: u32,
) -> RenderResult<ID3D12PipelineState> {
    let input_layout = main_input_layout();
    let rasterizer = D3D12_RASTERIZER_DESC {
        FillMode: D3D12_FILL_MODE_SOLID,
        CullMode: D3D12_CULL_MODE_FRONT,
        FrontCounterClockwise: windows::core::BOOL(1),
        DepthBias: 0,
        DepthBiasClamp: 0.0,
        SlopeScaledDepthBias: 0.0,
        DepthClipEnable: windows::core::BOOL(1),
        MultisampleEnable: windows::core::BOOL(if msaa_samples > 1 { 1 } else { 0 }),
        AntialiasedLineEnable: windows::core::BOOL(0),
        ForcedSampleCount: 0,
        ConservativeRaster: D3D12_CONSERVATIVE_RASTERIZATION_MODE_OFF,
    };

    let mut blend = D3D12_BLEND_DESC {
        AlphaToCoverageEnable: windows::core::BOOL(0),
        IndependentBlendEnable: windows::core::BOOL(0),
        RenderTarget: [D3D12_RENDER_TARGET_BLEND_DESC::default(); 8],
    };
    blend.RenderTarget[0] = D3D12_RENDER_TARGET_BLEND_DESC {
        BlendEnable: windows::core::BOOL(1),
        LogicOpEnable: windows::core::BOOL(0),
        SrcBlend: D3D12_BLEND_SRC_ALPHA,
        DestBlend: D3D12_BLEND_INV_SRC_ALPHA,
        BlendOp: D3D12_BLEND_OP_ADD,
        SrcBlendAlpha: D3D12_BLEND_ONE,
        DestBlendAlpha: D3D12_BLEND_INV_SRC_ALPHA,
        BlendOpAlpha: D3D12_BLEND_OP_ADD,
        LogicOp: D3D12_LOGIC_OP_NOOP,
        RenderTargetWriteMask: D3D12_COLOR_WRITE_ENABLE_ALL.0 as u8,
    };

    // Early-z against the bbox far face, but no depth write: the
    // medium doesn't occlude itself or update SSR/decal depth.
    let depth_stencil = Depth::read_only().raw();

    let mut rtv_formats = [DXGI_FORMAT_UNKNOWN; 8];
    rtv_formats[0] = HDR_FORMAT;
    let desc = D3D12_GRAPHICS_PIPELINE_STATE_DESC {
        pRootSignature: com::borrowed(root_sig),
        VS: D3D12_SHADER_BYTECODE {
            pShaderBytecode: vs.as_ptr() as _,
            BytecodeLength: vs.len(),
        },
        PS: D3D12_SHADER_BYTECODE {
            pShaderBytecode: ps.as_ptr() as _,
            BytecodeLength: ps.len(),
        },
        BlendState: blend,
        SampleMask: u32::MAX,
        RasterizerState: rasterizer,
        DepthStencilState: depth_stencil,
        InputLayout: D3D12_INPUT_LAYOUT_DESC {
            pInputElementDescs: input_layout.as_ptr(),
            NumElements: input_layout.len() as u32,
        },
        PrimitiveTopologyType: D3D12_PRIMITIVE_TOPOLOGY_TYPE_TRIANGLE,
        NumRenderTargets: 1,
        RTVFormats: rtv_formats,
        DSVFormat: DXGI_FORMAT_D32_FLOAT,
        SampleDesc: DXGI_SAMPLE_DESC {
            Count: msaa_samples.max(1),
            Quality: 0,
        },
        ..Default::default()
    };
    // SAFETY: `desc` outlives this synchronous call, and so do the root signature, shader bytecode
    // and input-element array whose raw pointers it borrows.
    unsafe { crate::directx::pso_library::create_graphics(device, &desc) }
        .map_err(|e| map_pso_hresult(e.code(), "create raymarch volumetric PSO"))
}

// Volumetric counterpart of `compile_volume_pso`. Wraps the user
// source with the volumetric template, compiles the vol-specific
// entry points, and builds the alpha-blended PSO.
fn compile_volume_volumetric_pso(
    device: &ID3D12Device,
    root_sig: &ID3D12RootSignature,
    programs: &SdfPrograms,
    asset_label: &str,
    msaa_samples: u32,
    hot_reload: bool,
) -> RenderResult<ID3D12PipelineState> {
    let (vs, ps) = family_artifacts(
        programs,
        Family::Volumetric,
        Platform::DirectX,
        hot_reload,
        asset_label,
    )?;
    create_raymarch_volumetric_pso(device, root_sig, &vs, &ps, msaa_samples)
}

// Root signature for the depth-only shadow PSO. Smaller surface than
// the main pass: no SRV / sampler tables since the shadow template
// only marches the SDF and writes depth.
//
//   [0] CBV b0 (RaymarchView)            : root descriptor
//   [1] CBV b1 (SdfVolumeUniforms)       : root descriptor
//   [2] CBV b2 (RaymarchLights)          : root descriptor
//   [3] CBV b3 (RaymarchShadowUniforms)  : root descriptor
//   [4] Root constants b4 (cascade_idx)  : 4 DWORDs
fn create_raymarch_shadow_root_signature(
    device: &ID3D12Device,
) -> RenderResult<ID3D12RootSignature> {
    use Visibility::{All, Pixel};
    RootSig::new()
        .cbv(0, All)
        .cbv(1, All)
        // Lights cbuffer is read by the pixel stage only (ray dir).
        .cbv(2, Pixel)
        // Shadow VPs read by both stages (VS projects through the
        // cascade VP, PS reprojects the hit through the same matrix).
        .cbv(3, All)
        .constants::<[u32; 4]>(4, All)
        .input_layout()
        .build(device, "raymarch shadow root sig")
}

// Build the depth-only shadow PSO for one volume. No RTV, no MSAA
// (shadow map is single-sample), front-face cull so back-face
// fragments produce rays through the bbox. Writes hit depth through the
// conservative-depth semantic; the writable shadow DSV at draw time supplies
// the comparison. Format matches the existing `create_shadow_pso`:
// D32_FLOAT, sample count 1.
fn create_raymarch_shadow_pso(
    device: &ID3D12Device,
    root_sig: &ID3D12RootSignature,
    vs: &[u8],
    ps: &[u8],
) -> RenderResult<ID3D12PipelineState> {
    let input_layout = main_input_layout();
    GraphicsPso::new(root_sig, vs, ps)
        .input_layout(&input_layout)
        .depth(DXGI_FORMAT_D32_FLOAT, Depth::write())
        .raster(proxy_raster(false, ProxyFaces::Back))
        .build(device, "raymarch shadow")
}

// Compile and link the per-volume shadow PSO. Mirrors `compile_volume_pso`
// for the main pass; uses the shadow template + shadow root sig.
fn compile_volume_shadow_pso(
    device: &ID3D12Device,
    root_sig: &ID3D12RootSignature,
    programs: &SdfPrograms,
    asset_label: &str,
    hot_reload: bool,
) -> RenderResult<ID3D12PipelineState> {
    let (vs, ps) = family_artifacts(
        programs,
        Family::Shadow,
        Platform::DirectX,
        hot_reload,
        asset_label,
    )?;
    create_raymarch_shadow_pso(device, root_sig, &vs, &ps)
}

// Build a surface volume's G-buffer pre-pass PSO: the pre-pass's three color
// targets over its private single-sample depth, on the shadow family's root
// signature, whose four constant buffers are everything the pre-pass family
// reads. Same proxy rasterizer and inclusive depth test as the main draw.
fn compile_volume_prepass_pso(
    t: &VolumePsoTargets<'_>,
    programs: &SdfPrograms,
    asset_label: &str,
    faces: ProxyFaces,
) -> RenderResult<ID3D12PipelineState> {
    let (vs, ps) = face_artifacts(
        programs,
        Family::Prepass,
        faces,
        Platform::DirectX,
        t.hot_reload,
        asset_label,
    )?;
    let input_layout = main_input_layout();
    crate::directx::post::gbuffer::gbuffer_targets(
        GraphicsPso::new(t.shadow_root_sig, &vs, &ps).input_layout(&input_layout),
    )
    .depth(DXGI_FORMAT_D32_FLOAT, Depth::write_inclusive())
    .raster(proxy_raster(false, faces))
    .build(t.device, "raymarch prepass")
}

// What a volume's PSOs are built against: the device, the pass's two root
// signatures, and the target configuration the pass was built with.
pub(in crate::directx) struct VolumePsoTargets<'a> {
    pub(in crate::directx) device: &'a ID3D12Device,
    pub(in crate::directx) info_queue: Option<&'a ID3D12InfoQueue>,
    pub(in crate::directx) root_sig: &'a ID3D12RootSignature,
    pub(in crate::directx) shadow_root_sig: &'a ID3D12RootSignature,
    pub(in crate::directx) msaa_samples: u32,
    pub(in crate::directx) hot_reload: bool,
}

// Every PSO one volume draws with: its own (both face sets for a surface), its
// shadow caster when it casts one, and its G-buffer pre-pass share when it is a
// surface.
pub(in crate::directx) struct VolumePsos {
    pub(in crate::directx) pso: ID3D12PipelineState,
    pub(in crate::directx) front_pso: Option<ID3D12PipelineState>,
    pub(in crate::directx) shadow_pso: Option<ID3D12PipelineState>,
    pub(in crate::directx) prepass_psos: Option<FacePsos>,
}

// Build the PSOs of a volume with these flags from its compiled field. A
// medium authors `sampleVolume` and blends without a depth write; a surface
// volume authors `map` and `shade` and writes an opaque surface.
pub(in crate::directx) fn build_volume_psos(
    t: &VolumePsoTargets<'_>,
    programs: &SdfPrograms,
    flags: VolumeFlags,
    label: &str,
) -> RenderResult<VolumePsos> {
    let surface = |faces| dump_on_err(t.info_queue, compile_volume_pso(t, programs, label, faces));
    let (pso, front_pso) = if flags.volumetric {
        let medium = dump_on_err(
            t.info_queue,
            compile_volume_volumetric_pso(
                t.device,
                t.root_sig,
                programs,
                label,
                t.msaa_samples,
                t.hot_reload,
            ),
        )?;
        (medium, None)
    } else {
        (
            surface(ProxyFaces::Back)?,
            Some(surface(ProxyFaces::Front)?),
        )
    };
    let shadow_pso = if flags.casts() {
        Some(dump_on_err(
            t.info_queue,
            compile_volume_shadow_pso(t.device, t.shadow_root_sig, programs, label, t.hot_reload),
        )?)
    } else {
        None
    };
    let prepass = |faces| {
        dump_on_err(
            t.info_queue,
            compile_volume_prepass_pso(t, programs, label, faces),
        )
    };
    let prepass_psos = if flags.volumetric {
        None
    } else {
        Some(FacePsos {
            front: prepass(ProxyFaces::Front)?,
            back: prepass(ProxyFaces::Back)?,
        })
    };
    Ok(VolumePsos {
        pso,
        front_pso,
        shadow_pso,
        prepass_psos,
    })
}

// Build the shared unit-cube proxy geometry. 8 corners at ±1; 36 CCW
// indices.
// The vertex shader scales positions by `vol_extent` to land at the
// AABB corners, matching the asset semantic where `extent` is the
// half-widths.
fn build_cube_buffers(
    alloc: &DeviceAllocator,
) -> RenderResult<(
    PooledBuffer,
    PooledBuffer,
    D3D12_VERTEX_BUFFER_VIEW,
    D3D12_INDEX_BUFFER_VIEW,
)> {
    #[rustfmt::skip]
    let corners: [Vertex; 8] = [
        v([-1.0, -1.0, -1.0]),
        v([ 1.0, -1.0, -1.0]),
        v([ 1.0,  1.0, -1.0]),
        v([-1.0,  1.0, -1.0]),
        v([-1.0, -1.0,  1.0]),
        v([ 1.0, -1.0,  1.0]),
        v([ 1.0,  1.0,  1.0]),
        v([-1.0,  1.0,  1.0]),
    ];
    #[rustfmt::skip]
    let indices: [u16; 36] = [
        // -Z
        0, 2, 1,  0, 3, 2,
        // +Z
        4, 5, 6,  4, 6, 7,
        // -X
        0, 4, 7,  0, 7, 3,
        // +X
        1, 2, 6,  1, 6, 5,
        // -Y
        0, 1, 5,  0, 5, 4,
        // +Y
        3, 7, 6,  3, 6, 2,
    ];

    let vb_bytes = std::mem::size_of_val(&corners) as u64;
    let ib_bytes = std::mem::size_of_val(&indices) as u64;

    let vb = alloc.alloc_buffer(
        vb_bytes,
        D3D12_HEAP_TYPE_UPLOAD,
        D3D12_RESOURCE_STATE_GENERIC_READ,
    )?;
    let ib = alloc.alloc_buffer(
        ib_bytes,
        D3D12_HEAP_TYPE_UPLOAD,
        D3D12_RESOURCE_STATE_GENERIC_READ,
    )?;
    // SAFETY: the mapping covers an UPLOAD-heap buffer created to hold this payload, and the source
    // is a separate allocation, so the ranges cannot overlap.
    unsafe {
        let mut p = std::ptr::null_mut::<c_void>();
        vb.Map(0, None, Some(&mut p))
            .map_err(|e| map_hresult(e.code(), "raymarch cube vb map"))?;
        std::ptr::copy_nonoverlapping(
            corners.as_ptr() as *const u8,
            p as *mut u8,
            vb_bytes as usize,
        );
        vb.Unmap(0, None);

        let mut p = std::ptr::null_mut::<c_void>();
        ib.Map(0, None, Some(&mut p))
            .map_err(|e| map_hresult(e.code(), "raymarch cube ib map"))?;
        std::ptr::copy_nonoverlapping(
            indices.as_ptr() as *const u8,
            p as *mut u8,
            ib_bytes as usize,
        );
        ib.Unmap(0, None);
    }

    let vbv = D3D12_VERTEX_BUFFER_VIEW {
        BufferLocation: com::gpu_va(&vb),
        SizeInBytes: vb_bytes as u32,
        StrideInBytes: std::mem::size_of::<Vertex>() as u32,
    };
    let ibv = D3D12_INDEX_BUFFER_VIEW {
        BufferLocation: com::gpu_va(&ib),
        SizeInBytes: ib_bytes as u32,
        Format: DXGI_FORMAT_R16_UINT,
    };
    Ok((vb, ib, vbv, ibv))
}

fn v(pos: [f32; 3]) -> Vertex {
    Vertex {
        pos,
        normal: [0.0, 0.0, 0.0],
        tangent: [0.0, 0.0, 0.0],
        color: [0.0, 0.0, 0.0],
        uv: [0.0, 0.0],
    }
}

// Write the 4-SRV descriptor table for the raymarch pass into the SRV
// heap, starting at `base_slot`. The slots are:
//   [+0] shadow_map  (Texture2DArray<float>)
//   [+1] irradiance  (TextureCube<float4>)
//   [+2] prefilter   (TextureCube<float4>)
//   [+3] scene_color (Texture2D<float4>, written separately by
//                     `write_scene_color_srv` so resize can re-point
//                     just this slot)
//
// The shadow / IBL descriptors duplicate views the engine already binds
// elsewhere (slots 0 / 1 / 2 of the SRV heap); we re-write them here so
// the raymarch root sig can bind a single contiguous descriptor table
// without multi-range offset trickery.
fn write_raymarch_srvs(
    device: &ID3D12Device,
    shadow_resource: Option<&ID3D12Resource>,
    irradiance_resource: &ID3D12Resource,
    prefilter_resource: &ID3D12Resource,
    base_cpu: D3D12_CPU_DESCRIPTOR_HANDLE,
    descriptor_size: usize,
    shadow_layers: u32,
) {
    let slot_cpu = |i: usize| D3D12_CPU_DESCRIPTOR_HANDLE {
        ptr: base_cpu.ptr + i * descriptor_size,
    };

    // shadow_map at +0. Texture2DArray<float> matching the main pass's
    // shadow SRV view dimension.
    if let Some(shadow) = shadow_resource {
        let desc = D3D12_SHADER_RESOURCE_VIEW_DESC {
            Format: DXGI_FORMAT_R32_FLOAT,
            ViewDimension: D3D12_SRV_DIMENSION_TEXTURE2DARRAY,
            Shader4ComponentMapping: D3D12_DEFAULT_SHADER_4_COMPONENT_MAPPING,
            Anonymous: D3D12_SHADER_RESOURCE_VIEW_DESC_0 {
                Texture2DArray: D3D12_TEX2D_ARRAY_SRV {
                    MostDetailedMip: 0,
                    MipLevels: 1,
                    FirstArraySlice: 0,
                    ArraySize: shadow_layers,
                    PlaneSlice: 0,
                    ResourceMinLODClamp: 0.0,
                },
            },
        };
        // SAFETY: the view descriptor and the resource it names are live for the call, and the
        // destination handle addresses a slot this context reserved for the view in a heap it owns.
        unsafe { device.CreateShaderResourceView(shadow, Some(&desc), slot_cpu(0)) };
    }

    // irradiance + prefilter cubes at +1 / +2. Resource format is
    // R32G32B32A32_FLOAT (see directx/texture.rs::upload_environment_map);
    // the SRV view format must match its family.
    for (i, res) in [irradiance_resource, prefilter_resource].iter().enumerate() {
        let desc = D3D12_SHADER_RESOURCE_VIEW_DESC {
            Format: DXGI_FORMAT_R32G32B32A32_FLOAT,
            ViewDimension: D3D12_SRV_DIMENSION_TEXTURECUBE,
            Shader4ComponentMapping: D3D12_DEFAULT_SHADER_4_COMPONENT_MAPPING,
            Anonymous: D3D12_SHADER_RESOURCE_VIEW_DESC_0 {
                TextureCube: D3D12_TEXCUBE_SRV {
                    MostDetailedMip: 0,
                    MipLevels: u32::MAX,
                    ResourceMinLODClamp: 0.0,
                },
            },
        };
        // SAFETY: the view descriptor and the resource it names are live for the call, and the
        // destination handle addresses a slot this context reserved for the view in a heap it owns.
        unsafe { device.CreateShaderResourceView(*res, Some(&desc), slot_cpu(1 + i)) };
    }
    // scene_color at +3, written by `write_scene_color_srv` from the
    // caller so resize can re-point just this slot.
}

// Write the `scene_color` SRV (slot +4 of the raymarch SRV block) at
// the supplied CPU descriptor. Split out so `resize_to` can re-point
// the slot after recreating `hdr_resolve_copy` without rewriting any
// of the other four descriptors.
fn write_scene_color_srv(
    device: &ID3D12Device,
    scene_resource: &ID3D12Resource,
    srv_cpu: D3D12_CPU_DESCRIPTOR_HANDLE,
) {
    let desc = D3D12_SHADER_RESOURCE_VIEW_DESC {
        Format: HDR_FORMAT,
        ViewDimension: D3D12_SRV_DIMENSION_TEXTURE2D,
        Shader4ComponentMapping: D3D12_DEFAULT_SHADER_4_COMPONENT_MAPPING,
        Anonymous: D3D12_SHADER_RESOURCE_VIEW_DESC_0 {
            Texture2D: D3D12_TEX2D_SRV {
                MostDetailedMip: 0,
                MipLevels: 1,
                PlaneSlice: 0,
                ResourceMinLODClamp: 0.0,
            },
        },
    };
    // SAFETY: the view descriptor and the resource it names are live for the call, and the
    // destination handle addresses a slot this context reserved for the view in a heap it owns.
    unsafe { device.CreateShaderResourceView(scene_resource, Some(&desc), srv_cpu) };
}

// Write the 3-sampler descriptor table for the raymarch pass into the
// sampler heap, starting at `base_slot`. The slots are:
//   [+0] shadow_samp (shadow comparison sampler)
//   [+1] cube_samp   (linear-clamp + mip linear, for IBL cubes)
//   [+2] scene_samp  (linear-clamp, for the scene_color tap)
fn write_raymarch_samplers(
    device: &ID3D12Device,
    base_cpu: D3D12_CPU_DESCRIPTOR_HANDLE,
    descriptor_size: usize,
) {
    let slot_cpu = |i: usize| D3D12_CPU_DESCRIPTOR_HANDLE {
        ptr: base_cpu.ptr + i * descriptor_size,
    };
    let shadow = D3D12_SAMPLER_DESC {
        Filter: D3D12_FILTER_COMPARISON_MIN_MAG_LINEAR_MIP_POINT,
        AddressU: D3D12_TEXTURE_ADDRESS_MODE_CLAMP,
        AddressV: D3D12_TEXTURE_ADDRESS_MODE_CLAMP,
        AddressW: D3D12_TEXTURE_ADDRESS_MODE_CLAMP,
        ComparisonFunc: shadow_sample_compare(),
        MinLOD: 0.0,
        MaxLOD: f32::MAX,
        ..Default::default()
    };
    // SAFETY: the view descriptor and the resource it names are live for the call, and the
    // destination handle addresses a slot this context reserved for the view in a heap it owns.
    unsafe { device.CreateSampler(&shadow, slot_cpu(0)) };

    let cube = D3D12_SAMPLER_DESC {
        Filter: D3D12_FILTER_MIN_MAG_MIP_LINEAR,
        AddressU: D3D12_TEXTURE_ADDRESS_MODE_CLAMP,
        AddressV: D3D12_TEXTURE_ADDRESS_MODE_CLAMP,
        AddressW: D3D12_TEXTURE_ADDRESS_MODE_CLAMP,
        MinLOD: 0.0,
        MaxLOD: f32::MAX,
        ..Default::default()
    };
    // SAFETY: the view descriptor and the resource it names are live for the call, and the
    // destination handle addresses a slot this context reserved for the view in a heap it owns.
    unsafe { device.CreateSampler(&cube, slot_cpu(1)) };

    let scene = D3D12_SAMPLER_DESC {
        Filter: D3D12_FILTER_MIN_MAG_MIP_LINEAR,
        AddressU: D3D12_TEXTURE_ADDRESS_MODE_CLAMP,
        AddressV: D3D12_TEXTURE_ADDRESS_MODE_CLAMP,
        AddressW: D3D12_TEXTURE_ADDRESS_MODE_CLAMP,
        MinLOD: 0.0,
        MaxLOD: f32::MAX,
        ..Default::default()
    };
    // SAFETY: the view descriptor and the resource it names are live for the call, and the
    // destination handle addresses a slot this context reserved for the view in a heap it owns.
    unsafe { device.CreateSampler(&scene, slot_cpu(2)) };
}

// DirectX device / queue / info handles the raymarch build submits against.
#[derive(Clone, Copy)]
pub(in crate::directx) struct RaymarchDeviceContext<'a> {
    pub alloc: &'a DeviceAllocator,
    pub info_queue: Option<&'a ID3D12InfoQueue>,
}

// Render-target configuration for the raymarch pass.
#[derive(Clone, Copy)]
pub(in crate::directx) struct RaymarchTargetConfig {
    pub width: u32,
    pub height: u32,
    pub msaa_samples: u32,
}

// Shared engine resources bound into the raymarch pass: the cascaded shadow map
// and the IBL cubes.
#[derive(Clone, Copy)]
pub(in crate::directx) struct RaymarchSharedBindings<'a> {
    // Cascaded shadow map (None when shadow mapping is off).
    pub shadow_resource: Option<&'a ID3D12Resource>,
    pub shadow_layers: u32,
    pub irradiance_resource: &'a ID3D12Resource,
    pub prefilter_resource: &'a ID3D12Resource,
}

// Descriptor table bases + strides for the raymarch SRV + sampler heaps.
#[derive(Clone, Copy)]
pub(in crate::directx) struct RaymarchDescriptorHandles {
    pub srv_base_cpu: D3D12_CPU_DESCRIPTOR_HANDLE,
    pub srv_base_gpu: SrvSlot,
    pub srv_descriptor_size: usize,
    pub sampler_base_cpu: D3D12_CPU_DESCRIPTOR_HANDLE,
    pub sampler_base_gpu: SamplerSlot,
    pub sampler_descriptor_size: usize,
}

// A per-frame `RaymarchView` cbuffer ring, persistently mapped.
fn view_ring(alloc: &DeviceAllocator) -> RenderResult<(Vec<PooledBuffer>, Vec<*mut u8>)> {
    let view_size = align256(std::mem::size_of::<RaymarchView>() as u64);
    let mut buffers: Vec<PooledBuffer> = Vec::with_capacity(FRAMES);
    let mut ptrs: Vec<*mut u8> = Vec::with_capacity(FRAMES);
    for _ in 0..FRAMES {
        let buf = alloc.alloc_buffer(
            view_size,
            D3D12_HEAP_TYPE_UPLOAD,
            D3D12_RESOURCE_STATE_GENERIC_READ,
        )?;
        let mut p = std::ptr::null_mut::<c_void>();
        // SAFETY: the resource is a live CPU-visible buffer, and the out-parameter is a live
        // local that receives the mapping.
        unsafe { buf.Map(0, None, Some(&mut p)) }
            .map_err(|e| map_hresult(e.code(), "raymarch view ubo map"))?;
        ptrs.push(p as *mut u8);
        buffers.push(buf);
    }
    Ok((buffers, ptrs))
}

impl RaymarchResources {
    // Build every raymarch resource and the per-volume records. Returns
    // `Ok(None)` when `sdf_volumes` is empty so the engine omits the pass.
    pub(in crate::directx) fn try_new(
        ctx: RaymarchDeviceContext,
        target: RaymarchTargetConfig,
        bindings: RaymarchSharedBindings,
        handles: RaymarchDescriptorHandles,
        sdf_volumes: &[SdfVolumeSource],
        hot_reload: bool,
    ) -> RenderResult<Option<Self>> {
        let RaymarchDeviceContext { alloc, info_queue } = ctx;
        let device = alloc.device();
        let RaymarchTargetConfig {
            width,
            height,
            msaa_samples,
        } = target;
        let RaymarchSharedBindings {
            shadow_resource,
            shadow_layers,
            irradiance_resource,
            prefilter_resource,
        } = bindings;
        let RaymarchDescriptorHandles {
            srv_base_cpu,
            srv_base_gpu,
            srv_descriptor_size,
            sampler_base_cpu,
            sampler_base_gpu,
            sampler_descriptor_size,
        } = handles;
        if sdf_volumes.is_empty() {
            return Ok(None);
        }

        let root_sig = dump_on_err(info_queue, create_raymarch_root_signature(device))?;
        let shadow_root_sig =
            dump_on_err(info_queue, create_raymarch_shadow_root_signature(device))?;

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

        let (view_cbuffers, view_ptrs) = view_ring(alloc)?;
        let (prepass_view_cbuffers, prepass_view_ptrs) = view_ring(alloc)?;

        // 1×1 white fallback retained for the resource lifetime (would
        // be needed again if a per-volume opt-out re-points the SRV
        // slot away from the snapshot).
        let scene_color_fallback = create_fallback_white_resource(alloc)?;

        // Pre-raymarch HDR scene snapshot; `encode_raymarch` copies
        // `hdr_resolve` / `hdr_color` into this resource on a frame some
        // visible volume taps the scene. Sized to render dims; created in
        // PIXEL_SHADER_RESOURCE, which is where it rests between copies and
        // where a frame that skips the copy leaves it.
        let hdr_resolve_copy = create_hdr_resolve_target(device, width.max(1), height.max(1))?;

        // Build per-volume records. Any failure here aborts init: a compile
        // error in an active volume is a developer-time bug.
        let mut volumes: Vec<RaymarchVolumeRecord> = Vec::with_capacity(sdf_volumes.len());
        for SdfVolumeSource {
            volume: vol,
            fragment_source: payload,
            label,
        } in sdf_volumes
        {
            let programs = crate::shader::raymarch_source::decode(payload, label)
                .map_err(RenderError::Other)?;
            let VolumePsos {
                pso,
                front_pso,
                shadow_pso,
                prepass_psos,
            } = build_volume_psos(
                &VolumePsoTargets {
                    device,
                    info_queue,
                    root_sig: &root_sig,
                    shadow_root_sig: &shadow_root_sig,
                    msaa_samples,
                    hot_reload,
                },
                &programs,
                VolumeFlags::of(vol),
                label,
            )?;
            // Per-volume cbuffer (static: `center`, `extent`,
            // `params` don't change frame-to-frame).
            let uniforms = volume_uniforms_from(vol);
            let cb_size = align256(std::mem::size_of::<RaymarchVolumeUniforms>() as u64);
            let cb = alloc.alloc_buffer(
                cb_size,
                D3D12_HEAP_TYPE_UPLOAD,
                D3D12_RESOURCE_STATE_GENERIC_READ,
            )?;
            let mut p = std::ptr::null_mut::<c_void>();
            // SAFETY: the resource is a live CPU-visible buffer, and the out-parameter is a live
            // local that receives the mapping.
            unsafe { cb.Map(0, None, Some(&mut p)) }
                .map_err(|e| map_hresult(e.code(), "raymarch volume cb map"))?;
            // SAFETY: the mapping covers an UPLOAD-heap buffer created to hold this payload, and
            // the source is a separate allocation, so the ranges cannot overlap.
            unsafe {
                std::ptr::copy_nonoverlapping(
                    &uniforms as *const RaymarchVolumeUniforms as *const u8,
                    p as *mut u8,
                    std::mem::size_of::<RaymarchVolumeUniforms>(),
                );
                // Persistently mapped, never unmap.
            }
            let gva = com::gpu_va(&cb);
            volumes.push(RaymarchVolumeRecord {
                label: label.clone(),
                pso,
                front_pso,
                shadow_pso,
                prepass_psos,
                volume_cbuffer: cb,
                volume_cbuffer_gva: gva,
                visible: vol.visible,
                volumetric: vol.volumetric,
                cast_shadows: vol.cast_shadows,
                refractive: crate::shader::raymarch_source::taps_scene(&programs),
                center: vol.center,
                extent: vol.extent,
            });
        }

        // Write the descriptor tables.
        write_raymarch_srvs(
            device,
            shadow_resource,
            irradiance_resource,
            prefilter_resource,
            srv_base_cpu,
            srv_descriptor_size,
            shadow_layers,
        );
        // scene_color slot points at the snapshot. Captured CPU handle
        // so `resize_to` can re-point the descriptor after the
        // snapshot is recreated at the new resolution.
        let scene_color_srv_cpu = D3D12_CPU_DESCRIPTOR_HANDLE {
            ptr: srv_base_cpu.ptr + 3 * srv_descriptor_size,
        };
        write_scene_color_srv(device, &hdr_resolve_copy, scene_color_srv_cpu);
        write_raymarch_samplers(device, sampler_base_cpu, sampler_descriptor_size);

        Ok(Some(Self {
            root_sig,
            shadow_root_sig,
            cube_vb,
            cube_ib,
            cube_vbv,
            cube_ibv,
            view_cbuffers,
            view_ptrs,
            prepass_view_cbuffers,
            prepass_view_ptrs,
            scene_color_fallback,
            hdr_resolve_copy,
            scene_color_srv_cpu,
            srv_table_gpu: srv_base_gpu,
            sampler_table_gpu: sampler_base_gpu,
            volumes,
        }))
    }

    // Recreate the HDR scene snapshot at new render-target dimensions
    // and rewrite the `scene_color` SRV descriptor in place. Called
    // from the swapchain-resize handler. The descriptor *slot* itself
    // doesn't move; the live raymarch root-table binding (which holds
    // the GPU handle) stays valid without a re-bind.
    pub(in crate::directx) fn resize_to(
        &mut self,
        device: &ID3D12Device,
        width: u32,
        height: u32,
    ) -> RenderResult<()> {
        self.hdr_resolve_copy = create_hdr_resolve_target(device, width.max(1), height.max(1))?;
        write_scene_color_srv(device, &self.hdr_resolve_copy, self.scene_color_srv_cpu);
        Ok(())
    }

    // True when any volume in the world is currently visible. Used by
    // `record_frame` to flip `FrameGraphInputs::raymarch_enabled`.
    pub(in crate::directx) 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 `hdr_resolve_copy` feeds. A world of opaque volumes skips
    // the full-target copy and the four transitions that bracket it.
    fn any_refractive_visible(&self) -> bool {
        self.volumes.iter().any(|v| v.visible && v.refractive)
    }
}

// Pointer drops in the resources struct are POD-style raw pointers; the
// underlying mapped upload buffers stay alive through the `Vec<ID3D12Resource>`
// fields, and the pointers are read on the render thread only.
// SAFETY: the raw pointers `RaymarchResources` holds are the mappings of upload buffers the struct
// also owns, so they stay valid for as long as it does. They are only values here: every
// dereference goes through a `&mut self` method on the context, which the main-thread guard keeps
// on the render thread.
unsafe impl Send for RaymarchResources {}
// SAFETY: sharing `&RaymarchResources` hands out the pointer values but no way to dereference them;
// every write goes through a `&mut self` method on the context.
unsafe impl Sync for RaymarchResources {}

impl DxContext {
    // Encode the raymarched SDF volume pass onto `cmd`. Called from the
    // render graph executor for `PassId::Raymarch`. Assumes the main
    // HDR target was resolved into `hdr_resolve` by the Main pass and
    // that resolve sits in `PIXEL_SHADER_RESOURCE` state (the post-
    // Main pipeline contract). Restores the same state at the end so
    // Decals + Fog + SSR / TAA / Bloom continue to see the resolve as
    // a sampler input.
    pub(in crate::directx) fn encode_raymarch(
        &self,
        cmd: &ID3D12GraphicsCommandList,
        frame_idx: usize,
        view: &RaymarchView,
    ) -> RenderResult<()> {
        let Some(rm) = self.raymarch.as_ref() else {
            return Ok(());
        };
        if !rm.any_visible() {
            return Ok(());
        }

        // Upload this frame's view into the cbuffer ring.
        let view_ptr = rm
            .view_ptrs
            .get(frame_idx)
            .copied()
            .ok_or_else(|| RenderError::Other("raymarch: view_ptrs index OOB".to_string()))?;
        // SAFETY: the mapping covers an UPLOAD-heap buffer created to hold this payload, and the
        // source is a separate allocation, so the ranges cannot overlap.
        unsafe {
            std::ptr::copy_nonoverlapping(
                view as *const RaymarchView as *const u8,
                view_ptr,
                std::mem::size_of::<RaymarchView>(),
            );
        }
        let view_gva = com::gpu_va(&rm.view_cbuffers[frame_idx]);
        let light_gva = com::gpu_va(&self.uniforms.light_ubo_resources[frame_idx]);
        let shadow_gva = com::gpu_va(&self.uniforms.shadow_ubo_resources[frame_idx]);

        // State entering this pass (post-Main, post-AutoExposure):
        //   * hdr_color (MSAA):  RENDER_TARGET  (the Main pass resolved
        //                        into hdr_resolve and restored hdr_color
        //                        back to RENDER_TARGET; see the resolve
        //                        block in `directx/draw/main.rs`).
        //   * hdr_color (no MSAA): PIXEL_SHADER_RESOURCE.
        //   * hdr_resolve:       PIXEL_SHADER_RESOURCE  (AutoExposure
        //                        sampled it; only present when MSAA on).
        //   * depth.resource:    DEPTH_WRITE.
        //
        // We snapshot the single-sample scene for the refraction SRV,
        // then render the raymarch into the MSAA `hdr_color` target
        // with the writable MSAA DSV bound. After the draws we
        // re-resolve hdr_color → hdr_resolve so all downstream
        // single-sample post-stack passes (Decals, Fog, SsrResolve,
        // TaaResolve, Bloom, Composite) pick up the raymarched
        // color AND the raymarched-surface depth (which flowed into
        // `depth.resource` as conservative depth). The MSAA-off path
        // skips the resolve and renders into hdr_color directly.
        let msaa = self.targets.hdr.resolve.is_some();

        // Pre-pass: snapshot the scene spine into `hdr_resolve_copy` for
        // refractive user shaders. A fragment cannot read the attachment it is
        // writing, so the copy and its restore both live inside this node and
        // leave no net state at the boundary. The spine is graph-driven and
        // enters in RENDER_TARGET (this pass declares its read-modify-write).
        //
        // The copy feeds the scene tap and nothing else, so a frame whose
        // visible volumes never call it skips the copy and all four
        // transitions; `hdr_resolve_copy` stays rested in PIXEL_SHADER_RESOURCE
        // where its SRV expects it, holding an earlier frame nothing reads.
        if rm.any_refractive_visible() {
            let snapshot_src_to_copy = transition_barrier(
                self.hdr_scene_target(),
                D3D12_RESOURCE_STATE_RENDER_TARGET,
                D3D12_RESOURCE_STATE_COPY_SOURCE,
            );
            let snapshot_dst_to_copy = transition_barrier(
                &rm.hdr_resolve_copy,
                D3D12_RESOURCE_STATE_PIXEL_SHADER_RESOURCE,
                D3D12_RESOURCE_STATE_COPY_DEST,
            );
            let snapshot_src_back = transition_barrier(
                self.hdr_scene_target(),
                D3D12_RESOURCE_STATE_COPY_SOURCE,
                D3D12_RESOURCE_STATE_RENDER_TARGET,
            );
            let snapshot_dst_to_psr = transition_barrier(
                &rm.hdr_resolve_copy,
                D3D12_RESOURCE_STATE_COPY_DEST,
                D3D12_RESOURCE_STATE_PIXEL_SHADER_RESOURCE,
            );
            // SAFETY: the command list is in the recording state, and every resource, descriptor
            // and slice these commands name is live for the call.
            unsafe {
                cmd.ResourceBarrier(&[snapshot_src_to_copy, snapshot_dst_to_copy]);
                cmd.CopyResource(&rm.hdr_resolve_copy, self.hdr_scene_target());
                cmd.ResourceBarrier(&[snapshot_src_back, snapshot_dst_to_psr]);
            }
        }

        // hdr_color is already in RENDER_TARGET: with MSAA on the graph rests it
        // there, and with MSAA off it is the spine this pass declares a write
        // on. Depth stays in DEPTH_WRITE; the DSV is writable + the inclusive
        // camera test composites against existing rasterized depth.

        let w = self.targets.extent.render_width;
        let h = self.targets.extent.render_height;
        // SAFETY: the command list is in the recording state, and every resource, descriptor and
        // slice these commands name is live for the call.
        unsafe {
            cmd.OMSetRenderTargets(
                1,
                Some(&self.targets.hdr.color_rtv),
                false,
                Some(&self.targets.depth.dsv),
            );
            let vp = D3D12_VIEWPORT {
                TopLeftX: 0.0,
                TopLeftY: 0.0,
                Width: w as f32,
                Height: h as f32,
                MinDepth: 0.0,
                MaxDepth: 1.0,
            };
            cmd.RSSetViewports(&[vp]);
            let scissor = windows::Win32::Foundation::RECT {
                left: 0,
                top: 0,
                right: w as i32,
                bottom: h as i32,
            };
            cmd.RSSetScissorRects(&[scissor]);
            cmd.IASetPrimitiveTopology(D3D_PRIMITIVE_TOPOLOGY_TRIANGLELIST);
            cmd.IASetVertexBuffers(0, Some(&[rm.cube_vbv]));
            cmd.IASetIndexBuffer(Some(&rm.cube_ibv));

            cmd.SetGraphicsRootSignature(&rm.root_sig);
            cmd.SetDescriptorHeaps(&[
                Some(self.descriptors.srv_heap.clone()),
                Some(self.descriptors.sampler_heap.clone()),
            ]);
            cmd.SetGraphicsRootConstantBufferView(0, view_gva);
            cmd.SetGraphicsRootConstantBufferView(2, light_gva);
            cmd.SetGraphicsRootConstantBufferView(3, shadow_gva);
            cmd.set_graphics_srv_table(4, rm.srv_table_gpu);
            cmd.set_graphics_sampler_table(5, rm.sampler_table_gpu);
        }

        for vol in &rm.volumes {
            if !vol.visible {
                continue;
            }
            // SAFETY: the command list is in the recording state, and every resource, descriptor
            // and slice these commands name is live for the call.
            unsafe {
                cmd.SetPipelineState(vol.draw_pso(view));
                cmd.SetGraphicsRootConstantBufferView(1, vol.volume_cbuffer_gva);
                cmd.DrawIndexedInstanced(36, 1, 0, 0, 0);
            }
            self.inc_draw_calls(1);
        }

        // Post-pass.
        //
        // MSAA path: re-resolve hdr_color → hdr_resolve so downstream
        // single-sample readers see the composited scene + raymarched
        // pixels. Both targets return to RENDER_TARGET, the state the
        // graph rests them in for the rest of the decoration chain; the
        // resolve step's own transitions are finer than the graph models.
        //
        // MSAA-off path: hdr_color *is* the single-sample spine and the
        // draws above already wrote it, so there is nothing to resolve.
        if msaa {
            let hdr_color_to_resolve_src = transition_barrier(
                &self.targets.hdr.color,
                D3D12_RESOURCE_STATE_RENDER_TARGET,
                D3D12_RESOURCE_STATE_RESOLVE_SOURCE,
            );
            let resolve_to_dst = transition_barrier(
                self.hdr_scene_target(),
                D3D12_RESOURCE_STATE_RENDER_TARGET,
                D3D12_RESOURCE_STATE_RESOLVE_DEST,
            );
            // SAFETY: the command list is in the recording state, and every resource, descriptor
            // and slice these commands name is live for the call.
            unsafe {
                cmd.ResourceBarrier(&[hdr_color_to_resolve_src, resolve_to_dst]);
                cmd.ResolveSubresource(
                    self.hdr_scene_target(),
                    0,
                    &self.targets.hdr.color,
                    0,
                    HDR_FORMAT,
                );
            }
            let resolve_back = transition_barrier(
                self.hdr_scene_target(),
                D3D12_RESOURCE_STATE_RESOLVE_DEST,
                D3D12_RESOURCE_STATE_RENDER_TARGET,
            );
            let hdr_color_back_to_rt = transition_barrier(
                &self.targets.hdr.color,
                D3D12_RESOURCE_STATE_RESOLVE_SOURCE,
                D3D12_RESOURCE_STATE_RENDER_TARGET,
            );
            // SAFETY: the command list is in the recording state, and every resource, descriptor
            // and slice these commands name is live for the call.
            unsafe { cmd.ResourceBarrier(&[resolve_back, hdr_color_back_to_rt]) };
        }
        Ok(())
    }
}

impl DxContext {
    // Draw every visible surface volume into the G-buffer pre-pass, whose
    // targets the caller has bound, after the rasterized surfaces and before
    // the sky: the march writes normal, depth, roughness and motion under the
    // same depth test, so volumes and meshes occlude each other there as they
    // do in the frame. The volumes march from the camera `prepass` rasterizes
    // through and reproject through `gbuffer`. Leaves the root signature for the
    // next draw to set.
    pub(in crate::directx) fn encode_raymarch_prepass(
        &self,
        cmd: &ID3D12GraphicsCommandList,
        frame_idx: usize,
        prepass: &GbufferPrepassView,
        gbuffer: &GBufferView,
    ) {
        let Some(rm) = self.raymarch.as_ref() else {
            return;
        };
        let surfaces = || {
            rm.volumes
                .iter()
                .filter(|v| v.visible)
                .filter_map(|v| v.prepass_psos.as_ref().map(|psos| (v, psos)))
        };
        if surfaces().next().is_none() {
            return;
        }
        let camera = PassCamera {
            vp: prepass.jittered_vp,
            inv_vp: mat4_inverse(prepass.jittered_vp),
            cam_pos: prepass.cam_pos,
            viewport: [
                self.targets.extent.render_width as f32,
                self.targets.extent.render_height as f32,
            ],
            time: prepass.elapsed,
            prefilter_mip_count: self.scene.env_map.prefilter_mip_count as f32,
            sky_rot: self.state.view.sky_rot,
        };
        let view = &RaymarchView::for_gbuffer(&camera, gbuffer);
        let draws = surfaces().map(|(v, psos)| (psos.get(v.faces(view)), v.volume_cbuffer_gva));
        let (Some(&view_ptr), Some(view_cb), Some(lights), Some(shadow)) = (
            rm.prepass_view_ptrs.get(frame_idx),
            rm.prepass_view_cbuffers.get(frame_idx),
            self.uniforms.light_ubo_resources.get(frame_idx),
            self.uniforms.shadow_ubo_resources.get(frame_idx),
        ) else {
            return;
        };
        // SAFETY: the mapping covers an UPLOAD-heap buffer created to hold this payload, and the
        // source is a separate allocation, so the ranges cannot overlap.
        unsafe {
            std::ptr::copy_nonoverlapping(
                view as *const RaymarchView as *const u8,
                view_ptr,
                std::mem::size_of::<RaymarchView>(),
            );
        }
        // SAFETY: the command list is in the recording state with the pre-pass targets bound,
        // and every resource these commands name is live for the call.
        unsafe {
            cmd.SetGraphicsRootSignature(&rm.shadow_root_sig);
            cmd.IASetPrimitiveTopology(D3D_PRIMITIVE_TOPOLOGY_TRIANGLELIST);
            cmd.IASetVertexBuffers(0, Some(&[rm.cube_vbv]));
            cmd.IASetIndexBuffer(Some(&rm.cube_ibv));
            cmd.SetGraphicsRootConstantBufferView(0, com::gpu_va(view_cb));
            cmd.SetGraphicsRootConstantBufferView(2, com::gpu_va(lights));
            cmd.SetGraphicsRootConstantBufferView(3, com::gpu_va(shadow));
            cmd.set_graphics_root_constants(4, &[0u32; 4]);
        }
        for (pso, volume_gva) in draws {
            // SAFETY: the command list is in the recording state, and every resource these
            // commands name is live for the call.
            unsafe {
                cmd.SetPipelineState(pso);
                cmd.SetGraphicsRootConstantBufferView(1, volume_gva);
                cmd.DrawIndexedInstanced(36, 1, 0, 0, 0);
            }
            self.inc_draw_calls(1);
        }
    }
}

impl RaymarchResources {
    // True when at least one volume both opted in to shadow casting at
    // init (`cast_shadows`, gated to `Some(shadow_pso)`) AND is visible
    // this frame. Drives the early-out for the shadow caster encoder
    // so non-cast-shadow worlds pay zero cost.
    pub(in crate::directx) fn any_shadow_casters(&self) -> bool {
        self.volumes
            .iter()
            .any(|v| v.visible && v.cast_shadows && v.shadow_pso.is_some())
    }
}

impl DxContext {
    // Encode the raymarched SDF shadow casters into the existing CSM
    // shadow DSVs, right before `encode_shadow_pass` transitions the
    // shadow map array to `PIXEL_SHADER_RESOURCE`. One draw per visible
    // caster per cascade; the proxy unit cube rasterizes through the
    // cascade's light VP (its back faces give one fragment per texel
    // inside the box), the depth-only fragment
    // marches the SDF, and writes the hit's NDC.z through the
    // conservative-depth semantic, so the cascade DSV's write test keeps
    // only the caster nearest the light between rasterized and raymarched.
    //
    // Uploads `view` into the same per-frame cbuffer ring
    // `encode_raymarch` uses. Bytes for the same frame_idx are written
    // twice (once here, once by `encode_raymarch` later in the frame);
    // both writes are byte-identical when the caller passes the same
    // view, and the shadow march only reads `view_time` so even if the
    // later write differs in fields the shadow path ignores, behavior
    // is unchanged.
    pub(in crate::directx) fn encode_sdf_shadow_casters(
        &self,
        cmd: &ID3D12GraphicsCommandList,
        frame_idx: usize,
        shadow_ubo_gva: u64,
        view: &RaymarchView,
    ) -> RenderResult<()> {
        let Some(rm) = self.raymarch.as_ref() else {
            return Ok(());
        };
        if !rm.any_shadow_casters() {
            return Ok(());
        }
        if self.shadow.dsvs.is_empty() {
            return Ok(());
        }

        // Share the cbuffer ring with the main raymarch pass. See the
        // docstring above for why the double-write is safe.
        let view_ptr = rm.view_ptrs.get(frame_idx).copied().ok_or_else(|| {
            RenderError::Other("raymarch shadow: view_ptrs index OOB".to_string())
        })?;
        // SAFETY: the mapping covers an UPLOAD-heap buffer created to hold this payload, and the
        // source is a separate allocation, so the ranges cannot overlap.
        unsafe {
            std::ptr::copy_nonoverlapping(
                view as *const RaymarchView as *const u8,
                view_ptr,
                std::mem::size_of::<RaymarchView>(),
            );
        }
        let view_gva = com::gpu_va(&rm.view_cbuffers[frame_idx]);
        let light_gva = com::gpu_va(&self.uniforms.light_ubo_resources[frame_idx]);

        let sm = self.shadow.map_size;
        // SAFETY: the command list is in the recording state, and every resource, descriptor and
        // slice these commands name is live for the call.
        unsafe {
            cmd.SetGraphicsRootSignature(&rm.shadow_root_sig);
            cmd.IASetPrimitiveTopology(D3D_PRIMITIVE_TOPOLOGY_TRIANGLELIST);
            cmd.IASetVertexBuffers(0, Some(&[rm.cube_vbv]));
            cmd.IASetIndexBuffer(Some(&rm.cube_ibv));

            let vp = D3D12_VIEWPORT {
                TopLeftX: 0.0,
                TopLeftY: 0.0,
                Width: sm as f32,
                Height: sm as f32,
                MinDepth: 0.0,
                MaxDepth: 1.0,
            };
            cmd.RSSetViewports(&[vp]);
            let scissor = windows::Win32::Foundation::RECT {
                left: 0,
                top: 0,
                right: sm as i32,
                bottom: sm as i32,
            };
            cmd.RSSetScissorRects(&[scissor]);

            // Shared cbuffers (view (b0), lights (b2), shadow (b3)) stay
            // bound across all cascades and all volumes. Volume cbuffer
            // (b1) + cascade root constant (b4) + PSO get updated inside
            // the loop.
            cmd.SetGraphicsRootConstantBufferView(0, view_gva);
            cmd.SetGraphicsRootConstantBufferView(2, light_gva);
            cmd.SetGraphicsRootConstantBufferView(3, shadow_ubo_gva);
        }

        // Only cast into cascades the rasterized shadow pass re-rendered this
        // frame: a skipped cascade's slice must stay exactly as it was last fully
        // rendered (raster + SDF), so we neither clear nor add to it. The 0
        // sentinel falls back to all cascades. Mirrors Metal.
        let all_cascades = (1u32 << render_types::NUM_SHADOW_CASCADES) - 1;
        let render_mask = if self.shadow.render_mask == 0 {
            all_cascades
        } else {
            self.shadow.render_mask
        };
        for cascade_idx in 0..render_types::NUM_SHADOW_CASCADES {
            if render_mask & (1u32 << cascade_idx) == 0 {
                continue;
            }
            let dsv = self.shadow.dsvs[cascade_idx];
            // SAFETY: the command list is in the recording state, and every resource, descriptor
            // and slice these commands name is live for the call.
            unsafe {
                cmd.OMSetRenderTargets(0, None, false, Some(&dsv));
                let constants = [cascade_idx as u32, 0u32, 0u32, 0u32];
                cmd.set_graphics_root_constants(4, &constants);
            }
            for vol in &rm.volumes {
                if !vol.visible || !vol.cast_shadows {
                    continue;
                }
                let Some(pso) = vol.shadow_pso.as_ref() else {
                    continue;
                };
                // SAFETY: the command list is in the recording state, and every resource,
                // descriptor and slice these commands name is live for the call.
                unsafe {
                    cmd.SetPipelineState(pso);
                    cmd.SetGraphicsRootConstantBufferView(1, vol.volume_cbuffer_gva);
                    cmd.DrawIndexedInstanced(36, 1, 0, 0, 0);
                }
                self.inc_draw_calls(1);
            }
        }
        Ok(())
    }
}

// Silence the unused-import warning when no `SdfVolume` ships in a build.
// `LightUniforms` is referenced only through the cbuffer GVA we read from
// `self.uniforms.light_ubo_resources`, but the type is part of the
// encode_raymarch contract surface for future readers.
const _LIGHT_LAYOUT_REF: usize = std::mem::size_of::<LightUniforms>();

// The `RaymarchView` / `RaymarchVolumeUniforms` layout tests live with the
// structs in `concinnity_core::render::uniforms::directx`.