concinnity-engine 0.19.0

// src/gfx/quality_preset.rs
//
// The master "Graphics Quality" preset and how it resolves to a performance
// ceiling over a world's authored look. The preset is persisted in
// GraphicsSettings; at init it produces a QualityCeiling that clamps the
// perf-relevant Tier-A settings DOWN where the chosen tier (or detected GPU,
// under Auto) cannot honor them. A ceiling never turns a feature on -- it only
// reduces -- so a world authored conservatively is never "upgraded", and an
// explicit per-row user override always wins over the ceiling (applied by the
// caller). The component defaults author the top-tier look, so under `Auto`
// this is what actually picks a world's quality: every tier below Ultra is
// reached by clamping, not by opting in. This keeps the per-field `None = use the world's value` contract: the
// only thing persisted is the one preset marker, not a bake of every field.

use serde::{Deserialize, Serialize};

use crate::components::{
    AaMode, ReflectionBlurResolution, ShadowUpdate, SsgiResolution, UpscaleQuality,
};
use crate::gfx::backend::{GpuProfile, GpuTier};

/// Persisted master graphics-quality choice. `Auto` resolves from the detected
/// GPU tier each launch; a named tier (Low..Ultra) is a fixed ceiling; `Custom`
/// imposes no ceiling (the user's per-row overrides drive). In GraphicsSettings
/// a `None` (never persisted) means "never configured": the first launch seeds
/// `Auto` and saves once.
#[derive(Clone, Copy, Debug, PartialEq, Eq, Serialize, Deserialize)]
pub enum QualityPreset {
    /// Resolve the ceiling from the GPU tier detected at launch.
    Auto,
    /// Fixed low-tier ceiling.
    Low,
    /// Fixed mid-tier ceiling.
    Medium,
    /// Fixed high-tier ceiling.
    High,
    /// Fixed top-tier ceiling; the only one that permits ray-traced reflections.
    Ultra,
    /// No ceiling: the world's authored look and the per-row overrides stand.
    Custom,
}

// A ceiling on the perf-relevant Tier-A settings: which feature toggles are
// permitted (`false` forces the feature off), and the least aggressive render
// scale allowed. A ceiling only reduces quality; it cannot enable a feature the
// world did not author.
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
pub(crate) struct QualityCeiling {
    // The most aggressive anti-aliasing mode the tier permits. Clamps a world's
    // authored mode DOWN by cost rank (Off < FXAA < TAA): a lower tier can force
    // TAA to FXAA (skipping the velocity pre-pass) but never enables a mode the
    // world did not author. The no-ceiling value is `Taa` (the maximum), so an
    // authored mode always stands under it.
    pub aa_mode: AaMode,
    pub ssao: bool,
    pub ssr: bool,
    pub ray_traced_reflections: bool,
    pub ssgi: bool,
    pub auto_exposure: bool,
    // The minimum upscaling the ceiling forces: the effective render scale is the
    // more aggressive (lower internal resolution) of the world's choice and this.
    // `Quality` (the least aggressive) means "no forced upscaling" -- the world's
    // choice stands.
    pub(crate) min_upscale: UpscaleQuality,
    // Caps on the SSGI gather sub-quality (they only bite where `ssgi` is
    // permitted): the finest gather resolution, and the most rays / ray-march
    // steps per pixel. Each clamps DOWN: the effective value is the coarser
    // resolution / smaller count of the world's choice and the cap. The
    // no-ceiling values are the engine maxima (`Full`, 32, 64), so a world's
    // authored value always stands under them.
    pub(crate) ssgi_resolution: SsgiResolution,
    pub(crate) ssgi_rays: u32,
    pub(crate) ssgi_steps: u32,
    // Cap on the roughness-aware reflection blur resolution (only bites where
    // `ssr` or `ray_traced_reflections` is permitted): the finest blur the tier
    // allows, clamping the world's choice coarser. The no-ceiling value is `Full`
    // (finest), so a world's authored value always stands under it.
    pub(crate) reflection_blur_resolution: ReflectionBlurResolution,
    // Cap on the shadow-map cascade resolution in texels (restart-required): the
    // effective size is the smaller of the world's choice and this cap. The
    // no-ceiling value is `u32::MAX`, so a world's authored size always stands.
    pub shadow_map_size: u32,
    // Whether the tier permits the `EveryFrame` shadow re-render cadence (live).
    // When false the cadence is clamped to the cheaper `Hybrid`; the no-ceiling
    // value is `true`, so a world's authored cadence always stands.
    pub(crate) allow_every_frame_shadows: bool,
    // Cap on the scene sampler's max anisotropic-filtering degree
    // (restart-required): the effective degree is the smaller of the world's
    // choice and this cap. The no-ceiling value is `ANISO_MAX` (16, the GPU
    // maximum), so a world's authored degree always stands.
    pub(crate) anisotropy: u32,
    // Cap on the shadow distance in world units (live): the effective distance is
    // the smaller of the world's choice and this cap. The no-ceiling value is
    // `u32::MAX`, so a world's authored distance always stands. A lower tier
    // shadows a shorter distance (cheaper, and sharper per texel).
    pub shadow_distance: u32,
    // Cap on the shadow cascade count (live): the effective count is the smaller
    // of the world's choice and this cap. The no-ceiling value is `4` (the
    // maximum), so a world's authored count always stands. A lower tier renders
    // fewer cascades (one shadow-map render saved per dropped cascade).
    pub shadow_cascades: u32,
    // Cap on the number of distinct planar reflection planes that render a mirror
    // pass each frame (restart-required -- the mirror targets are allocated at
    // backend init). There is no world-authored value: the engine baseline is the
    // capacity maximum (`PLANAR_PLANES_MAX`), so this cap is the effective budget
    // directly. The no-ceiling value is the maximum, so a full-budget world stands.
    // A lower tier renders fewer full render-res MSAA mirror passes (saving VRAM +
    // GPU cost); reflectors past the budget fall back to the box-projected probe
    // cube.
    pub(crate) planar_reflection_planes: u32,
}

// The coarser (higher render-resolution divisor) of two SSGI resolutions, the
// resolution analogue of `more_aggressive_upscale`. Used to clamp a world's
// gather resolution under a ceiling without ever making it finer.
pub(crate) fn coarser_ssgi_resolution(a: SsgiResolution, b: SsgiResolution) -> SsgiResolution {
    if a.scale_divisor() >= b.scale_divisor() {
        a
    } else {
        b
    }
}

// The authored anti-aliasing mode clamped under a ceiling: the cheaper of the
// world's mode and the cap, by the ascending-cost rank `aa_mode_index` defines
// (Off < FXAA < TAA). Never makes AA more aggressive than the world authored.
pub(crate) fn clamp_aa_mode(authored: AaMode, cap: AaMode) -> AaMode {
    use crate::gfx::settings::aa_mode_index;
    if aa_mode_index(authored) <= aa_mode_index(cap) {
        authored
    } else {
        cap
    }
}

// The coarser of two reflection-blur resolutions (the SSGI helper's sibling for
// the reflection blur enum).
pub(crate) fn coarser_reflection_blur(
    a: ReflectionBlurResolution,
    b: ReflectionBlurResolution,
) -> ReflectionBlurResolution {
    if a.scale_divisor() >= b.scale_divisor() {
        a
    } else {
        b
    }
}

// No ceiling: everything permitted, no forced upscaling. The resolved ceiling
// for `Custom` alone -- every `Auto` tier, unclassified hardware included,
// resolves to a named tier.
// The engine maxima for the SSGI sub-quality caps, used wherever a tier imposes
// no SSGI ceiling: `Full` gather resolution, and the upper clamp bounds the
// gather honours (rays <= 32, steps <= 64). A world's authored value always
// stands under these.
const SSGI_RES_MAX: SsgiResolution = SsgiResolution::Full;
const SSGI_RAYS_MAX: u32 = 32;
const SSGI_STEPS_MAX: u32 = 64;
// `Full` (finest) is the no-cap reflection-blur resolution: a world's choice
// always stands coarser-or-equal under it.
const REFLECTION_BLUR_MAX: ReflectionBlurResolution = ReflectionBlurResolution::Full;
// `u32::MAX` is the no-cap shadow-map resolution: a world's authored size always
// stands smaller-or-equal under it.
const SHADOW_SIZE_MAX: u32 = u32::MAX;
// `16` is the no-cap anisotropy degree -- the maximum every backend's API
// guarantees -- so a world's authored degree always stands smaller-or-equal
// under it.
const ANISO_MAX: u32 = 16;
// `u32::MAX` is the no-cap shadow distance: a world's authored distance always
// stands smaller-or-equal under it.
const SHADOW_DIST_MAX: u32 = u32::MAX;
// `4` is the no-cap shadow cascade count (the engine maximum = NUM_SHADOW_CASCADES):
// a world's authored count always stands smaller-or-equal under it.
const SHADOW_CASCADES_MAX: u32 = 4;
// The no-cap planar reflection plane budget: the engine capacity ceiling every
// backend sizes its mirror allocations to. Sourced from the single
// `gfx::planar_reflection` constant so a capacity bump flows here automatically.
const PLANAR_PLANES_MAX: u32 = crate::gfx::planar_reflection::MAX_PLANAR_PLANES as u32;

// The world's shadow re-render cadence clamped under the ceiling: a tier that
// disallows `EveryFrame` forces the cheaper `Hybrid`; otherwise the authored
// cadence stands. Never raises (`Hybrid` -> `EveryFrame`).
pub(crate) fn clamp_shadow_update(
    authored: ShadowUpdate,
    ceiling: &QualityCeiling,
) -> ShadowUpdate {
    if ceiling.allow_every_frame_shadows {
        authored
    } else {
        ShadowUpdate::Hybrid
    }
}

const NONE: QualityCeiling = QualityCeiling {
    aa_mode: AaMode::Taa,
    ssao: true,
    ssr: true,
    ray_traced_reflections: true,
    ssgi: true,
    auto_exposure: true,
    min_upscale: UpscaleQuality::Quality,
    ssgi_resolution: SSGI_RES_MAX,
    ssgi_rays: SSGI_RAYS_MAX,
    ssgi_steps: SSGI_STEPS_MAX,
    reflection_blur_resolution: REFLECTION_BLUR_MAX,
    shadow_map_size: SHADOW_SIZE_MAX,
    allow_every_frame_shadows: true,
    anisotropy: ANISO_MAX,
    shadow_distance: SHADOW_DIST_MAX,
    shadow_cascades: SHADOW_CASCADES_MAX,
    planar_reflection_planes: PLANAR_PLANES_MAX,
};
const LOW: QualityCeiling = QualityCeiling {
    aa_mode: AaMode::Fxaa,
    ssao: false,
    ssr: false,
    ray_traced_reflections: false,
    ssgi: false,
    auto_exposure: true,
    min_upscale: UpscaleQuality::Performance,
    ssgi_resolution: SsgiResolution::Quarter,
    ssgi_rays: 4,
    ssgi_steps: 8,
    reflection_blur_resolution: ReflectionBlurResolution::Quarter,
    shadow_map_size: 1024,
    allow_every_frame_shadows: false,
    anisotropy: 4,
    shadow_distance: 40,
    shadow_cascades: 2,
    // Integrated / weakest tier: keep only the two most impactful mirror planes
    // (e.g. a floor plus one wall); further reflectors take the probe cube.
    planar_reflection_planes: 2,
};
const MEDIUM: QualityCeiling = QualityCeiling {
    aa_mode: AaMode::Taa,
    ssao: true,
    ssr: false,
    ray_traced_reflections: false,
    ssgi: false,
    auto_exposure: true,
    min_upscale: UpscaleQuality::Balanced,
    ssgi_resolution: SsgiResolution::Half,
    ssgi_rays: 8,
    ssgi_steps: 12,
    reflection_blur_resolution: ReflectionBlurResolution::Half,
    shadow_map_size: 2048,
    allow_every_frame_shadows: false,
    anisotropy: 8,
    shadow_distance: 80,
    shadow_cascades: 3,
    // Entry discrete: one more mirror plane than Low before the probe fallback.
    planar_reflection_planes: 3,
};
const HIGH: QualityCeiling = QualityCeiling {
    aa_mode: AaMode::Taa,
    ssao: true,
    ssr: true,
    ray_traced_reflections: false,
    ssgi: true,
    auto_exposure: true,
    min_upscale: UpscaleQuality::Quality,
    ssgi_resolution: SsgiResolution::Half,
    ssgi_rays: 8,
    ssgi_steps: 12,
    reflection_blur_resolution: ReflectionBlurResolution::Half,
    shadow_map_size: 4096,
    allow_every_frame_shadows: false,
    anisotropy: 16,
    shadow_distance: 160,
    shadow_cascades: 4,
    // Mid discrete and up run the full mirror-plane budget, matching the flat
    // pre-scaling default, so a capable GPU is never downgraded.
    planar_reflection_planes: PLANAR_PLANES_MAX,
};
const ULTRA: QualityCeiling = QualityCeiling {
    aa_mode: AaMode::Taa,
    ssao: true,
    ssr: true,
    ray_traced_reflections: true,
    ssgi: true,
    auto_exposure: true,
    min_upscale: UpscaleQuality::Quality,
    ssgi_resolution: SSGI_RES_MAX,
    ssgi_rays: SSGI_RAYS_MAX,
    ssgi_steps: SSGI_STEPS_MAX,
    reflection_blur_resolution: REFLECTION_BLUR_MAX,
    shadow_map_size: SHADOW_SIZE_MAX,
    allow_every_frame_shadows: true,
    anisotropy: ANISO_MAX,
    shadow_distance: SHADOW_DIST_MAX,
    shadow_cascades: SHADOW_CASCADES_MAX,
    planar_reflection_planes: PLANAR_PLANES_MAX,
};

// The active ceiling for the persisted preset and detected GPU. `Auto` maps the
// GPU tier to a named tier; `Custom` imposes no ceiling; a named tier is fixed.
pub(crate) fn resolve_ceiling(preset: QualityPreset, profile: &GpuProfile) -> QualityCeiling {
    match preset {
        QualityPreset::Custom => NONE,
        QualityPreset::Low => LOW,
        QualityPreset::Medium => MEDIUM,
        QualityPreset::High => HIGH,
        QualityPreset::Ultra => ULTRA,
        QualityPreset::Auto => auto_tier(profile).map_or(NONE, |(_, ceiling)| ceiling),
    }
}

// The more aggressive (lower internal resolution) of two upscale qualities,
// ordered by `settings::render_scale_index` (Quality < Balanced < Performance <
// UltraPerformance). Used to clamp a world's render scale under a ceiling's
// `min_upscale` without ever raising it.
pub(crate) fn more_aggressive_upscale(a: UpscaleQuality, b: UpscaleQuality) -> UpscaleQuality {
    use crate::gfx::settings::render_scale_index;
    if render_scale_index(a) >= render_scale_index(b) {
        a
    } else {
        b
    }
}

impl QualityPreset {
    /// The presets in menu-cycle order. The settings-menu master row cycles
    /// through these; `GRAPHICS_QUALITY_OPTIONS` in `gfx::settings` holds the
    /// matching display labels in the same order (locked by a test there).
    pub const ALL: [QualityPreset; 6] = [
        Self::Auto,
        Self::Low,
        Self::Medium,
        Self::High,
        Self::Ultra,
        Self::Custom,
    ];

    // The display name for this preset (the bare label, without an `Auto`
    // tier suffix; see `preset_label`).
    pub(crate) fn name(self) -> &'static str {
        match self {
            Self::Auto => "Auto",
            Self::Low => "Low",
            Self::Medium => "Medium",
            Self::High => "High",
            Self::Ultra => "Ultra",
            Self::Custom => "Custom",
        }
    }
}

// The cycle index of a preset, and the preset at an index, over `ALL`. The
// master settings row cycles indices; these convert to and from the live
// `QualityPreset`. An out-of-range index falls back to `Auto`.
pub(crate) fn preset_index(preset: QualityPreset) -> usize {
    QualityPreset::ALL
        .iter()
        .position(|&p| p == preset)
        .unwrap_or(0)
}
pub(crate) fn preset_at(index: usize) -> QualityPreset {
    QualityPreset::ALL
        .get(index)
        .copied()
        .unwrap_or(QualityPreset::Auto)
}

// The named tier `Auto` resolves to on this GPU, for the menu label (e.g.
// "Auto (High)"). Always `Some` today; the `Option` keeps the label honest if a
// future tier is left unmapped.
pub(crate) fn auto_resolved_name(profile: &GpuProfile) -> Option<&'static str> {
    auto_tier(profile).map(|(name, _)| name)
}

// The named tier `Auto` resolves to on this GPU, as (label, ceiling). One
// table, so the menu label can never disagree with the ceiling actually
// applied.
fn auto_tier(profile: &GpuProfile) -> Option<(&'static str, QualityCeiling)> {
    match profile.tier {
        // A discrete GPU whose driver would not report its VRAM. The world's
        // defaults describe the top-tier look, so declining to clamp here would
        // hand an unclassified card the whole stack; the mid tier keeps the
        // cheap wins (TAA, ambient occlusion) and drops what an unknown GPU
        // might not carry, matching `GpuProfile::UNKNOWN`'s fail-safe intent.
        GpuTier::Unknown => Some(("Medium", MEDIUM)),
        GpuTier::Integrated => Some(("Low", LOW)),
        GpuTier::EntryDiscrete => Some(("Medium", MEDIUM)),
        GpuTier::MidDiscrete => Some(("High", HIGH)),
        GpuTier::HighDiscrete => Some(("Ultra", ULTRA)),
    }
}

// The master row's display text for a preset: a named tier shows its own name,
// while `Auto` annotates the tier it resolved to on the detected GPU (e.g.
// "Auto (High)") so the user can see what the auto-config chose.
pub(crate) fn preset_label(preset: QualityPreset, profile: &GpuProfile) -> String {
    match preset {
        QualityPreset::Auto => match auto_resolved_name(profile) {
            Some(tier) => format!("Auto ({tier})"),
            None => "Auto".to_string(),
        },
        other => other.name().to_string(),
    }
}

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

    fn profile_with_tier(tier: GpuTier) -> GpuProfile {
        GpuProfile {
            tier,
            ..GpuProfile::UNKNOWN
        }
    }

    #[test]
    fn only_custom_imposes_no_ceiling() {
        // Custom never clamps, regardless of hardware.
        assert_eq!(
            resolve_ceiling(
                QualityPreset::Custom,
                &profile_with_tier(GpuTier::Integrated)
            ),
            NONE
        );
        // Auto on an unclassified GPU takes the mid tier rather than handing it
        // the whole stack the component defaults author.
        assert_eq!(
            resolve_ceiling(QualityPreset::Auto, &profile_with_tier(GpuTier::Unknown)),
            MEDIUM
        );
    }

    #[test]
    fn auto_maps_tier_to_named_ceiling() {
        assert_eq!(
            resolve_ceiling(QualityPreset::Auto, &profile_with_tier(GpuTier::Integrated)),
            LOW
        );
        assert_eq!(
            resolve_ceiling(
                QualityPreset::Auto,
                &profile_with_tier(GpuTier::EntryDiscrete)
            ),
            MEDIUM
        );
        assert_eq!(
            resolve_ceiling(
                QualityPreset::Auto,
                &profile_with_tier(GpuTier::MidDiscrete)
            ),
            HIGH
        );
        assert_eq!(
            resolve_ceiling(
                QualityPreset::Auto,
                &profile_with_tier(GpuTier::HighDiscrete)
            ),
            ULTRA
        );
    }

    #[test]
    fn named_presets_resolve_independent_of_hardware() {
        // A named preset ignores the GPU tier.
        let weak = profile_with_tier(GpuTier::Integrated);
        assert_eq!(resolve_ceiling(QualityPreset::Low, &weak), LOW);
        assert_eq!(resolve_ceiling(QualityPreset::Ultra, &weak), ULTRA);
    }

    #[test]
    fn ceilings_are_monotonic_in_tier() {
        // Each tier permits a superset of the next-lower tier's features, so a
        // higher tier never disables something a lower tier allows.
        let order = [LOW, MEDIUM, HIGH, ULTRA];
        for pair in order.windows(2) {
            let (lo, hi) = (pair[0], pair[1]);
            for (lo_on, hi_on) in [
                (lo.ssao, hi.ssao),
                (lo.ssr, hi.ssr),
                (lo.ray_traced_reflections, hi.ray_traced_reflections),
                (lo.ssgi, hi.ssgi),
                (lo.auto_exposure, hi.auto_exposure),
            ] {
                assert!(!lo_on || hi_on, "a higher tier dropped a feature");
            }
            // The AA-mode cap rises (or holds) with the tier: a higher tier
            // never permits a less aggressive (cheaper) anti-aliasing mode.
            assert!(
                crate::gfx::settings::aa_mode_index(lo.aa_mode)
                    <= crate::gfx::settings::aa_mode_index(hi.aa_mode),
                "a higher tier capped AA at a cheaper mode"
            );
            // And never forces more aggressive upscaling than a lower tier.
            assert_eq!(
                more_aggressive_upscale(lo.min_upscale, hi.min_upscale),
                lo.min_upscale
            );
            // The SSGI sub-quality caps rise (or hold) with the tier too: a
            // higher tier never permits fewer rays / steps or a coarser gather.
            assert!(lo.ssgi_rays <= hi.ssgi_rays, "ssgi_rays cap dropped");
            assert!(lo.ssgi_steps <= hi.ssgi_steps, "ssgi_steps cap dropped");
            assert_eq!(
                coarser_ssgi_resolution(lo.ssgi_resolution, hi.ssgi_resolution),
                lo.ssgi_resolution,
                "a higher tier permitted a coarser SSGI gather"
            );
            assert_eq!(
                coarser_reflection_blur(
                    lo.reflection_blur_resolution,
                    hi.reflection_blur_resolution
                ),
                lo.reflection_blur_resolution,
                "a higher tier permitted a coarser reflection blur"
            );
            // The shadow caps rise (or hold) with the tier: a higher tier never
            // permits a smaller shadow map or forbids a cadence a lower tier
            // allowed.
            assert!(
                lo.shadow_map_size <= hi.shadow_map_size,
                "shadow_map_size cap dropped"
            );
            assert!(
                !lo.allow_every_frame_shadows || hi.allow_every_frame_shadows,
                "a higher tier forbade the EveryFrame shadow cadence"
            );
            // The anisotropy cap rises (or holds) with the tier too.
            assert!(lo.anisotropy <= hi.anisotropy, "anisotropy cap dropped");
            // The shadow-distance cap rises (or holds) with the tier too.
            assert!(
                lo.shadow_distance <= hi.shadow_distance,
                "shadow_distance cap dropped"
            );
            // The shadow cascade-count cap rises (or holds) with the tier too.
            assert!(
                lo.shadow_cascades <= hi.shadow_cascades,
                "shadow_cascades cap dropped"
            );
            // The planar reflection plane budget rises (or holds) with the tier too.
            assert!(
                lo.planar_reflection_planes <= hi.planar_reflection_planes,
                "planar plane budget cap dropped"
            );
        }
    }

    // Callers clamp with `authored.min(ceiling.field)`, so what each tier
    // actually promises is the cap value itself.
    #[test]
    fn tier_caps_bound_the_shadow_and_texture_knobs() {
        use crate::components::ShadowUpdate;
        // No ceiling (Custom / Ultra) leaves a world's authored values alone.
        let none = resolve_ceiling(QualityPreset::Custom, &GpuProfile::UNKNOWN);
        assert_eq!(none.shadow_map_size, SHADOW_SIZE_MAX);
        assert_eq!(none.anisotropy, ANISO_MAX);
        assert_eq!(none.shadow_distance, SHADOW_DIST_MAX);
        assert_eq!(none.shadow_cascades, SHADOW_CASCADES_MAX);
        assert_eq!(
            clamp_shadow_update(ShadowUpdate::EveryFrame, &none),
            ShadowUpdate::EveryFrame
        );

        // Low caps every knob hard and forces the cheaper Hybrid cadence.
        let low = resolve_ceiling(QualityPreset::Low, &GpuProfile::UNKNOWN);
        assert_eq!(low.shadow_map_size, 1024);
        assert_eq!(low.anisotropy, 4);
        assert_eq!(low.shadow_distance, 40);
        assert_eq!(low.shadow_cascades, 2);
        assert_eq!(
            clamp_shadow_update(ShadowUpdate::EveryFrame, &low),
            ShadowUpdate::Hybrid
        );
        // The cadence clamp never raises Hybrid to EveryFrame.
        assert_eq!(
            clamp_shadow_update(ShadowUpdate::Hybrid, &none),
            ShadowUpdate::Hybrid
        );

        let medium = resolve_ceiling(QualityPreset::Medium, &GpuProfile::UNKNOWN);
        assert_eq!(medium.shadow_cascades, 3);
    }

    #[test]
    fn planar_plane_budget_scales_with_tier_within_capacity() {
        // No ceiling (Custom / Ultra) permits the full engine capacity, matching
        // the flat pre-scaling default so capable GPUs are never downgraded.
        let none = resolve_ceiling(QualityPreset::Custom, &GpuProfile::UNKNOWN);
        assert_eq!(none.planar_reflection_planes, PLANAR_PLANES_MAX);
        let ultra = resolve_ceiling(QualityPreset::Ultra, &GpuProfile::UNKNOWN);
        assert_eq!(ultra.planar_reflection_planes, PLANAR_PLANES_MAX);
        // High (mid discrete under Auto) also runs the full budget.
        let high = resolve_ceiling(QualityPreset::High, &GpuProfile::UNKNOWN);
        assert_eq!(high.planar_reflection_planes, PLANAR_PLANES_MAX);
        // Lower tiers reduce the budget but keep at least one sharp mirror plane,
        // and never exceed the capacity every backend's allocation is sized to.
        for preset in [QualityPreset::Low, QualityPreset::Medium] {
            let c = resolve_ceiling(preset, &GpuProfile::UNKNOWN);
            assert!(
                c.planar_reflection_planes >= 1,
                "{preset:?} dropped all planes"
            );
            assert!(
                c.planar_reflection_planes < PLANAR_PLANES_MAX,
                "{preset:?} did not reduce the budget"
            );
        }
    }

    #[test]
    fn ssgi_caps_clamp_down_only() {
        // The no-ceiling values are the engine maxima, so any authored value
        // stands under them.
        assert_eq!(NONE.ssgi_rays, 32);
        assert_eq!(NONE.ssgi_steps, 64);
        assert_eq!(NONE.ssgi_resolution, SsgiResolution::Full);
        // The coarser-resolution helper picks the higher divisor (lower quality),
        // and an equal input is returned as-is.
        assert_eq!(
            coarser_ssgi_resolution(SsgiResolution::Full, SsgiResolution::Quarter),
            SsgiResolution::Quarter
        );
        assert_eq!(
            coarser_ssgi_resolution(SsgiResolution::Half, SsgiResolution::Half),
            SsgiResolution::Half
        );
        // Ultra imposes the maxima (no clamp); Low caps hard.
        let ultra = resolve_ceiling(QualityPreset::Ultra, &GpuProfile::UNKNOWN);
        assert_eq!(ultra.ssgi_rays, 32);
        let low = resolve_ceiling(QualityPreset::Low, &GpuProfile::UNKNOWN);
        assert_eq!(low.ssgi_rays, 4);
        assert_eq!(low.ssgi_resolution, SsgiResolution::Quarter);
    }

    #[test]
    fn low_disables_the_expensive_effects() {
        // Resolve through the public path so the assertions are on a runtime
        // value, not the `const LOW` directly.
        let low = resolve_ceiling(QualityPreset::Low, &GpuProfile::UNKNOWN);
        assert!(!low.ssr);
        assert!(!low.ssgi);
        assert!(!low.ray_traced_reflections);
        assert!(!low.ssao);
        // Low caps anti-aliasing at FXAA: it keeps edges smooth nearly for free
        // but skips TAA's velocity pre-pass and history buffer. Auto-exposure is
        // cheap enough to keep on.
        assert_eq!(low.aa_mode, AaMode::Fxaa);
        assert!(low.auto_exposure);
    }

    #[test]
    fn aa_mode_clamps_down_only() {
        // The no-ceiling cap is TAA (the maximum), so any authored mode stands.
        assert_eq!(NONE.aa_mode, AaMode::Taa);
        assert_eq!(clamp_aa_mode(AaMode::Taa, NONE.aa_mode), AaMode::Taa);
        // A lower cap forces a more expensive authored mode down to it, but
        // never raises a cheaper authored mode up.
        assert_eq!(clamp_aa_mode(AaMode::Taa, AaMode::Fxaa), AaMode::Fxaa);
        assert_eq!(clamp_aa_mode(AaMode::Fxaa, AaMode::Taa), AaMode::Fxaa);
        assert_eq!(clamp_aa_mode(AaMode::Fxaa, AaMode::Off), AaMode::Off);
        assert_eq!(clamp_aa_mode(AaMode::Off, AaMode::Taa), AaMode::Off);
        // Ultra imposes the maximum (no clamp); Low caps at FXAA.
        let ultra = resolve_ceiling(QualityPreset::Ultra, &GpuProfile::UNKNOWN);
        assert_eq!(ultra.aa_mode, AaMode::Taa);
        let low = resolve_ceiling(QualityPreset::Low, &GpuProfile::UNKNOWN);
        assert_eq!(low.aa_mode, AaMode::Fxaa);
    }

    #[test]
    fn preset_index_and_at_round_trip() {
        for p in QualityPreset::ALL {
            assert_eq!(preset_at(preset_index(p)), p);
        }
        // Auto leads the cycle order; an out-of-range index falls back to Auto.
        assert_eq!(preset_at(0), QualityPreset::Auto);
        assert_eq!(preset_at(99), QualityPreset::Auto);
    }

    #[test]
    fn auto_label_annotates_the_resolved_tier() {
        // Auto shows the tier it resolved to, so the user sees the auto choice.
        assert_eq!(
            preset_label(
                QualityPreset::Auto,
                &profile_with_tier(GpuTier::MidDiscrete)
            ),
            "Auto (High)"
        );
        assert_eq!(
            preset_label(QualityPreset::Auto, &profile_with_tier(GpuTier::Integrated)),
            "Auto (Low)"
        );
        // An unclassified GPU resolves to the mid tier, and says so.
        assert_eq!(
            preset_label(QualityPreset::Auto, &profile_with_tier(GpuTier::Unknown)),
            "Auto (Medium)"
        );
        // A named preset is just its own name, hardware-independent.
        assert_eq!(
            preset_label(
                QualityPreset::Ultra,
                &profile_with_tier(GpuTier::Integrated)
            ),
            "Ultra"
        );
        // The Auto suffix tracks the resolved ceiling.
        for tier in [
            GpuTier::Integrated,
            GpuTier::EntryDiscrete,
            GpuTier::MidDiscrete,
            GpuTier::HighDiscrete,
        ] {
            let profile = profile_with_tier(tier);
            let suffix = auto_resolved_name(&profile).unwrap();
            assert_eq!(
                preset_label(QualityPreset::Auto, &profile),
                format!("Auto ({suffix})")
            );
        }
    }

    #[test]
    fn more_aggressive_picks_the_lower_resolution() {
        // Higher index = more aggressive (lower internal resolution).
        assert_eq!(
            more_aggressive_upscale(UpscaleQuality::Quality, UpscaleQuality::Performance),
            UpscaleQuality::Performance
        );
        assert_eq!(
            more_aggressive_upscale(UpscaleQuality::UltraPerformance, UpscaleQuality::Balanced),
            UpscaleQuality::UltraPerformance
        );
        // Equal inputs return that quality; a ceiling of Quality never raises.
        assert_eq!(
            more_aggressive_upscale(UpscaleQuality::Balanced, UpscaleQuality::Quality),
            UpscaleQuality::Balanced
        );
    }
}