Performance Guide

The ApplicationLoop class provides profiling values for CPU/GPU/RAM usage and the amount of time spent invoking the application loop callbacks. See the ApplicationLoop.Profile* constants for details.

The TerrainView class provides a number of profiling values that are specific to the terrain rendering pipeline and data flow. See the TerrainView.Profile* constants for details.

When set to true, allocation stack-traces of Disposable objects are collected and included in the output of finalized disposables (which usually indicates improper use of the Disposal and Ownership rules).

In DEBUG mode, the report of finalized disposables is output to a file named tinman3d.finalizers.ID.txt (where ID is then ame of enclosing process) in the user’s profile folder (see Environment.SpecialFolder.UserProfile, for example C:\Users\TheUserName). The file will be deleted if the report is empty.

Please refer to the documentation of the DebugShowAllocationStackTraces field in the Disposable class for details.

When this debug helper is enabled, the calls to Begin of Monitor objects are counted, grouped by caller. A periodic report is output to the standard output stream of the process. The report can be used to track down excessive use of thread synchronization quickly.

Overuse of thread synchronization will degrade performance. Usually, those calls will appear at the top of the dump and can be used as starting points for additional profiling.

See Monitor.DebugDumpMonitorUsage for details.

Enabling this debug helper will measure the time spent by waiting during calls to WaitForNotify of Monitor objects. A periodic report is output to the standard output stream of the process. The report can be used to identify bottlenecks that limit parallel execution.

Long wait times do not necessarily indicate a performance problem. For example, pooled worker threads may spend most of their time waiting for work to be submitted. On the other hand, when callers spend lots of time waiting to gain access to shared memory caches, this usually means that there is some kind of performance problem, such as an improperly sized cache.

See Monitor.DebugDumpWaitTimes for details.

Object pools are used at various places in the Tinman 3D SDK, to reduce the number of dynamic allocations. The ObjectPoolUtil class provides some helpers that can be used to determine optimal pool parameters and to evaluate pool performance.

See ObjectPoolUtil.DebugInterval for details.

Graphics APIs usually provide a debug layer, which provides additional information that can be very helpful for debugging and testing. When this debug helper is enabled, IGraphicsContextFactory objects will enable the debug layer, if available.

See GraphicsContext.DebugEnableLogOutput for details.

Graphics context implementations that are based on GLBase need to check the current API error in order to detect failures. Always checking the current error hurts performance, not checking it often enough make debugging more difficult. This debug helper increases the number of performed error checks.

See GLContext.DebugFrequentErrorChecks for details.

When a GLContext encounters an error while compiling shaders and/or linking programs, it throws a RenderException, which includes the error log from the GL as well as the GLSL source code.

If this helper is enabled, The error log and GLSL source code will also be written to separate files in the glsl.cache directory tree (see leaf shaders directories and *.log files), if a public shader repository has been specified via IGraphicsContextFactory.ShaderRepository.

See GLContext.DebugOutputSourceAndErrors for details.

Being a low-level graphics API, Direct3D 12 requires an application to manage CPU/GPU descriptor values in pools. By enabling this debug helper, the descriptor pool usage of Tinman 3D is output periodically to the standard output stream of the process.

See DirectX12Context.DebugDumpDescriptorPools for details.

Being a low-level graphics API, Direct3D 12 requires that an application manages data uploads from the CPU to the GPU by itself. This debug helper periodically outputs the state of the internal upload buffer to the standard output stream of the process. This can be used to check that no inadvertent uploads are performed.

See DirectX12Context.DebugDumpUploadBuffer for details.

This helper will improve error logging of the OpenFlight API.

See MG.DebugSystemMessages for details.

Enabling this helper will skip loading of the high-resolution 3D model of Bennu, which can speed up things while working on the tutorial code.

See Tutorial_26_Bennu.DebugSkipLoadModel for details.

Enabling this helper will skip preloading of the terrain imagery layers from their web sources, which can speed up things while working on the tutorial code.

See Tutorial_31_Showcase.DebugSkipPreload for details.

The main loop of an application is responsible for consuming user input, for updating the application state and for rendering new graphics frames. Often, the cycles of that loop are referred to a frames and the application performance is measured with frames per second (FPS).

Basically, there are two options that determine the overall behaviour of an application loop, with respect to performance:

With Tinman 3D, an application loop may be established using any of the following:

The domain model for 3D Models provides the API for loading 3D model files, building 3D models from scratch and using the resulting model structure at runtime, for example to perform collision detection or rendering with the GPU Rendering abstraction layer.

By using IModel.Bounds or IModel.Collider, additional computations may need to be carried out, in order to obtain the required spatial data. By default, these computations are performed lazily, potentially causing framerate stuttering when triggered during rendering.

To counteract such problems, any of the following mechanisms may be used:

When rendering IModel objects, performance greatly depends on how effective the following techniques are applied at runtime:

To get a measure of the above, use ModelRenderer.Statistics to get a ModelRendererStats value. When using the TerrainView class, this is done automatically, in order to produce profiling values. These can be browsed at runtime in the Profiler GUI.

The following optimization methods exist for fixing problematic statistic values that might occur for a model hierarchy:

When using a ModelFormat that returns a ModelReader object for reading 3D model files, additional options may be specified for controlling how the read model data is going to be interpreted.

The default behaviour merges the hierarchical structure of a 3D model file quite aggressively, in order to reduce the number of generated IModel objects, which in turn allows further optimizations that benefit rendering performance.

This behaviour may not be suitable for complex models that represent whole 3D scenes, where the hierarchy is vital for visibility culling. In such cases, the following options may be used:

When using the OpenFlight API to load 3D model files in the *.flt format, lazy loading of IModelGeometry and IModelTexture data forces the OpenFlight database file to be re-opened each time, which can reduce performance significantly. With OpenFlightModelReader.Database, the OpenFlight database can be kept open, which eliminates this performance bottleneck.

The presence of the Culling, Query or ShadowReceiver flag in TerrainModel.Flags will cause the IModel.Bounds property to be get for TerrainModel.Model, which may trigger lazy computations at render time, possibly leading to framerate stuttering.

Using the ISpatialQuery interface on a terrain model may also trigger lazy computations, because the IModel.Collider property needs to be retrieved.

Please refer to General API / IModel for details on how to prevent the above from happening.