IModel

Description

interface Tinman.Engine.Models.IModel

Extended by: Model ^sealed

Base interface for classes that represent 3D models.

The coordinate space for untransformed top-level 3D models is defined as follows:

X+ : points westwards resp. sidewards.
Y+ : points upwards.
Z+ : points northwards resp. forwards.

The ground level is expected to be at Y-coordinate zero. The coordinate system for top-level IModel objects maps to standard North-East-Down (NED) coordinates as follows:

IModel  |   NED
--------+--------
X+ axis | Y- axis         /          \         /          \
X- axis | Y+ axis         |  0 -1  0 |         |  0  0 +1 |
Y+ axis | Z- axis    M1 = |  0  0 -1 |    M2 = | -1  0  0 |
Y- axis | Z+ axis         | +1  0  0 |         |  0 -1  0 |
Z+ axis | X+ axis         \          /         \          /
Z- axis | X- axis

The matrix M1 transforms from NED, the matrix M2 transforms to NED.

See also: ModelInfo

Public / Methods

BoundsWithPose

public method BoundsWithPose → (1)

pose ⁱⁿ : ModelPose: [not-null]
The model pose to use.
returns → ISpatialBounds: The posed spatial bounds.

Returns the non-shared ISpatialBounds for this IModel that uses the given model pose ⁱⁿ.

This method returns the same object as ColliderWithPose. For details on the semantic differences, please refer to Bounds and Collider.

See also: IModel.Bounds

ChildAt

[Pure]
public method ChildAt → (1)

index ⁱⁿ : int32: [0..IModel.ChildCount-1]
The child model index.
returns → IModel: The child model.

Returns the index ⁱⁿ-th child model.

The same IModel object may be a child of multiple parent IModel objects. The resulting graph of parent-child relations must not contain any cycles.

See also: IModel.ChildTransformAt

ChildTransformAt

[Pure]
public method ChildTransformAt → (1)

index ⁱⁿ : int32: [0..IModel.ChildCount-1]
The child model index.
returns → AffineTransform: The transformation from the child model to this model as parent.

Returns the child-to-parent transformation matrix of the index ⁱⁿ-th child model.

The transformation matrix uses the unit of measure of the parent model (see Unit).

See also: IModel.ChildAt

ColliderLoad

public method ColliderLoad → (1)

data ⁱⁿ : ISerializable: The precomputed spatial data structures.

Initializes the Collider object from the given precomputed spatial data structures.

As an alternative to this method, the ModelFlags.ComplexGeometry flag may be used.

If the given data ⁱⁿ is unsuitable, this method will return silently and a new IModelCollider will be computed.

See also: IModelCollider.Save

ColliderWithPose

public method ColliderWithPose → (1)

pose ⁱⁿ : ModelPose: [not-null]
The model pose to use.
returns → IModelCollider: The posed model collider.

Returns the non-shared IModelCollider for this IModel that uses the given model pose ⁱⁿ.

The returned collider will take the following into account:

If ModelPoseFlags.Hide is present in ModelPose.Flags¹, the model collider will behave as if ModelFlags.NoSpatialQuery had been specified for the IModel.
The custom transformation defined via ModelPose.Transform¹ is applied for children along the model hierarchy and the spatial bounds of the parent models are updated accordingly.

See also: IModel.Collider

Copy

public method Copy → ()

returns → Model: The mutable copy.

Creates a mutable deep copy of this model.

Modifying the returned Model will not affect this model.

PartAt

[Pure]
public method PartAt → (1)

index ⁱⁿ : int32: [0..IModel.PartCount-1]
The model part index.
returns → IModelPart: The model part.

Returns the index ⁱⁿ-th model part.

The same IModelPart object may be used by zero or more IModel objects.

PrepareLazy

public method PrepareLazy → ()

returns → IModel: this

Prepares lazy-loaded data for this model.

After calling this method, doing any of the following is guaranteed to not trigger any more lazy computations for this IModel and all of its descendants:

Bounds
BoundsWithPose
Collider
ColliderWithPose

This method does not pre-load vertex / index data (see IModelGeometry) or textures (see IModelTexture) for rendering.

IOException: If an I/O error has occurred while lazy-loading model data.

Simplify

public method Simplify → (2)

flags ^opt : ModelSimplifyFlags = ModelSimplifyFlags.All: The actions to apply.
nameSkip ^opt : PredicateDelegate<string> = null: Optional predicate to decide whether a model name (see Name) shall be treated as null, regarding the application of ModelSimplifyFlags.RemoveRedundant.
returns → IModel: this

Simplifies this model by applying the given actions.

Simplification is performed in-place and only modifies the model hierarchy, without loading or computing any additional model data, such as:

Collider, which would trigger computation of spatial acceleration data structures.
IModelGeometry.ReadVertices, which would read vertex data, usually involving file I/O.
IModelGeometry.ReadIndices, which would read index data, usually involving file I/O.
IModelTexture.ReadTexels, IModelTexture.ReadPixels or IModelTexture.ReadElevation, which would read texel data, usually involving file I/O.

See also: IModel.Copy

UseGeometryInstancing

public method UseGeometryInstancing → (1)

instanceBuffer ⁱⁿ : IResourceHandle: The resource handle that returns a IVertexBuffer object that holds instance data to use for this model object or null to disable geometry instancing. The instanceBuffer ⁱⁿ value will be returned by the IModelGeometry.InstanceBuffer property of the geometry objects of the returned model and all its descendants.
returns → IModel: The resulting model, which may be this.

Configures geometry instancing for this model.

See also: IModelGeometry.InstanceBuffer

Public / Attributes

Bounds

public attribute Bounds → (get)

value : ISpatialBounds: [not-null]
The spatial bounds (see remarks).

Returns the spatial bounds of this model, which may be shared with other model objects.

This property returns the same object as Collider. However, by using this property, the calling code indicates that it will not use the methods and properties of the ISpatialQuery and IModelCollider interfaces, which allows the implementation to defer pre-computations which would otherwise need to be performed. A ModelFormat may choose to store pre-computed spatial bounds in a model file, which will eliminate even the pre-computation for the spatial bounds.

ChildCount

public attribute ChildCount → (get)

value : int32: [>=0]
The child model count.

The number of child models.

See also: IModel.ChildAt
IModel.ChildTransformAt

Collider

public attribute Collider → (get)

value : IModelCollider: [not-null]
The collider object.

Returns the collider object for this model, which may be shared with other model objects.

Requesting the IModelCollider object of a model by getting this property can trigger lazy computation, which in turn invokes the following methods, if necessary:

IModelGeometry.ReadIndices on the IModelGeometry objects referenced by IModelPart.Geometry.
IModelGeometry.ReadVertices on the IModelGeometry objects referenced by IModelPart.Geometry.

If only the ISpatialBounds of the model are of interest, the Bounds property should be used instead of this property. Doing so allows to return pre-computed bounds, without triggering any lazy compuation.

See also: IModel.ColliderWithPose
IModel.PrepareLazy

FadeIn

public attribute FadeIn → (get)

value : Fade: The fade-in range for the view distance, in model-space.

The fade-in range of this model.

When Fade.Compute returns 0, the model will not be visible at all.

Defaults to Fade.AlwaysOne, i.e. always faded in.

FadeOut

public attribute FadeOut → (get)

value : Fade: The fade-out range for the view distance, in model-space.

The fade-out range of this model.

When Fade.Compute returns 1, the model will not be visible at all.

Defaults to Fade.AlwaysZero, i.e. never faded out.

Flags

public attribute Flags → (get)

value : ModelFlags: The model flags.

The model flags.

Defaults to ModelFlags.None.

Name

public attribute Name → (get)

value : string: The model name, will either be null or non-empty.

The name of this model.

Defaults to null.

PartCount

public attribute PartCount → (get)

value : int32: [>=0]
The model part count.

The number of model parts.

See also: IModel.PartAt

Unit

public attribute Unit → (get)

value : UnitOfMeasure: The model-space unit. If set to null, the default value is returned instead.

The unit of measure in which the vertex coordinates of the model parts are expressed.

Defaults to UnitOfMeasure.Metre.

Extensions

ChildFor

_2 overloads

[Pure]
public static method ChildFor¹ → (2)

name ⁱⁿ : string: The model name.
recursive ^opt : bool = false: true to search all descendant models, using in-order traversal,
false to only search the child models.
returns → IModel: The first matching child model or null if there is none.

Returns the first child or descendant model of the given name (see IModel.Name).

[Pure]
public static method ChildFor² → (3)

name ⁱⁿ : string: The model name.
transform ^out : AffineTransform: The transformation from the returned model to this model. Will be AffineTransform.Identity if null is returned.
recursive ^opt : bool = false: true to search all descendant models, using in-order traversal,
false to only search the child models.
returns → IModel: The first matching child or descendant model or null if there is none.

Returns the first child or descendant model of the given name (see IModel.Name).

ChildTransformWithUnitScaleAt

[Pure]
public static method ChildTransformWithUnitScaleAt → (1)

index ⁱⁿ : int32: [0..model.ChildCount-1]
The child model index.
returns → AffineTransform: The transformation matrix.

Returns the child-to-parent transformation matrix of the index ⁱⁿ-th child model.

The transformation matrix uses the unit of measure of the child model (see IModel.Unit).

See also: IModel.ChildAt

Traverse

public static method Traverse → (4)

action ⁱⁿ : ModelDelegate: [not-null]
The model action to perform.
includeThis ^opt : bool = true: Invoke action ⁱⁿ for this model?
includeChildren ^opt : bool = true: Invoke action ⁱⁿ for descendant models?
level ^opt : int32 = 0: [>=0]
The model hierarchy level, where 0 represents the top-most model of the traversal, which is not necessarily the root model of the hierarchy.

Traverses this model hierarchy and performs the given action at each node.

UnitScale

[Pure]
public static method UnitScale → (1)

unit ^opt : UnitOfMeasure = null: The target unit of measure. If null, metres will be used.
returns → float64: The scale factor from model units to target units.

Returns the scale factor for the give model, based on the specified unit of measure.

Wrap

[OwnerReturn]
public static method Wrap → ()

returns → IModelReader: The IModelReader that wraps this model.

Wraps this model in a IModelReader.

IModel

Description

Public / Methods

Bounds​With​Pose

Child​At

Child​Transform​At

Collider​Load

Collider​With​Pose