IModel

Description

interface Tinman.Engine.Models.IModel

Derived from: IModelCounts
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

ChildTransformWithUnitScaleAt

[Pure]
public method ChildTransformWithUnitScaleAt → (1)

index ⁱⁿ : int32: [0..IModel.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 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.

See also: IModel.Mutable

MergeFadeOut

public method MergeFadeOut → (3)

threshold ^opt : float64 = 1: [>=0]
The visibility threshold, given in screen units. Models with a bounding sphere having a radius less than the threshold will fade out. Screen space is defined by fieldOfView ^opt and viewport ^opt. If any defining parameter is 0, then all fade ranges will be set to Fade.AlwaysZero.
fieldOfView ^opt : float64 = 50: [>=0]
The field-of-view angle, in degrees.
viewport ^opt : float64 = 1000: [>=0]
The viewport size along the field-of-view, in screen units.
returns → IModel: this

Discards the fade out ranges of this model and its descendants and rebuilds them based on the given visibility threshold ^opt.

If this model has the ModelFlags.Group flag, the method returns without altering the fade out ranges. Otherwise, this method computes FadeOut for each model that has parts with geometry, based on ISpatialBounds.Sphere and threshold ^opt. Fade ranges of intermediate models are computed so that they form a nested hierarchy. Recursive traversal will stop at models that have the ModelFlags.Group flag.

See also: IModel.Copy

MergeGeometries

public method MergeGeometries → ()

returns → IModel: this

Merges all IModelGeometry objects of this model and its descendants.

The collected IModelGeometry objects are grouped by their ModelVertexFormat and then merged, by concatenating the data which is returned by IModelGeometry.ReadIndices and IModelGeometry.ReadVertices, followed by an adjustment of the primitive batches in the model parts. The merged geometries will always be non-instanced, even if the input was instanced, see IModelGeometry.InstanceBuffer. After merging geometries, further simplification via ModelSimplifyFlags.MergeParts may be possible.

See also: IModel.Copy
IModel.Simplify

MergeHierarchy

public method MergeHierarchy → (1)

rootTransform ^opt : bool = false: Compute a root transformation for this model?
returns → AffineTransform: The root transformation that must be applied to this model. If rootTransform ^opt is false, the root transformation will always be AffineTransform.Identity.

Discards the hierarchical structure of this model and builds a new one that is spatially optimized and thus suitable for efficient rendering and spatial queries.

If this model has the ModelFlags.Group flag, the method returns without altering the hierarchical structure. Otherwise, this method collects all descendants of this model and puts them into a flat list, while keeping their absolute position / orientation, unit of measure and fade range intact. Recursive traversal will stop at models that have the ModelFlags.Group flag. The models in the list are arranged in a hierarchical spatial structure, by creating new intermediate Model nodes where necessary.

See also: IModel.Copy

MergeModels

public method MergeModels → ()

returns → IModel: this

If possible, merges the model parts of all descendant models into this model and then removes them.

If this model has the ModelFlags.Group flag, the method returns without merging any child models. The recursive merge process will stop at child models that have a different unit of measure (see Unit) as this model, a non-identity child transform (see ChildTransformAt), non-default values for FadeIn and/or FadeOut or the ModelFlags.Group flag. All other child model data will be discarded, i.e. all Flags except ModelFlags.Group and Name. To ensure that the merge process is performed on all descendants, the MergeUnitsAndTransforms method may be used before merging models. After merging models, further simplification via ModelSimplifyFlags.MergeParts may be possible.

See also: IModel.Copy
IModel.Simplify

MergeUnitsAndTransforms

public method MergeUnitsAndTransforms → ()

returns → IModel: this

Applies Unit of this model to all its descendants, then uses IModelGeometry.Transform on IModelPart.Geometry to effectively turn all child transforms to identity and finally uses Fade.Mul to adjust FadeIn and FadeOut accordingly.

After merging units and transforms, further simplification via ModelSimplifyFlags.RemoveRedundant may be possible.

See also: IModel.Copy
IModel.Simplify

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. However, in order to be able to perform the lazy computations, vertex / index data needs to be read. This can lead to bad performance. For example, when triggering lazy computations in a hierarchy of models by getting Bounds separately for each leaf model, data must be read for each computation. Now, if there is a big shared model geometry buffer, a lot of data will be read repeatedly. By calling PrepareLazy on the root model, all lazy computations can be performed while reading the vertex / index data only once.

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

See also: IModel.Laziness

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
IModel.MergeGeometries
IModel.MergeModels
IModel.MergeUnitsAndTransforms

UnitScale

[Pure]
public 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.

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 computation.

See also: IModel.ColliderWithPose
IModel.PrepareLazy
ModelFlags.ComplexGeometry

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 would 0 for all points on model surface, the model will not be visible at all. Rendering of the model and its descendants will be skipped entirely if Fade.Compute would return 0 for all points on the surface of the bounding sphere (see ISpatialBounds.Sphere of Bounds).

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 would 1 for all points on model surface, the model will not be visible at all. Rendering of the model and its descendants will be skipped entirely if Fade.Compute would return 1 for all points on the surface of the bounding sphere (see ISpatialBounds.Sphere of Bounds).

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.

Laziness

public attribute Laziness → (get)

value : int32: 0 : neither Bounds nor Collider will trigger lazy computations
1 : only Collider will trigger lazy computations
2 : both Bounds and Collider will trigger lazy computations

Returns the current state of laziness of this model.

See also: IModel.PrepareLazy

Mutable

[Constant]
public attribute Mutable → (get)

value : Model: [not-null]
The mutable Model reference.

Returns the mutable Model reference for this model.

See also: IModel.Copy

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).

Save

public static method Save → (2)

path ⁱⁿ : Path: [not-null]
The output model file.
format ^opt : ModelFormat = null: The model format or null to use ModelFormat.Any.

Saves this model to a file.

IOException: If an I/O error has occurred while writing the 3D model data.

See also: Model.Load¹

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.

Wrap

[OwnerReturn]
public static method Wrap → ()

returns → IModelReader: The IModelReader that wraps this model.

Wraps this model in a IModelReader.

Write

[OwnerReturn]
public static method Write → (2)

path ⁱⁿ : Path: [not-null]
The output model file.
format ^opt : ModelFormat = null: The model format or null to use ModelFormat.Any.
returns → IModelWriter: The model writer operation.

Writes this model to a file.

IOException: If an I/O error has occurred while writing the 3D model data.

See also: Model.Read¹

IModel

Description

Public / Methods

Bounds​With​Pose

Child​At

Child​Transform​At

Child​Transform​With​Unit​Scale​At

Collider​Load

Collider​With​Pose