TINMAN 3D / REALTIME TERRAIN
Software Development Kit - User Manual

interface IHeightmapFormat in Tinman.Terrain.Heightmaps.Formats

Base interface for classes that convert heightmap samples to byte sequences and vice-versa.

interface IHeightmapFormat extends IConfigurable
  IEquatable<IHeightmapFormat>
  IHeightmapLayers
  ISerializable
  base of HeightmapFormat

Attributes

ByteCount

The number of dataset channels.

property ByteCount { get }
type int32
value [>0] The number of channels.

HasAlpha

Does this heightmap format store the alpha channel of the Texture layer?

property HasAlpha { get }
type bool
value true if this heightmap format stores alpha values, false if not.

LayerMask

The mask of heightmap layers this object uses.

property LayerMask { get }
type HeightmapLayer
value Bitwise combination of HeightmapLayer values.
inherited IHeightmapLayers.LayerMask

Remarks:

These heightmap layers store actual terrain data:

Missing data is represented with the Coverage layer. It describes how much information is present in a stored heightmap sample. The semantics of coverage with heightmap samples is the same as premultiplied alpha with texture samples. A LayerMask without Coverage means that all samples are fully solid. If a LayerMask contains the Coverage layer but no others, the coverage values are used to represent 'holes' in the terrain (e.g. creating holes for caves, tunnels, etc.).

SerialType

Returns the serial type of this object.

property SerialType { get }
type ISerialTypeInfo
value [not-null] The serial type.
inherited ISerializable.SerialType

SerialVersion

Returns the serial data version.

property SerialVersion { get }
type int32
value [>=1] The serial data version tag.
inherited ISerializable.SerialVersion

Remarks:

An ISerializable implementation is required to support all versions up to the one returned by SerialVersion.

See also:

ISerializable.Serialize
ISerializable.Deserialize

Methods

Collect

Converts this heightmap format to a list of atomic IHeightmapFormat components (i.e. format components that provide a single heightmap layer).

method Collect (ICollector<IHeightmapFormat> components)
params components [not-null] The output component list.

DatasetToHeightmap

Converts the given bytes into heightmap samples.

method DatasetToHeightmap (ByteBuffer buffer, HeightmapRegion region, VerticalRange range)
params buffer [not-null] The input buffer.
  region [not-null] The output heightmap region.
  range The vertical range.

Remarks:

This method will read a chunked array of bytes from the given buffer:

Source (chunked array, multiple samples per byte):

+---+---+---+---+---+---+---+---+---+---+---+---+---+
| 0 | 1 |...| 2 | 3 | 4 |...| 5 |...| 6 | 7 |...| 8 |
+---+---+---+---+---+---+---+---+---+---+---+---+---+
 \_____________/ \_____________/     \_____________/
  Samples 0-N     Sample 0-N          Samples 0-N
  Byte 0          Byte 1              Byte M

Target (interleaved array, multiple bytes per sample):

+---+---+---+---+---+---+---+---+---+---+---+---+---+
| 0 | 3 |...| 6 | 1 | 4 |...| 7 |...| 2 | 5 |...| 8 |
+---+---+---+---+---+---+---+---+---+---+---+---+---+
 \_____________/ \_____________/     \_____________/
  Sample 0        Sample 1            Sample N
  Bytes 0-M       Bytes 0-M           Bytes 0-M
Running through the samples of the given heightmap region in packed row-major order for each value byte will yield the source array. The elements of the target array will be written to the given buffer.

Deserialize

Initializes the state of this object from the given data stream.

method Deserialize (int32 serialVersion, ISerializer data)
type ISerializable
params serialVersion [>=1] The serial data version.
  data [not-null] The serial data stream.
returns [not-null] The deserialized object. This will typically be this, but in some circumstances, another instance may be returned (e.g. singletons).
inherited ISerializable.Deserialize

Remarks:

The Deserialize method will be called immediately after the object has been instantiated via its default constructor.

The provided serialVersion number is guaranteed to be equal to or less than the SerialVersion returned by this object (i.e. ISerializable object must provide backwards compatibility).

See also:

ISerializable.Serialize
ISerializable.SerialVersion

HeightmapToDataset

Converts the given heightmap samples into bytes.

method HeightmapToDataset (HeightmapRegion region, ByteBuffer buffer, VerticalRange range)
params region [not-null] The input heightmap region.
  buffer [not-null] The output buffer.
  range The vertical range.

Remarks:

This method will write a chunked array of bytes to the given buffer:

Source (interleaved array, multiple bytes per sample):

+---+---+---+---+---+---+---+---+---+---+---+---+---+
| 0 | 1 |...| 2 | 3 | 4 |...| 5 |...| 6 | 7 |...| 8 |
+---+---+---+---+---+---+---+---+---+---+---+---+---+
 \_____________/ \_____________/     \_____________/
  Sample 0        Sample 1            Sample N
  Bytes 0-M       Bytes 0-M           Bytes 0-M

Target (chunked array, multiple samples per channel):

+---+---+---+---+---+---+---+---+---+---+---+---+---+
| 0 | 3 |...| 6 | 1 | 4 |...| 7 |...| 2 | 5 |...| 8 |
+---+---+---+---+---+---+---+---+---+---+---+---+---+
 \_____________/ \_____________/     \_____________/
  Samples 0-N     Samples 0-N         Samples 0-N
  Channel 0       Channel 1           Channel M
Running through the samples of the given heightmap region in packed row-major order will yield the source array. The elements of the target array will be written to the given buffer.

Serialize

Serializes the current state of this object to the given data stream.

method Serialize (ISerializer data)
params data [not-null] The serial data stream.
inherited ISerializable.Serialize

See also:

ISerializable.Deserialize
ISerializable.SerialVersion

ToConfig

Returns the configuration value that describes this object.

method ToConfig ()
type ConfigValue
returns [not-null] The configuration value.
inherited IConfigurable.ToConfig

Remarks:

All configurable objects need to implement this interface. For simple types, it is preferable to delegate to ToValue.

The returned value may be of type Invalid, which means that this object in its current state cannot be described with the configuration API.

Before returning the resulting configuration value, Cache must be called on it, passing this IConfigurable object as parameter.

Extensions

Append

method Append (IHeightmapFormat format)
type IHeightmapFormat
params format