Gate VSM behind the high renderer tier

Author: proggeramlug

docs/renderer-capability-tiers.md

@@ -13,9 +13,9 @@ because an unrelated optional feature is absent.
 <!-- BEGIN GENERATED CAPABILITY TIERS -->
 | Tier | Materials | Geometry | Shadows | GI | Reflections | AA | Textures | Path tracing | Minimum contract |
 | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- |
-| baseline | Tier C per-material bind groups | CPU direct draws | Cascaded/VSM raster paths | Software SDF, probes, and SSGI | SSR, planar, and probe fallbacks | TAA/CAS/FXAA | Per-material resident textures | Disabled when this tier is forced | Active platform profile |
-| modern | Tier B deterministic paged arrays | CPU direct draws | Cascaded/VSM raster paths | Software SDF, probes, and SSGI | SSR, planar, and probe fallbacks | TAA/CAS/FXAA | Paged texture arrays/atlases | Disabled when this tier is forced | 16 texture-array layers; 8 sampled textures/stage |
-| high-end | Tier A descriptor-indexed global tables | GPU indirect when supported; CPU oracle fallback | Cascaded/VSM raster paths | Ray query when supported; software SDF/SSGI fallback | Ray query when supported; SSR/planar/probe fallback | TAA/CAS/FXAA | Descriptor-indexed texture/sampler arrays | Available only with ray query and required limits | Texture-binding arrays + non-uniform indexing; 2 array elements |
+| baseline | Tier C per-material bind groups | CPU direct draws | Cascaded raster shadows (VSM capability fallback) | Software SDF, probes, and SSGI | SSR, planar, and probe fallbacks | TAA/CAS/FXAA | Per-material resident textures | Disabled when this tier is forced | Active platform profile |
+| modern | Tier B deterministic paged arrays | CPU direct draws | Cascaded raster shadows (VSM capability fallback) | Software SDF, probes, and SSGI | SSR, planar, and probe fallbacks | TAA/CAS/FXAA | Paged texture arrays/atlases | Disabled when this tier is forced | 16 texture-array layers; 8 sampled textures/stage |
+| high-end | Tier A descriptor-indexed global tables | GPU indirect when supported; CPU oracle fallback | VSM page cache with cascaded fallback | Ray query when supported; software SDF/SSGI fallback | Ray query when supported; SSR/planar/probe fallback | TAA/CAS/FXAA | Descriptor-indexed texture/sampler arrays | Available only with ray query and required limits | Texture-binding arrays + non-uniform indexing; 2 array elements |
 <!-- END GENERATED CAPABILITY TIERS -->
 
 This table describes the cross-system path contract after device creation.

docs/virtual-shadow-maps.md

@@ -11,6 +11,14 @@ The default path remains the established cascaded shadow map (CSM). When VSM
 is not requested, Bloom allocates no VSM textures or buffers and compiles the
 canonical shaders without VSM bindings or sampling branches.
 
+VSM is also capability-gated at renderer startup. If `BLOOM_VSM=1` is present
+while `BLOOM_FORCE_RENDER_TIER=baseline` or `modern` selects a supported lower
+tier, Bloom compiles the same canonical CSM shaders and allocates no VSM or
+VSM-caster resources. The request remains visible in telemetry, together with
+`capability_eligible: false`, `enabled: false`, and
+`selection_reason: "lower-tier-csm-fallback"`. The public renderer capability
+report exposes the same state under `runtime_support.virtual_shadows`.
+
 ## Current contract
 
 - Three directional levels, each with a 32 by 32 virtual address space.
@@ -95,7 +103,8 @@ quality and performance fallbacks, not failure states.
 Quality telemetry reports the VSM state under
 `renderer_paths.virtual_shadows`:
 
-- `requested`, `active`, `fallback`, and `dynamic_fallback_mode`;
+- `requested`, `capability_eligible`, `enabled`, `active`,
+  `selection_reason`, `fallback`, and `dynamic_fallback_mode`;
 - physical capacity and depth/metadata/total bytes;
 - receiver demand source and count;
 - receiver-bounds count and active marking backend;

native/shared/src/renderer/capabilities.rs

@@ -62,7 +62,7 @@ pub const CAPABILITY_TIER_DEFINITIONS: [CapabilityTierDefinition; 3] = [
         min_sampled_textures: 0,
         material_bindings: "Tier C per-material bind groups",
         geometry_submission: "CPU direct draws",
-        shadows: "Cascaded/VSM raster paths",
+        shadows: "Cascaded raster shadows (VSM capability fallback)",
         gi: "Software SDF, probes, and SSGI",
         reflections: "SSR, planar, and probe fallbacks",
         anti_aliasing: "TAA/CAS/FXAA",
@@ -79,7 +79,7 @@ pub const CAPABILITY_TIER_DEFINITIONS: [CapabilityTierDefinition; 3] = [
         min_sampled_textures: 8,
         material_bindings: "Tier B deterministic paged arrays",
         geometry_submission: "CPU direct draws",
-        shadows: "Cascaded/VSM raster paths",
+        shadows: "Cascaded raster shadows (VSM capability fallback)",
         gi: "Software SDF, probes, and SSGI",
         reflections: "SSR, planar, and probe fallbacks",
         anti_aliasing: "TAA/CAS/FXAA",
@@ -97,7 +97,7 @@ pub const CAPABILITY_TIER_DEFINITIONS: [CapabilityTierDefinition; 3] = [
         min_sampled_textures: 0,
         material_bindings: "Tier A descriptor-indexed global tables",
         geometry_submission: "GPU indirect when supported; CPU oracle fallback",
-        shadows: "Cascaded/VSM raster paths",
+        shadows: "VSM page cache with cascaded fallback",
         gi: "Ray query when supported; software SDF/SSGI fallback",
         reflections: "Ray query when supported; SSR/planar/probe fallback",
         anti_aliasing: "TAA/CAS/FXAA",

native/shared/src/renderer/capability_api.rs

@@ -163,6 +163,8 @@ impl Renderer {
         });
         out.push_str(",\"gpu_driven\":");
         out.push_str(&self.gpu_driven.report_json());
+        out.push_str(",\"virtual_shadows\":");
+        out.push_str(&self.shadow_map.virtual_map.report_json());
         out.push_str(",\"vsm_gpu_casters\":");
         out.push_str(&self.vsm_gpu_casters.report_json());
         out.push_str(",\"imported_refraction\":");

native/shared/src/renderer/mod.rs

@@ -1832,6 +1832,14 @@ impl Renderer {
         logical_width: u32,
         logical_height: u32,
     ) -> Self {
+        // Optional renderer paths must observe the same accepted tier as
+        // device negotiation before selecting shader variants or resources.
+        // A forced baseline/modern run therefore stays on canonical CSM even
+        // when the high-tier VSM environment switch is also present.
+        let renderer_capabilities =
+            capabilities::RendererCapabilities::detect(device.features(), &device.limits());
+        crate::virtual_shadows::configure_capability_tier(renderer_capabilities.selected_tier);
+
         // EN-063 — the format frames are RENDERED in, as opposed to the
         // format the surface is CONFIGURED with. The tonemapper writes
         // LINEAR values and relies on hardware encode-on-store into an sRGB

native/shared/src/virtual_shadow_report.rs

@@ -33,7 +33,7 @@ pub(super) fn json(vsm: &DirectionalVirtualShadowMap) -> String {
         .map_or(0, |gpu| gpu.receiver_demand.in_flight());
     let gpu_overhead_bytes =
         page_table_bytes + render_staging_bytes + VSM_SAMPLING_PARAMS_BYTES + gpu_receiver_bytes;
-    let (physical_capacity, physical_bytes, gpu_overhead_bytes, render_budget) = if vsm.requested {
+    let (physical_capacity, physical_bytes, gpu_overhead_bytes, render_budget) = if vsm.enabled {
         (
             stats.capacity,
             vsm.cache.memory_bytes(),
@@ -45,7 +45,8 @@ pub(super) fn json(vsm: &DirectionalVirtualShadowMap) -> String {
     };
     format!(
         concat!(
-            "{{\"requested\":{},\"active\":{},",
+            "{{\"requested\":{},\"capability_eligible\":{},\"enabled\":{},\"active\":{},",
+            "\"selection_reason\":\"{}\",",
             "\"projection\":\"camera-centered-page-snapped-clipmap\",",
             "\"fallback\":\"csm\",\"dynamic_fallback\":{},",
             "\"dynamic_fallback_mode\":\"{}\",\"dynamic_fallback_pages\":{},",
@@ -72,8 +73,11 @@ pub(super) fn json(vsm: &DirectionalVirtualShadowMap) -> String {
             "{{\"level\":1,\"resident\":{},\"dirty\":{}}},",
             "{{\"level\":2,\"resident\":{},\"dirty\":{}}}]}}"
         ),
-        vsm.requested,
+        vsm.requested_by_user,
+        vsm.capability_eligible,
+        vsm.enabled,
         vsm.sampling_active,
+        vsm.selection_reason,
         vsm.dynamic_global_fallback || vsm.dynamic_overlay_deferred_pages > 0,
         if vsm.dynamic_global_fallback {
             "whole-frame-csm"
@@ -109,7 +113,7 @@ pub(super) fn json(vsm: &DirectionalVirtualShadowMap) -> String {
         stats.clipmap_pages_dropped,
         vsm.pending.len(),
         render_budget,
-        if !vsm.requested {
+        if !vsm.enabled {
             "disabled"
         } else if vsm.receiver_demand_active {
             "receiver-bounds"

native/shared/src/virtual_shadow_selection.rs

@@ -0,0 +1,91 @@
+use std::sync::OnceLock;
+
+use crate::renderer::capabilities::RendererCapabilityTier;
+
+#[derive(Clone, Copy, Debug, Eq, PartialEq)]
+pub(super) struct VirtualShadowSelection {
+    pub(super) requested_by_user: bool,
+    pub(super) capability_eligible: bool,
+    pub(super) enabled: bool,
+    pub(super) reason: &'static str,
+}
+
+static CONFIGURED_CAPABILITY_TIER: OnceLock<RendererCapabilityTier> = OnceLock::new();
+
+pub(crate) fn configure_capability_tier(tier: RendererCapabilityTier) {
+    let _ = CONFIGURED_CAPABILITY_TIER.set(tier);
+}
+
+fn selection_for(
+    requested_by_user: bool,
+    tier: Option<RendererCapabilityTier>,
+) -> VirtualShadowSelection {
+    let capability_eligible = tier.is_none_or(|tier| tier >= RendererCapabilityTier::HighEnd);
+    let (enabled, reason) = match (requested_by_user, capability_eligible) {
+        (false, _) => (false, "not-requested"),
+        (true, false) => (false, "lower-tier-csm-fallback"),
+        (true, true) => (true, "high-tier-vsm"),
+    };
+    VirtualShadowSelection {
+        requested_by_user,
+        capability_eligible,
+        enabled,
+        reason,
+    }
+}
+
+fn requested_by_user() -> bool {
+    static REQUESTED: OnceLock<bool> = OnceLock::new();
+    *REQUESTED.get_or_init(|| {
+        std::env::var("BLOOM_VSM")
+            .map(|value| {
+                matches!(
+                    value.trim().to_ascii_lowercase().as_str(),
+                    "1" | "on" | "true" | "enabled"
+                )
+            })
+            .unwrap_or(false)
+    })
+}
+
+pub(super) fn selection() -> VirtualShadowSelection {
+    selection_for(
+        requested_by_user(),
+        CONFIGURED_CAPABILITY_TIER.get().copied(),
+    )
+}
+
+pub(crate) fn virtual_shadows_requested() -> bool {
+    selection().enabled
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn requested_vsm_is_enabled_on_high_tier_only() {
+        let disabled = selection_for(false, Some(RendererCapabilityTier::HighEnd));
+        assert!(!disabled.requested_by_user);
+        assert!(disabled.capability_eligible);
+        assert!(!disabled.enabled);
+        assert_eq!(disabled.reason, "not-requested");
+
+        for tier in [
+            RendererCapabilityTier::Baseline,
+            RendererCapabilityTier::Modern,
+        ] {
+            let fallback = selection_for(true, Some(tier));
+            assert!(fallback.requested_by_user);
+            assert!(!fallback.capability_eligible);
+            assert!(!fallback.enabled);
+            assert_eq!(fallback.reason, "lower-tier-csm-fallback");
+        }
+
+        let high = selection_for(true, Some(RendererCapabilityTier::HighEnd));
+        assert!(high.requested_by_user);
+        assert!(high.capability_eligible);
+        assert!(high.enabled);
+        assert_eq!(high.reason, "high-tier-vsm");
+    }
+}

native/shared/src/virtual_shadows.rs

@@ -4,7 +4,6 @@
 //! CSM remains the fallback for absent, dirty, over-budget, or unrendered pages.
 
 use std::collections::HashMap;
-use std::sync::OnceLock;
 #[path = "directional_shadow_clipmap.rs"]
 mod clipmap;
 #[path = "virtual_shadow_gpu_receiver.rs"]
@@ -15,6 +14,11 @@ mod page_priority;
 mod receiver_demand;
 #[path = "virtual_shadow_report.rs"]
 mod report;
+#[path = "virtual_shadow_selection.rs"]
+mod selection;
+
+use selection::selection as virtual_shadow_selection;
+pub(crate) use selection::{configure_capability_tier, virtual_shadows_requested};
 
 pub const VSM_CLIP_LEVELS: u8 = 3;
 pub const VSM_VIRTUAL_PAGES_PER_AXIS: u16 = 32;
@@ -490,7 +494,10 @@ fn paint_debug_cell(
 /// performs no demand walk and allocates no GPU memory, so landing the
 /// foundation cannot change images, frame time, or residency.
 pub struct DirectionalVirtualShadowMap {
-    requested: bool,
+    requested_by_user: bool,
+    capability_eligible: bool,
+    enabled: bool,
+    selection_reason: &'static str,
     sampling_active: bool,
     dynamic_global_fallback: bool,
     dynamic_overlay_pages: Vec<VirtualShadowPage>,
@@ -522,8 +529,8 @@ pub struct DirectionalVirtualShadowMap {
 
 impl DirectionalVirtualShadowMap {
     pub fn new(device: &wgpu::Device, shadow_uniform_layout: &wgpu::BindGroupLayout) -> Self {
-        let requested = virtual_shadows_requested();
-        let requested_capacity = if requested {
+        let selection = virtual_shadow_selection();
+        let requested_capacity = if selection.enabled {
             env_u16(
                 "BLOOM_VSM_PHYSICAL_PAGES",
                 VSM_DEFAULT_PHYSICAL_PAGES,
@@ -547,16 +554,19 @@ impl DirectionalVirtualShadowMap {
             .min(VSM_MAX_PAGE_RENDER_BUDGET)
             .min(buffer_limited_budget.max(1));
         let render_budget = env_u16("BLOOM_VSM_PAGE_BUDGET", 8, 1, max_render_budget).into();
-        let gpu = requested.then(|| {
+        let gpu = selection.enabled.then(|| {
             GpuVirtualShadowResources::new(device, shadow_uniform_layout, capacity, render_budget)
         });
-        let fallback_demand = if requested {
+        let fallback_demand = if selection.enabled {
             centered_directional_demand(0)
         } else {
             Vec::new()
         };
         Self {
-            requested,
+            requested_by_user: selection.requested_by_user,
+            capability_eligible: selection.capability_eligible,
+            enabled: selection.enabled,
+            selection_reason: selection.reason,
             sampling_active: false,
             dynamic_global_fallback: false,
             dynamic_overlay_pages: Vec::new(),
@@ -601,7 +611,7 @@ impl DirectionalVirtualShadowMap {
         self.frame = self.frame.wrapping_add(1).max(1);
         self.cache.begin_frame(self.frame);
         self.pending.clear();
-        if !self.requested {
+        if !self.enabled {
             return;
         }
         self.dynamic_overlay_rendered_pages = 0;
@@ -740,7 +750,7 @@ impl DirectionalVirtualShadowMap {
             self.receiver_demand.clear();
             self.receiver_bounds_signature = 0;
             self.receiver_demand_level_vps = None;
-            self.receiver_marking_backend = if self.requested {
+            self.receiver_marking_backend = if self.enabled {
                 "center-fallback"
             } else {
                 "disabled"
@@ -859,7 +869,7 @@ impl DirectionalVirtualShadowMap {
         if global_fallback {
             self.cache.invalidate_light(0);
         }
-        let sampling_active = self.requested && self.gpu.is_some() && !global_fallback;
+        let sampling_active = self.enabled && self.gpu.is_some() && !global_fallback;
         if !self.sampling_params_initialized
             || sampling_active != self.sampling_active
             || (sampling_active && self.sampling_level_vps != Some(level_vps))
@@ -889,7 +899,7 @@ impl DirectionalVirtualShadowMap {
     }
 
     pub fn requested(&self) -> bool {
-        self.requested
+        self.enabled
     }
 
     pub fn physical_page_view(&self, physical_page: u16) -> Option<&wgpu::TextureView> {
@@ -958,7 +968,7 @@ impl DirectionalVirtualShadowMap {
     }
 
     pub fn debug_images(&self) -> Vec<(&'static str, u32, u32, Vec<u8>)> {
-        if !self.requested {
+        if !self.enabled {
             return Vec::new();
         }
         let (virtual_width, virtual_height, virtual_rgb) = self.cache.debug_virtual_rgb(0, 4);
@@ -1232,20 +1242,6 @@ pub(crate) fn directional_material_shader(source: String) -> String {
     output
 }
 
-pub(crate) fn virtual_shadows_requested() -> bool {
-    static REQUESTED: OnceLock<bool> = OnceLock::new();
-    *REQUESTED.get_or_init(|| {
-        std::env::var("BLOOM_VSM")
-            .map(|value| {
-                matches!(
-                    value.trim().to_ascii_lowercase().as_str(),
-                    "1" | "on" | "true" | "enabled"
-                )
-            })
-            .unwrap_or(false)
-    })
-}
-
 fn env_u16(name: &str, default: u16, min: u16, max: u16) -> u16 {
     std::env::var(name)
         .ok()

native/shared/tests/device_negotiation.rs

@@ -34,6 +34,10 @@ fn negotiated_headless_device_constructs_the_complete_renderer() {
     assert!(public["material_binding"]["selected_tier"].is_string());
     assert!(public["runtime_support"]["path_tracing"].is_boolean());
     assert!(public["runtime_support"]["gpu_driven"]["enabled"].is_boolean());
+    assert!(public["runtime_support"]["virtual_shadows"]["requested"].is_boolean());
+    assert!(public["runtime_support"]["virtual_shadows"]["capability_eligible"].is_boolean());
+    assert!(public["runtime_support"]["virtual_shadows"]["enabled"].is_boolean());
+    assert!(public["runtime_support"]["virtual_shadows"]["selection_reason"].is_string());
 
     // Headless qualification has no swapchain to configure, but it is still
     // uncapped and must retain the requested mode for truthful telemetry.