IHeightmapOps

Description

interface Tinman.Terrain.Heightmaps.IHeightmapOps

Extended by

IHeightmap

Defines common operations of IHeightmap objects.

The IHeightmap object that is returned by the heightmap operation methods must be used by the caller instead of the IHeightmap on which the method has been called.

Public / Methods

Border


[OwnerReturn] [OwnerThis]
public method Border → (2)

borderSample in : HeightmapSample

The border heightmap sample.

borderFalloff in : int32

[>0]
Width of the border falloff region, in heightmap samples.

returns → IHeightmap

The padded heightmap.

Pads this heightmap to the smallest fitting size of 2^n+1.

This method will add a border region at the right and bottom edges of a rectangular heightmap (see MapType.Rect). A smooth falloff is computed at the heightmap edges in order to avoid unnecessary triangles being created by CLOD mesh refinement for overly sharp corners.

Clip


[OwnerReturn] [OwnerThis]
public method Clip → (2)

mask in : IHeightmap own

[not-null]
The heightmap that is used as the clip mask (see remarks).

inverse opt : bool = false

Invert the coverage values in mask in before clipping?

returns → IHeightmap

The resulting heightmap.

Clips away portions of this heightmap, according to the HeightmapLayer.Coverage layer of the given heightmap.

The coverage values of the returned heightmap are computed like this:

inverse == false : c_out = c_in * c_mask
inverse == true  : c_out = in * (1 - c_mask)

where c_out is the normalized coverage value (i.e. in the range [0..1]) of the returned heightmap, c_in is the normalized coverage value of this heightmap and c_arg is the normalized coverage value of mask in.

Combine


[OwnerReturn] [OwnerThis]
public method Combine → (3)

detail in : IHeightmap own

[not-null]
The detail heightmap.

textureOp opt : ColorOp = ColorOp.Blend

The color operation to apply to the HeightmapLayer.Texture layer, if present.

scalarOp opt : ScalarOp = ScalarOp.Add

The scalar operation to apply to the HeightmapLayer.Elevation and HeightmapLayer.Displacement layers, if present.

returns → IHeightmap

The resulting heightmap.

Adds detail to this heightmap by combining it with the given heightmap.

The heightmap samples of this heightmap (source) are modified using the samples of the given detail heightmap (detail) according to these rules:

  • HeightmapLayer.Coverage:
    The coverage of this heightmap will remain unchanged. The coverage of the given detail heightmap will be ignored.

  • HeightmapLayer.Elevation:
    The terrain-space elevation values (see VerticalRange) of this heightmap and the given detail heightmap are combined using the given scalar operation (see scalarOp opt); then the resulting scalar value is converted back to elevation values using the combined vertical range.

  • HeightmapLayer.Texture:
    The given color operation (see textureOp opt) is applied to the texture color of this heightmap (first) and the color of the given detail heightmap ( second).

  • HeightmapLayer.Material:
    The material tokens of this heightmap are mixed with the tokens of the detail heightmap: If the weight sum (MaterialToken.WeightSum) of the detail token is greater than or equal to 255, the source token will be replaced with the detail token. Otherwise, the source token will be gradually blend into the detail token (see MaterialToken.Mix1).

  • HeightmapLayer.Displacement:
    The terrain-space displacement values (see VerticalRange) of this heightmap and the given detail heightmap are combined using the given scalar operation (see scalarOp opt); then the resulting scalar value is converted back to displacement values using the combined vertical range.

Merge


[OwnerReturn] [OwnerThis]
public method Merge → (1)

second in : IHeightmap own

[not-null]
The second heightmap.

returns → IHeightmap

The resulting heightmap.

Merges the given heightmap with this one. The coverage of both heightmaps will be taken into account during merging.

Merged heightmaps fill data into heightmap samples in order, with heightmaps at a later stage overwriting sample data written by heightmaps of an earlier stage.

Both heightmaps (this one and second in) will be scaled to the maximum possible size.

Proxy


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

returns → IHeightmapProxy

The proxy heightmap that wraps this one.

Wraps this heightmap in a proxy.

Scale


[OwnerReturn] [OwnerThis]
public method Scale → (1)

newSize in : int32

[pow2+1]
The scaled internal size (see IHeightmap.Type). The minimum internal size is HeightmapsUtil.MinSize.

returns → IHeightmap

The scaled heightmap.

Returns a scaled version of this heightmap.

The maximum up-scaling factor for heightmaps is 65536, so the given condition should be met when up-scaling a heightmap (otherwise only the 16 most significant bits of the interpolation factor will be used):

(newSize - 1) / (Size - 1) <= 65536

where newSize in is the new heightmap size and IHeightmap.Type is the current size of this heightmap.

Split


[OwnerReturn] [OwnerThis]
public method Split → (1)

layers in : HeightmapLayer

The heightmap layers to retain in the split heightmap.

returns → IHeightmap

The resulting heightmap.

Splits the layers of this heightmap.

Swizzle


[OwnerReturn] [OwnerThis]
public method Swizzle → (3)

material0 in : int32

[-1..255]
ID of the material to replace or -1 to replace the coverage layer.

material1 in : int32

[-1..255]
ID of the replacement material or -1 to use coverage layer as replacement.

bidi in : bool

true to establish a bi-directional mapping between material0 in and material1 in (which effectively swaps the materials),
false to establish a uni-directional mapping from material0 in to material1 in (which effectively merges the first material into the second).

returns → IHeightmap

The resulting heightmap.

Swizzles materials.

When the coverage layer is involved in the substitution, material weights are mapped to inverse coverage values.

Material substitution always has a fixed cost at runtime, no matter how many times this method has been used.

To​Pyramid


[OwnerReturn] [OwnerThis]
public method ToPyramid → (7)

tileSize opt : int32 = 256

[pow2]
The tile size.

tilePad opt : int32 = 0

[>=0]
The tile padding.

levels opt : int32 = 0

[>=0]
Defines how many pyramid levels (starting at the bottommost level) shall contain data. The heightmap sample step is 1 for the bottommost level and is multiplied by two for each parent level. If 0, all pyramid levels will contain data.

pixelLayer opt : IPixelLayer = null

Optional pixel layer to use.

flags opt : PyramidFlags = PyramidFlags.None

Optional pyramid flags.

geometry opt : IGeometry = null

Optional geometry to use for computing normal vectors in terrain-space (instead of tangent-space). Terrain-space normal vectors properly capture terrain features that result from displacement, for example overhangs. The IGeometry.ToSize method will be used to change the map size to the correct value, if necessary.

modifier opt : IMeshModifier = null

Optional mesh modifier to use, in addition to geometry opt.

returns → IPixelPyramid

The pixel pyramid.

Wraps this heightmap in a pixel pyramid.

The returned pixel pyramid will have uniform level of detail, so it is not necessary to user the PyramidFlags.Opaque flag.

Transform​Range


[OwnerReturn] [OwnerThis]
public method TransformRange → (3)

range in : VerticalRange

The range to translate to (see IHeightmap.Vertical).

unit opt : UnitOfMeasure = null

The vertical unit of range in. If null, UnitOfMeasure.Metre will be used.

reinterpret opt : bool = false

Keep elevation values of this heightmap and reinterpret them according to range in and unit opt, instead of scaling them?

returns → IHeightmap

The resulting heightmap.

Translates the normalized elevation values of this heightmap to the given range.

Use​Color​Ramp


[OwnerReturn] [OwnerThis]
public method UseColorRamp → (1)

colorRamp in : IColorRamp

[not-null]
The color ramp to use.

returns → IHeightmap

The resulting heightmap.

Return a heightmap that computes texture colors using an elevation-based color ramp.

The terrain-space values of the HeightmapLayer.Elevation layer (according to the vertical range and unit of the heightmap) are fed into the color ramp. The resulting diffuse color is used as the HeightmapLayer.Texture layer.