Class HeightField

Namespace

Box3D

Assembly

Box3D.NET.dll

A terrain surface defined by a grid of heights.

public sealed class HeightField : IDisposable

Inheritance

object

HeightField

Implements

IDisposable

Inherited Members

object.Equals(object?)

object.Equals(object?, object?)

object.GetHashCode()

object.GetType()

object.ReferenceEquals(object?, object?)

object.ToString()

Examples

// A 256 by 256 terrain from your own height data.
float[] heights = LoadHeightmap();

using var terrain = HeightField.FromHeights(
    heights,
    columnCount: 256,
    rowCount: 256,
    scale: new Vector3(1.0f, 100.0f, 1.0f));   // 1m cells, 100m of relief

Body ground = world.CreateStaticBody();
ground.AddHeightField(terrain);

Remarks

A height field is the right shape for terrain: it stores one number per grid point instead of triangles, compresses those numbers, and queries faster than the equivalent mesh. The cost is the restriction that it is a height map, so it cannot describe caves or overhangs.

Lifetime. As with Box3D.CollisionMesh, attaching a height field does not copy it. It must outlive every shape built from it, and disposing it early crashes inside the solver rather than raising. Dispose the world first.

Static bodies only.

Quantization. Heights are stored compressed against the minimum and maximum given at build time. Two height fields that must line up along an edge have to share the same minimum and maximum, or their quantization steps differ and a seam appears.

Placement. A height field starts at its body's origin and extends in positive x and z, rather than being centred on it. A 64 by 64 grid of two-metre cells therefore covers x and z from 0 to 128. Position the body to place it, or read Box3D.HeightField.Bounds to find out where it ended up.

Fields

HoleMaterial

The material index that marks a cell as a hole, which nothing collides with.

Properties

Bounds

Gets the local-space bounding box.

ByteCount

Gets the memory the height field occupies, in bytes.

ColumnCount

Gets the number of grid columns along the x axis.

IsDisposed

Gets a value indicating whether this height field has been disposed.

RowCount

Gets the number of grid rows along the z axis.

Methods

Dispose()

Releases the height field.

FromHeights(ReadOnlySpan<float>, int, int, Vector3, ReadOnlySpan<byte>, float?, float?, bool)

Builds a height field from a grid of heights.

Grid(int, int, Vector3, bool)

Builds a flat grid, useful as a test floor.

Wave(int, int, Vector3, float, float, bool)

Builds a rolling wave surface, useful for testing uneven terrain.