TerrainView
Description
A view onto a 3D terrain mesh.
At runtime, the application loop callbacks of all terrain views of a terrain mesh must be called, as described by IApplication and ApplicationLoop.MainLoop. The time deltas that are passed to IUpdateableFrameTime.UpdateFrameTime will be processed so that all terrain views receive the same time delta for each update cycle.
Updating the terrain views of a terrain mesh with IUpdateableFrameTime.UpdateFrameTime will trigger calls to MeshBuffer.MeshUpdate, to make sure that exactly one mesh buffer update is performed at the beginning of each update cycle. If there are no terrain views, the MeshBuffer.MeshUpdate method will not be called automatically.
For rendering, the terrain feature level (see ITerrainFeatureLevels.FeatureLevel) is clamped to ITerrainFeatureLevels.FeatureLevelMin and ITerrainFeatureLevels.FeatureLevelMax and the clamped feature level is used to create the terrain render effect (see TerrainParameters.FeatureLevel). Each time the terrain render effect is (re-)created, the triangle mode of the triangulation buffer (see TriangulationBuffer) is reset to the default value of the feature level, which is TriangleMode.SectorList for TerrainFeatureLevel.DX11 or higher and TriangleMode.TriangleStrip otherwise.
The terrain view provides a number of aggregated helper objects, which can be used to access / configure specific aspects of the terrain view:
-
ILightingContainer:
Global settings for image-based high-dynamic range lighting -
LightingSpace:
Coordinate system settings for material-based texturing on curved surfaces. -
Shadows:
The helper for performing cascaded shadow-mapping. -
Sky:
Visual settings for the sky background. -
Stage:
The render stage that is used for rendering. -
TriangulationBuffer:
The buffer that holds the result of terrain mesh triangulation. -
Viewport:
The camera viewport of the terrain view. -
VisibleCheck:
The vertex visibility check that is used by terrain mesh refinement.
Use the following properties to control the terrain view behaviour:
-
Bounds:
Sets the pixel bounds of the terrain view. -
ChunkSize:
Controls the granularity of terrain mesh processing. -
CullingCone, CullingDistance:
Controls terrain culling. -
DisplacementScale, DisplacementThreshold:
Controls GPU displacement mapping. -
ITerrainFeatureLevels.FeatureLevel:
The GPU feature level to use for the terrain view. -
Flags:
Sets the terrain view behaviour flags. -
FogDistance:
Controls the scene fog. -
ILightingContainer.LightingMap, LightingNorth:
Controls global lighting. -
ShadowTweak:
Tweaks shadow-mapping. -
IVisibleMask.VisibleMask:
Controls which TerrainDecal / TerrainModel object will be visible in this view.
Public / Constants
ProfilePrepareTerrainMesh
CPU time spent on preparing the terrain, for example culling or texturing (milli-seconds).
ProfileRenderTerrainData
CPU time spent in MeshBuffer.MeshUpdateData and TriangulationBuffer.Update (milli-seconds).
ProfileRenderTerrainPrepare
CPU time spent preparing instanced 3D models and planting (milli-seconds).
ProfileUpdateTerrainData
CPU time spent in MeshBuffer.MeshUpdate and TextureAtlas.TextureUpdate (milli-seconds).
Public / Methods
Public / Attributes
CullingDistance
The distance to use for culling, see DistanceCulling.Distance.
When this property is set to 0, the culling distance will be computed automatically.
DisplacementThreshold
The tessellation threshold for GPU terrain displacement, given as the average edge length of the triangles in the terrain mesh.
FogDistance
The fog distance.
Set to 0 to compute a nice fog distance automatically.
Defaults to 0.
LightingMatrix
Returns the transformation matrix from light-space to terrain-space.
The transformation takes the following settings into account:
LightingNorth
Defines the north-direction in terrain-space to use for setting up the local coordinate system for lighting and material coordinates.
If this vector is equal to Vec4D.Zero, the north-direction will be computed using IGeometry.ComputeNorth, passing in the heightmap coordinates that correspond to the current camera position.
If the Vec4D.W component of this vector is zero, this vector is normalized and used as the north-direction.
If the Vec4D.W component of this vector is not zero, this vector will be scaled by 1/W (resulting in the north position) and the north-direction is computed so that it points from the current camera position towards the north position.
The local coordinate system for lighting and material coordinates is defined as follows:
-
Y+ (up-vector)
The Y-axis is mapped to the up-vector of the terrain.
For planar terrains, the up-vector is computed via IGeometry.ComputeUp.
For geocentric terrains, the up-vector is computed by normalizing the terrain-space position. -
X+ (side-vector)
The X-axis is mapped to the cross product of the north-direction and the up-vector. -
Z+
The Z-axis is mapped to the cross product of the side-vector and the up-vector. -
The coordinate origin is coincident with the camera position in terrain-space.
A terrain is considered to be geocentric iff IGeometry.ToGeocentric returns a non-null value; otherwise it is considered to be planar.
Defaults to Vec4D.Zero
LightingSpace
Returns the helper object that provides coordinate transformation methods between terrain-space, light-space and material-space.
Shadows
The aggregated ShadowMapping object.
The ShadowMapping.CascadeRange property is updated automatically by this TerrainView object. To tweak the range, use ShadowTweak.
ShadowTweak
Tweaks the shadow cascade range by setting the lower bound (see ShadowMapping.Cascade).
TextureProgress
Returns the overall progress of unique terrain texturing.
If the terrain does not have any unique texturing layers, this property will return 100.
TriangulationBuffer
Returns the triangulation buffer that this view is using to render the terrain.
The TriangulationBuffer.Mode property may be set by client code. The terrain view will perform accordingly. The TriangulationBuffer.PrimitiveRestart and TriangulationBuffer.TriangleWinding properties are set by the terrain view and should not be modified by client code.
Viewport
Returns the viewport of this terrain view.
The Height, INearAtZero.NearAtZero, Width, CameraViewport.ZLog and ICameraViewportDepth.ZRange properties are set by the terrain view and should not be modified by client code.