concinnity-device 0.19.24

// src/directx/post/gbuffer.rs
//
// Unified geometry G-buffer pre-pass for the D3D12 backend. One jittered
// traversal of the GPU cull's records rasterises into a single MRT:
//
//   target 0  RGBA16F  view-space normal (rgb) + positive linear view depth (a)
//   target 1  R8       perceptual roughness
//   target 2  RG16F    screen-space motion (prev_uv - cur_uv)
//
// plus a private single-sample depth buffer. Every screen-space consumer (SSR
// resolve, SSAO kernel/blur, SSGI gather/composite, TAA resolve, FSR upscaler)
// reads this one output instead of re-rasterising, replacing the separate
// SsrPrepass + SSAO pre-pass + Velocity passes. Rasterisation uses the jittered
// VP (matching the main pass coverage); the motion vector derives from the
// un-jittered current / previous VPs in-shader so projection jitter never
// contaminates motion. Mirrors src/metal/post/gbuffer.rs.

use concinnity_core::gfx::transform::IDENTITY;
use std::cell::RefCell;

use windows::Win32::Foundation::RECT;
use windows::Win32::Graphics::Direct3D12::*;
use windows::Win32::Graphics::Dxgi::Common::*;

use crate::directx::allocator::{DeviceAllocator, PooledBuffer};
use crate::directx::com;
use crate::directx::context::{DxContext, FRAMES, align256, dump_on_err};
use crate::directx::pipeline::serialize_and_create_root_sig;
use crate::directx::slang_builtins;
use crate::directx::slang_builtins::SlangCompile;
use crate::directx::texture::{
    create_buffer, create_main_depth_texture, write_format_rtv, write_format_srv,
};

// Normal+depth target: rgb = unit view-space normal, a = positive linear view
// depth (-view_z). Alpha 0 (cleared background) marks "no geometry". Matches
// the SSR / SSAO G-buffer so the resolve / kernel maths is byte-identical.
pub(crate) const GBUFFER_NORMAL_DEPTH_FORMAT: DXGI_FORMAT = DXGI_FORMAT_R16G16B16A16_FLOAT;

// Single-channel perceptual roughness. 1.0 = fully rough (cleared background),
// 0.0 = mirror.
pub(crate) const GBUFFER_ROUGHNESS_FORMAT: DXGI_FORMAT = DXGI_FORMAT_R8_UNORM;

// Screen-space motion (prev_uv - cur_uv). Cleared to 0 (no motion).
pub(crate) const GBUFFER_VELOCITY_FORMAT: DXGI_FORMAT = DXGI_FORMAT_R16G16_FLOAT;

// Background roughness the prepass clears the roughness target to: fully rough,
// so untouched pixels emit no reflection. The per-frame clear uses it here; the
// matching optimized clear now comes from the graph's desc, and a test pins the
// two together.
pub(in crate::directx) const GBUFFER_ROUGHNESS_CLEAR: [f32; 4] = [1.0, 0.0, 0.0, 0.0];

// Size of the per-frame view UBO: jittered_vp + cur_vp + prev_vp + view_mat
// (four float4x4 = 256 B). Matches the `GbView` cbuffer in every pre-pass VS.
const GBUFFER_VIEW_UBO_SIZE: u64 = 256;

// `GBufferView` (the `GbView` cbuffer) is a GPU-free layout struct that lives in
// `core::render`; re-export it so
// `crate::directx::post::gbuffer::GBufferView` is unchanged.
pub(in crate::directx) use concinnity_core::render::uniforms::GBufferView;

// Root signatures

// PSO for the G-buffer pre-pass. Writes the three MRT targets over a private
// single-sample depth buffer. Mirrors the main pass's no-cull rasteriser + LESS
// depth test so the G-buffer matches the main pass's visible surfaces.
fn create_gbuffer_pso(
    device: &ID3D12Device,
    root_sig: &ID3D12RootSignature,
    vs: &[u8],
    ps: &[u8],
    layout: &[D3D12_INPUT_ELEMENT_DESC],
) -> Result<ID3D12PipelineState, String> {
    let pso_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(),
        },
        InputLayout: D3D12_INPUT_LAYOUT_DESC {
            pInputElementDescs: layout.as_ptr(),
            NumElements: layout.len() as u32,
        },
        PrimitiveTopologyType: D3D12_PRIMITIVE_TOPOLOGY_TYPE_TRIANGLE,
        NumRenderTargets: 3,
        RTVFormats: {
            let mut a = [DXGI_FORMAT_UNKNOWN; 8];
            a[0] = GBUFFER_NORMAL_DEPTH_FORMAT;
            a[1] = GBUFFER_ROUGHNESS_FORMAT;
            a[2] = GBUFFER_VELOCITY_FORMAT;
            a
        },
        DSVFormat: DXGI_FORMAT_D32_FLOAT,
        SampleDesc: DXGI_SAMPLE_DESC {
            Count: 1,
            Quality: 0,
        },
        SampleMask: u32::MAX,
        RasterizerState: D3D12_RASTERIZER_DESC {
            FillMode: D3D12_FILL_MODE_SOLID,
            CullMode: D3D12_CULL_MODE_NONE,
            FrontCounterClockwise: true.into(),
            DepthClipEnable: true.into(),
            ..Default::default()
        },
        DepthStencilState: D3D12_DEPTH_STENCIL_DESC {
            DepthEnable: true.into(),
            DepthWriteMask: D3D12_DEPTH_WRITE_MASK_ALL,
            DepthFunc: D3D12_COMPARISON_FUNC_LESS,
            StencilEnable: false.into(),
            ..Default::default()
        },
        BlendState: D3D12_BLEND_DESC {
            RenderTarget: {
                let mut arr = [D3D12_RENDER_TARGET_BLEND_DESC::default(); 8];
                let mt = D3D12_RENDER_TARGET_BLEND_DESC {
                    BlendEnable: false.into(),
                    RenderTargetWriteMask: D3D12_COLOR_WRITE_ENABLE_ALL.0 as u8,
                    ..Default::default()
                };
                arr[0] = mt;
                arr[1] = mt;
                arr[2] = mt;
                arr
            },
            ..Default::default()
        },
        ..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, &pso_desc) }
        .map_err(|e| format!("create gbuffer prepass PSO: {e}"))
}

// Vertex input layout for the GPU-driven (bindless) G-buffer pre-pass: the
// current-frame attributes the VS reads (position / normal / colour for the
// skybox sentinel) on slot 0, plus the previous-frame position on slot 1. Both
// slots carry the 56-byte `Vertex`; the static prefix binds the static VB to
// both slots (prev_pos == cur_pos), the skinned tail binds the current deformed
// buffer to slot 0 and the previous-frame deformed buffer to slot 1. Tangent +
// UV are unused (the pre-pass samples no textures), so they are omitted.
//
// The previous position carries its own semantic rather than POSITION1 because
// slangc appends an index to whatever a semantic spells; see the declaration in
// shaders/gbuffer_prepass.slang.
fn gbuffer_bindless_input_layout() -> Vec<D3D12_INPUT_ELEMENT_DESC> {
    vec![
        D3D12_INPUT_ELEMENT_DESC {
            SemanticName: windows::core::s!("POSITION"),
            SemanticIndex: 0,
            Format: DXGI_FORMAT_R32G32B32_FLOAT,
            InputSlot: 0,
            AlignedByteOffset: 0,
            InputSlotClass: D3D12_INPUT_CLASSIFICATION_PER_VERTEX_DATA,
            InstanceDataStepRate: 0,
        },
        D3D12_INPUT_ELEMENT_DESC {
            SemanticName: windows::core::s!("NORMAL"),
            SemanticIndex: 0,
            Format: DXGI_FORMAT_R32G32B32_FLOAT,
            InputSlot: 0,
            AlignedByteOffset: 12,
            InputSlotClass: D3D12_INPUT_CLASSIFICATION_PER_VERTEX_DATA,
            InstanceDataStepRate: 0,
        },
        D3D12_INPUT_ELEMENT_DESC {
            SemanticName: windows::core::s!("COLOR"),
            SemanticIndex: 0,
            Format: DXGI_FORMAT_R32G32B32_FLOAT,
            InputSlot: 0,
            AlignedByteOffset: 36,
            InputSlotClass: D3D12_INPUT_CLASSIFICATION_PER_VERTEX_DATA,
            InstanceDataStepRate: 0,
        },
        D3D12_INPUT_ELEMENT_DESC {
            SemanticName: windows::core::s!("PREVPOSITION"),
            SemanticIndex: 0,
            Format: DXGI_FORMAT_R32G32B32_FLOAT,
            InputSlot: 1,
            AlignedByteOffset: 0,
            InputSlotClass: D3D12_INPUT_CLASSIFICATION_PER_VERTEX_DATA,
            InstanceDataStepRate: 0,
        },
    ]
}

// Root signature for the GPU-driven G-buffer pre-pass. Mirrors the shadow
// bindless root signature's object-id delivery so the shared cull command
// signature works against it: [0] is the per-command b0 object-id root constant
// (set by the `ExecuteIndirect` command signature, so it MUST stay at root
// parameter 0), [1] the GbView CBV (jittered/cur/prev VP + view matrix), [2] the
// per-frame `StructuredBuffer<GpuObjectData>` (model + roughness), and [3] the
// parallel previous-frame model buffer. All vertex-stage only (roughness reaches
// the pixel shader through a flat varying; the FS reads no resources).
fn create_gbuffer_bindless_root_signature(
    device: &ID3D12Device,
) -> Result<ID3D12RootSignature, String> {
    let params = [
        // [0] Root constant b0: object id (set per command by the command sig).
        D3D12_ROOT_PARAMETER {
            ParameterType: D3D12_ROOT_PARAMETER_TYPE_32BIT_CONSTANTS,
            Anonymous: D3D12_ROOT_PARAMETER_0 {
                Constants: D3D12_ROOT_CONSTANTS {
                    ShaderRegister: 0,
                    RegisterSpace: 0,
                    Num32BitValues: 1,
                },
            },
            ShaderVisibility: D3D12_SHADER_VISIBILITY_VERTEX,
        },
        // [1] Root CBV b1: GbView (jittered_vp + cur_vp + prev_vp + view).
        D3D12_ROOT_PARAMETER {
            ParameterType: D3D12_ROOT_PARAMETER_TYPE_CBV,
            Anonymous: D3D12_ROOT_PARAMETER_0 {
                Descriptor: D3D12_ROOT_DESCRIPTOR {
                    ShaderRegister: 1,
                    RegisterSpace: 0,
                },
            },
            ShaderVisibility: D3D12_SHADER_VISIBILITY_VERTEX,
        },
        // [2] Root SRV t0: per-frame StructuredBuffer<GpuObjectData>.
        D3D12_ROOT_PARAMETER {
            ParameterType: D3D12_ROOT_PARAMETER_TYPE_SRV,
            Anonymous: D3D12_ROOT_PARAMETER_0 {
                Descriptor: D3D12_ROOT_DESCRIPTOR {
                    ShaderRegister: 0,
                    RegisterSpace: 0,
                },
            },
            ShaderVisibility: D3D12_SHADER_VISIBILITY_VERTEX,
        },
        // [3] Root SRV t1: the previous frame's model-history slot.
        D3D12_ROOT_PARAMETER {
            ParameterType: D3D12_ROOT_PARAMETER_TYPE_SRV,
            Anonymous: D3D12_ROOT_PARAMETER_0 {
                Descriptor: D3D12_ROOT_DESCRIPTOR {
                    ShaderRegister: 1,
                    RegisterSpace: 0,
                },
            },
            ShaderVisibility: D3D12_SHADER_VISIBILITY_VERTEX,
        },
        // [4] Root SRV t2: this frame's draw args, read for `NO_HISTORY`.
        D3D12_ROOT_PARAMETER {
            ParameterType: D3D12_ROOT_PARAMETER_TYPE_SRV,
            Anonymous: D3D12_ROOT_PARAMETER_0 {
                Descriptor: D3D12_ROOT_DESCRIPTOR {
                    ShaderRegister: 2,
                    RegisterSpace: 0,
                },
            },
            ShaderVisibility: D3D12_SHADER_VISIBILITY_VERTEX,
        },
    ];
    serialize_and_create_root_sig(device, &params, "gbuffer bindless root sig")
}

// Threads per group, matching `[numthreads(64, 1, 1)]` in model_history.slang.
const MODEL_HISTORY_THREADGROUP: u32 = 64;

// A UAV barrier over one buffer: orders its shader writes against later
// accesses without claiming a state transition a buffer does not have.
fn uav_barrier(resource: &ID3D12Resource) -> D3D12_RESOURCE_BARRIER {
    D3D12_RESOURCE_BARRIER {
        Type: D3D12_RESOURCE_BARRIER_TYPE_UAV,
        Flags: D3D12_RESOURCE_BARRIER_FLAG_NONE,
        Anonymous: D3D12_RESOURCE_BARRIER_0 {
            UAV: std::mem::ManuallyDrop::new(D3D12_RESOURCE_UAV_BARRIER {
                pResource: com::borrowed(resource),
            }),
        },
    }
}

// Root signature for the model-history snapshot kernel. slangc assigns
// b0/t0/u0 from declaration order, which is what these three parameters bind.
fn create_model_history_root_signature(
    device: &ID3D12Device,
) -> Result<ID3D12RootSignature, String> {
    let params = [
        // [0] Root constants b0: ModelHistoryParams (record count + padding).
        D3D12_ROOT_PARAMETER {
            ParameterType: D3D12_ROOT_PARAMETER_TYPE_32BIT_CONSTANTS,
            Anonymous: D3D12_ROOT_PARAMETER_0 {
                Constants: D3D12_ROOT_CONSTANTS {
                    ShaderRegister: 0,
                    RegisterSpace: 0,
                    Num32BitValues: 4,
                },
            },
            ShaderVisibility: D3D12_SHADER_VISIBILITY_ALL,
        },
        // [1] Root SRV t0: this frame's StructuredBuffer<GpuObjectData>.
        D3D12_ROOT_PARAMETER {
            ParameterType: D3D12_ROOT_PARAMETER_TYPE_SRV,
            Anonymous: D3D12_ROOT_PARAMETER_0 {
                Descriptor: D3D12_ROOT_DESCRIPTOR {
                    ShaderRegister: 0,
                    RegisterSpace: 0,
                },
            },
            ShaderVisibility: D3D12_SHADER_VISIBILITY_ALL,
        },
        // [2] Root UAV u0: this frame's model-history slot.
        D3D12_ROOT_PARAMETER {
            ParameterType: D3D12_ROOT_PARAMETER_TYPE_UAV,
            Anonymous: D3D12_ROOT_PARAMETER_0 {
                Descriptor: D3D12_ROOT_DESCRIPTOR {
                    ShaderRegister: 0,
                    RegisterSpace: 0,
                },
            },
            ShaderVisibility: D3D12_SHADER_VISIBILITY_ALL,
        },
    ];
    serialize_and_create_root_sig(device, &params, "model history root sig")
}

// Build the model-history snapshot kernel: the compute PSO and its root
// signature. Called under the same gate as the pre-pass it feeds.
pub(in crate::directx) fn build_model_history(
    device: &ID3D12Device,
    info_queue: Option<&ID3D12InfoQueue>,
    hot_reload: bool,
) -> Result<(ID3D12RootSignature, ID3D12PipelineState), String> {
    let cs = slang_builtins::MODEL_HISTORY.compile(hot_reload)?;
    let root_sig = dump_on_err(info_queue, create_model_history_root_signature(device))?;
    let pso = dump_on_err(
        info_queue,
        crate::directx::cull::create_cull_pso(device, &root_sig, &cs),
    )?;
    Ok((root_sig, pso))
}

// Build the GPU-driven G-buffer pre-pass pipeline: the bindless VS/FS, its root
// signature, and the shared cull command signature rebuilt against that root sig
// (object id at root param 0). Returns the trio the cull state stores; the
// per-frame `prev_model` buffers it reads are allocated alongside the other cull
// buffers. Reuses `create_gbuffer_pso` (3 MRT, private D32, single-sample, LESS
// depth) with the two-stream bindless input layout.
// The bindless g-buffer root signature, pipeline state, and command signature
// the cull state stores.
type GbufferBindlessPipeline = (
    ID3D12RootSignature,
    ID3D12PipelineState,
    ID3D12CommandSignature,
);

pub(in crate::directx) fn build_gbuffer_bindless(
    device: &ID3D12Device,
    info_queue: Option<&ID3D12InfoQueue>,
    hot_reload: bool,
) -> Result<GbufferBindlessPipeline, String> {
    let vs = slang_builtins::GBUFFER_BINDLESS_VERT.compile(hot_reload)?;
    let ps = slang_builtins::GBUFFER_BINDLESS_FRAG.compile(hot_reload)?;
    let root_sig = dump_on_err(info_queue, create_gbuffer_bindless_root_signature(device))?;
    let layout = gbuffer_bindless_input_layout();
    let pso = dump_on_err(
        info_queue,
        create_gbuffer_pso(device, &root_sig, &vs, &ps, &layout),
    )?;
    let cmd_sig = dump_on_err(
        info_queue,
        crate::directx::cull::create_cull_command_signature(device, &root_sig),
    )?;
    Ok((root_sig, pso, cmd_sig))
}

// Descriptor-slot handles for the three G-buffer SRVs, minted by the caller
// (which owns the heap layout). `Copy` so the caller can both pass it to `new`
// and stash a copy for the live `apply_quality_settings` rebuild.
#[derive(Clone, Copy)]
pub(in crate::directx) struct GbufferSlots {
    pub normal_depth_rtv: D3D12_CPU_DESCRIPTOR_HANDLE,
    pub normal_depth_srv: (D3D12_CPU_DESCRIPTOR_HANDLE, D3D12_GPU_DESCRIPTOR_HANDLE),
    pub roughness_rtv: D3D12_CPU_DESCRIPTOR_HANDLE,
    pub roughness_srv: (D3D12_CPU_DESCRIPTOR_HANDLE, D3D12_GPU_DESCRIPTOR_HANDLE),
    pub velocity_rtv: D3D12_CPU_DESCRIPTOR_HANDLE,
    pub velocity_srv: (D3D12_CPU_DESCRIPTOR_HANDLE, D3D12_GPU_DESCRIPTOR_HANDLE),
    pub depth_dsv: D3D12_CPU_DESCRIPTOR_HANDLE,
}

// Unified G-buffer resources held by `DxContext` when any screen-space consumer
// (SSR, SSGI, SSAO, TAA, or temporal upscaling) is enabled. Drops cleanly with
// the context: every D3D12 object is COM-refcounted.
pub(in crate::directx) struct GbufferResources {
    // MRT targets + their private single-sample depth.
    pub(in crate::directx) normal_depth: ID3D12Resource,
    pub(in crate::directx) normal_depth_rtv: D3D12_CPU_DESCRIPTOR_HANDLE,
    pub(in crate::directx) normal_depth_srv_gpu: D3D12_GPU_DESCRIPTOR_HANDLE,
    pub(in crate::directx) roughness: ID3D12Resource,
    pub(in crate::directx) roughness_rtv: D3D12_CPU_DESCRIPTOR_HANDLE,
    pub(in crate::directx) roughness_srv_gpu: D3D12_GPU_DESCRIPTOR_HANDLE,
    pub(in crate::directx) velocity: ID3D12Resource,
    pub(in crate::directx) velocity_rtv: D3D12_CPU_DESCRIPTOR_HANDLE,
    pub(in crate::directx) velocity_srv_gpu: D3D12_GPU_DESCRIPTOR_HANDLE,
    pub(in crate::directx) depth: ID3D12Resource,
    pub(in crate::directx) depth_dsv: D3D12_CPU_DESCRIPTOR_HANDLE,

    // Per-frame view UBO (jittered_vp + cur_vp + prev_vp + view), mapped.
    pub(in crate::directx) view_ubo_resources: Vec<PooledBuffer>,
    pub(in crate::directx) view_ubo_ptrs: Vec<*mut u8>,

    // Last frame's un-jittered VP, owned here so the velocity channel works for
    // any consumer (TAA or FSR) independent of whether engine-TAA is on. The
    // per-object half of the same history is the GPU-filled model-history ring.
    pub(in crate::directx) prev_view_proj: RefCell<[[f32; 4]; 4]>,
}

// The device the G-buffer builder allocates against.
#[derive(Clone, Copy)]
pub(in crate::directx) struct GbufferDeviceCtx<'a> {
    pub alloc: &'a DeviceAllocator,
}

// The three colour targets the transient pool owns, handed to the G-buffer at
// build / resize. The feature no longer creates them: they are graph resources
// the pool places, so it only writes their views. `depth` is absent because it
// stays feature-owned (see `transient_pool::pooled`).
#[derive(Clone)]
pub(in crate::directx) struct GbufferPooled {
    pub normal_depth: ID3D12Resource,
    pub roughness: ID3D12Resource,
    pub velocity: ID3D12Resource,
}

// Render-target extent plus which pipeline variants the G-buffer pre-pass builds.
#[derive(Clone, Copy)]
pub(in crate::directx) struct GbufferExtent {
    pub width: u32,
    pub height: u32,
}

// The RTV + SRV descriptor slots the three pooled colour targets are viewed
// through. Built from `GbufferSlots` at construction and from the stored
// handles at resize, so one routine writes the views in both paths.
struct GbufferViewSlots {
    normal_depth: (D3D12_CPU_DESCRIPTOR_HANDLE, D3D12_CPU_DESCRIPTOR_HANDLE),
    roughness: (D3D12_CPU_DESCRIPTOR_HANDLE, D3D12_CPU_DESCRIPTOR_HANDLE),
    velocity: (D3D12_CPU_DESCRIPTOR_HANDLE, D3D12_CPU_DESCRIPTOR_HANDLE),
}

// Point the pre-reserved RTV / SRV slots at the pool's placed resources and
// hand back a reference to each. Every pool rebuild (init, resize, and a
// quality toggle that changes the pooled set) relocates these resources, so
// every one of those paths must call this or the descriptors name freed memory.
fn write_pooled_views(
    device: &ID3D12Device,
    slots: GbufferViewSlots,
    pooled: &GbufferPooled,
) -> (ID3D12Resource, ID3D12Resource, ID3D12Resource) {
    for (res, (rtv, srv), format) in [
        (
            &pooled.normal_depth,
            slots.normal_depth,
            GBUFFER_NORMAL_DEPTH_FORMAT,
        ),
        (&pooled.roughness, slots.roughness, GBUFFER_ROUGHNESS_FORMAT),
        (&pooled.velocity, slots.velocity, GBUFFER_VELOCITY_FORMAT),
    ] {
        write_format_rtv(device, res, rtv, format);
        write_format_srv(device, res, srv, format);
    }
    (
        pooled.normal_depth.clone(),
        pooled.roughness.clone(),
        pooled.velocity.clone(),
    )
}

impl GbufferResources {
    pub(in crate::directx) fn new(
        ctx: GbufferDeviceCtx,
        extent: GbufferExtent,
        slots: GbufferSlots,
        pooled: &GbufferPooled,
    ) -> Result<Self, String> {
        let GbufferDeviceCtx { alloc } = ctx;
        let device = alloc.device();
        let GbufferExtent { width, height } = extent;
        // The three colour targets come from the transient pool; this only
        // writes their views into the pre-reserved descriptor slots.
        let (normal_depth, roughness, velocity) = write_pooled_views(
            device,
            GbufferViewSlots {
                normal_depth: (slots.normal_depth_rtv, slots.normal_depth_srv.0),
                roughness: (slots.roughness_rtv, slots.roughness_srv.0),
                velocity: (slots.velocity_rtv, slots.velocity_srv.0),
            },
            pooled,
        );

        let depth = create_main_depth_texture(device, width, height, slots.depth_dsv, 1, true)?;

        // Per-frame view UBO.
        let view_size = align256(GBUFFER_VIEW_UBO_SIZE);
        let mut view_ubo_resources: Vec<PooledBuffer> = Vec::with_capacity(FRAMES);
        let mut view_ubo_ptrs: Vec<*mut u8> = Vec::with_capacity(FRAMES);
        for _ in 0..FRAMES {
            let buf = create_buffer(
                alloc,
                view_size,
                D3D12_HEAP_TYPE_UPLOAD,
                D3D12_RESOURCE_STATE_GENERIC_READ,
            )?;
            let mut ptr = std::ptr::null_mut::<std::ffi::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 ptr)) }
                .map_err(|e| format!("map gbuffer view ubo: {e}"))?;
            view_ubo_ptrs.push(ptr as *mut u8);
            view_ubo_resources.push(buf);
        }

        Ok(Self {
            normal_depth,
            normal_depth_rtv: slots.normal_depth_rtv,
            normal_depth_srv_gpu: slots.normal_depth_srv.1,
            roughness,
            roughness_rtv: slots.roughness_rtv,
            roughness_srv_gpu: slots.roughness_srv.1,
            velocity,
            velocity_rtv: slots.velocity_rtv,
            velocity_srv_gpu: slots.velocity_srv.1,
            depth,
            depth_dsv: slots.depth_dsv,
            view_ubo_resources,
            view_ubo_ptrs,
            prev_view_proj: RefCell::new(IDENTITY),
        })
    }

    // Re-point the MRT views at the rebuilt pool and recreate the private depth
    // at a new resolution. The descriptor *slots* stay put; only the resources
    // behind them change, so no consumer needs a re-bind.
    //
    // The caller must have rebuilt the transient pool first: `pooled` names the
    // new placed resources, and the old ones are freed with the pool.
    pub(in crate::directx) fn resize_to(
        &mut self,
        device: &ID3D12Device,
        width: u32,
        height: u32,
        srv_cpu_base: D3D12_CPU_DESCRIPTOR_HANDLE,
        srv_gpu_base: D3D12_GPU_DESCRIPTOR_HANDLE,
        pooled: &GbufferPooled,
    ) -> Result<(), String> {
        self.repoint_pooled(device, srv_cpu_base, srv_gpu_base, pooled);
        self.depth = create_main_depth_texture(device, width, height, self.depth_dsv, 1, true)?;
        Ok(())
    }

    // Re-point the three pooled colour views after a pool rebuild that did not
    // change the resolution -- a quality toggle that adds or removes another
    // pooled resource relocates these too, because the pool repacks every slot.
    pub(in crate::directx) fn repoint_pooled(
        &mut self,
        device: &ID3D12Device,
        srv_cpu_base: D3D12_CPU_DESCRIPTOR_HANDLE,
        srv_gpu_base: D3D12_GPU_DESCRIPTOR_HANDLE,
        pooled: &GbufferPooled,
    ) {
        let srv_cpu = |gpu: D3D12_GPU_DESCRIPTOR_HANDLE| D3D12_CPU_DESCRIPTOR_HANDLE {
            ptr: srv_cpu_base.ptr + (gpu.ptr - srv_gpu_base.ptr) as usize,
        };
        let (normal_depth, roughness, velocity) = write_pooled_views(
            device,
            GbufferViewSlots {
                normal_depth: (self.normal_depth_rtv, srv_cpu(self.normal_depth_srv_gpu)),
                roughness: (self.roughness_rtv, srv_cpu(self.roughness_srv_gpu)),
                velocity: (self.velocity_rtv, srv_cpu(self.velocity_srv_gpu)),
            },
            pooled,
        );
        self.normal_depth = normal_depth;
        self.roughness = roughness;
        self.velocity = velocity;
    }
}

// Camera + view-projection inputs for the G-buffer pre-pass. The two VPs drive
// rasterisation (jittered) and motion vectors (un-jittered current vs previous).
pub(in crate::directx) struct GbufferPrepassView {
    // Jittered view-projection (rasterisation target).
    pub jittered_vp: [[f32; 4]; 4],
    // Un-jittered current view-projection (motion vectors).
    pub cur_vp: [[f32; 4]; 4],
}

impl DxContext {
    // Encode the unified G-buffer pre-pass: one jittered traversal of the cull
    // records into the normal+depth / roughness / velocity MRT.
    // `velocity_active` is true when a consumer (TAA or FSR) reads motion; when
    // false, cur == prev so the motion channel is a harmless zero.
    pub(in crate::directx) fn encode_gbuffer_prepass(
        &self,
        cmd: &ID3D12GraphicsCommandList,
        frame_idx: usize,
        view: GbufferPrepassView,
        velocity_active: bool,
    ) {
        let GbufferPrepassView {
            jittered_vp,
            cur_vp,
        } = view;
        let gb = match &self.gbuffer {
            Some(g) => g,
            None => return,
        };

        // Upload this frame's view UBO. When velocity is inactive the previous
        // VP equals the current one, so instanced + sky motion is zero.
        let prev_vp = if velocity_active {
            *gb.prev_view_proj.borrow()
        } else {
            cur_vp
        };
        let view_uni = GBufferView {
            jittered_vp,
            cur_vp,
            prev_vp,
            view: self.view.matrix,
        };
        // SAFETY: the destination is the persistent mapping of an UPLOAD-heap constant buffer that
        // init sized for this payload, and the source is a separate live value, so the ranges
        // cannot overlap.
        unsafe {
            std::ptr::copy_nonoverlapping(
                &view_uni as *const GBufferView as *const u8,
                gb.view_ubo_ptrs[frame_idx],
                std::mem::size_of::<GBufferView>(),
            );
        }
        let view_gva = com::gpu_va(&gb.view_ubo_resources[frame_idx]);

        let w = self.extent.render_width;
        let h = self.extent.render_height;

        // The three colour targets are one graph resource (`gbuffer`), so the
        // executor has already put them in RENDER_TARGET for this pass's write
        // and the consumers' barrier takes them back out. `gb.depth` is not part
        // of it and stays in DEPTH_WRITE throughout.
        let rtvs = [gb.normal_depth_rtv, gb.roughness_rtv, gb.velocity_rtv];
        // 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(3, Some(rtvs.as_ptr()), false, Some(&gb.depth_dsv));
            // Cleared alpha 0 marks "no geometry"; roughness 1.0 = non-reflective
            // background; velocity 0 = no motion.
            cmd.ClearRenderTargetView(gb.normal_depth_rtv, &[0.0_f32; 4], None);
            cmd.ClearRenderTargetView(gb.roughness_rtv, &GBUFFER_ROUGHNESS_CLEAR, None);
            cmd.ClearRenderTargetView(gb.velocity_rtv, &[0.0_f32; 4], None);
            cmd.ClearDepthStencilView(gb.depth_dsv, D3D12_CLEAR_FLAG_DEPTH, 1.0, 0, None);
            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 = RECT {
                left: 0,
                top: 0,
                right: w as i32,
                bottom: h as i32,
            };
            cmd.RSSetScissorRects(&[scissor]);
            cmd.IASetPrimitiveTopology(
                windows::Win32::Graphics::Direct3D::D3D_PRIMITIVE_TOPOLOGY_TRIANGLELIST,
            );
        }

        // The pre-pass is GPU-driven: it reuses the main pass's per-frame indirect
        // command buffer (same camera frustum + active LOD) with two
        // `ExecuteIndirect` draws (static + instance prefix, then the skinned
        // tail over the deformed VB). With nothing to draw the pass is the
        // clears above, which is what "no geometry" means to every reader.
        self.encode_gbuffer_prepass_gpu_driven(cmd, frame_idx, view_gva, velocity_active);

        // Snapshot this frame's models into this frame's history slot, AFTER the
        // pass above read the previous one -- which is what keeps a single frame
        // in flight (one slot, read then rewritten) correct.
        self.encode_model_history(cmd, frame_idx);
    }

    // Dispatch the model-history snapshot: one thread per cull record copying
    // `objects[i].model` into this frame's history slot. The slot rests as a
    // shader resource (the pre-pass reads it through a root SRV) and is
    // transitioned to a UAV for the write and back.
    fn encode_model_history(&self, cmd: &ID3D12GraphicsCommandList, frame_idx: usize) {
        let (Some(root_sig), Some(pso), true) = (
            self.cull.model_history_root_sig.as_ref(),
            self.cull.model_history_pso.as_ref(),
            frame_idx < self.cull.prev_model_buffers.len(),
        ) else {
            return;
        };
        let records = self.cull_count();
        if records == 0 {
            return;
        }
        // A rebuilt ring holds nothing these records were written for, so the
        // priming frame fills every slot rather than only its own: the instance
        // region is the one the draw args cannot flag, being init-written. The
        // request arrives through an atomic because passes encode on worker
        // threads and the tracker belongs to the draw-args build.
        let slots = match self
            .cull
            .model_history_prime
            .swap(false, std::sync::atomic::Ordering::Relaxed)
        {
            true => 0..self.cull.prev_model_buffers.len(),
            false => frame_idx..frame_idx + 1,
        };
        let params = concinnity_core::render::uniforms::ModelHistoryParams {
            record_count: records as u32,
            _pad: [0; 3],
        };
        let object_gva = com::gpu_va(&self.cull.object_buffer_resources[frame_idx]);
        // SAFETY: the command list is in the recording state, and every resource and slice these
        // commands name is live for the call.
        unsafe {
            cmd.SetPipelineState(pso);
            cmd.SetComputeRootSignature(root_sig);
            cmd.SetComputeRoot32BitConstants(
                0,
                4,
                &params as *const _ as *const std::ffi::c_void,
                0,
            );
            cmd.SetComputeRootShaderResourceView(1, object_gva);
            for slot in slots {
                let history = &self.cull.prev_model_buffers[slot];
                cmd.SetComputeRootUnorderedAccessView(2, com::gpu_va(history));
                cmd.Dispatch((records as u32).div_ceil(MODEL_HISTORY_THREADGROUP), 1, 1);
                // A UAV barrier, not a transition: a buffer lives in COMMON and
                // is promoted implicitly at each use, so this only has to order
                // the write against the next frame's read of the same slot.
                cmd.ResourceBarrier(&[uav_barrier(history)]);
            }
        }
    }

    // GPU-driven G-buffer pre-pass raster. Reuses the main pass's per-frame
    // indirect command buffer (the camera-frustum cull already produced it, so no
    // extra cull dispatch) with two `ExecuteIndirect` draws: the static + instance
    // prefix `[0, skinned_record_base())` over the static VB (bound to BOTH vertex
    // streams, so prev_pos == cur_pos and the motion is the per-object model delta
    // plus camera), then the skinned tail `[skinned_record_base(), cull_count())`
    // over the current deformed VB (slot 0) + the previous-frame deformed VB
    // (slot 1), so per-vertex skin deformation produces a correct motion vector.
    // model + roughness ride the per-frame GpuObjectData buffer; the previous-frame
    // model rides a parallel buffer. The CPU never walks the static / skinned
    // draw lists.
    fn encode_gbuffer_prepass_gpu_driven(
        &self,
        cmd: &ID3D12GraphicsCommandList,
        frame_idx: usize,
        view_gva: u64,
        velocity_active: bool,
    ) {
        let (Some(pso), Some(root_sig), Some(cmd_sig), true) = (
            self.cull.gbuffer_bindless_pso.as_ref(),
            self.cull.gbuffer_bindless_root_sig.as_ref(),
            self.cull.gbuffer_bindless_cmd_sig.as_ref(),
            frame_idx < self.cull.prev_model_buffers.len(),
        ) else {
            return;
        };
        let indirect = &self.cull.indirect_cmd_buffers[frame_idx];
        let stride = crate::directx::cull::INDIRECT_COMMAND_STRIDE as usize;
        let prefix = self.skinned_record_base();
        let object_gva = com::gpu_va(&self.cull.object_buffer_resources[frame_idx]);

        // The history slot the PREVIOUS frame's snapshot filled; this frame's
        // own snapshot runs after the pass below has read it.
        let frames = self.cull.prev_model_buffers.len();
        let prev_model_gva =
            com::gpu_va(&self.cull.prev_model_buffers[(frame_idx + frames - 1) % frames]);
        let draw_args_gva = com::gpu_va(&self.cull.draw_args_buffer_resources[frame_idx]);

        // Static + instance prefix: bind the static VB to BOTH vertex streams
        // (prev_pos == cur_pos) + the static u32 IB, then one `ExecuteIndirect`
        // over `[0, skinned_record_base())`.
        // 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.SetGraphicsRootSignature(root_sig);
            cmd.IASetVertexBuffers(
                0,
                Some(&[
                    self.geometry.vertex_buffer_view,
                    self.geometry.vertex_buffer_view,
                ]),
            );
            cmd.IASetIndexBuffer(Some(&self.geometry.index_buffer_view));
            // [1] GbView, [2] GpuObjectData, [3] model history, [4] draw args.
            cmd.SetGraphicsRootConstantBufferView(1, view_gva);
            cmd.SetGraphicsRootShaderResourceView(2, object_gva);
            cmd.SetGraphicsRootShaderResourceView(3, prev_model_gva);
            cmd.SetGraphicsRootShaderResourceView(4, draw_args_gva);
            cmd.ExecuteIndirect(
                cmd_sig,
                prefix as u32,
                indirect,
                0,
                None::<&ID3D12Resource>,
                0,
            );
        }
        self.inc_draw_calls(1);
        // The material-referenced shader buckets write their own regions of the
        // command buffer. The pre-pass shades nothing, so every bucket runs under
        // this single pipeline; a bucket whose Shader is not resident is skipped,
        // matching what the colour pass will draw.
        self.inc_draw_calls(self.execute_bucket_regions_shared_pso(
            cmd,
            cmd_sig,
            indirect,
            prefix as u32,
        ));

        // Skinned tail: bind the current deformed VB (slot 0) + the previous-frame
        // deformed VB (slot 1) + the skinned IB, then one `ExecuteIndirect`
        // over `[skinned_record_base(), cull_count())`. The records carry
        // base_vertex = 0 (global skinned indexing). When velocity is inactive the
        // previous deformed VB is the current one, so prev_pos == cur_pos and the
        // motion channel stays zero (GbView prev_vp also equals cur_vp).
        if self.draw.n_skinned > 0
            && let Some(cur_vbv) = self.skinned.deformed_vbvs.get(frame_idx)
        {
            // Read the previous frame's deformed pose only once the ring has been
            // primed (a prior frame's `encode_skin` filled that slot). On the
            // first frame (or after a runtime ring rebuild) the prev slot is
            // unposed, so bind the current deformed buffer as the previous one --
            // prev_pos == cur_pos gives a harmless zero skinned motion vector
            // instead of garbage. Same collapse `velocity_active == false` uses.
            let use_prev_pose = velocity_active
                && self
                    .skinned
                    .deformed_primed
                    .load(std::sync::atomic::Ordering::Relaxed);
            let prev_frame_idx = if use_prev_pose {
                (frame_idx + FRAMES - 1) % FRAMES
            } else {
                frame_idx
            };
            let prev_vbv = self
                .skinned
                .deformed_vbvs
                .get(prev_frame_idx)
                .copied()
                .unwrap_or(*cur_vbv);
            // 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.IASetVertexBuffers(0, Some(&[*cur_vbv, prev_vbv]));
                cmd.IASetIndexBuffer(Some(&self.skinned.index_buffer_view));
                cmd.ExecuteIndirect(
                    cmd_sig,
                    self.draw.n_skinned as u32,
                    indirect,
                    (prefix * stride) as u64,
                    None::<&ID3D12Resource>,
                    0,
                );
            }
            self.inc_draw_calls(1);
            // The current deformed buffer is posed this frame, so next frame's
            // history slot (this slot) is valid -- prime the ring.
            self.skinned
                .deformed_primed
                .store(true, std::sync::atomic::Ordering::Relaxed);
        }
    }
}

#[cfg(test)]
mod tests {
    use super::*;

    // The `GBufferView` layout test lives with the struct in
    // `concinnity_core::render::directx::uniforms`. `GBufferView` fitting the
    // 256-aligned UBO allocation is checked here, where `align256` +
    // `GBUFFER_VIEW_UBO_SIZE` live.
    #[test]
    fn gb_view_uniforms_fits_ubo_allocation() {
        assert!(std::mem::size_of::<GBufferView>() as u64 <= align256(GBUFFER_VIEW_UBO_SIZE));
    }
}