Interface ShadowFeatureOptions

Override the light source for cascade fitting. By default the feature uses the scene's first DirectionalLightComponent.

Override shadowFar passed to DirectionalLightComponent.computeCascadeMatrices.

External skinned shadow casters (the scene-traversal doesn't pre-bucket these — animated models supply them per-frame via this hook).

GPU-instanced skinned shadow casters (repeated static geometry). One instanced draw per batch per cascade.

Override the static shadow-caster list. By default the feature reads frame.shadowCasters (built from the scene's MeshRenderers).

SDSM depth feedback: a callback returning the visible scene's view-linear depth bounds (e.g. () => sdsmFeature.bounds). When it returns non-null the cascades are fit to that slab instead of the full [near, shadowFar] range, for a large texel-density gain on big scenes. See SdsmFeature.

Directional shadow mode. 'cascade' (default) = classic CSM. 'clipmap' = UE5-style virtual-shadow-map clipmap (Phase 1): N concentric, camera-centered, texel-snapped levels — tilt-stable with high near-resolution. Rendered into a separately-keyed deeper shadow-map array. depthBounds/SDSM are ignored in clipmap mode (it's view-independent by construction). The matching lighting feature must read frame.extras.get('shadow:mode') (the bundled DeferredLightingFeature/ForwardPlusFeature do). See TODO/virtual-shadow-maps.md.

Clipmap: number of concentric levels (≤ MAX_SHADOW_LEVELS). Overrides the light's own clipmapLevels when set.

Clipmap: world-space extent of level 0. Overrides the light's clipmapLevel0Extent when set.

Virtual-shadow-map page pooling (Phase 2). Only meaningful with mode:'clipmap'. Renders/allocates only the pages the scene samples into a shared pool atlas (big VRAM win + skips unsampled coarse-level pages) and the lighting samples through a page table. CPU-readback-driven (1-frame latency, like SDSM). PCSS only — virtualised + EVSM2 is a follow-up. Requires the feature to run after the geometry feature (it reads frame.gbuffer.depth).

Virtualised-clipmap page-pool atlas size in texels (default 4096×4096 = 1024 slots of 128² ≈ 64 MB at depth32float). The pool must hold the frame's whole sampled working set; if it overflows, the highest-index needed pages (coarsest levels, box corner) stay NOT_RESIDENT and read as lit — visible as an unshadowed region that slides as the camera-centered clipmap re-snaps with altitude. More clipmap levels and higher altitude both grow the working set, so size this up (e.g. 8192×4096 = 2048 slots) for high-altitude / many-level scenes. Only meaningful with virtualize:true.