filament-compose/io.github.erkko68.filament.compose.scene/ShadowConfig

ShadowConfig

data class ShadowConfig(val mapSize: Int = 1024, val constantBias: Float = 0.001f, val normalBias: Float = 1.0f, val shadowFar: Float = 0.0f, val shadowNearHint: Float = 1.0f, val shadowFarHint: Float = 100.0f, val stable: Boolean = false, val lispsm: Boolean = false, val cascades: Int = 1, val cascadeSplits: List<Float>? = null, val contactShadows: Boolean = false, val contactShadowDistance: Float = 0.3f, val contactShadowSteps: Int = 8, val bulbRadius: Float = 0.02f, val blurWidth: Float = 0.0f, val elvsm: Boolean = false, val transform: Rotation? = null)

Per-light shadow-map quality, mapping onto the core LightManager.ShadowOptions. Pass a non-null shadow to a DirectionalLight/SunLight/SpotLight/FocusedSpotLight to make it cast shadows; null disables them. (Point lights cannot cast shadows.)

Many fields apply only under a specific view Shadows technique (noted per property). Defaults mirror Filament's, except lispsm (defaults false here for cleaner soft shadows). Filament's polygonOffset* depth-bias fields are deliberately not exposed — they're package-private in the Android binding and so can't be surfaced cross-platform; use constantBias/normalBias for acne instead.

Constructors

ShadowConfig

constructor(mapSize: Int = 1024, constantBias: Float = 0.001f, normalBias: Float = 1.0f, shadowFar: Float = 0.0f, shadowNearHint: Float = 1.0f, shadowFarHint: Float = 100.0f, stable: Boolean = false, lispsm: Boolean = false, cascades: Int = 1, cascadeSplits: List<Float>? = null, contactShadows: Boolean = false, contactShadowDistance: Float = 0.3f, contactShadowSteps: Int = 8, bulbRadius: Float = 0.02f, blurWidth: Float = 0.0f, elvsm: Boolean = false, transform: Rotation? = null)

Properties

blurWidth

val blurWidth: Float

Blur width; only under the Shadows.Vsm technique. 0 disables.

bulbRadius

val bulbRadius: Float

Soft-shadow penumbra size, world units. Only under Shadows.Dpcf/Shadows.Pcss.

cascades

val cascades: Int

Directional-only: number of CSM cascades (1–4). >1 sharpens large scenes.

cascadeSplits

val cascadeSplits: List<Float>?

Optional explicit cascade split positions (size cascades - 1, camera-Z 0..1). Null auto-computes uniform splits.

constantBias

val constantBias: Float

World-space depth bias pushing shadows off surfaces (reduces acne). Ignored for VSM.

contactShadowDistance

val contactShadowDistance: Float

SSCS max occluder distance, world units.

contactShadows

val contactShadows: Boolean

Enable screen-space contact shadows (SSCS) for fine, close-up contact detail.

contactShadowSteps

val contactShadowSteps: Int

SSCS ray-march step count (directional lights only); higher = better, costlier.

elvsm

val elvsm: Boolean

Exponential Layered VSM — better light-leak reduction at 2× shadow memory. Only under Shadows.Vsm.

lispsm

val lispsm: Boolean

Light-space perspective shadow maps — boosts effective resolution near the camera, but can worsen DPCF/PCSS/VSM penumbra artifacts. Default false; ignored when stable is true.

mapSize

val mapSize: Int

Shadow-map resolution in texels; power-of-two ≥ 8. Higher = sharper but costlier.

normalBias

val normalBias: Float

Normal-scaled bias; typically 1.0. Ignored for VSM.

shadowFar

val shadowFar: Float

Directional-only: distance after which shadows are clipped. 0 = camera far.

shadowFarHint

val shadowFarHint: Float

Concentrate shadow resolution up to this camera distance (world units).