MeshChunkBuilder

Description

sealed class Tinman.Terrain.Kernel.MeshChunkBuilder

Derived from

Disposable abstract
IValidatable
IErrorScale

The MeshChunkBuilder class can be used to build static terrain mesh chunks for individual sectors.

The normal error metric is never applied by the MeshChunkBuilder class, so the Vec4F.Y component of IErrorScale.ErrorScale is ignored.

The MeshChunkBuilder class does not compute per-vertex ambient occlusion terms. Those can be computed as a separate texture (see TextureOcclusion).

The MeshChunkBuilder class does not apply per-vertex displacement values (see HeightmapLayer.Displacement). This feature will be added in a future version.

Public / Constants

TextureAlbedo


public constant TextureAlbedo → ("Albedo":string)

Pre-defined texture name for albedo color (compressed sRGB); can be computed with PixelLayer.Texture, for example.

If a texture layer of this name is present, the texture error metric will be disabled (i.e. IErrorScale.ErrorScale will be treated as if Vec4F.Z was zero).

TextureEmissive


public constant TextureEmissive → ("Emissive":string)

Pre-defined texture name for emissive color (linear sRGB).

TextureGloss


public constant TextureGloss → ("Gloss":string)

Pre-defined texture name for emissive light (linear sRGB).

Gloss is defined as microsurface smoothness: a value of 1 means that the surface is smooth (reflections will appear bright and crisp), a value of 0 means that the surface is rough (reflections will appear dim and blurry).

TextureNormal


public constant TextureNormal → ("Normal":string)

Pre-defined texture name for normal vectors (linear sRGB); can be computed with PixelLayer.Normals, for example.

If this layer is present, the terrain-space normal vectors will point upwards (see IGeometry.ComputeUp) and the tangent vectors will point into the direction of their respective texture axis, lying on the surface of the base terrain (i.e. the surface that results from using zero elevation anywhere).

The red, green and blue channels define the tangent-space normal vector (not necessarily of unit length). The alpha channel is ignored.

The relative pixel intensities (red, green, blue) in the range [0..1] are mapped to the unit cube:

red  :[0..1] => X:[-1 .. +1]
green:[0..1] => Y:[-1 .. +1]
blue :[0..1] => Z:[-1 .. +1]

where X+ is the tangent direction (positive texture U-axis), Y+ is the bitangent direction (positive texture V-axis) and Z+ is direction of the surface normal vector.

TextureOcclusion


public constant TextureOcclusion → ("Occlusion":string)

Pre-defined texture name for ambient occlusion (linear); can be computed with PixelLayer.Occlusion.

When generating terrain tiles, the occlusion textures should be seamless. This can be accomplished by choosing appropriate parameter values when calling PixelLayer.Occlusion.

TextureReflectivity


public constant TextureReflectivity → ("Reflectivity":string)

Pre-defined texture name for reflectivity color (linear sRGB).

Public / Constructors

MeshChunkBuilder


public constructor MeshChunkBuilder → (3)

heightmap in : IHeightmap

[not-null]
The heightmap to use.

geometry opt : IGeometry = null

The geometry to use. If null, a default one will be created via Geometry.ForGeoref, based on the geo-reference of heightmap in (see IGeorefInfo.Georef).

initialCapacity opt : int32 = 0

[>=0]
The initial vertex capacity to use. This value can be set to avoid that buffers grow unnecessarily; it is not related to VertexCount. Defaults to 0.

Creates a new instance of MeshChunkBuilder.

Public / Methods

Build


[OwnerReturn]
public method Build → ()

returns → MeshChunk

The built mesh chunk or null iff Region specified a cubemap face that is not present in the source heightmap.

Builds a mesh chunk, using the current properties.

One MeshChunkBuilder object may be used to build multiple MeshChunk objects.

GeorefException

If no IGeometry has been specified and the input IHeightmap does not provide sufficient geo-referencing information.

ValidatingException

If the mesh chunk cannot be built because the input parameters are invalid.

IOException

If an I/O error has occurred.

BuildAndDispose


[OwnerReturn] [OwnerThis]
public method BuildAndDispose → ()

returns → MeshChunk

The built mesh chunk.

Builds a mesh chunk, using the current properties.

One MeshChunkBuilder object may be used to build multiple MeshChunk objects.

GeorefException

If no IGeometry has been specified and the input IHeightmap does not provide sufficient geo-referencing information.

ValidatingException

If the mesh chunk cannot be built because the input parameters are invalid.

IOException

If an I/O error has occurred.

Texture

2 overloads


[OwnerReturn]
public method Texture1 → (1)

name in : string

[not-empty]
The layer name.

returns → TexelBuffer

The layer texture.

Returns a layer texture, building it if necessary.

This method may be called at any time, for example before calling Build.

A layer texture will be computed at most once, unless the layer texture specification is updated (see Texture2).

The textures returned from this method will also be accessible in MeshChunk.Textures.


public method Texture2 → (4)

name in : string

[not-empty]
The texture layer name.

srgb in : bool

The sRGB processing flag (see ISrgb.Srgb).

texture in : IPixelPyramid

The texture layer image content to use or null to remove the layer.

format opt : TextureFormat = null

The texture format to use. If null, TextureFormat.BC1 will be used.

Specifies a texture layer.

The specified texture layers will be accessible from the built mesh chunk via MeshChunk.Textures.

Public / Attributes

IndexCount


public attribute IndexCount → (get,set)

value : int32

[>0]
The maximum number of mesh indices.

Specifies the maximum number of mesh indices.

This value depicts the maximum index count that will result when triangulating the mesh chunk sector (see MeshChunk.Sector and IMesh.Triangulator) using the following settings:

This value depicts the maximum number of indices in the built MeshChunk for the mesh sector that corresponds to the chosen mesh region (see MeshChunk.Sector and Region). Please note that the index count of the whole MeshChunk may be slightly higher, because some indices are used for the outer mesh, in order to provide a full CLOD mesh (according to IMesh).

The average ratio between the index count and vertex count is 3.2.

The default value is 209715.

MeshModifier


public attribute MeshModifier → (get,set)

value : IMeshModifier

The mesh modifier to use or null to use the original terrain mesh.

The mesh modifier to use to deform the original terrain mesh.

Defaults to null.

Region


public attribute Region → (get,set)

value : PyramidCoords

The desired pyramid tile coordinates that represent the region of the mesh chunk. If necessary, the given value in will be adjusted, to reflect the internal size of the used heightmap (see IHeightmap.Size and IMesh.Heightmap) and the minimum chunk size (see HeightmapsUtil.MinSize).

The region for the mesh chunk.

The default value encompasses the whole CubemapFace.NegZ face.

VertexCount


public attribute VertexCount → (get,set)

value : int32

[512..536870912]
The maximum number of mesh vertices.

Specifies the maximum number of mesh vertices.

This value depicts the maximum number of vertices in the built MeshChunk for the mesh sector that corresponds to the chosen mesh region (see MeshChunk.Sector and Region). Please note that the vertex count of the whole MeshChunk may be slightly higher, because some vertices are used for the outer mesh, in order to provide a full CLOD mesh (according to IMesh).

The ratio between the vertex and index counts should be around 1.7.

The default value is 65536.