class ShadowMapping in Tinman.AddOns.Components

Performs computations for shadow mapping.

sealed class	ShadowMapping	implements	IMeshBoundMinRadius
			IMeshBoundMinSize
			INearAtZero
			IResourceHandle
		extends	MeshBoundBase

Remarks

A full computation cycle is made of these steps:

1. Configure the following values according to the current scene settings:
   • CameraInfo
   • CameraFrustum
   • Viewport
   • LightDirection
2. Configure FilterIn. The cull flags of this filter will be used to collect terrain mesh sectors that act as shadow receivers (see 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 Casters).
4. Optionally tweak the MinSize and 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 Casters) into the shadowmap, using the shadow projection matrix (see ShadowProjection).
8. Render the terrain mesh and other 3D geometry, using the shadow map texture and the shadow matrix to compute dynamic shadows (see ShadowMatrix resp. ShadowMatrixLocal).

ShadowMapping objects act as resource handles and produce ShadowMappingResource resource objects.

Public / Attributes

CameraFrustum

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

public property	CameraFrustum { get set }
type	IFrustum
value		The frustum or null to disable clipping.

CameraInfo

The object that provides the current camera position.

public property	CameraInfo { get set }
type	CameraInfo
value	[not-null]	The camera position provider.
implements	ICameraInfoDependent.CameraInfo

CascadeCount

The number of shadow map cascades.

public property	CascadeCount { get }
type	int32
value	[>=1]	The cascade count.

CascadeOverlap

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

public property	CascadeOverlap { get set }
type	float64
value	[>=0]	The relative overlap.

Remarks:

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 ViewRangeZ) and O is the configured cascade overlap.

The cascade overlap is not applied to the last cascade.

The default value is 0.1.

CascadeRange

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

public property	CascadeRange { get set }
type	RangeD
value		The Z-range of the shadow volume.

Remarks:

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 IsEmpty), the Z-range will be determined automatically from the collected shadow receivers.

The default value is Zero.

FilterIn

public property	FilterIn { get set }
type	MeshTreeFilter
value

FilterOut

public property	FilterOut { get set }
type	MeshTreeFilter
value

HasMesh

Has this object been bound to an IMesh object?

public property	HasMesh { get }
type	bool
value		true if this object is currently bound to an IMesh, false if not.
inherited	MeshBoundBase.HasMesh

LightDirection

The light direction.

public property	LightDirection { get set }
type	Vec3D
value		The light direction vector.

Mesh

The CLOD mesh this object is currently bound to.

public property	Mesh { get }
type	IMesh
value		The CLOD mesh or null.
inherited	MeshBoundBase.Mesh

MinRadius

The mesh sector quadtree is traversed until the bounding sphere radius of a mesh sector falls below this limit.

public property	MinRadius { get set }
type	float32
value	[>=0]	The minimum bounding sphere radius, in terrain-space.
implements	IMeshBoundMinRadius.MinRadius

Remarks:

The default value is 0 (i.e. the entire mesh is traversed).

MinSize

The mesh sector quadtree is traversed until the projected screen-size of a mesh sector falls below this limit.

public property	MinSize { get set }
type	float32
value	[>=0]	Minimum sector size, in screen-space.
implements	IMeshBoundMinSize.MinSize

Remarks:

This value is the square root of the approximated pixel area of the mesh sector on the screen.

The default value is 256.0f pixels.

NearAtZero

Is the near-clipping plane mapped to 0 in clip-space (true), or is it mapped to -1 (false)?

public property	NearAtZero { get set }
type	bool
value		The mapping behaviour for the near-clipping plane.
implements	INearAtZero.NearAtZero

Remarks:

The default value is true.

ViewDirection

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

public property	ViewDirection { get }
type	Vec3D
value		The unit-length view direction vector.

See also:

Compute

ViewPoint

The camera position that has been used for shadow computations.

public property	ViewPoint { get }
type	Vec3D
value		The camera position, in terrain-space.

See also:

Compute

Viewport

The current viewport object.

public property	Viewport { get set }
type	Viewport
value	[not-null]	The viewport object.
implements	IViewportDependent.Viewport

Public / Constructors

ShadowMapping

Creates a new instance of ShadowMapping.

public constructor	ShadowMapping (CameraInfo cameraInfo = null, Viewport viewport = null, int32 cascadeCount = 3)
params	cameraInfo		The terrain-space camera position. If null, a new instance of CameraInfo will be used. Defaults to null.
	viewport		The projection viewport. If null, a new instance of Viewport will be used. Defaults to null.
	cascadeCount	[>=1]	The number of shadow cascades.

Public / Methods

Cascade

Returns a shadow mapping cascade.

public method	Cascade (int32 index)
type	ShadowCascade
params	index	[0..CascadeCount-1]	The shadow mapping cascade index (0 is near).
returns		[not-null]	The list of shadow mapping cascades.

CascadeCullZ

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

public method	CascadeCullZ (int32 index)
type	RangeD
params	index	[0..CascadeCount-1]	The shadow mapping cascade index (0 is near).
returns			The Z-range, in view-space.

Compute

Performs shadow mapping computations (see class remarks).

public method	Compute (TerrainBoundsDelegate receivers = null, bool skipCascades = false)
params	receivers		Additional non-terrain shadow receivers. This callback will only be invoked when CameraFrustum has been set.
	skipCascades		Skip computation of shadow cascades? If set to true, only the shadow receivers (see Receivers) will be updated and the terrain mesh filter will not be modified (see FilterOut). Defaults to false.

CreateResource

Creates a new resource object, using the given graphics context.

[OwnerReturn]
public method	CreateResource (Graphics graphics)
type	IResource
params	graphics	[not-null]	The graphics context to use.
returns			The resource object or null.
implements	IResourceHandle.CreateResource

Remarks:

Resource objects may implement the IMemoryConsumption interface. In this case, the reported memory consumption will be interpreted as an estimate on how much GPU memory is consumed by the resource. This estimate can then be used for resource caching (e.g. CacheMemory).

Equals

Compares this object with the given one.

[Pure]
public method	Equals (IResourceHandle other)
type	bool
params	other		The object to compare to.
returns			true if this object is equal to other, false if not.
implements	IEquatable.Equals

GetHashCode

[Pure]
public override method	GetHashCode ()
type	int32

MeshBind

Binds this object to the given IMesh.

public override method	MeshBind (IMesh mesh)
params	mesh		The mesh object.
overrides	MeshBoundBase.MeshBind

MeshUnbind

Unbinds this object from its current IMesh.

public override method	MeshUnbind ()
overrides	MeshBoundBase.MeshUnbind