class TerrainMesh in Tinman.AddOns.Components

Represents a terrain mesh.

sealed class

TerrainMesh

extends

Disposable

Remarks

The TerrainMesh class provides a high-level API that wraps the terrain features of the Tinman 3D SDK in an easy to use way:

• Setup and configuration of the object graph that is necessary for terrain rendering.
• Terrain layers for flexible management of rendering style and data sources.
• Georeferenced terrain decals.
• Georeferenced terrain 3D models.
• Global dynamic planting of 3D models onto the terrain surface, using GPU instancing for rendering.

The layers of a terrain mesh are ordered by their sort index value (see SortIndex). Layers use alpha-blending, so layers with higher sort index values will occlude others. The implicit layer at sort index -0.5 is used to render the terrain materials with additive blending:

 |  ...  |
 +-------+
 | Layer |   SortIndex =   -2
 +-------+
 | Layer |   SortIndex =   -1
 +-------+
(Materials)  SortIndex = -0.5 (implicit layer for materials)
 +-------+
 | Layer |   SortIndex =    0
 +-------+
 | Layer |   SortIndex =   +1
 +-------+
 |  ...  |

The surface materials textures (see Material), defined by MaterialAdd.

Public / Attributes

Distance

Returns the DistanceToGround helper object for this terrain mesh.

public property	Distance { get }
type	DistanceToGround
value	[not-null]	The helper object.

Geocentric

The Geocentric helper object of the terrain mesh.

public property	Geocentric { get }
type	Geocentric
value		The Geocentric object or null if the terrain mesh does not have a geocentric reference.

Remarks:

The returned object is obtained from ToGeocentric and then augmented with the following data, if possible:

• Gravity-related height offsets (see Gravity):
  Using the IHeightmap object that has been specified in constructor call.
• Elevation model (see Ellipsoid):
  Derived from Heightmap, by extracting Elevation via Split.

Gravity

Optional heightmap that stores gravity-related offsets from the ellipsoid surface (see Gravity)

public property	Gravity { get }
type	IHeightmap
value		The gravity-related heightmap or null.

HasMaterials

Does this layer have terrain materials?

public property	HasMaterials { get }
type	bool
value		true if this layer has terrain materials, false if not.

See also:

TerrainLayerFlags.ShowTexture

Height

Returns the HeightAboveGround helper object for this terrain mesh.

public property	Height { get }
type	HeightAboveGround
value	[not-null]	The helper object.

LayerCount

Returns the number of terrain layers (excluding the implicit material layer).

public property	LayerCount { get }
type	int32
value	[>=0]	The terrain layer count.

LifecycleState

Returns the lifecycle state of this object.

public virtual property	LifecycleState { get }
type	LifecycleState
value		The lifecycle state.
inherited	Disposable.LifecycleState

MaterialChunks

The material chunking coefficient.

public property	MaterialChunks { get set }
type	float64
value		The chunking coefficient.

Remarks:

The material chunking coefficient must be divisible by all material scale factors (i.e. global factor MaterialScale multiplied with texture factor Scale).

The default value is 1.

MaterialFlags

Flags of the implicit terrain material layer.

public property	MaterialFlags { get set }
type	TerrainLayerFlags
value		The terrain material layer flags.

Remarks:

Only the following flags are used by the implicit material layer (all others are ignored):

• HintOpaque
• NoLighting
• ShowChunks
• ShowTexture

MaterialRange

The distance range in which the implicit terrain material layer is visible.

public property	MaterialRange { get set }
type	Vec2F
value		The layer distance range.

Remarks:

The terrain layer is fully faded in when the camera distance is equal to X and fully faded out when the distance is equal to Y.

If X is equal to Y, the distance range is disabled and the terrain layer is visible everywhere.

Defaults to Zero.

MaterialScale

The global material texture scale, in terrain-space.

public property	MaterialScale { get set }
type	float32
value		The global material texture scale, in terrain-space.

Remarks:

The scale of each terrain texture (see Scale) is multiplied with this value before being used for rendering.

Defaults to 1 (i.e. a material texture covers an area of 1x1 terrain-space units).

Mesh

The CLOD mesh of this terrain.

public property	Mesh { get }
type	IMeshDynamic
value	[not-null]	The IMesh object.

ModelCount

Returns the number of terrain 3D models.

public property	ModelCount { get }
type	int32
value	[>=0]	The number of terrain 3D models.

See also:

ModelAdd
ModelRemove

Picking

Returns the Picking helper object for this terrain mesh.

public property	Picking { get }
type	Picking
value	[not-null]	The helper object.

PlantingCount

public property	PlantingCount { get }
type	int32
value

TerrainBuffer

Returns the TerrainBuffer object that this terrain mesh is using.

public property	TerrainBuffer { get }
type	TerrainBuffer
value	[not-null]	The terrain buffer object.

World

Returns the ICameraWorld helper object for this terrain mesh.

public property	World { get }
type	MeshCameraWorld
value	[not-null]	The helper object.

Public / Constructors

TerrainMesh

Creates a new instance of TerrainMesh.

public constructor	TerrainMesh (TerrainBuffer buffer, [Owner] MeshOptions options, IHeightmap gravity = null)
params	buffer	[not-null]	The terrain buffer to use.
	options	[not-null]	The terrain mesh options. The Visibility option will be ignored. Instead, a separate instance of ScreenVisibleCheck will be used for each TerrainView.
	gravity		Optional heightmap that stores gravity-related offsets from the ellipsoid surface (see Gravity). Defaults to null.

Remarks:

Elevation values of the given mesh heightmap (see Heightmap) are interpreted as relative offsets to the ellipsoid surface.

Public / Methods

AcquireTry

Acquires a strong reference to this disposable object.

[OwnerReturn, ThreadSafe]
public method	AcquireTry ()
type	IDisposable
returns			this if a new strong reference has been acquired, null if this object is already being disposed.
inherited	Disposable.AcquireTry

Remarks:

The object will not be actually disposed by calls to Dispose when there is at least one strong reference left. Code that calls the AcquireTry method is responsible for calling the Dispose method accordingly.

This method is not intended to be used in performance-critical code. It should only be used to high-level resource management.

DecalAdd

Adds the given terrain decal.

public method	DecalAdd (TerrainDecal decal)
params	decal	[not-null]	The terrain decal to add.

DecalRemove

Removes the given terrain decal.

public method	DecalRemove (TerrainDecal decal)
params	decal	[not-null]	The terrain decal to remove.

Dispose

Releases all resources held by this object if there are no more strong references to it, decrements the reference counter by one otherwise.

[Dispose, OwnerThis, ThreadSafe]
public method	Dispose ()
inherited	Disposable.Dispose

Remarks:

The Dispose method silently returns if the object has already been disposed.

LayerAt

public method	LayerAt (int32 sortIndex)
type	TerrainLayer
params	sortIndex

LayerCreate

Creates a new instance of TerrainLayer for this terrain.

public method	LayerCreate (int32 sortIndex = 0, TerrainLayerFlags flags = TerrainLayerFlags.None)
type	TerrainLayer
params	sortIndex		Initial value for SortIndex. Defaults to 0.
	flags		Initial value for Flags. Defaults to None.
returns		[not-null]	The created terrain layer.

LayerGet

Returns an existing terrain layer.

public method	LayerGet (int32 index)
type	TerrainLayer
params	index	[0..LayerCount-1]	The layer index.
returns		[not-null]	The terrain layer.

LayerRemove

Removes an existing terrain layer.

public method	LayerRemove (TerrainLayer layer)
params	layer	[not-null]	The terrain layer to remove.

MaterialAdd

Adds the given material to this layer, replacing any existing one.

public method	MaterialAdd (TerrainMaterial material)
params	material	[not-null]	The material to add.

See also:

TerrainLayerFlags.ShowTexture

MaterialAddAll

Adds the given materials to this layer, replacing any existing ones.

public method	MaterialAddAll (IEnumerable<TerrainMaterial> materials)
params	materials	[not-null]	The materials to add.

See also:

TerrainLayerFlags.ShowTexture

MaterialClear

Removes all materials from this layer.

public method

MaterialClear ()

See also:

TerrainLayerFlags.ShowTexture

MaterialGet

Returns a terrain material.

public method	MaterialGet (int32 materialId)
type	TerrainMaterial
params	materialId	[0..255]	The material ID (see MaterialToken).
returns			The TerrainMaterial object or null if no terrain material has been defined.

See also:

TerrainLayerFlags.ShowTexture

MaterialRemove

Removes the given material from this layer.

public method	MaterialRemove (TerrainMaterial material)
params	material	[not-null]	The material to remove.

See also:

TerrainLayerFlags.ShowTexture

ModelAdd

Adds a terrain 3D model.

public method	ModelAdd (TerrainModel model)
params	model	[not-null]	The model to add.

ModelGet

Returns the index-th terrain model.

public method	ModelGet (int32 index)
type	TerrainModel
params	index	[0..ModelCount-1]	The terrain model index.
returns		[not-null]	The terrain model.

ModelRemove

Removes a terrain 3D model.

public method	ModelRemove (TerrainModel model)
params	model	[not-null]	The model to remove.

PlantingAdd

Adds the given terrain planting options.

public method	PlantingAdd (TerrainPlanting planting)
params	planting	[not-null]	The terrain planting options to add.

PlantingGet

Returns the index-th terrain planting options.

public method	PlantingGet (int32 index)
type	TerrainPlanting
params	index	[0..PlantingCount-1]	The terrain planting options index.
returns		[not-null]	The terrain planting options.

PlantingRemove

Removes the given terrain planting options.

public method	PlantingRemove (TerrainPlanting planting)
params	planting	[not-null]	The terrain planting options to remove.