TinmanModule

Description

abstract class Tinman.Core.TinmanModule

Derived from

IComparable<TinmanModule>
IPleaseIncludeInBinaryThanks

Extended by

TinmanAddOnsDirectX11Module sealed
TinmanAddOnsDirectX12Module sealed
TinmanAddOnsDirectX9Module sealed
TinmanAddOnsModule sealed
TinmanCoreModule sealed
TinmanDemoModule sealed
TinmanDemoStandAloneModule sealed
TinmanEngineModule sealed
TinmanGpuModule sealed
TinmanProcessorModule sealed
TinmanTerrainModule sealed

Abstract base class for Tinman module descriptors.

Public / Constants

Weblink​Codex​Processor

public constant WeblinkCodexProcessor → ("https://manual.tinman3d.com/LATEST/codex-processor.html":string)

Permanent weblink to online manual of the Code-X Processor.

Weblink​Demo​Application

public constant WeblinkDemoApplication → ("https://manual.tinman3d.com/LATEST/Demo_Application.html":string)

Permanent weblink to online manual of the Demo Application.

Weblink​Features

public constant WeblinkFeatures → ("https://manual.tinman3d.com/LATEST/Features.html":string)

Permanent weblink to the feature overview of the Tinman 3D SDK.

Weblink​Geodata​Examples

public constant WeblinkGeodataExamples → ("https://manual.tinman3d.com/LATEST/Geodata_Examples.html":string)

Permanent weblink to the geodata examples.

Weblink​Geodata​Processor

public constant WeblinkGeodataProcessor → ("https://manual.tinman3d.com/LATEST/Geodata_Processor.html":string)

Permanent weblink to online manual of the Geodata Processor.

Weblink​Licence​Bakery

public constant WeblinkLicenceBakery → ("https://manual.tinman3d.com/LATEST/Licence_baKErY.html":string)

Permanent weblink to online manual of the Licence Bakery tool.

Weblink​Licencing​And​Pricing

public constant WeblinkLicencingAndPricing → ("https://manual.tinman3d.com/LATEST/Licensing_and_Pricing.html":string)

Permanent weblink to licensing and pricing information of the Tinman 3D SDK.

Weblink​Release​Notes

public constant WeblinkReleaseNotes → ("https://manual.tinman3d.com/LATEST/Release_Notes.html":string)

Permanent weblink to release notes of the Tinman 3D SDK.

Weblink​Sdk

public constant WeblinkSdk → ("https://manual.tinman3d.com/LATEST/Tinman_3D_SDK.html":string)

Permanent weblink to the online manual of the latest SDK release.

Weblink​Terms​And​Conditions

public constant WeblinkTermsAndConditions → ("https://manual.tinman3d.com/LATEST/Terms_and_Conditions.html":string)

Permanent weblink to terms and conditions of the Tinman 3D SDK.

Weblink​Workshop

public constant WeblinkWorkshop → ("https://manual.tinman3d.com/LATEST/Workshop_Application.html":string)

Permanent weblink to online manual of the Workshop Application.

Welcome

public constant Welcome → ("\n         _____          _______                                   ____   _____\n     ,-:` \\;',`'-,     |__  _(_)                                 |___ \\ |  __ \\\n   .'-;_,;  ':-;_,'.      | | _  _ __   _ __ ___    __ _  _ __     __) || |  | |\n  /;   '/    ,  _`.-\\     | || || '_ \\ | '_ ` _ \\  / _` || '_ \\   |__ < | |  | |\n | '`. (`     /` ` \\`|    | || || | | || | | | | || (_| || | | |  ___) || |__| |\n |:.  `\\`-.   \\_   / |    |_||_||_| |_||_| |_| |_| \\__,_||_| |_| |____/ |_____/\n |     (   `,  .`\\ ;'|\n  \\     | .'     `-'/      Real-time terrain processing, rendering and analysis\n   `.   ;/        .'\n     `'-._____.-'`             https://www.tinman3d.com - info@tinman3d.com\n":string)

The Tinman 3D welcome ASCII art.

Public / Methods

Add​Config​Documentation

[ThreadSafe]
public static method AddConfigDocumentation → (1)

configDoc in : ConfigDoc

[not-null]
The config documentation to add.

returns → bool

true if ConfigDocumentation of the associated TinmanModule is the same as configDoc in,
false if there is no associated module or some other config documentation has already been set.

Adds the given config documentation to the associated module.

This method uses For to obtain the associated TinmanModule object. If ConfigDocumentation returns null, the given config documentation is set.

Dependencies

[OwnerReturn] [ThreadSafe]
public static method Dependencies → ()

returns → Graph<TinmanModule>

The dependency graph.

Computes a dependency graph of all library modules (source depends on target).

For

[ThreadSafe]
public static method For → (1)

guid in : GUID

The GUID value.

returns → TinmanModule

The module or null if not found.

Retrieves a module by its GUID.

Initialize

public static method Initialize → ()

Initializes the Tinman 3D library.

Before calling this method, call IPleaseIncludeInBinaryThanks.PleaseIncludeInBinaryThanks on the top-level module(s) of the enclosing application. Then, based on the collected module dependencies (see Dependencies), this method will call IPleaseIncludeInBinaryThanks.PleaseIncludeInBinaryThanks and DoInitialize on all modules.

This method may be called repeatedly, subsequent invocations have no effect, except that they will initialize those TinmanModule instances that have been created since the most recent call to Initialize, for example after loading a plugin library.

LicenceException

If LicenceDomain.Tinman is still locked.

See also

LowLevel.PlatformForce

Prepare​Resource

2 overloads

[Pure]
public static method PrepareResource1 → (4)

input in : Path

[not-null]
Path to the resource data file.

guid in : GUID

The module Guid to use.

columns opt : int32 = 100

[>=0]
Number of columns to output before a line break is emitted. If set to 0, no line breaks will be emitted at all.

lineEnding opt : LineEnding = LineEnding.LF

The line ending token to use for emitting line breaks.

returns → string

The prepared base-85 resource data.

Prepares a binary resource for being embedded in the source code as a base-85 string literal.

Prepared resource data can only be read by modules that have the same Guid as the given guid in.

IOException

If an I/O error has occurred.

See also

TinmanModule.ReadResourceNull
TinmanModule.RegisterResource

[Pure]
public static method PrepareResource2 → (4)

input in : IDataStream own

[not-null]
The resource data stream.

guid in : GUID

The module Guid to use.

columns opt : int32 = 100

[>=0]
Number of columns to output before a line break is emitted. If set to 0, no line breaks will be emitted at all.

lineEnding opt : LineEnding = LineEnding.LF

The line ending token to use for emitting line breaks.

returns → string

The prepared base-85 resource data.

Prepares a binary resource for being embedded in the source code as a base-85 string literal.

Prepared resource data can only be read by modules that have the same Guid as the given guid in.

IOException

If an I/O error has occurred.

See also

TinmanModule.RegisterResource

Read​Resource

[OwnerReturn]
public method ReadResource → (1)

resourceData in : string

[not-null]
The embedded resource data prepared with PrepareResource1.

returns → ByteBuffer

The resource data.

Reads the data of the given resource.

IOException

If resourceData in is malformed.

Read​Resource​Null

[OwnerReturn]
public method ReadResourceNull → (1)

resourceData in : string

[not-null]
The embedded resource data prepared with PrepareResource1.

returns → ByteBuffer

The resource data or null iff resourceData in is malformed.

Reads the data of the given resource.

Resource

2 overloads

[Constant]
public method Resource1 → (1)

resourceName in : string

[not-null]
The name of the embedded resource.

returns → Path

The canonical resource path.

Returns the canonical path to the given embedded resource.

IOException

If the given resourceName in is not a valid path name.

See also

TinmanModule.Resource2

[Constant]
public method Resource2 → (1)

resourceName in : Path

[not-null]
The name of the embedded resource.

returns → Path

The canonical resource path.

Returns the canonical path to the given embedded resource.

The canonical resource path is constructed as follows:

  1. The given resourceName in path is made relative by calling Path.ToRelative.

  2. The root selector (if any) is removed from resourceName in by calling Path.ToRootSelector1.

  3. The resulting path is constructed by appending the following components:

    res:/{moduleName}/{resourceName}

    where moduleName is BuildInformation.ModuleName of Info and resourceName is the result of steps 1 and 2.

For example, the canonical resource path for a resourceName in of Resources/MyData.bin in a module named My.Own.Module would be:

res:/My.Own.Module/Resources/MyData.bin

Shutdown

[Shutdown]
public static method Shutdown → ()

Shuts down the Tinman 3D library.

Before calling this method, make sure to relinquish ownership of all IDisposable objects. This method will call DoShutdown on all modules.

This method may be called repeatedly, subsequent invocations have no effect.

System​Info

public static method SystemInfo → (1)

columns opt : int32 = 100

[>0]
Maximum number of text column.

returns → string

The system information dump.

Collects textual information about the runtime environment and code modules.

To​String

2 overloads

public method ToString2 → (1)

includeBuildDate in : bool

Include the build date?

returns → string

The string representation.

Returns a string representation of this module.

Public / Attributes

All

[ThreadSafe]
public static attribute All → (get)

value : IVectorConst<TinmanModule>

[not-null]
The list of all library modules.

Returns all library modules.

Modules without dependencies come first.

Config​Documentation

public attribute ConfigDocumentation → (get)

value : ConfigDoc

The ConfigDoc object or null if no documentation has been loaded yet.

Returns the config documentation for this module.

See also

ConfigDoc.Load1

Config​Types

public attribute ConfigTypes → (get)

value : ConfigType [ ]

[not-null]
The list of config types.

Returns all ConfigTypes this module owns.

Guid

public attribute Guid → (get)

value : GUID

The GUID.

Returns the GUID of this module.

Info

public abstract attribute Info → (get)

value : BuildInformation

[not-null]
The build information object.

The build information object of this library module.

Is​Debug

[Constant]
public attribute IsDebug → (get)

value : bool

true for DEBUG mode,
false for RELEASE mode.

Has this module been compiled in DEBUG mode?

For DEBUG mode, code optimization is disabled and no runtime checks are performed, see InvalidArgumentException and FailedAssertionException.

See also

LowLevel.IsDebug

Is​Initialized

[ThreadSafe]
public static attribute IsInitialized → (get)

value : bool

true if Initialize has been called and Shutdown has not been called afterwards,
false if Initialize has not been called yet or if Shutdown has already been called.

Checks if the Tinman 3D library has been initialized.

If new TinmanModule instances have become available after initializating, the Initialize method needs to be called again in order to initialize the new modules.

Settings

public attribute Settings → (get)

value : Path

[not-null]
The settings directory.

Canonical path to directory where to put application-specific settings for the current user.

The directory will be created, if necessary.

IOException

If an I/O error has occurred.

Protected / Constructors

Tinman​Module

protected constructor TinmanModule → (1)

guid in : string

[not-empty]
The GUID of this module.

Creates a new instance of TinmanModule.

Protected / Methods

Assert​Debug

[Assertion]
protected method AssertDebug → (1)

source in : string @ Tag

The error source tag.

This is a fake assertion method which never throws an exception but instead sets the debug mode flag for this module when called (which by definition of an assertion method, only happens in debug mode).

Collect​Dependencies

protected abstract method CollectDependencies → (1)

dependencies in : IBag<TinmanModule>

[not-null]
The set to use for collecting.

Collects those TinmanModule module descriptors this module directly depends on.

Collect​System​Info

[EmptyBody]
protected virtual method CollectSystemInfo → (1)

writer in : SourceCodeWriter

[not-null]
The text writer to use.

Collects textual system information for debugging purposes.

IOException

If an I/O error has occurred while writing to writer in.

Do​Initialize

[EmptyBody]
protected virtual method DoInitialize → ()

Initializes this Tinman module.

Overriding methods may use RegisterResource to add files to the in-memory filesystem for embedded resources (res:/), see Resource2.

LicenceException

If LicenceDomain.Tinman is still locked.

Do​Shutdown

[EmptyBody]
protected virtual method DoShutdown → ()

Shuts down this Tinman module.

Register​Resource

protected method RegisterResource → (3)

name in : string

The resource name to use for fetching the resource data from the application binary (if data opt is null) and for registering the resource (if type opt is not 1).

type opt : int32 = 0

[0..2]
The resource type:
0 : file
Treat name in as a single file and register it as a resource.
1 : config
Treat name in as compiled documentation and load it via ConfigDoc.Load1, without registering it as a resource.
2 : zip
Treat name in as a ZIP archive:
the resource will be extracted and each resulting file will be registered as a separate resource, using the following name, which is constructed by appending these name parts:

  1. The value of name in, without the last path element (i.e. the filename of the ZIP archive).

  2. The last path element of name in, without the filename suffix (e.g. '.zip').

  3. The ZIP entry name, treating '/' characters as directory separators.

For example, given a name in of 'SomeDir/Data.zip' and a ZIP archive containing entries 'abc/data.dat' and 'info.txt', the following resources would be registered:

SomeDir/Data/abc/data.dat
SomeDir/Data/info.txt
data opt : string = null

The embedded resource data prepared with PrepareResource1 or null to fetch the resource data from the application binary, which must have been embedded there using the platform-specific build mechanism. The following examples refer to a name in of "Resources/MyImage.png" and a BuildInformation.ModuleName of "Example.MyModule:

  • .NET Assembly / .csproj:

    <ItemGroup>
  <EmbeddedResource Include="Resources/Image.png"/>
</ItemGroup>

  • Windows DLL or EXE / .vcxproj:

    <ItemGroup>
  <ResourceCompile Include="SomeResourceFile.rc"/>
</ItemGroup>

    SomeResourceFile.rc:

    Example.MyModule.Resources.Image.png FILE "Resources/Image.png"
returns → bool

true if the resource has been registered successfully,
false if an error has occurred (see log message for details).

Registers an embedded binary resource.

A TinmanModule class may call this method from DoInitialize. If the call is made from another site, the resource cannot be found or the ZIP archive is corrupt, an error log message is generated and the method returns silently.

See also

TinmanModule.Logger

Register​Resources

protected method RegisterResources → (1)

resources in : EmbeddedResource [ ]

[not-null]
The array of embedded resources to register.

returns → bool

true if all resources have been registered successfully,
false if an error has occurred (see log message for details).

Registers the given embedded resources.

This method delegates to EmbeddedResource.Register, which in turn delegates to RegisterResource.

Protected / Attributes

please​Include​In​Binary​Thanks

[ShutdownClear]
protected static attribute pleaseIncludeInBinaryThanks → (int32)

Subclasses may increment this dummy counter from within IPleaseIncludeInBinaryThanks.PleaseIncludeInBinaryThanks in order to prevent overly aggressive code optimizations that may alter the order of initialization.

Logging

Logger

public static readonly attribute Logger → (ILogger)

The logger object of this class.