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 ⁱⁿ : HeightmapSample: The border heightmap sample.
borderFalloff ⁱⁿ : 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 ⁱⁿ : 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 ⁱⁿ 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 ⁱⁿ.

Combine

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

detail ⁱⁿ : 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.Mix¹).
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 ⁱⁿ : 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 ⁱⁿ) 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.

See also: HeightmapBuilder.Proxy

Scale

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

newSize ⁱⁿ : 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 ⁱⁿ is the new heightmap size and IHeightmap.Type is the current size of this heightmap.

Split

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

layers ⁱⁿ : 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 ⁱⁿ : int32: [-1..255]
ID of the material to replace or -1 to replace the coverage layer.
material1 ⁱⁿ : int32: [-1..255]
ID of the replacement material or -1 to use coverage layer as replacement.
bidi ⁱⁿ : bool: true to establish a bi-directional mapping between material0 ⁱⁿ and material1 ⁱⁿ (which effectively swaps the materials),
false to establish a uni-directional mapping from material0 ⁱⁿ to material1 ⁱⁿ (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.

ToPyramid

[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.

TransformRange

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

range ⁱⁿ : VerticalRange: The range to translate to (see IHeightmap.Vertical). Set to VerticalRange.None in order to keep the current vertical range.
unit ^opt : UnitOfMeasure = null: The vertical unit of range ⁱⁿ. If null, UnitOfMeasure.Metre will be used.
reinterpret ^opt : bool = false: Keep elevation values of this heightmap and reinterpret them according to range ⁱⁿ and unit ^opt, instead of scaling them?
returns → IHeightmap: The resulting heightmap.

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

UseColorRamp

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

colorRamp ⁱⁿ : 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.