Developer Guide

This page contains technical information for developers.

Technical Overview

To get an overview of the Tinman 3D SDK, please refer to the following documentation:

  • Software Architecture
    Explains common code constructs as well as the overall structure and design of the SDK

  • Terrain Overview
    Explains concepts and building blocks that are specific to the realtime terrain processing, visualization and analysis features of the SDK

  • Scene Overview
    Explains how to create interactive 3D scenes that are based on the terrain features of the SDK

  • Code-X Framework
    Explains how automatic code translation from C# to other programming languages (C++, HLSL, GLSL, …​) is performed by the Code-X Framework

  • GPU Programming
    Explains how to write GPU programs in C#

  • Scripting Overview
    Explains how to use the scripting language of the SDK

  • Geodata Processing
    Explains how to setup and run geodata processing pipelines

  • Streaming and Caching
    Explains how to setup data streaming from external source, backed by efficient data caching

  • User Interface
    Explains the built-in user interface framework of the SDK

  • Native Libraries
    Describes the native library / function dependencies of the SDK

Tutorials and Examples

To find the tutorial and example source code in the Tinman 3D SDK, please have a look at these places:

GUI Widgets

The Tinman 3D SDK contains several GUI widgets, which can be used as plug-and-play components for other applications.

Every widget implements the IWidget interface. Widgets are assembled into an IApplication object, which is then run by an application-defined host.

The following built-in application hosts are available:

  • Native window
    The application object is run in an own application window (see IApplication.Run).

  • WinForms Host
    The application uses the ApplicationControl class of the Tinman.AddOns.WinForms component.

  • WPF Host
    The application uses the ApplicationControlWpf class of the Tinman.AddOns.WPF component. This WPF Control is provided as source code.

  • MFC Host
    The application uses the CApplicationControlMfc class of the Tinman.AddOns.MFC component.

If you get errors when loading one of the above controls into the GUI designer of your IDE, please build and run the corresponding demo first (e.g. Tinman.Demo.WinForms). This usually fixes the problem.

The Workshop Application lets the user configure an App object, uses the ConfigScript class to create an IApplication object from the script source code and finally runs the resulting widget(s) in its WPF host.

Please refer to the help browser in the Demo Application for details on available GUI widgets.

Hello World

This is the "Hello World!" example of the Tinman 3D SDK:

C# class file of the 'Hello World' example
using CodeX;
using Tinman.AddOns.DirectX11;
using Tinman.Core;
using Tinman.Core.Config;
using Tinman.Core.IO;
using Tinman.Core.Licensing;
using Tinman.Core.Math.Vectors;
using Tinman.Core.Util;
using Tinman.Engine;
using Tinman.Engine.Application;
using Tinman.Engine.Drawing;
using Tinman.Engine.Rendering;

namespace Tinman.Demo.Examples
{
  public sealed class Example_HelloWorld : ApplicationBase
  {
    public override ConfigValue ToConfig()
    {
      // This means our application is not exposed to the Config API.
      return ConfigValue.Invalid;
    }

    [ThrowAny]
    public static void Main(Path repository)
    {
      // Before initializing the Tinman 3D library, at least one valid licence
      // key must be given.
      LicenceDomain.Tinman.LicenceKey("Add licence key(s) here, if necessary.");

      // To initialize the Tinman 3D library, this method must be called on the
      // root module(s) that are being used by the application.
      TinmanEngineModule.Instance.PleaseIncludeInBinaryThanks();

      // The Tinman 3D library can now be initialized. Licence checking will be
      // performed here.
      TinmanModule.Initialize();
      try
      {
        IGraphicsContextFactory factory;
        IApplicationWindow window; // [!]
        IApplication application; // [!]
        TinmanError error;

        // Setup the graphics context factory, which will be used to create a
        // rendering context for the client area of the application window.
        factory = new DirectX11ContextFactory();
        factory.ShaderRepository = repository.AppendName("src.fx");

        // Create a new top-level application window.
        window = ApplicationWindow.Create("Hello World!", new Vec2I(1280, 768));

        // Create the application.
        application = new Example_HelloWorld();

        // Create the application loop and run it.
        error = application.Run("Example_HelloWorld.Main", factory, window,
          true);

        if (error != null)
          throw TinmanException.Error("Example_HelloWorld.Main",
            "Hello World has crashed.", error);
      }
      finally
      {
        // Shut down the Tinman 3D library.
        TinmanModule.Shutdown();
      }
    }

    public override void Render()
    {
      Graphics g; // [!]

      // Acquire reference to graphics object and release it when done.
      g = context.Graphics;
      try
      {
        g.Begin();
        try
        {
          // Draw "Hello World!" at the center of the screen.
          g.Fullscreen();
          g.DrawString((PixelFont) g.Cache.GetNull(PixelFont.HandleDefault),
            "Hello World!",
            g.ScreenWidth / 2, g.ScreenHeight / 2,
            Colors.White, Anchor.Center);
        }
        finally
        {
          g.End();
        }
      }
      finally
      {
        g.Dispose();
      }
    }

    #endregion
  }
}

To run the above code example, the following library components of the Tinman 3D SDK are required:

  • CodeX.System

  • Tinman.Licence

  • Tinman.Core

  • Tinman.Terrain

  • Tinman.Engine

  • Tinman.AddOns

  • Tinman.AddOns.DirectX11

In an MSBuild project file, these libraries may be referenced via NuGet, for example by using <PackageReference…​/> directives in an SDK-style project.

For release candidates, the corresponding NuGet packages will be tagged as pre-release packages, so it might be necessary to enable your IDE’s "Include prerelease?" option.
Example C# project file, using the Tinman 3D SDK
<?xml version="1.0" encoding="utf-8"?>
<Project Sdk="Microsoft.NET.Sdk"
  DefaultTargets="Build"
  xmlns="http://schemas.microsoft.com/developer/msbuild/2003">
  <!-- ... -->
  <ItemGroup>
    <PackageReference
      Include="Tinman.AddOns.DirectX11" Version="1.0.0-rc4.18"/>
  </ItemGroup>
  <!-- ... -->
</Project>

The dependencies of Tinman.AddOns.DirectX11 will make sure that all required libraries are included. It is not necessary to reference each required library individually.

The Tinman.AddOns.* library components are included with full source code in the Tinman 3D SDK packages, the binary NuGet versions are provided for convenience.