sealed class Tinman.Engine.Components.TerrainView

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:

Public / Constants


public static readonly attribute ProfileGpuRateTerrainTriangulate → (ProfilerValue)

GPU time spent on terrain mesh triangulation (milli-seconds).


public static readonly attribute ProfilePipelineDraw → (ProfilerValue)


public static readonly attribute ProfilePipelineModels → (ProfilerValue)


public static readonly attribute ProfilePipelinePrimitives → (ProfilerValue)


public static readonly attribute ProfilePipelineStateGeometry → (ProfilerValue)


public static readonly attribute ProfilePipelineStateMaterial → (ProfilerValue)


public static readonly attribute ProfilePipelineStatePass → (ProfilerValue)


public static readonly attribute ProfilePrepareTerrainMesh → (ProfilerValue)

CPU time spent on preparing the terrain, for example culling or texturing (milli-seconds).


public static readonly attribute ProfilePrepareTerrainShadow → (ProfilerValue)

CPU time spent on preparing shadow mapping (milli-seconds).


public static readonly attribute ProfilePrepareTerrainTriangulate → (ProfilerValue)

CPU time spent on terrain mesh triangulation (milli-seconds).


public static readonly attribute ProfileRenderTerrainData → (ProfilerValue)

CPU time spent in MeshBuffer.MeshUpdateData and TriangulationBuffer.Update (milli-seconds).


public static readonly attribute ProfileRenderTerrainMesh → (ProfilerValue)

CPU time spent on rendering the terrain (milli-seconds).


public static readonly attribute ProfileRenderTerrainModels → (ProfilerValue)

CPU time spent on rendering 3D models and planting (milli-seconds).


public static readonly attribute ProfileRenderTerrainPrepare → (ProfilerValue)

CPU time spent preparing instanced 3D models and planting (milli-seconds).


public static readonly attribute ProfileRenderTerrainShadow → (ProfilerValue)

CPU time spent on rendering the shadow maps (milli-seconds).


public static readonly attribute ProfileTerrain → (ProfilerValue)

A profiler value that groups values that are related to terrain processing.


public static readonly attribute ProfileTerrainBandwidth → (ProfilerValue)

Amount of data transfer from CPU to GPU, in megabytes per second.


public static readonly attribute ProfileTerrainCacheResource → (ProfilerValue)

Resource cache utilization (percent).


public static readonly attribute ProfileTerrainCacheTexture → (ProfilerValue)

Texture tile utilization of the texture atlas (percent).


public static readonly attribute ProfileTerrainCacheVertices → (ProfilerValue)

Visible vertices in the terrain mesh buffer (percent).


public static readonly attribute ProfileTerrainLocality → (ProfilerValue)

Estimated cache locality of current terrain.


public static readonly attribute ProfileUpdateTerrainData → (ProfilerValue)

CPU time spent in MeshBuffer.MeshUpdate and TextureAtlas.TextureUpdate (milli-seconds).

Public / Constructors


public constructor TerrainView → (2)

terrain in : TerrainMesh

The terrain mesh to use.

stage opt : IRenderStage own = null

The render stage to use. If null, RenderStage.Default will be used. A full frame will be rendered when IRenderable.Render is called.

Creates a new instance of TerrainView.

Public / Methods


public method ClearCache → ()

Clears the terrain view caches.


2 overloads

public method Flag1 → (1)

flags in : TerrainViewFlags

The flags to query.

returns → bool

true if at least one flag in flags in is set,
false if none of the given flags in is set.

Queries terrain view flags.

public method Flag2 → (2)

flags in : TerrainViewFlags

The flags to update.

state in : bool

true to set the given flags in,
false to clear the given flags in.

Updates terrain view flags.


public static method ProfilePipelineProduce → (2)

profiler in : IProfiler

The profiler to use.

statistics in : ModelRendererStats

The input values to use.

Produces profiler variable values.


public method ResetCamera → ()

Resets the terrain view camera to the standard position for the terrain mesh.

Public / Attributes


public attribute Bounds → (get,set)

value : Box2I

The screen bounds.

The screen bounds of this terrain view.

See also



public attribute ChunkSize → (get,set)

value : int32

The chunk size, see IMeshBoundMinSize.

The overall mesh traversal chunk size.

Defaults to 256


public attribute CullingCone → (get,set)

value : float64

The cone culling angle.

The cone angle to use for culling, see ConeCulling.ConeAngle.


public attribute CullingDistance → (get,set)

value : float64

The culling distance value.

The distance to use for culling, see DistanceCulling.Distance.

When this property is set to 0, the culling distance will be computed automatically.


public attribute DisplacementScale → (get,set)

value : float32

The uniform scale factor.

Uniform scale factor for GPU terrain displacement.


public attribute DisplacementThreshold → (get,set)

value : float32

The tessellation threshold, in screen-space.

The tessellation threshold for GPU terrain displacement, given as the average edge length of the triangles in the terrain mesh.


public attribute Flags → (get,set)

value : TerrainViewFlags

The behaviour flags.

The behaviour flags of this terrain view.

Defaults to FlagsDefault.


public attribute FogDistance → (get,set)

value : float64

The fog distance, in terrain-space.

The fog distance.

Set to 0 to compute a nice fog distance automatically.

Defaults to 0.


public attribute IsTexturingBusy → (get)

value : bool

true if texture tiles are being computed, false if texturing is idle.

Returns the overall status of unique terrain texturing.


public attribute LightingMatrix → (get)

value : Mat3D

The transformation matrix from light-space to terrain-space.

Returns the transformation matrix from light-space to terrain-space.

The transformation takes the following settings into account:


public attribute LightingNorth → (get,set)

value : Vec4D

The north-direction vector (see remarks).

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


public attribute LightingSpace → (get)

value : TerrainSpace

The terrain-space transformation helper object.

Returns the helper object that provides coordinate transformation methods between terrain-space, light-space and material-space.


public attribute Shadows → (get)

value : ShadowMapping

The ShadowMapping object.

The aggregated ShadowMapping object.

The ShadowMapping.CascadeRange property is updated automatically by this TerrainView object. To tweak the range, use ShadowTweak.


public attribute ShadowTweak → (get,set)

value : float64

The lower shadow cascade range value.

Tweaks the shadow cascade range by setting the lower bound (see ShadowMapping.Cascade).

Defaults to 1.


public attribute Sky → (get)

value : TerrainSky

The TerrainSky object.

Returns the TerrainSky object that represents the sky background for the terrain.


public attribute Stage → (get)

value : IRenderStage

The IRenderStage object.

The IRenderStage object that is used by this terrain view.


public attribute Terrain → (get)

value : TerrainMesh

The terrain mesh.

Returns the terrain mesh this terrain view belongs to.


public attribute TextureDetail → (get)

value : float64

The overall texturing detail, in pixel/texel.

Returns the overall detail of unique terrain texturing.


public attribute TextureProgress → (get)

value : int32

The overall texturing progress, in percent.

Returns the overall progress of unique terrain texturing.

If the terrain does not have any unique texturing layers, this property will return 100.


public attribute TriangulationBuffer → (get)

value : TriangulationBuffer

The triangulation buffer.

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.


public attribute TriangulationFlags → (get)

value : int32

Bitwise combination of the following info flags:
0x1 : the CPU is decoding the triangulation result before rendering
0x2 : the GPU is decoding the triangulation result before rendering
0x4 : the GPU is consuming the triangulation result directly

Returns information about the current triangulation mode.


public attribute Viewport → (get)

value : CameraViewport

The terrain 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.


public attribute VisibleCheck → (get)

value : ScreenVisibleCheck

The visible check.

Returns the vertex visibility check that is used for terrain mesh refinement.

Changes made to the visibility check will be forwarded to background refinement as soon as possible.



public static readonly attribute Logger → (ILogger)

The logger object of this class.