concinnity-device 0.19.119

//! Projected (deferred) decals for the D3D12 backend. Each decal is drawn as a
//! unit cube (positions in `[-0.5, 0.5]^3`) transformed by its world model
//! matrix and the camera VP; the fragment shader samples the main pass's depth
//! attachment to reconstruct the world-space sample point at each pixel and
//! tests it against the decal's local bounding box, stamping the texture onto
//! whatever fills the box.
//!
//! Runs after the main HDR resolve and before SSR resolve / TAA, so decals
//! are reflected and tracked by the temporal history just like the rest of
//! the scene. Mirrors src/metal/decal.rs.

use concinnity_core::gfx::frustum::Frustum;
use concinnity_core::render::decal::{DecalRecord, DecalSet};
use concinnity_core::render::error::{RenderError, RenderResult};
use concinnity_core::transform::mat4_inverse;
use windows::Win32::Foundation::RECT;
use windows::Win32::Graphics::Direct3D12::*;
use windows::Win32::Graphics::Dxgi::Common::*;

use super::allocator::{DeviceAllocator, PooledBuffer};
use super::com;
use crate::directx::builtin_shaders;
use crate::directx::builtin_shaders::CompileProgram;
use crate::directx::context::{DxContext, FRAMES, align256, dump_on_err};
use crate::directx::descriptor_slot::DescriptorTables;
use crate::directx::descriptor_slot::SrvSlot;
use crate::directx::error::map_hresult;
use crate::directx::pso::{Blend, Cull, GraphicsPso, Raster};
use crate::directx::root_sig::{RootSig, SamplerState, Visibility};
use crate::directx::texture::{HDR_FORMAT, upload_buffer, write_texture_srv};

// Projected decals. `state` (pipeline + unit-cube buffers + per-frame uniform
// rings) is always built so runtime `add_decal` works from a world that started
// empty; the encoder skips the pass when no slot is live or every live decal
// culls. `set` is the shared slot table, indexing the per-decal albedo SRVs and
// the per-frame params ring by decal id.
pub(in crate::directx) struct DecalState {
    pub state: Option<DecalResources>,
    pub set: DecalSet,
}

// Compile the decal vertex + fragment shaders; the MSAA variant keeps the
// fragment shader's depth SRV declaration in sync with the resource's
// sample count. Used by [`DecalResources::new`] at init and by shader hot-
// reload to rebuild the decal PSO.
pub(in crate::directx) fn compile_decal_shaders(
    msaa_samples: u32,
    hot_reload: bool,
) -> RenderResult<(Vec<u8>, Vec<u8>)> {
    let vs = builtin_shaders::DECAL_VERT.compile(hot_reload)?;
    let ps = builtin_shaders::DECAL_FRAG
        .at(msaa_samples > 1)
        .compile(hot_reload)?;
    Ok((vs, ps))
}

// Rebuild the decal PSO against fresh shader source. Called from the
// DirectX shader hot-reload pass. The root signature is reused; the new
// PSO is returned for the caller to swap in atomically.
pub(in crate::directx) fn rebuild_decal_pso(
    device: &ID3D12Device,
    root_sig: &ID3D12RootSignature,
    msaa_samples: u32,
    hot_reload: bool,
    info_queue: Option<&ID3D12InfoQueue>,
) -> RenderResult<ID3D12PipelineState> {
    let (vs, ps) = compile_decal_shaders(msaa_samples, hot_reload)?;
    dump_on_err(info_queue, create_decal_pso(device, root_sig, &vs, &ps))
}

// Cap on the number of active decals: the SRV heap reserves a fixed block
// of `MAX_DECALS` per-decal albedo descriptors at init, so runtime adds past
// this many return an error. 256 is well under the 1024 SRV slot heap cap
// the existing backend allocates.
pub(in crate::directx) const MAX_DECALS: usize = 256;

// Eight unit-cube corners in `[-0.5, 0.5]^3`. Matches the Metal vertex list.
const CUBE_VERTS: [f32; 24] = [
    -0.5, -0.5, -0.5, 0.5, -0.5, -0.5, 0.5, 0.5, -0.5, -0.5, 0.5, -0.5, -0.5, -0.5, 0.5, 0.5, -0.5,
    0.5, 0.5, 0.5, 0.5, -0.5, 0.5, 0.5,
];

// 36 indices forming 12 triangles wound CCW outward. Matches the Metal
// index list so the rasterized cube exactly mirrors the reference.
const CUBE_INDICES: [u16; 36] = [
    // -Z face                +Z face
    0, 2, 1, 0, 3, 2, 4, 5, 6, 4, 6, 7, // -Y                     +Y
    0, 1, 5, 0, 5, 4, 3, 6, 2, 3, 7, 6, // -X                     +X
    0, 4, 7, 0, 7, 3, 1, 2, 6, 1, 6, 5,
];

// `DecalView` (per-frame) and `DecalParams` (per-decal) are GPU-free layout
// structs that live in `core::render`; re-export them so
// `crate::directx::decal::{DecalView,DecalParams}` are unchanged.
pub(in crate::directx) use concinnity_core::render::uniforms::DecalParams;
pub(in crate::directx) use concinnity_core::render::uniforms::DecalView;

// Root-signature layout (binds 1:1 with the `decal.hlsl` declarations, whose
// `register()` annotations `DXIL_ENTRY_ABI` in build.rs pins):
//   [0] root CBV b0   DecalView    (per-frame)
//   [1] root CBV b1   DecalParams  (per-decal)
//   [2] table  t0     scene depth SRV (Texture2D[MS]<float>)
//   [3] table  t1     decal albedo SRV
//   static sampler s0 : linear clamp
fn create_decal_root_signature(device: &ID3D12Device) -> RenderResult<ID3D12RootSignature> {
    RootSig::new()
        .cbv(0, Visibility::All)
        .cbv(1, Visibility::All)
        .srv_table(0, 1, Visibility::Pixel)
        .srv_table(1, 1, Visibility::Pixel)
        .static_sampler(SamplerState::LinearClamp, 0, Visibility::Pixel)
        .input_layout()
        .build(device, "decal root sig")
}

fn decal_input_layout() -> [D3D12_INPUT_ELEMENT_DESC; 1] {
    [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,
    }]
}

// PSO for the decal pass. Writes the resolved HDR target with src-alpha /
// inv-src-alpha blending: the fragment shader emits `tint * tex.rgb` at the
// computed fade-weighted alpha and the blend composites it onto the scene.
// No depth attachment; the unit-cube + reconstructed-position clip in the
// fragment shader does the volumetric culling.
fn create_decal_pso(
    device: &ID3D12Device,
    root_sig: &ID3D12RootSignature,
    vs: &[u8],
    ps: &[u8],
) -> RenderResult<ID3D12PipelineState> {
    let layout = decal_input_layout();
    GraphicsPso::new(root_sig, vs, ps)
        .target(HDR_FORMAT, Blend::AlphaOver)
        .input_layout(&layout)
        .raster(Raster {
            // Cull front faces: the camera may be inside a decal box. With
            // back-face culling on, entering the volume would make the unit
            // cube disappear; culling the front face keeps the back faces
            // rasterized in both cases.
            cull: Cull::Front,
            depth_clip: false,
            ..Raster::default()
        })
        .build(device, "decal")
}

// Owned by `DxContext` exactly once: the decal pipeline, the unit-cube
// vertex / index buffers, and the per-frame uniform ring (one big upload
// buffer per frame split into per-decal regions). The decal slot table lives on
// `DxContext` itself (mirroring the Metal context layout).
pub(in crate::directx) struct DecalResources {
    pub(in crate::directx) root_sig: ID3D12RootSignature,
    pub(in crate::directx) pso: ID3D12PipelineState,

    // Resources held to keep the GPU memory alive while the views below
    // reference them; the encoder binds through the views.
    #[expect(
        dead_code,
        reason = "held to keep the GPU memory alive; the encoder binds through vertex_buffer_view"
    )]
    pub(in crate::directx) vertex_buffer: PooledBuffer,
    pub(in crate::directx) vertex_buffer_view: D3D12_VERTEX_BUFFER_VIEW,
    #[expect(
        dead_code,
        reason = "held to keep the GPU memory alive; the encoder binds through index_buffer_view"
    )]
    pub(in crate::directx) index_buffer: PooledBuffer,
    pub(in crate::directx) index_buffer_view: D3D12_INDEX_BUFFER_VIEW,

    // Per-frame view UBO (single 144-byte block), persistently mapped.
    pub(in crate::directx) view_ubo_resources: Vec<PooledBuffer>,
    pub(in crate::directx) view_ubo_ptrs: Vec<*mut u8>,
    // Per-frame `MAX_DECALS`-slot params ring. Each slot is `align256(160)`
    // = 256 bytes wide so the per-decal CBV GPU address is naturally aligned.
    pub(in crate::directx) params_ubo_resources: Vec<PooledBuffer>,
    pub(in crate::directx) params_ubo_ptrs: Vec<*mut u8>,
    pub(in crate::directx) params_stride: u64,

    // Heap slot of the first per-decal albedo SRV; slot `i` is the SRV for
    // decal id `i`. Written by `add_decal` / refreshed by `update_texture_slot`
    // when a streamed texture lands.
    pub(in crate::directx) decal_srv_base_slot: usize,
    // Heap slot of the main-depth SRV. Bound at decal pass t0; the resource
    // is transitioned to PIXEL_SHADER_RESOURCE around the pass.
    pub(in crate::directx) depth_srv_gpu: SrvSlot,
}

impl DecalResources {
    // Build the decal pipeline + unit-cube buffers + per-frame uniform
    // rings. Called from `DxContext::new` when the world declares any
    // `Decal` OR unconditionally so runtime `add_decal` works from a world
    // that started empty; the cost is one PSO + a few small buffers.
    pub(in crate::directx) fn new(
        alloc: &DeviceAllocator,
        msaa_samples: u32,
        decal_srv_base_slot: usize,
        depth_srv_gpu: SrvSlot,
        info_queue: Option<&ID3D12InfoQueue>,
        hot_reload: bool,
    ) -> RenderResult<Self> {
        let device = alloc.device();
        let (vs, ps) = compile_decal_shaders(msaa_samples, hot_reload)?;

        let root_sig = dump_on_err(info_queue, create_decal_root_signature(device))?;
        let pso = dump_on_err(info_queue, create_decal_pso(device, &root_sig, &vs, &ps))?;

        // Unit-cube vertex + index buffers.
        let vbytes = bytemuck::cast_slice(CUBE_VERTS.as_slice());
        let ibytes = bytemuck::cast_slice(CUBE_INDICES.as_slice());
        let vertex_buffer = upload_buffer(
            alloc,
            vbytes,
            D3D12_RESOURCE_STATE_VERTEX_AND_CONSTANT_BUFFER,
        )?;
        let index_buffer = upload_buffer(alloc, ibytes, D3D12_RESOURCE_STATE_INDEX_BUFFER)?;
        let vertex_buffer_view = D3D12_VERTEX_BUFFER_VIEW {
            BufferLocation: com::gpu_va(&vertex_buffer),
            SizeInBytes: vbytes.len() as u32,
            StrideInBytes: 12,
        };
        let index_buffer_view = D3D12_INDEX_BUFFER_VIEW {
            BufferLocation: com::gpu_va(&index_buffer),
            SizeInBytes: ibytes.len() as u32,
            Format: DXGI_FORMAT_R16_UINT,
        };

        // Per-frame view UBO.
        let view_size = align256(std::mem::size_of::<DecalView>() as u64);
        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 = alloc.alloc_buffer(
                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| map_hresult(e.code(), "map decal view ubo"))?;
            view_ubo_ptrs.push(ptr as *mut u8);
            view_ubo_resources.push(buf);
        }

        // Per-frame per-decal params ring. One CBV is 256-aligned, so size
        // each slot to align256(sizeof(DecalParams)).
        let params_stride = align256(std::mem::size_of::<DecalParams>() as u64);
        let params_total = params_stride * MAX_DECALS as u64;
        let mut params_ubo_resources: Vec<PooledBuffer> = Vec::with_capacity(FRAMES);
        let mut params_ubo_ptrs: Vec<*mut u8> = Vec::with_capacity(FRAMES);
        for _ in 0..FRAMES {
            let buf = alloc.alloc_buffer(
                params_total,
                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| map_hresult(e.code(), "map decal params ubo"))?;
            params_ubo_ptrs.push(ptr as *mut u8);
            params_ubo_resources.push(buf);
        }

        Ok(Self {
            root_sig,
            pso,
            vertex_buffer,
            vertex_buffer_view,
            index_buffer,
            index_buffer_view,
            view_ubo_resources,
            view_ubo_ptrs,
            params_ubo_resources,
            params_ubo_ptrs,
            params_stride,
            decal_srv_base_slot,
            depth_srv_gpu,
        })
    }
}

// Helpers for writing the main-depth SRV (so the runtime can rebuild it on
// resize if a future change adds that path) and the per-decal albedo SRVs.

// Write the main depth resource's SRV. MSAA: `Texture2DMS<float>`;
// otherwise plain `Texture2D<float>`. Format is the typed view of
// `R32_TYPELESS` (the depth resource's underlying format): `R32_FLOAT`.
pub(in crate::directx) fn write_main_depth_srv(
    device: &ID3D12Device,
    depth: &ID3D12Resource,
    srv_cpu: D3D12_CPU_DESCRIPTOR_HANDLE,
    sample_count: u32,
) {
    let srv_desc = if sample_count > 1 {
        D3D12_SHADER_RESOURCE_VIEW_DESC {
            Format: DXGI_FORMAT_R32_FLOAT,
            ViewDimension: D3D12_SRV_DIMENSION_TEXTURE2DMS,
            Shader4ComponentMapping: D3D12_DEFAULT_SHADER_4_COMPONENT_MAPPING,
            Anonymous: D3D12_SHADER_RESOURCE_VIEW_DESC_0 {
                Texture2DMS: D3D12_TEX2DMS_SRV {
                    UnusedField_NothingToDefine: 0,
                },
            },
        }
    } else {
        D3D12_SHADER_RESOURCE_VIEW_DESC {
            Format: DXGI_FORMAT_R32_FLOAT,
            ViewDimension: D3D12_SRV_DIMENSION_TEXTURE2D,
            Shader4ComponentMapping: D3D12_DEFAULT_SHADER_4_COMPONENT_MAPPING,
            Anonymous: D3D12_SHADER_RESOURCE_VIEW_DESC_0 {
                Texture2D: D3D12_TEX2D_SRV {
                    MipLevels: 1,
                    ..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.CreateShaderResourceView(depth, Some(&srv_desc), srv_cpu) };
}

// Encoder

impl DxContext {
    // Encode the projected-decal pass. Called between the main HDR resolve
    // and the SSR resolve so a decal is reflected by SSR and tracked by
    // TAA's history buffer like the rest of the scene.
    //
    // `vp` is the same jittered view-projection the main pass rasterized
    // with; the inverse drives the world-space reconstruction in the
    // fragment shader.
    pub(in crate::directx) fn encode_decals(
        &self,
        cmd: &ID3D12GraphicsCommandList,
        frame_idx: usize,
        vp: [[f32; 4]; 4],
        frustum: &Frustum,
    ) {
        let decals = match &self.decal.state {
            Some(s) => s,
            None => return,
        };
        // Frustum-cull first so a frame where every live decal lands
        // off-screen skips the pass, including the depth-transition
        // barriers. Peeking answers that without testing any decal twice.
        let mut visible = self.decal.set.visible(frustum).peekable();
        if visible.peek().is_none() {
            return;
        }

        // Upload this frame's view UBO.
        let inv_vp = mat4_inverse(vp);
        let viewport = [
            self.targets.extent.render_width as f32,
            self.targets.extent.render_height as f32,
        ];
        let view_uni = DecalView {
            vp,
            inv_vp,
            viewport,
            _pad: [0.0; 2],
        };
        // 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 DecalView as *const u8,
                decals.view_ubo_ptrs[frame_idx],
                std::mem::size_of::<DecalView>(),
            );
        }
        let view_gva = com::gpu_va(&decals.view_ubo_resources[frame_idx]);
        let params_base_gva = com::gpu_va(&decals.params_ubo_resources[frame_idx]);

        // Main depth is already in a shader-resource state for the fragment's
        // sample: the graph declares this pass's depth read and the executor emits
        // the transition ahead of this command list.

        // The scene spine is a graph resource: this pass declares its
        // read-modify-write, so the executor has already put it in RENDER_TARGET
        // and the next consumer's barrier takes it back out.
        let scene_rtv = self.hdr_scene_rtv();

        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(&scene_rtv), false, 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,
            );
            cmd.IASetVertexBuffers(0, Some(&[decals.vertex_buffer_view]));
            cmd.IASetIndexBuffer(Some(&decals.index_buffer_view));

            cmd.SetPipelineState(&decals.pso);
            cmd.SetGraphicsRootSignature(&decals.root_sig);
            cmd.SetDescriptorHeaps(&[Some(self.descriptors.srv_heap.clone())]);
            cmd.SetGraphicsRootConstantBufferView(0, view_gva);
            cmd.set_graphics_srv_table(2, decals.depth_srv_gpu);
        }

        // Base of this pass's per-decal albedo SRVs, written into the heap at
        // `decal_srv_base_slot + id` by `add_decal`. The heap start is fixed
        // for the heap's lifetime, so it is resolved out of the draw loop and
        // each decal's slot is a stride from here.
        let albedo_base = SrvSlot::at(
            &self.descriptors.srv_heap,
            self.descriptors.srv_descriptor_size,
            decals.decal_srv_base_slot,
        );

        for decal in visible {
            // This frame's ring slot keeps what an earlier frame wrote, so a
            // decal whose record has not changed since is already uploaded.
            if decal.take_upload(frame_idx) {
                // SAFETY: each ring slot is `params_stride * MAX_DECALS` bytes and `add_decal`
                // refuses records past `MAX_DECALS`, so `id * params_stride` stays inside this
                // frame's mapping.
                let dst = unsafe {
                    decals.params_ubo_ptrs[frame_idx]
                        .add((decal.id as u64 * decals.params_stride) as usize)
                };
                // 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(
                        decal.params as *const DecalParams as *const u8,
                        dst,
                        std::mem::size_of::<DecalParams>(),
                    );
                }
            }
            let params_gva = params_base_gva + decal.id as u64 * decals.params_stride;
            let albedo_srv_gpu = albedo_base.offset(decal.id, self.descriptors.srv_descriptor_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.SetGraphicsRootConstantBufferView(1, params_gva);
                cmd.set_graphics_srv_table(3, albedo_srv_gpu);
                cmd.DrawIndexedInstanced(36, 1, 0, 0, 0);
            }
            self.inc_draw_calls(1);
        }
    }
}

// Runtime mutation (RenderBackend::add_decal / remove_decal)

// Runtime-mutation surface driven only by the cn-debug command server
// ([debug/verbs/render.rs]). This module tree is compiled into both the FFI
// library crate (`concinnity_dev`) and the `concinnity` binary; the cn-debug
// chain is reachable from the binary's `main` but not from the library crate's
// (FFI) roots, so dead-code flags these in the lib build. Not backend-specific.
// `allow` (not `expect`) because the same source is live in the binary, where
// an `expect` would be unfulfilled. Suppressing the methods also marks them live
// roots, so the slot-table / SRV-slot fields they touch stay un-flagged on their
// own.
impl DxContext {
    // Append a runtime decal. Writes the per-decal albedo SRV into the
    // reserved heap region; the encoder reads it next frame. Reuses
    // tombstoned slots from a prior `remove_decal` before growing the vec.
    pub(crate) fn add_decal(&mut self, record: DecalRecord) -> RenderResult<usize> {
        let state = self.decal.state.as_ref().ok_or_else(|| {
            RenderError::Other("add_decal: decal pipeline unavailable".to_string())
        })?;
        let base_slot = state.decal_srv_base_slot;

        let last_tex = self.scene.textures.len().saturating_sub(1);
        let tex_idx = record.texture_slot.min(last_tex);

        // Write the SRV for the chosen texture into this decal's heap slot.
        // The slot may be reused from a prior tombstone, in which case the
        // old descriptor is just overwritten.
        let id = self.decal.set.insert(record).map_err(|_| {
            RenderError::Other(format!("add_decal: MAX_DECALS ({MAX_DECALS}) exceeded"))
        })?;
        let srv_cpu = D3D12_CPU_DESCRIPTOR_HANDLE {
            // SAFETY: a property query on a live descriptor heap; it only reads.
            ptr: unsafe {
                self.descriptors
                    .srv_heap
                    .GetCPUDescriptorHandleForHeapStart()
            }
            .ptr + (base_slot + id) * self.descriptors.srv_descriptor_size,
        };
        write_texture_srv(&self.hw.device, &self.scene.textures[tex_idx], srv_cpu);
        Ok(id)
    }

    // Tombstone a runtime decal slot. The id becomes invalid; the next
    // `add_decal` may reuse it. Returns an error when the id is out of
    // range or already tombstoned.
    pub(crate) fn remove_decal(&mut self, decal_id: usize) -> RenderResult<()> {
        self.decal
            .set
            .remove(decal_id)
            .map_err(|e| RenderError::Other(format!("remove_decal: id {decal_id} {e}")))
    }
}