class HeightmapFormat in Tinman.Terrain.Heightmaps.Formats

Abstract base class for IHeightmapFormat implementations.

abstract class	HeightmapFormat	implements	IHeightmapFormat
		extends	SerializableBase

Configuration

Config

The configurator object for this type.

public static readonly field	Config
type	IConfigurator<IHeightmapFormat>

ToConfig

Returns the configuration value that describes this object.

public virtual method	ToConfig ()
type	ConfigValue
returns		[not-null]	The configuration value.
implements	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.

Public / Attributes

ByteCount

The number of dataset channels.

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

HasAlpha

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

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

LayerMask

The mask of heightmap layers this object uses.

public abstract property	LayerMask { get }
type	HeightmapLayer
value		Bitwise combination of HeightmapLayer values.
implements	IHeightmapLayers.LayerMask

Remarks:

These heightmap layers store actual terrain data:

• Elevation:
  The terrain elevation, measured upwards from the base geometry (usually an ellipsoid). See VerticalRange.
• Texture:
  A 64-bit ARGB color value that describes the terrain surface (e.g. surface reflectance). See Colors.
• Material:
  A 64-bit ARGB material token that describes the terrain surface (e.g. land cover). See MaterialToken.

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.

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

SerialVersion

Returns the serial data version.

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

Remarks:

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

See also:

ISerializable.Serialize
ISerializable.Deserialize

Public / Constructors

For

Returns a default IHeightmapFormat object for the given pixel format.

[Pure]
public static method	For (PixelFormat format)
type	IHeightmapFormat
params	format		The pixel format.
returns		[not-null]	The IHeightmapFormat object to use.

Remarks:

Depending on the pixel format flags, the following heightmap layer will be processed by the returned IHeightmapFormat object:

• Grayscale and no Alpha: Elevation
• Truecolor or Alpha: Texture

---

Returns an IHeightmapFormat object for the given pixel format and target heightmap layer.

[Pure]
public static method	For (HeightmapLayer layer, PixelFormat format = PixelFormat.Truecolor | PixelFormat.SixteenBits)
type	IHeightmapFormat
params	layer		The target heightmap layer.
	format		The pixel format. Defaults to Truecolor | SixteenBits.
returns		[not-null]	The IHeightmapFormat object to use.

Remarks:

The given layer specifies which heightmap layer will be processed by the returned IHeightmapFormat object. The format value is used to determine the required byte channels (i.e. red, green, blue, alpha, intensity, elevation high/low byte).

ForAll

Returns an IHeightmapFormat that contains default formats for the given layers, augmented with all mandatory layers (see Mandatory).

[Pure]
public static method	ForAll (HeightmapLayer layers = HeightmapLayer.All, PixelFormat format = PixelFormat.Truecolor | PixelFormat.SixteenBits)
type	IHeightmapFormat
params	layers		The heightmap layers. Defaults to All
	format		The pixel format. Defaults to Truecolor | SixteenBits.
returns		[not-null]	The heightmap format to use.

Mandatory

Fixes the given IHeightmapFormat by appending all mandatory heightmap layers.

[Pure]
public static method	Mandatory (IHeightmapFormat format)
type	IHeightmapFormat
params	format		The heightmap format or null.
returns		[not-null]	The heightmap format to use.

Remarks:

It is not necessary to use this method when creating heightmap datasets. It can be used to obtain an equivalent to the IHeightmapFormat object that the dataset is using.

Public / Methods

Collect

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

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

DatasetToHeightmap

Converts the given bytes into heightmap samples.

public abstract 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.
implements	IHeightmapFormat.DatasetToHeightmap

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.

public virtual 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	SerializableBase.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

Equals

Compares this object with the given one.

[Pure]
public abstract method	Equals (IHeightmapFormat other)
type	bool
params	other		The object to compare to.
returns			true if this object is equal to other, false if not.
implements	IEquatable.Equals

HeightmapToDataset

Converts the given heightmap samples into bytes.

public abstract 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.
implements	IHeightmapFormat.HeightmapToDataset

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.

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

See also:

ISerializable.Deserialize
ISerializable.SerialVersion

Protected / Constructors

HeightmapFormat

Creates a new instance of HeightmapFormat.

protected constructor	HeightmapFormat (ISerialTypeInfo serialType)
params	serialType	[not-null]	The serial type ID.