interface IMeshDynamic in Tinman.Terrain.Kernel

Base interface for dynamic continuous level-of-detail terrain meshes that perform view-dependent refinement at runtime.

interface

IMeshDynamic

extends

IMesh

Remarks

The terrain mesh version (see Version) is incremented during MeshUpdate if the mesh structure has changed since the last call.

Attributes

AllowSleep

Allow refinement to sleep for a short period of time when little refinement work is necessary?

property	AllowSleep { get set }
type	bool
value		true to allow sleeping, false to disallow it.

Remarks:

The default value is true.

AutoPause

Shall refinement be paused when it has finished?

property	AutoPause { get set }
type	bool
value		true if refinement shall be paused when it has finished, false to keep background refinement active even if an optimal mesh structure has been reached.

Remarks:

When the background refinement has been paused, the application must explicitly resume it by calling Resume (usually when the visibility criterion parameters have changed).

Geometry

The IGeometry object this terrain mesh uses.

property	Geometry { get }
type	IGeometry
value	[not-null]	The geometry object.
inherited	IMesh.Geometry

Remarks:

The geometry object is used to compute actual vertex data from the terrain data that has been gathered from the heightmap.

See also:

IMesh.Heightmap

Heightmap

The heightmap of this terrain mesh.

property	Heightmap { get }
type	IHeightmap
value	[not-null]	The heightmap.
inherited	IMesh.Heightmap

Remarks:

The heightmap delivers terrain data, such as elevation and diffuse color.

See also:

IMesh.Geometry

IsReady

Is this terrain mesh ready for traversal and triangulation?

property	IsReady { get }
type	bool
value		true if this mesh is ready, false if not.
inherited	IMesh.IsReady

Remarks:

When a mesh is not ready yet, calling GetRoot will always return Null.

LifecycleState

Returns the lifecycle state of this object.

property	LifecycleState { get }
type	LifecycleState
value		The lifecycle state.
inherited	ILifecycleState.LifecycleState

Progress

Returns the estimate progress of the refinement, in percent.

property	Progress { get }
type	int32
value	[0..100]	The refinement progress, in percent.

Remarks:

A value of 100 means that refinement has reached an optimal mesh structure, i.e. no more vertices will be added to or removed from any terrain meshes.

QualityThreshold

The quality setting for mesh refinement.

[ThreadSafe]
property	QualityThreshold { get set }
type	float64
value	[>0]	The quality threshold value.

Remarks:

The quality threshold value is passed to the IsVertexVisible method of the meshes Visibility check. Quality increases with smaller threshold values. The interpretation of this value depends on the used visibility check (e.g. screen-space pixels or terrain-space units). The default value is 2.5.

Status

Returns the current refinement status.

property	Status { get }
type	RefinementStatus
value		The current refinement status.

TaskGroup

The task group that is used by this mesh for background computations.

property	TaskGroup { get }
type	TaskGroup
value	[not-null]	The task group.
inherited	IMesh.TaskGroup

Tree

Returns the mesh quadtree object which can be used during traversals.

property	Tree { get }
type	MeshTree
value	[not-null]	The mesh structure helper object.
inherited	IMesh.Tree

Remarks:

Each mesh face (see CubemapFace) represents the root of a quadtree structure. During mesh traversal (via the IMeshTraversal), the MeshTree object provides access to the underlying quadtree structure.

TriangleThreshold

Specifies the target triangle count for mesh refinement.

[ThreadSafe]
property	TriangleThreshold { get set }
type	int32
value	[>=0]	The target triangle count.

Remarks:

When the target triangle count is greater than zero, mesh refinement automatically adjusts the internal quality threshold value, in order to reach resp. maintain the target triangle count. In this case, the configured quality threshold (see QualityThreshold) is used as the lower boundary; i.e. the internal value will always be greater than or equal to the configured value.

Defaults to 0.

Triangulator

Return the Triangulator object to use for mesh triangulation.

property	Triangulator { get }
type	Triangulator
value	[not-null]	The Triangulator instance.
inherited	IMesh.Triangulator

Version

Returns the current version of object.

property	Version { get }
type	int32
value		The current version number.
inherited	IVersioned.Version

Remarks:

For each modification, the version is incremented by at least one.

Vertices

Returns the CPU vertex data collection of this terrain mesh.

property	Vertices { get }
type	VertexArrays
value	[not-null]	The vertex data collection.
inherited	IMesh.Vertices

Remarks:

All meshes created by a single MeshBuffer share the same vertex data collection.

Visibility

The vertex visibility check that is used for mesh refinement.

[ThreadSafe]
property	Visibility { get set }
type	IVisibleCheck
value	[not-null]	The visibility check.

Remarks:

The given IVisibleCheck object will be handed over to the refinement thread in the thread-safe manner. Then the SetVertexArrays will be called one and the IsVertexVisible method will be called repeatedly by the refinement thread. The implementation of IVisibleCheck should not allow modifications (thus making instances inherently thread-safe). Otherwise, the implementation is responsible for providing proper thread synchronization.

Methods

AcquireTry

Acquires a strong reference to this disposable object.

[OwnerReturn, ThreadSafe]
method	AcquireTry ()
type	IDisposable
returns			this if a new strong reference has been acquired, null if this object is already being disposed.
inherited	IDisposable.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.

DirtyRegion

Marks the given heightmap coordinate region as dirty.

[ThreadSafe]
method	DirtyRegion (int32 x1, int32 x2, int32 y1, int32 y2, int32 z1 = 0, int32 z2 = 0)
params	x1		Minimum heightmap X-coordinate (inclusive).
	x2		Maximum heightmap X-coordinate (inclusive).
	y1		Minimum heightmap Y-coordinate (inclusive).
	y2		Maximum heightmap Y-coordinate (inclusive).
	z1		Minimum heightmap Z-coordinate (inclusive). Defaults to 0.
	z2		Maximum heightmap Z-coordinate (inclusive). Defaults to 0.

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]
method	Dispose ()
inherited	IDisposable.Dispose

Remarks:

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

Resume

Resumes background refinement.

method

Resume ()

Remarks:

This method must be called iff AutoPause has been set to true and background refinement has finished (i.e. when Status is Paused). Otherwise, refinement will not continue and the mesh structure will remain unchanged, even if the parameters of the visibility criterion are changed.

If this method is called in other cases it performs no action and silently returns.

Extensions

DirtyRegion

Marks the given heightmap coordinate region as dirty.

[ThreadSafe]
method	DirtyRegion (Box2I region)
params	region		The heightmap coordinate region.

---

Marks the given heightmap coordinate region as dirty.

[ThreadSafe]
method	DirtyRegion (Box3I region)
params	region		The heightmap coordinate region.