ShadowOptions

VSM-only shadow options.

Split positions for shadow cascades along the camera's Z axis. Camera near plane = 0.0f, far plane = 1.0f. For N cascades, store N-1 split positions (e.g., for 4 cascades: 0.25f, 0.50f, 0.75f). Use ShadowCascades helper methods to compute. Default: 0.125f, 0.25f, 0.50f.

Constant bias in world units (e.g., meters) to move shadows away from the light. Ignored for VSM shadow type. Default: 0.001 (1mm).

Light-space perspective shadow mapping (LiSPSM) improves effective shadow resolution without cascades. Incompatible with large blur widths. Disable if blurring artifacts become problematic (only relevant for VSM with blur or PCSS shadow types). Automatically disabled if stable is true. Default: true.

Size of the shadow map in texels. Must be a power of two and at least 8. Default: 1024. Larger values improve shadow quality but hurt performance.

Per-light cap on the PCSS penumbra ratio, applied as a smooth asymptotic squash. 0 defers to the View-wide View.SoftShadowOptions.maxPenumbraRatio. Default: 0.0.

Per-light limit, in world units, on the PCSS blocker-search footprint. 0 defers to the View-wide View.SoftShadowOptions.maxSearchRadius. Default: 0.0.

Maximum shadow-occluder distance for SSCS in world units. (ignored for non-directional lights). Default: 0.3 (30 cm).

Scale for maximum sampling error to move shadows away from fragment normals. Should typically be 1.0. Ignored for VSM shadow type. Default: 1.0.

Per-light scale on the PCSS geometric ratio — how fast the shadow softens with blocker distance — modulated with View.SoftShadowOptions.penumbraRatioScale. Default: 1.0.

Per-light scale on the final PCSS penumbra size, modulated with the View-wide View.SoftShadowOptions.penumbraScale (global * local). Default: 1.0.

Constant bias in depth-resolution units by which shadows are moved away from the light. The default value of 0.5 is used to round depth values up. Generally this value shouldn't be changed or at least be small and positive. Ignored when the View's ShadowType is set to VSM. Default: 0.5.

Bias based on the change in depth in depth-resolution units by which shadows are moved away from the light. The default value of 2.0 works well with SHADOW_SAMPLING_PCF_LOW. Generally this value is between 0.5 and the size in texel of the PCF filter. Setting this value correctly is essential for LiSPSM shadow maps. Ignored when the View's ShadowType is set to VSM. Default: 2.0.

Enable screen-space contact shadows (SSCS) for more detailed shadow transitions. Useful in large scenes; adds overhead. Applies regardless of shadow-caster status. Default: false.

Light bulb radius for soft shadow effects (DPCF/PCSS only). For spot and point lights, this is the radius of the light bulb in meters. For directional lights, this is tan(angularRadius). Default: -1.0 (automatic calculation based on light type).

Number of shadow cascades (1-4). Values > 1 enable Cascaded Shadow Mapping (CSM). Only applicable to directional lights. When using cascades, cascadeSplitPositions must also be set. Default: 1.

Distance from camera after which shadows are clipped (directional lights only). Use 0.0 to use the camera's far distance. Improves quality and performance by discarding distant shadows that don't contribute. Default: 0.0.

Optimize shadow quality until this distance. Shadows render behind this distance but may have degraded quality. Use Float.POSITIVE_INFINITY for camera far distance. Default: 100.0.

Optimize shadow quality from this distance onward. Shadows render in front of this distance but may have degraded quality. Use 0.0 for camera near distance. Default: 1.0 (1 meter). Quality may degrade when this is reduced significantly.

When true, prioritizes stability over resolution by disabling resolution-enhancing features. Disables LiSPSM. Produces lower-resolution but stable shadows. Default: false.

Number of ray-marching steps for SSCS (ignored for non-directional lights). Default: 8.

Transform the shadow direction via a unit quaternion (artistic use only). Ignored for non-directional lights. Default: identity.

Options available when the View's ShadowType is set to VSM.