TerrainModel

Description

sealed class Tinman.Engine.Components.TerrainModel

Derived from

MeshBoundBase
ISpatialQuery
IVisibleMask

Describes a 3D model that is placed somewhere onto the terrain.

The coordinate system of a terrain model (in terms of ISpatialQuery) is terrain-space. For planetary terrains, this is the geocentric frame (see Geocentric). Analogously, the spatial bounds returned by ISpatialBounds are also in terrain-space.

When using a ISpatialCallback with the ISpatialQuery interface, the child indices provided by ISpatialCallback.ChildPush correlate with IModel.ChildAt for Model.

Geometry instancing can be used to render the 3D model multiple times on the GPU, without additional overhead on the CPU. The following mechanisms are provided by this class:

Public / Constructors

Terrain​Model

5 overloads

public constructor TerrainModel1 → (1)

visibleMask opt : int64 = ~0

The initial value for IVisibleMask.VisibleMask.

Creates a new instance of TerrainModel.

public constructor TerrainModel2 → (2)

flags in : TerrainModelFlags

Initial value for Flags.

visibleMask opt : int64 = ~0

The initial value for IVisibleMask.VisibleMask.

Creates a new instance of TerrainModel.

public constructor TerrainModel3 → (3)

withPose in : bool

Set Pose to a new ModelPose object?

flags opt : TerrainModelFlags = TerrainModelFlags.Default

Initial value for Flags.

visibleMask opt : int64 = ~0

The initial value for IVisibleMask.VisibleMask.

Creates a new instance of TerrainModel.

public constructor TerrainModel4 → (4)

model in : IModel

The initial value for Model.

withPose opt : bool = false

Set Pose to a new ModelPose object?

flags opt : TerrainModelFlags = TerrainModelFlags.Default

Initial value for Flags.

visibleMask opt : int64 = ~0

The initial value for IVisibleMask.VisibleMask.

Creates a new instance of TerrainModel.

public constructor TerrainModel5 → (5)

transform in : AffineTransform

The initial value for Transform.

model opt : IModel = null

The initial value for Model.

withPose opt : bool = false

Set Pose to a new ModelPose object?

flags opt : TerrainModelFlags = TerrainModelFlags.Default

Initial value for Flags.

visibleMask opt : int64 = ~0

The initial value for IVisibleMask.VisibleMask.

Creates a new instance of TerrainModel.

Public / Methods

Bounds

public method Bounds → (6)

bounds in : BoxSoup

[not-null]
The output box soup that will receive those IModel objects nearest to the root that contain visual geometry.

spatial in : BoxSoup

Optional output box soup for the intermediate spatial nodes between the root and the nodes in bounds in.

frustum opt : Frustum = null

The view frustum to use for culling or null to disable.

viewport opt : Viewport = null

The viewport to use for screen size culling or null to disable.

cameraPosition opt : Vec3D = default(Vec3D)

The camera position for screen size culling.

screenSize opt : float64 = Maths.Sqrt2

The smallest screen size (in pixels) for which culling will be performed.

Outputs the bounds of this terrain model to the given box soup.

Decoration​Dirty

public method DecorationDirty → ()

Invalidates the current 3D model decoration, if any.

This method must be called in the following situations:

  • The model (see Model) has been modified externally, for example by adding child models or model parts.

  • The pose (see Pose) has been modified in a way that affects the decorator (see Decorator), for example by hiding descendant models for a decorator that processes the whole model hierarchy.

Setting different model, pose or decorator objects automatically invalidates the model decoration. In these cases, this method does not need to be called.

See also

TerrainModel.Decoration

Decoration​Update

public method DecorationUpdate → ()

Applies the current 3D model decorator.

This method may be called repeatedly. If necessary, it will rebuild the model decoration (which may take some time) or update the existing model decoration (which usually completes quickly). If there is no work to do, the method returns instantly.

See also

TerrainModel.Decoration
TerrainModel.DecorationDirty

Instance​Dynamic

public method InstanceDynamic → (2)

count in : int32

[>=0]
The number of geometry instances, see InstanceCount.

updater opt : IInstanceUpdater = null

The instance updater to use or null for none, InstanceUpdater.

Configures dynamic geometry instancing.

Instance​None

public method InstanceNone → ()

Disables geometry instancing for the 3D model.

Instance​Static

public method InstanceStatic → (1)

data in : ModelInstance [ ]

[not-null]
The geometry instances.

Configures static geometry instancing.

See also

TerrainModel.InstanceCount
TerrainModel.InstanceData

Instance​Update

public method InstanceUpdate → (4)

pose in : AffineTransform

The instance pose.

color opt : int64 = ~0

The instance color (low dynamic range).

intensity opt : float32 = 1

The instance color intensity (high dynamic range).

worldSpace opt : bool = true

true to apply AffineTransform.Translation in world-space,
false to apply AffineTransform.Translation in model-space.

Updates the next model instance.

This method may only be called between calls to InstanceUpdateBegin and InstanceUpdateEnd. Alternatively, model instance data (see ModelInstance.WriteInstance) may also be written directly to the model instance buffer (see InstanceUpdateBuffer).

Instance​Update​Begin

public method InstanceUpdateBegin → (4)

view in : TerrainView

[not-null]
The terrain view.

first opt : int32 = 0

[0..TerrainModel.InstanceCount]
The first instance that will be updated.

count opt : int32 = -1

[-1..TerrainModel.InstanceCount-first]
The number of instances that will be updated. If -1, all remaining instances will be updated.

flag opt : GpuUpdateFlag = GpuUpdateFlag.Discard

The update flag to use for accessing the instance buffer on the GPU.

returns → int32

The number of instances that are expected to be updated subsequently, by calling the InstanceUpdate method once for each one.

Begins to update the instance data of this model for the given view.

See also

TerrainModel.InstanceUpdater

Instance​Update​Buffer

public method InstanceUpdateBuffer → ()

returns → ByteBuffer

The buffer that holds the model instance data (see ModelInstance.WriteInstance) or null if not between a pair of calls to InstanceUpdateBegin and InstanceUpdateEnd. The buffer is positioned at the next model instance. The caller is responsible for writing correct model instance data to the returned buffer. The InstanceUpdate method may be used to write correct model instance data safely, at the cost of flexibility.

Returns the buffer for updating model instances.

See also

TerrainModel.InstanceUpdate

Instance​Update​End

public method InstanceUpdateEnd → ()

Ends the current instance data update.

Public / Attributes

Decoration

public attribute Decoration → (get)

value : IModel

The decoration model or null if there is no decorator or if the model is instanced.

Returns the current 3D model decoration, building / updating it if necessary.

Building a new decoration may incur additional computational overhead, whereas updating it usually completes quickly. The DecorationUpdate method may be used to perform the building work eagerly, instead of lazily via this property.

See also

TerrainModel.Decorator
TerrainModel.InstanceCount

Decorator

public attribute Decorator → (get,set)

value : IModelDecorator

The decorator.

The decorator to use for building the decoration for non-instanced 3D models.

Defaults to null.

Flags

public attribute Flags → (get,set)

value : TerrainModelFlags

The flags.

The behaviour flags of this 3D model.

Defaults to TerrainModelFlags.Default.

Instance​Count

public attribute InstanceCount → (get)

value : int32

[>=0]
The number of model instances. Will be 0 if model instancing is disabled.

The number of model instances.

See also

TerrainModel.InstanceDynamic
TerrainModel.InstanceStatic

Instance​Data

public attribute InstanceData → (get)

value : ModelInstance [ ]

The static geometry instance data or null if static model instancing is disabled.

The static geometry instance data that is used for rendering the 3D model.

See also

TerrainModel.InstanceStatic

Instance​Range

public attribute InstanceRange → (get,set)

value : RangeI

The model instance range.

The range of model instances to render.

The instance range is clamped to the valid range of instance indices. Defaults to RangeI.Zero.

See also

TerrainModel.InstanceDynamic
TerrainModel.InstanceStatic

Instance​Updater

public attribute InstanceUpdater → (get)

value : IInstanceUpdater

The used instance updater or null if dynamic model instancing is disabled.

The IInstanceUpdater that is used for this terrain model.

When an instance updater is present and InstanceCount is greater than zero, the TerrainView will call IInstanceUpdater.UpdateTerrainModelInstances from within IRenderable.Render automatically. Defaults to null.

See also

TerrainModel.InstanceDynamic

Is​Valid

public attribute IsValid → (get)

value : bool

true if this 3D model is valid, false if not.

Is this 3D model valid?

Only valid models will be processed and rendered.

Model

public attribute Model → (get,set)

value : IModel

The 3D model or null.

The 3D model.

Defaults to ModelDecorator.None.

Model​Bounds

public attribute ModelBounds → (get)

value : ISpatialBounds

[not-null]
The spatial bounds.

Returns the ISpatialBounds of Model which takes Pose into account, if present.

See also

IModel.Bounds
IModel.BoundsWithPose

Model​Collider

public attribute ModelCollider → (get)

value : IModelCollider

[not-null]
The model collider.

Returns the IModelCollider of Model which takes Pose into account, if present.

See also

IModel.Collider
IModel.ColliderWithPose

Pose

public attribute Pose → (get,set)

value : ModelPose

The 3D model pose or null.

The 3D model pose.

Defaults to null.

Transform

public attribute Transform → (get,set)

value : AffineTransform

The model transform.

The transformation from model-space (in terrain units) to terrain-space (in terrain units), not taking into account the model pose.

Defaults to AffineTransform.Identity.

Transform​Unit​Pose

public attribute TransformUnitPose → (get)

value : AffineTransform

The model transform.

The transformation from model-space (in model units) to terrain-space (in terrain units), taking into account the current model pose.