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

class ModelReader in Tinman.AddOns.Models

Abstract base class for implementations of the IModelReader interface that perform additional processing while reading 3D models.

abstract class ModelReader extends ModelReaderBase

Configuration

Config

The configurator object for this type.

public static property Config { get }
type IConfigurator<IModelReader>
value [not-null] The configurator object.

ConfigReadModelFlags

The configurator object for ReadModelFlags values.

public static readonly field ConfigReadModelFlags
type IConfigurator<ReadModelFlags>

ToConfig

Returns the configuration value that describes this object.

public override sealed method ToConfig ()
type ConfigValue
returns [not-null] The configuration value.
implements ModelReaderBase.ToConfig

Remarks:

All configurable objects need to implement this interface. For simple types, it is preferable to delegate to ToValue.

The returned value may be of type Invalid, which means that this object in its current state cannot be described with the configuration API.

Before returning the resulting configuration value, Cache must be called on it, passing this IConfigurable object as parameter.

Public / Attributes

BadTextureNames

Returns the texture names (see TextureName) that could not have been resolved.

public property BadTextureNames { get }
type string[]
value The bad texture names or null if texture names have been resolved or the ReadModel method has not been called yet.

Remarks:

A warning message is generated for each bad texture name during validation (see Validate).

FixWinding

Fix vertex winding of indexed triangle list primitives?

public property FixWinding { get set }
type int32
value Given a triangle (a,b,c), vertex winding is fixed using the face normal N and the cross product X=(b-a)x(c-a):
> 0: Fix triangle winding so that dot(N,X) is positive.
< 0: Fix triangle winding so that dot(N,X) is negative.
= 0: Do not fix triangle winding.

Remarks:

If the model does not have normal vectors, vertex winding will never be fixed. This fix is applied after FlipWinding.

Defaults to 0.

See also:

ReadModelFlags.FlipWinding
ModelFlags.FrontFaces
ModelFlags.BackFaces

Flags

The flags to use for reading the 3D model.

public property Flags { get set }
type ReadModelFlags
value The flags.

Remarks:

Defaults to None.

GlossScale

Scale factor to apply to Gloss of all read materials.

public property GlossScale { get set }
type float32
value [>=0] The gloss scale.

Remarks:

Defaults to 1.0.

LifecycleState

Returns the lifecycle state of this object.

public virtual property LifecycleState { get }
type LifecycleState
value The lifecycle state.
inherited Disposable.LifecycleState

ReflectivityScale

Modulation color to apply to Reflectivity of all read materials.

public property ReflectivityScale { get set }
type ColorF
value The reflectivity scale.

Remarks:

Defaults to White.

RootMaterial

The material to use for the model root node.

public property RootMaterial { get set }
type IMaterial
value The root material or null.

RootUnit

The unit of measure to use for the model root node.

public property RootUnit { get set }
type UnitOfMeasure
value The root unit of measure or null.

TexturePath

The base directory to use for resolving relative texture file paths in the 3D model.

public property TexturePath { get set }
type Path
value [not-null] The texture base directory.

Remarks:

The given base directory can be relative; in this case, it will be resolved using the path of the directory that contains the model file. If there is no path info for the model data (see IsPathInfoValid), the current filesystem directory is used instead.

Defaults to Current.

Transform

Optional transformation matrix to apply to the model geometry.

public property Transform { get set }
type Mat4D
value The transformation matrix.

Remarks:

The transformation matrix is applied as the last transformation step, before the custom post processors are invoked.

Defaults to Identity.

Public / Methods

AcquireTry

Acquires a strong reference to this disposable object.

[OwnerReturn, ThreadSafe]
public method AcquireTry ()
type IDisposable
returns this if a new strong reference has been acquired, null if this object is already being disposed.
inherited Disposable.AcquireTry

Remarks:

The object will not be actually disposed by calls to Dispose when there is at least one strong reference left. Code that calls the AcquireTry method is responsible for calling the Dispose method accordingly.

This method is not intended to be used in performance-critical code. It should only be used to high-level resource management.

Dispose

Releases all resources held by this object if there are no more strong references to it, decrements the reference counter by one otherwise.

[Dispose, OwnerThis, ThreadSafe]
public method Dispose ()
inherited Disposable.Dispose

Remarks:

The Dispose method silently returns if the object has already been disposed.

PostProcess

Adds the given custom model post processor.

public method PostProcess (IModelPostProcessor postProcessor)
params postProcessor [not-null] The custom post processor.

ReadModel

Reads the 3D model using the current options.

public method ReadModel ()
type IModel
returns [not-null] The read 3D model.
inherited ModelReaderBase.ReadModel

Remarks:

When the ReadModel method is called multiple times, the same IModel object will be returned, unless the model reader options have been modified.

ResolveTexturePath

Resolves the given texture path, using the current model reader settings.

[Pure]
public method ResolveTexturePath (Path path)
type Path
params path [not-null] The texture path.
returns [not-null] The resolved canonical texture path.

ResolveTexturePathReverse

Reverse-resolves the given texture path.

public method ResolveTexturePathReverse (Path path)
type Path
params path [not-null] The resolved texture path.
returns [not-null] The texture path (relative if possible).

TextureFileReplace

Replaces a texture file.

public method TextureFileReplace (Path path, IModelTexture texture)
params path [not-null] The texture file path.
  texture [not-null] The replacement model texture object.

Remarks:

The given texture file path will be resolved (see ResolveTexturePath), if necessary.

See also:

TextureFile

TextureNameReplace

Replaces a texture name.

public method TextureNameReplace (string original, string corrected)
params original [not-null] The original texture name.
  corrected [not-null] The corrected texture name.

See also:

TextureName

Validate

Validates the state of this object.

public override method Validate (Validator validator)
params validator [not-null] The validator object.
overrides ModelReaderBase.Validate

Protected / Attributes

data

The file data from which to read the 3D model.

protected field data
type IFileData
inherited ModelReaderBase.data

Protected / Constructors

ModelReader

Creates a new instance of ModelReader.

protected constructor ModelReader (IFileData data, string modelFormatName)
params data [not-null] The 3D model file data to read.
  modelFormatName Name of the ModelFormat.

Protected / Methods

ComputeNormals

protected static method ComputeNormals (VertexArrays vertices, int32[] triangleList)
params vertices
  triangleList

Dirty

Subclasses must call this method when the model reader options have been modified.

protected method Dirty ()
inherited ModelReaderBase.Dirty

DisposeManaged

Disposes the managed resources held by a concrete subclass. This method will be called at most once per subclass.

protected override method DisposeManaged ()
overrides ModelReaderBase.DisposeManaged

Remarks:

This method will only be called when a disposable object is explicitly destroyed by user code calling the Dispose method. It will not be called when the object is collected as garbage by the system.

Overriding methods must call the DisposeManaged method of their base class. The base call should be the last statement.

The DisposeManaged method is called before the DisposeUnmanaged method.

DisposeUnmanaged

Disposes the unmanaged resources held by a concrete subclass. This method will be called exactly once per subclass.

protected virtual method DisposeUnmanaged ()
inherited Disposable.DisposeUnmanaged

Remarks:

Overriding methods must call the DisposeUnmanaged method of their base class. The base call should be the last statement.

The DisposeUnmanaged method is called after the DisposeManaged method.

DoReadModel

Reads the 3D model.

protected abstract method DoReadModel ()
type IModel
returns [not-null] The read 3D model.
inherited ModelReaderBase.DoReadModel

PostProcess

Performs in-place post processing on the given vertex data.

protected method PostProcess (VertexArrays vertices)
params vertices The vertex data to process.

See also:

ReadModelFlags.FlipNormals
ReadModelFlags.FlipU
ReadModelFlags.FlipV
ReadModelFlags.FlipX
ReadModelFlags.FlipY
ReadModelFlags.FlipZ

Performs in-place post processing on the given index data.

protected method PostProcess (VertexArrays vertices, int32[] indices, PrimitiveBatch batch)
params vertices The vertex data.
  indices The index data to process.
  batch The geometry batch.

See also:

FixWinding
ReadModelFlags.FlipWinding

ReadTextLine

protected static method ReadTextLine (IDataStream stream, StringBuilder output)
type int32
params stream
  output

TextureFile

Returns the model texture object for the given texture file.

protected method TextureFile (Path file, bool srgb)
type IModelTexture
params file [not-null] The texture file path.
  srgb The Srgb flag to use for encoding the texture. Defaults to true.
returns The model texture or null.

Remarks:

The model texture object for the given texture file is obtained by the following steps:

  1. The given texture path is resolved (see ResolveTexturePath).
  2. If a model texture object has been specified earlier for the resolved texture path via TextureFileReplace, that object is used (the srgb parameter is ignored in this case). Otherwise, a new model texture object is created and cached, using the canonical path value as the key.

TextureName

Returns the model texture object for the given texture name.

protected method TextureName (string name, bool srgb)
type IModelTexture
params name The texture name, as found in the 3D model.
  srgb The Srgb flag to use for encoding the texture. Defaults to true.
returns The model texture or null.

Remarks:

The model texture object for the given texture name is obtained by the following steps:

  1. The texture name is replaced, according to the mappings that have been established earlier via TextureNameReplace.
  2. The texture name is interpreted as a file path and resolved (see Resolve) using the configured texture path (see TexturePath).
  3. This method delegates to TextureFile, using the resolved texture path.

ValidateFlush

Flushes cached validation data.

[EmptyBody]
protected override method ValidateFlush ()
overrides ModelReaderBase.ValidateFlush