sealed class Tinman.Engine.Components.ShadowMapping

Performs computations for shadow mapping.

A full computation cycle is made of these steps:

  1. Configure the following values according to the current scene settings:

  2. Configure FilterIn. The cull flags of this filter will be used to collect terrain mesh sectors that act as shadow receivers (see ShadowCascade.Receivers).

  3. Configure FilterOut. Sector marks will be output to this filter for the render batches of the terrain mesh sectors that act as shadow casters (see ShadowCascade.Casters).

  4. Optionally tweak the IMeshBoundMinSize.MinSize and IMeshBoundMinRadius.MinRadius settings, to adjust the behaviour of these internally used objects:

    • TerrainBounds
      This object collects the terrain mesh sectors that will act as shadow receivers. Collecting too many mesh sectors will waste CPU cycles, but collecting too few mesh sectors will reduce shadow frustum fitting, which reduces shadow quality and performance, since more geometry will need to be rendered into the shadowmap.

    • FrustumCulling
      This object will compute the set of mesh sectors that act as shadow casters and thus need to be rendered into the shadowmap. Tweaking can reduce the number of collected mesh sectors, while keeping the triangle count reasonably low, since mesh sectors usually have less triangles when farther away from the view point.

  5. Call Compute, optionally specifying a collector delegate for additional shadow receivers.

  6. Perform triangulation of the terrain mesh (see Triangulation), including the mesh sector marks of FilterOut.

  7. Render the shadowmap batches (see ShadowCascade.Casters) into the shadowmap, using the shadow projection matrix (see ShadowCascade.ShadowProjection).

  8. Render the terrain mesh and other 3D geometry, using the shadow map texture and the shadow matrix to compute dynamic shadows (see ShadowCascade.ShadowMatrix resp. ShadowCascade.ShadowMatrixLocal).

ShadowMapping objects act as resource handles and produce ShadowMappingResource resource objects. ShadowMapping objects with compatible settings will produce the same ShadowMappingResource resource objects.

Public / Constructors


public constructor ShadowMapping → (4)

cameraInfo opt : CameraInfo = null

The terrain-space camera position. If null, a new instance of CameraInfo will be used.

viewport opt : Viewport = null

The projection viewport. If null, a new instance of Viewport will be used.

textureSize opt : int32 = 2048

The shadow map texture size, per cascade.

cascadeCount opt : int32 = 3

The number of shadow cascades.

Creates a new instance of ShadowMapping.

Public / Methods


public method Cascade → (1)

index in : int32

The shadow mapping cascade index (0 is near).

returns → ShadowCascade

The list of shadow mapping cascades.

Returns a shadow mapping cascade.


public method CascadeCullZ → (1)

index in : int32

The shadow mapping cascade index (0 is near).

returns → RangeD

The Z-range, in view-space.

Returns the Z-range in view-space of the given shadow cascade, to be used for culling shadow casters.


public method Compute → (2)

receivers opt : TerrainBoundsDelegate = null

Additional non-terrain shadow receivers. This callback will only be invoked when CameraFrustum has been set.

skipCascades opt : bool = false

Skip computation of shadow cascades? If set to true, only the shadow receivers (see ShadowCascade.Receivers) will be updated and the terrain mesh filter will not be modified (see FilterOut).

Performs shadow mapping computations (see class remarks).


public method UseFilterInForCasters → ()

Applies the cull flags in FilterIn to the shadow casters.

Terrain parts that are not visible may still need to be included as shadow casters. When this method is called, the cull flags currently present in FilterIn are copied and then used as input when computing the shadow caster terrain parts during the next call to Compute.

Public / Attributes


public attribute CameraFrustum → (get,set)

value : IFrustum

The frustum or null to disable clipping.

The camera frustum to use for clipping the bounding boxes of the shadow receivers (see ShadowCascade.Receivers).


public attribute CascadeCount → (get)

value : int32

The cascade count.

The number of shadow map cascades.


public attribute CascadeOverlap → (get,set)

value : float64

The relative overlap.

The relative overlap of the shadow cascades, along the view direction.

The cascade overlap is applied by shifting the far splitting plane away from the view point, by the amount S:

S = Zfar * O

where Zfar is the view-space Z-coordinate of the far splitting plane of the cascade (see ShadowCascade.ViewRangeZ) and O is the configured cascade overlap.

The cascade overlap is not applied to the last cascade.

The default value is 0.1.


public attribute CascadeRange → (get,set)

value : RangeD

The Z-range of the shadow volume.

The fixed Z-range (in camera-space) of the whole shadow volume, before being split into cascades.

This range only influences the Z-slices of the shadow cascades. All collected shadow receivers will be covered by the shadow maps.

If the given range is empty (see RangeD.IsEmpty), the Z-range will be determined automatically from the collected shadow receivers.

The default value is RangeD.Pos.


public attribute FilterIn → (get,set)

value : MeshTreeFilter

The mesh tree filter.

The input mesh tree filter that represents the visible terrain parts.


public attribute FilterOut → (get,set)

value : MeshTreeFilter

The mesh tree filter.

The output mesh filter that will receive marks for each terrain part that acts as a shadow receiver.


public attribute LightDirection → (get,set)

value : Vec3D

The light direction vector.

The light direction.


public attribute LightFix → (get,set)

value : float32

The amount of light-bleeding, will be clamped to [0..1].

Controls the amount of light-bleeding correction.

Light-bleeding may occur in shadowed areas that have multiple occluders. Defaults to 0.25.


public attribute TextureSize → (get)

value : int32

The shadow map size, per cascade.

The shadow map texture size.


public attribute ViewDirection → (get)

value : Vec3D

The unit-length view direction vector.

The camera view direction that has been used for shadow computations.


public attribute ViewPoint → (get)

value : Vec3D

The camera position, in terrain-space.

The camera position that has been used for shadow computations.