Contact and Support

Licensing Support

If you are experiencing problems with the licensing of Tinman 3D, please refer to Licencing and Pricing.

If this does not resolve the issue, please contact us at: support@tinman3d.com

Technical Support

Please refer to the Support Level entries in your Licence Certificate to see which individuals are eligible for receiving email support.

If you experience technical problems using the Tinman 3D SDK, please do not hesitate to contact us at support@tinman3d.com.

We will help you to solve the problem as quickly as possible.

Support Level Disambiguation

The items in your Licence Certificate may include multiple support levels, for example, BASIC and PREMIUM. Typically, the lower-grade level is included in the Development licence, whereas the upper-grade level may be purchased separately and may include a compensation for unused time periods.

Sending an upper-grade support request voids compensation for the current time period (calendar week). To prevent this from happening unintentionally, please specify the intended support level explicitly in your support request (email subject or body, for example).

Frequently Asked Questions

You can find answers to some of the most frequently asked questions below.

Where is the Web / Zip / Git password?

Please read and accept the Terms and Conditions. Then you may use the password in the Download Protection section.

Which is my effective EULA version?

The Terms and Conditions specify the End User License Agreement (EULA) of the Tinman 3D SDK.

The EULA effectively begins where a licence item has been purchased (see "If YOU purchased a …​" wording). It does not specify how the purchase process looks like and does not include pricing details or quotes.

The EULA must be accepted at these points in time:

  • When downloading a Tinman 3D SDK package
    The Download Protection requires that a password is specified, in order to be able to start the download, which represents the legal act of accepting the EULA. The download contains an identical copy.

  • When purchasing a licence
    The Purchase Document contains a copy of the EULA, which is always identical to the most recent version, on the document date.

  • When upgrading from an earlier version
    The EULA of the new Tinman 3D SDK version replaces the one of the old version, see section:
    "3. SOFTWARE MAINTENANCE AND UPDATES / c. Exchange Of License".

In the end, the effective EULA is always the one that is included in the Tinman 3D SDK package which you are using for development and/or redistribution.

The Terms and Conditions page includes a version history, to make sure that a licence exchange never goes unnoticed or happens unexpectedly.

Which is my effective TOSA version?

The Terms and Conditions specify the Terms of Service (TOSA) for custom services.

The TOSA effectively begins where a service package has been purchased (see "If YOU purchased a …​" wording). It does not specify how the purchase process looks like and does not include pricing details or quotes.

The most recent TOSA must to be accepted when purchasing a service package. An identical copy is included in the corresponding Task Document.

The Terms and Conditions page includes a version history, to make sure that a change of terms never goes unnoticed or happens unexpectedly.

Why does the graphics context fail to initialize?

In an ideal world, all computers would have a single graphics adapter with high-performance capabilities.

However, in the real world it is often the case that computers (especially notebooks) have multiple graphics adapters: one designed for low-power consumption and another one for high-performance applications.

The GPU-Z tool can be helpful when debugging problems related to graphics adapters.

With IGraphicsContextFactory.AdapterNames and Graphics.adapters, the list of supported graphics adapters may be queried. Then with IGraphicsContextFactory.AdapterOrdinal and Graphics.adapter, a specific adapter may be chosen. By default, the first adapter (i.e., ordinal #0) is chosen.

Even if a graphics adapter is included in the list of supported ones, initialization of a graphics context may still fail, for example if a render effect requires a missing GPU feature.

To fix failures during graphics context initialization, please do the following:

The Demo Application logs some information about the graphics context factories that it supports:

Graphics context factory information for Direct3D 11
[I] Found graphics context factory: DirectX11
    {
      repository  = <e:\svn.tinman\release\src.fx>,
      multisample = 8,
      vsync       = false,
      adapters    = ['#0: NVIDIA GeForce RTX 2080 Ti',
                     '#1: Microsoft Basic Render Driver']

After creating a graphics context, the DemoApplication output the following log message, for debugging:

Graphics context information
[I] Created graphics context 'DirectX 11' on adapter #0
    'NVIDIA GeForce RTX 2080 Ti' with 10.8 gb of video memory.

To choose a graphics adapter other than #0, update the configuration settings file as follows:

Configuration settings
` The available graphics context factories.
intern graphics : Graphics[] =
[
  DirectX11
  {
    adapter     = ?, (1)
    multisample = graphicsAntialias,
    repository  = home + <src.fx>,
    vsync       = graphicsVsync
  },
  ... (2)
];
1 The adapter ordinal: 0, 1, 2, …​
2 Same for other factories, omitted for brevity.

Some graphics context factories (for example OpenGL) only report the system’s default graphics adapter. In this case, the above solution cannot be applied. Instead, the default graphics adapter must be configured using the system settings, usually by one of the following means:

Why does compilation or linking fail?

Some components of the Tinman 3D SDK are provided as source code. The following sections explain how to fix the most common build problems.

[C++] Cannot convert …​ to CodeX::Object*

error C2664: 'void CodeX::Object::ReleaseRef(CodeX::Object *)' :
cannot convert argument 1 from '<some type> *' to 'CodeX::Object *'

Tinman 3D minimizes the use of #include directives in header files, in order to reduce compilation time and to avoid cyclic include dependencies, by using forward declarations where possible.

The type <some type> is a forward declaration only and thus incomplete. To resolve the error, an #include directive for <some type> must be added, which provides the type definition.

[C++] Unresolved external symbol

error LNK2001: unresolved external symbol "<some class member name>" (<some ugly mangled name>)

Tinman 3D uses separate files (*.h / *.hpp) for template types.

Please make sure you include all *.hpp implementations in your source file.

[C++] <identifier> is not a member of <some type>

error C2039: 'GetMessageW': is not a member of 'CodeX::Exception'

A preprocessor macro redefines an identifier (most likely a member name) that is used by Tinman 3D.

In a perfect world, nobody would ever define a preprocessor macro that is not using an UPPER_CASE_NAME. However, in the real world, the WinAPI (as an example of a widely-used API), is doing exactly that. Here is a popular example:

From WinUser.h - a part of the _WinAPI
#ifdef UNICODE
#define GetMessage  GetMessageW
#else
#define GetMessage  GetMessageA
#endif // !UNICODE

This breaks CodeX::Exception::GetMessage and any overriding member (see System.Message). To fix this, please add #undef directives before including the Tinman 3D header file.

To find the culprit (usually an #include) quickly, you can exploit the syntax highlighting feature of modern IDEs: put the problematic identifier (e.g. GetMessage) into the code and observe whether it is displayed as a preprocessor macro or as an undefined symbol. Then do manual binary subdivision until you find the problematic locations in the code.

If you find yourself in the situation that you need #undef to make a Tinman 3D header work and you need the original #define (for example to run a Windows message loop or to call ID3D11InfoQueue::GetMessage), then replicate the original macro under a different name - and please remember that it is not Tinman 3D that is defining these culprit preprocessor macros in the first place.

Why does my licence key fail to work?

Please keep in mind that licence keys have metadata bindings, so the same licence key may not work for other users, products, etc.

Development licence keys (i.e. User, Site and Academic) only work during the licence period (see the Valid Until date in the Licence Certificate).

Distribution licence keys (i.e. Product, Company and Full) and Content licence keys (i.e. Source) only work for Tinman 3D SDK versions that have been released during the licence period (see the Updates Until date in the Licence Certificate).

A licence key might not work because of the following reasons:

The licence key is invalid

Please make sure you specify the entire licence key (100 non-whitespace ASCII characters).

The licence metadata does not match

If you need additional metadata bindings (e.g. more than one workstation, typo in metadata values), you may request extra licence keys. Please refer to Order Process for details.

The licence key has expired

You will receive new licence keys for each purchase you make. If your Development licence has expired, you can continue to use your Distribution licence keys. If the update period of your Distribution / Content licence has expired, you can continue to use all previous Tinman 3D SDK releases perpetually.

The licence key source has been disabled

The LicenceDomain.AllowUnlockByEnvironment property of the Tinman domain can be set to false, which disables use of the TINMAN_3D_LICENCEKEY environment variable.

If you are specifying your licence key via the environment variable, make sure the name is spelled correctly and that there are no extra characters before or after the licence key (whitespaces are ok):

TINMAN_3D_LICENCEKEY= CIk!6Dh6Ui;lSE+Z{{jx7$Y~8,#TSt~o%CK#(e,F#O9.d;fGc+bU35%HVl;[.+s#@h.bo1~{riL.4|UreHfeuac}5ZV~DBocxU}@

Changes to environment variables are not always forwarded to running processes, so it might be necessary to restart your IDE (for example Visual Studio) to make your licence key take effect.

When your IDE (for example Visual Studio 2015 or older) is using a hosting process to debug your application, different metadata values will be returned and your licence keys might stop working.

The recommended solution for this problem is to have a User, Site or Academic licence key ready in the environment variable TINMAN_3D_LICENCEKEY while doing development work.

To work around the problem, you can disable the hosting process in your IDE. For Visual Studio 2015 or older, this can be done in the project properties:

hosting process
Figure 1. Project properties - Visual Studio C#

Why does my application crash?

Tinman 3D uses exceptions. Make sure you catch and report those in your application. Uncaught exceptions will terminate the application, usually leaving no or little error trace.

For more information about Tinman exception handling, please refer to:

The Demo Application shows how to catch exceptions properly.

Tinman 3D makes use of method precondition checks and state assertions in order to validate the execution context. This helps to avoid out-of-range errors and memory corruption:

These sanity checks are only performed in DEBUG mode, see Software Architecture / DEBUG vs. RELEASE.

When running in RELEASE mode, invalid parameters or calls can easily corrupt memory and crash the application. Please make sure to run in DEBUG mode at least once, then you will get proper exceptions, and you can identify the error source.

The licence protection module of Tinman 3D uses encrypted data which must be unlocked with a licence key. Encrypted data is automatically unlocked when the application needs to access it for the first time. This can lead to unpredictable error situations when no valid licence key is available.

As best practice, you should specify your licence key(s) before using any other API of the Tinman 3D SDK:

  1. Call LicenceKey on LicenceDomain.Tinman for each one of your licence keys.

  2. Call Unlock or TryUnlock explicitly so you can handle any errors up-front.

Why do I get strange TinmanExceptions?

While developing software using the Tinman 3D SDK, you might - sooner or later - run into uncaught TinmanExceptions. The following section explains the most common ones.

Unknown type

Unknown type: '00000000-0000-0000-0000-000000000000'
No such type: 'Type.Name'

Tinman 3D uses lazy initialization, for example for serializable types and config types.

Some entity is referenced from outside of the application (e.g. serialized in a file or created from source code in a config script), but has not been initialized yet.

To fix this, use the IPleaseIncludeInBinaryThanks interface to force initialization up-front by calling PleaseIncludeInBinaryThanks on all TinmanModules you are using.

Example 1. Lazy initialization of the Workshop Application

  1. Call PleaseIncludeInBinaryThanks on TinmanWorkshopModule. This initializes the top-level module of the application.

  2. Call TinmanModule.Initialize. Since each module instance references its dependencies and the top-level module has already been initialized, this will initialize all other modules, too.

The dependency graph of the modules can be queried via TinmanModule.Dependencies.

Null-pointer

Null-pointer exception (NPE)
e.g. "Object reference not set to an instance of an object"

A common cause for NPEs is trying to use a IDisposable object that has already been disposed (see LifecycleState.Disposed), often because of an incorrect sequence of ownership transfers.

In DEBUG mode, a FailedAssertionException should be thrown in this case, whereas in RELEASE mode, the code will usually run into an NPE, because references and pointers are cleared upon disposal, as required by the rules of Disposal and Ownership.

Calls to IDisposable.Acquire will return null for disposed objects, which is the correct behaviour but can still cause NPEs if not anticipated. Using ILifecycleState.AssertValid in DEBUG mode can help to avoid that.

Please check ownership transfers to see if there are missing IDisposable.AcquireBase calls or surplus IDisposable.Dispose calls. Keep in mind that disposal may happen implicitly, for example when using the C# using statement.

Why does my OS freeze while importing geodata?

If you are using the Geodata Processor on Windows 7 to run a bulk import of geodata, the filesystem cache may grow until application code gets paged to disk. This kills runtime performance and the system freezes.

Please note that this is not problem of Tinman 3D.

This problem can be avoided by importing geodata incrementally, instead of running a single import process for hours or days.

Also there are some tools available on the web that can help fixing this, for example SetSystemFileCacheSize.

What to do with the bugs I found?

Please have a look at the changelog to see if your problem has already been reported and fixed.

Please send your bug reports to support@tinman3d.com. If possible, include the following information in the report:

Problem Description

Please describe the context of the problem and the problem itself. If you make the description as concise as possible and as precise as necessary, this will very much help to fix the problem.

System Information

If you deem it helpful, please provide us with information about the computer system you are using.
TinmanModule.SystemInfo
Geodata Processor / sysinfo

Stacktrace

The exception message and stacktrace, if is available.
TinmanException.ErrorInfo

Error Dump

The error dump file that has been generated by TinmanErrorDump.
This happens rarely, but if it does, providing the error dump file will help greatly to fix the problem.

Executable code fragment

If you provide us with code that triggers the bug, we will usually be able to fix it quickly. To defeat the bug, we must understand the bug, so to speak.