TerrainView

Description

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

Profile​Gpu​Rate​Terrain​Triangulate


public static readonly attribute ProfileGpuRateTerrainTriangulate → (ProfilerValue)

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

Profile​Pipeline​Draw


public static readonly attribute ProfilePipelineDraw → (ProfilerValue)

Profile​Pipeline​Models


public static readonly attribute ProfilePipelineModels → (ProfilerValue)

Profile​Pipeline​Primitives


public static readonly attribute ProfilePipelinePrimitives → (ProfilerValue)

Profile​Pipeline​State​Geometry


public static readonly attribute ProfilePipelineStateGeometry → (ProfilerValue)

Profile​Pipeline​State​Material


public static readonly attribute ProfilePipelineStateMaterial → (ProfilerValue)

Profile​Pipeline​State​Pass


public static readonly attribute ProfilePipelineStatePass → (ProfilerValue)

Profile​Prepare​Terrain​Mesh


public static readonly attribute ProfilePrepareTerrainMesh → (ProfilerValue)

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

Profile​Prepare​Terrain​Shadow


public static readonly attribute ProfilePrepareTerrainShadow → (ProfilerValue)

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

Profile​Prepare​Terrain​Triangulate


public static readonly attribute ProfilePrepareTerrainTriangulate → (ProfilerValue)

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

Profile​Render​Terrain​Data


public static readonly attribute ProfileRenderTerrainData → (ProfilerValue)

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

Profile​Render​Terrain​Mesh


public static readonly attribute ProfileRenderTerrainMesh → (ProfilerValue)

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

Profile​Render​Terrain​Models


public static readonly attribute ProfileRenderTerrainModels → (ProfilerValue)

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

Profile​Render​Terrain​Prepare


public static readonly attribute ProfileRenderTerrainPrepare → (ProfilerValue)

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

Profile​Render​Terrain​Shadow


public static readonly attribute ProfileRenderTerrainShadow → (ProfilerValue)

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

Profile​Terrain


public static readonly attribute ProfileTerrain → (ProfilerValue)

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

Profile​Terrain​Bandwidth


public static readonly attribute ProfileTerrainBandwidth → (ProfilerValue)

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

Profile​Terrain​Cache​Resource


public static readonly attribute ProfileTerrainCacheResource → (ProfilerValue)

Resource cache utilization (percent).

Profile​Terrain​Cache​Texture


public static readonly attribute ProfileTerrainCacheTexture → (ProfilerValue)

Texture tile utilization of the texture atlas (percent).

Profile​Terrain​Cache​Vertices


public static readonly attribute ProfileTerrainCacheVertices → (ProfilerValue)

Visible vertices in the terrain mesh buffer (percent).

Profile​Terrain​Locality


public static readonly attribute ProfileTerrainLocality → (ProfilerValue)

Estimated cache locality of current terrain.

Profile​Update​Terrain​Data


public static readonly attribute ProfileUpdateTerrainData → (ProfilerValue)

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

Public / Constructors

Terrain​View


public constructor TerrainView → (2)

terrain in : TerrainMesh

[not-null]
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

Clear​Cache


public method ClearCache → ()

Clears the terrain view caches.

Flag

2 overloads


[Pure]
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.

Profile​Pipeline​Produce


public static method ProfilePipelineProduce → (2)

profiler in : IProfiler

The profiler to use.

statistics in : ModelRendererStats

The input values to use.

Produces profiler variable values.

Reset​Camera


public method ResetCamera → ()

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

Public / Attributes

Bounds


public attribute Bounds → (get,set)

value : Box2I

The screen bounds.

The screen bounds of this terrain view.

See also

Graphics.Bounds

Chunk​Size


public attribute ChunkSize → (get,set)

value : int32

[>=0]
The chunk size, see IMeshBoundMinSize.

The overall mesh traversal chunk size.

Defaults to 256

Culling​Cone


public attribute CullingCone → (get,set)

value : float64

The cone culling angle.

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

Culling​Distance


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.

Displacement​Scale


public attribute DisplacementScale → (get,set)

value : float32

[>=0]
The uniform scale factor.

Uniform scale factor for GPU terrain displacement.

Displacement​Threshold


public attribute DisplacementThreshold → (get,set)

value : float32

[>0]
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.

Flags


public attribute Flags → (get,set)

value : TerrainViewFlags

The behaviour flags.

The behaviour flags of this terrain view.

Defaults to FlagsDefault.

Fog​Distance


public attribute FogDistance → (get,set)

value : float64

[>=0]
The fog distance, in terrain-space.

The fog distance.

Set to 0 to compute a nice fog distance automatically.

Defaults to 0.

Is​Texturing​Busy


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.

Lighting​Matrix


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:

Lighting​North


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

Lighting​Space


public attribute LightingSpace → (get)

value : TerrainSpace

[not-null]
The terrain-space transformation helper object.

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

Shadows


public attribute Shadows → (get)

value : ShadowMapping

[not-null]
The ShadowMapping object.

The aggregated ShadowMapping object.

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

Shadow​Tweak


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).

Sky


public attribute Sky → (get)

value : TerrainSky

[not-null]
The TerrainSky object.

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

Stage


public attribute Stage → (get)

value : IRenderStage

[not-null]
The IRenderStage object.

The IRenderStage object that is used by this terrain view.

Terrain


public attribute Terrain → (get)

value : TerrainMesh

[not-null]
The terrain mesh.

Returns the terrain mesh this terrain view belongs to.

Texture​Detail


public attribute TextureDetail → (get)

value : float64

The overall texturing detail, in pixel/texel.

Returns the overall detail of unique terrain texturing.

Texture​Progress


public attribute TextureProgress → (get)

value : int32

[0..100]
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.

Triangulation​Buffer


public attribute TriangulationBuffer → (get)

value : TriangulationBuffer

[not-null]
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.

Triangulation​Flags


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.

Viewport


[Constant]
public attribute Viewport → (get)

value : CameraViewport

[not-null]
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.

Visible​Check


public attribute VisibleCheck → (get)

value : ScreenVisibleCheck

[not-null]
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.

Logging

Logger


public static readonly attribute Logger → (ILogger)

The logger object of this class.