concinnity-device 0.19.119

//! Bootstrap for DxContext: Win32 window registration, DXGI factory, adapter
//! selection, D3D12 device + (optional) debug info-queue, command queue,
//! allocator, and swapchain creation. Returns the context's `DxHardware` group
//! and the swapchain it presents through.

use concinnity_core::render::backend_init::SwapchainConfig;
use concinnity_core::render::error::{RenderError, RenderResult};
use concinnity_core::render::hdr_output;
use concinnity_core::render::hdr_output::HdrOutputMode;
use windows::Win32::Graphics::Direct3D12::*;
use windows::Win32::Graphics::Dxgi::Common::*;
use windows::Win32::Graphics::Dxgi::*;
use windows::core::Interface;

use crate::directx::allocator::DeviceAllocator;
use crate::directx::context::{DxHardware, FRAMES};
use crate::directx::error::map_hresult;
use crate::directx::texture::HDR_FORMAT;
use crate::win32::display_mode::FullscreenDisplayMode;
use crate::win32::window::create_window;

// The DXGI swapchain as created on the window, before its back buffers are
// wrapped in the frame's RTV heap. A live reload hands the retained one to the
// rebuilt context.
pub(super) struct DxgiSwapchain {
    pub handle: IDXGISwapChain3,
    pub format: DXGI_FORMAT,
    // Whether the swapchain was created with DXGI_SWAP_CHAIN_FLAG_ALLOW_TEARING
    // (vsync off + tearing supported). Drives the present sync interval / flags
    // and must be mirrored in every `ResizeBuffers` call.
    pub allow_tearing: bool,
}

// The window's own configuration: its title, requested size, and whether the
// title bar is drawn. Mirrors the Metal backend's `WindowConfig`.
pub(super) struct WindowConfig<'a> {
    pub title: &'a str,
    pub width: u32,
    pub height: u32,
    pub title_bar: bool,
}

pub(super) fn setup(
    config: WindowConfig,
    validation: bool,
    vsync: bool,
    swapchain_config: SwapchainConfig,
) -> RenderResult<(DxHardware, DxgiSwapchain)> {
    let WindowConfig {
        title,
        width,
        height,
        title_bar,
    } = config;
    // Validation / debug layer. `D3D12GetDebugInterface` fails when the Windows
    // "Graphics Tools" optional feature is absent, and a run without the layer
    // looks exactly like a run the layer found nothing wrong with, so say which
    // one happened: a verification pass that reports "0 errors" needs to know
    // the layer was there to report them.
    if validation {
        // SAFETY: `d` is a live local the call fills with the debug interface when one is
        // available.
        let debug = unsafe {
            let mut d: Option<ID3D12Debug> = None;
            D3D12GetDebugInterface(&mut d).ok().and(d)
        };
        match debug {
            Some(d) => {
                // SAFETY: `d` is the live debug interface the query above produced, and enabling
                // the layer borrows nothing.
                unsafe { d.EnableDebugLayer() };
                tracing::info!("d3d12 debug layer: enabled");
            }
            None => tracing::warn!(
                "d3d12 debug layer: requested but unavailable (install the Windows \
                 \"Graphics Tools\" optional feature); running unvalidated"
            ),
        }
    }

    // Win32 window (create_window also registers raw mouse input and installs
    // the GWLP_USERDATA state pointer for the wnd_proc).
    let (hwnd, win_state) =
        create_window(title, width, height, title_bar).map_err(RenderError::Other)?;

    // DXGI factory
    // DXGI_CREATE_FACTORY_DEBUG requires the Windows "Graphics Tools" optional
    // feature; fall back silently if it isn't installed.
    let factory: IDXGIFactory4 = if validation {
        // SAFETY: the create descriptor and every pointer it borrows are live for the call, and the
        // new COM object lands in a binding that owns it.
        unsafe {
            CreateDXGIFactory2(DXGI_CREATE_FACTORY_DEBUG)
                .or_else(|_| CreateDXGIFactory2(DXGI_CREATE_FACTORY_FLAGS(0)))
        }
        .map_err(|e| map_hresult(e.code(), "CreateDXGIFactory2"))?
    } else {
        // SAFETY: the create descriptor and every pointer it borrows are live for the call, and the
        // new COM object lands in a binding that owns it.
        unsafe { CreateDXGIFactory2(DXGI_CREATE_FACTORY_FLAGS(0)) }
            .map_err(|e| map_hresult(e.code(), "CreateDXGIFactory2"))?
    };

    let super::adapter::Selection { adapter, device } = super::adapter::select(&factory)?;
    // Try to upcast to IDXGIAdapter3 for QueryVideoMemoryInfo. Optional; pre-
    // WDDM 2.0 drivers may not expose it, in which case the VRAM chip stays
    // at 0 MB and the rest of the overlay still works.
    let adapter3: Option<IDXGIAdapter3> = adapter.cast().ok();

    // Validation message sink
    // Disable break-on-error so the debug layer doesn't terminate the process
    // before we can log the message via tracing.
    let info_queue: Option<ID3D12InfoQueue> = if validation {
        // SAFETY: `iq` is the live info queue this closure was handed, and `filter` (with the
        // `denied` array it points into) outlives the `AddStorageFilterEntries` call at the end of
        // the block.
        let iq = device.cast::<ID3D12InfoQueue>().ok().inspect(|iq| unsafe {
            let _ = iq.SetBreakOnSeverity(D3D12_MESSAGE_SEVERITY_CORRUPTION, false);
            let _ = iq.SetBreakOnSeverity(D3D12_MESSAGE_SEVERITY_ERROR, false);
            let _ = iq.SetBreakOnSeverity(D3D12_MESSAGE_SEVERITY_WARNING, false);
            // A pipeline-library miss is how `pso_library` asks whether the
            // blob already holds a PSO, and it builds the PSO when the answer
            // is no. Every cold run would otherwise warn once per pipeline
            // about a branch the engine took on purpose; `pipeline_cache`
            // reports the library's real state in one line instead.
            let mut denied = [D3D12_MESSAGE_ID_LOADPIPELINE_NAMENOTFOUND];
            let filter = D3D12_INFO_QUEUE_FILTER {
                DenyList: D3D12_INFO_QUEUE_FILTER_DESC {
                    NumIDs: denied.len() as u32,
                    pIDList: denied.as_mut_ptr(),
                    ..Default::default()
                },
                ..Default::default()
            };
            let _ = iq.AddStorageFilterEntries(&filter);
        });
        if iq.is_none() {
            tracing::warn!("d3d12 info queue: unavailable; layer messages will not be logged");
        }
        iq
    } else {
        None
    };

    // Command queue
    let queue_desc = D3D12_COMMAND_QUEUE_DESC {
        Type: D3D12_COMMAND_LIST_TYPE_DIRECT,
        ..Default::default()
    };
    // SAFETY: the create descriptor and every pointer it borrows are live for the call, and the new
    // COM object lands in a binding that owns it.
    let command_queue: ID3D12CommandQueue = unsafe { device.CreateCommandQueue(&queue_desc) }
        .map_err(|e| map_hresult(e.code(), "CreateCommandQueue"))?;

    // HDR-output detection. Walk the adapter's outputs, find the highest
    // max-EDR multiplier reported by any HDR-capable output, and feed it
    // through the asset-side `hdr_display` toggle. EDR support is per-output
    // (per-monitor), so the answer depends on which display the window will
    // land on; before the swapchain exists we have to scan every output and
    // pick the best. A capable output reports `ColorSpace ==
    // DXGI_COLOR_SPACE_RGB_FULL_G2084_NONE_P2020` (the standard "HDR
    // available" signal); `MaxLuminance` in cd/m² divided by the 80-nit SDR
    // reference white gives the EDR multiplier the resolver expects.
    let max_edr = measure_max_edr(&adapter);
    // `mut` so a later PQ-not-supported fallback can downgrade the encoding
    // before the returned `hdr_mode` reaches the caller; see the
    // SetColorSpace1 block below.
    let hdr_display_requested = swapchain_config.hdr_display;
    let mut hdr_mode =
        HdrOutputMode::resolve(hdr_display_requested, swapchain_config.hdr_pq, max_edr);
    if hdr_display_requested && !hdr_mode.is_hdr() {
        tracing::warn!(
            "HDR display requested but the active adapter's outputs report max EDR \
             multiplier {:.3}, falling back to SDR (BGRA8Unorm) output",
            max_edr
        );
    } else if hdr_mode.is_hdr() {
        tracing::info!(
            "HDR display output enabled: max EDR multiplier {:.3} on the active adapter",
            max_edr
        );
    }

    // Swapchain
    // SDR: BGRA8Unorm (the historical default). HDR: RGBA16Float so the
    // compositor receives linear extended-range floats. The scRGB color space
    // is set via `SetColorSpace1` after the cast to `IDXGISwapChain3` below;
    // CreateSwapChain itself does not take a color-space parameter.
    let swapchain_format = if hdr_mode.is_hdr() {
        HDR_SWAPCHAIN_FORMAT
    } else {
        DXGI_FORMAT_B8G8R8A8_UNORM
    };
    // Tearing support gates true uncapped (no-vsync) presentation on the flip
    // model: without it, a windowed flip swapchain paces to the display refresh
    // even at sync interval 0. Probe it via IDXGIFactory5; if vsync is requested
    // or the factory / hardware doesn't support tearing, create the swapchain
    // without the flag (refresh-paced fallback).
    let allow_tearing = !vsync
        && factory
            .cast::<IDXGIFactory5>()
            .ok()
            .map(|f5| {
                // CheckFeatureSupport writes a 4-byte Win32 BOOL; an i32 matches
                // its layout without pulling in the BOOL type.
                let mut data: i32 = 0;
                // SAFETY: a query on a live COM object; the descriptor it reads and the out-
                // parameters it fills are live locals that outlive the call.
                unsafe {
                    f5.CheckFeatureSupport(
                        DXGI_FEATURE_PRESENT_ALLOW_TEARING,
                        &mut data as *mut _ as *mut core::ffi::c_void,
                        std::mem::size_of::<i32>() as u32,
                    )
                }
                .is_ok()
                    && data != 0
            })
            .unwrap_or(false);
    let sc_desc = DXGI_SWAP_CHAIN_DESC1 {
        Width: width,
        Height: height,
        Format: swapchain_format,
        SampleDesc: DXGI_SAMPLE_DESC {
            Count: 1,
            Quality: 0,
        },
        BufferUsage: DXGI_USAGE_RENDER_TARGET_OUTPUT,
        BufferCount: FRAMES as u32,
        SwapEffect: DXGI_SWAP_EFFECT_FLIP_DISCARD,
        Flags: if allow_tearing {
            DXGI_SWAP_CHAIN_FLAG_ALLOW_TEARING.0 as u32
        } else {
            0
        },
        ..Default::default()
    };
    let sc_base: IDXGISwapChain1 =
        // SAFETY: the create descriptor and every pointer it borrows are live for the call, and the
        // new COM object lands in a binding that owns it.
        unsafe { factory.CreateSwapChainForHwnd(&command_queue, hwnd, &sc_desc, None, None) }
            .map_err(|e| map_hresult(e.code(), "CreateSwapChain"))?;
    let swapchain: IDXGISwapChain3 = sc_base
        .cast()
        .map_err(|e| map_hresult(e.code(), "SwapChain3 cast"))?;

    // On the HDR path, tell DXGI which color space the swapchain pixels
    // carry. Two flavors, picked by `hdr_mode.encoding`:
    //
    //   - `ExtendedLinear` → `DXGI_COLOR_SPACE_RGB_FULL_G10_NONE_P709`
    //     (scRGB linear). The compositor maps `1.0` to SDR reference white
    //     and gives the panel headroom above that, same envelope as Metal's
    //     extended-linear Display P3, but Rec.709 primaries. The standard
    //     DXGI linear-HDR signal supported on every recent driver.
    //
    //   - `Pq` → `DXGI_COLOR_SPACE_RGB_FULL_G2084_NONE_P2020` (HDR10 PQ).
    //     The shader emits SMPTE ST 2084 PQ-encoded values directly; the
    //     panel decodes via the PQ EOTF. SDR reference white maps to 203
    //     nits per BT.2408.
    //
    // PQ-not-supported worlds gracefully fall back to scRGB linear (the
    // rewritten encoding is what [`super::DxContext::new`] composes
    // `pq_output` from, so the shader doesn't double-encode). If neither
    // signal is advertised by the swapchain, leave at the platform default
    // and warn; the resolver path has already gated us on the panel
    // reporting HDR headroom, so the format itself works; only the precise
    // encoding hand-off may be wrong.
    if hdr_mode.is_hdr() {
        let pq_max_edr = match hdr_mode {
            HdrOutputMode::Hdr {
                max_edr,
                encoding: hdr_output::HdrEncoding::Pq,
            } => Some(max_edr),
            _ => None,
        };
        let (primary, primary_label) = if pq_max_edr.is_some() {
            (HDR_PQ_COLOR_SPACE, "HDR10 PQ")
        } else {
            (HDR_LINEAR_COLOR_SPACE, "scRGB linear")
        };
        // A PQ failure goes on to try scRGB linear; any other failure is final.
        let outcome = if pq_max_edr.is_some() {
            ""
        } else {
            "; leaving the swapchain at its default color space"
        };
        let primary_attempt = try_color_space(&swapchain, primary);
        match &primary_attempt {
            ColorSpaceAttempt::Applied => {}
            ColorSpaceAttempt::Unsupported(flags) => tracing::warn!(
                "HDR display enabled but the swapchain does not advertise {primary_label} \
                 support (CheckColorSpaceSupport flags = {flags:#x}){outcome}"
            ),
            ColorSpaceAttempt::SetFailed(e) => tracing::warn!(
                "HDR display enabled but SetColorSpace1({primary_label}) failed ({e}); the \
                 compositor may still treat the RGBA16Float swapchain as sRGB{outcome}"
            ),
        }
        if !matches!(primary_attempt, ColorSpaceAttempt::Applied)
            && let Some(max_edr) = pq_max_edr
        {
            match try_color_space(&swapchain, HDR_LINEAR_COLOR_SPACE) {
                ColorSpaceAttempt::Applied => {
                    tracing::warn!("falling back to scRGB linear extended-range output");
                    // Keep the caller's `pq_output` in sync with the swapchain encoding.
                    hdr_mode = HdrOutputMode::Hdr {
                        max_edr,
                        encoding: hdr_output::HdrEncoding::ExtendedLinear,
                    };
                }
                ColorSpaceAttempt::Unsupported(flags) => tracing::warn!(
                    "the swapchain does not advertise the scRGB linear fallback either \
                     (CheckColorSpaceSupport flags = {flags:#x}); leaving the swapchain at its \
                     default color space"
                ),
                ColorSpaceAttempt::SetFailed(e) => tracing::warn!(
                    "scRGB linear fallback also failed ({e}); leaving the swapchain at its \
                     default color space"
                ),
            }
        }
    }

    // Disable Alt+Enter fullscreen toggle.
    // SAFETY: `factory` and `hwnd` are both live, and the association takes no other borrowed
    // state.
    unsafe { factory.MakeWindowAssociation(hwnd, DXGI_MWA_NO_ALT_ENTER) }.ok();

    let hw = DxHardware {
        // Built before the first resource so nothing has to fall back to a
        // committed allocation.
        alloc: DeviceAllocator::new(&device, &command_queue, FRAMES),
        rt_capable: crate::directx::raytrace::raytracing_supported(&device),
        device,
        command_queue,
        adapter: adapter3,
        info_queue,
        hdr_mode,
        swapchain_config,
        fullscreen_display: FullscreenDisplayMode::new(),
        win_state: Some(win_state),
    };
    let swapchain = DxgiSwapchain {
        handle: swapchain,
        format: swapchain_format,
        allow_tearing,
    };
    Ok((hw, swapchain))
}

// Swapchain pixel format on the HDR path. RGBA16Float gives the compositor
// the headroom to drive values past SDR reference white without crushing
// precision; an 8-bit format cannot represent the extended range.
const HDR_SWAPCHAIN_FORMAT: DXGI_FORMAT = DXGI_FORMAT_R16G16B16A16_FLOAT;

// DXGI color space for scRGB linear: Rec.709 primaries, gamma 1.0 (linear),
// extended range. `1.0` is SDR reference white; values above that map to the
// panel's HDR headroom. The standard DXGI signal for "linear HDR", supported
// on every recent driver alongside the older HDR10 (PQ) path.
const HDR_LINEAR_COLOR_SPACE: DXGI_COLOR_SPACE_TYPE = DXGI_COLOR_SPACE_RGB_FULL_G10_NONE_P709;

// DXGI color space for HDR10 PQ: Rec.2020 primaries, SMPTE ST 2084 EOTF
// (PQ), absolute-luminance signal capped at 10,000 cd/m². The shader emits
// PQ-encoded values directly; the panel decodes via the PQ EOTF. SDR
// reference white maps to 203 nits per BT.2408.
const HDR_PQ_COLOR_SPACE: DXGI_COLOR_SPACE_TYPE = DXGI_COLOR_SPACE_RGB_FULL_G2084_NONE_P2020;

// Outcome of tagging the swapchain with one color space.
enum ColorSpaceAttempt {
    Applied,
    // The swapchain does not advertise present support; carries the support flags.
    Unsupported(u32),
    SetFailed(windows::core::Error),
}

fn try_color_space(swapchain: &IDXGISwapChain3, space: DXGI_COLOR_SPACE_TYPE) -> ColorSpaceAttempt {
    // SAFETY: a query on a live COM object; the descriptor it reads and the out-parameters it
    // fills are live locals that outlive the call.
    let support = unsafe { swapchain.CheckColorSpaceSupport(space) }.unwrap_or(0);
    if (support & DXGI_SWAP_CHAIN_COLOR_SPACE_SUPPORT_FLAG_PRESENT.0 as u32) == 0 {
        return ColorSpaceAttempt::Unsupported(support);
    }
    // SAFETY: the swapchain is live and the color space is a plain enum value.
    match unsafe { swapchain.SetColorSpace1(space) } {
        Ok(()) => ColorSpaceAttempt::Applied,
        Err(e) => ColorSpaceAttempt::SetFailed(e),
    }
}

// Largest extended-range color-component multiplier any output on this
// adapter reports. Returns `1.0` on an SDR-only adapter (or when no output
// is available, a head-less unit test) so the resolver stays on the SDR
// path. An HDR output's `MaxLuminance` is in cd/m²; SDR reference white is
// 80 nits, so the EDR multiplier is `MaxLuminance / 80.0`.
fn measure_max_edr(adapter: &IDXGIAdapter1) -> f32 {
    const SDR_REFERENCE_NITS: f32 = 80.0;
    let mut best: f32 = 1.0;
    let mut i: u32 = 0;
    loop {
        // SAFETY: a query on a live COM object; the descriptor it reads and the out-parameters it
        // fills are live locals that outlive the call.
        let output: IDXGIOutput = match unsafe { adapter.EnumOutputs(i) } {
            Ok(o) => o,
            Err(_) => break,
        };
        i += 1;
        let output6: IDXGIOutput6 = match output.cast() {
            Ok(o) => o,
            Err(_) => continue, // pre-Windows-10 output, no HDR info
        };
        // SAFETY: a property query on a live COM object; it only reads.
        let desc1 = match unsafe { output6.GetDesc1() } {
            Ok(d) => d,
            Err(_) => continue,
        };
        // The color-space field is the canonical "HDR available" signal:
        // PQ here means the output is wired to an HDR-capable display.
        let hdr_advertised = desc1.ColorSpace == DXGI_COLOR_SPACE_RGB_FULL_G2084_NONE_P2020;
        if !hdr_advertised {
            continue;
        }
        let nits = desc1.MaxLuminance;
        if nits.is_finite() && nits > 0.0 {
            let edr = nits / SDR_REFERENCE_NITS;
            if edr > best {
                best = edr;
            }
        }
    }
    best
}

pub(super) fn query_msaa_samples(device: &ID3D12Device) -> u32 {
    // Queried against the off-screen HDR target's format: that is the only
    // multisampled render target; the swapchain backbuffer is always 1x.
    for &count in &[4u32, 2] {
        let mut data = D3D12_FEATURE_DATA_MULTISAMPLE_QUALITY_LEVELS {
            Format: HDR_FORMAT,
            SampleCount: count,
            Flags: D3D12_MULTISAMPLE_QUALITY_LEVELS_FLAG_NONE,
            NumQualityLevels: 0,
        };
        // SAFETY: a query on a live COM object; the descriptor it reads and the out-parameters it
        // fills are live locals that outlive the call.
        if unsafe {
            device.CheckFeatureSupport(
                D3D12_FEATURE_MULTISAMPLE_QUALITY_LEVELS,
                &mut data as *mut _ as *mut std::ffi::c_void,
                std::mem::size_of::<D3D12_FEATURE_DATA_MULTISAMPLE_QUALITY_LEVELS>() as u32,
            )
        }
        .is_ok()
            && data.NumQualityLevels > 0
        {
            return count;
        }
    }
    1
}

// The requested HDR sample count clamped to this adapter's ceiling. `requested`
// is 1 whenever a temporal technique is active (see
// `concinnity_core::components::hdr_sample_count`), which collapses the main
// pass to the single-sample path: no resolve step, and `hdr.color` is the
// scene spine.
pub(super) fn resolve_sample_count(supported: u32, requested: u32) -> u32 {
    for candidate in [4u32, 2] {
        if supported >= candidate && requested >= candidate {
            return candidate;
        }
    }
    1
}

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

    #[test]
    fn a_temporal_request_collapses_to_one_sample() {
        for supported in [4, 2, 1] {
            assert_eq!(resolve_sample_count(supported, 1), 1);
        }
    }

    #[test]
    fn a_multisample_request_clamps_to_adapter_support() {
        assert_eq!(resolve_sample_count(4, 4), 4);
        // An adapter that only reaches 2x still honors a 4x request at 2x,
        // the behavior `query_msaa_samples` had on its own.
        assert_eq!(resolve_sample_count(2, 4), 2);
        assert_eq!(resolve_sample_count(1, 4), 1);
    }
}