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

class HeightmapRegion in Tinman.Terrain.Heightmaps

This class represents the samples of a rectangular region of a heightmap.

sealed class HeightmapRegion implements IDeletable
  IHeightmapBuffer
  ISampleBufferBase

See also:

HeightmapSample

Public / Attributes

Coverage

The buffer for Coverage values.

public property Coverage { get }
type CoverageBuffer
value [not-null] The coverage buffer.

See also:

HeightmapSample.Coverage
HeightmapSamples.Coverage

Exceptions:

CoverageNull

The buffer for Coverage values.

public property CoverageNull { get }
type CoverageBuffer
value The coverage buffer or null if all samples in this region are fully solid or if this heightmap region does not store coverage values.

See also:

HeightmapSample.Coverage
HeightmapSamples.Coverage

Displacement

The buffer for Displacement values.

public property Displacement { get }
type ElevationBuffer
value [not-null] The displacement buffer.

See also:

HeightmapSample.Displacement
HeightmapSamples.Displacement

Exceptions:

Elevation

The buffer for Elevation values.

public property Elevation { get }
type ElevationBuffer
value [not-null] The elevation buffer.

See also:

HeightmapSample.Elevation
HeightmapSamples.Elevation

Exceptions:

Height

The height of the buffer, in samples.

public property Height { get }
type int32
value [>0] The height of the buffer, in samples.
implements ISampleBufferBase.Height

Horizontal

The horizontal scale of the samples in this region (in Metre).

public property Horizontal { get set }
type float64
value [>0] The horizontal scale (i.e. ground sample distance).

Remarks:

Defaults to 1.

IsPacked

Returns if this sample buffer is densely packed.

public property IsPacked { get }
type bool
value true if this buffer is densely packed, false if not.
implements ISampleBufferBase.IsPacked

Remarks:

A packed sample buffer can be indexed with the following scheme: 

Samples[(y * Width + x) * TupleSize + 0] := 1st value of sample at (x,y).
Samples[(y * Width + x) * TupleSize + 1] := 2nd value of sample at (x,y).
...
Samples[(y * Width + x) * TupleSize + TupleSize - 1] := last value of sample.
Thus the samples of a densely packed buffer form a contiguous region in memory.

LayerMask

The mask of heightmap layers this object uses.

public property LayerMask { get }
type HeightmapLayer
value Bitwise combination of HeightmapLayer values.
implements 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.).

Material

The buffer for Material values.

public property Material { get }
type MaterialBuffer
value [not-null] The material buffer.

Remarks:

The heightmap region will never modify the ScanlineMaterials property of the material buffer.

See also:

HeightmapSample.Material
HeightmapSamples.Material

Exceptions:

MemoryConsumption

Returns the estimated memory consumption of this object.

public property MemoryConsumption { get }
type int64
value [>=0] The estimated memory consumption, in bytes.
implements IMemoryConsumption.MemoryConsumption

Offset

Index of top-left sample in the buffer.

public property Offset { get }
type int32
value [>=0] The buffer offset.
implements ISampleBufferBase.Offset

Slope

Returns the slope info of the samples in this region.

public property Slope { get }
type SlopeInfo
value The slope info.

Remarks:

The slope info is computed from Vertical and Horizontal.

Stride

Distance between two consecutive rows in the buffer.

public property Stride { get }
type int32
value [>0] The buffer stride, in samples.
implements ISampleBufferBase.Stride

Texture

The buffer for Texture values.

public property Texture { get }
type ColorBuffer
value [not-null] The texture buffer.

See also:

HeightmapSample.Texture
HeightmapSamples.Texture

Exceptions:

Vertical

The vertical range of the samples in this region (in Metre).

public property Vertical { get set }
type VerticalRange
value The vertical range.

Remarks:

Defaults to Default.

Width

The width of the buffer, in samples.

public property Width { get }
type int32
value [>0] The width of the buffer, in samples.
implements ISampleBufferBase.Width

Public / Constructors

Create

Creates a new instance of HeightmapRegion.

public static method Create (int32 width, int32 height, HeightmapLayer layers, bool swapAxes = false)
type HeightmapRegion
params width [>0] The heightmap region width, in samples.
  height [>0] The heightmap region height, in samples.
  layers The heightmap layers.
  swapAxes Swap width and height (useful when creating buffers for Transforms)? Defaults to false.
returns [not-null] The heightmap region.

Remarks:

Instances of HeightmapRegion can be pooled by calling Delete.

ForBrush

Returns a new HeightmapRegion which can be used to apply the given brush.

public static method ForBrush (IBrush brush)
type HeightmapRegion
params brush [not-null] The brush.
returns [not-null] The heightmap region.

Public / Methods

AddLayers

Adds the given heightmap layers this buffer.

public method AddLayers (HeightmapLayer layers)
params layers The set of heightmap layers this buffer shall be able to store.
implements IHeightmapBuffer.AddLayers

ApplyTransform

Perform an in-place Transform of the samples in the given region.

public method ApplyTransform (int32 x, int32 y, int32 width, int32 height, Transform transform)
params x [0..Width] X-coordinate of top-left sample of region.
  y [0..Height] Y-coordinate of top-left sample of region.
  width [0..Width-x] Width of region to transform.
  height [0..Height-y] Height of region to transform.
  transform The 2D transform to apply.

Remarks:

For square regions (i.e. same width and height), all Transform s can be applied in-place. For rectangular regions, width and height might be swapped ( WillSwapAxes) while the top-left sample of the given region remains in the same place.

If this sample buffer is not big enough to hold the swapped width resp. height, output samples will be discarded.

This method reads samples from the given input region and writes samples to the transformed output region. No other sample are accessed by this method.

Buffer

Returns the sample buffer for the given heightmap layer.

public method Buffer (HeightmapLayer layer)
type ISampleBuffer
params layer The heightmap layer.
returns The sample buffer or null if not present.

Clear

Clears the given sample block.

public method Clear (bool voidOrDefault, int32 width, int32 height, HeightmapLayer layers = HeightmapLayer.All, int32 x = 0, int32 y = 0, int32 step = 1)
params voidOrDefault Clear to Void (true) or to Default (false)?
  width [>=0] Number of samples to clear along X-axis.
  height [>=0] Number of samples to clear along Y-axis.
  layers The heightmap layers to clear. Defaults to All.
  x [0..Width] X-coordinate of top-left sample to clear. Defaults to 0.
  y [0..Height] Y-coordinate of top-left sample to clear. Defaults to 0.
  step [>=1] Step distance between samples to clear in region. Defaults to 1.

Copy

Copies heightmap samples from this region to the given one.

public method Copy (HeightmapRegion target, int32 width, int32 height, HeightmapLayer layers = HeightmapLayer.All, int32 sourceX = 0, int32 sourceY = 0, int32 targetX = 0, int32 targetY = 0, int32 sourceStep = 1, int32 targetStep = 1, Transform transform = Transform.None)
params target [not-null] The target heightmap region.
  width [>=0] Number of samples to copy along source X-axis.
  height [>=0] Number of samples to copy along source Y-axis.
  layers The heightmap layers to copy. Defaults to All.
  sourceX [0..Width] X-coordinate of top-left source sample to copy. Defaults to 0.
  sourceY [0..Height] Y-coordinate of top-left source sample to copy. Defaults to 0.
  targetX [0..target.Width] X-coordinate of top-left target sample to copy. Defaults to 0.
  targetY [0..target.Height] Y-coordinate of top-left target sample to copy. Defaults to 0.
  sourceStep [>=1] Step distance between samples to copy in source region. Defaults to 1.
  targetStep [>=1] Step distance between samples to copy in target region. Defaults to 1.
  transform Optional affine transformation to apply to the copied samples. The top-left corners of the source region and transformed target region coincide. Defaults to None.

CoverageFlagsOf

Compute the coverage flags of the heightmap samples in the given rectangle.

public method CoverageFlagsOf (int32 x = 0, int32 y = 0, int32 width = -1, int32 height = -1, int32 step = 1)
type CoverageFlags
params x [0..Width] X-coordinate of top-left sample to check. Defaults to 0.
  y [0..Height] Y-coordinate of top-left sample to check. Defaults to 0.
  width [>=-1] Number of samples to check along X-axis. If -1, all samples towards the right buffer edge will be checked. Defaults to -1.
  height [>=-1] Number of samples to check along Y-axis. If -1, all samples towards to the bottom buffer edge will be checked. Defaults to -1.
  step [>=1] [>=1] Step distance between samples to check. Defaults to 1.
returns The coverage flags.

Delete

Deletes this object immediately.

public method Delete ()
implements IDeletable.Delete

Remarks:

Deletion is considered to be a notification that the object is no longer used. The implementation is then free to perform cleanup or pooling actions.

Using an object after Delete has been called will yield undefined results. The code that calls Delete must make sure that there are no shared usages of the object that is being deleted.

Fill

Fills buffer samples with the given value.

public method Fill (HeightmapSample value, int32 x = 0, int32 y = 0, int32 countX = -1, int32 countY = -1, int32 step = 1)
params value The value to fill with.
  x [0..Width] X-coordinate of top-left buffer sample to clear.
  y [0..Height] Y-coordinate of top-left buffer sample to clear.
  countX [>=-1] Number of buffer samples to clear along X-axis. If -1, samples up to the right buffer edge will be cleared. Defaults to -1.
  countY [>=-1] Number of buffer samples to clear along Y-axis. If -1, samples down to the bottom buffer edge will be cleared. Defaults to -1.
  step [>=1] The step distance between buffer samples. Defaults to 1.

Gather

Fetches scattered samples from this heightmap region and stores them into the given linear buffer.

public method Gather (HeightmapSamples target, [] Vec2I[] coords, int32[] indices, int32 first, int32 count, HeightmapLayer layers = HeightmapLayer.All)
params target [not-null] The target buffer.
  coords [not-null] Buffer coordinates of samples to gather from this region.
  indices [not-null] Indices into coords, determining which samples to gather. Also output sample indices for storing results into target.
  first [0..indices.Length] Index of first element in indices to process.
  count [0..indices.Length-first] Number of samples to gather.
  layers The heightmap layers to gather. Defaults to All.

GetAt

Returns a single heightmap sample.

[Pure]
public method GetAt (int32 offset)
type HeightmapSample
params offset [>=0] The heightmap sample offset.
returns The heightmap sample value.
implements IHeightmapBuffer.GetAt

Remarks:

The maximum valid sample offset is defined by the implementing class.

Returns a single sample in the region.

public method GetAt (int32 x, int32 y)
type HeightmapSample
params x [0..Width-1] The sample X-coordinate (relative to region).
  y [0..Height-1] The sample Y-coordinate (relative to region).

Modulate

Modulates the heightmap samples in this region with the given coverage buffer.

public method Modulate (CoverageBuffer coverage = null, HeightmapLayer layers = HeightmapLayer.All)
params coverage The coverage buffer or null. If null the coverage of this region will be used. Defaults to null
  layers The heightmap layers to modulate. Defaults to All.

OffsetAt

Computes the buffer index for the given heightmap sample.

[Pure]
public method OffsetAt (int32 y)
type int32
params y [0..Height-1] Y-coordinate of the row.
returns [>=0] Buffer index of the heightmap sample.
implements ISampleBufferBase.OffsetAt

Remarks:

The returned buffer index may only be used to access the heightmap samples in the specified row (see y).

Computes the buffer index for the given heightmap sample.

[Pure]
public method OffsetAt (int32 x, int32 y)
type int32
params x [0..Width-1] X-coordinate of sample.
  y [0..Height-1] Y-coordinate of sample.
returns [>=0] Buffer index of the heightmap sample.
implements ISampleBufferBase.OffsetAt

Pad

public method Pad (IHeightmap map, CubemapFaceRect bounds, int32 step = 1)
params map
  bounds
  step

Duplicates the samples on the edge of the given rectangle towards the buffer boundary.

public method Pad (int32 x, int32 y, int32 width, int32 height)
params x [0..Width] X-coordinate of top-left corner of rectangle.
  y [0..Height] Y-coordinate of top-left corner of rectangle.
  width [0..Width-x] Width of rectangle.
  height [0..Height-y] Height of rectangle.

SetAt

Sets a single heightmap sample.

public method SetAt (int32 offset, HeightmapSample sample, HeightmapLayer layers = HeightmapLayer.All)
params offset [>=0] The heightmap sample offset.
  sample The heightmap sample value.
  layers The heightmap layers to set. Defaults to All.
implements IHeightmapBuffer.SetAt

Remarks:

Passing a heightmap sample with partial coverage to a buffer that does not contain the Coverage layer will result in that layer being added to this buffer via a call to AddLayers.

The maximum valid sample offset is defined by the implementing class.

Sets a single sample in the region.

public method SetAt (int32 x, int32 y, HeightmapSample sample, HeightmapLayer layers = HeightmapLayer.All)
params x [0..Width-1] The sample X-coordinate (relative to region).
  y [0..Height-1] The sample Y-coordinate (relative to region).
  sample The sample.
  layers The heightmap layers to set. Defaults to All.

Shift

Shifts the samples in this buffer by the given amount.

public method Shift (int32 x, int32 y, ICollector<Box2I> callback = null)
params x Horizontal shift amount.
  y Vertical shift amount.
  callback Collector for sample buffer regions that have been invalidated by the shift.
implements ISampleBufferBase.Shift

Remarks:

This method allows sample buffers to be used in a toroidal manner (i.e. as a two-dimensional ringbuffer).

Specifying a positive value for x will create space for new samples at the left buffer border, a negative value for x will create space at the right border.

Specifying a positive value for y will create space for new samples at the top buffer border, a negative value for y will create space at the bottom border.

The contents of the samples in the additional space at the buffer border is unspecified and must be set by the application.

SubRegion

Returns a HeightmapRegion object that represents a subregion of this region.

public method SubRegion (int32 x, int32 y, int32 width, int32 height)
type HeightmapRegion
params x [0..Width] X-coordinate of top-left corner of subregion.
  y [0..Height] Y-coordinate of top-left corner of subregion.
  width [0..Width-x] Width of subregion.
  height [0..Height-y] Height of subregion.
returns [not-null] The subregion of this heightmap region.

Warp

Fills a rectangular region in the given target buffer by warping target buffer coordinates to source buffer coordinates using the given transform, followed by interpolation of source buffer samples.

public method Warp (Mat3F transform, HeightmapRegion target, HeightmapLayer layers = HeightmapLayer.All, int32 targetX = 0, int32 targetY = 0, int32 targetWidth = -1, int32 targetHeight = -1, int32 sourceX = 0, int32 sourceY = 0, int32 sourceWidth = -1, int32 sourceHeight = -1)
params transform The homogeneous transformation matrix that warps target buffer coordinates (relative to targetX and targetY) to source buffer coordinates (relative to sourceX and sourceY). Such a matrix can be created with Warp. Source buffer coordinates will be clamped to the specified range.
  target [not-null] The target sample buffer.
  layers The heightmap layers to process. Defaults to All.
  targetX [0..target.Width] X-coordinate of top-left corner of target buffer rectangle to fill. Defaults to 0.
  targetY [0..target.Height] Y-coordinate of top-left corner of target buffer rectangle to fill. Defaults to 0.
  targetWidth [>=-1] Width of of target buffer rectangle. If -1, the rectangle will reach to the right target buffer edge. Defaults to -1.
  targetHeight [>=-1] Height of of target buffer rectangle. If -1, the rectangle will reach to the bottom target buffer edge. Defaults to -1.
  sourceX [0..Width] X-coordinate of top-left corner of source buffer rectangle to use for interpolation. Defaults to 0.
  sourceY [0..Height] Y-coordinate of top-left corner of source buffer rectangle to use for interpolation. Defaults to 0.
  sourceWidth [>=-1] Width of of source buffer rectangle. If -1, the rectangle will reach to the right source buffer edge. Defaults to -1.
  sourceHeight [>=-1] Height of of source buffer rectangle. If -1, the rectangle will reach to the bottom source buffer edge. Defaults to -1.
Tinman 3D SDK v1.0 | info@tinman3d.com | Copyright © 2012 - 2017 Matthias Englert, Fulda (Germany)