MeshBuffer

Description

sealed class Tinman.Terrain.Kernel.MeshBuffer

Derived from: Disposable ^abstract
ICapacity
IMemoryConsumption
IBeginEnd

Provides the shared buffer for terrain meshes.

Using a mesh buffer involves the following steps:

Create a MeshBuffer object by calling Create. A container for per-vertex CPU data must be given (see VertexArrays). Optionally, updater objects for vertex data or mesh structure data may be specified; these are usually used to populate GPU buffers, for GPU-based rendering and triangulation.
Create terrain meshes by calling MeshCreate. All terrain meshes will use vertices that are stored in the shared mesh buffer.
The mesh buffer has a background refinement thread which periodically traverses all terrain meshes, updates the tessellation and triggers background computation of vertex data. This happens automatically and is not visible to the application.
The mesh buffer is supposed to be accessed by a single dedicated thread in the application (usually the render thread). A separate snapshot of the terrain mesh tessellation is maintained for consistent access by the application thread.
The MeshUpdate and MeshUpdateData will update the terrain snapshot according to the current state of background refinement. This is a write-only access. Subsequently, the application will read from the terrain snapshot (for example, while traversing the MeshTree).
If an application needs to read from the terrain snapshot from another thread than the dedicated one, then the IBeginEnd.Begin and IBeginEnd.End methods must be used to wrap each read access. This will ensure that all accesses are properly synchronized: write-accesses and read-accesses are mutually exclusive, while read-accesses will be performed in parallel.

The following API will read from the terrain snapshot:

Public / Constructors

Create

[OwnerReturn]
public static method Create → (3)

vertexData ⁱⁿ : VertexArrays: [not-null]
The CPU vertex data collection.
vertexUpdater ^opt : IVertexUpdater = null: The vertex data updater.
meshStructureUpdater ^opt : IMeshStructureUpdater = null: The mesh structure updater.
returns → MeshBuffer: The mesh buffer object.

Creates a new instance of MeshBuffer.

If necessary, the following vertex data arrays will be created:

TinmanException: If vertexUpdater ^opt is not null and vertexData ⁱⁿ is missing some required data arrays.

Public / Methods

BuildFragmentationImage

[ThreadSafe]
public method BuildFragmentationImage → ()

returns → ColorBuffer: The color coded fragmentation image.

Builds a color-coded image that represents the fragmentation of the shared vertex buffer.

Both width and height of the image are powers of two (but not necessarily the same). Each pixel in the image represent the status of a specific vertex in the shared vertex buffer:

index(x,y)  := y * width + x
color(x,y)  := status

where width and height are the dimensions of the image, x and y are pixel coordinates, index is the mapping from pixel coordinates to zero-based vertex indices and status if the color-coded vertex status:

Black
The vertex is not used by any terrain mesh.
Dark rainbow color
The vertex is used by a terrain mesh and currently invisible.
Bright rainbow color
The vertex is used by a terrain mesh and currently visible.
White
The vertex belongs to the skeleton of a terrain mesh.

The hue of the rainbow colors indicates the level of the respective vertex in the mesh structure (i.e, the number of parent vertices, up to the root sector; see XDag).

MeshCreate

[OwnerReturn] [ThreadSafe]
public method MeshCreate → (1)

options ⁱⁿ : MeshOptions: [not-null]
The mesh options.
returns → IMeshDynamic: The created CLOD mesh.

Creates a new dynamic terrain mesh.

ValidatingException: If the given options ⁱⁿ are invalid.

GeorefException: If MeshOptions.Geometry is null and the given geo-reference is not suitable.

MeshUpdate

public method MeshUpdate → (1)

wait ^opt : bool = false: true to wait for other application threads that use IBeginEnd.Begin and IBeginEnd.End to read from the current terrain snapshot, before applying the buffered mesh updates,
false to skip buffered mesh updates and return 0 when other threads are still reading from the terrain snapshot.
returns → int32: > 0 : if the vertex/index data has changed
= 0 : if no vertex/index data has changed
< 0 : if the mesh buffer has encountered an unexpected error. Mesh refinement will have been stopped in this case. To recover, call Reinitialize.

Applies all buffered mesh updates, but does not update vertex data via IVertexUpdater or mesh data via IMeshStructureUpdater.

The MeshUpdateData method must be called before vertex data is used (e.g. rendering using the GPU vertex buffer). This ensures that the mesh structure is consistent with the vertex data that has been sent to the IVertexUpdater object.

The call to MeshUpdateData may be omitted iff the vertex data is not used. Calling the MeshUpdateData more than once is allowed, but has no effect.

MeshUpdateData

public method MeshUpdateData → (2)

vertexData ^opt : bool = true: Update vertex data?
meshData ^opt : bool = true: Update mesh data?
returns → int64: The amount of data that has been updated, in bytes.

Performs all vertex data and mesh structure updates that have been left out during the last call to MeshUpdate.

This method can be called multiple times, data updates will only be performed once.

Reinitialize

[ThreadSafe]
public method Reinitialize → ()

Re-initializes the mesh buffer and all meshes.

This method can be called after MeshUpdate has returned a negative value, in order to recover from an error that has occurred earlier.

Public / Attributes

AllowSleep

public attribute AllowSleep → (get,set)

value : bool: true to allow sleeping, false to disallow it.

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

The default value is true.

CountUnused

public attribute CountUnused → (get)

value : int32: [>=0]
The number of unused mesh buffer vertices.

Returns the number of vertices that are not used by any mesh, neither as visible nor invisible vertex.

See also: MeshBuffer.MeshUpdate

CountVisible

public attribute CountVisible → (get)

value : int32: [>=0]
The number of visible mesh vertices.

Returns the number of visible vertices in all meshes.

See also: IMeshDynamic.VisibleCount
MeshBuffer.MeshUpdate

MeshStructureUpdater

[Constant]
public attribute MeshStructureUpdater → (get)

value : IMeshStructureUpdater: The mesh structure updater or null.

Returns the mesh structure updater of this mesh buffer.

VertexArrays

[Constant]
public attribute VertexArrays → (get)

value : VertexArrays: [not-null]
The vertex data collection.

Returns the CPU vertex data collection of this mesh buffer.

VertexUpdater

[Constant]
public attribute VertexUpdater → (get)

value : IVertexUpdater: The vertex updater or null.

Returns the vertex updater of this mesh buffer.